@fleetless/contracts 1.2.0 → 2.0.0

package/dist/routes.js

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: Apache-2.0
 import { appListResponse, createAppRequest, createServerKeyResponse, app as appSchema, role, roleListResponse, rolePermissions, serverKeyListResponse, updateAppRequest, } from './apps.js';
 import { alertListResponse, orgAlertsQuery, orgFiringAlertsResponse } from './alerts.js';
-import { asset, assetListResponse, assetSyncRequest, assetSyncResponse, assetSyncStatus, missingAssetQuery } from './assets.js';
+import { asset, assetListResponse, assetsClearResponse, 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';
@@ -10,7 +10,7 @@ import { acceptTeamInviteRequest, authMeResponse, createTeamInviteRequest, fleet
 import { jobRunListResponse, jobRunQuery, jobRunSummary, jobRunSummaryQuery } from './jobs.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';
+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, robotTokenRotateResponse, jointStatePutRequest, jointStatePutResponse, releaseLiveQuery, renameSlugRequest, renameSlugResponse, robotDeleteQuery, resourceHealthListResponse, robotDeletionSummary, robotDetailResponse, robotJobsResponse, robotListResponse, slugUsageResponse, snapshotMetaResponse, typesResponse, } from './rest.js';
 export const ROUTE_SECTIONS = [
     { id: 'health', title: 'Health' },
     { id: 'developer-auth', title: 'Developer auth' },
@@ -1664,6 +1664,40 @@ export const ROUTES = [
             'and the event carries no `details`, because the one interesting value here is the token. `max_robots` is checked before anything is ' +
             'created, which is only safe because robot deletion exists.',
     },
+    {
+        method: 'POST', path: '/api/robots/:id/token/rotate', section: 'robots',
+        summary: 'Mints a new bridge token for the robot and invalidates the old one.',
+        audience: 'developer', auth: 'developer', rateLimited: false, ownerTier: true, status: 201,
+        params: [{ name: 'id', description: 'The robot\'s uuid, as returned by `POST /api/robots` or listed by `GET /api/robots`.' }],
+        query: null, request: null, response: robotTokenRotateResponse,
+        errors: [...DEVELOPER_GUARD, 'tier_required', 'invalid_uuid', 'not_found'], transport: 'http',
+        notes: 'Owner tier, behind the org-scoped lookup, so a developer-tier admin sees the `404` a stranger would for a robot outside their org rather ' +
+            'than a tier refusal that confirms the id exists. `token` is the only moment the new secret exists outside the caller\'s hands — the cloud ' +
+            'stores a hash — so a caller who loses it rotates again. Audited as `robot.token_rotated`, with no `details`: the one interesting value ' +
+            'here is the token. \n\n**It stops the bridge that is connected right now.** The old secret is gone the instant the hash is replaced, so ' +
+            'the cloud closes that socket with `CLOSE_TOKEN_ROTATED` rather than leaving a bridge speaking on a credential nothing would accept ' +
+            'again. A bridge that does not know the code reconnects and is refused at hello as `invalid_token`, which is the honest answer and ends ' +
+            'the same way. **The robot is offline until somebody puts the new token on it** — this is a deliberate interruption, not a background ' +
+            'rekey, and a fleet cannot be rotated without a visit to each robot.',
+    },
+    {
+        method: 'PUT', path: '/api/robots/:id/urdf/joint-state', section: 'robots',
+        summary: 'Chooses the datapoint whose joint positions move the robot\'s URDF, or clears it.',
+        audience: 'developer', auth: 'developer', rateLimited: false, ownerTier: false, status: 200,
+        params: [{ name: 'id', description: 'The robot\'s uuid, as returned by `POST /api/robots` or listed by `GET /api/robots`.' }],
+        query: null, request: jointStatePutRequest, response: jointStatePutResponse,
+        errors: [...DEVELOPER_GUARD, 'invalid_uuid', 'not_found', 'validation_error'], transport: 'http',
+        notes: '**What qualifies**: a datapoint of the **published** configuration whose ROS type is `sensor_msgs/msg/JointState` and which carries no ' +
+            '`field` — the whole message, because positions and names arrive together and a single extracted field is half of a pose. Anything else ' +
+            'is a `validation_error` naming that rule rather than a stored mapping that renders a battery reading as a robot. `{ "slug": null }` ' +
+            'clears it, which is why the field is required and nullable rather than optional. \n\n**The mapping cannot outlive what it points at.** ' +
+            'Every successful publish re-checks it against the new document and clears it when it no longer qualifies, recording ' +
+            '`robot.joint_state_cleared` with the version that did it; a slug rename rewrites it like every other reference the editor already ' +
+            'rewrites; deleting the robot takes it along. Every write through this route — a slug or `null` — is on the record too, as ' +
+            '`robot.joint_state_set` with the actor and the slug, so a clear a person made is never mistaken for one a publish made. The stored ' +
+            'value reads back on `GET /api/robots/:id/assets` as `joint_state_slug`, so a renderer fetches the URDF, the meshes and the mapping ' +
+            'from one place.',
+    },
     {
         method: 'GET', path: '/api/robots', section: 'robots',
         summary: "Lists the org's robots with their connection state and exposure counts.",
@@ -2233,6 +2267,20 @@ export const ROUTES = [
         notes: 'Developer sessions only, like starting a sync: the guard admits three caller kinds and the handler answers `401 unauthorized` to the ' +
             'other two. A sync belonging to another robot reads exactly like one that never existed, which is why the robot is resolved first.',
     },
+    {
+        method: 'DELETE', path: '/api/robots/:id/assets', section: 'assets',
+        summary: "Empties a robot's asset store: every URDF, mesh and texture, gone at once.",
+        audience: 'client', auth: 'developer_or_client', rateLimited: false, ownerTier: true, status: 200,
+        params: [{ name: 'id', description: 'The robot\'s uuid, as returned by `POST /api/robots` or listed by `GET /api/robots`.' }],
+        query: null, request: null, response: assetsClearResponse,
+        errors: [...CLIENT_GUARD, 'tier_required', 'invalid_uuid', 'not_found', 'busy'], transport: 'http',
+        notes: 'The store\'s escape hatch: a full store is never a dead end, and this is the blunt third of the three answers to it — the URDF upload ' +
+            'is exempt from the gate, reconcile after a sync already frees what the new URDF stopped referencing, and this route lets an Owner clear ' +
+            'the robot outright. Owner tier, unconditionally, like starting a sync. Removes every asset of the robot and resets its store to `0`; ' +
+            "the next sync fills it again. It does not touch the bridge's availability report — `urdf_available` still answers from the connected " +
+            'robot, unrelated to what this cloud happens to have stored. A clear while a sync is running is `409 busy` naming that sync\'s ' +
+            'details, the same refusal starting a second sync gets, because deleting under a running upload would leave the store counter wrong.',
+    },
     /* ------------------------------------------------ org (quotas and fleet reads) */
     {
         method: 'GET', path: '/api/org/quotas', section: 'org',
@@ -2306,15 +2354,16 @@ export const ROUTES = [
         summary: 'Takes one asset file from a robot during a sync.',
         audience: 'internal', auth: 'robot_upload', rateLimited: false, ownerTier: false, status: 201,
         params: [], query: null, request: null, response: asset,
-        errors: ['unauthorized', 'rate_limited', 'asset_too_large', 'validation_error', 'not_found', 'quota_exceeded', 'bad_request'], transport: 'http',
+        errors: ['unauthorized', 'rate_limited', 'validation_error', 'not_found', 'quota_exceeded', 'bad_request'], transport: 'http',
         notes: 'The body is the **raw file bytes**, not JSON, so it has no request schema; everything about the file — its kind, its name, its sync id ' +
             'and its announced size — rides in the `x-fleetless-asset-*` headers `ASSET_UPLOAD_HEADERS` names. The credential is a short-lived ' +
             'upload token minted by `POST /api/robots/:id/assets/sync`, verified in a `preParsing` hook so a refusal precedes the work rather than ' +
-            'following it: a `preHandler` would already have buffered the whole file. The announced size is refused there too, before a single byte ' +
-            'is read — it is an announcement and not a proof, so it only ever rejects early and never accepts early, and a body that lies small is ' +
-            'still caught by the real length check. Past both, the server\'s own body limit answers a bare `413 bad_request` with neither ceiling nor ' +
-            'size in it. Rate limited per robot inside that same hook, which is why `rateLimited` is `false`: there is no rate-limiting preHandler ' +
-            'registered on this route.',
+            'following it: a `preHandler` would already have buffered the whole file. **Nothing is refused for its own size** — the robot\'s asset ' +
+            'store is the only limit, so the announced size is checked there against `ROBOT_ASSET_STORE_BYTES` and a file with no room left answers ' +
+            '`409 quota_exceeded` carrying `store_bytes`, `used_bytes` and `size_bytes`, while the sync carries on with the next file. Past that, ' +
+            'the server\'s own body limit answers a bare `413 bad_request` with none of those numbers in it. Rate limited per robot inside that same ' +
+            'hook, which is why `rateLimited` is `false`: there is no rate-limiting preHandler registered on this route. The URDF itself is never ' +
+            'refused for the store; only meshes and textures are charged against it.',
     },
     /* ------------------------------------ realtime and bridge transports */
     {

package/package.json

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

package/artifacts/schema/bridge-pressure.schema.json

@@ -1,292 +0,0 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "type": "object",
-  "properties": {
-    "link": {
-      "type": "object",
-      "properties": {
-        "rate_bps": {
-          "anyOf": [
-            {
-              "type": "number",
-              "minimum": 0
-            },
-            {
-              "type": "null"
-            }
-          ]
-        },
-        "snapshot_max_bytes": {
-          "type": "integer",
-          "minimum": 0,
-          "maximum": 9007199254740991
-        }
-      },
-      "required": [
-        "rate_bps",
-        "snapshot_max_bytes"
-      ]
-    },
-    "tiers": {
-      "type": "object",
-      "properties": {
-        "0": {
-          "type": "object",
-          "properties": {
-            "sent": {
-              "type": "integer",
-              "minimum": 0,
-              "maximum": 9007199254740991
-            },
-            "bytes": {
-              "type": "integer",
-              "minimum": 0,
-              "maximum": 9007199254740991
-            },
-            "drops": {
-              "type": "integer",
-              "minimum": 0,
-              "maximum": 9007199254740991
-            },
-            "high_water": {
-              "type": "integer",
-              "minimum": 0,
-              "maximum": 9007199254740991
-            }
-          },
-          "required": [
-            "sent",
-            "bytes",
-            "drops",
-            "high_water"
-          ]
-        },
-        "1": {
-          "type": "object",
-          "properties": {
-            "sent": {
-              "type": "integer",
-              "minimum": 0,
-              "maximum": 9007199254740991
-            },
-            "bytes": {
-              "type": "integer",
-              "minimum": 0,
-              "maximum": 9007199254740991
-            },
-            "drops": {
-              "type": "integer",
-              "minimum": 0,
-              "maximum": 9007199254740991
-            },
-            "high_water": {
-              "type": "integer",
-              "minimum": 0,
-              "maximum": 9007199254740991
-            }
-          },
-          "required": [
-            "sent",
-            "bytes",
-            "drops",
-            "high_water"
-          ]
-        },
-        "2": {
-          "type": "object",
-          "properties": {
-            "sent": {
-              "type": "integer",
-              "minimum": 0,
-              "maximum": 9007199254740991
-            },
-            "bytes": {
-              "type": "integer",
-              "minimum": 0,
-              "maximum": 9007199254740991
-            },
-            "drops": {
-              "type": "integer",
-              "minimum": 0,
-              "maximum": 9007199254740991
-            },
-            "high_water": {
-              "type": "integer",
-              "minimum": 0,
-              "maximum": 9007199254740991
-            }
-          },
-          "required": [
-            "sent",
-            "bytes",
-            "drops",
-            "high_water"
-          ]
-        },
-        "3": {
-          "type": "object",
-          "properties": {
-            "sent": {
-              "type": "integer",
-              "minimum": 0,
-              "maximum": 9007199254740991
-            },
-            "bytes": {
-              "type": "integer",
-              "minimum": 0,
-              "maximum": 9007199254740991
-            },
-            "drops": {
-              "type": "integer",
-              "minimum": 0,
-              "maximum": 9007199254740991
-            },
-            "high_water": {
-              "type": "integer",
-              "minimum": 0,
-              "maximum": 9007199254740991
-            }
-          },
-          "required": [
-            "sent",
-            "bytes",
-            "drops",
-            "high_water"
-          ]
-        },
-        "4": {
-          "type": "object",
-          "properties": {
-            "sent": {
-              "type": "integer",
-              "minimum": 0,
-              "maximum": 9007199254740991
-            },
-            "bytes": {
-              "type": "integer",
-              "minimum": 0,
-              "maximum": 9007199254740991
-            },
-            "drops": {
-              "type": "integer",
-              "minimum": 0,
-              "maximum": 9007199254740991
-            },
-            "high_water": {
-              "type": "integer",
-              "minimum": 0,
-              "maximum": 9007199254740991
-            }
-          },
-          "required": [
-            "sent",
-            "bytes",
-            "drops",
-            "high_water"
-          ]
-        },
-        "5": {
-          "type": "object",
-          "properties": {
-            "sent": {
-              "type": "integer",
-              "minimum": 0,
-              "maximum": 9007199254740991
-            },
-            "bytes": {
-              "type": "integer",
-              "minimum": 0,
-              "maximum": 9007199254740991
-            },
-            "drops": {
-              "type": "integer",
-              "minimum": 0,
-              "maximum": 9007199254740991
-            },
-            "high_water": {
-              "type": "integer",
-              "minimum": 0,
-              "maximum": 9007199254740991
-            }
-          },
-          "required": [
-            "sent",
-            "bytes",
-            "drops",
-            "high_water"
-          ]
-        }
-      },
-      "additionalProperties": false
-    },
-    "video": {
-      "type": "object",
-      "properties": {
-        "active_streams": {
-          "type": "integer",
-          "minimum": 0,
-          "maximum": 9007199254740991
-        },
-        "bitrate_sum_kbps": {
-          "type": "integer",
-          "minimum": 0,
-          "maximum": 9007199254740991
-        },
-        "uplink_kbps": {
-          "anyOf": [
-            {
-              "type": "integer",
-              "minimum": 0,
-              "maximum": 9007199254740991
-            },
-            {
-              "type": "null"
-            }
-          ]
-        },
-        "override_kbps": {
-          "anyOf": [
-            {
-              "type": "integer",
-              "minimum": 0,
-              "maximum": 9007199254740991
-            },
-            {
-              "type": "null"
-            }
-          ]
-        },
-        "video_budget_kbps": {
-          "anyOf": [
-            {
-              "type": "integer",
-              "minimum": 0,
-              "maximum": 9007199254740991
-            },
-            {
-              "type": "null"
-            }
-          ]
-        },
-        "reserve_kbps": {
-          "type": "integer",
-          "minimum": 0,
-          "maximum": 9007199254740991
-        }
-      },
-      "required": [
-        "active_streams",
-        "bitrate_sum_kbps",
-        "uplink_kbps",
-        "override_kbps",
-        "video_budget_kbps",
-        "reserve_kbps"
-      ]
-    }
-  },
-  "required": [
-    "link",
-    "tiers",
-    "video"
-  ]
-}