@myrobotaxi/contracts 0.1.0

package/package.json

@@ -0,0 +1,77 @@
+{
+  "name": "@myrobotaxi/contracts",
+  "version": "0.1.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": {
+    "type": "git",
+    "url": "git+https://github.com/myrobotaxi/contracts.git"
+  },
+  "homepage": "https://github.com/myrobotaxi/contracts#readme",
+  "bugs": "https://github.com/myrobotaxi/contracts/issues",
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./types": {
+      "import": {
+        "types": "./dist/types.d.ts",
+        "default": "./dist/types.js"
+      },
+      "require": {
+        "types": "./dist/types.d.cts",
+        "default": "./dist/types.cjs"
+      }
+    },
+    "./schemas/vehicle-state.json": "./schemas/vehicle-state.schema.json",
+    "./schemas/ws-messages.json": "./schemas/ws-messages.schema.json",
+    "./schemas/ws-envelope.json": "./schemas/ws-envelope.schema.json"
+  },
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "schemas",
+    "README.md",
+    "CONTRIBUTING.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "codegen": "node scripts/codegen.mjs",
+    "build": "tsup",
+    "clean": "rm -rf dist coverage",
+    "lint": "eslint .",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "prepare": "[ -d schemas ] && npm run codegen && npm run build || true"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "@typescript-eslint/eslint-plugin": "^8.18.0",
+    "@typescript-eslint/parser": "^8.18.0",
+    "eslint": "^9.39.3",
+    "json-schema-to-typescript": "^15.0.4",
+    "tsup": "^8.5.0",
+    "typescript": "^5.7.0",
+    "typescript-eslint": "^8.18.0",
+    "vitest": "^4.0.18"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  }
+}

package/schemas/vehicle-state.schema.json

@@ -0,0 +1,343 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://myrobotaxi.com/schemas/vehicle-state.schema.json",
+  "title": "VehicleState",
+  "description": "Canonical vehicle state as consumed by MyRoboTaxi SDKs. Defines every field name, type, unit, nullability, atomic group membership, and data classification. Both the WebSocket vehicle_update messages and the REST snapshot endpoint return subsets of this schema.",
+  "type": "object",
+  "required": [
+    "vehicleId",
+    "name",
+    "model",
+    "year",
+    "color",
+    "status",
+    "chargeLevel",
+    "estimatedRange",
+    "speed",
+    "heading",
+    "latitude",
+    "longitude",
+    "locationName",
+    "locationAddress",
+    "interiorTemp",
+    "exteriorTemp",
+    "odometerMiles",
+    "fsdMilesSinceReset",
+    "lastUpdated"
+  ],
+  "properties": {
+    "vehicleId": {
+      "type": "string",
+      "description": "Opaque database identifier (cuid). NOT the VIN. All SDK API calls use this ID (FR-4.2).",
+      "x-classification": "P0",
+      "examples": ["clxyz1234567890abcdef"]
+    },
+    "name": {
+      "type": "string",
+      "description": "User-assigned vehicle name from DB Vehicle.name (managed by the Next.js settings UI). NOT the Tesla-streamed VehicleName proto field — see vehicle-state-schema.md §1.2 for the disambiguation rationale (MYR-30).",
+      "x-classification": "P0",
+      "examples": ["Optimus"]
+    },
+    "model": {
+      "type": "string",
+      "description": "Vehicle model (e.g., 'Model 3', 'Model Y'). Sourced from DB Vehicle.model (Prisma NOT NULL). Loaded by the Go Vehicle struct and populated on snapshot as of MYR-24 (2026-04-23).",
+      "x-classification": "P0",
+      "examples": ["Model 3"]
+    },
+    "year": {
+      "type": "integer",
+      "description": "Model year. Sourced from DB Vehicle.year (Prisma NOT NULL). Loaded by the Go Vehicle struct and populated on snapshot as of MYR-24 (2026-04-23).",
+      "x-classification": "P0",
+      "examples": [2024]
+    },
+    "color": {
+      "type": "string",
+      "description": "Vehicle exterior color. Sourced from DB Vehicle.color (Prisma NOT NULL). Loaded by the Go Vehicle struct and populated on snapshot as of MYR-24 (2026-04-23).",
+      "x-classification": "P0",
+      "examples": ["Midnight Silver Metallic"]
+    },
+    "status": {
+      "type": "string",
+      "enum": ["driving", "parked", "charging", "offline", "in_service"],
+      "description": "Derived vehicle status. Part of the gear atomic group -- updated atomically with gearPosition. When gearPosition is D or R, status is 'driving'; otherwise 'parked'. The 'charging', 'offline', and 'in_service' states are set by server-side logic.",
+      "x-classification": "P0",
+      "x-atomic-group": "gear"
+    },
+    "speed": {
+      "type": "integer",
+      "description": "Current vehicle speed. Rounded to nearest integer from Tesla's float emission.",
+      "x-unit": "mph",
+      "x-classification": "P0",
+      "minimum": 0
+    },
+    "heading": {
+      "type": "integer",
+      "description": "Compass heading. 0 = North, 90 = East, 180 = South, 270 = West.",
+      "x-unit": "degrees",
+      "x-classification": "P0",
+      "minimum": 0,
+      "maximum": 359,
+      "x-atomic-group": "gps"
+    },
+    "latitude": {
+      "type": "number",
+      "description": "Current GPS latitude. Encrypted at rest (AES-256-GCM). Non-nullable: on initial connect before the first GPS fix, latitude/longitude default to 0. Per the '0,0 = no fix' convention (§2.3), SDK consumers MUST treat latitude == 0 && longitude == 0 as 'no position available' rather than a valid location in the Gulf of Guinea.",
+      "x-unit": "degrees",
+      "x-classification": "P1",
+      "x-encrypted": true,
+      "minimum": -90,
+      "maximum": 90,
+      "x-atomic-group": "gps"
+    },
+    "longitude": {
+      "type": "number",
+      "description": "Current GPS longitude. Encrypted at rest (AES-256-GCM). Non-nullable: on initial connect before the first GPS fix, latitude/longitude default to 0. Per the '0,0 = no fix' convention (§2.3), SDK consumers MUST treat latitude == 0 && longitude == 0 as 'no position available' rather than a valid location in the Gulf of Guinea.",
+      "x-unit": "degrees",
+      "x-classification": "P1",
+      "x-encrypted": true,
+      "minimum": -180,
+      "maximum": 180,
+      "x-atomic-group": "gps"
+    },
+    "locationName": {
+      "type": "string",
+      "description": "Reverse-geocoded place name for current location (e.g., 'Home', 'Whole Foods Market'). Derived from GPS coordinates server-side. Non-nullable per DB Vehicle.locationName (NOT NULL DEFAULT ''); an empty string means no geocode is yet available. Loaded by the Go Vehicle struct and populated on snapshot as of MYR-24 (2026-04-23).",
+      "x-classification": "P1"
+    },
+    "locationAddress": {
+      "type": "string",
+      "description": "Reverse-geocoded street address for current location. Derived from GPS coordinates server-side. Non-nullable per DB Vehicle.locationAddress (NOT NULL DEFAULT ''); an empty string means no geocode is yet available. Loaded by the Go Vehicle struct and populated on snapshot as of MYR-24 (2026-04-23).",
+      "x-classification": "P1"
+    },
+    "gearPosition": {
+      "type": ["string", "null"],
+      "enum": ["P", "D", "R", "N", null],
+      "description": "Transmission gear position. Null when vehicle is asleep or gear has not yet been reported. When gearPosition changes, status is re-derived and both are delivered together.",
+      "x-classification": "P0",
+      "x-atomic-group": "gear"
+    },
+    "chargeLevel": {
+      "type": "integer",
+      "description": "Battery state of charge. Rounded to nearest integer from Tesla's float emission. Maps from Tesla SOC or BatteryLevel fields.",
+      "x-unit": "percent",
+      "x-classification": "P0",
+      "minimum": 0,
+      "maximum": 100,
+      "x-atomic-group": "charge"
+    },
+    "chargeState": {
+      "type": ["string", "null"],
+      "description": "Charge state enum sourced from Tesla proto field 179 (DetailedChargeState) as of MYR-42 (2026-04-23). Added as a v1 charge atomic group member by MYR-11; live WS wiring completed by MYR-40 on 2026-04-22 using proto 2 (ChargeState); re-sourced to proto 179 by MYR-42 after empirical capture showed Tesla firmware ≥ 2024.44.25 accepts proto 2 in fleet_telemetry_config but never actually emits it. Proto 179 fires on the same transitions with identical enum string values (see websocket-protocol.md §4.1.4 and §10 DV-03 + DV-19). DB persistence on the Prisma-owned Vehicle table landed in MYR-41 on 2026-04-25 (Vehicle.chargeState String? + Go writer pipeline applier + store SELECT/UPDATE wiring). Nullable in steady state — a vehicle that has never charged surfaces null on both wire and REST /snapshot. SDK consumers MUST tolerate null and render a neutral placeholder (not a spinner). Nullability is expressed via the union `type: [\"string\", \"null\"]`; the `enum` list includes `null` explicitly alongside the string values for maximum validator compatibility (some Go and Python JSON Schema libraries require `null` in the enum to accept null values even when `type` includes `null`).",
+      "enum": ["Unknown", "Disconnected", "NoPower", "Starting", "Charging", "Complete", "Stopped", null],
+      "x-classification": "P0",
+      "x-atomic-group": "charge",
+      "x-tesla-proto-field": 179
+    },
+    "estimatedRange": {
+      "type": "integer",
+      "description": "Estimated remaining driving range based on current charge. Rounded to nearest integer.",
+      "x-unit": "miles",
+      "x-classification": "P0",
+      "minimum": 0,
+      "x-atomic-group": "charge"
+    },
+    "timeToFull": {
+      "type": ["number", "null"],
+      "description": "Estimated time to full charge at the current charging rate. Added as a v1 charge atomic group member by MYR-11; live WS wiring completed by MYR-40 on 2026-04-22 (see websocket-protocol.md §4.1.4 and §10 DV-04). Tesla proto field 43 (TimeToFullCharge, double). Unit is HOURS (decimal, fractional values supported — e.g. 1.5 for 90 minutes) per the tesla-fleet-telemetry-sme skill and the legacy Tesla REST API; empirically verified as 1.066666841506958 hours during a home charging session on 2026-04-22 (DV-17 resolved — see MYR-25 comment and TestDecoder_DecodePayload_TimeToFull). DB persistence on the Prisma-owned Vehicle table landed in MYR-41 on 2026-04-25 (Vehicle.timeToFull Float? + Go writer pipeline applier + store SELECT/UPDATE wiring). Nullable in steady state — null means no active charging session or no charge frame has arrived yet. SDK consumers MUST tolerate null and render a neutral placeholder (not a spinner). 0 (or null when disconnected) means no active charging session.",
+      "x-unit": "hours",
+      "x-classification": "P0",
+      "minimum": 0,
+      "x-atomic-group": "charge",
+      "x-tesla-proto-field": 43
+    },
+    "interiorTemp": {
+      "type": "integer",
+      "description": "Cabin interior temperature. Rounded to nearest integer.",
+      "x-unit": "fahrenheit",
+      "x-classification": "P0"
+    },
+    "exteriorTemp": {
+      "type": "integer",
+      "description": "Ambient exterior temperature. Rounded to nearest integer.",
+      "x-unit": "fahrenheit",
+      "x-classification": "P0"
+    },
+    "odometerMiles": {
+      "type": "integer",
+      "description": "Total odometer reading. Rounded to nearest integer.",
+      "x-unit": "miles",
+      "x-classification": "P0",
+      "minimum": 0
+    },
+    "fsdMilesSinceReset": {
+      "type": "number",
+      "description": "Miles driven using Full Self-Driving since last reset. The counter resets on OTA updates and factory resets, NOT daily. Maps from Tesla SelfDrivingMilesSinceReset. Non-nullable per DB Vehicle.fsdMilesSinceReset (NOT NULL DEFAULT 0) — DB column renamed from the legacy fsdMilesToday by MYR-24 (2026-04-23, cross-repo Prisma migration). Loaded by the Go Vehicle struct and populated on snapshot.",
+      "x-unit": "miles",
+      "x-classification": "P0",
+      "minimum": 0
+    },
+    "destinationName": {
+      "type": ["string", "null"],
+      "description": "Name of the active navigation destination. Null when no navigation is active. When navigation is cancelled, this field and all other navigation group fields are atomically cleared to null.",
+      "x-classification": "P1",
+      "x-atomic-group": "navigation",
+      "examples": ["Whole Foods Market"]
+    },
+    "destinationAddress": {
+      "type": ["string", "null"],
+      "description": "Street address of the active navigation destination. Null when no navigation is active. Sourced from DB Vehicle.destinationAddress (Prisma String?, nullable). Loaded by the Go Vehicle struct and populated on snapshot as of MYR-24 (2026-04-23).",
+      "x-classification": "P1",
+      "x-atomic-group": "navigation"
+    },
+    "destinationLatitude": {
+      "type": ["number", "null"],
+      "description": "Latitude of the navigation destination. Encrypted at rest (AES-256-GCM). Null when no navigation is active.",
+      "x-unit": "degrees",
+      "x-classification": "P1",
+      "x-encrypted": true,
+      "minimum": -90,
+      "maximum": 90,
+      "x-atomic-group": "navigation"
+    },
+    "destinationLongitude": {
+      "type": ["number", "null"],
+      "description": "Longitude of the navigation destination. Encrypted at rest (AES-256-GCM). Null when no navigation is active.",
+      "x-unit": "degrees",
+      "x-classification": "P1",
+      "x-encrypted": true,
+      "minimum": -180,
+      "maximum": 180,
+      "x-atomic-group": "navigation"
+    },
+    "originLatitude": {
+      "type": ["number", "null"],
+      "description": "Latitude of the navigation trip origin. Encrypted at rest (AES-256-GCM). Null when no navigation is active.",
+      "x-unit": "degrees",
+      "x-classification": "P1",
+      "x-encrypted": true,
+      "minimum": -90,
+      "maximum": 90,
+      "x-atomic-group": "navigation"
+    },
+    "originLongitude": {
+      "type": ["number", "null"],
+      "description": "Longitude of the navigation trip origin. Encrypted at rest (AES-256-GCM). Null when no navigation is active.",
+      "x-unit": "degrees",
+      "x-classification": "P1",
+      "x-encrypted": true,
+      "minimum": -180,
+      "maximum": 180,
+      "x-atomic-group": "navigation"
+    },
+    "etaMinutes": {
+      "type": ["integer", "null"],
+      "description": "Estimated time of arrival in minutes remaining. Null when no navigation is active. Rounded to nearest integer.",
+      "x-unit": "minutes",
+      "x-classification": "P0",
+      "minimum": 0,
+      "x-atomic-group": "navigation"
+    },
+    "tripDistanceRemaining": {
+      "type": ["number", "null"],
+      "description": "Remaining distance to navigation destination. Null when no navigation is active.",
+      "x-unit": "miles",
+      "x-classification": "P0",
+      "minimum": 0,
+      "x-atomic-group": "navigation"
+    },
+    "navRouteCoordinates": {
+      "type": ["array", "null"],
+      "description": "Active navigation route as an array of [longitude, latitude] coordinate pairs (GeoJSON/Mapbox order). Decoded from Tesla's RouteLine (Base64-encoded protobuf wrapping a Google Encoded Polyline at 1e6 precision). Encrypted at rest (AES-256-GCM). Null when no navigation is active.",
+      "x-classification": "P1",
+      "x-encrypted": true,
+      "x-atomic-group": "navigation",
+      "items": {
+        "type": "array",
+        "items": {
+          "type": "number"
+        },
+        "minItems": 2,
+        "maxItems": 2,
+        "description": "A coordinate pair: [longitude, latitude]."
+      }
+    },
+    "lastUpdated": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO 8601 timestamp of the most recent telemetry update applied to this vehicle state.",
+      "x-classification": "P0"
+    }
+  },
+  "x-atomic-groups": {
+    "navigation": {
+      "description": "Navigation state delivered as a single atomic unit. When any navigation field changes, the server accumulates all sibling nav fields within a 500ms debounce window (NFR-3.2) and delivers them together. When navigation is cancelled, ALL fields in this group are atomically cleared to null (FR-2.3).",
+      "fields": [
+        "destinationName",
+        "destinationAddress",
+        "destinationLatitude",
+        "destinationLongitude",
+        "originLatitude",
+        "originLongitude",
+        "etaMinutes",
+        "tripDistanceRemaining",
+        "navRouteCoordinates"
+      ],
+      "consistency-predicates": [
+        "If destinationLatitude is non-null, then destinationLongitude MUST also be non-null, and vice versa.",
+        "If originLatitude is non-null, then originLongitude MUST also be non-null, and vice versa.",
+        "If destinationName is non-null, then destinationLatitude, destinationLongitude, and navRouteCoordinates MUST also be non-null (NFR-3.3).",
+        "If any navigation field is null, ALL navigation fields MUST be null (atomic clear on nav cancel, FR-2.3).",
+        "etaMinutes and tripDistanceRemaining MAY be null independently during the 500ms accumulation window, but the DB snapshot MUST have all-or-nothing consistency."
+      ],
+      "nullability": "All fields nullable. Null = no active navigation."
+    },
+    "charge": {
+      "description": "Battery and charge state delivered together. When any charge field changes within the same Tesla 500ms vehicle-side bucket, sibling fields are included in the same vehicle_update message. v1 expands this group to four fields per MYR-11; live WS wiring for chargeState and timeToFull completed by MYR-40 on 2026-04-22; DB persistence for both completed by MYR-41 on 2026-04-25 (Prisma columns + Go writer applier + SELECT/UPDATE wiring).",
+      "fields": [
+        "chargeLevel",
+        "chargeState",
+        "estimatedRange",
+        "timeToFull"
+      ],
+      "consistency-predicates": [
+        "chargeLevel and estimatedRange MUST both be present in the DB snapshot (NFR-3.5). They are non-nullable with default 0.",
+        "chargeState and timeToFull are nullable in steady state — null surfaces when the vehicle has never charged or when no charge frame has arrived yet. Consumers MUST tolerate null on both wire and REST /snapshot responses.",
+        "chargeLevel: 0 is context-dependent. With status == 'offline', the UI SHOULD interpret chargeLevel: 0 as 'unknown' (no telemetry received yet, DB default). With status == 'driving' or 'parked' (i.e., the vehicle is online), chargeLevel: 0 SHOULD be interpreted as 'critical' or 'empty battery'. See §2.2 of vehicle-state-schema.md."
+      ],
+      "nullability": "chargeLevel and estimatedRange are non-nullable (default 0 on initial vehicle creation). chargeState and timeToFull are nullable on both wire and REST /snapshot — the Prisma-owned Vehicle columns are String?/Float? (post-MYR-41) and steady-state null is the expected shape for vehicles that have never charged."
+    },
+    "gps": {
+      "description": "GPS position and orientation delivered together. On initial connect before the first GPS fix, latitude and longitude may be 0 (DB default).",
+      "fields": [
+        "latitude",
+        "longitude",
+        "heading"
+      ],
+      "consistency-predicates": [
+        "latitude and longitude MUST always be present together (NFR-3.3).",
+        "heading MUST be present whenever latitude/longitude are present.",
+        "Values of 0,0 for latitude/longitude represent the DB default (no GPS fix yet), not a valid location."
+      ],
+      "nullability": "Non-nullable in DB (default 0). SDK consumers SHOULD treat 0,0 as 'no fix'."
+    },
+    "gear": {
+      "description": "Gear position and derived vehicle status delivered together. When gearPosition changes, the server derives status (driving/parked) and includes both fields in the same message.",
+      "fields": [
+        "gearPosition",
+        "status"
+      ],
+      "consistency-predicates": [
+        "When gearPosition is 'D' or 'R', status MUST be 'driving'.",
+        "When gearPosition is 'P' or 'N', status MUST be 'parked' (unless overridden by charging/offline/in_service logic).",
+        "status is always present; gearPosition is nullable (null = vehicle asleep or gear not yet reported)."
+      ],
+      "nullability": "gearPosition is nullable. status is non-nullable (default 'offline')."
+    }
+  },
+  "dependentRequired": {
+    "destinationLatitude": ["destinationLongitude"],
+    "destinationLongitude": ["destinationLatitude"],
+    "originLatitude": ["originLongitude"],
+    "originLongitude": ["originLatitude"]
+  }
+}

package/schemas/ws-envelope.schema.json

@@ -0,0 +1,65 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://myrobotaxi.com/schemas/ws-envelope.schema.json",
+  "title": "WebSocketEnvelope",
+  "description": "Top-level envelope for every WebSocket frame exchanged between the telemetry server and SDK clients. Both directions (server->client and client->server) use this envelope. The `type` discriminator selects the payload schema; `seq` and `ts` are server-authoritative fields populated only on server->client frames to support snapshot resume per NFR-3.11.",
+  "type": "object",
+  "required": ["type"],
+  "additionalProperties": false,
+  "properties": {
+    "type": {
+      "type": "string",
+      "description": "Discriminator naming the message type. Server->client values: 'auth_ok' (v1-required positive auth acknowledgement, triggers state-machine C-3 — see websocket-protocol.md §2.3), 'vehicle_update', 'drive_started', 'drive_ended', 'connectivity', 'heartbeat', 'error'. Client->server values: 'auth' (only message currently accepted; 'subscribe', 'unsubscribe', 'ping' are reserved for follow-up — see websocket-protocol.md §10 DV-07).",
+      "enum": [
+        "auth",
+        "auth_ok",
+        "vehicle_update",
+        "drive_started",
+        "drive_ended",
+        "connectivity",
+        "heartbeat",
+        "error",
+        "subscribe",
+        "unsubscribe",
+        "ping",
+        "pong"
+      ],
+      "x-classification": "P0"
+    },
+    "payload": {
+      "description": "Type-specific payload object. Schema is selected by the `type` discriminator. Omitted on bare control frames such as 'heartbeat'. See websocket-protocol.md §4 (server->client) and §5 (client->server) for the catalog.",
+      "x-classification": "P0"
+    },
+    "seq": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "PLANNED — NOT emitted by the server today. Monotonic per-connection sequence number assigned by the server, starting at 0 on each successful authenticated session. Used by clients on reconnect to request snapshot-resume from sequence N (NFR-3.11) via the planned `subscribe.sinceSeq` field. Until the server is extended to emit `seq`, clients MUST tolerate its absence and treat every frame as gap-free. Tracked as divergence DV-02 in websocket-protocol.md §10.",
+      "x-classification": "P0"
+    },
+    "ts": {
+      "type": "string",
+      "format": "date-time",
+      "description": "PLANNED — NOT emitted by the server today. Server-authoritative ISO 8601 UTC timestamp for the envelope itself, distinct from any payload-internal `timestamp` field. Clients MUST tolerate its absence today; the per-payload `timestamp` field (e.g., `vehicle_update.timestamp`, `drive_started.timestamp`) carries the same information in v1.0. Tracked as divergence DV-02 in websocket-protocol.md §10.",
+      "x-classification": "P0"
+    }
+  },
+  "$defs": {
+    "MessageType": {
+      "type": "string",
+      "enum": [
+        "auth",
+        "auth_ok",
+        "vehicle_update",
+        "drive_started",
+        "drive_ended",
+        "connectivity",
+        "heartbeat",
+        "error",
+        "subscribe",
+        "unsubscribe",
+        "ping",
+        "pong"
+      ]
+    }
+  }
+}