@fleetless/sdk 3.0.3 → 3.1.1

package/dist/index.d.ts

@@ -2,6 +2,68 @@
 import { z } from 'zod';
 
 
+/**
+ * One exposure of a robot, as `robot_describe` and the console's per-role
+ * preview list it. Every exposure the role grants is listed —
+ * a missing `description` is shown as `null`, never used to hide the entry.
+ *
+ * `input_schema` is a JSON Schema document generated from an action's,
+ * service's or publisher's `parameters`; `null` for the other kinds. It is
+ * `unknown` for the same reason the retired `mcpToolPreview.input_schema`
+ * was: pinning it would mean maintaining a zod description of JSON Schema.
+ */
+declare const mcpExposure: z.ZodObject<{
+    slug: z.ZodString;
+    kind: z.ZodEnum<{
+        datapoint: "datapoint";
+        action: "action";
+        service: "service";
+        publisher: "publisher";
+        camera: "camera";
+    }>;
+    description: z.ZodNullable<z.ZodString>;
+    unit: z.ZodNullable<z.ZodString>;
+    decimals: z.ZodNullable<z.ZodNumber>;
+    input_schema: z.ZodNullable<z.ZodUnknown>;
+}, z.core.$strip>;
+type McpExposure$1 = z.infer<typeof mcpExposure>;
+/** The two role capabilities a robot tool can need beyond a slug grant. `presence` is a stream and has no tool. */
+declare const mcpCapabilities: z.ZodObject<{
+    action_history: z.ZodBoolean;
+    assets: z.ZodBoolean;
+}, z.core.$strip>;
+type McpCapabilities$1 = z.infer<typeof mcpCapabilities>;
+/**
+ * What one caller may do on one robot — the answer to `robot_describe`, and
+ * since 1.1.0 to `GET /api/robots/:id/datasheet` as well. One schema for both
+ * surfaces on purpose: an app and an AI tool read the same description of the
+ * same grant. The `mcp` prefix is history, not scope.
+ */
+declare const mcpRobotDatasheet: z.ZodObject<{
+    robot_id: z.ZodUUID;
+    robot_name: z.ZodString;
+    capabilities: z.ZodObject<{
+        action_history: z.ZodBoolean;
+        assets: z.ZodBoolean;
+    }, z.core.$strip>;
+    exposures: z.ZodArray<z.ZodObject<{
+        slug: z.ZodString;
+        kind: z.ZodEnum<{
+            datapoint: "datapoint";
+            action: "action";
+            service: "service";
+            publisher: "publisher";
+            camera: "camera";
+        }>;
+        description: z.ZodNullable<z.ZodString>;
+        unit: z.ZodNullable<z.ZodString>;
+        decimals: z.ZodNullable<z.ZodNumber>;
+        input_schema: z.ZodNullable<z.ZodUnknown>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+type McpRobotDatasheet = z.infer<typeof mcpRobotDatasheet>;
+
+
 /**
  * Jobs: one running unit of work on a robot — an action
  * goal or a service call — with an id both sides know, so bridge and cloud
@@ -116,6 +178,94 @@ declare const busyDetails: z.ZodObject<{
     }, z.core.$strip>;
 }, z.core.$strip>;
 type BusyDetails = z.infer<typeof busyDetails>;
+/**
+ * One durable record of one invocation. One row per run, never one per event:
+ * the per-event timeline's write rate
+ * is set by the bridge, and a throttled log that cannot say it was throttled is
+ * an instrument that cannot say what it does not know. The live timeline is
+ * delivered in full by realtime, for as long as somebody is watching.
+ */
+declare const jobRun: z.ZodObject<{
+    id: z.ZodUUID;
+    robot_id: z.ZodUUID;
+    slug: z.ZodString;
+    kind: z.ZodEnum<{
+        action: "action";
+        service: "service";
+    }>;
+    state: z.ZodEnum<{
+        failed: "failed";
+        running: "running";
+        succeeded: "succeeded";
+        cancelled: "cancelled";
+        lost: "lost";
+    }>;
+    started_at: z.ZodISODateTime;
+    ended_at: z.ZodNullable<z.ZodISODateTime>;
+    duration_ms: z.ZodNullable<z.ZodNumber>;
+    result: z.ZodNullable<z.ZodUnknown>;
+    error: z.ZodNullable<z.ZodObject<{
+        code: z.ZodString;
+        message: z.ZodString;
+        details: z.ZodOptional<z.ZodUnknown>;
+    }, z.core.$strip>>;
+    actor: z.ZodObject<{
+        kind: z.ZodEnum<{
+            developer: "developer";
+            server_key: "server_key";
+            end_user: "end_user";
+            app_user: "app_user";
+        }>;
+        id: z.ZodUUID;
+        label: z.ZodString;
+    }, z.core.$strip>;
+    seq: z.ZodNumber;
+    progress: z.ZodNullable<z.ZodNumber>;
+    feedback: z.ZodNullable<z.ZodUnknown>;
+}, z.core.$strip>;
+type JobRun = z.infer<typeof jobRun>;
+declare const jobRunListResponse: z.ZodObject<{
+    runs: z.ZodArray<z.ZodObject<{
+        id: z.ZodUUID;
+        robot_id: z.ZodUUID;
+        slug: z.ZodString;
+        kind: z.ZodEnum<{
+            action: "action";
+            service: "service";
+        }>;
+        state: z.ZodEnum<{
+            failed: "failed";
+            running: "running";
+            succeeded: "succeeded";
+            cancelled: "cancelled";
+            lost: "lost";
+        }>;
+        started_at: z.ZodISODateTime;
+        ended_at: z.ZodNullable<z.ZodISODateTime>;
+        duration_ms: z.ZodNullable<z.ZodNumber>;
+        result: z.ZodNullable<z.ZodUnknown>;
+        error: z.ZodNullable<z.ZodObject<{
+            code: z.ZodString;
+            message: z.ZodString;
+            details: z.ZodOptional<z.ZodUnknown>;
+        }, z.core.$strip>>;
+        actor: z.ZodObject<{
+            kind: z.ZodEnum<{
+                developer: "developer";
+                server_key: "server_key";
+                end_user: "end_user";
+                app_user: "app_user";
+            }>;
+            id: z.ZodUUID;
+            label: z.ZodString;
+        }, z.core.$strip>;
+        seq: z.ZodNumber;
+        progress: z.ZodNullable<z.ZodNumber>;
+        feedback: z.ZodNullable<z.ZodUnknown>;
+    }, z.core.$strip>>;
+    next_cursor: z.ZodNullable<z.ZodNumber>;
+}, z.core.$strip>;
+type JobRunListResponse = z.infer<typeof jobRunListResponse>;
 
 /**
  * The REST read of one datapoint. For bridge-captured data `timestamp_ms`
@@ -413,6 +563,29 @@ declare const clientIdentity: z.ZodObject<{
 type ClientIdentity = z.infer<typeof clientIdentity>;
 
 
+/**
+ * One robot as `GET /api/client/robots` lists it — the REST twin of the MCP
+ * tool `robots_list`, and the one robot question no robot-scoped route can
+ * answer: which robots may I name at all.
+ *
+ * Deliberately not `robotListItem`: that one carries `exposes`, the per-kind
+ * counts a developer's list shows, which are a configuration fact rather than
+ * something an app user's role grants. What an app user is entitled to is the
+ * robot, its bridge state, and whether anything is published on it yet.
+ */
+declare const clientRobotListItem: z.ZodObject<{
+    bridge_state: z.ZodObject<{
+        online: z.ZodBoolean;
+        latency_ms: z.ZodNullable<z.ZodNumber>;
+    }, z.core.$strip>;
+    published_version: z.ZodNullable<z.ZodNumber>;
+    id: z.ZodUUID;
+    name: z.ZodString;
+    created_at: z.ZodISODateTime;
+}, z.core.$strip>;
+type ClientRobotListItem = z.infer<typeof clientRobotListItem>;
+
+
 declare const asset: z.ZodObject<{
     id: z.ZodUUID;
     robot_id: z.ZodUUID;
@@ -555,10 +728,10 @@ type AssetListResponse = z.infer<typeof assetListResponse>;
  * console renders a third, and each is right in its own tests.
  *
  * `field` is the **flat key exactly as the caller sent it** — the same string
- * as the `parameterSpec.name` it violated. That is the entire justification
- * for the flat parameter form: a refusal has to name something the caller can
- * find in what they typed, and a console can attach the error to that one
- * input rather than to the form.
+ * as the `parameterSpec.name` it violated. That is why the parameter form
+ * stays flat: a refusal has to name something the caller can find in what
+ * they typed, and a console can attach the error to that one input rather
+ * than to the form.
  */
 declare const parameterViolation: z.ZodObject<{
     field: z.ZodString;
@@ -1867,6 +2040,30 @@ interface DatapointsApi {
     }): Promise<HistorySamplesResponse>;
 }
 
+/**
+ * The filters `jobs.history` reads. Every field is optional; the wire names
+ * are snake_case and this SDK spells them the way its other options are
+ * spelt. `fromMs`/`toMs` are unix milliseconds, a half-open window
+ * `[from, to)` so adjacent windows never both contain the run on their
+ * boundary. `limit` above the platform's page cap is refused with
+ * `validation_error`, not quietly reduced.
+ */
+interface JobHistoryOptions {
+    /** Only runs of this action or service. */
+    slug?: string;
+    /** Only runs in this state: `running`, `succeeded`, `failed`, `cancelled` or `lost`. */
+    state?: JobState;
+    /** Only `action` runs, or only `service` runs. */
+    kind?: 'action' | 'service';
+    /** How many runs to return, 1 to 200; absent means 100. Above the cap the platform refuses with `validation_error` rather than trimming. */
+    limit?: number;
+    /** The previous page's `next_cursor`. Send it back rather than computing one. */
+    beforeSeq?: number;
+    /** Only runs that started at or after this unix timestamp in milliseconds; with `toMs` the window is half-open, `[from, to)`. */
+    fromMs?: number;
+    /** Only runs that started before this unix timestamp in milliseconds. */
+    toMs?: number;
+}
 /**
  * Robot-wide job reads, reachable as `client.jobs` — addressed by robot,
  * not slug, which `actions` and `services` cannot do.
@@ -1883,11 +2080,11 @@ interface JobsApi {
      * way an app developer reaches them.
      *
      * At most one entry per slug: the current job there, same as a per-slug
-     * read would answer. Not a history endpoint. Grant-filtered same as
-     * `cameras.list`/`datapoints` — an end user or server key sees only jobs
-     * on slugs their role grants, a developer session sees every job on the
-     * robot. Never empty-vs-missing ambiguity: a robot doing nothing
-     * resolves `[]`.
+     * read would answer. Not a history endpoint — that is `history` below.
+     * Grant-filtered same as `cameras.list`/`datapoints` — an end user or
+     * server key sees only jobs on slugs their role grants, a developer
+     * session sees every job on the robot. Never empty-vs-missing ambiguity:
+     * a robot doing nothing resolves `[]`.
      *
      * **Ordered newest first by `started_at`, with `job.seq` as the
      * tiebreaker** (`started_at` alone is not a total order — two jobs minted
@@ -1900,6 +2097,26 @@ interface JobsApi {
      * hour-long one was only just adopted.
      */
     list(robotId: string): Promise<Job[]>;
+    /**
+     * What *has* run on this robot: one row per run, newest first by the
+     * durable `seq`, with its actor, its outcome and its `duration_ms`, kept
+     * for 90 days. The durable counterpart of `list`.
+     *
+     * **Needs the `action_history` capability** on the caller's role, or it
+     * rejects `capability_required`. An app user sees only runs on the slugs
+     * their role grants; a developer session sees the whole robot.
+     *
+     * **Page until `next_cursor` is `null`, never until a page looks short.**
+     * The cloud applies the role's grants to the page it already read, so a
+     * page can come back thin — or empty — with a perfectly good non-null
+     * cursor behind it. `runs.length === 0` is not an end-of-data signal.
+     *
+     * It lags realtime by a moment, deliberately: a run watched to completion
+     * over `actions.subscribe` can still read `running` here for an instant.
+     * Render the outcome from the realtime job you already have; use this for
+     * what you were not watching.
+     */
+    history(robotId: string, options?: JobHistoryOptions): Promise<JobRunListResponse>;
 }
 
 /**
@@ -1928,6 +2145,57 @@ interface PublishersApi {
     publish(robotId: string, slug: string, message: Record<string, unknown>, options?: SendCommandOptions): Promise<void>;
 }
 
+/**
+ * One row of a datasheet's `exposures`: a granted datapoint, action, service,
+ * publisher or camera, with its `slug`, `kind`, `description` (or `null`),
+ * a datapoint's `unit` and `decimals`, and for anything that takes
+ * parameters the JSON Schema under `input_schema`. The wire shape is
+ * contracts' `mcpExposure`; the alias exists so the reference can describe it.
+ */
+type McpExposure = McpExposure$1;
+/**
+ * The two role capabilities a datasheet names beyond slugs: `action_history`
+ * (may `jobs.history` be read) and `assets` (may the URDF and meshes be read).
+ * The wire shape is contracts' `mcpCapabilities`.
+ */
+type McpCapabilities = McpCapabilities$1;
+/**
+ * Discovery, reachable as `client.robots`: which robots may I name at all,
+ * and what may I do on one. The two calls every app screen starts from;
+ * every other namespace takes a `robotId` that came from here.
+ *
+ * The answers are the caller's role made visible — the same rows and the
+ * same datasheet the MCP tools `robots_list` and `robot_describe` answer,
+ * from the same code on the server. There is no client-side filtering to
+ * do and nothing to cache: a role change shows at the next call.
+ */
+interface RobotsApi {
+    /**
+     * The robots this caller reaches, in name order with the id as the tiebreak.
+     *
+     * An app user reaches the robots their app attaches on which their role
+     * grants at least one slug or capability; a server key reaches every robot
+     * its app attaches. A robot the role grants nothing on is absent rather
+     * than listed empty — reach is a grant, not an attachment — so a new app
+     * whose built-in roles grant nothing yet resolves `[]`, and that is the
+     * console's Roles tab talking, not a broken login.
+     */
+    list(): Promise<ClientRobotListItem[]>;
+    /**
+     * Everything the caller's role lets them do on one robot: every granted
+     * datapoint (with `unit` and `decimals`), action, service and publisher
+     * (with the parameter JSON Schema under `input_schema`) and camera, plus
+     * the two capabilities that gate whole features, `action_history` and
+     * `assets`. A robot with nothing published resolves an empty `exposures`
+     * list. One the caller does not reach rejects `not_found`, exactly as a
+     * robot that does not exist — never `forbidden`, which would say it exists.
+     *
+     * The type is `McpRobotDatasheet` because the MCP server answered it first;
+     * the prefix is history, not scope.
+     */
+    describe(robotId: string): Promise<McpRobotDatasheet>;
+}
+
 /**
  * Request/response calls to a robot, reachable as `client.services`. A
  * service answers once and is done — one method, nothing to subscribe to.
@@ -2037,6 +2305,8 @@ interface FleetlessClient {
     readonly jobs: JobsApi;
     /** URDF and mesh reads — list/get/urdf, plus the `urdf-loader` mesh callback. */
     readonly assets: AssetsApi;
+    /** Which robots this caller reaches, and what their role lets them do on each — the calls every screen starts from. */
+    readonly robots: RobotsApi;
     /**
      * Closes the realtime channel and stops it from reconnecting. Safe with
      * no subscription ever made, and safe to call twice. A Node script (the
@@ -2060,4 +2330,4 @@ interface FleetlessClient {
  */
 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 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 JobState, type JobSubscription, type JobSubscriptionHandlers, type JobsApi, type McpConsentGrant, type McpInteractionDecision, type MeshLoaderDelegate, type OidcLoginRequest, type ParameterInvalidDetails, type ParameterViolation, type PrepareUrdfSceneOptions, type ProviderButton, type PublishersApi, type RateLimitDetails, type RegisterOptions, 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 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 };