@myrobotaxi/contracts 0.1.4 → 0.3.0

package/dist/types.d.ts

@@ -244,6 +244,100 @@ interface VehicleState {
     lastUpdated: 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.
+ */
+/**
+ * Envelope returned by GET /api/vehicles. Wraps an array of VehicleSummary rows under the `items` key. Pagination fields are reserved per rest-api.md §7.0 and intentionally absent in v1. The envelope itself is part of the wire contract: consumers MUST NOT strip it silently.
+ */
+interface VehicleListResponse {
+    /**
+     * Per-vehicle summary rows for vehicles the caller has access to. Order is server-defined (currently ORDER BY Vehicle.createdAt ASC in the telemetry list query). An empty array means the caller has no vehicles (or is a v1 viewer-tier caller — see rest-api.md §7.0 RBAC v1 implementation note).
+     */
+    items: VehicleSummary[];
+}
+/**
+ * Lean per-vehicle row returned by GET /api/vehicles. A list-view projection of VehicleState containing only the fields the catalog UI needs (identity, model/year/color, status, charge headline, last-updated). No GPS, no navigation, no climate, no encrypted-at-rest fields. Mirrors the Go `vehicleSummary` struct in telemetry/internal/telemetry/vehicles_list_handler.go and the `VehicleSummary` shape in telemetry/specs/rest.openapi.yaml. Use VehicleState for the full snapshot/WebSocket payload; use VehicleSummary for list endpoints.
+ *
+ * This interface was referenced by `VehicleListResponse`'s JSON-Schema
+ * via the `definition` "VehicleSummary".
+ */
+interface VehicleSummary {
+    /**
+     * Opaque database identifier (cuid). NOT the VIN. All SDK API calls use this ID (FR-4.2). Matches VehicleState.vehicleId.
+     *
+     * @classification "P0"
+     */
+    vehicleId: string;
+    /**
+     * User-assigned vehicle name from DB Vehicle.name. Matches VehicleState.name.
+     *
+     * @classification "P0"
+     */
+    name: string;
+    /**
+     * Vehicle model (e.g., 'Model 3', 'Model Y'). Sourced from DB Vehicle.model. Matches VehicleState.model.
+     *
+     * @classification "P0"
+     */
+    model: string;
+    /**
+     * Model year. Sourced from DB Vehicle.year. Matches VehicleState.year.
+     *
+     * @classification "P0"
+     */
+    year: number;
+    /**
+     * Vehicle exterior color. Sourced from DB Vehicle.color. Matches VehicleState.color.
+     *
+     * @classification "P0"
+     */
+    color: string;
+    /**
+     * Last 4 characters of the vehicle's 17-character VIN. The full VIN is never emitted on the list endpoint — vinLast4 is sufficient for human disambiguation in the catalog UI without exposing the full identifier. Empty string when the VIN is unknown.
+     *
+     * @classification "P1"
+     */
+    vinLast4: string;
+    /**
+     * Derived vehicle status snapshot at the time of the last telemetry update. Same enum as VehicleState.status.
+     *
+     * @classification "P0"
+     */
+    status: 'driving' | 'parked' | 'charging' | 'offline' | 'in_service';
+    /**
+     * Battery state of charge snapshot at the time of the last telemetry update. Same semantics as VehicleState.chargeLevel.
+     *
+     * @classification "P0"
+     * @unit "percent"
+     */
+    chargeLevel: number;
+    /**
+     * Estimated remaining driving range snapshot at the time of the last telemetry update. Same semantics as VehicleState.estimatedRange.
+     *
+     * @classification "P0"
+     * @unit "miles"
+     */
+    estimatedRange: number;
+    /**
+     * ISO 8601 timestamp of the most recent telemetry update applied to this vehicle. Same semantics as VehicleState.lastUpdated. Telemetry emits RFC 3339 UTC strings (e.g., '2026-05-25T17:30:00Z').
+     *
+     * @classification "P0"
+     */
+    lastUpdated: string;
+    /**
+     * RBAC role the caller holds against this vehicle. v1 only emits 'owner' rows (every vehicle returned is one the caller owns via Vehicle.userId). The 'viewer' value is reserved for the viewer-merged invite-read pathway tracked as a follow-up — see rest-api.md §7.0 RBAC v1 implementation note.
+     *
+     * @classification "P0"
+     */
+    role: 'owner' | 'viewer';
+}
+
 /**
  * AUTO-GENERATED by scripts/codegen.mjs from the corresponding JSON Schema
  * in ../schemas/. DO NOT EDIT BY HAND — re-run `npm run codegen` instead.
@@ -467,11 +561,11 @@ interface HeartbeatPayload {
  */
 interface ErrorPayload {
     /**
-     * Stable typed error code from the catalog in websocket-protocol.md §6.1.1. Consumer SDKs map these to typed errors per FR-7.1 and MUST NOT string-match on the sibling `message` field. `auth_failed` and `auth_timeout` are emitted today; the remaining values are reserved for PLANNED server emission tracked by divergences DV-02 / DV-07 / DV-08 in websocket-protocol.md §10. `rate_limited` has two carriers: (a) an HTTP 429 response on the WS upgrade (per-IP cap breach, pre-auth) and (b) an `error` frame paired with WebSocket close code 4003 Server Overload (per-user cap breach, post-auth). The SDK MUST treat both carriers as the same typed error and apply the extended reconnect backoff documented in websocket-protocol.md §6.1.1 and §7.1.
+     * Stable typed error code. Shared enum across the WebSocket and REST transports so the SDK's CoreError is a single union (rest-api.md §4.1.1, §4.1.1.a; ws catalog websocket-protocol.md §6.1.1). Consumer SDKs map these to typed errors per FR-7.1 and MUST NOT string-match on the sibling `message` field. WS emits today: `auth_failed`, `auth_timeout`; the remaining WS values are PLANNED (divergences DV-02 / DV-07 / DV-08 in websocket-protocol.md §10). `not_found` and `invalid_request` are REST-only on the wire (the WS path enforces ownership via silent filtering and has no structured request bodies, rest-api.md §4.1.1.a) but are members of this shared enum by mandate so the SDK union is one enum across transports — they are NOT a WS drift (DV-20 enum slice). `service_unavailable` is intentionally NOT in this enum: it is REST-only and the WS 503 analogue is a close code, not a typed frame (rest-api.md:258); the SDK declares it as a REST-only variant on its side. `rate_limited` has two carriers: (a) HTTP 429 on the WS upgrade (per-IP, pre-auth) and (b) an `error` frame paired with WS close 4003 (per-user, post-auth) — the SDK treats both as the same typed error with the extended backoff in websocket-protocol.md §6.1.1 / §7.1.
      *
      * @classification "P0"
      */
-    code: 'auth_failed' | 'auth_timeout' | 'permission_denied' | 'vehicle_not_owned' | 'rate_limited' | 'internal_error' | 'snapshot_required';
+    code: 'auth_failed' | 'auth_timeout' | 'permission_denied' | 'vehicle_not_owned' | 'rate_limited' | 'internal_error' | 'snapshot_required' | 'not_found' | 'invalid_request';
     /**
      * Human-readable description for logs and developer tooling. P0 BUT MUST NOT contain P1 values (no GPS, no addresses, no tokens, no emails, no VINs unless redacted to ***XXXX). Per data-classification.md §2.1-2.2, error message construction sites MUST use opaque IDs only.
      *
@@ -479,11 +573,11 @@ interface ErrorPayload {
      */
     message: string;
     /**
-     * Optional typed sub-code for branching consumer-visible UI when the primary code is ambiguous across carriers. Currently defined only for `rate_limited`: when the server rejects a connection because it breached the per-user cap (post-auth, close 4003), the error frame MUST carry `subCode: "device_cap"` so SDKs can surface an actionable 'Too many devices signed in' message instead of a generic rate-limit toast. Per-IP breaches (HTTP 429 on upgrade) do NOT carry a sub-code because the SDK cannot distinguish NAT-mate floods from user intent. See websocket-protocol.md §6.1.1 for the full device_cap UX contract.
+     * Optional typed sub-code for branching consumer-visible UI when the primary code is ambiguous across carriers. v1 enum: `device_cap` (WS-only) and `reauth_required` (REST-only). `device_cap`: WS server rejected a connection because it breached the per-user cap (post-auth, close 4003); the error frame carries `subCode: "device_cap"` so SDKs surface an actionable 'Too many devices signed in' message instead of a generic rate-limit toast (per-IP HTTP 429 breaches carry no sub-code — see websocket-protocol.md §6.1.1). `reauth_required`: REST-only, emitted with `code: auth_failed` by rest-api.md §7.6 / §7.7 when the bearer token is valid but the most recent fresh OAuth sign-in is older than the recent-auth window — the SDK MUST surface this to the consumer's auth layer to trigger a fresh interactive sign-in and MUST NOT silently retry via getToken() (a silent refresh cannot advance the `auth_time` claim). Declared on this shared enum for single-union SDK typing; the WS transport never emits `reauth_required`.
      *
      * @classification "P0"
      */
-    subCode?: 'device_cap';
+    subCode?: 'device_cap' | 'reauth_required';
 }
 /**
  * PLANNED — NOT accepted by the server today. Client->server request to begin or resume streaming a specific vehicle. Today the server implicitly subscribes the client to ALL vehicles owned by the authenticated user as part of the auth handshake (handler.go authenticateClient -> Authenticator.GetUserVehicles). Adding explicit subscribe/unsubscribe is tracked as divergence DV-07 in websocket-protocol.md §10. `sinceSeq` snapshot-resume depends on divergence DV-02 (envelope `seq`) landing first.
@@ -587,4 +681,4 @@ interface WebSocketEnvelope {
     ts?: string;
 }
 
-export type { AuthOkPayload, AuthPayload, ConnectivityPayload, DriveEndedPayload, DriveStartedPayload, ErrorPayload, HeartbeatPayload, MessageType, PingPayload, PongPayload, SubscribePayload, UnsubscribePayload, VehicleState, VehicleUpdatePayload, WebSocketEnvelope, WebSocketMessages };
+export type { AuthOkPayload, AuthPayload, ConnectivityPayload, DriveEndedPayload, DriveStartedPayload, ErrorPayload, HeartbeatPayload, MessageType, PingPayload, PongPayload, SubscribePayload, UnsubscribePayload, VehicleListResponse, VehicleState, VehicleSummary, VehicleUpdatePayload, WebSocketEnvelope, WebSocketMessages };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@myrobotaxi/contracts",
-  "version": "0.1.4",
+  "version": "0.3.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": {
@@ -38,6 +38,7 @@
       }
     },
     "./schemas/vehicle-state.json": "./schemas/vehicle-state.schema.json",
+    "./schemas/vehicle-summary.json": "./schemas/vehicle-summary.schema.json",
     "./schemas/ws-messages.json": "./schemas/ws-messages.schema.json",
     "./schemas/ws-envelope.json": "./schemas/ws-envelope.schema.json"
   },

package/schemas/vehicle-summary.schema.json

@@ -0,0 +1,108 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://myrobotaxi.com/schemas/vehicle-summary.schema.json",
+  "title": "VehicleListResponse",
+  "description": "Envelope returned by GET /api/vehicles. Wraps an array of VehicleSummary rows under the `items` key. Pagination fields are reserved per rest-api.md §7.0 and intentionally absent in v1. The envelope itself is part of the wire contract: consumers MUST NOT strip it silently.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["items"],
+  "properties": {
+    "items": {
+      "type": "array",
+      "description": "Per-vehicle summary rows for vehicles the caller has access to. Order is server-defined (currently ORDER BY Vehicle.createdAt ASC in the telemetry list query). An empty array means the caller has no vehicles (or is a v1 viewer-tier caller — see rest-api.md §7.0 RBAC v1 implementation note).",
+      "items": { "$ref": "#/$defs/VehicleSummary" }
+    }
+  },
+  "$defs": {
+    "VehicleSummary": {
+      "title": "VehicleSummary",
+      "description": "Lean per-vehicle row returned by GET /api/vehicles. A list-view projection of VehicleState containing only the fields the catalog UI needs (identity, model/year/color, status, charge headline, last-updated). No GPS, no navigation, no climate, no encrypted-at-rest fields. Mirrors the Go `vehicleSummary` struct in telemetry/internal/telemetry/vehicles_list_handler.go and the `VehicleSummary` shape in telemetry/specs/rest.openapi.yaml. Use VehicleState for the full snapshot/WebSocket payload; use VehicleSummary for list endpoints.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "vehicleId",
+        "name",
+        "model",
+        "year",
+        "color",
+        "vinLast4",
+        "status",
+        "chargeLevel",
+        "estimatedRange",
+        "lastUpdated",
+        "role"
+      ],
+      "properties": {
+        "vehicleId": {
+          "type": "string",
+          "description": "Opaque database identifier (cuid). NOT the VIN. All SDK API calls use this ID (FR-4.2). Matches VehicleState.vehicleId.",
+          "x-classification": "P0",
+          "examples": ["clxyz1234567890abcdef"]
+        },
+        "name": {
+          "type": "string",
+          "description": "User-assigned vehicle name from DB Vehicle.name. Matches VehicleState.name.",
+          "x-classification": "P0",
+          "examples": ["Optimus"]
+        },
+        "model": {
+          "type": "string",
+          "description": "Vehicle model (e.g., 'Model 3', 'Model Y'). Sourced from DB Vehicle.model. Matches VehicleState.model.",
+          "x-classification": "P0",
+          "examples": ["Model 3"]
+        },
+        "year": {
+          "type": "integer",
+          "description": "Model year. Sourced from DB Vehicle.year. Matches VehicleState.year.",
+          "x-classification": "P0",
+          "examples": [2024]
+        },
+        "color": {
+          "type": "string",
+          "description": "Vehicle exterior color. Sourced from DB Vehicle.color. Matches VehicleState.color.",
+          "x-classification": "P0",
+          "examples": ["Midnight Silver Metallic"]
+        },
+        "vinLast4": {
+          "type": "string",
+          "description": "Last 4 characters of the vehicle's 17-character VIN. The full VIN is never emitted on the list endpoint — vinLast4 is sufficient for human disambiguation in the catalog UI without exposing the full identifier. Empty string when the VIN is unknown.",
+          "x-classification": "P1",
+          "examples": ["3F5A"]
+        },
+        "status": {
+          "type": "string",
+          "enum": ["driving", "parked", "charging", "offline", "in_service"],
+          "description": "Derived vehicle status snapshot at the time of the last telemetry update. Same enum as VehicleState.status.",
+          "x-classification": "P0"
+        },
+        "chargeLevel": {
+          "type": "integer",
+          "description": "Battery state of charge snapshot at the time of the last telemetry update. Same semantics as VehicleState.chargeLevel.",
+          "x-classification": "P0",
+          "x-unit": "percent",
+          "minimum": 0,
+          "maximum": 100
+        },
+        "estimatedRange": {
+          "type": "integer",
+          "description": "Estimated remaining driving range snapshot at the time of the last telemetry update. Same semantics as VehicleState.estimatedRange.",
+          "x-classification": "P0",
+          "x-unit": "miles",
+          "minimum": 0
+        },
+        "lastUpdated": {
+          "type": "string",
+          "format": "date-time",
+          "description": "ISO 8601 timestamp of the most recent telemetry update applied to this vehicle. Same semantics as VehicleState.lastUpdated. Telemetry emits RFC 3339 UTC strings (e.g., '2026-05-25T17:30:00Z').",
+          "x-classification": "P0"
+        },
+        "role": {
+          "type": "string",
+          "enum": ["owner", "viewer"],
+          "description": "RBAC role the caller holds against this vehicle. v1 only emits 'owner' rows (every vehicle returned is one the caller owns via Vehicle.userId). The 'viewer' value is reserved for the viewer-merged invite-read pathway tracked as a follow-up — see rest-api.md §7.0 RBAC v1 implementation note.",
+          "x-classification": "P0"
+        }
+      }
+    }
+  }
+}

package/schemas/ws-messages.schema.json

@@ -213,7 +213,7 @@
       "properties": {
         "code": {
           "type": "string",
-          "description": "Stable typed error code from the catalog in websocket-protocol.md §6.1.1. Consumer SDKs map these to typed errors per FR-7.1 and MUST NOT string-match on the sibling `message` field. `auth_failed` and `auth_timeout` are emitted today; the remaining values are reserved for PLANNED server emission tracked by divergences DV-02 / DV-07 / DV-08 in websocket-protocol.md §10. `rate_limited` has two carriers: (a) an HTTP 429 response on the WS upgrade (per-IP cap breach, pre-auth) and (b) an `error` frame paired with WebSocket close code 4003 Server Overload (per-user cap breach, post-auth). The SDK MUST treat both carriers as the same typed error and apply the extended reconnect backoff documented in websocket-protocol.md §6.1.1 and §7.1.",
+          "description": "Stable typed error code. Shared enum across the WebSocket and REST transports so the SDK's CoreError is a single union (rest-api.md §4.1.1, §4.1.1.a; ws catalog websocket-protocol.md §6.1.1). Consumer SDKs map these to typed errors per FR-7.1 and MUST NOT string-match on the sibling `message` field. WS emits today: `auth_failed`, `auth_timeout`; the remaining WS values are PLANNED (divergences DV-02 / DV-07 / DV-08 in websocket-protocol.md §10). `not_found` and `invalid_request` are REST-only on the wire (the WS path enforces ownership via silent filtering and has no structured request bodies, rest-api.md §4.1.1.a) but are members of this shared enum by mandate so the SDK union is one enum across transports — they are NOT a WS drift (DV-20 enum slice). `service_unavailable` is intentionally NOT in this enum: it is REST-only and the WS 503 analogue is a close code, not a typed frame (rest-api.md:258); the SDK declares it as a REST-only variant on its side. `rate_limited` has two carriers: (a) HTTP 429 on the WS upgrade (per-IP, pre-auth) and (b) an `error` frame paired with WS close 4003 (per-user, post-auth) — the SDK treats both as the same typed error with the extended backoff in websocket-protocol.md §6.1.1 / §7.1.",
           "enum": [
             "auth_failed",
             "auth_timeout",
@@ -221,7 +221,9 @@
             "vehicle_not_owned",
             "rate_limited",
             "internal_error",
-            "snapshot_required"
+            "snapshot_required",
+            "not_found",
+            "invalid_request"
           ],
           "x-classification": "P0"
         },
@@ -232,8 +234,8 @@
         },
         "subCode": {
           "type": "string",
-          "description": "Optional typed sub-code for branching consumer-visible UI when the primary code is ambiguous across carriers. Currently defined only for `rate_limited`: when the server rejects a connection because it breached the per-user cap (post-auth, close 4003), the error frame MUST carry `subCode: \"device_cap\"` so SDKs can surface an actionable 'Too many devices signed in' message instead of a generic rate-limit toast. Per-IP breaches (HTTP 429 on upgrade) do NOT carry a sub-code because the SDK cannot distinguish NAT-mate floods from user intent. See websocket-protocol.md §6.1.1 for the full device_cap UX contract.",
-          "enum": ["device_cap"],
+          "description": "Optional typed sub-code for branching consumer-visible UI when the primary code is ambiguous across carriers. v1 enum: `device_cap` (WS-only) and `reauth_required` (REST-only). `device_cap`: WS server rejected a connection because it breached the per-user cap (post-auth, close 4003); the error frame carries `subCode: \"device_cap\"` so SDKs surface an actionable 'Too many devices signed in' message instead of a generic rate-limit toast (per-IP HTTP 429 breaches carry no sub-code — see websocket-protocol.md §6.1.1). `reauth_required`: REST-only, emitted with `code: auth_failed` by rest-api.md §7.6 / §7.7 when the bearer token is valid but the most recent fresh OAuth sign-in is older than the recent-auth window — the SDK MUST surface this to the consumer's auth layer to trigger a fresh interactive sign-in and MUST NOT silently retry via getToken() (a silent refresh cannot advance the `auth_time` claim). Declared on this shared enum for single-union SDK typing; the WS transport never emits `reauth_required`.",
+          "enum": ["device_cap", "reauth_required"],
           "x-classification": "P0"
         }
       }