@fleetless/contracts 1.0.5 → 1.0.6
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +11 -2
- package/CONTRIBUTING.md +100 -75
- package/README.md +69 -83
- package/SECURITY.md +24 -24
- package/artifacts/openapi.json +65 -65
- package/artifacts/routes.json +3 -3
- package/artifacts/schema/app-list-response.schema.json +2 -2
- package/artifacts/schema/app-oidc-provider-list-response.schema.json +1 -1
- package/artifacts/schema/app-oidc-provider.schema.json +1 -1
- package/artifacts/schema/app-user-list-response.schema.json +2 -2
- package/artifacts/schema/app-user.schema.json +2 -2
- package/artifacts/schema/app.schema.json +2 -2
- package/artifacts/schema/asset-list-response.schema.json +7 -7
- package/artifacts/schema/asset-sync-request.schema.json +1 -1
- package/artifacts/schema/asset-sync-status.schema.json +1 -1
- package/artifacts/schema/asset.schema.json +3 -3
- package/artifacts/schema/auth-me-response.schema.json +2 -2
- package/artifacts/schema/auth-ok.schema.json +1 -1
- package/artifacts/schema/authorization-server-metadata.schema.json +1 -1
- package/artifacts/schema/bridge-asset-progress.schema.json +1 -1
- package/artifacts/schema/busy-details.schema.json +3 -3
- package/artifacts/schema/client-identity.schema.json +1 -1
- package/artifacts/schema/client-login-request.schema.json +1 -1
- package/artifacts/schema/client-logout-request.schema.json +1 -1
- package/artifacts/schema/client-mcp-interaction.schema.json +1 -1
- package/artifacts/schema/cloud-config.schema.json +1 -1
- package/artifacts/schema/command-result.schema.json +3 -3
- package/artifacts/schema/config-draft-response.schema.json +1 -1
- package/artifacts/schema/config-version-response.schema.json +1 -1
- package/artifacts/schema/create-server-key-response.schema.json +1 -1
- package/artifacts/schema/datapoint-config.schema.json +1 -1
- package/artifacts/schema/datapoint-value.schema.json +2 -2
- package/artifacts/schema/dynamic-client-registration-request.schema.json +2 -2
- package/artifacts/schema/fleetless-user-list-response.schema.json +2 -2
- package/artifacts/schema/fleetless-user.schema.json +2 -2
- package/artifacts/schema/invoke-or-service-response.schema.json +4 -4
- package/artifacts/schema/invoke-response.schema.json +3 -3
- package/artifacts/schema/job-actor.schema.json +1 -1
- package/artifacts/schema/job-event.schema.json +3 -3
- package/artifacts/schema/job-response.schema.json +3 -3
- package/artifacts/schema/job-run-list-response.schema.json +2 -2
- package/artifacts/schema/job-run.schema.json +2 -2
- package/artifacts/schema/job.schema.json +3 -3
- package/artifacts/schema/mcp-consent-grant-list-response.schema.json +2 -2
- package/artifacts/schema/mcp-consent-grant.schema.json +2 -2
- package/artifacts/schema/oauth-authorize-query.schema.json +1 -1
- package/artifacts/schema/oauth-token-request.schema.json +1 -1
- package/artifacts/schema/patch-org-response.schema.json +1 -1
- package/artifacts/schema/patch-robot-response.schema.json +1 -1
- package/artifacts/schema/robot-config-doc.schema.json +1 -1
- package/artifacts/schema/robot-jobs-response.schema.json +3 -3
- package/artifacts/schema/role-list-response.schema.json +1 -1
- package/artifacts/schema/role.schema.json +1 -1
- package/artifacts/schema/server-key-list-response.schema.json +2 -2
- package/artifacts/schema/server-key.schema.json +1 -1
- package/artifacts/schema/service-call-response.schema.json +1 -1
- package/artifacts/schema/sign-up-response.schema.json +2 -2
- package/artifacts/schema/urdf-completeness.schema.json +2 -2
- package/artifacts/schema-outgoing/bridge-asset-progress.schema.json +1 -1
- package/dist/alerts.d.ts +15 -17
- package/dist/alerts.js +15 -17
- package/dist/app-users.d.ts +5 -6
- package/dist/app-users.js +9 -10
- package/dist/apps.d.ts +5 -6
- package/dist/apps.js +11 -12
- package/dist/assets.js +10 -13
- package/dist/audit.d.ts +10 -12
- package/dist/audit.js +14 -17
- package/dist/client-auth.d.ts +8 -9
- package/dist/client-auth.js +14 -15
- package/dist/config-issues.d.ts +3 -3
- package/dist/config-issues.js +3 -3
- package/dist/config.d.ts +5 -6
- package/dist/config.js +7 -8
- package/dist/errors.d.ts +4 -4
- package/dist/errors.js +8 -9
- package/dist/identity.d.ts +4 -5
- package/dist/identity.js +7 -8
- package/dist/index.d.ts +1 -1
- package/dist/index.js +1 -1
- package/dist/jobs.js +5 -5
- package/dist/mcp.d.ts +5 -8
- package/dist/mcp.js +2 -2
- package/dist/oauth.d.ts +8 -10
- package/dist/oauth.js +13 -15
- package/dist/protocol.d.ts +7 -8
- package/dist/protocol.js +20 -22
- package/dist/realtime.js +4 -4
- package/dist/rest.js +4 -4
- package/dist/routes.js +3 -3
- package/package.json +1 -1
package/dist/jobs.js
CHANGED
|
@@ -21,17 +21,17 @@ import { slug, wireSeqCursor, wireTimestampMs } from './common.js';
|
|
|
21
21
|
export const jobState = z.enum(['running', 'succeeded', 'failed', 'cancelled', 'lost']);
|
|
22
22
|
export const job = z.object({
|
|
23
23
|
id: z.uuid().meta({
|
|
24
|
-
description: 'The job\'s id, minted by the cloud when the invocation is accepted. Informative
|
|
24
|
+
description: 'The job\'s id, minted by the cloud when the invocation is accepted. Informative — state is observed by slug; a cancel names this id to stop one specific job rather than whatever is running.',
|
|
25
25
|
}),
|
|
26
26
|
robot_id: z.uuid().meta({ description: 'The robot this job is running on.' }),
|
|
27
27
|
slug: slug.meta({
|
|
28
28
|
description: 'The action or service this job is running, as the published configuration exposes it. One slug carries one job at a time, so every observer of that slug sees the same one.',
|
|
29
29
|
}),
|
|
30
30
|
state: jobState.meta({
|
|
31
|
-
description: 'Where the job stands: `running`, `succeeded`, `failed`, `cancelled` or `lost`. `lost` is a real outcome — the bridge restarted mid-job and the result is gone —
|
|
31
|
+
description: 'Where the job stands: `running`, `succeeded`, `failed`, `cancelled` or `lost`. `lost` is a real outcome — the bridge restarted mid-job and the result is gone — stated rather than left reading `running` by default.',
|
|
32
32
|
}),
|
|
33
33
|
started_at: z.iso.datetime().meta({
|
|
34
|
-
description: 'When the cloud minted this job, as an ISO 8601 timestamp. For a job adopted from a reconnecting bridge
|
|
34
|
+
description: 'When the cloud minted this job, as an ISO 8601 timestamp. For a job adopted from a reconnecting bridge, this is **adoption time**, not the real start — the cloud never minted it.',
|
|
35
35
|
}),
|
|
36
36
|
updated_at: z.iso.datetime().meta({
|
|
37
37
|
description: 'When this job last changed, as an ISO 8601 timestamp.',
|
|
@@ -176,7 +176,7 @@ export const JOB_RUN_RETENTION_DAYS = 90;
|
|
|
176
176
|
*/
|
|
177
177
|
export const jobActor = z.object({
|
|
178
178
|
kind: z.enum(['developer', 'end_user', 'app_user', 'server_key']).meta({
|
|
179
|
-
description: 'What the caller was acting as: a `developer` in the console, an `app_user` of one app, or a `server_key` used by server-side code. A bridge invokes nothing, so it is deliberately not a case here. `end_user` appears only on runs recorded before app users replaced the organisation-wide user pool —
|
|
179
|
+
description: 'What the caller was acting as: a `developer` in the console, an `app_user` of one app, or a `server_key` used by server-side code. A bridge invokes nothing, so it is deliberately not a case here. `end_user` appears only on runs recorded before app users replaced the organisation-wide user pool — kept so old runs still render; nothing writes it now.',
|
|
180
180
|
}),
|
|
181
181
|
id: z.uuid().meta({
|
|
182
182
|
description: 'The id of the Fleetless user, app user or server key that invoked the run.',
|
|
@@ -200,7 +200,7 @@ export const jobRunKind = z.enum(['action', 'service']);
|
|
|
200
200
|
*/
|
|
201
201
|
export const jobRun = z.object({
|
|
202
202
|
id: z.uuid().meta({
|
|
203
|
-
description: 'The run\'s id
|
|
203
|
+
description: 'The run\'s id — the same id the invocation was answered with, so a caller that kept a job id can find its durable record here later.',
|
|
204
204
|
}),
|
|
205
205
|
robot_id: z.uuid().meta({ description: 'The robot the run happened on.' }),
|
|
206
206
|
slug: slug.meta({
|
package/dist/mcp.d.ts
CHANGED
|
@@ -8,8 +8,8 @@ import { z } from 'zod';
|
|
|
8
8
|
* **This file describes the seam, not the protocol.** The MCP messages
|
|
9
9
|
* themselves (`initialize`, `tools/list`, `tools/call`) are defined by the
|
|
10
10
|
* Model Context Protocol and implemented with its official SDK — writing our
|
|
11
|
-
* own zod copies of them would
|
|
12
|
-
*
|
|
11
|
+
* own zod copies of them would duplicate somebody else's specification, the
|
|
12
|
+
* one thing this package exists to avoid.
|
|
13
13
|
* What lives here is what *Fleetless* decides: which revision we speak, where
|
|
14
14
|
* the endpoint is, how a tool is named, and what the console is shown before
|
|
15
15
|
* an end user ever connects.
|
|
@@ -94,12 +94,9 @@ export declare function mcpAppEndpointPath(appIdentifier: string): string;
|
|
|
94
94
|
* ever fetch. Writing them here is what keeps that reading from being made
|
|
95
95
|
* twice.
|
|
96
96
|
*
|
|
97
|
-
* **These are paths, not URLs.** Append them to `PUBLIC_API_BASE_URL`,
|
|
98
|
-
*
|
|
99
|
-
*
|
|
100
|
-
* string, never against the request's `Host`. The friendly alias is a proxy in
|
|
101
|
-
* front of the same cloud, and a URL built on it hands a client an audience
|
|
102
|
-
* the token endpoint will refuse.
|
|
97
|
+
* **These are paths, not URLs.** Append them to `PUBLIC_API_BASE_URL`, not the
|
|
98
|
+
* friendly `mcp.fleetless.dev` alias — see `mcpAppEndpointPath` for why: a URL
|
|
99
|
+
* built on the alias carries an audience the token endpoint refuses.
|
|
103
100
|
*
|
|
104
101
|
* Named in the shape `OAUTH_PATHS` had, and deliberately a **function** rather
|
|
105
102
|
* than the object that constant was: there is one set of these per app, and a
|
package/dist/mcp.js
CHANGED
|
@@ -9,8 +9,8 @@ import { slug } from './common.js';
|
|
|
9
9
|
* **This file describes the seam, not the protocol.** The MCP messages
|
|
10
10
|
* themselves (`initialize`, `tools/list`, `tools/call`) are defined by the
|
|
11
11
|
* Model Context Protocol and implemented with its official SDK — writing our
|
|
12
|
-
* own zod copies of them would
|
|
13
|
-
*
|
|
12
|
+
* own zod copies of them would duplicate somebody else's specification, the
|
|
13
|
+
* one thing this package exists to avoid.
|
|
14
14
|
* What lives here is what *Fleetless* decides: which revision we speak, where
|
|
15
15
|
* the endpoint is, how a tool is named, and what the console is shown before
|
|
16
16
|
* an end user ever connects.
|
package/dist/oauth.d.ts
CHANGED
|
@@ -14,8 +14,8 @@ import { z } from 'zod';
|
|
|
14
14
|
* and per app for an app's users — and the console's own OAuth portal, which
|
|
15
15
|
* answers `oauthRedirectResponse` at its login and sign-up steps.
|
|
16
16
|
*
|
|
17
|
-
* The client model this file was written to get right
|
|
18
|
-
*
|
|
17
|
+
* The client model this file was written to get right survived the cut
|
|
18
|
+
* intact: an MCP client **registers itself**
|
|
19
19
|
* (RFC 7591) because the person only ever pastes a URL into an AI tool.
|
|
20
20
|
* Nobody vetted it, its redirect URIs arrive from the client itself, and the
|
|
21
21
|
* tools it will call move a physical robot. That is why consent names the
|
|
@@ -37,10 +37,9 @@ import { z } from 'zod';
|
|
|
37
37
|
* app's auth settings — are ordinary console API and use `apiError` with
|
|
38
38
|
* `ERROR_CODES` like everything else.
|
|
39
39
|
*
|
|
40
|
-
* So: **two shapes, split by audience, not by accident.** Written down
|
|
41
|
-
* because
|
|
42
|
-
*
|
|
43
|
-
* there.
|
|
40
|
+
* So: **two shapes, split by audience, not by accident.** Written down
|
|
41
|
+
* because two error formats in one server invite unifying them — which would
|
|
42
|
+
* silently erase the reason the standard one exists.
|
|
44
43
|
*
|
|
45
44
|
* **The split is by audience and the path prefix will mislead you.**
|
|
46
45
|
* `/mcp/oauth/consent` sits under an `/oauth/` segment and is nevertheless an
|
|
@@ -198,10 +197,9 @@ export type DynamicClientRegistrationResponse = z.infer<typeof dynamicClientRegi
|
|
|
198
197
|
* from a client we are about to trust, where an unknown key is a caller
|
|
199
198
|
* assuming a feature into existence, while a token request comes from any
|
|
200
199
|
* RFC-compliant client, which may legitimately send parameters this server
|
|
201
|
-
* does not read. Refusing those would be a conformance bug.
|
|
202
|
-
*
|
|
203
|
-
*
|
|
204
|
-
* an absent one. Assert on the parsed value.
|
|
200
|
+
* does not read. Refusing those would be a conformance bug. Unknown keys are
|
|
201
|
+
* **stripped**, which bit the test for this schema: `safeParse().success`
|
|
202
|
+
* cannot tell a present field from an absent one. Assert on the parsed value.
|
|
205
203
|
*/
|
|
206
204
|
export declare const oauthTokenRequest: z.ZodObject<{
|
|
207
205
|
grant_type: z.ZodLiteral<"authorization_code">;
|
package/dist/oauth.js
CHANGED
|
@@ -14,8 +14,8 @@ import { z } from 'zod';
|
|
|
14
14
|
* and per app for an app's users — and the console's own OAuth portal, which
|
|
15
15
|
* answers `oauthRedirectResponse` at its login and sign-up steps.
|
|
16
16
|
*
|
|
17
|
-
* The client model this file was written to get right
|
|
18
|
-
*
|
|
17
|
+
* The client model this file was written to get right survived the cut
|
|
18
|
+
* intact: an MCP client **registers itself**
|
|
19
19
|
* (RFC 7591) because the person only ever pastes a URL into an AI tool.
|
|
20
20
|
* Nobody vetted it, its redirect URIs arrive from the client itself, and the
|
|
21
21
|
* tools it will call move a physical robot. That is why consent names the
|
|
@@ -37,10 +37,9 @@ import { z } from 'zod';
|
|
|
37
37
|
* app's auth settings — are ordinary console API and use `apiError` with
|
|
38
38
|
* `ERROR_CODES` like everything else.
|
|
39
39
|
*
|
|
40
|
-
* So: **two shapes, split by audience, not by accident.** Written down
|
|
41
|
-
* because
|
|
42
|
-
*
|
|
43
|
-
* there.
|
|
40
|
+
* So: **two shapes, split by audience, not by accident.** Written down
|
|
41
|
+
* because two error formats in one server invite unifying them — which would
|
|
42
|
+
* silently erase the reason the standard one exists.
|
|
44
43
|
*
|
|
45
44
|
* **The split is by audience and the path prefix will mislead you.**
|
|
46
45
|
* `/mcp/oauth/consent` sits under an `/oauth/` segment and is nevertheless an
|
|
@@ -180,10 +179,10 @@ export const MCP_DCR_MAX_REDIRECT_URIS = 5;
|
|
|
180
179
|
export const dynamicClientRegistrationRequest = z
|
|
181
180
|
.object({
|
|
182
181
|
redirect_uris: z.array(redirectUri).min(1).max(MCP_DCR_MAX_REDIRECT_URIS).meta({
|
|
183
|
-
description: `Where the authorization code may be returned, and the one field a registration cannot omit. Each must be an \`https\` URL, or \`http\` on an explicit loopback address for a native app that cannot hold a certificate, and none may carry a fragment.
|
|
182
|
+
description: `Where the authorization code may be returned, and the one field a registration cannot omit. Each must be an \`https\` URL, or \`http\` on an explicit loopback address for a native app that cannot hold a certificate, and none may carry a fragment. Between \`1\` and \`${MCP_DCR_MAX_REDIRECT_URIS}\` of them; duplicates are collapsed rather than counted twice. Matched **exactly** at the authorize step against what was registered here.`,
|
|
184
183
|
}),
|
|
185
184
|
client_name: z.string().min(1).max(200).optional().meta({
|
|
186
|
-
description: 'The name the client calls itself. Optional
|
|
185
|
+
description: 'The name the client calls itself. Optional: RFC 7591 makes every metadata field optional, so a registration without one is recorded under a default name. It is **not** vouched for by Fleetless and must never be rendered as if it were: a self-registered client chooses this string, and one has called itself *"Fleetless Official Helper"*.',
|
|
187
186
|
}),
|
|
188
187
|
token_endpoint_auth_method: z.enum(['none']).optional().meta({
|
|
189
188
|
description: '`none`, RFC 7591\'s value for a public client, and the only value either server registers. Any other value is **refused rather than silently downgraded**: a client that believes it holds a secret and does not has a wrong mental model of its own security. There is no client secret to hold — mandatory PKCE (`S256`) is the defence.',
|
|
@@ -257,10 +256,9 @@ export const dynamicClientRegistrationResponse = z.object({
|
|
|
257
256
|
* from a client we are about to trust, where an unknown key is a caller
|
|
258
257
|
* assuming a feature into existence, while a token request comes from any
|
|
259
258
|
* RFC-compliant client, which may legitimately send parameters this server
|
|
260
|
-
* does not read. Refusing those would be a conformance bug.
|
|
261
|
-
*
|
|
262
|
-
*
|
|
263
|
-
* an absent one. Assert on the parsed value.
|
|
259
|
+
* does not read. Refusing those would be a conformance bug. Unknown keys are
|
|
260
|
+
* **stripped**, which bit the test for this schema: `safeParse().success`
|
|
261
|
+
* cannot tell a present field from an absent one. Assert on the parsed value.
|
|
264
262
|
*/
|
|
265
263
|
export const oauthTokenRequest = z
|
|
266
264
|
.object({
|
|
@@ -280,7 +278,7 @@ export const oauthTokenRequest = z
|
|
|
280
278
|
description: 'The PKCE verifier whose `S256` hash was sent as the challenge at the authorize step. Between `43` and `128` unreserved characters, per RFC 7636 §4.1 — it is compared rather than parsed, so a length nobody checks is a length an attacker chooses. PKCE is mandatory for every client under OAuth 2.1.',
|
|
281
279
|
}),
|
|
282
280
|
resource: z.url().optional().meta({
|
|
283
|
-
description: 'The resource the token is
|
|
281
|
+
description: 'The resource the token is requested for, per RFC 8707. It must match the audience the code was authorized for, or the answer is `invalid_target`; omitted, the code\'s own audience stands. It becomes the token\'s `aud`, and a resource refuses a token whose audience names something else — which is what keeps a token minted for one app out of another app\'s endpoint.',
|
|
284
282
|
}),
|
|
285
283
|
})
|
|
286
284
|
.meta({
|
|
@@ -325,7 +323,7 @@ export const authorizationServerMetadata = z.object({
|
|
|
325
323
|
description: 'The issuer identifier of this authorization server, per RFC 8414 §2. It is what a client checks a token\'s `iss` against.',
|
|
326
324
|
}),
|
|
327
325
|
authorization_endpoint: z.url().meta({
|
|
328
|
-
description: '
|
|
326
|
+
description: 'Where a client sends the user to authorize.',
|
|
329
327
|
}),
|
|
330
328
|
token_endpoint: z.url().meta({
|
|
331
329
|
description: 'The URL where a client exchanges an authorization code, or a refresh token, for tokens.',
|
|
@@ -438,7 +436,7 @@ export const oauthAuthorizeQuery = z
|
|
|
438
436
|
description: 'One of the client\'s registered redirect URIs, compared **exactly** — string equality against the registered list, never a prefix or a host match. Both the shape (`redirectUri`) and the registration are checked, and a failure of either is a `400 invalid_request` with no redirect.',
|
|
439
437
|
}),
|
|
440
438
|
code_challenge: z.string().min(1).meta({
|
|
441
|
-
description: 'The PKCE challenge; the verifier is presented at the token endpoint. Only non-emptiness is checked here — length and alphabet are not — since the verifier is what
|
|
439
|
+
description: 'The PKCE challenge; the verifier is presented at the token endpoint. Only non-emptiness is checked here — length and alphabet are not — since the verifier is what has to match.',
|
|
442
440
|
}),
|
|
443
441
|
code_challenge_method: z.literal('S256').meta({
|
|
444
442
|
description: 'Only `S256`. `plain` is refused: a challenge equal to its verifier defends against nothing.',
|
package/dist/protocol.d.ts
CHANGED
|
@@ -4,8 +4,8 @@ import { z } from 'zod';
|
|
|
4
4
|
* Bridge <-> cloud protocol, version 2.
|
|
5
5
|
*
|
|
6
6
|
* The version is exchanged in the hello handshake; the cloud refuses an
|
|
7
|
-
* incompatible bridge
|
|
8
|
-
*
|
|
7
|
+
* incompatible bridge: `protocol_mismatch`, which names both versions and
|
|
8
|
+
* reaches the robot's detail view as `last_hello_error`.
|
|
9
9
|
*
|
|
10
10
|
* **2 (2026-08-21):** `config_applied.errors` entries gained `kind` and `code`
|
|
11
11
|
* beside `message`. The check is `!==`, not a floor, so a bridge that is not
|
|
@@ -72,12 +72,11 @@ export { slug } from './common.js';
|
|
|
72
72
|
*
|
|
73
73
|
* It carries the **slug and the state**, not only the id, because the cloud's
|
|
74
74
|
* reconciliation needs both and had neither. Reading `active_job_ids` as bare
|
|
75
|
-
* uuids, a restarted cloud could
|
|
76
|
-
*
|
|
77
|
-
*
|
|
78
|
-
*
|
|
79
|
-
*
|
|
80
|
-
* the row.
|
|
75
|
+
* uuids, a restarted cloud could only ask "is this job still alive?" for jobs
|
|
76
|
+
* it already knew about — not what the robot is doing, not whether a
|
|
77
|
+
* `running` job had actually finished while the cloud was down, and nothing
|
|
78
|
+
* at all about a job it never recorded because it crashed between minting the
|
|
79
|
+
* id and writing the row.
|
|
81
80
|
*
|
|
82
81
|
* `state` is the bridge's own current answer, not a history. A bridge that
|
|
83
82
|
* has a terminal result still in hand reports it here and the cloud writes it
|
package/dist/protocol.js
CHANGED
|
@@ -10,8 +10,8 @@ import { rosTypeName } from './common.js';
|
|
|
10
10
|
* Bridge <-> cloud protocol, version 2.
|
|
11
11
|
*
|
|
12
12
|
* The version is exchanged in the hello handshake; the cloud refuses an
|
|
13
|
-
* incompatible bridge
|
|
14
|
-
*
|
|
13
|
+
* incompatible bridge: `protocol_mismatch`, which names both versions and
|
|
14
|
+
* reaches the robot's detail view as `last_hello_error`.
|
|
15
15
|
*
|
|
16
16
|
* **2 (2026-08-21):** `config_applied.errors` entries gained `kind` and `code`
|
|
17
17
|
* beside `message`. The check is `!==`, not a floor, so a bridge that is not
|
|
@@ -78,12 +78,11 @@ export { slug } from './common.js';
|
|
|
78
78
|
*
|
|
79
79
|
* It carries the **slug and the state**, not only the id, because the cloud's
|
|
80
80
|
* reconciliation needs both and had neither. Reading `active_job_ids` as bare
|
|
81
|
-
* uuids, a restarted cloud could
|
|
82
|
-
*
|
|
83
|
-
*
|
|
84
|
-
*
|
|
85
|
-
*
|
|
86
|
-
* the row.
|
|
81
|
+
* uuids, a restarted cloud could only ask "is this job still alive?" for jobs
|
|
82
|
+
* it already knew about — not what the robot is doing, not whether a
|
|
83
|
+
* `running` job had actually finished while the cloud was down, and nothing
|
|
84
|
+
* at all about a job it never recorded because it crashed between minting the
|
|
85
|
+
* id and writing the row.
|
|
87
86
|
*
|
|
88
87
|
* `state` is the bridge's own current answer, not a history. A bridge that
|
|
89
88
|
* has a terminal result still in hand reports it here and the cloud writes it
|
|
@@ -103,22 +102,21 @@ export const bridgeHello = z.object({
|
|
|
103
102
|
/**
|
|
104
103
|
* Every job this bridge still knows about, right now.
|
|
105
104
|
*
|
|
106
|
-
* A reconnect and a restart look **identical** on the wire
|
|
107
|
-
*
|
|
108
|
-
*
|
|
109
|
-
*
|
|
110
|
-
*
|
|
111
|
-
*
|
|
112
|
-
* `lost`.
|
|
105
|
+
* A reconnect and a restart look **identical** on the wire — same token,
|
|
106
|
+
* same version, same frame — but must end differently: after a dropped
|
|
107
|
+
* connection the running jobs are still running, after a restart their
|
|
108
|
+
* results are gone forever. Enumerating what the bridge still has settles
|
|
109
|
+
* it without either side guessing: the cloud marks every job it believed
|
|
110
|
+
* running that is *not* named here as `lost`.
|
|
113
111
|
*
|
|
114
|
-
*
|
|
115
|
-
*
|
|
116
|
-
*
|
|
117
|
-
*
|
|
112
|
+
* Deliberately needs no persistence at the bridge: a live process lists its
|
|
113
|
+
* live jobs, a process that just started lists none — exactly the truth
|
|
114
|
+
* the cloud needs. A breadcrumb file would only add a window in which the
|
|
115
|
+
* crash beat the write.
|
|
118
116
|
*
|
|
119
|
-
* Defaulted, so a bridge that sends no such field still parses;
|
|
120
|
-
*
|
|
121
|
-
*
|
|
117
|
+
* Defaulted, so a bridge that sends no such field still parses; no jobs
|
|
118
|
+
* and no report both mean the same thing to the cloud: nothing to keep
|
|
119
|
+
* alive.
|
|
122
120
|
*/
|
|
123
121
|
active_jobs: z.array(activeJob).max(500).default([]),
|
|
124
122
|
});
|
package/dist/realtime.js
CHANGED
|
@@ -324,10 +324,10 @@ export const liveSessionEvent = z.object({
|
|
|
324
324
|
/**
|
|
325
325
|
* **Classified text the cloud produced, never text the robot sent.**
|
|
326
326
|
*
|
|
327
|
-
*
|
|
328
|
-
*
|
|
329
|
-
*
|
|
330
|
-
*
|
|
327
|
+
* Nothing sanitises `bridgeCameraState.error.message`, and a camera
|
|
328
|
+
* password reaches a developer surface through exactly that route — which
|
|
329
|
+
* is why the cloud maps a robot's diagnosis to fixed strings rather than
|
|
330
|
+
* forwarding it.
|
|
331
331
|
*
|
|
332
332
|
* So: `null` unless the cloud itself has something classified to say. If a
|
|
333
333
|
* developer needs the robot's own diagnosis later, it arrives as a mapped
|
package/dist/rest.js
CHANGED
|
@@ -23,7 +23,7 @@ export const robot = z.object({
|
|
|
23
23
|
/** What `PATCH /api/robots/:id` answers: the robot as it now stands. */
|
|
24
24
|
export const patchRobotResponse = z.object({
|
|
25
25
|
robot: robot.meta({
|
|
26
|
-
description: 'The robot as it now stands, after the patch
|
|
26
|
+
description: 'The robot as it now stands, after the patch. The whole resource comes back, not only the changed fields.',
|
|
27
27
|
}),
|
|
28
28
|
});
|
|
29
29
|
export const createRobotRequest = z.object({
|
|
@@ -85,10 +85,10 @@ export const robotListResponse = z.object({
|
|
|
85
85
|
export const datapointValue = z.object({
|
|
86
86
|
slug: slug.meta({ description: 'The datapoint this value belongs to.' }),
|
|
87
87
|
value: z.unknown().meta({
|
|
88
|
-
description: 'The value
|
|
88
|
+
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.',
|
|
89
89
|
}),
|
|
90
90
|
timestamp_ms: z.number().int().nonnegative().meta({
|
|
91
|
-
description: 'When the value was captured, as a unix timestamp in milliseconds.
|
|
91
|
+
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.',
|
|
92
92
|
}),
|
|
93
93
|
});
|
|
94
94
|
/* ------------------------------------------------------------------------
|
|
@@ -396,7 +396,7 @@ export const invokeResponse = z.object({
|
|
|
396
396
|
/** A service call answers with its result directly — no job to observe. */
|
|
397
397
|
export const serviceCallResponse = z.object({
|
|
398
398
|
result: z.unknown().meta({
|
|
399
|
-
description: 'What the service returned, shaped by the ROS service
|
|
399
|
+
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.',
|
|
400
400
|
}),
|
|
401
401
|
});
|
|
402
402
|
/**
|
package/dist/routes.js
CHANGED
|
@@ -509,7 +509,7 @@ export const ROUTES = [
|
|
|
509
509
|
params: [
|
|
510
510
|
{ name: 'id', description: 'The app\'s uuid, as returned by `POST /api/apps` or listed by `GET /api/apps`.' },
|
|
511
511
|
{ name: 'userId', description: 'The app user\'s uuid, from `GET /api/apps/:id/users`; a user of another app answers `404`.' },
|
|
512
|
-
{ name: 'clientId', description: 'The MCP client, as `GET /api/apps/:id/users/:userId/mcp-grants` reports its `client_id`. Not a uuid —
|
|
512
|
+
{ 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.' },
|
|
513
513
|
],
|
|
514
514
|
query: null, request: null, response: null,
|
|
515
515
|
errors: [...DEVELOPER_GUARD, 'invalid_uuid', 'not_found'], transport: 'http',
|
|
@@ -1628,7 +1628,7 @@ export const ROUTES = [
|
|
|
1628
1628
|
method: 'DELETE', path: '/api/client/mcp/grants/:clientId', section: 'client-auth',
|
|
1629
1629
|
summary: 'Withdraws the signed-in app user\'s consent to one MCP client.',
|
|
1630
1630
|
audience: 'client', auth: 'developer_or_client', rateLimited: false, ownerTier: false, status: 204,
|
|
1631
|
-
params: [{ name: 'clientId', description: 'The MCP client, as `GET /api/client/mcp/grants` reports its `client_id`. Not a uuid —
|
|
1631
|
+
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.' }],
|
|
1632
1632
|
query: null, request: null, response: null, errors: [...CLIENT_GUARD], transport: 'http',
|
|
1633
1633
|
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 ' +
|
|
1634
1634
|
'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 ' +
|
|
@@ -1946,7 +1946,7 @@ export const ROUTES = [
|
|
|
1946
1946
|
audience: 'client', auth: 'developer_or_client', rateLimited: false, ownerTier: false, status: 202,
|
|
1947
1947
|
params: [
|
|
1948
1948
|
{ name: 'id', description: 'The robot\'s uuid; an end user reaches it through an app that attaches it.' },
|
|
1949
|
-
{ name: 'slug', description: 'The action or service slug from the published configuration
|
|
1949
|
+
{ name: 'slug', description: 'The action or service slug from the published configuration — the cloud already knows which kind.' },
|
|
1950
1950
|
],
|
|
1951
1951
|
query: null, request: invokeRequest, response: invokeOrServiceResponse,
|
|
1952
1952
|
errors: [
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@fleetless/contracts",
|
|
3
|
-
"version": "1.0.
|
|
3
|
+
"version": "1.0.6",
|
|
4
4
|
"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.",
|
|
5
5
|
"license": "Apache-2.0",
|
|
6
6
|
"author": "Dehne Robotik GmbH",
|