@fleetless/contracts 1.0.5 → 1.1.0

package/dist/protocol.js

@@ -10,8 +10,8 @@ import { rosTypeName } from './common.js';
  * Bridge <-> cloud protocol, version 2.
  *
  * The version is exchanged in the hello handshake; the cloud refuses an
- * incompatible bridge with a clear message: `protocol_mismatch`, which names
- * both versions and reaches the robot's detail view as `last_hello_error`.
+ * incompatible bridge: `protocol_mismatch`, which names both versions and
+ * reaches the robot's detail view as `last_hello_error`.
  *
  * **2 (2026-08-21):** `config_applied.errors` entries gained `kind` and `code`
  * beside `message`. The check is `!==`, not a floor, so a bridge that is not
@@ -78,12 +78,11 @@ export { slug } from './common.js';
  *
  * It carries the **slug and the state**, not only the id, because the cloud's
  * reconciliation needs both and had neither. Reading `active_job_ids` as bare
- * uuids, a restarted cloud could answer exactly one question — "is this job
- * still alive?" — for jobs it already knew about. It could not name what the
- * robot is doing, could not tell a job that is still `running` from one that
- * finished while the cloud was down, and had nothing at all to say about a
- * job it never recorded because it crashed between minting the id and writing
- * the row.
+ * uuids, a restarted cloud could only ask "is this job still alive?" for jobs
+ * it already knew about — not what the robot is doing, not whether a
+ * `running` job had actually finished while the cloud was down, and nothing
+ * at all about a job it never recorded because it crashed between minting the
+ * id and writing the row.
  *
  * `state` is the bridge's own current answer, not a history. A bridge that
  * has a terminal result still in hand reports it here and the cloud writes it
@@ -103,22 +102,21 @@ export const bridgeHello = z.object({
     /**
      * Every job this bridge still knows about, right now.
      *
-     * A reconnect and a restart look **identical** on the wire otherwise: same
-     * token, same version, same frame. But they must end differently — after a
-     * dropped connection the running jobs are still running, after a restart
-     * their results are gone forever. Asking the bridge to enumerate what it
-     * still has settles it without either side guessing: the cloud marks every
-     * job it believes is running on this robot and that is *not* named here as
-     * `lost`.
+     * A reconnect and a restart look **identical** on the wire — same token,
+     * same version, same frame — but must end differently: after a dropped
+     * connection the running jobs are still running, after a restart their
+     * results are gone forever. Enumerating what the bridge still has settles
+     * it without either side guessing: the cloud marks every job it believed
+     * running that is *not* named here as `lost`.
      *
-     * This deliberately needs no persistence at the bridge. A live process
-     * lists its live jobs; a process that just started lists none, because it
-     * has none — which is exactly the truth the cloud needs. A breadcrumb file
-     * would only add a window in which the crash beat the write.
+     * Deliberately needs no persistence at the bridge: a live process lists its
+     * live jobs, a process that just started lists none — exactly the truth
+     * the cloud needs. A breadcrumb file would only add a window in which the
+     * crash beat the write.
      *
-     * Defaulted, so a bridge that sends no such field still parses; a bridge
-     * with no jobs and a bridge that does not report them both mean the cloud
-     * has nothing to keep alive.
+     * Defaulted, so a bridge that sends no such field still parses; no jobs
+     * and no report both mean the same thing to the cloud: nothing to keep
+     * alive.
      */
     active_jobs: z.array(activeJob).max(500).default([]),
 });

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/realtime.js

@@ -324,10 +324,10 @@ export const liveSessionEvent = z.object({
     /**
      * **Classified text the cloud produced, never text the robot sent.**
      *
-     * It is **not** the robot's own words. Nothing sanitises
-     * `bridgeCameraState.error.message`, and a camera password reaches a
-     * developer surface through exactly that route — which is why the cloud maps
-     * a robot's diagnosis to fixed strings rather than forwarding it.
+     * Nothing sanitises `bridgeCameraState.error.message`, and a camera
+     * password reaches a developer surface through exactly that route — which
+     * is why the cloud maps a robot's diagnosis to fixed strings rather than
+     * forwarding it.
      *
      * So: `null` unless the cloud itself has something classified to say. If a
      * developer needs the robot's own diagnosis later, it arrives as a mapped

package/dist/rest.js

@@ -23,7 +23,7 @@ export const robot = z.object({
 /** What `PATCH /api/robots/:id` answers: the robot as it now stands. */
 export const patchRobotResponse = z.object({
     robot: robot.meta({
-        description: 'The robot as it now stands, after the patch was applied. The whole resource comes back, not only the fields that changed.',
+        description: 'The robot as it now stands, after the patch. The whole resource comes back, not only the changed fields.',
     }),
 });
 export const createRobotRequest = z.object({
@@ -85,10 +85,10 @@ export const robotListResponse = z.object({
 export const datapointValue = z.object({
     slug: slug.meta({ description: 'The datapoint this value belongs to.' }),
     value: z.unknown().meta({
-        description: 'The value itself, shaped by the datapoint: a number, a boolean, a string, or the whole ROS message where the configuration names no field inside it. Any `scale` and `offset` the configuration declares have already been applied, at the robot.',
+        description: 'The value, shaped by the datapoint: a number, a boolean, a string, or the whole ROS message where the configuration names no field inside it. Any `scale` and `offset` the configuration declares have already been applied, at the robot.',
     }),
     timestamp_ms: z.number().int().nonnegative().meta({
-        description: 'When the value was captured, as a unix timestamp in milliseconds. This is the **bridge\'s capture time**, never the time the cloud received it — the one exception is the built-in `bridge_state`, which the cloud observes by construction.',
+        description: 'When the value was captured, as a unix timestamp in milliseconds. The **bridge\'s capture time**, never the time the cloud received it — the one exception is the built-in `bridge_state`, which the cloud observes by construction.',
     }),
 });
 /* ------------------------------------------------------------------------
@@ -396,7 +396,7 @@ export const invokeResponse = z.object({
 /** A service call answers with its result directly — no job to observe. */
 export const serviceCallResponse = z.object({
     result: z.unknown().meta({
-        description: 'What the service returned, shaped by the ROS service itself. A service call is awaited to completion, so there is no job to observe afterwards and no id to hold on to.',
+        description: 'What the service returned, shaped by the ROS service. A service call is awaited to completion, so there is no job to observe afterwards and no id to hold on to.',
     }),
 });
 /**

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.',
@@ -509,7 +518,7 @@ export const ROUTES = [
         params: [
             { name: 'id', description: 'The app\'s uuid, as returned by `POST /api/apps` or listed by `GET /api/apps`.' },
             { name: 'userId', description: 'The app user\'s uuid, from `GET /api/apps/:id/users`; a user of another app answers `404`.' },
-            { name: 'clientId', description: 'The MCP client, as `GET /api/apps/:id/users/:userId/mcp-grants` reports its `client_id`. Not a uuid — it is the identifier the dynamic registration issued.' },
+            { name: 'clientId', description: 'The MCP client, as `GET /api/apps/:id/users/:userId/mcp-grants` reports its `client_id`. Not a uuid — the identifier dynamic registration issued.' },
         ],
         query: null, request: null, response: null,
         errors: [...DEVELOPER_GUARD, 'invalid_uuid', 'not_found'], transport: 'http',
@@ -1628,7 +1637,7 @@ export const ROUTES = [
         method: 'DELETE', path: '/api/client/mcp/grants/:clientId', section: 'client-auth',
         summary: 'Withdraws the signed-in app user\'s consent to one MCP client.',
         audience: 'client', auth: 'developer_or_client', rateLimited: false, ownerTier: false, status: 204,
-        params: [{ name: 'clientId', description: 'The MCP client, as `GET /api/client/mcp/grants` reports its `client_id`. Not a uuid — it is the identifier the dynamic registration issued.' }],
+        params: [{ name: 'clientId', description: 'The MCP client, as `GET /api/client/mcp/grants` reports its `client_id`. Not a uuid — the identifier dynamic registration issued.' }],
         query: null, request: null, response: null, errors: [...CLIENT_GUARD], transport: 'http',
         notes: 'The person\'s own door, beside the developer\'s `DELETE /api/apps/:id/users/:userId/mcp-grants/:clientId`. It acts on the bearer\'s ' +
             'own account and on no other — the path carries a client and never a subject — so there is no user for a caller to name and none to ' +
@@ -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',
@@ -1946,7 +1982,7 @@ export const ROUTES = [
         audience: 'client', auth: 'developer_or_client', rateLimited: false, ownerTier: false, status: 202,
         params: [
             { name: 'id', description: 'The robot\'s uuid; an end user reaches it through an app that attaches it.' },
-            { name: 'slug', description: 'The action or service slug from the published configuration; the cloud already knows which kind it is.' },
+            { name: 'slug', description: 'The action or service slug from the published configuration — the cloud already knows which kind.' },
         ],
         query: null, request: invokeRequest, response: invokeOrServiceResponse,
         errors: [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fleetless/contracts",
-  "version": "1.0.5",
+  "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",