# Transport API Reference

The Transport API enables seed-to-seed tracking of all plant movement and transformation events within the LocalGreenChain ecosystem.

## Base URL

```
Development: http://localhost:3001/api/transport
Production:  https://api.localgreenchain.org/transport
```

## Authentication

All transport endpoints require authentication:

```http
Authorization: Bearer <user_token>
X-Wallet-Address: <wallet_address>
```

## Endpoints

### Record Seed Acquisition

Record the acquisition of seeds from any source.

```http
POST /api/transport/seed-acquisition
Content-Type: application/json

{
  "seedBatchId": "batch-2025-001",
  "sourceType": "seed_bank",
  "species": "Solanum lycopersicum",
  "variety": "Cherokee Purple",
  "quantity": 50,
  "quantityUnit": "seeds",
  "geneticLineageId": "lineage-tomato-cp-001",
  "generation": 0,
  "fromLocation": {
    "latitude": 40.7128,
    "longitude": -74.0060,
    "locationType": "seed_bank",
    "facilityName": "Baker Creek Seeds"
  },
  "toLocation": {
    "latitude": 40.7589,
    "longitude": -73.9851,
    "locationType": "farm",
    "facilityName": "Urban Farm NYC"
  },
  "transportMethod": "local_delivery",
  "certifications": ["organic", "heirloom"]
}
```

**Response:**
```json
{
  "success": true,
  "event": {
    "id": "evt-seed-acq-123",
    "timestamp": "2025-01-15T10:30:00Z",
    "eventType": "seed_acquisition",
    "status": "verified"
  },
  "block": {
    "index": 5,
    "hash": "0000abc123...",
    "carbonFootprintKg": 0.02,
    "foodMiles": 5.2
  }
}
```

---

### Record Planting

Record when seeds are planted.

```http
POST /api/transport/planting
Content-Type: application/json

{
  "seedBatchId": "batch-2025-001",
  "plantIds": ["plant-001", "plant-002", "plant-003"],
  "plantingMethod": "transplant",
  "quantityPlanted": 25,
  "growingEnvironment": "vertical_farm",
  "location": {
    "latitude": 40.7589,
    "longitude": -73.9851,
    "locationType": "vertical_farm",
    "facilityName": "Urban Farm NYC"
  },
  "expectedHarvestDate": "2025-03-15T00:00:00Z"
}
```

**Response:**
```json
{
  "success": true,
  "event": {
    "id": "evt-planting-124",
    "timestamp": "2025-01-20T08:00:00Z",
    "eventType": "planting",
    "plantIds": ["plant-001", "plant-002", "plant-003"]
  },
  "block": {
    "index": 6,
    "hash": "0000def456..."
  }
}
```

---

### Record Growing Transport

Record plant movement during growing (transplanting, relocating).

```http
POST /api/transport/growing
Content-Type: application/json

{
  "plantIds": ["plant-001", "plant-002"],
  "reason": "transplant",
  "plantStage": "seedling",
  "handlingMethod": "potted",
  "fromLocation": {
    "latitude": 40.7589,
    "longitude": -73.9851,
    "locationType": "greenhouse",
    "facilityName": "Seedling House A"
  },
  "toLocation": {
    "latitude": 40.7589,
    "longitude": -73.9852,
    "locationType": "vertical_farm",
    "facilityName": "Main Growing Tower"
  },
  "transportMethod": "walking",
  "rootDisturbance": "minimal",
  "acclimatizationRequired": true,
  "acclimatizationDays": 3
}
```

---

### Record Harvest

Record harvest events with yield data.

```http
POST /api/transport/harvest
Content-Type: application/json

{
  "plantIds": ["plant-001", "plant-002", "plant-003"],
  "harvestBatchId": "harvest-2025-050",
  "harvestType": "full",
  "produceType": "tomatoes",
  "grossWeight": 15.5,
  "netWeight": 14.2,
  "weightUnit": "kg",
  "qualityGrade": "A",
  "packagingType": "compostable_clamshell",
  "temperatureRequired": {
    "min": 10,
    "max": 15,
    "optimal": 12,
    "unit": "celsius"
  },
  "shelfLifeHours": 168,
  "seedsSaved": true,
  "seedBatchIdCreated": "batch-2025-002"
}
```

**Response:**
```json
{
  "success": true,
  "event": {
    "id": "evt-harvest-125",
    "timestamp": "2025-03-15T06:00:00Z",
    "eventType": "harvest",
    "harvestBatchId": "harvest-2025-050",
    "netWeight": 14.2
  },
  "block": {
    "index": 25,
    "hash": "0000ghi789...",
    "carbonFootprintKg": 0.1
  },
  "seedBatch": {
    "id": "batch-2025-002",
    "parentPlants": ["plant-001", "plant-002", "plant-003"],
    "generation": 1
  }
}
```

---

### Record Distribution

Record movement through distribution chain.

```http
POST /api/transport/distribution
Content-Type: application/json

{
  "batchIds": ["harvest-2025-050"],
  "destinationType": "consumer",
  "fromLocation": {
    "latitude": 40.7589,
    "longitude": -73.9851,
    "locationType": "vertical_farm"
  },
  "toLocation": {
    "latitude": 40.7614,
    "longitude": -73.9776,
    "locationType": "consumer"
  },
  "transportMethod": "bicycle",
  "orderId": "order-2025-1234",
  "customerType": "individual",
  "deliveryWindow": {
    "start": "2025-03-15T14:00:00Z",
    "end": "2025-03-15T18:00:00Z"
  }
}
```

---

### Record Seed Saving

Record seed saving from harvested plants.

```http
POST /api/transport/seed-saving
Content-Type: application/json

{
  "parentPlantIds": ["plant-001", "plant-002"],
  "newSeedBatchId": "batch-2025-003",
  "collectionMethod": "fermentation",
  "seedCount": 200,
  "seedWeight": 15,
  "seedWeightUnit": "grams",
  "storageConditions": {
    "temperature": 10,
    "humidity": 40,
    "lightExposure": "dark",
    "containerType": "vacuum_sealed",
    "desiccant": true,
    "estimatedViability": 5
  },
  "newGenerationNumber": 2,
  "availableForSharing": true,
  "sharingTerms": "trade"
}
```

---

### Record Seed Sharing

Record when seeds are shared with others.

```http
POST /api/transport/seed-sharing
Content-Type: application/json

{
  "seedBatchId": "batch-2025-003",
  "quantityShared": 25,
  "quantityUnit": "seeds",
  "sharingType": "trade",
  "tradeDetails": "Traded for 25 basil seeds",
  "recipientId": "user-xyz-456",
  "fromLocation": {...},
  "toLocation": {...},
  "recipientAgreement": true,
  "growingCommitment": "Will grow and report back",
  "reportBackRequired": true
}
```

---

## Query Endpoints

### Get Plant Journey

Get complete transport history for a plant.

```http
GET /api/transport/journey/:plantId
```

**Response:**
```json
{
  "plantId": "plant-001",
  "seedBatchOrigin": "batch-2025-001",
  "currentCustodian": "user-abc-123",
  "currentLocation": {
    "latitude": 40.7614,
    "longitude": -73.9776,
    "locationType": "consumer"
  },
  "currentStage": "post_harvest",
  "events": [
    {
      "eventType": "seed_acquisition",
      "timestamp": "2025-01-15T10:30:00Z",
      "fromLocation": {...},
      "toLocation": {...}
    },
    {
      "eventType": "planting",
      "timestamp": "2025-01-20T08:00:00Z",
      ...
    },
    ...
  ],
  "totalFoodMiles": 12.5,
  "totalCarbonKg": 0.35,
  "daysInTransit": 2,
  "daysGrowing": 54,
  "generation": 1,
  "ancestorPlantIds": ["parent-plant-001"],
  "descendantSeedBatches": ["batch-2025-003"]
}
```

---

### Get Environmental Impact

Get carbon footprint and food miles for a user.

```http
GET /api/transport/footprint/:userId
```

**Response:**
```json
{
  "totalCarbonKg": 15.5,
  "totalFoodMiles": 250,
  "carbonPerKgProduce": 0.25,
  "milesPerKgProduce": 4.0,
  "breakdownByMethod": {
    "bicycle": { "distance": 50, "carbon": 0 },
    "electric_vehicle": { "distance": 150, "carbon": 3.0 },
    "walking": { "distance": 50, "carbon": 0 }
  },
  "breakdownByEventType": {
    "seed_acquisition": { "count": 5, "carbon": 0.5 },
    "distribution": { "count": 50, "carbon": 10.0 },
    ...
  },
  "comparisonToConventional": {
    "carbonSaved": 140.5,
    "milesSaved": 74750,
    "percentageReduction": 90
  }
}
```

---

### Verify Block

Verify a transport block's integrity.

```http
GET /api/transport/verify/:blockHash
```

**Response:**
```json
{
  "valid": true,
  "block": {
    "index": 25,
    "hash": "0000ghi789...",
    "previousHash": "0000fgh678...",
    "timestamp": "2025-03-15T06:00:00Z"
  },
  "chainValid": true,
  "crossReferences": [
    {
      "userId": "user-xyz-456",
      "blockIndex": 12,
      "type": "receiver",
      "verified": true
    }
  ]
}
```

---

### Generate QR Code

Generate QR code data for a plant or batch.

```http
GET /api/transport/qr/:plantId
```

**Response:**
```json
{
  "plantId": "plant-001",
  "blockchainAddress": "0x1234567890abcdef...",
  "quickLookupUrl": "https://localgreenchain.org/track/plant-001",
  "lineageHash": "a1b2c3d4e5f6...",
  "currentCustodian": "user-abc-123",
  "lastEventType": "distribution",
  "lastEventTimestamp": "2025-03-15T14:30:00Z",
  "verificationCode": "A1B2C3D4",
  "qrCodeImage": "data:image/png;base64,..."
}
```

---

## Error Codes

| Code | Message | Description |
|------|---------|-------------|
| 400 | Invalid request | Missing or invalid parameters |
| 401 | Unauthorized | Invalid or missing auth token |
| 403 | Forbidden | Not authorized for this resource |
| 404 | Not found | Plant/batch/block not found |
| 409 | Conflict | Duplicate event or chain conflict |
| 422 | Validation error | Data validation failed |
| 500 | Server error | Internal server error |

## Rate Limits

| Endpoint Type | Limit | Window |
|---------------|-------|--------|
| Read (GET) | 100 | per minute |
| Write (POST) | 20 | per minute |
| Batch operations | 5 | per minute |

## Webhooks

Subscribe to transport events:

```http
POST /api/transport/webhooks
Content-Type: application/json

{
  "url": "https://your-server.com/webhook",
  "events": ["seed_acquisition", "harvest", "distribution"],
  "filters": {
    "plantIds": ["plant-001", "plant-002"],
    "userId": "user-abc-123"
  }
}
```
