@myrobotaxi/contracts 0.5.0 → 0.7.0

package/schemas/drives-list.schema.json

@@ -0,0 +1,184 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://myrobotaxi.com/schemas/drives-list.schema.json",
+  "title": "DrivesListResponse",
+  "description": "Cursor-paginated envelope returned by GET /api/vehicles/{vehicleId}/drives (rest-api.md §7.2). Wraps an array of DriveSummary rows under `items`, newest first (ORDER BY startTime DESC, id DESC). Mirrors the Go `drivesPageResponse` struct in telemetry/internal/telemetry/vehicle_drives_types.go and the `PaginatedDrives` component in telemetry/docs/contracts/specs/rest.openapi.yaml. Pairs with the WebSocket `drive_ended` subscription for FR-9.1/FR-9.2: the SDK hydrates the first page here and prepends live `drive_ended` frames without re-fetching. The envelope is part of the wire contract: consumers MUST NOT strip it silently.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["items", "nextCursor", "hasMore"],
+  "properties": {
+    "items": {
+      "type": "array",
+      "description": "Drive summary rows for this page. Always present; an empty array (never null) means no more drives — e.g. the final page or a vehicle with no completed drives. Ordered startTime DESC, id DESC (rest-api.md §7.2 Ordering).",
+      "x-classification": "P0",
+      "items": { "$ref": "#/$defs/DriveSummary" }
+    },
+    "nextCursor": {
+      "type": ["string", "null"],
+      "description": "Opaque base64 cursor for the next page, or null on the final page. Pass it back as the `cursor` query param to fetch the next page. Encodes (startTime, id) so pagination is stable across concurrent writes. Nullable on the wire — the Go server emits JSON `null` (not an omitted key) when there is no further page (drivesPageResponse.NextCursor is a `*string` with no omitempty, telemetry/internal/telemetry/vehicle_drives_types.go). Redundant with `hasMore == false`.",
+      "x-classification": "P0"
+    },
+    "hasMore": {
+      "type": "boolean",
+      "description": "True iff more pages exist after this one. Redundant with `nextCursor != null`, provided for caller convenience.",
+      "x-classification": "P0"
+    }
+  },
+  "$defs": {
+    "DriveSummary": {
+      "title": "DriveSummary",
+      "description": "Lightweight per-drive row returned by GET /api/vehicles/{vehicleId}/drives. A list-view projection of a completed drive containing the FR-3.4 headline stats plus origin/destination labels, so the history list renders without a per-row DriveDetail fetch. Includes the four P1 location/address labels (MYR-145) and the P0 fsdMiles/fsdPercentage stats (MYR-152). Deliberately omits energyUsedKwh, interventions, and routePoints — those live on Drive (drive detail, §7.3) and DriveRoute (§7.4). Mirrors the Go `driveSummary` struct + `toMaskMap` in telemetry/internal/telemetry/vehicle_drives_types.go and the `DriveSummary` component in telemetry/docs/contracts/specs/rest.openapi.yaml.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "id",
+        "vehicleId",
+        "startTime",
+        "endTime",
+        "date",
+        "distanceMiles",
+        "durationSeconds",
+        "avgSpeedMph",
+        "maxSpeedMph",
+        "startChargeLevel",
+        "endChargeLevel",
+        "fsdMiles",
+        "fsdPercentage",
+        "createdAt"
+      ],
+      "properties": {
+        "id": {
+          "type": "string",
+          "description": "Opaque database identifier (cuid) for this drive. Matches the `driveId` carried by `drive_started` / `drive_ended` WebSocket frames and the path param of GET /api/drives/{driveId}.",
+          "x-classification": "P0",
+          "examples": ["clmno9876543210zyxw0001"]
+        },
+        "vehicleId": {
+          "type": "string",
+          "description": "Opaque database identifier (cuid) for the drive's parent vehicle. Matches VehicleState.vehicleId / VehicleSummary.vehicleId.",
+          "x-classification": "P0",
+          "examples": ["clxyz1234567890abcdef"]
+        },
+        "startTime": {
+          "type": "string",
+          "format": "date-time",
+          "description": "ISO 8601 / RFC 3339 UTC timestamp when the drive began (e.g., '2026-04-13T18:22:00Z').",
+          "x-classification": "P0",
+          "examples": ["2026-04-13T18:22:00Z"]
+        },
+        "endTime": {
+          "type": "string",
+          "format": "date-time",
+          "description": "ISO 8601 / RFC 3339 UTC timestamp when the drive ended (e.g., '2026-04-13T18:46:18Z').",
+          "x-classification": "P0",
+          "examples": ["2026-04-13T18:46:18Z"]
+        },
+        "date": {
+          "type": "string",
+          "format": "date",
+          "description": "Local calendar date of the drive as a 'YYYY-MM-DD' string (e.g., '2026-04-13'), for day-grouping the history list. Not a full timestamp — use startTime/endTime for instants.",
+          "x-classification": "P0",
+          "examples": ["2026-04-13"]
+        },
+        "startLocation": {
+          "type": "string",
+          "description": "Reverse-geocoded place name at the drive's start (e.g., 'Home', 'Whole Foods Market'). OPTIONAL on the wire: the Go handler OMITS this key entirely (never emits '' or null) when the underlying Drive.startLocation column is empty — zero-GPS at drive start or reverse-geocode failed (toMaskMap, telemetry/internal/telemetry/vehicle_drives_types.go). Consumers branch on key presence.",
+          "x-classification": "P1",
+          "examples": ["Home"]
+        },
+        "startAddress": {
+          "type": "string",
+          "description": "Reverse-geocoded street address at the drive's start. OPTIONAL on the wire: the key is omitted entirely when the underlying Drive.startAddress column is empty (same omit-when-empty convention as startLocation).",
+          "x-classification": "P1",
+          "examples": ["742 Evergreen Terrace, San Francisco, CA 94107"]
+        },
+        "endLocation": {
+          "type": "string",
+          "description": "Reverse-geocoded place name at the drive's end. OPTIONAL on the wire: the key is omitted entirely when the underlying Drive.endLocation column is empty — drive in progress, zero-GPS at drive end, or reverse-geocode failed.",
+          "x-classification": "P1",
+          "examples": ["Whole Foods Market"]
+        },
+        "endAddress": {
+          "type": "string",
+          "description": "Reverse-geocoded street address at the drive's end. OPTIONAL on the wire: the key is omitted entirely when the underlying Drive.endAddress column is empty.",
+          "x-classification": "P1",
+          "examples": ["399 4th Street, San Francisco, CA 94107"]
+        },
+        "distanceMiles": {
+          "type": "number",
+          "description": "Total distance driven, in miles (FR-3.4).",
+          "x-classification": "P0",
+          "x-unit": "miles",
+          "minimum": 0,
+          "examples": [12.4]
+        },
+        "durationSeconds": {
+          "type": "integer",
+          "description": "Total drive duration, in seconds (FR-3.4). The Go server converts the stored DurationMinutes to seconds (DurationMinutes * 60) before emitting. Matches the WebSocket drive_ended.payload.durationSeconds shape (DV-12).",
+          "x-classification": "P0",
+          "x-unit": "seconds",
+          "minimum": 0,
+          "examples": [1458]
+        },
+        "avgSpeedMph": {
+          "type": "number",
+          "description": "Average speed over the drive, in miles per hour (FR-3.4).",
+          "x-classification": "P0",
+          "x-unit": "mph",
+          "minimum": 0,
+          "examples": [30.5]
+        },
+        "maxSpeedMph": {
+          "type": "number",
+          "description": "Maximum speed reached during the drive, in miles per hour (FR-3.4).",
+          "x-classification": "P0",
+          "x-unit": "mph",
+          "minimum": 0,
+          "examples": [65.2]
+        },
+        "startChargeLevel": {
+          "type": "integer",
+          "description": "Battery state of charge at drive start (FR-3.4).",
+          "x-classification": "P0",
+          "x-unit": "percent",
+          "minimum": 0,
+          "maximum": 100,
+          "examples": [82]
+        },
+        "endChargeLevel": {
+          "type": "integer",
+          "description": "Battery state of charge at drive end (FR-3.4).",
+          "x-classification": "P0",
+          "x-unit": "percent",
+          "minimum": 0,
+          "maximum": 100,
+          "examples": [76]
+        },
+        "fsdMiles": {
+          "type": "number",
+          "description": "Miles driven under Full Self-Driving during this drive (FR-3.4, MYR-152). Always present; defaults to 0 for a drive with no FSD usage.",
+          "x-classification": "P0",
+          "x-unit": "miles",
+          "minimum": 0,
+          "examples": [8.1]
+        },
+        "fsdPercentage": {
+          "type": "number",
+          "description": "Percent of the drive covered by FSD (FR-3.4, MYR-152). Always present; defaults to 0 for a drive with no FSD usage.",
+          "x-classification": "P0",
+          "x-unit": "percent",
+          "minimum": 0,
+          "maximum": 100,
+          "examples": [65.3]
+        },
+        "createdAt": {
+          "type": "string",
+          "format": "date-time",
+          "description": "ISO 8601 / RFC 3339 UTC row-creation timestamp. The Go server renders it as `CreatedAt.UTC().Format(time.RFC3339)` (telemetry/internal/telemetry/vehicle_drives_types.go).",
+          "x-classification": "P0",
+          "examples": ["2026-04-13T18:46:19Z"]
+        }
+      }
+    }
+  }
+}