@fleetless/contracts 1.0.6 → 1.1.0

package/CHANGELOG.md

@@ -7,6 +7,12 @@ the wire shapes.
 
 ## [Unreleased]
 
+## [1.1.0] — 2026-09-17
+
+### Added
+
+- **Two discovery routes for app users**, the REST twins of the MCP tools every session starts from: `GET /api/client/robots` lists the robots the caller reaches (`clientRobotListResponse`, new), and `GET /api/robots/:id/datasheet` answers the same `mcpRobotDatasheet` that `robot_describe` does — every granted slug with its kind, unit, decimals and parameter JSON Schema, plus the `action_history` and `assets` capabilities. No existing wire shape changes.
+
 ## [1.0.6] — 2026-09-16
 
 - Published from GitHub Actions by npm trusted publishing: no publish token exists anywhere, and every version from this one on carries a provenance attestation linking it to the commit and the run that built it. `npm audit signatures` checks it.

package/artifacts/openapi.json

@@ -5446,6 +5446,104 @@
         "description": "For a client caller the grant check runs **before** any existence lookup, with no extra query on either path to time: a denied slug and a nonexistent one must be one answer. That is why an ungranted slug is `403 forbidden` while a granted-but-unconfigured one is `404 unknown_datapoint` and a configured one with no sample yet is `404 no_data` — three facts a caller who is entitled to them needs told apart. The plane built-ins (`bridge_state`, `robot_details`) answer here too, without appearing in any document."
       }
     },
+    "/api/client/robots": {
+      "get": {
+        "operationId": "get_api_client_robots",
+        "summary": "Lists the robots the caller reaches, with bridge state and the published configuration version.",
+        "tags": [
+          "robots"
+        ],
+        "security": [
+          {
+            "developerSession": []
+          },
+          {
+            "clientToken": []
+          },
+          {
+            "serverKey": []
+          }
+        ],
+        "parameters": [],
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/client-robot-list-response"
+                }
+              }
+            }
+          },
+          "default": {
+            "description": "An error envelope. Codes this route is known to answer: `unauthorized`, `token_expired`, `token_revoked`, `forbidden`.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/api-error"
+                }
+              }
+            }
+          }
+        },
+        "description": "**The REST twin of the MCP tool `robots_list`**, and the one robot question no robot-scoped route can answer: which robots may I name at all. An app user sees the robots their app attaches on which their role grants at least one slug or capability; a server key sees every robot its app attaches; a developer bearer sees the organisation's robots. Name order, id as the tiebreak. A robot on which the role grants nothing is absent rather than listed empty — the same answer `robots_list` gives, for the same reason: reach is a grant, not an attachment. Under `/api/client/` because it names no robot; every robot-scoped read stays under `/api/robots/:id/…`."
+      }
+    },
+    "/api/robots/{id}/datasheet": {
+      "get": {
+        "operationId": "get_api_robots_id_datasheet",
+        "summary": "Describes everything the caller's role lets them do on one robot, with parameter schemas.",
+        "tags": [
+          "robots"
+        ],
+        "security": [
+          {
+            "developerSession": []
+          },
+          {
+            "clientToken": []
+          },
+          {
+            "serverKey": []
+          }
+        ],
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "description": "The robot's uuid, as `GET /api/client/robots` lists it.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/mcp-robot-datasheet"
+                }
+              }
+            }
+          },
+          "default": {
+            "description": "An error envelope. Codes this route is known to answer: `unauthorized`, `token_expired`, `token_revoked`, `forbidden`, `invalid_uuid`, `not_found`.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/api-error"
+                }
+              }
+            }
+          }
+        },
+        "description": "**The REST twin of the MCP tool `robot_describe`**: one answer per robot — every datapoint, action, service, publisher and camera the role grants, each with its `input_schema` where it takes parameters, plus the two capabilities that gate whole features, `action_history` and `assets`. A robot with nothing published answers an empty `exposures` list, never a refusal. A robot the caller does not reach — not attached to their app, or attached with a role that grants nothing on it — answers `404` exactly as one that does not exist. The app-user datapoint and camera listings under this prefix stay; this is the one read that also names actions, services, publishers and capabilities, which is what an app needs before it can draw a screen."
+      }
+    },
     "/api/robots/{id}/config/draft": {
       "get": {
         "operationId": "get_api_robots_id_config_draft",
@@ -10395,6 +10493,88 @@
         ],
         "additionalProperties": false
       },
+      "client-robot-list-response": {
+        "type": "object",
+        "properties": {
+          "robots": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "id": {
+                  "type": "string",
+                  "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)$",
+                  "description": "The robot, and what every robot-scoped route takes as its `:id`."
+                },
+                "name": {
+                  "type": "string",
+                  "minLength": 1,
+                  "maxLength": 63,
+                  "description": "The robot's display name, at most 63 characters. Free text, changed through `PATCH /api/robots/:id`."
+                },
+                "created_at": {
+                  "type": "string",
+                  "format": "date-time",
+                  "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])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
+                  "description": "When the robot was created, as an ISO 8601 timestamp."
+                },
+                "bridge_state": {
+                  "type": "object",
+                  "properties": {
+                    "online": {
+                      "type": "boolean"
+                    },
+                    "latency_ms": {
+                      "anyOf": [
+                        {
+                          "type": "number",
+                          "minimum": 0
+                        },
+                        {
+                          "type": "null"
+                        }
+                      ]
+                    }
+                  },
+                  "required": [
+                    "online",
+                    "latency_ms"
+                  ],
+                  "additionalProperties": false,
+                  "description": "The built-in `bridge_state` datapoint as the cloud observes it right now: whether the bridge is connected, and its latency when it is."
+                },
+                "published_version": {
+                  "anyOf": [
+                    {
+                      "type": "integer",
+                      "exclusiveMinimum": 0,
+                      "maximum": 9007199254740991
+                    },
+                    {
+                      "type": "null"
+                    }
+                  ],
+                  "description": "The published configuration version, or `null` when nothing has been published yet. A robot with nothing published is still listed — \"not configured yet\" is a real state, and the caller is entitled to it — and its datasheet answers an empty exposure list."
+                }
+              },
+              "required": [
+                "id",
+                "name",
+                "created_at",
+                "bridge_state",
+                "published_version"
+              ],
+              "additionalProperties": false
+            },
+            "description": "Every robot the caller reaches, in name order with the id as the tiebreak. An app user reaches the robots their app attaches on which their role grants at least one slug or capability; a server key reaches every robot its app attaches; a developer reaches every robot of the organisation."
+          }
+        },
+        "required": [
+          "robots"
+        ],
+        "additionalProperties": false
+      },
       "client-verify-email-request": {
         "type": "object",
         "properties": {
@@ -14446,6 +14626,120 @@
         ],
         "additionalProperties": false
       },
+      "mcp-robot-datasheet": {
+        "type": "object",
+        "properties": {
+          "robot_id": {
+            "type": "string",
+            "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)$"
+          },
+          "robot_name": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 200
+          },
+          "capabilities": {
+            "type": "object",
+            "properties": {
+              "action_history": {
+                "type": "boolean"
+              },
+              "assets": {
+                "type": "boolean"
+              }
+            },
+            "required": [
+              "action_history",
+              "assets"
+            ],
+            "additionalProperties": false
+          },
+          "exposures": {
+            "maxItems": 2000,
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "slug": {
+                  "type": "string",
+                  "minLength": 2,
+                  "maxLength": 63,
+                  "pattern": "^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$"
+                },
+                "kind": {
+                  "type": "string",
+                  "enum": [
+                    "datapoint",
+                    "service",
+                    "action",
+                    "publisher",
+                    "camera"
+                  ]
+                },
+                "description": {
+                  "anyOf": [
+                    {
+                      "type": "string",
+                      "maxLength": 2000
+                    },
+                    {
+                      "type": "null"
+                    }
+                  ]
+                },
+                "unit": {
+                  "anyOf": [
+                    {
+                      "type": "string",
+                      "maxLength": 32
+                    },
+                    {
+                      "type": "null"
+                    }
+                  ]
+                },
+                "decimals": {
+                  "anyOf": [
+                    {
+                      "type": "integer",
+                      "minimum": 0,
+                      "maximum": 6
+                    },
+                    {
+                      "type": "null"
+                    }
+                  ]
+                },
+                "input_schema": {
+                  "anyOf": [
+                    {},
+                    {
+                      "type": "null"
+                    }
+                  ]
+                }
+              },
+              "required": [
+                "slug",
+                "kind",
+                "description",
+                "unit",
+                "decimals",
+                "input_schema"
+              ],
+              "additionalProperties": false
+            }
+          }
+        },
+        "required": [
+          "robot_id",
+          "robot_name",
+          "capabilities",
+          "exposures"
+        ],
+        "additionalProperties": false
+      },
       "mcp-role-preview-response": {
         "type": "object",
         "properties": {

package/artifacts/routes.json

@@ -273,6 +273,24 @@
       "transport": "http",
       "notes": "HTML. An unknown, spent or expired token renders one \"link no longer valid\" page at `410` — they are one refusal on the wire already, and splitting them here would tell a stranger which tokens ever existed. No rate limiter: the GET changes nothing, and the POST it leads to is limited per IP."
     },
+    {
+      "method": "GET",
+      "path": "/favicon.svg",
+      "section": "client-auth",
+      "summary": "Serves the Fleetless icon for the auth portal's and the MCP welcome page's browser tab.",
+      "audience": "internal",
+      "auth": "none",
+      "rateLimited": false,
+      "ownerTier": false,
+      "status": 200,
+      "params": [],
+      "query": null,
+      "request": null,
+      "response": null,
+      "errors": [],
+      "transport": "http",
+      "notes": "An SVG, not JSON. Those pages carry a Content-Security-Policy that admits no `data:` image, so the icon is a file on their own origin — the one source `img-src 'self'` names. Cached for a day: the bytes change when the brand does, not per deploy."
+    },
     {
       "method": "POST",
       "path": "/api/auth/password/reset/confirm",
@@ -3300,6 +3318,59 @@
       "transport": "http",
       "notes": "For a client caller the grant check runs **before** any existence lookup, with no extra query on either path to time: a denied slug and a nonexistent one must be one answer. That is why an ungranted slug is `403 forbidden` while a granted-but-unconfigured one is `404 unknown_datapoint` and a configured one with no sample yet is `404 no_data` — three facts a caller who is entitled to them needs told apart. The plane built-ins (`bridge_state`, `robot_details`) answer here too, without appearing in any document."
     },
+    {
+      "method": "GET",
+      "path": "/api/client/robots",
+      "section": "robots",
+      "summary": "Lists the robots the caller reaches, with bridge state and the published configuration version.",
+      "audience": "client",
+      "auth": "developer_or_client",
+      "rateLimited": false,
+      "ownerTier": false,
+      "status": 200,
+      "params": [],
+      "query": null,
+      "request": null,
+      "response": "client-robot-list-response",
+      "errors": [
+        "unauthorized",
+        "token_expired",
+        "token_revoked",
+        "forbidden"
+      ],
+      "transport": "http",
+      "notes": "**The REST twin of the MCP tool `robots_list`**, and the one robot question no robot-scoped route can answer: which robots may I name at all. An app user sees the robots their app attaches on which their role grants at least one slug or capability; a server key sees every robot its app attaches; a developer bearer sees the organisation's robots. Name order, id as the tiebreak. A robot on which the role grants nothing is absent rather than listed empty — the same answer `robots_list` gives, for the same reason: reach is a grant, not an attachment. Under `/api/client/` because it names no robot; every robot-scoped read stays under `/api/robots/:id/…`."
+    },
+    {
+      "method": "GET",
+      "path": "/api/robots/:id/datasheet",
+      "section": "robots",
+      "summary": "Describes everything the caller's role lets them do on one robot, with parameter schemas.",
+      "audience": "client",
+      "auth": "developer_or_client",
+      "rateLimited": false,
+      "ownerTier": false,
+      "status": 200,
+      "params": [
+        {
+          "name": "id",
+          "description": "The robot's uuid, as `GET /api/client/robots` lists it."
+        }
+      ],
+      "query": null,
+      "request": null,
+      "response": "mcp-robot-datasheet",
+      "errors": [
+        "unauthorized",
+        "token_expired",
+        "token_revoked",
+        "forbidden",
+        "invalid_uuid",
+        "not_found"
+      ],
+      "transport": "http",
+      "notes": "**The REST twin of the MCP tool `robot_describe`**: one answer per robot — every datapoint, action, service, publisher and camera the role grants, each with its `input_schema` where it takes parameters, plus the two capabilities that gate whole features, `action_history` and `assets`. A robot with nothing published answers an empty `exposures` list, never a refusal. A robot the caller does not reach — not attached to their app, or attached with a role that grants nothing on it — answers `404` exactly as one that does not exist. The app-user datapoint and camera listings under this prefix stay; this is the one read that also names actions, services, publishers and capabilities, which is what an app needs before it can draw a screen."
+    },
     {
       "method": "GET",
       "path": "/api/robots/:id/config/draft",

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

@@ -0,0 +1,70 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "id": {
+      "type": "string",
+      "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)$",
+      "description": "The robot, and what every robot-scoped route takes as its `:id`."
+    },
+    "name": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 63,
+      "description": "The robot's display name, at most 63 characters. Free text, changed through `PATCH /api/robots/:id`."
+    },
+    "created_at": {
+      "type": "string",
+      "format": "date-time",
+      "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])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
+      "description": "When the robot was created, as an ISO 8601 timestamp."
+    },
+    "bridge_state": {
+      "type": "object",
+      "properties": {
+        "online": {
+          "type": "boolean"
+        },
+        "latency_ms": {
+          "anyOf": [
+            {
+              "type": "number",
+              "minimum": 0
+            },
+            {
+              "type": "null"
+            }
+          ]
+        }
+      },
+      "required": [
+        "online",
+        "latency_ms"
+      ],
+      "additionalProperties": false,
+      "description": "The built-in `bridge_state` datapoint as the cloud observes it right now: whether the bridge is connected, and its latency when it is."
+    },
+    "published_version": {
+      "anyOf": [
+        {
+          "type": "integer",
+          "exclusiveMinimum": 0,
+          "maximum": 9007199254740991
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "The published configuration version, or `null` when nothing has been published yet. A robot with nothing published is still listed — \"not configured yet\" is a real state, and the caller is entitled to it — and its datasheet answers an empty exposure list."
+    }
+  },
+  "required": [
+    "id",
+    "name",
+    "created_at",
+    "bridge_state",
+    "published_version"
+  ],
+  "additionalProperties": false
+}

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

@@ -0,0 +1,83 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "robots": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "string",
+            "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)$",
+            "description": "The robot, and what every robot-scoped route takes as its `:id`."
+          },
+          "name": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 63,
+            "description": "The robot's display name, at most 63 characters. Free text, changed through `PATCH /api/robots/:id`."
+          },
+          "created_at": {
+            "type": "string",
+            "format": "date-time",
+            "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])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
+            "description": "When the robot was created, as an ISO 8601 timestamp."
+          },
+          "bridge_state": {
+            "type": "object",
+            "properties": {
+              "online": {
+                "type": "boolean"
+              },
+              "latency_ms": {
+                "anyOf": [
+                  {
+                    "type": "number",
+                    "minimum": 0
+                  },
+                  {
+                    "type": "null"
+                  }
+                ]
+              }
+            },
+            "required": [
+              "online",
+              "latency_ms"
+            ],
+            "additionalProperties": false,
+            "description": "The built-in `bridge_state` datapoint as the cloud observes it right now: whether the bridge is connected, and its latency when it is."
+          },
+          "published_version": {
+            "anyOf": [
+              {
+                "type": "integer",
+                "exclusiveMinimum": 0,
+                "maximum": 9007199254740991
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "The published configuration version, or `null` when nothing has been published yet. A robot with nothing published is still listed — \"not configured yet\" is a real state, and the caller is entitled to it — and its datasheet answers an empty exposure list."
+          }
+        },
+        "required": [
+          "id",
+          "name",
+          "created_at",
+          "bridge_state",
+          "published_version"
+        ],
+        "additionalProperties": false
+      },
+      "description": "Every robot the caller reaches, in name order with the id as the tiebreak. An app user reaches the robots their app attaches on which their role grants at least one slug or capability; a server key reaches every robot its app attaches; a developer reaches every robot of the organisation."
+    }
+  },
+  "required": [
+    "robots"
+  ],
+  "additionalProperties": false
+}

package/dist/client-robots.d.ts

@@ -0,0 +1,37 @@
+// SPDX-License-Identifier: Apache-2.0
+import { z } from 'zod';
+/**
+ * One robot as `GET /api/client/robots` lists it — the REST twin of the MCP
+ * tool `robots_list`, and the one robot question no robot-scoped route can
+ * answer: which robots may I name at all.
+ *
+ * Deliberately not `robotListItem`: that one carries `exposes`, the per-kind
+ * counts a developer's list shows, which are a configuration fact rather than
+ * something an app user's role grants. What an app user is entitled to is the
+ * robot, its bridge state, and whether anything is published on it yet.
+ */
+export declare const clientRobotListItem: z.ZodObject<{
+    bridge_state: z.ZodObject<{
+        online: z.ZodBoolean;
+        latency_ms: z.ZodNullable<z.ZodNumber>;
+    }, z.core.$strip>;
+    published_version: z.ZodNullable<z.ZodNumber>;
+    id: z.ZodUUID;
+    name: z.ZodString;
+    created_at: z.ZodISODateTime;
+}, z.core.$strip>;
+export type ClientRobotListItem = z.infer<typeof clientRobotListItem>;
+/** What `GET /api/client/robots` answers. Never null: a caller who reaches nothing gets an empty array, and an absent key would make "nothing" and "not answered" the same reading. */
+export declare const clientRobotListResponse: z.ZodObject<{
+    robots: z.ZodArray<z.ZodObject<{
+        bridge_state: z.ZodObject<{
+            online: z.ZodBoolean;
+            latency_ms: z.ZodNullable<z.ZodNumber>;
+        }, z.core.$strip>;
+        published_version: z.ZodNullable<z.ZodNumber>;
+        id: z.ZodUUID;
+        name: z.ZodString;
+        created_at: z.ZodISODateTime;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type ClientRobotListResponse = z.infer<typeof clientRobotListResponse>;

package/dist/client-robots.js

@@ -0,0 +1,30 @@
+// SPDX-License-Identifier: Apache-2.0
+import { z } from 'zod';
+import { bridgeState } from './protocol.js';
+import { robot } from './rest.js';
+/* ------------------------------------------ the robots an app user reaches */
+/**
+ * One robot as `GET /api/client/robots` lists it — the REST twin of the MCP
+ * tool `robots_list`, and the one robot question no robot-scoped route can
+ * answer: which robots may I name at all.
+ *
+ * Deliberately not `robotListItem`: that one carries `exposes`, the per-kind
+ * counts a developer's list shows, which are a configuration fact rather than
+ * something an app user's role grants. What an app user is entitled to is the
+ * robot, its bridge state, and whether anything is published on it yet.
+ */
+export const clientRobotListItem = z.object({
+    ...robot.shape,
+    bridge_state: bridgeState.meta({
+        description: 'The built-in `bridge_state` datapoint as the cloud observes it right now: whether the bridge is connected, and its latency when it is.',
+    }),
+    published_version: z.number().int().positive().nullable().meta({
+        description: 'The published configuration version, or `null` when nothing has been published yet. A robot with nothing published is still listed — "not configured yet" is a real state, and the caller is entitled to it — and its datasheet answers an empty exposure list.',
+    }),
+});
+/** What `GET /api/client/robots` answers. Never null: a caller who reaches nothing gets an empty array, and an absent key would make "nothing" and "not answered" the same reading. */
+export const clientRobotListResponse = z.object({
+    robots: z.array(clientRobotListItem).meta({
+        description: 'Every robot the caller reaches, in name order with the id as the tiebreak. An app user reaches the robots their app attaches on which their role grants at least one slug or capability; a server key reaches every robot its app attaches; a developer reaches every robot of the organisation.',
+    }),
+});

package/dist/index.d.ts

@@ -35,6 +35,8 @@ export { appIdentifier, app, appListResponse, createAppRequest, updateAppRequest
 export type { App, AppListResponse, CreateAppRequest, UpdateAppRequest, ServerKey, ServerKeyListResponse, CreateServerKeyResponse, Role, RoleListResponse, RolePermissions, } from './apps.js';
 export { clientLoginRequest, clientRefreshRequest, clientLogoutRequest, clientRegisterRequest, clientVerifyEmailRequest, clientResendVerificationRequest, clientPasswordResetRequest, clientPasswordResetConfirmRequest, clientAcceptInvitationRequest, CLIENT_OIDC_CALLBACK_PATH, clientProviderListQuery, clientProviderListResponse, clientOidcStartQuery, clientOidcCallbackQuery, clientOidcExchangeRequest, clientOidcErrorCode, clientMcpInteraction, clientMcpInteractionDecisionResponse, mcpConsentGrant, mcpConsentGrantListResponse, clientIdentity, } from './client-auth.js';
 export type { ClientLoginRequest, ClientRefreshRequest, ClientLogoutRequest, ClientRegisterRequest, ClientVerifyEmailRequest, ClientResendVerificationRequest, ClientPasswordResetRequest, ClientPasswordResetConfirmRequest, ClientAcceptInvitationRequest, ClientProviderListQuery, ClientProviderListResponse, ClientOidcStartQuery, ClientOidcCallbackQuery, ClientOidcExchangeRequest, ClientOidcErrorCode, ClientMcpInteraction, ClientMcpInteractionDecisionResponse, McpConsentGrant, McpConsentGrantListResponse, ClientIdentity, } from './client-auth.js';
+export { clientRobotListItem, clientRobotListResponse } from './client-robots.js';
+export type { ClientRobotListItem, ClientRobotListResponse } from './client-robots.js';
 export { APP_USER_DISPLAY_NAME_MAX, APP_URL_PLACEHOLDERS, MAIL_TEMPLATE_VARIABLES, DEFAULT_MAIL_TEMPLATES, providerSlug, appUserStatus, appUser, appUserListResponse, createAppUserRequest, patchAppUserRequest, createAppInvitationRequest, appInvitation, pendingAppInvitation, appInvitationListResponse, appOidcProvider, appOidcProviderListResponse, createAppOidcProviderRequest, patchAppOidcProviderRequest, appUrlTemplate, allowedOrigin, emailDomain, appAuthConfig, putAppAuthConfigRequest, mailTemplateKind, appMailTemplate, appMailTemplateListResponse, putAppMailTemplateRequest, mailTemplatePreviewRequest, mailTemplatePreviewResponse, mailTemplateProblemDetails, mailOutcome, } from './app-users.js';
 export type { AppUserStatus, AppUser, AppUserListResponse, CreateAppUserRequest, PatchAppUserRequest, CreateAppInvitationRequest, AppInvitation, PendingAppInvitation, AppInvitationListResponse, AppOidcProvider, AppOidcProviderListResponse, CreateAppOidcProviderRequest, PatchAppOidcProviderRequest, AppAuthConfig, PutAppAuthConfigRequest, MailTemplateKind, AppMailTemplate, AppMailTemplateListResponse, PutAppMailTemplateRequest, MailTemplatePreviewRequest, MailTemplatePreviewResponse, MailTemplateProblemDetails, MailOutcome, } from './app-users.js';
 export { assetKind, URDF_ASSET_NAME, asset, urdfCompleteness, assetListResponse, missingAssetQuery, assetSyncRequest, assetSyncResponse, assetSyncState, assetSyncStatus, assetFailure, assetFailureKind, assetTooLargeDetails, assetSyncBusyDetails, ASSET_UPLOAD_MAX_BYTES, } from './assets.js';

package/dist/index.js

@@ -40,6 +40,7 @@ mailStatus, tierRequiredDetails, passwordChangeRequest, passwordResetRequest, pa
 authMeResponse, patchOrgRequest, patchAuthMeRequest, } from './identity.js';
 export { appIdentifier, app, appListResponse, createAppRequest, updateAppRequest, serverKeyToken, serverKey, serverKeyListResponse, createServerKeyResponse, role, roleListResponse, rolePermissions, } from './apps.js';
 export { clientLoginRequest, clientRefreshRequest, clientLogoutRequest, clientRegisterRequest, clientVerifyEmailRequest, clientResendVerificationRequest, clientPasswordResetRequest, clientPasswordResetConfirmRequest, clientAcceptInvitationRequest, CLIENT_OIDC_CALLBACK_PATH, clientProviderListQuery, clientProviderListResponse, clientOidcStartQuery, clientOidcCallbackQuery, clientOidcExchangeRequest, clientOidcErrorCode, clientMcpInteraction, clientMcpInteractionDecisionResponse, mcpConsentGrant, mcpConsentGrantListResponse, clientIdentity, } from './client-auth.js';
+export { clientRobotListItem, clientRobotListResponse } from './client-robots.js';
 // The per-app identity space.
 export { APP_USER_DISPLAY_NAME_MAX, APP_URL_PLACEHOLDERS, MAIL_TEMPLATE_VARIABLES, DEFAULT_MAIL_TEMPLATES, providerSlug, appUserStatus, appUser, appUserListResponse, createAppUserRequest, patchAppUserRequest, createAppInvitationRequest, appInvitation, pendingAppInvitation, appInvitationListResponse, appOidcProvider, appOidcProviderListResponse, createAppOidcProviderRequest, patchAppOidcProviderRequest, appUrlTemplate, allowedOrigin, emailDomain, appAuthConfig, putAppAuthConfigRequest, mailTemplateKind, appMailTemplate, appMailTemplateListResponse, putAppMailTemplateRequest, mailTemplatePreviewRequest, mailTemplatePreviewResponse, mailTemplateProblemDetails, mailOutcome, } from './app-users.js';
 export { assetKind, URDF_ASSET_NAME, asset, urdfCompleteness, assetListResponse, missingAssetQuery, assetSyncRequest, assetSyncResponse, assetSyncState, assetSyncStatus, assetFailure, assetFailureKind, assetTooLargeDetails, assetSyncBusyDetails, ASSET_UPLOAD_MAX_BYTES, } from './assets.js';

package/dist/mcp.d.ts

@@ -169,7 +169,12 @@ export declare const mcpCapabilities: z.ZodObject<{
     assets: z.ZodBoolean;
 }, z.core.$strip>;
 export type McpCapabilities = z.infer<typeof mcpCapabilities>;
-/** What one caller may do on one robot — the answer to `robot_describe`. */
+/**
+ * What one caller may do on one robot — the answer to `robot_describe`, and
+ * since 1.1.0 to `GET /api/robots/:id/datasheet` as well. One schema for both
+ * surfaces on purpose: an app and an AI tool read the same description of the
+ * same grant. The `mcp` prefix is history, not scope.
+ */
 export declare const mcpRobotDatasheet: z.ZodObject<{
     robot_id: z.ZodUUID;
     robot_name: z.ZodString;

package/dist/mcp.js

@@ -124,7 +124,12 @@ export const mcpCapabilities = z.object({
     action_history: z.boolean(),
     assets: z.boolean(),
 });
-/** What one caller may do on one robot — the answer to `robot_describe`. */
+/**
+ * What one caller may do on one robot — the answer to `robot_describe`, and
+ * since 1.1.0 to `GET /api/robots/:id/datasheet` as well. One schema for both
+ * surfaces on purpose: an app and an AI tool read the same description of the
+ * same grant. The `mcp` prefix is history, not scope.
+ */
 export const mcpRobotDatasheet = z.object({
     robot_id: z.uuid(),
     robot_name: z.string().min(1).max(200),

package/dist/realtime.d.ts

@@ -254,8 +254,8 @@ export type DatapointEvent = z.infer<typeof datapointEvent>;
  */
 export declare const liveSessionEndReason: z.ZodEnum<{
     unknown: "unknown";
-    robot_offline: "robot_offline";
     publish_failed: "publish_failed";
+    robot_offline: "robot_offline";
     released_by_peer: "released_by_peer";
     config_changed: "config_changed";
     revoked: "revoked";
@@ -285,8 +285,8 @@ export declare const liveSessionEvent: z.ZodObject<{
     state: z.ZodLiteral<"ended">;
     reason: z.ZodEnum<{
         unknown: "unknown";
-        robot_offline: "robot_offline";
         publish_failed: "publish_failed";
+        robot_offline: "robot_offline";
         released_by_peer: "released_by_peer";
         config_changed: "config_changed";
         revoked: "revoked";

package/dist/routes.js

@@ -4,10 +4,11 @@ import { alertListResponse, orgAlertsQuery, orgFiringAlertsResponse } from './al
 import { asset, assetListResponse, assetSyncRequest, assetSyncResponse, assetSyncStatus, missingAssetQuery } from './assets.js';
 import { auditListResponse, auditQuery } from './audit.js';
 import { CLIENT_OIDC_CALLBACK_PATH, clientAcceptInvitationRequest, clientIdentity, clientLoginRequest, clientLogoutRequest, clientMcpInteraction, clientMcpInteractionDecisionResponse, clientOidcCallbackQuery, clientOidcExchangeRequest, clientOidcStartQuery, clientPasswordResetConfirmRequest, clientPasswordResetRequest, clientProviderListQuery, clientProviderListResponse, clientRefreshRequest, clientRegisterRequest, clientResendVerificationRequest, clientVerifyEmailRequest, mcpConsentGrantListResponse, } from './client-auth.js';
+import { clientRobotListResponse } from './client-robots.js';
 import { appAuthConfig, appInvitation, appInvitationListResponse, appMailTemplate, appMailTemplateListResponse, appOidcProvider, appOidcProviderListResponse, appUser, appUserListResponse, createAppInvitationRequest, createAppOidcProviderRequest, createAppUserRequest, mailOutcome, mailTemplatePreviewRequest, mailTemplatePreviewResponse, patchAppOidcProviderRequest, patchAppUserRequest, putAppAuthConfigRequest, putAppMailTemplateRequest, } from './app-users.js';
 import { acceptTeamInviteRequest, authMeResponse, createTeamInviteRequest, fleetlessUser, fleetlessUserListResponse, passwordChangeRequest, passwordResetConfirm, passwordResetRequest, patchAuthMeRequest, patchFleetlessUserRequest, patchOrgRequest, patchOrgResponse, pendingTeamInviteListResponse, refreshRequest, sessionTokens, signUpRequest, signUpResponse, teamInvite, tierChangeRequest, waitlistRequest, } from './identity.js';
 import { jobRunListResponse, jobRunQuery, jobRunSummary, jobRunSummaryQuery } from './jobs.js';
-import { MCP_APP_PATHS, mcpRolePreviewResponse } from './mcp.js';
+import { MCP_APP_PATHS, mcpRobotDatasheet, mcpRolePreviewResponse } from './mcp.js';
 import { authorizationServerMetadata, dynamicClientRegistrationRequest, dynamicClientRegistrationResponse, oauthAuthorizeQuery, oauthRedirectResponse, oauthTokenRequest, oauthTokenResponse, protectedResourceMetadata, } from './oauth.js';
 import { cameraListResponse, cancelRequest, configDraftResponse, configVersionResponse, configVersionsResponse, createRobotRequest, createRobotResponse, datapointListResponse, datapointValue, exposureListResponse, fetchTypesRequest, fetchTypesResponse, historyQuery, historyResponse, introspectionResponse, invokeOrServiceResponse, invokeRequest, jobResponse, liveSessionResponse, orgHealthQuery, orgLatencyQuery, orgLatencyResponse, orgQuotaUsage, orgUsageQuery, orgUsageResponse, patchRobotRequest, patchRobotResponse, publishConfigResponse, publishRequest, putConfigDraftRequest, putRobotDetailsRequest, putRobotDetailsResponse, releaseLiveQuery, renameSlugRequest, renameSlugResponse, robotDeleteQuery, resourceHealthListResponse, robotDeletionSummary, robotDetailResponse, robotJobsResponse, robotListResponse, slugUsageResponse, snapshotMetaResponse, typesResponse, } from './rest.js';
 export const ROUTE_SECTIONS = [
@@ -208,6 +209,14 @@ export const ROUTES = [
             'and splitting them here would tell a stranger which tokens ever existed. No rate limiter: the GET changes nothing, and the POST it ' +
             'leads to is limited per IP.',
     },
+    {
+        method: 'GET', path: '/favicon.svg', section: 'client-auth',
+        summary: 'Serves the Fleetless icon for the auth portal\'s and the MCP welcome page\'s browser tab.',
+        audience: 'internal', auth: 'none', rateLimited: false, ownerTier: false, status: 200,
+        params: [], query: null, request: null, response: null, errors: [], transport: 'http',
+        notes: 'An SVG, not JSON. Those pages carry a Content-Security-Policy that admits no `data:` image, so the icon is a file on their own ' +
+            'origin — the one source `img-src \'self\'` names. Cached for a day: the bytes change when the brand does, not per deploy.',
+    },
     {
         method: 'POST', path: '/api/auth/password/reset/confirm', section: 'developer-auth',
         summary: 'Spends a reset token, sets the new password and ends every session of the account.',
@@ -1750,6 +1759,33 @@ export const ROUTES = [
             '`404 unknown_datapoint` and a configured one with no sample yet is `404 no_data` — three facts a caller who is entitled to them needs ' +
             'told apart. The plane built-ins (`bridge_state`, `robot_details`) answer here too, without appearing in any document.',
     },
+    /* ------------------------------------------ discovery: the REST twins of the two MCP tools a session starts from */
+    {
+        method: 'GET', path: '/api/client/robots', section: 'robots',
+        summary: 'Lists the robots the caller reaches, with bridge state and the published configuration version.',
+        audience: 'client', auth: 'developer_or_client', rateLimited: false, ownerTier: false, status: 200,
+        params: [], query: null, request: null, response: clientRobotListResponse,
+        errors: [...CLIENT_GUARD], transport: 'http',
+        notes: '**The REST twin of the MCP tool `robots_list`**, and the one robot question no robot-scoped route can answer: which robots may I name ' +
+            'at all. An app user sees the robots their app attaches on which their role grants at least one slug or capability; a server key sees ' +
+            'every robot its app attaches; a developer bearer sees the organisation\'s robots. Name order, id as the tiebreak. A robot on which the ' +
+            'role grants nothing is absent rather than listed empty — the same answer `robots_list` gives, for the same reason: reach is a grant, ' +
+            'not an attachment. Under `/api/client/` because it names no robot; every robot-scoped read stays under `/api/robots/:id/…`.',
+    },
+    {
+        method: 'GET', path: '/api/robots/:id/datasheet', section: 'robots',
+        summary: 'Describes everything the caller\'s role lets them do on one robot, with parameter schemas.',
+        audience: 'client', auth: 'developer_or_client', rateLimited: false, ownerTier: false, status: 200,
+        params: [{ name: 'id', description: 'The robot\'s uuid, as `GET /api/client/robots` lists it.' }],
+        query: null, request: null, response: mcpRobotDatasheet,
+        errors: [...CLIENT_GUARD, 'invalid_uuid', 'not_found'], transport: 'http',
+        notes: '**The REST twin of the MCP tool `robot_describe`**: one answer per robot — every datapoint, action, service, publisher and camera the ' +
+            'role grants, each with its `input_schema` where it takes parameters, plus the two capabilities that gate whole features, ' +
+            '`action_history` and `assets`. A robot with nothing published answers an empty `exposures` list, never a refusal. A robot the caller ' +
+            'does not reach — not attached to their app, or attached with a role that grants nothing on it — answers `404` exactly as one that ' +
+            'does not exist. The app-user datapoint and camera listings under this prefix stay; this is the one read that also names actions, ' +
+            'services, publishers and capabilities, which is what an app needs before it can draw a screen.',
+    },
     /* ------------------------------------------------- config (draft/publish) */
     {
         method: 'GET', path: '/api/robots/:id/config/draft', section: 'config',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fleetless/contracts",
-  "version": "1.0.6",
+  "version": "1.1.0",
   "description": "Fleetless wire contracts: the bridge-cloud protocol, the REST API schemas and the error codes, as zod schemas with generated JSON Schema and OpenAPI artifacts.",
   "license": "Apache-2.0",
   "author": "Dehne Robotik GmbH",