@fleetless/sdk 3.1.1 → 4.1.0

package/dist/index.d.ts

@@ -74,14 +74,20 @@ type McpRobotDatasheet = z.infer<typeof mcpRobotDatasheet>;
  * 1. **State is observed by slug, not by id.** The id is informative; a client
  *    watches `robot × slug` and sees whatever job is running there, which is
  *    also why every observer of a slug sees the same job.
- * 2. **`lost` is a real outcome and must be said out loud.** Job state
- *    lives only in the bridge's memory; if it restarts mid-job, the results
- *    are gone. The cloud then marks the job `lost` — never leaves it reading
- *    "running" because nobody contradicted it. A system that reports a
- *    machine is still working when it does not know is worse than one that
- *    admits it lost track.
+ * 2. **What the cloud does not know it calls `unknown`, and `lost` is final.**
+ *    A job whose robot went quiet — offline past `JOB_OFFLINE_GRACE_MS`, or
+ *    connected but silent past `JOB_HEARTBEAT_TIMEOUT_MS` — is `unknown`: not
+ *    terminal, the slug stays occupied, and only a statement of the bridge
+ *    resolves it (it is running, it ended, or the bridge does not know it and
+ *    nothing else runs on its action). `lost` is what that last statement
+ *    produces, and nothing ever leaves it. Neither is left reading "running"
+ *    because nobody contradicted it: a system that reports a machine is still
+ *    working when it does not know is worse than one that says so — and one
+ *    that declares work lost on a guess is wrong the moment the robot comes
+ *    back and says it finished.
  */
 declare const jobState: z.ZodEnum<{
+    unknown: "unknown";
     failed: "failed";
     running: "running";
     succeeded: "succeeded";
@@ -89,17 +95,42 @@ declare const jobState: z.ZodEnum<{
     lost: "lost";
 }>;
 type JobState = z.infer<typeof jobState>;
+/**
+ * Who started a job.
+ *
+ * `fleetless` for every job the cloud minted from an invocation. `external`
+ * for a goal the bridge found active on a published action without having
+ * sent it — started by anyone else on the robot's ROS graph, or the bridge's
+ * own goal after its mapping was lost. An external job has the same shape,
+ * states, live stream and cancel as any other, but no parameters (ROS 2
+ * publishes a goal's request nowhere), no starter, and it lives in memory
+ * only: it is never written to `job_runs` and never counts towards quotas.
+ */
+declare const jobOrigin: z.ZodEnum<{
+    fleetless: "fleetless";
+    external: "external";
+}>;
+type JobOrigin = z.infer<typeof jobOrigin>;
+/**
+ * One job, as the cloud tells every client about it — a Fleetless job or an
+ * external goal alike, told apart only by `origin`.
+ */
 declare const job: z.ZodObject<{
     id: z.ZodUUID;
     robot_id: z.ZodUUID;
     slug: z.ZodString;
     state: z.ZodEnum<{
+        unknown: "unknown";
         failed: "failed";
         running: "running";
         succeeded: "succeeded";
         cancelled: "cancelled";
         lost: "lost";
     }>;
+    origin: z.ZodEnum<{
+        fleetless: "fleetless";
+        external: "external";
+    }>;
     started_at: z.ZodISODateTime;
     updated_at: z.ZodISODateTime;
     seq: z.ZodNumber;
@@ -129,12 +160,17 @@ declare const jobEvent: z.ZodObject<{
         robot_id: z.ZodUUID;
         slug: z.ZodString;
         state: z.ZodEnum<{
+            unknown: "unknown";
             failed: "failed";
             running: "running";
             succeeded: "succeeded";
             cancelled: "cancelled";
             lost: "lost";
         }>;
+        origin: z.ZodEnum<{
+            fleetless: "fleetless";
+            external: "external";
+        }>;
         started_at: z.ZodISODateTime;
         updated_at: z.ZodISODateTime;
         seq: z.ZodNumber;
@@ -153,6 +189,11 @@ type JobEvent = z.infer<typeof jobEvent>;
 /**
  * What a busy refusal tells the caller: what is already running. A refusal that
  * only says "busy" forces the caller to guess whether to wait or to give up.
+ *
+ * `running` is whatever occupies the slug — a `running` job, an `unknown` one
+ * the robot has not accounted for yet, or an `external` goal someone else
+ * started — and its `state` and `origin` say which, so a caller can tell
+ * "wait for it" from "cancel what someone else started".
  */
 declare const busyDetails: z.ZodObject<{
     running: z.ZodObject<{
@@ -160,12 +201,17 @@ declare const busyDetails: z.ZodObject<{
         robot_id: z.ZodUUID;
         slug: z.ZodString;
         state: z.ZodEnum<{
+            unknown: "unknown";
             failed: "failed";
             running: "running";
             succeeded: "succeeded";
             cancelled: "cancelled";
             lost: "lost";
         }>;
+        origin: z.ZodEnum<{
+            fleetless: "fleetless";
+            external: "external";
+        }>;
         started_at: z.ZodISODateTime;
         updated_at: z.ZodISODateTime;
         seq: z.ZodNumber;
@@ -194,6 +240,7 @@ declare const jobRun: z.ZodObject<{
         service: "service";
     }>;
     state: z.ZodEnum<{
+        unknown: "unknown";
         failed: "failed";
         running: "running";
         succeeded: "succeeded";
@@ -234,6 +281,7 @@ declare const jobRunListResponse: z.ZodObject<{
             service: "service";
         }>;
         state: z.ZodEnum<{
+            unknown: "unknown";
             failed: "failed";
             running: "running";
             succeeded: "succeeded";
@@ -352,8 +400,8 @@ declare const historySamplesResponse: z.ZodObject<{
     }, z.core.$strip>>;
     truncated: z.ZodBoolean;
     truncated_by: z.ZodNullable<z.ZodEnum<{
-        limit: "limit";
         bytes: "bytes";
+        limit: "limit";
     }>>;
 }, z.core.$strip>;
 type HistorySamplesResponse = z.infer<typeof historySamplesResponse>;
@@ -577,6 +625,7 @@ declare const clientRobotListItem: z.ZodObject<{
     bridge_state: z.ZodObject<{
         online: z.ZodBoolean;
         latency_ms: z.ZodNullable<z.ZodNumber>;
+        low_bandwidth: z.ZodBoolean;
     }, z.core.$strip>;
     published_version: z.ZodNullable<z.ZodNumber>;
     id: z.ZodUUID;
@@ -593,7 +642,6 @@ declare const asset: z.ZodObject<{
         urdf: "urdf";
         mesh: "mesh";
         texture: "texture";
-        other: "other";
     }>;
     name: z.ZodString;
     media_type: z.ZodString;
@@ -649,14 +697,16 @@ declare const assetSyncStatus: z.ZodObject<{
             unresolvable: "unresolvable";
             upload_failed: "upload_failed";
             refused: "refused";
-            too_large: "too_large";
         }>;
         details: z.ZodOptional<z.ZodNullable<z.ZodObject<{
-            limit_bytes: z.ZodNumber;
+            store_bytes: z.ZodNumber;
+            used_bytes: z.ZodNumber;
             size_bytes: z.ZodNumber;
         }, z.core.$strip>>>;
     }, z.core.$strip>>;
     reason: z.ZodNullable<z.ZodString>;
+    stored: z.ZodNullable<z.ZodNumber>;
+    announced: z.ZodNumber;
     started_at: z.ZodISODateTime;
     updated_at: z.ZodISODateTime;
 }, z.core.$strip>;
@@ -669,7 +719,6 @@ declare const assetListResponse: z.ZodObject<{
             urdf: "urdf";
             mesh: "mesh";
             texture: "texture";
-            other: "other";
         }>;
         name: z.ZodString;
         media_type: z.ZodString;
@@ -693,14 +742,16 @@ declare const assetListResponse: z.ZodObject<{
                 unresolvable: "unresolvable";
                 upload_failed: "upload_failed";
                 refused: "refused";
-                too_large: "too_large";
             }>;
             details: z.ZodOptional<z.ZodNullable<z.ZodObject<{
-                limit_bytes: z.ZodNumber;
+                store_bytes: z.ZodNumber;
+                used_bytes: z.ZodNumber;
                 size_bytes: z.ZodNumber;
             }, z.core.$strip>>>;
         }, z.core.$strip>>;
         reason: z.ZodNullable<z.ZodString>;
+        stored: z.ZodNullable<z.ZodNumber>;
+        announced: z.ZodNumber;
         started_at: z.ZodISODateTime;
         updated_at: z.ZodISODateTime;
     }, z.core.$strip>>;
@@ -716,6 +767,11 @@ declare const assetListResponse: z.ZodObject<{
         }, z.core.$strip>>;
     }, z.core.$strip>;
     urdf_available: z.ZodNullable<z.ZodBoolean>;
+    store: z.ZodObject<{
+        bytes: z.ZodNumber;
+        used_bytes: z.ZodNumber;
+    }, z.core.$strip>;
+    joint_state_slug: z.ZodNullable<z.ZodString>;
 }, z.core.$strip>;
 type AssetListResponse = z.infer<typeof assetListResponse>;
 
@@ -758,7 +814,7 @@ type ParameterInvalidDetails = z.infer<typeof parameterInvalidDetails>;
  * list is the shared vocabulary, not a closed set, so a new refusal never
  * needs a contracts release before it can be reported honestly.
  */
-declare const ERROR_CODES: readonly ["not_found", "validation_error", "bad_request", "unknown_datapoint", "invalid_token", "protocol_mismatch", "invalid_frame", "duplicate_slug", "reserved_slug", "unknown_slug", "unknown_field_path", "unknown_type", "unknown_topic", "invalid_rate", "invalid_range", "config_conflict", "no_data", "robot_offline", "bridge_timeout", "unauthorized", "forbidden", "invalid_credentials", "token_expired", "token_revoked", "email_taken", "identifier_taken", "weak_password", "account_blocked", "busy", "parameter_invalid", "job_lost", "publisher_busy", "unknown_command", "not_subscribable", "camera_offline", "no_snapshot_yet", "live_unavailable", "wrong_kind", "not_recorded", "not_aggregatable", "quota_exceeded", "credential_in_use", "goal_timeout", "robot_in_use", "robot_deletion_partial", "job_queue_full", "invalid_uuid", "rate_limited", "tier_required", "token_spent", "service_timeout", "asset_missing", "asset_too_large", "dynamic_registration_disabled", "client_limit_reached", "idp_unavailable", "mcp_disabled", "tool_not_available", "capability_required", "last_owner", "target_state_conflict", "signup_closed", "draft_not_a_document", "internal_error", "not_cancellable", "unsupported_media_type", "wrong_browser", "invalid_yaml", "unstorable_yaml", "registration_closed", "domain_not_allowed", "email_unverified", "origin_not_allowed", "template_invalid", "provider_disabled", "provider_misconfigured", "invalid_redirect_uri", "interaction_expired"];
+declare const ERROR_CODES: readonly ["not_found", "validation_error", "bad_request", "unknown_datapoint", "invalid_token", "protocol_mismatch", "bridge_too_old", "invalid_frame", "duplicate_slug", "reserved_slug", "unknown_slug", "unknown_field_path", "unknown_type", "unknown_topic", "invalid_rate", "invalid_range", "config_conflict", "no_data", "robot_offline", "bridge_timeout", "unauthorized", "forbidden", "invalid_credentials", "token_expired", "token_revoked", "email_taken", "identifier_taken", "weak_password", "account_blocked", "busy", "parameter_invalid", "cancel_rejected", "job_lost", "job_unknown_to_bridge", "action_server_lost", "action_failed", "goal_rejected", "goal_send_failed", "result_failed", "goal_uncontrollable", "bridge_disconnected", "config_changed", "publisher_busy", "unknown_command", "not_subscribable", "camera_offline", "no_snapshot_yet", "live_unavailable", "wrong_kind", "not_recorded", "not_aggregatable", "quota_exceeded", "credential_in_use", "goal_timeout", "robot_in_use", "robot_deletion_partial", "job_queue_full", "invalid_uuid", "rate_limited", "tier_required", "token_spent", "service_timeout", "asset_missing", "dynamic_registration_disabled", "client_limit_reached", "idp_unavailable", "mcp_disabled", "tool_not_available", "capability_required", "last_owner", "target_state_conflict", "signup_closed", "draft_not_a_document", "internal_error", "not_cancellable", "unsupported_media_type", "wrong_browser", "invalid_yaml", "unstorable_yaml", "registration_closed", "domain_not_allowed", "email_unverified", "origin_not_allowed", "template_invalid", "provider_disabled", "provider_misconfigured", "invalid_redirect_uri", "interaction_expired"];
 type ErrorCode = (typeof ERROR_CODES)[number];
 
 /**
@@ -912,6 +968,34 @@ declare class FleetlessError extends Error {
     constructor(code: FleetlessErrorCode, message: string, options?: FleetlessErrorOptions);
 }
 
+/**
+ * Supplies the `Authorization` header value for a request, and knows what to
+ * do when the server says the token has expired. `HttpClient` is agnostic to
+ * *what* is authenticating it — an end-user session with silent refresh, or
+ * a static server key — so both can share one request path.
+ */
+interface CredentialSource {
+    /**
+     * The current raw bearer credential — a JWT or a server key (`flk_...`) —
+     * or null if not authenticated. Raw, not `Bearer <token>`: REST forms the
+     * `Authorization` header from it, and the realtime auth frame
+     * carries the very same value unprefixed, so there is exactly one place
+     * that knows what "the token" currently is.
+     */
+    token(): Promise<string | null>;
+    /**
+     * Called once when a request comes back `token_expired`. Three outcomes:
+     * - resolves `true` — a fresh credential is ready, retry the request;
+     * - resolves `false` — nothing to do (e.g. a server key, which cannot be
+     *   refreshed at all), propagate the original `token_expired`;
+     * - throws a `FleetlessError` — refreshing itself failed for a specific,
+     *   more useful reason (e.g. `token_revoked`, a reused refresh token);
+     *   that error propagates instead of the original `token_expired`, so the
+     *   caller learns what actually happened, not just that a retry was tried.
+     */
+    handleExpired(): Promise<boolean>;
+}
+
 /**
  * The options every realtime command accepts — `actions.cancel` and
  * `publishers.publish` take exactly these; `InvokeOptions` extends them for
@@ -1023,6 +1107,25 @@ interface ActionsApi {
      * was nothing there", and "I stopped a job that started after I last
      * looked" are three different outcomes a discarded result cannot tell
      * apart.
+     *
+     * **Resolving means the robot's action server accepted the cancel, not
+     * that the goal ended.** The returned job is usually still `running`; how
+     * it ends arrives as its own update (`subscribe`). The platform answers
+     * from the action server's `CancelGoal` return codes, so a cancel can
+     * also reject with:
+     * - `cancel_rejected` — the server refused (`ERROR_REJECTED`) and the goal
+     *   keeps running unless its job later says otherwise. `error.details.goals`
+     *   lists every goal the cancel reached as `{ job_id, goal_id, return_code }`
+     *   (`0` accepted, `1` rejected, `2` unknown goal, `3` already ended, `null`
+     *   when that goal's server did not answer).
+     * - `bridge_timeout` — the robot's bridge did not answer in time; whether
+     *   the cancel reached the server is unknown.
+     * - the bridge's own code when it could not ask at all (e.g.
+     *   `unknown_slug`, `action_server_lost`), `not_cancellable` for a service,
+     *   and `robot_offline`.
+     *
+     * Cancelling an `unknown` job cancels every `external` goal on its action,
+     * never another of the platform's own jobs.
      */
     cancel(robotId: string, slug: string, jobId?: string | null, options?: SendCommandOptions): Promise<Job | null>;
     /**
@@ -2051,7 +2154,7 @@ interface DatapointsApi {
 interface JobHistoryOptions {
     /** Only runs of this action or service. */
     slug?: string;
-    /** Only runs in this state: `running`, `succeeded`, `failed`, `cancelled` or `lost`. */
+    /** Only runs in this state: `running`, `unknown`, `succeeded`, `failed`, `cancelled` or `lost`. */
     state?: JobState;
     /** Only `action` runs, or only `service` runs. */
     kind?: 'action' | 'service';
@@ -2253,6 +2356,25 @@ interface FleetlessClientOptions {
      * with a server key never calls `auth.login`/`auth.logout`.
      */
     serverKey?: string;
+    /**
+     * **A credential this client does not own.** The caller answers both
+     * questions a bearer raises: what the token is right now (`token()`), and
+     * what to do when the server says it expired (`handleExpired()`).
+     *
+     * For an embedder that already holds a session and refreshes it itself —
+     * the Fleetless console is the case this exists for. Without it such a
+     * caller had to impersonate a `TokenStore`, and a cloud-side
+     * `token_expired` arriving while its own clock still read live posted one
+     * empty refresh whose `validation_error` had to be translated back into a
+     * session message. A source that answers `handleExpired: false` never
+     * builds a refresh request at all.
+     *
+     * Mutually exclusive with `tokenStore` and `serverKey`, which each own a
+     * credential of their own; a client acts as exactly one identity.
+     * `auth.login`/`auth.logout` refuse here for the same reason they refuse
+     * on a server key: there is no session for this client to start or end.
+     */
+    credentials?: CredentialSource;
     /** Injectable for tests, or a non-global `fetch` implementation. */
     fetch?: typeof fetch;
     /** Injectable for tests, or a non-global `WebSocket` implementation. */
@@ -2322,12 +2444,14 @@ interface FleetlessClient {
  * Builds a client for one app. Pass `tokenStore` (or nothing — the default
  * keeps the session in memory) for an app-user client that signs in with
  * `auth.login` or a federated provider; pass `serverKey` for a server-side
- * caller that never holds a user session. Passing both throws, because the
- * two are different identities and a client acts as exactly one.
+ * caller that never holds a user session; pass `credentials` when the
+ * embedder already holds the bearer and refreshes it itself. Passing more
+ * than one throws, because each is a different identity and a client acts
+ * as exactly one.
  *
  * Nothing is fetched here: the realtime channel opens on the first
  * subscription and closes on `close()` or `auth.logout()`.
  */
 declare function createClient(options: FleetlessClientOptions): FleetlessClient;
 
-export { type AcceptInvitationOptions, type ActionsApi, type Asset, type AssetBytes, type AssetListResponse, type AssetsApi, type AuthApi, type BeginOidcLoginOptions, type BusyDetails, type CameraDescriptor, type CameraLiveSession, type CameraSnapshot, type CameraSnapshotMeta, type CamerasApi, type ClientIdentity, type ClientMcpInteraction, type ClientOidcErrorCode, type ClientRobotListItem, type CompleteOidcLoginOptions, type CreateMeshLoaderOptions, type DatapointEvent, type DatapointSubscription, type DatapointSubscriptionHandlers, type DatapointValue, type DatapointsApi, type FleetlessClient, type FleetlessClientConfig, type FleetlessClientOptions, FleetlessError, type FleetlessErrorCode, type FleetlessErrorOptions, type HistoryAggregation, type HistoryBucketsResponse, type HistoryOptions, type HistorySamplesResponse, InMemoryTokenStore, type InvokeOptions, type Job, type JobEvent, type JobHistoryOptions, type JobRun, type JobRunListResponse, type JobState, type JobSubscription, type JobSubscriptionHandlers, type JobsApi, type McpCapabilities, type McpConsentGrant, type McpExposure, type McpInteractionDecision, type McpRobotDatasheet, type MeshLoaderDelegate, type OidcLoginRequest, type ParameterInvalidDetails, type ParameterViolation, type PrepareUrdfSceneOptions, type ProviderButton, type PublishersApi, type RateLimitDetails, type RegisterOptions, type RobotsApi, SDK_ERROR_CODES, type SdkErrorCode, type SendCommandOptions, type ServicesApi, type StoredSession, type TokenStore, type UrdfCompleteness, type UrdfSceneManager, type UrdfSceneResources, createClient, parameterInvalidDetails };
+export { type AcceptInvitationOptions, type ActionsApi, type Asset, type AssetBytes, type AssetListResponse, type AssetsApi, type AuthApi, type BeginOidcLoginOptions, type BusyDetails, type CameraDescriptor, type CameraLiveSession, type CameraSnapshot, type CameraSnapshotMeta, type CamerasApi, type ClientIdentity, type ClientMcpInteraction, type ClientOidcErrorCode, type ClientRobotListItem, type CompleteOidcLoginOptions, type CreateMeshLoaderOptions, type CredentialSource, type DatapointEvent, type DatapointSubscription, type DatapointSubscriptionHandlers, type DatapointValue, type DatapointsApi, type FleetlessClient, type FleetlessClientConfig, type FleetlessClientOptions, FleetlessError, type FleetlessErrorCode, type FleetlessErrorOptions, type HistoryAggregation, type HistoryBucketsResponse, type HistoryOptions, type HistorySamplesResponse, InMemoryTokenStore, type InvokeOptions, type Job, type JobEvent, type JobHistoryOptions, type JobOrigin, type JobRun, type JobRunListResponse, type JobState, type JobSubscription, type JobSubscriptionHandlers, type JobsApi, type McpCapabilities, type McpConsentGrant, type McpExposure, type McpInteractionDecision, type McpRobotDatasheet, type MeshLoaderDelegate, type OidcLoginRequest, type ParameterInvalidDetails, type ParameterViolation, type PrepareUrdfSceneOptions, type ProviderButton, type PublishersApi, type RateLimitDetails, type RegisterOptions, type RobotsApi, SDK_ERROR_CODES, type SdkErrorCode, type SendCommandOptions, type ServicesApi, type StoredSession, type TokenStore, type UrdfCompleteness, type UrdfSceneManager, type UrdfSceneResources, createClient, parameterInvalidDetails };