@fleetless/contracts 1.0.0

package/dist/realtime.d.ts

@@ -0,0 +1,494 @@
+import { z } from 'zod';
+/**
+ * Client realtime protocol (spec §11.1): WebSocket subscriptions on
+ * datapoints. W1 scope: subscribe/unsubscribe plus the datapoint event
+ * stream; command parity arrives in W4.
+ */
+/**
+ * The first frame a client sends after the socket opens (W3, spec §3.4).
+ *
+ * A browser cannot set an `Authorization` header on a WebSocket handshake,
+ * and a token in the query string would outlive the request in server,
+ * proxy and browser-history logs. So `/realtime` authenticates the way
+ * `/bridge` already does: with a frame. `token` is the same bearer value
+ * REST takes — a user's JWT or a server key (`flk_…`), told apart by prefix.
+ *
+ * Any `subscribe` before `auth_ok` is refused, and a socket that sends no
+ * auth frame in time is closed with **4002**, the code the bridge socket
+ * already uses for a missing hello.
+ */
+export declare const clientAuth: z.ZodObject<{
+    type: z.ZodLiteral<"auth">;
+    token: z.ZodString;
+}, z.core.$strip>;
+export type ClientAuth = z.infer<typeof clientAuth>;
+/**
+ * Who the socket turned out to belong to. Carrying the identity here means a
+ * client never has to decode a JWT to render its own session — decoding a
+ * token client-side is how apps end up trusting claims nobody verified.
+ */
+export declare const authOk: z.ZodObject<{
+    type: z.ZodLiteral<"auth_ok">;
+    identity: z.ZodObject<{
+        kind: z.ZodEnum<{
+            developer: "developer";
+            server_key: "server_key";
+            app_user: "app_user";
+        }>;
+        developer_id: z.ZodNullable<z.ZodUUID>;
+        app_user_id: z.ZodNullable<z.ZodUUID>;
+        server_key_id: z.ZodNullable<z.ZodUUID>;
+        app_id: z.ZodNullable<z.ZodUUID>;
+        role_id: z.ZodNullable<z.ZodUUID>;
+        email: z.ZodNullable<z.ZodEmail>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type AuthOk = z.infer<typeof authOk>;
+/** Refusal, followed by close 1008 — same shape as the bridge's hello_error. */
+export declare const authError: z.ZodObject<{
+    type: z.ZodLiteral<"auth_error">;
+    code: z.ZodString;
+    message: z.ZodString;
+}, z.core.$strip>;
+export type AuthError = z.infer<typeof authError>;
+/**
+ * Command parity (spec §11.1): everything REST can do — invoke an action,
+ * call a service, publish, cancel — also travels over this socket.
+ *
+ * **Every command carries a `request_id` and every reply echoes it.** A
+ * subscribe that gets dropped is self-healing: the client resubscribes on
+ * reconnect and nothing was promised. A *command* that gets dropped is an
+ * instruction someone believes they issued and no one will ever run — on a
+ * machine that may be moving. Correlation is what makes the difference
+ * observable instead of silent.
+ */
+export declare const clientInvoke: z.ZodObject<{
+    type: z.ZodLiteral<"invoke">;
+    request_id: z.ZodString;
+    robot_id: z.ZodUUID;
+    slug: z.ZodString;
+    params: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    patience_ms: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type ClientInvoke = z.infer<typeof clientInvoke>;
+export declare const clientCancel: z.ZodObject<{
+    type: z.ZodLiteral<"cancel">;
+    request_id: z.ZodString;
+    robot_id: z.ZodUUID;
+    slug: z.ZodString;
+    job_id: z.ZodNullable<z.ZodUUID>;
+}, z.core.$strip>;
+export type ClientCancel = z.infer<typeof clientCancel>;
+export declare const clientPublish: z.ZodObject<{
+    type: z.ZodLiteral<"publish">;
+    request_id: z.ZodString;
+    robot_id: z.ZodUUID;
+    slug: z.ZodString;
+    message: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+}, z.core.$strip>;
+export type ClientPublish = z.infer<typeof clientPublish>;
+/**
+ * The reply to exactly one command. `ok:false` carries the stable code —
+ * `busy`, `robot_offline`, `parameter_invalid`, `forbidden` — so a caller
+ * branches without parsing prose.
+ *
+ * **`request_id` is the only correlation, and the order these arrive in is
+ * not promised.** Commands sent on one socket reach the robot in the order
+ * they were sent — that ordering is guaranteed and is the point of the
+ * command chain — but their *replies* may arrive in any order, and a client
+ * that pairs them up by arrival order will attribute an outcome to the wrong
+ * command.
+ *
+ * This is not theoretical and not jitter. The ordering chain is released once
+ * a command has reached the bridge, deliberately, so that the next command —
+ * a stop, say — is never held up behind bookkeeping. Work that follows the
+ * send therefore runs unordered: a publish that *acquires* a slug writes an
+ * audit record before answering, while an immediately following publish by
+ * the now-current holder has nothing to write and answers at once. Its reply
+ * overtakes. Measured in W5: exactly one reversal in fifty-six zero-gap
+ * bursts, which is the signature of that cause — it can happen only once per
+ * identity and slug — and not of a race.
+ *
+ * Serialising the replies would mean putting that bookkeeping in front of
+ * every following command, including the stop. The ordering that matters is
+ * the one on the wire to the robot, and it is kept.
+ */
+export declare const commandResult: z.ZodObject<{
+    type: z.ZodLiteral<"command_result">;
+    request_id: z.ZodString;
+    ok: z.ZodBoolean;
+    job: z.ZodNullable<z.ZodObject<{
+        id: z.ZodUUID;
+        robot_id: z.ZodUUID;
+        slug: z.ZodString;
+        state: z.ZodEnum<{
+            failed: "failed";
+            running: "running";
+            succeeded: "succeeded";
+            cancelled: "cancelled";
+            lost: "lost";
+        }>;
+        started_at: z.ZodISODateTime;
+        updated_at: z.ZodISODateTime;
+        seq: z.ZodNumber;
+        result: z.ZodNullable<z.ZodUnknown>;
+        error: z.ZodNullable<z.ZodObject<{
+            code: z.ZodString;
+            message: z.ZodString;
+            details: z.ZodOptional<z.ZodUnknown>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    kind: z.ZodNullable<z.ZodEnum<{
+        datapoint: "datapoint";
+        action: "action";
+        service: "service";
+        publisher: "publisher";
+        camera: "camera";
+    }>>;
+    code: z.ZodNullable<z.ZodString>;
+    message: z.ZodNullable<z.ZodString>;
+    details: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$strip>;
+export type CommandResult = z.infer<typeof commandResult>;
+/**
+ * A well-formed frame this server does not understand. The socket **stays
+ * open** — closing it would mean a newer client against an older cloud
+ * reconnects, resends, and takes every unrelated subscription down with it
+ * on every attempt. Close 1008 is reserved for frames that are not parseable
+ * JSON objects at all.
+ */
+export declare const errorFrame: z.ZodObject<{
+    type: z.ZodLiteral<"error">;
+    code: z.ZodString;
+    message: z.ZodString;
+}, z.core.$strip>;
+export type ErrorFrame = z.infer<typeof errorFrame>;
+/**
+ * Subscribe to a slug's stream (spec §11.3: **state is observed by slug**).
+ *
+ * Which kinds are subscribable, and why it is not a matter of taste:
+ *
+ * - **datapoint** — its values.
+ * - **action** — its `jobEvent`s.
+ * - **service** — its `jobEvent`s too. A service call mints a job like an
+ *   action does; the only difference is that the caller usually gets the
+ *   result inline. But when they do *not* — a socket that died before the
+ *   reply, answered with `command_outcome_unknown` — the documented recovery
+ *   is to observe the slug. Refusing that leaves the caller with an error
+ *   that names a remedy the platform does not offer.
+ * - **publisher** — not subscribable: there is no job and no stream. It must
+ *   still be refused *honestly*, with a code saying so, and never as though
+ *   the slug did not exist. A caller who was granted a slug is entitled to
+ *   be told the truth about it.
+ */
+export declare const clientSubscribe: z.ZodObject<{
+    type: z.ZodLiteral<"subscribe">;
+    robot_id: z.ZodUUID;
+    slug: z.ZodString;
+    kind: z.ZodOptional<z.ZodEnum<{
+        datapoint: "datapoint";
+        action: "action";
+        service: "service";
+        publisher: "publisher";
+        camera: "camera";
+    }>>;
+    options: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+export type ClientSubscribe = z.infer<typeof clientSubscribe>;
+export declare const clientUnsubscribe: z.ZodObject<{
+    type: z.ZodLiteral<"unsubscribe">;
+    robot_id: z.ZodUUID;
+    slug: z.ZodString;
+}, z.core.$strip>;
+export type ClientUnsubscribe = z.infer<typeof clientUnsubscribe>;
+/**
+ * Refusal of a subscribe, addressed by the (robot_id, slug) it refers to.
+ * Codes follow the §11.5 error culture: stable code + human message.
+ * robot_id/slug are plain strings ECHOING what the client sent — the frame
+ * must be constructible precisely when those values are malformed, so that
+ * a bad robot_id or slug gets a diagnosis instead of a dead socket.
+ */
+export declare const subscribeError: z.ZodObject<{
+    type: z.ZodLiteral<"subscribe_error">;
+    robot_id: z.ZodString;
+    slug: z.ZodString;
+    code: z.ZodString;
+    message: z.ZodString;
+}, z.core.$strip>;
+export type SubscribeError = z.infer<typeof subscribeError>;
+/**
+ * One datapoint sample pushed to a subscriber. The current value arrives
+ * immediately on subscribe, then every change. `timestamp_ms` semantics as
+ * in `datapointValue` (capture time; cloud-observed for `bridge_state`).
+ */
+export declare const datapointEvent: z.ZodObject<{
+    type: z.ZodLiteral<"datapoint">;
+    robot_id: z.ZodUUID;
+    slug: z.ZodString;
+    value: z.ZodUnknown;
+    timestamp_ms: z.ZodNumber;
+}, z.core.$strip>;
+export type DatapointEvent = z.infer<typeof datapointEvent>;
+/**
+ * A change in the health of something the developer configured (W6a).
+ *
+ * The push half of `resourceHealthState`; the REST list is the snapshot half,
+ * and neither is useful alone — a page that loads after the change would see
+ * nothing, and a page that never reloads would never learn.
+ *
+ * Delivered on the **developer** socket and scoped to the org, not to a
+ * subscription: the whole point is to reach somebody who is *not* currently
+ * looking at the thing that broke.
+ */
+/**
+ * Why a live camera session ended (W9a).
+ *
+ * **The reason travels WITH the ending, and that is the whole point of this
+ * enum existing rather than a state somebody reads afterwards.** W6a put a
+ * `cause` on the wire, the console named the real reason, and the lead
+ * observed the gate step and closed it — and the review then found it still
+ * could not tell, for a different reason: `stopped_by_config_change` is
+ * **sticky**, nothing moves a camera out of it, and `LiveCameraRow` read that
+ * *current* state at the moment a stream ended. A config change at 10:00 and
+ * an unrelated release at 10:30 therefore reported the same cause (DEF-070).
+ *
+ * A state read after the fact answers "what is true now". A viewer needs
+ * "what happened to my session", and only an event carries that.
+ */
+export declare const liveSessionEndReason: z.ZodEnum<{
+    unknown: "unknown";
+    robot_offline: "robot_offline";
+    publish_failed: "publish_failed";
+    released_by_peer: "released_by_peer";
+    config_changed: "config_changed";
+    revoked: "revoked";
+    expired: "expired";
+    robot_deleted: "robot_deleted";
+}>;
+export type LiveSessionEndReason = z.infer<typeof liveSessionEndReason>;
+/**
+ * A live camera session ended, told to the **client that holds it** (W9a).
+ *
+ * This is the channel `DEF-051`, `DEF-052`, `DEF-053` and `DEF-070` each
+ * described from a different direction across four waves. Until now the only
+ * vehicle was `camera_state`, which the cloud stores in `publishState` and
+ * reads in exactly one place — refusing a *later* joiner — so reporting a
+ * failure would have written to a dead end.
+ *
+ * Unlike `resourceHealthEvent`, which is developer-only and org-scoped, this
+ * one is addressed to the **holder of the session**: it names `session_id`
+ * (W6b gave `liveSessionResponse` one precisely so a session could be
+ * addressed) and is delivered only to the identity that session was minted
+ * for. A developer watching the same robot learns about the *resource* health;
+ * the viewer learns about *their own session*. Two questions, two channels,
+ * on purpose.
+ */
+export declare const liveSessionEvent: z.ZodObject<{
+    type: z.ZodLiteral<"live_session">;
+    robot_id: z.ZodUUID;
+    slug: z.ZodString;
+    session_id: z.ZodUUID;
+    state: z.ZodLiteral<"ended">;
+    reason: z.ZodEnum<{
+        unknown: "unknown";
+        robot_offline: "robot_offline";
+        publish_failed: "publish_failed";
+        released_by_peer: "released_by_peer";
+        config_changed: "config_changed";
+        revoked: "revoked";
+        expired: "expired";
+        robot_deleted: "robot_deleted";
+    }>;
+    detail: z.ZodNullable<z.ZodString>;
+    ended_at_ms: z.ZodNumber;
+}, z.core.$strip>;
+export type LiveSessionEvent = z.infer<typeof liveSessionEvent>;
+/**
+ * A resource's health entry was **withdrawn** (W9a, DEF-071).
+ *
+ * The store's `invalidate()` deliberately emitted nothing, reasoning that
+ * "withdrawing a claim nobody can currently stand behind is not new
+ * information — the next `GET` already reflects it." That holds for a page
+ * that loads later. **It is false for a page that is already open, because
+ * there is no next `GET`:** `ensureSnapshot()` runs on `acquire` and nowhere
+ * else, there is no interval, and the event handler only ever *writes* keys.
+ * A camera retargeted to a source that never reports — which is the case the
+ * clearing exists for — leaves an open tab showing the old value indefinitely.
+ *
+ * **A separate event type rather than a nullable `state` on the existing
+ * one**, so a consumer's `switch` has to name it. A nullable field invites
+ * `if (state)` and fails silently when somebody forgets; an unhandled variant
+ * fails `tsc`, which is the difference between a rule and a mechanism.
+ */
+export declare const resourceHealthCleared: z.ZodObject<{
+    type: z.ZodLiteral<"resource_health_cleared">;
+    robot_id: z.ZodUUID;
+    kind: z.ZodEnum<{
+        camera: "camera";
+    }>;
+    ref: z.ZodString;
+    facet: z.ZodEnum<{
+        source: "source";
+        publish: "publish";
+    }>;
+    cleared_at_ms: z.ZodNumber;
+}, z.core.$strip>;
+export type ResourceHealthCleared = z.infer<typeof resourceHealthCleared>;
+export declare const resourceHealthEvent: z.ZodObject<{
+    type: z.ZodLiteral<"resource_health">;
+    robot_id: z.ZodUUID;
+    kind: z.ZodEnum<{
+        camera: "camera";
+    }>;
+    ref: z.ZodString;
+    facet: z.ZodEnum<{
+        source: "source";
+        publish: "publish";
+    }>;
+    state: z.ZodEnum<{
+        unknown: "unknown";
+        ok: "ok";
+        unreachable: "unreachable";
+        auth_failed: "auth_failed";
+        unreadable_credential: "unreadable_credential";
+        credential_missing: "credential_missing";
+        stopped_by_config_change: "stopped_by_config_change";
+        publish_failed: "publish_failed";
+    }>;
+    reason: z.ZodNullable<z.ZodString>;
+    changed_at_ms: z.ZodNumber;
+}, z.core.$strip>;
+export type ResourceHealthEvent = z.infer<typeof resourceHealthEvent>;
+/**
+ * One line of the developer console's activity panel (spec
+ * `2026-08-20-org-event-stream`).
+ *
+ * **This is an activity log for humans, not a complete feed.** It is throttled
+ * and sampled. `orgEventDropped` still reports a drop on the wire, but since
+ * FL-001 **no Fleetless surface renders it** — the console's gap banner was
+ * removed on request, and nothing replaced it. A reader of this stream
+ * therefore cannot tell a complete window from a sampled one, and this
+ * comment says so rather than implying a notice that exists only in the
+ * protocol. Anything that needs completeness reads the audit log or the
+ * job-run history, both durable, both 90 days.
+ */
+export declare const ORG_EVENT_SAMPLE_INTERVAL_MS = 1000;
+/** The backstop above the per-slug cap: a fleet larger than the panel could serve anyway. */
+export declare const ORG_EVENT_ORG_CEILING_PER_SECOND = 50;
+/** Roughly 25 screens of scrollback. */
+export declare const ORG_EVENT_BUFFER_SIZE = 200;
+/** An org's buffer is dropped after this long without an event, so memory follows active orgs rather than all of them. */
+export declare const ORG_EVENT_BUFFER_IDLE_MS = 3600000;
+/** A log line, not a payload: a datapoint value is `unknown` and a LaserScan is megabytes. */
+export declare const ORG_EVENT_DETAIL_MAX_BYTES = 4096;
+/**
+ * `'alert'` — a transition of a datapoint alert (`ok ⇄ firing`, spec
+ * `2026-08-28-alerts-and-datapoint-modal-design` D2). A firing event carries
+ * the alert's own `severity`; a resolved event is always `info` — resolving
+ * is good news regardless of how bad the firing was.
+ *
+ * `'datapoint'` — since FL-001, **no producer emits this kind**: the
+ * datapoint producer was made a deliberate no-op (Task 5/6, this stream's own
+ * per-slug sampling made it redundant with what the datapoint history route
+ * already serves). The member stays in the enum rather than being removed,
+ * because a reader may still hold a pre-deploy frame of this kind sitting in
+ * a buffer (a reconnect replay, a client that hasn't refreshed) and must be
+ * able to parse it rather than fail closed on an old, valid value. Same shape
+ * as the correction on `ORG_EVENT_SAMPLE_INTERVAL_MS`'s comment just above:
+ * name what the wire no longer does instead of leaving a value the cloud can
+ * never send undocumented.
+ */
+export declare const orgEventKind: z.ZodEnum<{
+    datapoint: "datapoint";
+    bridge: "bridge";
+    job: "job";
+    health: "health";
+    audit: "audit";
+    alert: "alert";
+}>;
+export type OrgEventKind = z.infer<typeof orgEventKind>;
+/**
+ * Assigned by the **producer**, never derived by the reader. The console's
+ * `errors` filter cuts across all five kinds, and only the source knows whether
+ * an `auth_failed` is bad. A reader guessing from `detail` guesses differently
+ * for each source.
+ */
+export declare const orgEventSeverity: z.ZodEnum<{
+    error: "error";
+    warning: "warning";
+    info: "info";
+}>;
+export type OrgEventSeverity = z.infer<typeof orgEventSeverity>;
+export declare const orgEvent: z.ZodObject<{
+    type: z.ZodLiteral<"org_event">;
+    seq: z.ZodNumber;
+    at: z.ZodISODateTime;
+    kind: z.ZodEnum<{
+        datapoint: "datapoint";
+        bridge: "bridge";
+        job: "job";
+        health: "health";
+        audit: "audit";
+        alert: "alert";
+    }>;
+    severity: z.ZodEnum<{
+        error: "error";
+        warning: "warning";
+        info: "info";
+    }>;
+    robot_id: z.ZodNullable<z.ZodUUID>;
+    subject: z.ZodString;
+    detail: z.ZodNullable<z.ZodUnknown>;
+}, z.core.$strict>;
+export type OrgEvent = z.infer<typeof orgEvent>;
+/** Sent by a developer's socket to start the stream. Answered by `orgEventReplay`, then live `orgEvent`s. */
+export declare const orgEventSubscribe: z.ZodObject<{
+    type: z.ZodLiteral<"org_event_subscribe">;
+}, z.core.$strict>;
+export type OrgEventSubscribe = z.infer<typeof orgEventSubscribe>;
+export declare const orgEventUnsubscribe: z.ZodObject<{
+    type: z.ZodLiteral<"org_event_unsubscribe">;
+}, z.core.$strict>;
+export type OrgEventUnsubscribe = z.infer<typeof orgEventUnsubscribe>;
+/**
+ * What the cloud still remembers, oldest first, sent once before the live
+ * stream starts — so the panel is filled on arrival rather than blank until
+ * something happens. A blank panel is indistinguishable from a broken one.
+ */
+export declare const orgEventReplay: z.ZodObject<{
+    type: z.ZodLiteral<"org_event_replay">;
+    events: z.ZodArray<z.ZodObject<{
+        type: z.ZodLiteral<"org_event">;
+        seq: z.ZodNumber;
+        at: z.ZodISODateTime;
+        kind: z.ZodEnum<{
+            datapoint: "datapoint";
+            bridge: "bridge";
+            job: "job";
+            health: "health";
+            audit: "audit";
+            alert: "alert";
+        }>;
+        severity: z.ZodEnum<{
+            error: "error";
+            warning: "warning";
+            info: "info";
+        }>;
+        robot_id: z.ZodNullable<z.ZodUUID>;
+        subject: z.ZodString;
+        detail: z.ZodNullable<z.ZodUnknown>;
+    }, z.core.$strict>>;
+    complete: z.ZodBoolean;
+}, z.core.$strict>;
+export type OrgEventReplay = z.infer<typeof orgEventReplay>;
+/**
+ * Events this socket will never see. Two causes, reported alike: the cloud
+ * sampled them away, or this socket's send buffer was too far behind. Both mean
+ * *there was more than you are being shown*.
+ */
+export declare const orgEventDropped: z.ZodObject<{
+    type: z.ZodLiteral<"org_event_dropped">;
+    since_ms: z.ZodNumber;
+    dropped: z.ZodNumber;
+}, z.core.$strict>;
+export type OrgEventDropped = z.infer<typeof orgEventDropped>;