@myrobotaxi/contracts 0.6.0 → 0.7.0

package/README.md

@@ -36,6 +36,7 @@ Raw JSON for non-JS consumers (Go):
 ./node_modules/@myrobotaxi/contracts/schemas/vehicle-summary.schema.json
 ./node_modules/@myrobotaxi/contracts/schemas/drives-list.schema.json
 ./node_modules/@myrobotaxi/contracts/schemas/drive-detail.schema.json
+./node_modules/@myrobotaxi/contracts/schemas/drive-route.schema.json
 ./node_modules/@myrobotaxi/contracts/schemas/ws-messages.schema.json
 ./node_modules/@myrobotaxi/contracts/schemas/ws-envelope.schema.json
 ```

package/dist/index.cjs

@@ -817,6 +817,86 @@ var drive_detail_schema_default = {
   }
 };
 
+// schemas/drive-route.schema.json
+var drive_route_schema_default = {
+  $schema: "https://json-schema.org/draft/2020-12/schema",
+  $id: "https://myrobotaxi.com/schemas/drive-route.schema.json",
+  title: "DriveRoute",
+  description: "Full GPS polyline for a single completed drive, returned as a bare object by GET /api/drives/{driveId}/route (rest-api.md \xA77.4, FR-3.3). This is the heavy per-drive route payload deliberately excluded from both DriveSummary (\xA77.2) and Drive detail (\xA77.3): the SDK fetches it lazily on tap-through of a drive's map view, NOT eagerly per drive-list row (see \xA77.4 lazy-fetch guidance \u2014 cellular bandwidth / perceived latency, not heap pressure). The polyline is AES-256-GCM encrypted at rest on Drive.routePoints (NFR-3.23, data-classification.md \xA71.5) and decrypted in the store layer (NFR-3.25) before the handler serializes it; the SDK never sees ciphertext. Mirrors the Go `driveRouteResponse` struct in telemetry/internal/telemetry/drive_route_handler.go and the `DriveRoute` component in telemetry/docs/contracts/specs/rest.openapi.yaml. NOTE: the handler passes `routePoints` through as `json.RawMessage` (raw decrypted JSONB) \u2014 the per-point shape is owned by the writer that persisted it (store.RoutePointRecord, telemetry/internal/store/types.go), so RoutePoint below documents that persisted format field-for-field.",
+  type: "object",
+  additionalProperties: false,
+  required: ["driveId", "routePoints"],
+  properties: {
+    driveId: {
+      type: "string",
+      description: "Opaque database identifier (cuid) for this drive. Echoes the `driveId` path param and matches Drive.id / DriveSummary.id and the `driveId` carried by `drive_started` / `drive_ended` WebSocket frames. Always present (Go `driveRouteResponse.DriveID`, no omitempty).",
+      "x-classification": "P0",
+      examples: ["clmno9876543210zyxw0001"]
+    },
+    routePoints: {
+      type: "array",
+      description: "Ordered GPS breadcrumb trail for the drive, oldest point first, suitable for rendering the drive's polyline on a map. ALWAYS PRESENT and ALWAYS AN ARRAY, never null: the Go handler substitutes an empty `[]` when the underlying Drive.routePoints column is empty/absent (writeMaskedRoute, telemetry/internal/telemetry/drive_route_handler.go) \u2014 so a very short drive with no captured points, or a route that failed to decrypt, yields `[]` rather than a missing key or null. A 60-minute drive captured at ~1 Hz is roughly 3,600 points (~200-300 KB JSON); no server-side downsampling or paging \u2014 the entire polyline is returned in one response (there is no cursor/limit on this endpoint, unlike the \xA77.2 drives list).",
+      "x-classification": "mixed",
+      items: { $ref: "#/$defs/RoutePoint" }
+    }
+  },
+  $defs: {
+    RoutePoint: {
+      title: "RoutePoint",
+      description: "A single GPS sample on a drive's polyline. Matches the `RoutePointRecord` shape from data-classification.md \xA71.5 \u2014 the JSONB element format persisted by the Go writer (store.RoutePointRecord, telemetry/internal/store/types.go) and the legacy Next.js app. lat/lng are P1 (identifying GPS); speed, heading, and timestamp are P0 in isolation but are encrypted at rest as a unit inside the P1 routePoints column (NFR-3.23) and MUST NOT be logged separately. All five fields are always present on the wire (the Go struct carries no omitempty). Mirrors the `RoutePoint` component in telemetry/docs/contracts/specs/rest.openapi.yaml.",
+      type: "object",
+      additionalProperties: false,
+      required: ["lat", "lng", "speed", "heading", "timestamp"],
+      properties: {
+        lat: {
+          type: "number",
+          description: "Latitude in degrees at this point. Emitted as a JSON number (Go float64); whole-degree values serialize without a decimal point (Go shortest-float marshaling), so `10` and `10.0000` are the same value on the wire.",
+          "x-classification": "P1",
+          "x-encrypted-at-rest": true,
+          "x-unit": "degrees",
+          minimum: -90,
+          maximum: 90,
+          examples: [37.7749]
+        },
+        lng: {
+          type: "number",
+          description: "Longitude in degrees at this point. Emitted as a JSON number (Go float64).",
+          "x-classification": "P1",
+          "x-encrypted-at-rest": true,
+          "x-unit": "degrees",
+          minimum: -180,
+          maximum: 180,
+          examples: [-122.4194]
+        },
+        speed: {
+          type: "number",
+          description: "Instantaneous speed at this point, in miles per hour. P0 in isolation but encrypted at rest alongside the parent P1 routePoints column. Emitted as a JSON number (Go float64).",
+          "x-classification": "P0",
+          "x-unit": "mph",
+          minimum: 0,
+          examples: [15]
+        },
+        heading: {
+          type: "number",
+          description: "Compass heading at this point, in degrees (0-360, 0 = North). P0 in isolation but encrypted at rest alongside the parent P1 routePoints column. Emitted as a JSON number (Go float64).",
+          "x-classification": "P0",
+          "x-unit": "degrees",
+          minimum: 0,
+          maximum: 360,
+          examples: [175]
+        },
+        timestamp: {
+          type: "string",
+          format: "date-time",
+          description: "ISO 8601 / RFC 3339 UTC timestamp at which this point was captured. The Go writer renders it as `Timestamp.Format(time.RFC3339)` (telemetry/internal/store/drive_mapper.go). P0 in isolation but encrypted at rest alongside the parent P1 routePoints column.",
+          "x-classification": "P0",
+          examples: ["2026-04-13T18:22:00Z"]
+        }
+      }
+    }
+  }
+};
+
 // schemas/ws-messages.schema.json
 var ws_messages_schema_default = {
   $schema: "https://json-schema.org/draft/2020-12/schema",
@@ -1189,6 +1269,7 @@ var schemas = {
   vehicleSummary: vehicle_summary_schema_default,
   drivesList: drives_list_schema_default,
   driveDetail: drive_detail_schema_default,
+  driveRoute: drive_route_schema_default,
   wsMessages: ws_messages_schema_default,
   wsEnvelope: ws_envelope_schema_default
 };