Build With AI

# GNet Platform — Farm Out Integration (One-Shot Build Prompt)

> **How to use:** Fill in the `<<...>>` placeholders in the **Variables** block below, then paste this entire file into your AI coding assistant (Cursor, Claude, ChatGPT, Copilot, etc.). It will generate a complete, runnable Farm Out integration in the language you specify. This block is the only thing you edit.

---

## Variables (fill these in)

```
TARGET_LANGUAGE_AND_FRAMEWORK = <<e.g. "TypeScript + Express" | "PHP + Laravel" | "Java + Spring Boot" | "Python + FastAPI">>
YOUR_GRIDDID                  = <<your GNet requester griddID, e.g. "acmelimo">>
DEFAULT_PROVIDER_GRIDDID      = <<griddID of the partner you farm out to (optional default)>>
GATEWAY_UID                   = <<your API Gateway user id, for getToken2>>
GATEWAY_PW                    = <<your API Gateway password, for getToken2>>
CALLBACK_WEBHOOK_ROUTE_PATH   = <<e.g. "/api/gnet-callback" — endpoint GNet posts provider updates to>>
CALLBACK_BASIC_AUTH_USER      = <<credential you require on your callback endpoint (confirm scheme with GNet)>>
CALLBACK_BASIC_AUTH_SECRET    = <<secret you require on your callback endpoint>>
```

> Treat every value above as configuration. Read them from environment variables / a secrets manager. Never hardcode secrets in source.

---

## Role & Context

You are a senior backend engineer. Build a **GNet Platform "Farm Out" integration** in **`TARGET_LANGUAGE_AND_FRAMEWORK`**.

GNet is a B2B platform that connects ground-transportation operators and dispatch/reservation systems. In a Farm Out flow, **we (the requester) send a reservation to GNet, which routes it to a partner operator (the provider)**. Our system must authenticate, submit trips, receive asynchronous status updates back from the provider via a callback webhook, and support updates and cancellations.

This integration has two halves:
1. **Outbound** — calls *we* make to GNet: get token, send trip, update, cancel.
2. **Inbound** — a callback webhook GNet posts to with provider status updates.

> Partnerships are established in GNet Connect (https://connect.grdd.net) **before** trips flow. Assume the partner `griddID` is already an approved partner.

Produce production-quality, fully runnable code with tests. Where the spec is silent, make the safe, conventional choice and **list your assumptions explicitly** at the end. Do not invent credentials or URLs beyond those given here.

---

## Part 1 — Authenticate

Get a token, cache it, and refresh on expiry or on any `401`:
```
POST https://api.grdd.net/Platform.svc/getToken2
Content-Type: application/json

{ "uid": "GATEWAY_UID", "pw": "GATEWAY_PW" }
```
The response contains a `token` string used as a `token:` header on all subsequent Platform calls.

## Part 2 — Send a trip (sendTrip)

```
POST https://api.grdd.net/Platform.svc/sendTrip/v1
token: <token from getToken2>
Content-Type: application/json

<reservation JSON>
```

Build the reservation from the GNet object model. You are the **requester**; set `affiliateReservation.requesterId = YOUR_GRIDDID`, `affiliateReservation.providerId = DEFAULT_PROVIDER_GRIDDID` (or a per-call override), `affiliateReservation.action = "NEW"`, and a unique `affiliateReservation.requesterResNo` (your internal reservation number). Representative payload to model your builder on:

```json
{
  "reservationDate": "-07:00",
  "affiliateReservation": {
    "action": "NEW",
    "status": "BOOKING_REQUEST",
    "requesterId": "YOUR_GRIDDID",
    "requesterResNo": "1715016686",
    "providerId": "DEFAULT_PROVIDER_GRIDDID"
  },
  "reservationType": "REGULAR",
  "runType": "Airport",
  "passengerCount": "2",
  "passengers": [
    { "firstName": "Alex", "lastName": "Smith", "email": "alex@example.com",
      "phones": [{ "number": "+155550044444", "type": "mobile" }] }
  ],
  "locations": {
    "pickup": { "locationType": "address", "address": "123 S Beverly Dr, Beverly Hills, CA 90212, USA",
      "lat": 34.0664703, "lon": -118.3993243, "time": "2024-08-03T10:27:22" },
    "dropOff": { "locationType": "airport", "address": "LAX",
      "flightInfo": { "flightNumber": "123", "airlineCode": "UA" }, "meetAndGreet": "False" },
    "stops": []
  },
  "preferredVehicleType": "SEDAN",
  "specialInstructions": "- Carseat needed ",
  "notes": [{ "message": "VIP Client", "context": "AFFILIATE" }],
  "submitMode": "WAIT"
}
```
> A `NEW` send omits `transactionId` — GNet generates and returns it (see Notes).

Notes:
- **`transactionId` lifecycle:** a `NEW` sendTrip leaves `transactionId` **blank**. GNet returns the `transactionId` in the response (and a `reservationId` when `submitMode = "WAIT"`). Persist both against your internal reservation — the `transactionId` is the correlation key for every later `UPDATE`, cancel, and callback.
- **`submitMode`:** `sendTrip` is asynchronous by default. `submitMode = "WAIT"` makes it synchronous (slower) and also returns a `reservationId`; otherwise final pricing and identifiers arrive later via the callback webhook.
- **Response shape (`200`):** `{ "transactionId", "reservationId" (WAIT only), "fees": [...], "totalAmount" }`. Store the `transactionId` immediately; treat a rules-engine error in the response as a failed send.
- `preferredVehicleType` must be a standardized GNet vehicle type (see Reference). Map your internal fleet types to GNet types in one module.
- Recent additions to the sendTrip payload include `namesignURL` and `tripAttributes` — support them if relevant (see the changelog link in Reference).
- **Version segment:** the reference specifies `V1` (the Quick Start shows it lower-case as `v1`); use what your onboarding contact confirms.

## Part 3 — Receive provider updates (callback webhook)

Expose **`POST CALLBACK_WEBHOOK_ROUTE_PATH`**. GNet posts provider status updates here in real time — status changes, chauffeur and vehicle info, fees, and the final `totalAmount` at trip close.

> You do **not** self-register this endpoint. Build the listener, then tell the GRiDD team your URL and they configure delivery on their side.

Representative payload to model your receiver on:

```json
{
  "transactionId": "11111111-2e7f-47a7-acb8-fc9136916c32",
  "status": "ASSIGNED",
  "totalAmount": "120.00",
  "affiliateReservation": {
    "requesterId": "YOUR_GRIDDID",
    "requesterResNo": "1723840",
    "providerId": "somepartner",
    "providerResNo": "58689",
    "action": "UPDATE",
    "status": "BOOKING_REQUEST"
  },
  "fees": [
    { "type": "EXPENSE", "currency": "USD", "code": "fixedcharge", "description": "Meet & Greet", "fee": "25.00" },
    { "type": "EXPENSE", "currency": "USD", "code": "percentagecharge", "description": "Driver Gratuity", "fee": "3.00" }
  ],
  "vehicle": { "vehicleId": "223", "vehicleType": { "type": "SEDAN" }, "make": "Sedan", "model": "Chrysler" },
  "chauffeur": {
    "griddID": "somepartner", "firstName": "Joey", "lastName": "ZaZa",
    "phones": [{ "number": "323.222.1111", "type": "mobile" }], "chauffeurId": "zaza@grdd.net"
  }
}
```

**Required handling**
1. **Authenticate** the inbound request (Basic auth against `CALLBACK_BASIC_AUTH_USER`/`CALLBACK_BASIC_AUTH_SECRET`, or whatever scheme your GNet onboarding contact confirms — flag as an assumption). Reject bad credentials with `401`.
2. **Return `200` fast.** Acknowledge immediately, then process asynchronously (queue/worker or background task). Do not block the response on heavy work.
3. **Correlate** by `transactionId` (fall back to `affiliateReservation.requesterResNo`) to find the original trip. Persist `providerResNo`, `totalAmount`, `fees`, `vehicle`, and `chauffeur`.
4. **Idempotency:** the same update may be delivered more than once. Dedupe so reprocessing a delivered update is a no-op.
5. **Map** the provider `status` (e.g. `ASSIGNED`, `EN_ROUTE`, `ON_LOCATION`, `CONFIRMED`) to your internal status in one mapping module (see Status Codes reference).
6. **Handle `FAILED`:** if `status == "FAILED"`, the reason is in `affiliateReservation.notes`. Surface it and mark the trip failed — don't silently drop it.
7. **`totalAmount` is an estimate** until the trip reaches `CLOSE`; treat the close-time amount as final.

## Part 4 — Update and cancel

**Update** an existing trip: re-`POST sendTrip/V1` with the **same** `transactionId` returned by the original `NEW`, `affiliateReservation.action = "UPDATE"`, and the changed fields. `transactionId` is **required** on every `UPDATE`.

**Cancel** a trip:
```
POST https://api.grdd.net/Platform.svc/cancelTripByTransactionId/{TRANSACTIONID}/{VERSION}
token: <token from getToken2>
```
Use the documented version segment (`V1`; the Quick Start shows `v1`) and the `transactionId` returned by the original `NEW`.

> Optional but recommended helpers: `getBookingByTransactionId` (reconcile state) and `retryTransaction` (re-drive a failed send). See Reference.

---

## Non-functional requirements (apply to all of the above)

- **Config & secrets:** all URLs, IDs, and credentials come from environment/config. Nothing secret in source or logs.
- **Outbound resilience:** every outbound call (token, sendTrip, cancel) has a timeout and retries with exponential backoff + jitter, capped attempts, treating only `2xx` as success. A `401` triggers one token refresh + retry. Note a `NEW` send has no `transactionId` yet, so a blind retry can duplicate a trip — guard `NEW` with your own idempotency key (e.g. `requesterResNo`); `UPDATE`/cancel carry the `transactionId` and are safe to retry.
- **Callback durability:** persist received callbacks before processing so none are lost on a crash; process via a queue/worker. In-memory default is fine, but note the production swap (the platform stack here is Next.js + Azure + Redis — make Redis/queue the obvious choice).
- **Idempotency:** dedupe inbound callbacks by `transactionId` + `status`; make outbound sends safe to retry.
- **Logging:** structured logs correlated by `transactionId`. Never log `token`, `Authorization`, or passenger/chauffeur PII (names, phones, emails) above debug level.
- **Tests** (idiomatic framework for the language): build-and-send a `NEW` trip with no `transactionId` and persist the one returned (token mocked), token-refresh-on-`401`, callback happy path updates internal state, duplicate callback is idempotent, callback with bad auth → `401`, a `FAILED` callback surfaces `affiliateReservation.notes`, `UPDATE` reuses the `transactionId`, and `cancel` hits `cancelTripByTransactionId`.

## Deliverables

1. A complete, runnable project in `TARGET_LANGUAGE_AND_FRAMEWORK` with a clear file layout.
2. A GNet client (token caching, `sendTrip`, `cancel`, optional get/retry), the callback receiver, and validation + status/vehicle mapping modules.
3. `.env.example` listing every variable from the Variables block.
4. Tests covering the cases above.
5. A `README` with run instructions and this verification snippet:
   ```bash
   # 1) get a token
   curl -X POST "https://api.grdd.net/Platform.svc/getToken2" \
     -H "Content-Type: application/json" \
     -d '{"uid":"GATEWAY_UID","pw":"GATEWAY_PW"}'
   # 2) send a trip
   curl -X POST "https://api.grdd.net/Platform.svc/sendTrip/v1" \
     -H "token: $TOKEN" -H "Content-Type: application/json" \
     -d @reservation.json
   ```
6. A short list of **assumptions** you made.

## Acceptance criteria (self-check before finishing)

- [ ] Token is obtained, cached, and refreshed on `401`.
- [ ] `sendTrip` builds a valid `NEW` payload with `requesterId = YOUR_GRIDDID`, **no** `transactionId`, and a standardized `preferredVehicleType`.
- [ ] The `transactionId` from the `sendTrip` response is persisted and reused on `UPDATE` and cancel.
- [ ] Callback endpoint authenticates, returns `200` immediately, and processes asynchronously.
- [ ] A `FAILED` callback is surfaced with its `affiliateReservation.notes` reason (not silently dropped).
- [ ] Re-delivered callback (same `transactionId` + `status`) is a no-op.
- [ ] `UPDATE` reuses the original `transactionId` with `action:"UPDATE"`.
- [ ] `cancelTripByTransactionId` is wired and tested.
- [ ] No secrets or PII in logs; all config externalized.

## Reference (consult for field-level detail; do not hardcode anything beyond the Variables block)

- Quick Start: https://docs.grdd.dev/gnet-platform/quick-start
- Sending Reservations: https://docs.grdd.dev/platform-api/sending-reservations
- Send Reservation (sendTrip): https://docs.grdd.dev/platform-api/reservations/send-trip
- sendTrip payload update (namesignURL, tripAttributes): https://docs.grdd.dev/changelog/gnet-platform/2026-05-sendtrip-payload-update
- Webhook Callbacks: https://docs.grdd.dev/platform-api/reference/webhook-callbacks
- Reservation Object Model: https://docs.grdd.dev/platform-api/reference/object-model
- Status Codes: https://docs.grdd.dev/platform-api/reference/status-codes
- Vehicle Types: https://docs.grdd.dev/platform-api/reference/vehicle-types
- Cancel Reservation: https://docs.grdd.dev/platform-api/reservations/cancel-by-transaction-id
- Get by Transaction ID: https://docs.grdd.dev/platform-api/reservations/get-by-transaction-id
- Retry Transaction: https://docs.grdd.dev/platform-api/reservations/retry
- Get Token: https://docs.grdd.dev/platform-api/authentication/get-token
- Full sample sendTrip / webhook payloads: https://raw.githubusercontent.com/GRiDD/GRiDD.github.io/main/gnet-sample-reservation.json · https://raw.githubusercontent.com/GRiDD/GRiDD.github.io/main/gnet-sample-webhook.json
- API reference (Apiary): https://gnet.docs.apiary.io/
- Postman collection: https://raw.githubusercontent.com/GRiDD/GRiDD.github.io/refs/heads/main/GNET.postman_collection.json

Now build it.