@fleetless/contracts 2.0.0 → 4.0.0-next.1

package/artifacts/routes.json

@@ -487,6 +487,65 @@
       "transport": "http",
       "notes": "A `default_role_id` naming a role of another app is refused: it is the one cross-app authorization check this shape can carry. Changing the robot set closes every live subscription the app's users hold, since a grant may no longer name a reachable robot."
     },
+    {
+      "method": "GET",
+      "path": "/api/apps/:id/deletion-preview",
+      "section": "apps",
+      "summary": "Reports what deleting the app would destroy, without destroying it.",
+      "audience": "developer",
+      "auth": "developer",
+      "rateLimited": false,
+      "ownerTier": false,
+      "status": 200,
+      "params": [
+        {
+          "name": "id",
+          "description": "The app's uuid, as returned by `POST /api/apps` or listed by `GET /api/apps`."
+        }
+      ],
+      "query": null,
+      "request": null,
+      "response": "app-deletion-summary",
+      "errors": [
+        "unauthorized",
+        "token_expired",
+        "token_revoked",
+        "invalid_uuid",
+        "not_found"
+      ],
+      "transport": "http",
+      "notes": "The same shape the delete's own audit event carries, computed by the same function on purpose: the confirmation dialog and the eventual receipt agree by construction, and any difference between them is real drift rather than two estimates that quietly disagree. \n\n**No `force` parameter, unlike the robot pair this is modelled on.** A robot's open live session is a single nameable state whose interruption is its own hazard, which is why that route makes the caller pass `force` explicitly. An app has no equivalent state to force past, and inventing one would be a guess wearing a guard's clothes — this preview is the guard."
+    },
+    {
+      "method": "DELETE",
+      "path": "/api/apps/:id",
+      "section": "apps",
+      "summary": "Deletes an app and everything it produced.",
+      "audience": "developer",
+      "auth": "developer",
+      "rateLimited": false,
+      "ownerTier": true,
+      "status": 204,
+      "params": [
+        {
+          "name": "id",
+          "description": "The app's uuid, as returned by `POST /api/apps` or listed by `GET /api/apps`."
+        }
+      ],
+      "query": null,
+      "request": null,
+      "response": null,
+      "errors": [
+        "unauthorized",
+        "token_expired",
+        "token_revoked",
+        "tier_required",
+        "invalid_uuid",
+        "not_found"
+      ],
+      "transport": "http",
+      "notes": "Owner tier, and the gate runs **after** the org-scoped lookup: a developer-tier admin therefore sees the same `404` a stranger would for an app outside their org, rather than a tier refusal that confirms the id exists. A full cascade — its users, roles, server keys, invitations, OIDC provider configuration and mail templates all go, recorded once as `app.deleted` carrying an `appDeletionSummary`. Its robots are untouched: they belong to the org, not to the app. \n\n**No `force` parameter** — see `GET /api/apps/:id/deletion-preview`."
+    },
     {
       "method": "POST",
       "path": "/api/apps/:id/roles",
@@ -1360,13 +1419,73 @@
         "not_found"
       ],
       "transport": "http",
-      "notes": "One row per app, created with the app and never absent — an app that has configured nothing reads back the defaults rather than a `404`. `oidc_callback_url` is in the answer and not in the request: it is minted by the cloud from its own public base URL, is the same for every app and every provider, and is the value a developer registers at their identity provider."
+      "notes": "One row per app, created with the app and never absent — an app that has configured nothing reads back the defaults rather than a `404`. `oidc_callback_url` is in the answer and not in the request: it is minted by the cloud from its own public base URL, is the same for every app and every provider, and is the value a developer registers at their identity provider. It stays read-only on every slice write below for a second reason: a writable callback URL would let a caller point the return leg of an OIDC sign-in, which carries an authorization code, at a host they own. `updated_at` is read-only for a duller one: the server stamps it on every write, and a client-supplied value would be a lie about when the row last changed."
     },
     {
       "method": "PUT",
-      "path": "/api/apps/:id/auth-config",
+      "path": "/api/apps/:id/auth-config/registration",
+      "section": "apps",
+      "summary": "Replaces who may self-register, and from where.",
+      "audience": "developer",
+      "auth": "developer",
+      "rateLimited": false,
+      "ownerTier": false,
+      "status": 200,
+      "params": [
+        {
+          "name": "id",
+          "description": "The app's uuid, as returned by `POST /api/apps` or listed by `GET /api/apps`."
+        }
+      ],
+      "query": null,
+      "request": "put-app-auth-registration-request",
+      "response": "app-auth-config",
+      "errors": [
+        "unauthorized",
+        "token_expired",
+        "token_revoked",
+        "invalid_uuid",
+        "validation_error",
+        "not_found"
+      ],
+      "transport": "http",
+      "notes": "**A replace, not a merge, and `.strict()`**: `self_registration`, `allowed_domains` and `allowed_origins` all arrive or the write is refused, so a client built against an older shape cannot silently clear a setting it does not know about. `oidc_callback_url` and `updated_at` are the server's, refused in this body as in every slice's — see `GET`'s notes for why. \n\n`400 validation_error` is where the two field rules land: an entry in `allowed_domains` must be lowercase, since a capitalised one can never match a lowercased address, and an entry in `allowed_origins` must be a bare scheme-host-port with no path, since a browser sends nothing longer in its `Origin` header. Each refuses at configuration time rather than failing silently later. \n\nThe merge is server-side against the stored row, so this write never disturbs the urls or mcp slice."
+    },
+    {
+      "method": "PUT",
+      "path": "/api/apps/:id/auth-config/urls",
+      "section": "apps",
+      "summary": "Replaces the three pages Fleetless's mails point at.",
+      "audience": "developer",
+      "auth": "developer",
+      "rateLimited": false,
+      "ownerTier": false,
+      "status": 200,
+      "params": [
+        {
+          "name": "id",
+          "description": "The app's uuid, as returned by `POST /api/apps` or listed by `GET /api/apps`."
+        }
+      ],
+      "query": null,
+      "request": "put-app-auth-urls-request",
+      "response": "app-auth-config",
+      "errors": [
+        "unauthorized",
+        "token_expired",
+        "token_revoked",
+        "invalid_uuid",
+        "validation_error",
+        "not_found"
+      ],
+      "transport": "http",
+      "notes": "**A replace, not a merge, and `.strict()`**: `invite_url`, `verify_url` and `reset_url` all arrive or the write is refused, so a client built against an older shape cannot silently clear a setting it does not know about. `oidc_callback_url` and `updated_at` are the server's, refused in this body as in every slice's — see `GET`'s notes for why. \n\n`400 validation_error` is where the field rule lands: a URL template must be https (or `http` on `localhost`) and carry its placeholder exactly once — a second occurrence leaves one literal in a mailed link, refused here rather than failing silently once the mail is sent. \n\nThe merge is server-side against the stored row, so this write never disturbs the registration or mcp slice."
+    },
+    {
+      "method": "PUT",
+      "path": "/api/apps/:id/auth-config/mcp",
       "section": "apps",
-      "summary": "Replaces the app's auth settings in one write.",
+      "summary": "Replaces the MCP switch and its login URL together.",
       "audience": "developer",
       "auth": "developer",
       "rateLimited": false,
@@ -1379,7 +1498,7 @@
         }
       ],
       "query": null,
-      "request": "put-app-auth-config-request",
+      "request": "put-app-auth-mcp-request",
       "response": "app-auth-config",
       "errors": [
         "unauthorized",
@@ -1390,7 +1509,7 @@
         "not_found"
       ],
       "transport": "http",
-      "notes": "**A replace, not a merge, and `.strict()`**: every field arrives or the write is refused, so a client built against an older shape cannot silently clear a setting it does not know about. `oidc_callback_url` and `updated_at` are refused in the body — a writable callback URL would let a caller point the return leg of an OIDC sign-in, which carries an authorization code, at a host they own. \n\n`400 validation_error` is where the three field rules land: a URL template must be https (or `http` on `localhost`) and carry its placeholder exactly once, an origin must be a bare scheme-host-port with no path, and a domain must be lowercase. Each refuses at configuration time because each would otherwise fail silently later — a second placeholder leaves one occurrence literal in a mailed link, an origin with a path can never equal a browser's `Origin` header, and a capitalised domain can never match a lowercased address."
+      "notes": "**A replace, not a merge, and `.strict()`**: `mcp_enabled` and `mcp_login_url` both arrive or the write is refused, so a client built against an older shape cannot silently clear a setting it does not know about. `oidc_callback_url` and `updated_at` are the server's, refused in this body as in every slice's — see `GET`'s notes for why. \n\n`mcp_login_url` answers to the same rule as the `urls` slice's three templates — https (or `http` on `localhost`), its placeholder exactly once — refused as `400 validation_error` rather than left to fail mid-OAuth, in a client's browser where no console screen is watching. \n\nThe merge is server-side against the stored row, so this write never disturbs the registration or urls slice."
     },
     {
       "method": "GET",

package/artifacts/schema/app-deletion-summary.schema.json

@@ -0,0 +1,51 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "user_count": {
+      "type": "integer",
+      "minimum": 0,
+      "maximum": 9007199254740991,
+      "description": "App users deleted with the app. They are the developer's own customers, not Fleetless users, and exist in no other app."
+    },
+    "role_count": {
+      "type": "integer",
+      "minimum": 0,
+      "maximum": 9007199254740991,
+      "description": "Roles deleted with the app, each with its per-robot slug grants."
+    },
+    "server_key_count": {
+      "type": "integer",
+      "minimum": 0,
+      "maximum": 9007199254740991,
+      "description": "Server keys deleted with the app. A client still holding one is refused at its next request."
+    },
+    "invitation_count": {
+      "type": "integer",
+      "minimum": 0,
+      "maximum": 9007199254740991,
+      "description": "Outstanding invitations — unspent and unexpired — that will never be accepted."
+    },
+    "oidc_provider_count": {
+      "type": "integer",
+      "minimum": 0,
+      "maximum": 9007199254740991,
+      "description": "Identity providers configured for this app. The providers themselves are somebody else's; only this app's configuration of them goes."
+    },
+    "mail_template_count": {
+      "type": "integer",
+      "minimum": 0,
+      "maximum": 9007199254740991,
+      "description": "Custom mail templates, of at most three. A kind using the Fleetless default text is not counted — there is no row to lose."
+    }
+  },
+  "required": [
+    "user_count",
+    "role_count",
+    "server_key_count",
+    "invitation_count",
+    "oidc_provider_count",
+    "mail_template_count"
+  ],
+  "additionalProperties": false
+}

package/artifacts/schema/bridge-job-lost.schema.json

@@ -13,6 +13,23 @@
         "format": "uuid",
         "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
       }
+    },
+    "error": {
+      "type": "object",
+      "properties": {
+        "code": {
+          "type": "string",
+          "minLength": 1
+        },
+        "message": {
+          "type": "string",
+          "minLength": 1
+        }
+      },
+      "required": [
+        "code",
+        "message"
+      ]
     }
   },
   "required": [

package/artifacts/schema/put-app-auth-mcp-request.schema.json

@@ -0,0 +1,27 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "mcp_enabled": {
+      "type": "boolean",
+      "description": "Whether this app serves an MCP endpoint at `/mcp/<identifier>`. Off refuses the whole OAuth surface for the app, not merely the tool calls, and is re-read on every request rather than cached off a token."
+    },
+    "mcp_login_url": {
+      "anyOf": [
+        {
+          "type": "string",
+          "maxLength": 500
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "The page an MCP authorization redirects to, with `{interaction}` where the interaction id goes. Not a token: the id names a pending request the server already holds, and the app authenticates the user itself before approving it."
+    }
+  },
+  "required": [
+    "mcp_enabled",
+    "mcp_login_url"
+  ],
+  "additionalProperties": false
+}

package/artifacts/schema/put-app-auth-registration-request.schema.json

@@ -0,0 +1,36 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "self_registration": {
+      "type": "boolean",
+      "description": "Whether a stranger may create an account in this app. Off refuses `POST /api/client/register` with `403 registration_closed`, and refuses an unknown identity at an OIDC callback with the same reasoning — one switch for one decision, whichever door the person arrives at."
+    },
+    "allowed_domains": {
+      "maxItems": 50,
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1,
+        "maxLength": 253,
+        "pattern": "^(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+[a-z]{2,63}$"
+      },
+      "description": "The email domains self-registration accepts, lowercase. An empty list means no domain restriction, not \"nobody\" — the switch above is what closes the door. **An invitation always bypasses this**, by password and through a provider alike."
+    },
+    "allowed_origins": {
+      "maxItems": 20,
+      "type": "array",
+      "items": {
+        "type": "string",
+        "maxLength": 200
+      },
+      "description": "The origins the client auth API answers CORS for, and the only origins an OIDC `redirect_uri` may name. Bare origins: scheme, host and port, with no path — a browser sends nothing longer, so an entry carrying one could never match."
+    }
+  },
+  "required": [
+    "self_registration",
+    "allowed_domains",
+    "allowed_origins"
+  ],
+  "additionalProperties": false
+}

package/artifacts/schema/put-app-auth-urls-request.schema.json

@@ -0,0 +1,48 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "invite_url": {
+      "anyOf": [
+        {
+          "type": "string",
+          "maxLength": 500
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "The page in the developer's app that accepts an invitation, with `{token}` where the token goes. `null` when unconfigured, and then an invitation still issues but `send_mail` is refused with `409 target_state_conflict` — there would be nowhere for the link to point."
+    },
+    "verify_url": {
+      "anyOf": [
+        {
+          "type": "string",
+          "maxLength": 500
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "The page that confirms a new address, with `{token}` where the token goes. Self-registration needs it: without a page to send people to, a registration would leave an account nobody can activate."
+    },
+    "reset_url": {
+      "anyOf": [
+        {
+          "type": "string",
+          "maxLength": 500
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "The page that takes a new password, with `{token}` where the token goes."
+    }
+  },
+  "required": [
+    "invite_url",
+    "verify_url",
+    "reset_url"
+  ],
+  "additionalProperties": false
+}

package/artifacts/schema-outgoing/bridge-job-lost.schema.json

@@ -13,6 +13,24 @@
         "format": "uuid",
         "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
       }
+    },
+    "error": {
+      "type": "object",
+      "properties": {
+        "code": {
+          "type": "string",
+          "minLength": 1
+        },
+        "message": {
+          "type": "string",
+          "minLength": 1
+        }
+      },
+      "required": [
+        "code",
+        "message"
+      ],
+      "additionalProperties": false
     }
   },
   "required": [

package/dist/app-users.d.ts

@@ -400,23 +400,41 @@ export declare const appAuthConfig: z.ZodObject<{
 }, z.core.$strip>;
 export type AppAuthConfig = z.infer<typeof appAuthConfig>;
 /**
- * `PUT /api/apps/:id/auth-config` — a replace, not a merge, and `.strict()`.
+ * `PUT /api/apps/:id/auth-config/registration` — who may get in, and from
+ * where.
  *
- * `oidc_callback_url` and `updated_at` are omitted because both are the
- * server's: see the callback URL's own note for why a writable one would be a
- * redirect-target hole rather than a convenience.
+ * Three slices rather than one document, and each still a **replace** with
+ * every field of its slice required: three screens carving up one
+ * all-required request is how a field nobody's screen shows becomes a field
+ * somebody's save clears. The slice states its own ownership, so a new field
+ * lands in one schema and one screen.
+ *
+ * The merge is the server's, against the stored row — never the caller's,
+ * whose copy may be older than the row it would overwrite.
  */
-export declare const putAppAuthConfigRequest: z.ZodObject<{
+export declare const putAppAuthRegistrationRequest: z.ZodObject<{
     self_registration: z.ZodBoolean;
     allowed_domains: z.ZodArray<z.ZodString>;
     allowed_origins: z.ZodArray<z.ZodString>;
-    mcp_enabled: z.ZodBoolean;
+}, z.core.$strict>;
+export type PutAppAuthRegistrationRequest = z.infer<typeof putAppAuthRegistrationRequest>;
+/** `PUT /api/apps/:id/auth-config/urls` — the three pages Fleetless's mails point at. */
+export declare const putAppAuthUrlsRequest: z.ZodObject<{
     invite_url: z.ZodNullable<z.ZodString>;
     verify_url: z.ZodNullable<z.ZodString>;
     reset_url: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>;
+export type PutAppAuthUrlsRequest = z.infer<typeof putAppAuthUrlsRequest>;
+/**
+ * `PUT /api/apps/:id/auth-config/mcp` — the switch and the login URL, which
+ * belong together: on without a URL refuses every sign-in, in the MCP
+ * client's browser mid-OAuth, where no console screen ever sees it.
+ */
+export declare const putAppAuthMcpRequest: z.ZodObject<{
+    mcp_enabled: z.ZodBoolean;
     mcp_login_url: z.ZodNullable<z.ZodString>;
 }, z.core.$strict>;
-export type PutAppAuthConfigRequest = z.infer<typeof putAppAuthConfigRequest>;
+export type PutAppAuthMcpRequest = z.infer<typeof putAppAuthMcpRequest>;
 /**
  * The three mails a developer may replace with their own template.
  * Mails to *Fleetless* users — a team invitation, a console password reset —

package/dist/app-users.js

@@ -481,14 +481,32 @@ export const appAuthConfig = z.object({
     updated_at: z.iso.datetime().meta({ description: 'When the configuration was last written, as an ISO 8601 timestamp.' }),
 });
 /**
- * `PUT /api/apps/:id/auth-config` — a replace, not a merge, and `.strict()`.
+ * `PUT /api/apps/:id/auth-config/registration` — who may get in, and from
+ * where.
  *
- * `oidc_callback_url` and `updated_at` are omitted because both are the
- * server's: see the callback URL's own note for why a writable one would be a
- * redirect-target hole rather than a convenience.
+ * Three slices rather than one document, and each still a **replace** with
+ * every field of its slice required: three screens carving up one
+ * all-required request is how a field nobody's screen shows becomes a field
+ * somebody's save clears. The slice states its own ownership, so a new field
+ * lands in one schema and one screen.
+ *
+ * The merge is the server's, against the stored row — never the caller's,
+ * whose copy may be older than the row it would overwrite.
+ */
+export const putAppAuthRegistrationRequest = appAuthConfig
+    .pick({ self_registration: true, allowed_domains: true, allowed_origins: true })
+    .strict();
+/** `PUT /api/apps/:id/auth-config/urls` — the three pages Fleetless's mails point at. */
+export const putAppAuthUrlsRequest = appAuthConfig
+    .pick({ invite_url: true, verify_url: true, reset_url: true })
+    .strict();
+/**
+ * `PUT /api/apps/:id/auth-config/mcp` — the switch and the login URL, which
+ * belong together: on without a URL refuses every sign-in, in the MCP
+ * client's browser mid-OAuth, where no console screen ever sees it.
  */
-export const putAppAuthConfigRequest = appAuthConfig
-    .omit({ oidc_callback_url: true, updated_at: true })
+export const putAppAuthMcpRequest = appAuthConfig
+    .pick({ mcp_enabled: true, mcp_login_url: true })
     .strict();
 /**
  * The three mails a developer may replace with their own template.

package/dist/apps.d.ts

@@ -42,6 +42,28 @@ export declare const appListResponse: z.ZodObject<{
     }, z.core.$strip>>;
 }, z.core.$strip>;
 export type AppListResponse = z.infer<typeof appListResponse>;
+/**
+ * What deleting an app would destroy — read before the irreversible click,
+ * and carried again by the `app.deleted` audit event.
+ *
+ * **Six numbers, never a sum**, for the reason `robotDeletionSummary` states
+ * at length: the console reads this aloud as one sentence, and a total would
+ * describe six unrelated magnitudes with one figure on the one screen whose
+ * entire justification is naming what cannot be undone.
+ *
+ * Robots are not here because they do not go: they belong to the
+ * organization, not to the app. The audit trail is not here either — a record
+ * of what happened outlives the thing it happened to.
+ */
+export declare const appDeletionSummary: z.ZodObject<{
+    user_count: z.ZodNumber;
+    role_count: z.ZodNumber;
+    server_key_count: z.ZodNumber;
+    invitation_count: z.ZodNumber;
+    oidc_provider_count: z.ZodNumber;
+    mail_template_count: z.ZodNumber;
+}, z.core.$strip>;
+export type AppDeletionSummary = z.infer<typeof appDeletionSummary>;
 /**
  * **`robot_ids` is accepted here, and `.strict()` catches everything else.**
  * A create shape carrying `name` and `identifier` only would let zod strip an

package/dist/apps.js

@@ -78,6 +78,39 @@ export const appListResponse = z.object({
         description: 'Every app of the caller\'s organisation, oldest first by `created_at`. The org scope is the whole filter — there is no id to narrow by and nothing to refuse.',
     }),
 });
+/**
+ * What deleting an app would destroy — read before the irreversible click,
+ * and carried again by the `app.deleted` audit event.
+ *
+ * **Six numbers, never a sum**, for the reason `robotDeletionSummary` states
+ * at length: the console reads this aloud as one sentence, and a total would
+ * describe six unrelated magnitudes with one figure on the one screen whose
+ * entire justification is naming what cannot be undone.
+ *
+ * Robots are not here because they do not go: they belong to the
+ * organization, not to the app. The audit trail is not here either — a record
+ * of what happened outlives the thing it happened to.
+ */
+export const appDeletionSummary = z.object({
+    user_count: z.number().int().nonnegative().meta({
+        description: 'App users deleted with the app. They are the developer\'s own customers, not Fleetless users, and exist in no other app.',
+    }),
+    role_count: z.number().int().nonnegative().meta({
+        description: 'Roles deleted with the app, each with its per-robot slug grants.',
+    }),
+    server_key_count: z.number().int().nonnegative().meta({
+        description: 'Server keys deleted with the app. A client still holding one is refused at its next request.',
+    }),
+    invitation_count: z.number().int().nonnegative().meta({
+        description: 'Outstanding invitations — unspent and unexpired — that will never be accepted.',
+    }),
+    oidc_provider_count: z.number().int().nonnegative().meta({
+        description: 'Identity providers configured for this app. The providers themselves are somebody else\'s; only this app\'s configuration of them goes.',
+    }),
+    mail_template_count: z.number().int().nonnegative().meta({
+        description: 'Custom mail templates, of at most three. A kind using the Fleetless default text is not counted — there is no row to lose.',
+    }),
+});
 /**
  * **`robot_ids` is accepted here, and `.strict()` catches everything else.**
  * A create shape carrying `name` and `identifier` only would let zod strip an

package/dist/errors.d.ts

@@ -49,5 +49,5 @@ export type ParameterInvalidDetails = z.infer<typeof parameterInvalidDetails>;
  * list is the shared vocabulary, not a closed set, so a new refusal never
  * needs a contracts release before it can be reported honestly.
  */
-export declare const ERROR_CODES: readonly ["not_found", "validation_error", "bad_request", "unknown_datapoint", "invalid_token", "protocol_mismatch", "invalid_frame", "duplicate_slug", "reserved_slug", "unknown_slug", "unknown_field_path", "unknown_type", "unknown_topic", "invalid_rate", "invalid_range", "config_conflict", "no_data", "robot_offline", "bridge_timeout", "unauthorized", "forbidden", "invalid_credentials", "token_expired", "token_revoked", "email_taken", "identifier_taken", "weak_password", "account_blocked", "busy", "parameter_invalid", "job_lost", "publisher_busy", "unknown_command", "not_subscribable", "camera_offline", "no_snapshot_yet", "live_unavailable", "wrong_kind", "not_recorded", "not_aggregatable", "quota_exceeded", "credential_in_use", "goal_timeout", "robot_in_use", "robot_deletion_partial", "job_queue_full", "invalid_uuid", "rate_limited", "tier_required", "token_spent", "service_timeout", "asset_missing", "dynamic_registration_disabled", "client_limit_reached", "idp_unavailable", "mcp_disabled", "tool_not_available", "capability_required", "last_owner", "target_state_conflict", "signup_closed", "draft_not_a_document", "internal_error", "not_cancellable", "unsupported_media_type", "wrong_browser", "invalid_yaml", "unstorable_yaml", "registration_closed", "domain_not_allowed", "email_unverified", "origin_not_allowed", "template_invalid", "provider_disabled", "provider_misconfigured", "invalid_redirect_uri", "interaction_expired"];
+export declare const ERROR_CODES: readonly ["not_found", "validation_error", "bad_request", "unknown_datapoint", "invalid_token", "protocol_mismatch", "invalid_frame", "duplicate_slug", "reserved_slug", "unknown_slug", "unknown_field_path", "unknown_type", "unknown_topic", "invalid_rate", "invalid_range", "config_conflict", "no_data", "robot_offline", "bridge_timeout", "unauthorized", "forbidden", "invalid_credentials", "token_expired", "token_revoked", "email_taken", "identifier_taken", "weak_password", "account_blocked", "busy", "parameter_invalid", "job_lost", "action_server_lost", "action_failed", "goal_rejected", "goal_send_failed", "result_failed", "goal_uncontrollable", "bridge_disconnected", "config_changed", "publisher_busy", "unknown_command", "not_subscribable", "camera_offline", "no_snapshot_yet", "live_unavailable", "wrong_kind", "not_recorded", "not_aggregatable", "quota_exceeded", "credential_in_use", "goal_timeout", "robot_in_use", "robot_deletion_partial", "job_queue_full", "invalid_uuid", "rate_limited", "tier_required", "token_spent", "service_timeout", "asset_missing", "dynamic_registration_disabled", "client_limit_reached", "idp_unavailable", "mcp_disabled", "tool_not_available", "capability_required", "last_owner", "target_state_conflict", "signup_closed", "draft_not_a_document", "internal_error", "not_cancellable", "unsupported_media_type", "wrong_browser", "invalid_yaml", "unstorable_yaml", "registration_closed", "domain_not_allowed", "email_unverified", "origin_not_allowed", "template_invalid", "provider_disabled", "provider_misconfigured", "invalid_redirect_uri", "interaction_expired"];
 export type ErrorCode = (typeof ERROR_CODES)[number];

package/dist/errors.js

@@ -71,6 +71,13 @@ export const ERROR_CODES = [
     'no_data',
     // Talking to the robot.
     'robot_offline',
+    /**
+     * The cloud has heard nothing — heartbeat or real progress — from a
+     * running job for longer than it tolerates while the bridge is connected:
+     * `patience_ms` for a protocol-3 bridge, `JOB_HEARTBEAT_TIMEOUT_MS` for a
+     * protocol-4 one once it has heard from the job at all. `job.error.code`
+     * on `lost`.
+     */
     'bridge_timeout',
     // Identity and rights. `forbidden` is deliberately the answer both
     // for "your role does not grant this" and for "there is no such slug":
@@ -140,6 +147,37 @@ export const ERROR_CODES = [
     'parameter_invalid',
     /** The bridge could not account for this job after a restart. */
     'job_lost',
+    /**
+     * The robot's action server vanished mid-goal — the bridge's own liveness
+     * check found `server_is_ready()` false for three seconds straight and
+     * gave up waiting for it to come back. A `job.error.code` on `lost`: the
+     * outcome the goal actually reached is unknown, so `lost` — not `failed` —
+     * is the honest state, and this code says why.
+     */
+    'action_server_lost',
+    /** The action ended with a ROS status other than succeeded; `job.error.code` on `failed`. */
+    'action_failed',
+    /** The action server rejected the goal outright; `job.error.code` on `failed`. */
+    'goal_rejected',
+    /** Sending the goal to the action server itself raised; `job.error.code` on `failed`. */
+    'goal_send_failed',
+    /** Asking the action server for its result raised; `job.error.code` on `failed`. */
+    'result_failed',
+    /** A goal accepted after its own timeout could not then be cancelled; `job.error.code` on `failed`. */
+    'goal_uncontrollable',
+    /**
+     * The robot stayed offline for longer than `JOB_OFFLINE_GRACE_MS` while a
+     * job was running. A late real outcome, if the robot reconnects and the
+     * bridge still has it, corrects this — it is not final the way a genuine
+     * bridge report is. `job.error.code` on `lost`.
+     */
+    'bridge_disconnected',
+    /**
+     * The job's action or service no longer exists in the published
+     * configuration — a republish invalidated it while it was running.
+     * `job.error.code` on `cancelled`.
+     */
+    'config_changed',
     /** Another user holds this publisher and has not been quiet long enough. */
     'publisher_busy',
     /** A well-formed realtime frame this server does not know — the socket stays open. */