@myrobotaxi/contracts 0.5.0 → 0.6.0

package/dist/index.js

@@ -453,6 +453,368 @@ var vehicle_summary_schema_default = {
   }
 };
 
+// schemas/drives-list.schema.json
+var drives_list_schema_default = {
+  $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 \xA77.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 \u2014 e.g. the final page or a vehicle with no completed drives. Ordered startTime DESC, id DESC (rest-api.md \xA77.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 \u2014 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 \u2014 those live on Drive (drive detail, \xA77.3) and DriveRoute (\xA77.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 \u2014 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 \u2014 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 \u2014 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"]
+        }
+      }
+    }
+  }
+};
+
+// schemas/drive-detail.schema.json
+var drive_detail_schema_default = {
+  $schema: "https://json-schema.org/draft/2020-12/schema",
+  $id: "https://myrobotaxi.com/schemas/drive-detail.schema.json",
+  title: "Drive",
+  description: "Full FR-3.4 record for a single completed drive, returned as a bare object (NOT an envelope) by GET /api/drives/{driveId} (rest-api.md \xA77.3). Contains every FR-3.4 stat EXCEPT routePoints, which is served separately by GET /api/drives/{driveId}/route (DriveRoute, \xA77.4). This is the tap-through detail behind a DriveSummary row / a `drive_ended` frame: the SDK's fetchDrive(driveId) helper. Mirrors the Go `driveDetail` struct + `toMaskMap` in telemetry/internal/telemetry/drive_detail_types.go and the `DriveDetail` component in telemetry/docs/contracts/specs/rest.openapi.yaml. Owners and viewers see the same field set including start/end location and address (viewer consent via accepted invite, \xA75.2.3).",
+  type: "object",
+  additionalProperties: false,
+  required: [
+    "id",
+    "vehicleId",
+    "startTime",
+    "endTime",
+    "date",
+    "distanceMiles",
+    "durationSeconds",
+    "avgSpeedMph",
+    "maxSpeedMph",
+    "energyUsedKwh",
+    "startChargeLevel",
+    "endChargeLevel",
+    "fsdMiles",
+    "fsdPercentage",
+    "interventions",
+    "createdAt"
+  ],
+  properties: {
+    id: {
+      type: "string",
+      description: "Opaque database identifier (cuid) for this drive. Matches DriveSummary.id and the `driveId` carried by `drive_started` / `drive_ended` WebSocket frames.",
+      "x-classification": "P0",
+      examples: ["clmno9876543210zyxw0001"]
+    },
+    vehicleId: {
+      type: "string",
+      description: "Opaque database identifier (cuid) for the drive's parent vehicle. Matches VehicleState.vehicleId / VehicleSummary.vehicleId / DriveSummary.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'). Same field as DriveSummary.date.",
+      "x-classification": "P0",
+      examples: ["2026-04-13"]
+    },
+    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.",
+      "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]
+    },
+    energyUsedKwh: {
+      type: "number",
+      description: "Energy consumed during the drive, in kilowatt-hours (FR-3.4). Detail-only stat \u2014 deliberately absent from DriveSummary.",
+      "x-classification": "P0",
+      "x-unit": "kWh",
+      minimum: 0,
+      examples: [4.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). 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). 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]
+    },
+    interventions: {
+      type: "integer",
+      description: "Count of FSD interventions recorded during the drive (FR-3.4). Detail-only stat \u2014 deliberately absent from DriveSummary.",
+      "x-classification": "P0",
+      minimum: 0,
+      examples: [1]
+    },
+    startLocation: {
+      type: "string",
+      description: "Reverse-geocoded place name at the drive's start (e.g., 'Home'). OPTIONAL on the wire: the Go handler OMITS this key entirely (never emits '' or null) when the underlying Drive.startLocation column is empty (toMaskMap, telemetry/internal/telemetry/drive_detail_types.go). Consumers branch on key presence. NOTE: the OpenAPI DriveDetail component types this `[string, null]`, but the Go handler omits the key rather than emitting null \u2014 the code is ground truth (see MYR-202 PR body doc-drift note).",
+      "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.",
+      "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"]
+    },
+    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/drive_detail_types.go).",
+      "x-classification": "P0",
+      examples: ["2026-04-13T18:46:19Z"]
+    }
+  }
+};
+
 // schemas/ws-messages.schema.json
 var ws_messages_schema_default = {
   $schema: "https://json-schema.org/draft/2020-12/schema",
@@ -823,6 +1185,8 @@ var ws_envelope_schema_default = {
 var schemas = {
   vehicleState: vehicle_state_schema_default,
   vehicleSummary: vehicle_summary_schema_default,
+  drivesList: drives_list_schema_default,
+  driveDetail: drive_detail_schema_default,
   wsMessages: ws_messages_schema_default,
   wsEnvelope: ws_envelope_schema_default
 };