@mentra/cloud-protocol 0.1.0-beta.0

package/README.md

@@ -0,0 +1,45 @@
+# @mentra/cloud-protocol
+
+The MentraOS phone ↔ cloud wire protocol: message schemas, envelopes, and
+error types shared by everything that speaks to the MentraOS cloud. Pure
+TypeScript + [zod](https://github.com/colinhacks/zod) — no server or native
+dependencies.
+
+This is a **leaf package**: [`@mentra/cloud-client`](https://www.npmjs.com/package/@mentra/cloud-client)
+and [`@mentra/engine`](https://www.npmjs.com/package/@mentra/engine) depend on
+it, and the MentraOS cloud runtime consumes the same schemas server-side, so
+both ends of the wire validate against one definition.
+
+## Install
+
+You normally get this package automatically as a dependency of
+`@mentra/cloud-client` or a peer of `@mentra/engine`. For direct use:
+
+```sh
+npm install @mentra/cloud-protocol@dev
+```
+
+> Currently published on the `dev` dist-tag (prerelease channel).
+
+## Usage
+
+```ts
+import {envelopeSchema, PROTOCOL_MAJOR, type Envelope} from "@mentra/cloud-protocol";
+
+const message: Envelope = envelopeSchema.parse(JSON.parse(raw));
+
+// or per-module subpaths:
+import {normalizePhotoSizeTier} from "@mentra/cloud-protocol/camera";
+```
+
+Modules: `envelope`, `messages`, `handshake`, `control`, `camera`, `audio`,
+`maps`, `errors` — each importable as `@mentra/cloud-protocol/<module>`.
+
+The package ships TypeScript source (`main: ./src/index.ts`) and targets
+consumers that compile TS themselves (Metro / bundlers / tsc); it is not
+precompiled for plain Node `require`.
+
+## Part of MentraOS
+
+Source lives in the [MentraOS monorepo](https://github.com/Mentra-Community/MentraOS)
+under `cloud-v2/packages/protocol`. Issues and contributions welcome there.

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@mentra/cloud-protocol",
+  "version": "0.1.0-beta.0",
+  "type": "module",
+  "main": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./*": "./src/*.ts"
+  },
+  "files": [
+    "src",
+    "!src/**/*.test.ts"
+  ],
+  "scripts": {
+    "test": "bun test"
+  },
+  "dependencies": {
+    "zod": "^3.24.1"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Mentra-Community/MentraOS.git",
+    "directory": "cloud-v2/packages/protocol"
+  },
+  "description": "MentraOS phone-cloud wire protocol — message schemas, envelopes and error types (zod)",
+  "keywords": [
+    "mentra",
+    "mentraos",
+    "protocol",
+    "schemas",
+    "zod"
+  ],
+  "homepage": "https://github.com/Mentra-Community/MentraOS/tree/dev/cloud-v2/packages/protocol#readme",
+  "bugs": {
+    "url": "https://github.com/Mentra-Community/MentraOS/issues"
+  }
+}

package/src/audio.ts

@@ -0,0 +1,121 @@
+/**
+ * @fileoverview Canonical audio wire types for the Mentra Runtime protocol.
+ *
+ * zod schemas + inferred TS types for the audio service's subscription model
+ * and result types. These are the single source of truth; `src/audio.types.ts`
+ * re-exports the subscription types from here and adds `subscriptionKey()`.
+ *
+ * Mirrors docs/issues/002-cloud-runtime/audio/spec.md
+ * ("Subscription model" and "Result types"). Pure + isomorphic: no server
+ * imports, safe to bundle into the RN client.
+ */
+import { z } from "zod";
+
+// --- Subscription model -----------------------------------------------------
+
+export const languageSourceSchema = z.discriminatedUnion("mode", [
+  z.object({ mode: z.literal("specific"), code: z.string() }),
+  z.object({ mode: z.literal("auto"), hints: z.array(z.string()).optional() }),
+]);
+export type LanguageSource = z.infer<typeof languageSourceSchema>;
+
+export const transcriptionSubscriptionSchema = z.object({
+  kind: z.literal("transcription"),
+  language: languageSourceSchema,
+});
+export type TranscriptionSubscription = z.infer<
+  typeof transcriptionSubscriptionSchema
+>;
+
+export const translationSubscriptionSchema = z.object({
+  kind: z.literal("translation"),
+  source: languageSourceSchema,
+  target: z.string(),
+});
+export type TranslationSubscription = z.infer<
+  typeof translationSubscriptionSchema
+>;
+
+export const audioSubscriptionSchema = z.discriminatedUnion("kind", [
+  transcriptionSubscriptionSchema,
+  translationSubscriptionSchema,
+]);
+export type AudioSubscription = z.infer<typeof audioSubscriptionSchema>;
+
+// --- UDP liveness -----------------------------------------------------------
+
+export const UDP_LIVENESS_PROBE_PREFIX = "mentra:udp-probe:";
+
+export const udpLivenessAckPayloadSchema = z.object({
+  sessionId: z.string(),
+  sessionTag: z.number().int(),
+  probeId: z.string(),
+  receivedAt: z.number().int(),
+});
+export type UdpLivenessAckPayload = z.infer<typeof udpLivenessAckPayloadSchema>;
+
+// --- Result types -----------------------------------------------------------
+
+export const transcriptionTokenSchema = z.object({
+  text: z.string(),
+  startMs: z.number(),
+  endMs: z.number(),
+  confidence: z.number(),
+  isFinal: z.boolean(),
+  speaker: z.string().optional(),
+  // per-token; mid-sentence language switches are possible
+  detectedLanguage: z.string().optional(),
+});
+export type TranscriptionToken = z.infer<typeof transcriptionTokenSchema>;
+
+export const transcriptionDataSchema = z.object({
+  userId: z.string(),
+  subscription: transcriptionSubscriptionSchema,
+
+  // Aggregated for simple consumers
+  text: z.string(),
+  isFinal: z.boolean(),
+  utteranceId: z.string().optional(),
+  speakerId: z.string().optional(),
+  startMs: z.number(),
+  endMs: z.number(),
+  durationMs: z.number().optional(),
+  confidence: z.number().optional(),
+
+  // Language resolution
+  resolvedLanguage: z.string(),
+  languageDetected: z.boolean(),
+
+  // Per-token detail for consumers that need it
+  tokens: z.array(transcriptionTokenSchema),
+
+  provider: z.string(),
+  timestamp: z.number(),
+});
+export type TranscriptionData = z.infer<typeof transcriptionDataSchema>;
+
+export const translationDataSchema = z.object({
+  userId: z.string(),
+  subscription: translationSubscriptionSchema,
+
+  text: z.string(), // translated
+  originalText: z.string().optional(), // source-language text
+  isFinal: z.boolean(),
+  utteranceId: z.string().optional(),
+  speakerId: z.string().optional(),
+  startMs: z.number(),
+  endMs: z.number(),
+  durationMs: z.number().optional(),
+  confidence: z.number().optional(),
+
+  source: z.object({
+    language: z.string(), // resolved (specified or detected)
+    detected: z.boolean(),
+    confidence: z.number().optional(),
+  }),
+  target: z.object({ language: z.string() }),
+
+  provider: z.string(),
+  timestamp: z.number(),
+});
+export type TranslationData = z.infer<typeof translationDataSchema>;

package/src/camera.ts

@@ -0,0 +1,157 @@
+/**
+ * @fileoverview Canonical camera wire types: managed photo + managed stream.
+ *
+ * zod schemas + inferred TS types for the camera service. The request/result
+ * shapes ride REST; `photo.ready` / `photo.error` are WebSocket push events
+ * registered into the message union (messages.ts). Pure + isomorphic: no server
+ * imports, safe to bundle into the client.
+ *
+ * Mirrors docs/issues/002-cloud-runtime/camera/spec.md.
+ */
+import { z } from "zod";
+
+// --- Managed photo ----------------------------------------------------------
+
+/** Device-canonical photo size tier (matches miniapp SDK and ASG). */
+export const photoSizeCanonicalSchema = z.enum(["low", "medium", "high", "max"]);
+export type PhotoSizeTier = z.infer<typeof photoSizeCanonicalSchema>;
+
+/** Accepted on the wire: canonical names plus legacy cloud aliases. */
+const photoSizeInputSchema = z.enum([
+  "low",
+  "medium",
+  "high",
+  "max",
+  "small",
+  "large",
+  "full",
+]);
+
+/**
+ * Normalize a photo size string to the device-canonical tier.
+ * Legacy aliases: small→low, large→high, full→max.
+ */
+export function normalizePhotoSizeTier(value: string): PhotoSizeTier {
+  switch (value) {
+    case "small":
+      return "low";
+    case "large":
+      return "high";
+    case "full":
+      return "max";
+    case "low":
+    case "medium":
+    case "high":
+    case "max":
+      return value;
+    default:
+      throw new Error(`invalid photo size: ${value}`);
+  }
+}
+
+const photoCompressInputSchema = z.enum(["none", "low", "medium", "high", "heavy"]);
+
+/** Normalize compression aliases to the cloud wire enum. */
+export function normalizePhotoCompress(
+  value: string,
+): "none" | "medium" | "heavy" {
+  switch (value) {
+    case "low":
+    case "medium":
+      return "medium";
+    case "high":
+    case "heavy":
+      return "heavy";
+    case "none":
+      return "none";
+    default:
+      throw new Error(`invalid photo compress: ${value}`);
+  }
+}
+
+export const photoOptionsSchema = z.object({
+  size: photoSizeInputSchema
+    .optional()
+    .transform((value) => (value === undefined ? undefined : normalizePhotoSizeTier(value))),
+  compress: photoCompressInputSchema
+    .optional()
+    .transform((value) => (value === undefined ? undefined : normalizePhotoCompress(value))),
+  saveToGallery: z.boolean().optional(),
+  sound: z.boolean().optional(),
+});
+export type PhotoOptions = z.infer<typeof photoOptionsSchema>;
+
+/**
+ * The REST response to a photo request. The capture happens out of band (the
+ * glasses upload to `uploadUrl`); `readUrl` is the presigned URL the finished
+ * photo will be readable at, returned up front so the client has it before the
+ * `photo.ready` push confirms the upload landed.
+ */
+export const photoRequestResultSchema = z.object({
+  requestId: z.string(),
+  uploadUrl: z.string(),
+  readUrl: z.string(),
+});
+export type PhotoRequestResult = z.infer<typeof photoRequestResultSchema>;
+
+/** `photo.ready` push payload: the capture+upload completed. */
+export const photoReadyPayloadSchema = z.object({
+  requestId: z.string(),
+  readUrl: z.string(),
+});
+export type PhotoReady = z.infer<typeof photoReadyPayloadSchema>;
+
+/** `photo.error` push payload: the capture+upload failed. */
+export const photoErrorPayloadSchema = z.object({
+  requestId: z.string(),
+  reason: z.string(),
+});
+export type PhotoError = z.infer<typeof photoErrorPayloadSchema>;
+
+// --- Managed stream ---------------------------------------------------------
+
+/** A restream destination: re-publish the ingest to an external RTMP target. */
+export const restreamDestinationSchema = z.union([
+  z.string(),
+  z.object({ url: z.string(), name: z.string().optional() }),
+]);
+export type RestreamDestination = z.infer<typeof restreamDestinationSchema>;
+
+export const streamOptionsSchema = z.object({
+  /** Region hint so the cloud provisions a nearby ingest endpoint. */
+  region: z.string().optional(),
+  /** External RTMP targets the provider re-publishes the ingest to. */
+  restreamDestinations: z.array(restreamDestinationSchema).optional(),
+});
+export type StreamOptions = z.infer<typeof streamOptionsSchema>;
+
+/**
+ * A provisioned stream. `ingest` is where the device pushes frames; `playback`
+ * is where viewers watch. Both are left as open records because the provider
+ * (Cloudflare Stream by default) is swappable per region and its exact field
+ * shapes are not finalized. The Cloudflare provider populates ingest
+ * `{protocol, url, streamKey, rtmpUrl, srtUrl?, webrtcPublishUrl?}` (the last
+ * three ready-to-publish with credentials embedded) and playback
+ * `{hls, dash, webrtc?}`.
+ */
+export const managedStreamSchema = z.object({
+  streamId: z.string(),
+  ingest: z.record(z.unknown()),
+  playback: z.record(z.unknown()),
+});
+export type ManagedStream = z.infer<typeof managedStreamSchema>;
+
+/**
+ * `GET /api/camera/stream/:id` result: the provider's view of the ingest.
+ * `isConnected` is the portable signal (is the device's push arriving?);
+ * the rest is provider detail for debugging.
+ */
+export const streamStatusResultSchema = z.object({
+  streamId: z.string(),
+  isConnected: z.boolean(),
+  state: z.string().nullable(),
+  connectedAt: z.string().optional(),
+  lastSeenAt: z.string().optional(),
+  reason: z.string().optional(),
+});
+export type StreamStatusResult = z.infer<typeof streamStatusResultSchema>;

package/src/control.ts

@@ -0,0 +1,13 @@
+/**
+ * @fileoverview Control payloads: control.ping and control.pong.
+ *
+ * Mirrors docs/issues/002-cloud-runtime/protocol.md ("Control"). Liveness and
+ * RTT, separate from the WebSocket ping frame. Pure + isomorphic.
+ */
+import { z } from "zod";
+
+export const controlPingPayloadSchema = z.object({}).strict();
+export type ControlPing = z.infer<typeof controlPingPayloadSchema>;
+
+export const controlPongPayloadSchema = z.object({}).strict();
+export type ControlPong = z.infer<typeof controlPongPayloadSchema>;

package/src/envelope.ts

@@ -0,0 +1,48 @@
+/**
+ * @fileoverview The transport envelope shared by every WebSocket message.
+ *
+ * Mirrors docs/issues/002-cloud-runtime/protocol.md ("Envelope"). Pure +
+ * isomorphic: no server imports.
+ */
+import { z } from "zod";
+
+/** Protocol major. A mismatched major is rejected at the handshake. */
+export const PROTOCOL_MAJOR = 2 as const;
+
+/**
+ * Wraps a payload schema in the protocol envelope with a literal `type`, so a
+ * set of message schemas can be combined into a discriminated union on `type`.
+ *
+ *   const connectionAck = envelope("connection.ack", connectionAckPayloadSchema)
+ */
+export function envelope<Type extends string, Payload extends z.ZodTypeAny>(
+  type: Type,
+  payload: Payload,
+) {
+  return z.object({
+    v: z.literal(PROTOCOL_MAJOR),
+    type: z.literal(type),
+    // present only when a message needs request/ack correlation
+    id: z.string().optional(),
+    // epoch milliseconds (Unix time)
+    timestamp: z.number().int(),
+    payload,
+  });
+}
+
+/** The structural envelope, payload left open. Useful for a first-pass parse. */
+export const envelopeSchema = z.object({
+  v: z.literal(PROTOCOL_MAJOR),
+  type: z.string(),
+  id: z.string().optional(),
+  timestamp: z.number().int(),
+  payload: z.unknown(),
+});
+
+export interface Envelope<T = unknown> {
+  v: typeof PROTOCOL_MAJOR;
+  type: string;
+  id?: string;
+  timestamp: number;
+  payload: T;
+}

package/src/errors.ts

@@ -0,0 +1,27 @@
+/**
+ * @fileoverview The error payload and transport-level error codes.
+ *
+ * Mirrors docs/issues/002-cloud-runtime/protocol.md ("Errors"). Services may
+ * define additional codes for their own payloads (documented in the service
+ * doc). Pure + isomorphic.
+ */
+import { z } from "zod";
+
+/** Transport-level error codes shared by every runtime service. */
+export const PROTOCOL_ERROR_CODES = {
+  AUTH_FAILED: { fatal: true }, // token missing or invalid
+  AUTH_EXPIRED: { fatal: true }, // token expired; client should refresh and reopen
+  UNSUPPORTED_VERSION: { fatal: true }, // protocol major mismatch
+  BAD_REQUEST: { fatal: false }, // malformed payload for a known type
+  UNKNOWN_TYPE: { fatal: false }, // unrecognized `type`
+  INTERNAL: { fatal: false }, // server-side failure
+} as const;
+
+export type ProtocolErrorCode = keyof typeof PROTOCOL_ERROR_CODES;
+
+export const protocolErrorPayloadSchema = z.object({
+  code: z.string(), // a ProtocolErrorCode or a service-defined code
+  message: z.string(),
+  fatal: z.boolean(), // if true, the server closes the socket after sending
+});
+export type ProtocolError = z.infer<typeof protocolErrorPayloadSchema>;

package/src/handshake.ts

@@ -0,0 +1,60 @@
+/**
+ * @fileoverview Handshake payloads: connection.init and connection.ack.
+ *
+ * Mirrors docs/issues/002-cloud-runtime/protocol.md ("Auth and handshake").
+ * Service-scoped config rides in scoped blocks; audio is the only one today.
+ * Pure + isomorphic: no server imports.
+ */
+import { z } from "zod";
+import { audioSubscriptionSchema } from "./audio";
+
+// --- connection.init (client to cloud) --------------------------------------
+
+export const connectionInitPayloadSchema = z.object({
+  // omitted if provided via the ?token= fallback
+  token: z.string().optional(),
+  // semver of the client protocol build, e.g. "2.0.0"
+  protocolVersion: z.string(),
+  client: z
+    .object({
+      platform: z.enum(["ios", "android"]),
+      appVersion: z.string().optional(),
+    })
+    .optional(),
+  // Service-scoped config blocks. Audio is the only one today.
+  audio: z
+    .object({
+      codec: z.enum(["lc3", "pcm"]),
+      sampleRate: z.number().int(), // e.g. 16000
+      // LC3 bitrate / frame size in bytes. Only meaningful when codec is
+      // "lc3"; omitted PCM sessions keep treating payload bytes as PCM.
+      frameSizeBytes: z.union([z.literal(20), z.literal(40), z.literal(60)]).optional(),
+      // Optional initial subscription set, seeded atomically with the session
+      // so audio that starts before the first REST update is not transcribed
+      // with an empty set.
+      initialSubscriptions: z.array(audioSubscriptionSchema).optional(),
+    })
+    .optional(),
+});
+export type ConnectionInit = z.infer<typeof connectionInitPayloadSchema>;
+
+// --- connection.ack (cloud to client) ---------------------------------------
+
+export const connectionAckPayloadSchema = z.object({
+  sessionId: z.string(), // control-plane runtime session id
+  negotiatedVersion: z.string(),
+  // Audio session ingest coordinates (audio service, UDP path).
+  audio: z
+    .object({
+      sessionTag: z.number().int(), // u32 stamped into UDP audio frames
+      udp: z.object({ host: z.string(), port: z.number().int() }),
+      // Per-session key for encrypting UDP audio. Delivered here because the
+      // handshake is over the TLS WebSocket.
+      encryption: z.object({
+        algorithm: z.literal("xsalsa20-poly1305"), // NaCl secretbox
+        key: z.string(), // base64, 32 bytes
+      }),
+    })
+    .optional(),
+});
+export type ConnectionAck = z.infer<typeof connectionAckPayloadSchema>;

package/src/index.ts

@@ -0,0 +1,17 @@
+/**
+ * @fileoverview `@mentra/cloud-runtime/protocol` public entrypoint.
+ *
+ * Pure, isomorphic transport types + zod validators for the Mentra Runtime
+ * protocol. Zero server imports (no `node:*`, no service code) so the client
+ * can import the contract without pulling in server code.
+ *
+ * See docs/issues/002-cloud-runtime/protocol.md.
+ */
+export * from "./envelope";
+export * from "./handshake";
+export * from "./control";
+export * from "./errors";
+export * from "./messages";
+export * from "./audio";
+export * from "./camera";
+export * from "./maps";

package/src/maps.ts

@@ -0,0 +1,185 @@
+/**
+ * @fileoverview Canonical maps wire types: directions + reverse geocoding.
+ *
+ * zod schemas + inferred TS types for the maps service. Both flows are plain
+ * REST request/result (no WebSocket push, unlike camera), so nothing here is
+ * registered into the message union. Pure + isomorphic: no server imports, safe
+ * to bundle into the client.
+ *
+ * The vocabulary (TravelMode, ManeuverKind, avoidances, the route/step shapes)
+ * deliberately mirrors the mobile miniapp navigation SDK
+ * (mobile/modules/miniapp/src/modules/navigation.ts) so the contract is identical
+ * end-to-end: miniapp SDK <-> cloud-client <-> runtime. These are the PROVIDER-
+ * NEUTRAL types; each provider (Mapbox, Google) normalizes its own response into
+ * these inside its provider file, so this contract never leaks a vendor's shape.
+ *
+ * See docs/issues/002-cloud-runtime/maps/spec.md.
+ */
+import { z } from "zod";
+
+// --- Shared geometry --------------------------------------------------------
+
+export const latLngSchema = z.object({
+  lat: z.number(),
+  lng: z.number(),
+});
+export type LatLng = z.infer<typeof latLngSchema>;
+
+/** Travel profile. Providers map this to their own profile vocabulary. */
+export const travelModeSchema = z.enum(["walking", "driving", "cycling", "two_wheeler"]);
+export type TravelMode = z.infer<typeof travelModeSchema>;
+
+/** Routing preferences. All flags default to false. */
+export const routeAvoidancesSchema = z.object({
+  highways: z.boolean().optional(),
+  tolls: z.boolean().optional(),
+  ferries: z.boolean().optional(),
+});
+export type RouteAvoidances = z.infer<typeof routeAvoidancesSchema>;
+
+/**
+ * Neutral maneuver vocabulary. Each provider maps its own maneuver type/modifier
+ * vocabulary into exactly these values; consumers never see vendor strings.
+ */
+export const maneuverKindSchema = z.enum([
+  "STRAIGHT",
+  "CONTINUE",
+  "SLIGHT_LEFT",
+  "SLIGHT_RIGHT",
+  "TURN_LEFT",
+  "TURN_RIGHT",
+  "SHARP_LEFT",
+  "SHARP_RIGHT",
+  "U_TURN",
+  "NAME_CHANGE",
+  "DEPART",
+  "ARRIVE",
+  "CROSS_STREET",
+]);
+export type ManeuverKind = z.infer<typeof maneuverKindSchema>;
+
+// --- Directions -------------------------------------------------------------
+
+export const directionsRequestSchema = z.object({
+  origin: latLngSchema,
+  /** Ordered stops; last is the final destination. Must have >= 1 entry. */
+  stops: z.array(latLngSchema).min(1),
+  /** Defaults to "driving" when omitted. */
+  mode: travelModeSchema.optional(),
+  avoid: routeAvoidancesSchema.optional(),
+  /**
+   * Total number of routes to return — the primary plus any alternates, provider
+   * permitting. 1 (the default) means the primary route only, no alternates; a
+   * value > 1 asks the provider for alternates. (Mirrors the prior on-device
+   * behavior: Mapbox `alternatives` is requested only when this exceeds 1.)
+   */
+  alternatives: z.number().int().positive().optional(),
+});
+export type DirectionsRequest = z.infer<typeof directionsRequestSchema>;
+
+/** One step of a computed route. The maneuver ENDS the segment. */
+export const routeStepSchema = z.object({
+  lat: z.number(),
+  lng: z.number(),
+  endLat: z.number(),
+  endLng: z.number(),
+  distanceMeters: z.number(),
+  maneuver: maneuverKindSchema.optional(),
+  /** Full instruction from the provider (e.g. "Turn left onto Fell St"). */
+  instruction: z.string().optional(),
+  /** Resolved road name. Prefer this over parsing `instruction`. */
+  road: z.string().nullable().optional(),
+});
+export type RouteStep = z.infer<typeof routeStepSchema>;
+
+export const routeSchema = z.object({
+  points: z.array(latLngSchema),
+  totalDistanceMeters: z.number(),
+  totalDurationSeconds: z.number(),
+  summary: z.string().optional(),
+  steps: z.array(routeStepSchema).optional(),
+});
+export type Route = z.infer<typeof routeSchema>;
+
+/** The REST response for `POST /api/maps/directions`. Primary route first. */
+export const directionsResultSchema = z.object({
+  routes: z.array(routeSchema),
+});
+export type DirectionsResult = z.infer<typeof directionsResultSchema>;
+
+// --- Reverse geocoding ------------------------------------------------------
+
+export const reverseGeocodeRequestSchema = latLngSchema;
+export type ReverseGeocodeRequest = z.infer<typeof reverseGeocodeRequestSchema>;
+
+/**
+ * The REST response for `POST /api/maps/reverse-geocode`.
+ *
+ * - `road`    — short street name (e.g. "Hayes Street"). Backs the pivot
+ *   engine's road-name fallback.
+ * - `address` — full formatted street address with house number + locality
+ *   (e.g. "369 Hayes Street, San Francisco, California 94102"). Backs the
+ *   navigation miniapp's dropped-pin / POI-tap labels.
+ *
+ * Either field is null when nothing of that kind was found near the coordinate;
+ * that is a successful empty answer, not an error (an actual failure is a
+ * non-2xx response).
+ */
+export const reverseGeocodeResultSchema = z.object({
+  road: z.string().nullable(),
+  address: z.string().nullable(),
+});
+export type ReverseGeocodeResult = z.infer<typeof reverseGeocodeResultSchema>;
+
+// --- Place search (autocomplete + details) ----------------------------------
+//
+// A two-step "type-ahead then pick" flow, provider-neutral like the rest of this
+// file. `placeAutocomplete` lists lightweight suggestions as the user types;
+// `placeDetails` resolves the chosen suggestion to coordinates. A `sessionToken`
+// threads BOTH calls so the provider can bill the keystrokes + the final detail
+// fetch as ONE search session (Mapbox Search Box and Google Places both work
+// this way). Callers create one token per "search box opening" and rotate it
+// after a pick.
+
+export const placeAutocompleteRequestSchema = z.object({
+  /** The user's partial query. Empty/whitespace yields no suggestions. */
+  query: z.string(),
+  /** Optional location bias — rank results near this coordinate. */
+  near: latLngSchema.optional(),
+  /** Opaque per-search-session token; the same value should go on `placeDetails`. */
+  sessionToken: z.string(),
+});
+export type PlaceAutocompleteRequest = z.infer<typeof placeAutocompleteRequestSchema>;
+
+/** One type-ahead suggestion. `placeId` is fed back into `placeDetails`. */
+export const placeSuggestionSchema = z.object({
+  placeId: z.string(),
+  /** Primary line, e.g. "Blue Bottle Coffee". */
+  mainText: z.string(),
+  /** Secondary line, e.g. "66 Mint St, San Francisco". Empty when none. */
+  secondaryText: z.string(),
+});
+export type PlaceSuggestion = z.infer<typeof placeSuggestionSchema>;
+
+export const placeAutocompleteResultSchema = z.object({
+  suggestions: z.array(placeSuggestionSchema),
+});
+export type PlaceAutocompleteResult = z.infer<typeof placeAutocompleteResultSchema>;
+
+export const placeDetailsRequestSchema = z.object({
+  /** A `placeId` returned by a prior `placeAutocomplete` suggestion. */
+  placeId: z.string(),
+  /** The same session token used for the autocomplete that produced this id. */
+  sessionToken: z.string(),
+});
+export type PlaceDetailsRequest = z.infer<typeof placeDetailsRequestSchema>;
+
+/** The resolved place: a name, formatted address, and coordinates to route to. */
+export const placeDetailsResultSchema = z.object({
+  placeId: z.string(),
+  name: z.string(),
+  address: z.string(),
+  lat: z.number(),
+  lng: z.number(),
+});
+export type PlaceDetailsResult = z.infer<typeof placeDetailsResultSchema>;

package/src/messages.ts

@@ -0,0 +1,74 @@
+/**
+ * @fileoverview The WebSocket message registry.
+ *
+ * Each transport `type` maps 1:1 to an enveloped zod schema; the schemas are
+ * combined into discriminated unions on `type` for parse-time validation on
+ * both ends. Transport-level types live in protocol.md; per-service push events
+ * (stream.transcript / stream.translation) are registered by the audio service
+ * doc but their schemas live here so the one union validates everything.
+ *
+ * Pure + isomorphic: no server imports.
+ */
+import { z } from "zod";
+import { envelope } from "./envelope";
+import { connectionInitPayloadSchema, connectionAckPayloadSchema } from "./handshake";
+import { controlPingPayloadSchema, controlPongPayloadSchema } from "./control";
+import { protocolErrorPayloadSchema } from "./errors";
+import { transcriptionDataSchema, translationDataSchema, udpLivenessAckPayloadSchema } from "./audio";
+import { photoReadyPayloadSchema, photoErrorPayloadSchema } from "./camera";
+
+// --- Per-type enveloped message schemas -------------------------------------
+
+export const connectionInitMessage = envelope("connection.init", connectionInitPayloadSchema);
+export const connectionAckMessage = envelope("connection.ack", connectionAckPayloadSchema);
+export const controlPingMessage = envelope("control.ping", controlPingPayloadSchema);
+export const controlPongMessage = envelope("control.pong", controlPongPayloadSchema);
+export const errorMessage = envelope("error", protocolErrorPayloadSchema);
+
+// Audio service push events (registered in audio/protocol.md).
+export const streamTranscriptMessage = envelope("stream.transcript", transcriptionDataSchema);
+export const streamTranslationMessage = envelope("stream.translation", translationDataSchema);
+export const audioUdpLivenessAckMessage = envelope("audio.udp_liveness_ack", udpLivenessAckPayloadSchema);
+
+// Camera service push events (registered in camera/spec.md).
+export const photoReadyMessage = envelope("photo.ready", photoReadyPayloadSchema);
+export const photoErrorMessage = envelope("photo.error", photoErrorPayloadSchema);
+
+// --- Direction-scoped unions ------------------------------------------------
+
+/** Messages the client sends to the cloud. */
+export const clientToCloudMessage = z.discriminatedUnion("type", [
+  connectionInitMessage,
+  controlPingMessage,
+  controlPongMessage,
+]);
+export type ClientToCloudMessage = z.infer<typeof clientToCloudMessage>;
+
+/** Messages the cloud pushes to the client. */
+export const cloudToClientMessage = z.discriminatedUnion("type", [
+  connectionAckMessage,
+  controlPingMessage,
+  controlPongMessage,
+  errorMessage,
+  streamTranscriptMessage,
+  streamTranslationMessage,
+  audioUdpLivenessAckMessage,
+  photoReadyMessage,
+  photoErrorMessage,
+]);
+export type CloudToClientMessage = z.infer<typeof cloudToClientMessage>;
+
+/** Every known message in either direction. */
+export const anyMessage = z.discriminatedUnion("type", [
+  connectionInitMessage,
+  connectionAckMessage,
+  controlPingMessage,
+  controlPongMessage,
+  errorMessage,
+  streamTranscriptMessage,
+  streamTranslationMessage,
+  audioUdpLivenessAckMessage,
+  photoReadyMessage,
+  photoErrorMessage,
+]);
+export type AnyMessage = z.infer<typeof anyMessage>;