@fleetless/contracts 1.2.0 → 3.0.0

package/artifacts/schema/robot-detail-response.schema.json

@@ -36,11 +36,16 @@
               "type": "null"
             }
           ]
+        },
+        "low_bandwidth": {
+          "type": "boolean",
+          "description": "Whether the bridge is in its low-bandwidth mode: datapoints capped, cameras reduced or stopped. Bridge-reported."
         }
       },
       "required": [
         "online",
-        "latency_ms"
+        "latency_ms",
+        "low_bandwidth"
       ],
       "additionalProperties": false
     },
@@ -82,6 +87,15 @@
       ],
       "additionalProperties": false
     },
+    "protocol_status": {
+      "description": "Where this robot's bridge stands against the protocol window: `current`, `deprecated` (still served, sunset date on the detail), or `refused` (its last hello was refused for its version; offline until upgraded). Absent from a cloud older than 0.21.0; read absence as `current`.",
+      "type": "string",
+      "enum": [
+        "current",
+        "deprecated",
+        "refused"
+      ]
+    },
     "bridge_version": {
       "anyOf": [
         {
@@ -93,6 +107,52 @@
         }
       ]
     },
+    "protocol_version": {
+      "description": "The protocol version the bridge announced in its last accepted hello; `null` before the first. Absent from a cloud older than 0.21.0.",
+      "anyOf": [
+        {
+          "type": "integer",
+          "exclusiveMinimum": 0,
+          "maximum": 9007199254740991
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "protocol": {
+      "description": "The window verdict for `protocol_version`.",
+      "type": "object",
+      "properties": {
+        "status": {
+          "type": "string",
+          "enum": [
+            "current",
+            "deprecated",
+            "refused"
+          ],
+          "description": "Same values as `protocol_status`."
+        },
+        "sunset_at": {
+          "anyOf": [
+            {
+              "type": "string",
+              "format": "date",
+              "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "description": "ISO date the announced version stops being served; `null` when current or unknown."
+        }
+      },
+      "required": [
+        "status",
+        "sunset_at"
+      ],
+      "additionalProperties": false
+    },
     "last_hello_error": {
       "anyOf": [
         {
@@ -202,7 +262,8 @@
                       "action",
                       "service",
                       "publisher",
-                      "camera"
+                      "camera",
+                      "low_bandwidth"
                     ]
                   },
                   "code": {

package/artifacts/schema/robot-list-item.schema.json

@@ -36,11 +36,16 @@
               "type": "null"
             }
           ]
+        },
+        "low_bandwidth": {
+          "type": "boolean",
+          "description": "Whether the bridge is in its low-bandwidth mode: datapoints capped, cameras reduced or stopped. Bridge-reported."
         }
       },
       "required": [
         "online",
-        "latency_ms"
+        "latency_ms",
+        "low_bandwidth"
       ],
       "additionalProperties": false
     },
@@ -81,6 +86,15 @@
         "cameras"
       ],
       "additionalProperties": false
+    },
+    "protocol_status": {
+      "description": "Where this robot's bridge stands against the protocol window: `current`, `deprecated` (still served, sunset date on the detail), or `refused` (its last hello was refused for its version; offline until upgraded). Absent from a cloud older than 0.21.0; read absence as `current`.",
+      "type": "string",
+      "enum": [
+        "current",
+        "deprecated",
+        "refused"
+      ]
     }
   },
   "required": [

package/artifacts/schema/robot-list-response.schema.json

@@ -41,11 +41,16 @@
                     "type": "null"
                   }
                 ]
+              },
+              "low_bandwidth": {
+                "type": "boolean",
+                "description": "Whether the bridge is in its low-bandwidth mode: datapoints capped, cameras reduced or stopped. Bridge-reported."
               }
             },
             "required": [
               "online",
-              "latency_ms"
+              "latency_ms",
+              "low_bandwidth"
             ],
             "additionalProperties": false
           },
@@ -86,6 +91,15 @@
               "cameras"
             ],
             "additionalProperties": false
+          },
+          "protocol_status": {
+            "description": "Where this robot's bridge stands against the protocol window: `current`, `deprecated` (still served, sunset date on the detail), or `refused` (its last hello was refused for its version; offline until upgraded). Absent from a cloud older than 0.21.0; read absence as `current`.",
+            "type": "string",
+            "enum": [
+              "current",
+              "deprecated",
+              "refused"
+            ]
           }
         },
         "required": [

package/artifacts/schema/robot-token-rotate-response.schema.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "token": {
+      "type": "string",
+      "pattern": "^frt_[0-9a-f]{32}$",
+      "description": "The robot's new bridge token. Returned exactly once; the previous token stops working at the bridge's next hello."
+    }
+  },
+  "required": [
+    "token"
+  ],
+  "additionalProperties": false
+}

package/artifacts/schema-outgoing/bridge-asset-progress.schema.json

@@ -38,32 +38,38 @@
             "enum": [
               "unresolvable",
               "upload_failed",
-              "refused",
-              "too_large"
+              "refused"
             ],
-            "description": "Why it failed. `unresolvable` means the reference names nothing the producer can find or may read, and is **permanent** — the only kind reconciliation may treat as gone. `upload_failed` means the bytes exist and the transfer did not succeed, `refused` means it was never attempted because a producer-side ceiling was hit, and `too_large` means it exceeds the upload limit and carries both numbers in `details`."
+            "description": "Why it failed. `unresolvable` means the reference names nothing the producer can find or may read, and is **permanent** — the only kind reconciliation may treat as gone. `upload_failed` means the bytes exist and the transfer did not succeed, and `refused` means it was never attempted, either because the robot's asset store had no room — then `details` carries the three numbers — or because a producer-side ceiling was hit."
           },
           "details": {
-            "description": "The two numbers behind a `too_large` failure, and absent for every other kind — a forced `null` on every `unresolvable` entry buys nothing. The pairing is enforced, not merely described.",
+            "description": "The three numbers behind a `refused` entry the robot's store had no room for, and absent for every other kind — a forced `null` on every `unresolvable` entry buys nothing. A `refused` entry may also carry no details: the producer's own ceiling is the other half of that kind, and no store number describes it.",
             "anyOf": [
               {
                 "type": "object",
                 "properties": {
-                  "limit_bytes": {
+                  "store_bytes": {
                     "type": "integer",
                     "exclusiveMinimum": 0,
                     "maximum": 9007199254740991,
-                    "description": "The upload ceiling, in bytes."
+                    "description": "The robot's store, in bytes."
+                  },
+                  "used_bytes": {
+                    "type": "integer",
+                    "minimum": 0,
+                    "maximum": 9007199254740991,
+                    "description": "Bytes the robot's assets occupy before this upload."
                   },
                   "size_bytes": {
                     "type": "integer",
                     "exclusiveMinimum": 0,
                     "maximum": 9007199254740991,
-                    "description": "How large the refused file is, in bytes. With `limit_bytes` beside it a developer can tell whether to shrink the mesh or raise the limit; \"too large\" alone answers neither."
+                    "description": "The refused upload, in bytes."
                   }
                 },
                 "required": [
-                  "limit_bytes",
+                  "store_bytes",
+                  "used_bytes",
                   "size_bytes"
                 ],
                 "additionalProperties": false

package/artifacts/schema-outgoing/bridge-config-applied.schema.json

@@ -29,7 +29,8 @@
               "action",
               "service",
               "publisher",
-              "camera"
+              "camera",
+              "low_bandwidth"
             ]
           },
           "code": {

package/artifacts/schema-outgoing/bridge-link-mode.schema.json

@@ -0,0 +1,37 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "type": {
+      "type": "string",
+      "const": "link_mode"
+    },
+    "low_bandwidth": {
+      "type": "boolean",
+      "description": "Whether the mode is active after this transition."
+    },
+    "reason": {
+      "type": "string",
+      "enum": [
+        "lag",
+        "dwell",
+        "forced",
+        "recovered"
+      ],
+      "description": "`lag`: the cloud-measured lag crossed the threshold; `dwell`: the bridge-measured queue dwell did; `forced`: `mode: on` or `off`; `recovered`: both measures stayed at or below the exit threshold."
+    },
+    "at_ms": {
+      "type": "integer",
+      "minimum": 0,
+      "maximum": 9007199254740991,
+      "description": "Bridge time of the transition, epoch milliseconds."
+    }
+  },
+  "required": [
+    "type",
+    "low_bandwidth",
+    "reason",
+    "at_ms"
+  ],
+  "additionalProperties": false
+}

package/artifacts/schema-outgoing/datapoint-frame.schema.json

@@ -17,6 +17,10 @@
       "type": "integer",
       "minimum": 0,
       "maximum": 9007199254740991
+    },
+    "backfill": {
+      "description": "true when the sample was captured while the bridge was disconnected and is being replayed after the reconnect. The cloud keeps such a sample out of its lag measure; absent means live.",
+      "type": "boolean"
     }
   },
   "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