@fleetless/sdk 3.0.1 → 3.0.3

package/dist/index.cjs

@@ -144,7 +144,7 @@ var HttpClient = class {
    * RequestOptionsFor<P>` would type-check by construction — the cast
    * bypasses the very check this exists to add, which is the identical
    * "special case that quietly exempts calls from the general rule" shape
-   * this file has already been caught by once. Every current call site to a route
+   * this file has already made once. Every current call site to a route
    * with no body already passes `{}` explicitly for exactly this reason.
    */
   async request(path, options) {
@@ -334,7 +334,7 @@ function createAssetsApi(http) {
           finish(
             null,
             new Error(
-              `createMeshLoader and prepareUrdfScene were both installed on the same LoadingManager for robot ${robotId}. Use one or the other on a given manager, not both \u2014 see the README.`
+              `createMeshLoader and prepareUrdfScene were both installed on the same LoadingManager for robot ${robotId}. Use one or the other on a given manager, not both \u2014 see the SDK reference.`
             )
           );
           return;
@@ -441,7 +441,7 @@ function createAssetsApi(http) {
   };
 }
 
-// node_modules/.pnpm/@fleetless+contracts@1.0.4/node_modules/@fleetless/contracts/dist/common.js
+// node_modules/.pnpm/@fleetless+contracts@1.0.5/node_modules/@fleetless/contracts/dist/common.js
 var import_zod = require("zod");
 var SLUG_RULE = "A name is lower-case: it starts with a letter, continues with letters and digits, and joins further words with a single underscore \u2014 `battery_voltage`. Capitals, dashes, dots, spaces, a leading digit and a doubled or trailing underscore are all refused.";
 var slug = import_zod.z.string().min(2).max(63).regex(/^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$/, SLUG_RULE);
@@ -465,7 +465,7 @@ var applyError = import_zod.z.object({
   details: import_zod.z.record(import_zod.z.string(), import_zod.z.unknown()).optional()
 });
 
-// node_modules/.pnpm/@fleetless+contracts@1.0.4/node_modules/@fleetless/contracts/dist/mcp.js
+// node_modules/.pnpm/@fleetless+contracts@1.0.5/node_modules/@fleetless/contracts/dist/mcp.js
 var import_zod2 = require("zod");
 function mcpAppEndpointPath(appIdentifier2) {
   return `/mcp/${appIdentifier2}`;
@@ -514,10 +514,10 @@ var mcpRolePreviewResponse = import_zod2.z.object({
 });
 var MCP_ASSET_LINK_TTL_MS = 15 * 60 * 1e3;
 
-// node_modules/.pnpm/@fleetless+contracts@1.0.4/node_modules/@fleetless/contracts/dist/protocol.js
+// node_modules/.pnpm/@fleetless+contracts@1.0.5/node_modules/@fleetless/contracts/dist/protocol.js
 var import_zod8 = require("zod");
 
-// node_modules/.pnpm/@fleetless+contracts@1.0.4/node_modules/@fleetless/contracts/dist/assets.js
+// node_modules/.pnpm/@fleetless+contracts@1.0.5/node_modules/@fleetless/contracts/dist/assets.js
 var import_zod3 = require("zod");
 var assetKind = import_zod3.z.enum(["urdf", "mesh", "texture", "other"]);
 var asset = import_zod3.z.object({
@@ -775,10 +775,10 @@ var assetSyncBusyDetails = import_zod3.z.object({
   started_at_ms: import_zod3.z.number().int().nonnegative()
 });
 
-// node_modules/.pnpm/@fleetless+contracts@1.0.4/node_modules/@fleetless/contracts/dist/config.js
+// node_modules/.pnpm/@fleetless+contracts@1.0.5/node_modules/@fleetless/contracts/dist/config.js
 var import_zod5 = require("zod");
 
-// node_modules/.pnpm/@fleetless+contracts@1.0.4/node_modules/@fleetless/contracts/dist/alerts.js
+// node_modules/.pnpm/@fleetless+contracts@1.0.5/node_modules/@fleetless/contracts/dist/alerts.js
 var import_zod4 = require("zod");
 var alertRowCondition = import_zod4.z.discriminatedUnion("kind", [
   import_zod4.z.strictObject({
@@ -848,7 +848,7 @@ var putDatapointDisplayRequest = import_zod4.z.object({
   y_max: import_zod4.z.number().finite().nullable()
 }).strict();
 
-// node_modules/.pnpm/@fleetless+contracts@1.0.4/node_modules/@fleetless/contracts/dist/config.js
+// node_modules/.pnpm/@fleetless+contracts@1.0.5/node_modules/@fleetless/contracts/dist/config.js
 var RTSP_URL_RULE = "The URL has to begin with `rtsp://` or `rtsps://` \u2014 `rtsp://cam-1.plant.local/stream1`. No other scheme is accepted: the bridge opens this with a library that would equally honour `file:`.";
 var MJPEG_URL_RULE = "The URL has to begin with `http://` or `https://` \u2014 `http://cam-1.plant.local/video.mjpg`. No other scheme is accepted: the bridge opens this with a library that would equally serve `file:`.";
 var DEVICE_PATH_RULE = "A capture device is a path under `/dev/`, and the character straight after it is a letter or a digit \u2014 `/dev/video0`, or a stable `/dev/v4l/by-id/...` symlink. Nothing outside `/dev/` is accepted: the string reaches OpenCV, which would as happily open an ordinary file.";
@@ -1895,7 +1895,7 @@ var configState = import_zod5.z.object({
   applied_errors: import_zod5.z.array(applyError).nullable()
 });
 
-// node_modules/.pnpm/@fleetless+contracts@1.0.4/node_modules/@fleetless/contracts/dist/introspection.js
+// node_modules/.pnpm/@fleetless+contracts@1.0.5/node_modules/@fleetless/contracts/dist/introspection.js
 var import_zod6 = require("zod");
 var rosGraphEntry = import_zod6.z.object({
   name: rosName,
@@ -1934,7 +1934,7 @@ var typeDefinition = import_zod6.z.discriminatedUnion("kind", [
   })
 ]);
 
-// node_modules/.pnpm/@fleetless+contracts@1.0.4/node_modules/@fleetless/contracts/dist/jobs.js
+// node_modules/.pnpm/@fleetless+contracts@1.0.5/node_modules/@fleetless/contracts/dist/jobs.js
 var import_zod7 = require("zod");
 var jobState = import_zod7.z.enum(["running", "succeeded", "failed", "cancelled", "lost"]);
 var job = import_zod7.z.object({
@@ -2152,7 +2152,7 @@ var jobRunSummary = import_zod7.z.object({
   since_ms: import_zod7.z.number().int().nonnegative()
 });
 
-// node_modules/.pnpm/@fleetless+contracts@1.0.4/node_modules/@fleetless/contracts/dist/protocol.js
+// node_modules/.pnpm/@fleetless+contracts@1.0.5/node_modules/@fleetless/contracts/dist/protocol.js
 var MAX_PATIENCE_MS = 12e4;
 var MIN_PATIENCE_MS = 1e3;
 var activeJob = import_zod8.z.object({
@@ -2551,11 +2551,11 @@ var bridgeCameraState = import_zod8.z.object({
   request_id: import_zod8.z.string().min(1).max(64).nullable()
 });
 
-// node_modules/.pnpm/@fleetless+contracts@1.0.4/node_modules/@fleetless/contracts/dist/config-issues.js
+// node_modules/.pnpm/@fleetless+contracts@1.0.5/node_modules/@fleetless/contracts/dist/config-issues.js
 var EXPOSURE_SECTIONS = ["datapoints", "actions", "services", "publishers", "cameras"];
 var EXPOSURE_SECTION_NAMES = new Set(EXPOSURE_SECTIONS);
 
-// node_modules/.pnpm/@fleetless+contracts@1.0.4/node_modules/@fleetless/contracts/dist/rest.js
+// node_modules/.pnpm/@fleetless+contracts@1.0.5/node_modules/@fleetless/contracts/dist/rest.js
 var import_zod9 = require("zod");
 var robot = import_zod9.z.object({
   id: import_zod9.z.uuid().meta({
@@ -3315,13 +3315,13 @@ var slugUsageResponse = import_zod9.z.object({
   alert_count: import_zod9.z.number().int().nonnegative()
 });
 
-// node_modules/.pnpm/@fleetless+contracts@1.0.4/node_modules/@fleetless/contracts/dist/realtime.js
+// node_modules/.pnpm/@fleetless+contracts@1.0.5/node_modules/@fleetless/contracts/dist/realtime.js
 var import_zod14 = require("zod");
 
-// node_modules/.pnpm/@fleetless+contracts@1.0.4/node_modules/@fleetless/contracts/dist/client-auth.js
+// node_modules/.pnpm/@fleetless+contracts@1.0.5/node_modules/@fleetless/contracts/dist/client-auth.js
 var import_zod13 = require("zod");
 
-// node_modules/.pnpm/@fleetless+contracts@1.0.4/node_modules/@fleetless/contracts/dist/apps.js
+// node_modules/.pnpm/@fleetless+contracts@1.0.5/node_modules/@fleetless/contracts/dist/apps.js
 var import_zod10 = require("zod");
 var appIdentifier = slug;
 var app = import_zod10.z.object({
@@ -3503,10 +3503,10 @@ var rolePermissions = import_zod10.z.object({
   })
 });
 
-// node_modules/.pnpm/@fleetless+contracts@1.0.4/node_modules/@fleetless/contracts/dist/app-users.js
+// node_modules/.pnpm/@fleetless+contracts@1.0.5/node_modules/@fleetless/contracts/dist/app-users.js
 var import_zod12 = require("zod");
 
-// node_modules/.pnpm/@fleetless+contracts@1.0.4/node_modules/@fleetless/contracts/dist/identity.js
+// node_modules/.pnpm/@fleetless+contracts@1.0.5/node_modules/@fleetless/contracts/dist/identity.js
 var import_zod11 = require("zod");
 var password = import_zod11.z.string().min(12).max(256);
 var USER_DISPLAY_NAME_MAX = 120;
@@ -3668,7 +3668,7 @@ var authMeResponse = import_zod11.z.object({ org, user: fleetlessUser });
 var patchOrgRequest = import_zod11.z.object({ name: import_zod11.z.string().min(1).max(120) }).strict();
 var patchAuthMeRequest = import_zod11.z.object({ display_name: import_zod11.z.string().min(1).max(USER_DISPLAY_NAME_MAX).nullable() }).strict();
 
-// node_modules/.pnpm/@fleetless+contracts@1.0.4/node_modules/@fleetless/contracts/dist/app-users.js
+// node_modules/.pnpm/@fleetless+contracts@1.0.5/node_modules/@fleetless/contracts/dist/app-users.js
 var APP_USER_DISPLAY_NAME_MAX = 120;
 var providerSlug = import_zod12.z.string().max(40).regex(/^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/, "a provider slug is lowercase and hyphen-separated, starting with a letter");
 var appUserStatus = import_zod12.z.enum(["pending_verification", "active", "blocked"]);
@@ -3919,7 +3919,7 @@ var mailOutcome = import_zod12.z.object({
   })
 });
 
-// node_modules/.pnpm/@fleetless+contracts@1.0.4/node_modules/@fleetless/contracts/dist/client-auth.js
+// node_modules/.pnpm/@fleetless+contracts@1.0.5/node_modules/@fleetless/contracts/dist/client-auth.js
 var clientLoginRequest = import_zod13.z.object({
   app_identifier: appIdentifier.meta({
     description: "The app being logged in to, as its globally unique identifier \u2014 the lowercase, underscore-separated string the developer chose when the app was created. There is no organisation context at login, so this is what decides which app the credentials are checked for."
@@ -4108,7 +4108,7 @@ var clientIdentity = import_zod13.z.object({
   })
 });
 
-// node_modules/.pnpm/@fleetless+contracts@1.0.4/node_modules/@fleetless/contracts/dist/realtime.js
+// node_modules/.pnpm/@fleetless+contracts@1.0.5/node_modules/@fleetless/contracts/dist/realtime.js
 var clientAuth = import_zod14.z.object({
   type: import_zod14.z.literal("auth"),
   token: import_zod14.z.string().min(1)
@@ -4386,7 +4386,7 @@ var orgEventDropped = import_zod14.z.object({
   dropped: import_zod14.z.number().int().positive()
 }).strict();
 
-// node_modules/.pnpm/@fleetless+contracts@1.0.4/node_modules/@fleetless/contracts/dist/audit.js
+// node_modules/.pnpm/@fleetless+contracts@1.0.5/node_modules/@fleetless/contracts/dist/audit.js
 var import_zod15 = require("zod");
 var auditActor = import_zod15.z.object({
   kind: import_zod15.z.enum(["developer", "end_user", "app_user", "server_key", "bridge"]),
@@ -4517,7 +4517,7 @@ var auditListResponse = import_zod15.z.object({
   next_cursor: import_zod15.z.number().int().positive().nullable()
 });
 
-// node_modules/.pnpm/@fleetless+contracts@1.0.4/node_modules/@fleetless/contracts/dist/errors.js
+// node_modules/.pnpm/@fleetless+contracts@1.0.5/node_modules/@fleetless/contracts/dist/errors.js
 var import_zod16 = require("zod");
 var apiError = import_zod16.z.object({
   code: import_zod16.z.string().min(1),
@@ -4534,7 +4534,7 @@ var parameterInvalidDetails = import_zod16.z.object({
   violations: import_zod16.z.array(parameterViolation).min(1)
 });
 
-// node_modules/.pnpm/@fleetless+contracts@1.0.4/node_modules/@fleetless/contracts/dist/oauth.js
+// node_modules/.pnpm/@fleetless+contracts@1.0.5/node_modules/@fleetless/contracts/dist/oauth.js
 var import_zod17 = require("zod");
 var oauthErrorCode = import_zod17.z.enum([
   "invalid_request",
@@ -4755,7 +4755,7 @@ var oauthAuthorizeQuery = import_zod17.z.object({
   description: "The authorization request an MCP client sends, per RFC 6749 \xA74.1.1 with mandatory PKCE. The handler reads it parameter by parameter rather than through one parse, because the answers differ: `client_id` and `redirect_uri` are refused flat, with no redirect, since until both are confirmed there is no trusted target to bounce a browser to, and everything after them is reported to the client's own callback as query parameters."
 });
 
-// node_modules/.pnpm/@fleetless+contracts@1.0.4/node_modules/@fleetless/contracts/dist/routes.js
+// node_modules/.pnpm/@fleetless+contracts@1.0.5/node_modules/@fleetless/contracts/dist/routes.js
 var MCP_APP = MCP_APP_PATHS(":appIdentifier");
 var APP_IDENTIFIER = {
   name: "appIdentifier",
@@ -6355,7 +6355,7 @@ var ROUTES = [
     response: null,
     errors: ["not_found", "unauthorized", "forbidden"],
     transport: "http",
-    notes: "MCP's Streamable HTTP gives this path three verbs: `POST` carries JSON-RPC, `GET` opens the server-initiated SSE stream, and `DELETE` ends a session. This server has no sessions \u2014 the argument is in `MCP_PROTOCOL_VERSION`'s own note, and a per-process session map is what breaks at the second cloud instance \u2014 so `GET` and `DELETE` answer `405`, which is what a client is built to fall back from. \n\n**The `405` is this cloud's own answer, not the SDK's**, and the two differ: MCP SDK 1.30.0 opens an SSE stream on `GET` (`handleGetRequest`) and answers `200` on `DELETE` (`handleDeleteRequest`), neither of which a stateless server has any business doing, so the cloud writes the `405` itself in the transport's own JSON-RPC error shape with `Allow: POST`. \n\n**The row exists so that the `405` is not a `404`.** An unregistered verb answers `404`, and at a path whose last segment is an app identifier a `404` already means *no such app* \u2014 one answer for two states, which is one answer for two states. Registering the verb lets the endpoint say \"this app's server is here; this verb is not part of it\". The central `/mcp` registers neither verb and does not need to: its path takes no parameter, so nothing can misread its `404`. \n\n**The `405` body is the transport's JSON-RPC error object, not the `apiError` envelope.** The three codes above are the refusals that come *first* \u2014 the app, its switch, then the bearer, in the order `POST` describes \u2014 and they are `apiError` because they are answered before the transport is reached at all. If this server ever becomes stateful, this row and the `DELETE` beside it are where that lands, and the cloud's route-manifest test is what would make both repositories notice."
+    notes: "MCP's Streamable HTTP gives this path three verbs: `POST` carries JSON-RPC, `GET` opens the server-initiated SSE stream, and `DELETE` ends a session. This server has no sessions \u2014 the argument is in `MCP_PROTOCOL_VERSION`'s own note, and a per-process session map is what breaks at the second cloud instance \u2014 so `GET` and `DELETE` answer `405`, which is what a client is built to fall back from. \n\n**The `405` is this cloud's own answer, not the SDK's**, and the two differ: MCP SDK 1.30.0 opens an SSE stream on `GET` (`handleGetRequest`) and answers `200` on `DELETE` (`handleDeleteRequest`), neither of which a stateless server has any business doing, so the cloud writes the `405` itself in the transport's own JSON-RPC error shape with `Allow: POST`. \n\n**The row exists so that the `405` is not a `404`.** An unregistered verb answers `404`, and at a path whose last segment is an app identifier a `404` already means *no such app* \u2014 so an unregistered verb and an unknown app would answer identically. Registering the verb lets the endpoint say \"this app's server is here; this verb is not part of it\". The central `/mcp` registers neither verb and does not need to: its path takes no parameter, so nothing can misread its `404`. \n\n**The `405` body is the transport's JSON-RPC error object, not the `apiError` envelope.** The three codes above are the refusals that come *first* \u2014 the app, its switch, then the bearer, in the order `POST` describes \u2014 and they are `apiError` because they are answered before the transport is reached at all. If this server ever becomes stateful, this row and the `DELETE` beside it are where that lands, and the cloud's route-manifest test is what would make both repositories notice."
   },
   {
     method: "DELETE",
@@ -7320,7 +7320,7 @@ var ROUTES = [
     response: jobRunListResponse,
     errors: [...CLIENT_GUARD, "invalid_uuid", "not_found", "capability_required", "validation_error"],
     transport: "http",
-    notes: "Needs the `action_history` capability, and **this route is what makes that switch mean something** \u2014 it was unkeepable while nothing durable recorded what had run. Two residuals worth stating rather than implying away. `history` is a syntactically valid slug and The router matches a static segment first, so a robot with a service literally slugged `history` can no longer be **read** through `GET /api/robots/:id/jobs/:slug`; invoking, cancelling and the listing are unaffected. And a run row names its actor by email address, so an end user holding this capability learns which other people have been driving the machine. `robot_id` in the query is shared with the org-wide read; a *different* one here is refused rather than quietly answered about the robot in the path."
+    notes: "Needs the `action_history` capability, and **this route is what makes that switch mean something** \u2014 it was unkeepable while nothing durable recorded what had run. Two residuals worth stating rather than implying away. `history` is a syntactically valid slug, and a static segment matches before a parameter, so a robot with a service literally slugged `history` can no longer be **read** through `GET /api/robots/:id/jobs/:slug`; invoking, cancelling and the listing are unaffected. And a run row names its actor by email address, so an end user holding this capability learns which other people have been driving the machine. `robot_id` in the query is shared with the org-wide read; a *different* one here is refused rather than quietly answered about the robot in the path."
   },
   {
     method: "POST",
@@ -8332,21 +8332,21 @@ function assertValidJobId(jobId) {
   if (jobId === void 0 || jobId === null || typeof jobId === "string") return;
   throw new FleetlessError(
     "invalid_option",
-    `cancel()'s third argument must be a job id (string), null, or omitted \u2014 got ${typeof jobId === "object" ? "an object" : typeof jobId}. If you are passing an options object (e.g. {timeoutMs}) as the third argument, note the signature changed in this release: cancel(robotId, slug) is unchanged, but a third positional argument is now the job id to cancel and options moved to a fourth argument \u2014 cancel(robotId, slug, jobId, options). See the README's Actions section.`
+    `cancel()'s third argument must be a job id (string), null, or omitted \u2014 got ${typeof jobId === "object" ? "an object" : typeof jobId}. If you are passing an options object (e.g. {timeoutMs}) as the third argument, note the signature changed in this release: cancel(robotId, slug) is unchanged, but a third positional argument is now the job id to cancel and options moved to a fourth argument \u2014 cancel(robotId, slug, jobId, options). See the Actions section of the SDK reference at https://docs.fleetless.dev/reference/sdk/`
   );
 }
 function createRealtimeCommandTransport(channel) {
   return {
-    // Declared `async` deliberately, unlike `cancel`/`publish` below: it is
+    // Declared `async` deliberately, unlike `cancel`/`publish` below: it's
     // the only one of the three that can refuse *before* sending anything
-    // (resolveLocalWaitMs's `invalid_option`, D3a), and every caller of
-    // this interface — starting with this file's own `sendCommand` callers
-    // — is entitled to assume `CommandTransport.invoke` always returns a
-    // promise rather than throwing synchronously. Without `async` here, a
-    // synchronous throw from `resolveLocalWaitMs` would escape as a thrown
-    // exception instead of a rejection, breaking that assumption for any
-    // caller that isn't itself inside an `async` function (e.g. a test
-    // calling this transport directly).
+    // (`resolveLocalWaitMs`'s `invalid_option`), and every caller of this
+    // interface — starting with this file's own `sendCommand` callers —
+    // assumes `CommandTransport.invoke` always returns a promise, never
+    // throws synchronously. Without `async` here, a synchronous throw from
+    // `resolveLocalWaitMs` would escape as a thrown exception instead of a
+    // rejection, breaking that assumption for a caller that isn't itself
+    // inside an `async` function (e.g. a test calling this transport
+    // directly).
     async invoke(robotId, slug2, params, options) {
       const timeoutMs = resolveLocalWaitMs(options ?? {}, DEFAULT_COMMAND_TIMEOUT_MS);
       const frame = {
@@ -8546,12 +8546,11 @@ var RealtimeChannel = class {
   }
   /**
    * Increments on every successful authentication (first connect and every
-   * reconnect). A command sent on one physical socket can only ever be
-   * answered on that socket — comparing the epoch captured at send time
-   * against the current one is how a caller (see `commands.ts`) tells "still
-   * waiting on the connection it was sent over" from "that connection is
-   * gone and a new one has taken its place", the moment it happens rather
-   * than after a timeout elapses.
+   * reconnect). A command sent on one socket can only be answered on that
+   * socket — comparing the epoch at send time against the current one is
+   * how a caller (see `commands.ts`) tells "still waiting on the connection
+   * it was sent over" from "that connection is gone and a new one has taken
+   * its place", the moment it happens rather than after a timeout elapses.
    */
   get connectionEpoch() {
     return this.#connectionEpoch;
@@ -8852,7 +8851,7 @@ function createSlugSubscriptions(channel) {
 // src/token-store.ts
 var InMemoryTokenStore = class {
   #session = null;
-  /** Creates an empty store. Nothing is loaded from anywhere — a client built with it starts logged out. */
+  /** Nothing is loaded from anywhere — a client built with it starts logged out. */
   constructor() {
   }
   /** Returns the session held in memory, or `null` if there is none. */