@myrobotaxi/contracts 0.1.4 → 0.3.0

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-export { AuthOkPayload, AuthPayload, ConnectivityPayload, DriveEndedPayload, DriveStartedPayload, ErrorPayload, HeartbeatPayload, MessageType, PingPayload, PongPayload, SubscribePayload, UnsubscribePayload, VehicleState, VehicleUpdatePayload, WebSocketEnvelope, WebSocketMessages } from './types.cjs';
+export { AuthOkPayload, AuthPayload, ConnectivityPayload, DriveEndedPayload, DriveStartedPayload, ErrorPayload, HeartbeatPayload, MessageType, PingPayload, PongPayload, SubscribePayload, UnsubscribePayload, VehicleListResponse, VehicleState, VehicleSummary, VehicleUpdatePayload, WebSocketEnvelope, WebSocketMessages } from './types.cjs';
 
 declare const schemas: {
     readonly vehicleState: {
@@ -284,6 +284,104 @@ declare const schemas: {
             originLongitude: string[];
         };
     };
+    readonly vehicleSummary: {
+        $schema: string;
+        $id: string;
+        title: string;
+        description: string;
+        type: string;
+        additionalProperties: boolean;
+        required: string[];
+        properties: {
+            items: {
+                type: string;
+                description: string;
+                items: {
+                    $ref: string;
+                };
+            };
+        };
+        $defs: {
+            VehicleSummary: {
+                title: string;
+                description: string;
+                type: string;
+                additionalProperties: boolean;
+                required: string[];
+                properties: {
+                    vehicleId: {
+                        type: string;
+                        description: string;
+                        "x-classification": string;
+                        examples: string[];
+                    };
+                    name: {
+                        type: string;
+                        description: string;
+                        "x-classification": string;
+                        examples: string[];
+                    };
+                    model: {
+                        type: string;
+                        description: string;
+                        "x-classification": string;
+                        examples: string[];
+                    };
+                    year: {
+                        type: string;
+                        description: string;
+                        "x-classification": string;
+                        examples: number[];
+                    };
+                    color: {
+                        type: string;
+                        description: string;
+                        "x-classification": string;
+                        examples: string[];
+                    };
+                    vinLast4: {
+                        type: string;
+                        description: string;
+                        "x-classification": string;
+                        examples: string[];
+                    };
+                    status: {
+                        type: string;
+                        enum: string[];
+                        description: string;
+                        "x-classification": string;
+                    };
+                    chargeLevel: {
+                        type: string;
+                        description: string;
+                        "x-classification": string;
+                        "x-unit": string;
+                        minimum: number;
+                        maximum: number;
+                    };
+                    estimatedRange: {
+                        type: string;
+                        description: string;
+                        "x-classification": string;
+                        "x-unit": string;
+                        minimum: number;
+                    };
+                    lastUpdated: {
+                        type: string;
+                        format: string;
+                        description: string;
+                        "x-classification": string;
+                    };
+                    role: {
+                        type: string;
+                        enum: string[];
+                        description: string;
+                        "x-classification": string;
+                    };
+                };
+            };
+        };
+    };
     readonly wsMessages: {
         $schema: string;
         $id: string;

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { AuthOkPayload, AuthPayload, ConnectivityPayload, DriveEndedPayload, DriveStartedPayload, ErrorPayload, HeartbeatPayload, MessageType, PingPayload, PongPayload, SubscribePayload, UnsubscribePayload, VehicleState, VehicleUpdatePayload, WebSocketEnvelope, WebSocketMessages } from './types.js';
+export { AuthOkPayload, AuthPayload, ConnectivityPayload, DriveEndedPayload, DriveStartedPayload, ErrorPayload, HeartbeatPayload, MessageType, PingPayload, PongPayload, SubscribePayload, UnsubscribePayload, VehicleListResponse, VehicleState, VehicleSummary, VehicleUpdatePayload, WebSocketEnvelope, WebSocketMessages } from './types.js';
 
 declare const schemas: {
     readonly vehicleState: {
@@ -284,6 +284,104 @@ declare const schemas: {
             originLongitude: string[];
         };
     };
+    readonly vehicleSummary: {
+        $schema: string;
+        $id: string;
+        title: string;
+        description: string;
+        type: string;
+        additionalProperties: boolean;
+        required: string[];
+        properties: {
+            items: {
+                type: string;
+                description: string;
+                items: {
+                    $ref: string;
+                };
+            };
+        };
+        $defs: {
+            VehicleSummary: {
+                title: string;
+                description: string;
+                type: string;
+                additionalProperties: boolean;
+                required: string[];
+                properties: {
+                    vehicleId: {
+                        type: string;
+                        description: string;
+                        "x-classification": string;
+                        examples: string[];
+                    };
+                    name: {
+                        type: string;
+                        description: string;
+                        "x-classification": string;
+                        examples: string[];
+                    };
+                    model: {
+                        type: string;
+                        description: string;
+                        "x-classification": string;
+                        examples: string[];
+                    };
+                    year: {
+                        type: string;
+                        description: string;
+                        "x-classification": string;
+                        examples: number[];
+                    };
+                    color: {
+                        type: string;
+                        description: string;
+                        "x-classification": string;
+                        examples: string[];
+                    };
+                    vinLast4: {
+                        type: string;
+                        description: string;
+                        "x-classification": string;
+                        examples: string[];
+                    };
+                    status: {
+                        type: string;
+                        enum: string[];
+                        description: string;
+                        "x-classification": string;
+                    };
+                    chargeLevel: {
+                        type: string;
+                        description: string;
+                        "x-classification": string;
+                        "x-unit": string;
+                        minimum: number;
+                        maximum: number;
+                    };
+                    estimatedRange: {
+                        type: string;
+                        description: string;
+                        "x-classification": string;
+                        "x-unit": string;
+                        minimum: number;
+                    };
+                    lastUpdated: {
+                        type: string;
+                        format: string;
+                        description: string;
+                        "x-classification": string;
+                    };
+                    role: {
+                        type: string;
+                        enum: string[];
+                        description: string;
+                        "x-classification": string;
+                    };
+                };
+            };
+        };
+    };
     readonly wsMessages: {
         $schema: string;
         $id: string;

package/dist/index.js

@@ -343,6 +343,116 @@ var vehicle_state_schema_default = {
   }
 };
 
+// schemas/vehicle-summary.schema.json
+var vehicle_summary_schema_default = {
+  $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 \xA77.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 \u2014 see rest-api.md \xA77.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 \u2014 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 \u2014 see rest-api.md \xA77.0 RBAC v1 implementation note.",
+          "x-classification": "P0"
+        }
+      }
+    }
+  }
+};
+
 // schemas/ws-messages.schema.json
 var ws_messages_schema_default = {
   $schema: "https://json-schema.org/draft/2020-12/schema",
@@ -559,7 +669,7 @@ var ws_messages_schema_default = {
       properties: {
         code: {
           type: "string",
-          description: "Stable typed error code from the catalog in websocket-protocol.md \xA76.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 \xA710. `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 \xA76.1.1 and \xA77.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 \xA74.1.1, \xA74.1.1.a; ws catalog websocket-protocol.md \xA76.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 \xA710). `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 \xA74.1.1.a) but are members of this shared enum by mandate so the SDK union is one enum across transports \u2014 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) \u2014 the SDK treats both as the same typed error with the extended backoff in websocket-protocol.md \xA76.1.1 / \xA77.1.",
           enum: [
             "auth_failed",
             "auth_timeout",
@@ -567,7 +677,9 @@ var ws_messages_schema_default = {
             "vehicle_not_owned",
             "rate_limited",
             "internal_error",
-            "snapshot_required"
+            "snapshot_required",
+            "not_found",
+            "invalid_request"
           ],
           "x-classification": "P0"
         },
@@ -578,8 +690,8 @@ var ws_messages_schema_default = {
         },
         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 \xA76.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 \u2014 see websocket-protocol.md \xA76.1.1). `reauth_required`: REST-only, emitted with `code: auth_failed` by rest-api.md \xA77.6 / \xA77.7 when the bearer token is valid but the most recent fresh OAuth sign-in is older than the recent-auth window \u2014 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"
         }
       }
@@ -710,6 +822,7 @@ var ws_envelope_schema_default = {
 // src/index.ts
 var schemas = {
   vehicleState: vehicle_state_schema_default,
+  vehicleSummary: vehicle_summary_schema_default,
   wsMessages: ws_messages_schema_default,
   wsEnvelope: ws_envelope_schema_default
 };