@myrobotaxi/contracts 0.6.0 → 0.7.0

package/dist/types.d.cts

@@ -637,6 +637,76 @@ interface Drive {
     createdAt: string;
 }
 
+/**
+ * AUTO-GENERATED by scripts/codegen.mjs from the corresponding JSON Schema
+ * in ../schemas/. DO NOT EDIT BY HAND — re-run `npm run codegen` instead.
+ *
+ * The x-classification / x-atomic-group / x-unit / x-encrypted custom JSON
+ * Schema annotations from the source schemas are folded into the generated
+ * TSDoc comments so grep can find them without leaving the editor.
+ */
+/**
+ * Full GPS polyline for a single completed drive, returned as a bare object by GET /api/drives/{driveId}/route (rest-api.md §7.4, FR-3.3). This is the heavy per-drive route payload deliberately excluded from both DriveSummary (§7.2) and Drive detail (§7.3): the SDK fetches it lazily on tap-through of a drive's map view, NOT eagerly per drive-list row (see §7.4 lazy-fetch guidance — 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 §1.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) — 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.
+ */
+interface DriveRoute {
+    /**
+     * 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).
+     *
+     * @classification "P0"
+     */
+    driveId: string;
+    /**
+     * 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) — 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 — the entire polyline is returned in one response (there is no cursor/limit on this endpoint, unlike the §7.2 drives list).
+     *
+     * @classification "mixed"
+     */
+    routePoints: RoutePoint[];
+}
+/**
+ * A single GPS sample on a drive's polyline. Matches the `RoutePointRecord` shape from data-classification.md §1.5 — 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.
+ *
+ * This interface was referenced by `DriveRoute`'s JSON-Schema
+ * via the `definition` "RoutePoint".
+ */
+interface RoutePoint {
+    /**
+     * 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.
+     *
+     * @classification "P1"
+     * @unit "degrees"
+     * @encrypted-at-rest true
+     */
+    lat: number;
+    /**
+     * Longitude in degrees at this point. Emitted as a JSON number (Go float64).
+     *
+     * @classification "P1"
+     * @unit "degrees"
+     * @encrypted-at-rest true
+     */
+    lng: number;
+    /**
+     * 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).
+     *
+     * @classification "P0"
+     * @unit "mph"
+     */
+    speed: number;
+    /**
+     * 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).
+     *
+     * @classification "P0"
+     * @unit "degrees"
+     */
+    heading: number;
+    /**
+     * 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.
+     *
+     * @classification "P0"
+     */
+    timestamp: string;
+}
+
 /**
  * AUTO-GENERATED by scripts/codegen.mjs from the corresponding JSON Schema
  * in ../schemas/. DO NOT EDIT BY HAND — re-run `npm run codegen` instead.
@@ -980,4 +1050,4 @@ interface WebSocketEnvelope {
     ts?: string;
 }
 
-export type { AuthOkPayload, AuthPayload, ConnectivityPayload, Drive, DriveEndedPayload, DriveStartedPayload, DriveSummary, DrivesListResponse, ErrorPayload, HeartbeatPayload, MessageType, PingPayload, PongPayload, SubscribePayload, UnsubscribePayload, VehicleListResponse, VehicleState, VehicleSummary, VehicleUpdatePayload, WebSocketEnvelope, WebSocketMessages };
+export type { AuthOkPayload, AuthPayload, ConnectivityPayload, Drive, DriveEndedPayload, DriveRoute, DriveStartedPayload, DriveSummary, DrivesListResponse, ErrorPayload, HeartbeatPayload, MessageType, PingPayload, PongPayload, RoutePoint, SubscribePayload, UnsubscribePayload, VehicleListResponse, VehicleState, VehicleSummary, VehicleUpdatePayload, WebSocketEnvelope, WebSocketMessages };

package/dist/types.d.ts

@@ -637,6 +637,76 @@ interface Drive {
     createdAt: string;
 }
 
+/**
+ * AUTO-GENERATED by scripts/codegen.mjs from the corresponding JSON Schema
+ * in ../schemas/. DO NOT EDIT BY HAND — re-run `npm run codegen` instead.
+ *
+ * The x-classification / x-atomic-group / x-unit / x-encrypted custom JSON
+ * Schema annotations from the source schemas are folded into the generated
+ * TSDoc comments so grep can find them without leaving the editor.
+ */
+/**
+ * Full GPS polyline for a single completed drive, returned as a bare object by GET /api/drives/{driveId}/route (rest-api.md §7.4, FR-3.3). This is the heavy per-drive route payload deliberately excluded from both DriveSummary (§7.2) and Drive detail (§7.3): the SDK fetches it lazily on tap-through of a drive's map view, NOT eagerly per drive-list row (see §7.4 lazy-fetch guidance — 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 §1.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) — 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.
+ */
+interface DriveRoute {
+    /**
+     * 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).
+     *
+     * @classification "P0"
+     */
+    driveId: string;
+    /**
+     * 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) — 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 — the entire polyline is returned in one response (there is no cursor/limit on this endpoint, unlike the §7.2 drives list).
+     *
+     * @classification "mixed"
+     */
+    routePoints: RoutePoint[];
+}
+/**
+ * A single GPS sample on a drive's polyline. Matches the `RoutePointRecord` shape from data-classification.md §1.5 — 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.
+ *
+ * This interface was referenced by `DriveRoute`'s JSON-Schema
+ * via the `definition` "RoutePoint".
+ */
+interface RoutePoint {
+    /**
+     * 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.
+     *
+     * @classification "P1"
+     * @unit "degrees"
+     * @encrypted-at-rest true
+     */
+    lat: number;
+    /**
+     * Longitude in degrees at this point. Emitted as a JSON number (Go float64).
+     *
+     * @classification "P1"
+     * @unit "degrees"
+     * @encrypted-at-rest true
+     */
+    lng: number;
+    /**
+     * 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).
+     *
+     * @classification "P0"
+     * @unit "mph"
+     */
+    speed: number;
+    /**
+     * 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).
+     *
+     * @classification "P0"
+     * @unit "degrees"
+     */
+    heading: number;
+    /**
+     * 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.
+     *
+     * @classification "P0"
+     */
+    timestamp: string;
+}
+
 /**
  * AUTO-GENERATED by scripts/codegen.mjs from the corresponding JSON Schema
  * in ../schemas/. DO NOT EDIT BY HAND — re-run `npm run codegen` instead.
@@ -980,4 +1050,4 @@ interface WebSocketEnvelope {
     ts?: string;
 }
 
-export type { AuthOkPayload, AuthPayload, ConnectivityPayload, Drive, DriveEndedPayload, DriveStartedPayload, DriveSummary, DrivesListResponse, ErrorPayload, HeartbeatPayload, MessageType, PingPayload, PongPayload, SubscribePayload, UnsubscribePayload, VehicleListResponse, VehicleState, VehicleSummary, VehicleUpdatePayload, WebSocketEnvelope, WebSocketMessages };
+export type { AuthOkPayload, AuthPayload, ConnectivityPayload, Drive, DriveEndedPayload, DriveRoute, DriveStartedPayload, DriveSummary, DrivesListResponse, ErrorPayload, HeartbeatPayload, MessageType, PingPayload, PongPayload, RoutePoint, SubscribePayload, UnsubscribePayload, VehicleListResponse, VehicleState, VehicleSummary, VehicleUpdatePayload, WebSocketEnvelope, WebSocketMessages };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@myrobotaxi/contracts",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Canonical wire-protocol schemas for the MyRoboTaxi platform. JSON Schema (draft-2020-12) + pre-generated TypeScript types. Consumed by SDKs (TS, Swift) and the Go telemetry server.",
   "license": "MIT",
   "repository": {
@@ -41,6 +41,7 @@
     "./schemas/vehicle-summary.json": "./schemas/vehicle-summary.schema.json",
     "./schemas/drives-list.json": "./schemas/drives-list.schema.json",
     "./schemas/drive-detail.json": "./schemas/drive-detail.schema.json",
+    "./schemas/drive-route.json": "./schemas/drive-route.schema.json",
     "./schemas/ws-messages.json": "./schemas/ws-messages.schema.json",
     "./schemas/ws-envelope.json": "./schemas/ws-envelope.schema.json"
   },

package/schemas/drive-route.schema.json

@@ -0,0 +1,78 @@
+{
+  "$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 §7.4, FR-3.3). This is the heavy per-drive route payload deliberately excluded from both DriveSummary (§7.2) and Drive detail (§7.3): the SDK fetches it lazily on tap-through of a drive's map view, NOT eagerly per drive-list row (see §7.4 lazy-fetch guidance — 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 §1.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) — 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) — 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 — the entire polyline is returned in one response (there is no cursor/limit on this endpoint, unlike the §7.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 §1.5 — 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"]
+        }
+      }
+    }
+  }
+}