@steerpane/sdk 0.0.0-stage → 0.2.0

package/dist/client.d.ts

@@ -0,0 +1,409 @@
+import { APIError } from "./errors.js";
+import type { ActionGuard, ActionGuardRule, ActionGuardUnlock, AgentRun, CaptchaSolveResult, Capture, Credential, CrawlJob, Device, DevicePairingCode, EmbedLink, EndUser, FetchResult, HelpRequest, HumanResult, Json, Page, Profile, SearchResponse, SecretFillResult, Session, StoredFile, UploadUrl, WaitForCodeOptions, WaitForCodeResult, Webhook, WebhookDelivery } from "./types.js";
+export declare const DEFAULT_BASE_URL = "https://api.steerpane.app";
+export interface SteerpaneOptions {
+    /** Falls back to `STEERPANE_API_TOKEN`. */
+    token?: string;
+    /** Falls back to `STEERPANE_API_URL`, then `DEFAULT_BASE_URL`. */
+    baseUrl?: string;
+    timeoutMs?: number;
+    maxRetries?: number;
+    /** Allow sending the token over plain http to a host that isn't local. */
+    allowInsecureHttp?: boolean;
+    /** Replace `fetch`, for tests. */
+    fetch?: typeof fetch;
+    /** Who your program is, e.g. "Acme support bot" (falls back to `STEERPANE_AGENT_NAME`). The dashboard shows it on the sessions it
+     *  drives, their activity and the agent cursor (sent as `X-Steerpane-Agent`). Without it the token's name is shown. */
+    agentName?: string;
+}
+interface RequestOptions {
+    json?: unknown;
+    params?: Record<string, unknown>;
+    headers?: Record<string, string>;
+    body?: FormData;
+    timeoutMs?: number;
+}
+/** Browser actions, `POST /v1/sessions/{id}/actions`. While a human holds control, acting calls throw `HumanInControlError` and queue. */
+declare class Actions {
+    private readonly c;
+    constructor(c: Steerpane);
+    /** Run any action type. `waitS` holds the call until a takeover ends instead of throwing, up to 600 seconds. */
+    run<T = Json>(sessionId: string, type: string, args?: Json, options?: {
+        waitS?: number;
+    }): Promise<T>;
+    navigate(sessionId: string, url: string, args?: Json): Promise<Json>;
+    click(sessionId: string, selector: string, args?: Json): Promise<Json>;
+    type(sessionId: string, selector: string, text: string, args?: Json): Promise<Json>;
+    pressKey(sessionId: string, key: string, args?: Json): Promise<Json>;
+    selectOption(sessionId: string, selector: string, option: string, args?: Json): Promise<Json>;
+    scroll(sessionId: string, args?: Json): Promise<Json>;
+    /** Exactly one of `selector` (+ `state`), `text`, `url`, `load_state` or `ms`. `timeout_ms` defaults to 10000. */
+    waitFor(sessionId: string, args: Json): Promise<Json>;
+    snapshot(sessionId: string, args?: Json): Promise<Json>;
+    getPageText(sessionId: string, args?: Json): Promise<{
+        text: string;
+    } & Json>;
+    elementState(sessionId: string, selector: string, args?: Json): Promise<Json>;
+    formFields(sessionId: string, args?: Json): Promise<{
+        fields: Json[];
+    } & Json>;
+    screenshot(sessionId: string, args?: Json): Promise<Json>;
+    /** Run JavaScript in the page. `code` is a function body, so use `return` to get a value back as `result`. */
+    execute<R = unknown>(sessionId: string, code: string, args?: Json): Promise<{
+        result: R;
+    } & Json>;
+    /** Needs a model key on the organization. */
+    extract(sessionId: string, instruction: string, args?: Json): Promise<Json>;
+    download(sessionId: string, args?: Json): Promise<Json>;
+    uploadFile(sessionId: string, args?: Json): Promise<Json>;
+    /** Type a value you hold (a password, an access code) into ONE field of the page, on the site you name. `POST /v1/sessions/{id}/secret-fill`; needs the `vault:use` scope.
+     * The runtime checks the origin of the frame holding the field against `site` in the same step that types (`exact: true`: the host must match exactly, no subdomains).
+     * `kind` is `password` (default; the field must be a password input) or `code`. `submit` and `exact` must be real booleans.
+     *
+     * The value is never logged, recorded, queued or returned (the result shows `value: "••••••"`). The SDK doesn't echo it either, and this call is NEVER retried: no
+     * automatic retry, no Idempotency-Key (the API refuses one). Treat every failure that isn't a definitive refusal before typing (`origin_mismatch`, `insecure_origin`,
+     * `field_type_mismatch`, `element_not_found`, ...) as "maybe typed": look at the page before you send it again.
+     * **`typed: true` in the result, or a 409 with `details.typed`, means the value is already in the page: do not send it again.** A human in control or a paused agent
+     * answers 409 `human_in_control` with nothing typed; a secret is never queued. */
+    secretFill(sessionId: string, input: {
+        site: string;
+        selector: string;
+        value: string;
+        kind?: "password" | "code";
+        submit?: boolean;
+        exact?: boolean;
+        frame?: string;
+    }): Promise<SecretFillResult>;
+    /** Type a stored credential into the page. The secret never comes back. Refused off the credential's site. */
+    vaultFill(sessionId: string, credentialId: string, args?: Json): Promise<Json>;
+}
+declare class Sessions {
+    private readonly c;
+    constructor(c: Steerpane);
+    list(params?: {
+        status?: string;
+        profile_id?: string;
+        q?: string;
+        project_id?: string;
+        end_user_id?: string;
+        limit?: number;
+        cursor?: string | null;
+    }): Promise<Page<Session>>;
+    /** Start a browser. `config` takes the session fields in the API docs, such as `initial_url`, `profile_id`, `end_user_id`, `auto_close`, `timeout_min`.
+     * `profile_wait: { timeout_s: 300 }` queues behind the profile's current writer instead of failing with 409 `profile_locked`: the session comes back with
+     * `status: "queued"` and `queue_position`; stop it to cancel. Without `profile_id` you get a throwaway browser that saves nothing. */
+    create(config?: Json, options?: {
+        idempotencyKey?: string;
+    }): Promise<Session>;
+    get(sessionId: string): Promise<Session>;
+    /** Wait for the browser to leave `starting` (and `queued`, for a session created with `profile_wait`: raise `timeoutS` to cover the wait). Throws if it ends instead, or doesn't start in time. */
+    waitUntilReady(sessionId: string, options?: {
+        timeoutS?: number;
+        pollS?: number;
+    }): Promise<Session>;
+    stop(sessionId: string): Promise<Session>;
+    delete(sessionId: string): Promise<void>;
+    keepalive(sessionId: string): Promise<Session>;
+    takeover(sessionId: string): Promise<Session>;
+    /** Give control back. The waiting agent receives `outcome` and `note`. */
+    handback(sessionId: string, input?: {
+        outcome?: "done" | "not_done";
+        note?: string;
+    }): Promise<Session>;
+    /** Name what the agent may not click or submit without approval. `rules` replaces the current ones; `[]` removes the guard. A blocked action fails with the
+     * `action_guard_blocked` error code until `unlockAction` is called. The service ships no rules of its own. */
+    setActionGuard(sessionId: string, rules: ActionGuardRule[]): Promise<ActionGuard>;
+    getActionGuard(sessionId: string): Promise<ActionGuard>;
+    removeActionGuard(sessionId: string): Promise<void>;
+    /** Approve ONE blocked gesture (the next matching click, Enter-submit or form submit, optionally only for `ruleId`) within `ttlS` seconds (1 to 120, default 30). Needs the `takeover` scope.
+     * The result's `late_targets` counts frames where a page script may have registered a listener ahead of the guard; if you need certainty, decline to rely on the guard when it is above 0.
+     * An action that spends the unlock returns `unlock_spent: true`, and an error it ends with carries `details.unlock_spent: true` (read it from `APIError.details`/`ToolError.details`): the act may have happened, so never click again, whatever the error.
+     * A session whose guard can't be installed refuses guarded actions with `action_guard_unavailable`. */
+    unlockAction(sessionId: string, options?: {
+        ruleId?: string;
+        ttlS?: number;
+    }): Promise<ActionGuardUnlock>;
+    /** Run the CAPTCHA solver on the session's page. One call waits about 45 s: while `status` is `in_progress`, call again (the worker keeps running, it never restarts).
+     * `onFailure` is `wait_for_human` (default), `request_help` or `return`. Needs a CAPTCHA model on the organization. */
+    solveCaptcha(sessionId: string, options?: {
+        onFailure?: "wait_for_human" | "request_help" | "return";
+        maxReloads?: number;
+        model?: string;
+        captchaImageSelector?: string;
+        captchaInputSelector?: string;
+    }): Promise<CaptchaSolveResult>;
+    /** Ask a person for help. The agent goes on hold, and `agent.human_help_requested` fires. */
+    requestHelp(sessionId: string, input: {
+        reason: string;
+        message?: string;
+    }): Promise<HelpRequest>;
+    /** Long-poll until the human hands back. `status` is `handed_back`, `timeout` (call again) or `stopped`. */
+    waitForHuman(sessionId: string, options?: {
+        requestId?: string;
+        timeoutS?: number;
+    }): Promise<HumanResult>;
+    events(sessionId: string, params?: {
+        limit?: number;
+        cursor?: string | null;
+    }): Promise<Page<Json>>;
+    files(sessionId: string): Promise<Json>;
+    /** Pack what the session downloaded into one ZIP in the file store. */
+    zipFiles(sessionId: string): Promise<Json>;
+}
+declare class Profiles {
+    private readonly c;
+    constructor(c: Steerpane);
+    list(params?: {
+        tag?: string;
+        q?: string;
+        end_user_id?: string;
+        limit?: number;
+        cursor?: string | null;
+    }): Promise<Page<Profile>>;
+    get(profileId: string): Promise<Profile>;
+    /** `fields` include `end_user_id` to give the profile to one of your end users. */
+    create(name: string, fields?: Json): Promise<Profile>;
+    update(profileId: string, fields: Json): Promise<Profile>;
+    delete(profileId: string): Promise<void>;
+    clone(profileId: string): Promise<Profile>;
+    /** Really load each signed-in site with the profile's state, and report whether it is still signed in. */
+    verify(profileId: string, input?: {
+        domains?: string[];
+    }): Promise<Json>;
+    lock(profileId: string): Promise<Json>;
+    importCookies(profileId: string, cookies: Json[]): Promise<{
+        imported: number;
+    }>;
+}
+/** Your own customers. Profiles and sessions can belong to one; a session only uses profiles of its own end user. */
+declare class EndUsers {
+    private readonly c;
+    constructor(c: Steerpane);
+    /** Idempotent on `external_id`: calling it again returns the existing end user unchanged. */
+    create(externalId: string, fields?: {
+        name?: string;
+        metadata?: Record<string, string>;
+    }): Promise<EndUser>;
+    list(params?: {
+        external_id?: string;
+        limit?: number;
+        cursor?: string | null;
+    }): Promise<Page<EndUser>>;
+    get(endUserId: string): Promise<EndUser>;
+    update(endUserId: string, fields: {
+        name?: string;
+        metadata?: Record<string, string>;
+        disabled?: boolean;
+    }): Promise<EndUser>;
+    /** 409 while it owns profiles or live sessions; `cascade: true` deletes its profiles too (never while a session is live). */
+    delete(endUserId: string, options?: {
+        cascade?: boolean;
+    }): Promise<void>;
+    /** A single-use code (valid a few minutes) to hand to this end user so they can pair their own computer. Answers 404 while devices are off for the service. */
+    createDevicePairingCode(endUserId: string): Promise<DevicePairingCode>;
+}
+/** Computers that run sessions: yours, shared ones, and your end users'. Answers 404 while devices are off for the service. */
+declare class Devices {
+    private readonly c;
+    constructor(c: Steerpane);
+    /** `scope` is `user`, `org` or `end_user`; `end_user_id` narrows to one end user's devices. Capped at 200, no cursor. */
+    list(params?: {
+        scope?: "user" | "org" | "end_user";
+        end_user_id?: string;
+    }): Promise<{
+        data: Device[];
+    }>;
+    get(deviceId: string): Promise<Device>;
+}
+/** Hosted agent runs. These use your organization's own model key. */
+declare class Runs {
+    private readonly c;
+    constructor(c: Steerpane);
+    /** `fields`: `profile_id`, `agent_id`, `model`, `max_steps`, `max_cost_usd`, `max_duration_s`, `result_schema`, `variables`, `project_id`. */
+    create(task: string, fields?: Json, options?: {
+        idempotencyKey?: string;
+    }): Promise<AgentRun>;
+    get(runId: string): Promise<AgentRun>;
+    list(params?: {
+        status?: string;
+        agent_id?: string;
+        project_id?: string;
+        limit?: number;
+        cursor?: string | null;
+    }): Promise<Page<AgentRun>>;
+    messages(runId: string): Promise<Page<Json>>;
+    cancel(runId: string): Promise<AgentRun>;
+    /** Poll until the run finishes. Returns the run whatever its outcome, so check `status`. */
+    wait(runId: string, options?: {
+        timeoutS?: number;
+        pollS?: number;
+    }): Promise<AgentRun>;
+}
+declare class Files {
+    private readonly c;
+    constructor(c: Steerpane);
+    /** Store a file: a path, or bytes with `name`. The result's `id` goes straight into `actions.uploadFile(sessionId, { file_id })`. */
+    upload(file: string | Uint8Array, options?: {
+        name?: string;
+        mime?: string;
+        ttlHours?: number;
+    }): Promise<StoredFile>;
+    createUploadUrl(name: string, fields?: {
+        mime?: string;
+        size_bytes?: number;
+        ttl_hours?: number;
+    }): Promise<UploadUrl>;
+    list(params?: {
+        source?: string;
+        session_id?: string;
+        q?: string;
+        limit?: number;
+        cursor?: string | null;
+    }): Promise<Page<StoredFile>>;
+    get(fileId: string): Promise<StoredFile>;
+    /** The file's bytes. On S3 storage the API redirects to a presigned URL, which `fetch` follows without your token. */
+    download(fileId: string): Promise<Uint8Array>;
+    delete(fileId: string): Promise<void>;
+}
+/** Links that show a session inside your own product. Scale and Enterprise plans. The URL is a credential: keep it out of logs. */
+declare class Embeds {
+    private readonly c;
+    constructor(c: Steerpane);
+    create(sessionId: string, config?: {
+        allow_takeover?: boolean;
+        allowed_origins?: string[];
+        expires_in_min?: number;
+        hide_toolbar?: boolean;
+        show_control?: boolean;
+        theme?: string;
+        end_user?: {
+            id: string;
+            name?: string;
+        };
+        mode?: string;
+    }): Promise<EmbedLink>;
+    list(params?: {
+        session_id?: string;
+        limit?: number;
+        cursor?: string | null;
+    }): Promise<Page<EmbedLink>>;
+    /** Closes open iframes at once, and returns control to the agent if this link held it. */
+    revoke(linkId: string): Promise<EmbedLink>;
+}
+/** Endpoint management. To check a delivery's signature use `verifySignature`, which needs no client. */
+declare class Webhooks {
+    private readonly c;
+    constructor(c: Steerpane);
+    list(): Promise<Page<Webhook>>;
+    create(url: string, events: string[], fields?: Json): Promise<Webhook>;
+    get(webhookId: string): Promise<Webhook>;
+    delete(webhookId: string): Promise<void>;
+    sendTest(webhookId: string, input?: {
+        event?: string;
+    }): Promise<WebhookDelivery>;
+}
+/** Stored logins. Passwords and TOTP secrets go in and never come back to an API token. */
+declare class Vault {
+    private readonly c;
+    constructor(c: Steerpane);
+    list(): Promise<Page<Credential>>;
+    create(input: {
+        domain: string;
+        username: string;
+        password: string;
+        name?: string;
+        totp_secret?: string;
+        profile_ids?: string[];
+        token_ids?: string[];
+    }): Promise<Credential>;
+    delete(credentialId: string): Promise<void>;
+}
+declare class Crawls {
+    private readonly c;
+    constructor(c: Steerpane);
+    /** `options`: `limit`, `max_depth`, `mode`, `formats`, `include_paths`, `exclude_paths`, `check_links`, `same_site`, ... */
+    start(url: string, options?: Json): Promise<CrawlJob>;
+    get(jobId: string, params?: {
+        cursor?: string | number | null;
+        limit?: number;
+        include_content?: boolean;
+    }): Promise<CrawlJob>;
+    cancel(jobId: string): Promise<CrawlJob>;
+    wait(jobId: string, options?: {
+        timeoutS?: number;
+        pollS?: number;
+    }): Promise<CrawlJob>;
+}
+/** Call MCP tools over the API's Streamable HTTP endpoint. A few tools are MCP only, such as `act`, `observe` and `wait_for_code`. */
+declare class Mcp {
+    private readonly c;
+    private sessionId;
+    private nextId;
+    constructor(c: Steerpane);
+    private post;
+    private ensureSession;
+    /** The default list: core tools plus `search_tools` and `call_tool`. Any tool still runs by name with `call`. */
+    listTools(): Promise<Json[]>;
+    /** Run a tool and return its JSON result. A tool failure throws `ToolError` with the API's error code. */
+    call<T = Json>(tool: string, args?: Json, options?: {
+        timeoutS?: number;
+    }): Promise<T>;
+    /** Wait for an email or SMS verification code (the MCP tool `wait_for_code`). With `sessionId` the code is typed into the page and never reaches you
+     * (`status: "entered"`); with `returnCode: true` you get it back (`status: "received"`). The server answers in rounds of about 45 s with `status: "waiting"`:
+     * this keeps calling, with the `started_at` it was given, until the code arrives or `timeoutS` runs out (`status: "timeout"`), so the result is always final.
+     * Needs the `vault:use` scope and a code source set up on the organization. */
+    waitForCode(options?: WaitForCodeOptions): Promise<WaitForCodeResult>;
+}
+/** Client for the Steerpane API. */
+export declare class Steerpane {
+    readonly baseUrl: string;
+    readonly timeoutMs: number;
+    readonly maxRetries: number;
+    /** Sent as X-Steerpane-Agent: the name the dashboard shows for this program. */
+    readonly agentName: string | undefined;
+    /** The token, for helpers that need it. Not enumerable, so logging the client doesn't print it. */
+    readonly token: string;
+    private readonly fetchImpl;
+    readonly sessions: Sessions;
+    readonly actions: Actions;
+    readonly profiles: Profiles;
+    readonly endUsers: EndUsers;
+    readonly devices: Devices;
+    readonly runs: Runs;
+    readonly files: Files;
+    readonly embeds: Embeds;
+    readonly webhooks: Webhooks;
+    readonly vault: Vault;
+    readonly crawls: Crawls;
+    readonly mcp: Mcp;
+    constructor(options?: SteerpaneOptions);
+    /** One HTTP call with your token and the retry rules. Doesn't throw on an error status. */
+    rawRequest(method: string, path: string, options?: RequestOptions): Promise<Response>;
+    /** Call any endpoint, for what this client has no method for. Returns the parsed body, or throws `APIError`. */
+    request<T = unknown>(method: string, path: string, options?: RequestOptions): Promise<T>;
+    /** Every item across pages: `for await (const s of client.paginate((p) => client.sessions.list({ ...p, status: "live" })))`. */
+    paginate<T>(listCall: (page: {
+        cursor: string | null;
+    }) => Promise<Page<T>>): AsyncGenerator<T>;
+    /** Fetch a page without a browser session. `mode` is `fast`, `deep` or `auto`. The site's own status is in the result's `status`. */
+    fetch(url: string, options?: {
+        format?: string;
+        mode?: string;
+        formats?: string[];
+    } & Json): Promise<FetchResult>;
+    fetchBatch(urls: string[], options?: Json): Promise<Json>;
+    search(query: string, options?: {
+        limit?: number;
+    }): Promise<SearchResponse>;
+    screenshot(url: string, options?: Json): Promise<Capture>;
+    pdf(url: string, options?: Json): Promise<Capture>;
+    map(url: string, options?: Json): Promise<Json>;
+    /** Structured data from up to 10 URLs. Needs a model key on the organization. */
+    extract(input: {
+        instruction: string;
+        url?: string;
+        urls?: string[];
+        schema?: Json;
+    } & Json): Promise<Json>;
+}
+export { APIError };