@steerpane/sdk 0.0.0-stage → 0.2.0

package/dist/client.js

@@ -0,0 +1,506 @@
+import { readFile } from "node:fs/promises";
+import { basename } from "node:path";
+import { APIError, errorFromResponse, SteerpaneError, ToolError } from "./errors.js";
+import { VERSION } from "./version.js";
+export const DEFAULT_BASE_URL = "https://api.steerpane.app";
+const LOCAL_HOSTS = new Set(["localhost", "127.0.0.1", "[::1]"]);
+const RETRY_STATUSES = new Set([502, 503, 504]);
+const MCP_PROTOCOL = "2025-06-18";
+const seg = (value) => encodeURIComponent(String(value));
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+const clean = (values) => Object.fromEntries(Object.entries(values).filter(([, v]) => v !== undefined && v !== null));
+const retryAfterOf = (res) => {
+    const v = Number(res.headers.get("retry-after"));
+    return res.headers.has("retry-after") && Number.isFinite(v) ? v : null;
+};
+async function parse(res) {
+    const text = await res.text();
+    if (!text)
+        return null;
+    if ((res.headers.get("content-type") ?? "").includes("json"))
+        return JSON.parse(text);
+    return text;
+}
+/** Browser actions, `POST /v1/sessions/{id}/actions`. While a human holds control, acting calls throw `HumanInControlError` and queue. */
+class Actions {
+    c;
+    constructor(c) {
+        this.c = c;
+    }
+    /** Run any action type. `waitS` holds the call until a takeover ends instead of throwing, up to 600 seconds. */
+    run(sessionId, type, args = {}, options = {}) {
+        const headers = options.waitS === undefined ? {} : { "Steerpane-Wait": String(options.waitS) };
+        return this.c.request("POST", `/v1/sessions/${seg(sessionId)}/actions`, { json: { type, ...clean(args) }, headers, timeoutMs: Math.max(this.c.timeoutMs, ((options.waitS ?? 0) + 30) * 1000) });
+    }
+    navigate(sessionId, url, args = {}) { return this.run(sessionId, "navigate", { url, ...args }); }
+    click(sessionId, selector, args = {}) { return this.run(sessionId, "click", { selector, ...args }); }
+    type(sessionId, selector, text, args = {}) { return this.run(sessionId, "type", { selector, text, ...args }); }
+    pressKey(sessionId, key, args = {}) { return this.run(sessionId, "press_key", { key, ...args }); }
+    selectOption(sessionId, selector, option, args = {}) { return this.run(sessionId, "select_option", { selector, option, ...args }); }
+    scroll(sessionId, args = {}) { return this.run(sessionId, "scroll", args); }
+    /** Exactly one of `selector` (+ `state`), `text`, `url`, `load_state` or `ms`. `timeout_ms` defaults to 10000. */
+    waitFor(sessionId, args) { return this.run(sessionId, "wait_for", args); }
+    snapshot(sessionId, args = {}) { return this.run(sessionId, "snapshot", args); }
+    getPageText(sessionId, args = {}) { return this.run(sessionId, "get_page_text", args); }
+    elementState(sessionId, selector, args = {}) { return this.run(sessionId, "element_state", { selector, ...args }); }
+    formFields(sessionId, args = {}) { return this.run(sessionId, "form_fields", args); }
+    screenshot(sessionId, args = {}) { return this.run(sessionId, "screenshot", args); }
+    /** Run JavaScript in the page. `code` is a function body, so use `return` to get a value back as `result`. */
+    execute(sessionId, code, args = {}) { return this.run(sessionId, "execute", { code, ...args }); }
+    /** Needs a model key on the organization. */
+    extract(sessionId, instruction, args = {}) { return this.run(sessionId, "extract", { instruction, ...args }); }
+    download(sessionId, args = {}) { return this.run(sessionId, "download", args); }
+    uploadFile(sessionId, args = {}) { return this.run(sessionId, "upload_file", args); }
+    /** 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, input) {
+        return this.c.request("POST", `/v1/sessions/${seg(sessionId)}/secret-fill`, { json: clean(input) });
+    }
+    /** Type a stored credential into the page. The secret never comes back. Refused off the credential's site. */
+    vaultFill(sessionId, credentialId, args = {}) { return this.run(sessionId, "vault_fill", { credential_id: credentialId, ...args }); }
+}
+class Sessions {
+    c;
+    constructor(c) {
+        this.c = c;
+    }
+    list(params = {}) {
+        return this.c.request("GET", "/v1/sessions", { params });
+    }
+    /** 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 = {}, options = {}) {
+        return this.c.request("POST", "/v1/sessions", { json: clean(config), headers: { "Idempotency-Key": options.idempotencyKey ?? crypto.randomUUID() } });
+    }
+    get(sessionId) { return this.c.request("GET", `/v1/sessions/${seg(sessionId)}`); }
+    /** 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. */
+    async waitUntilReady(sessionId, options = {}) {
+        const timeoutS = options.timeoutS ?? 90;
+        const deadline = Date.now() + timeoutS * 1000;
+        for (;;) {
+            const session = await this.get(sessionId);
+            if (session.status === "stopped" || session.status === "error")
+                throw new SteerpaneError(`Session ${sessionId} ended before it was ready: ${session.error_message ?? session.status}`);
+            if (session.status !== "starting" && session.status !== "queued")
+                return session;
+            if (Date.now() >= deadline)
+                throw new SteerpaneError(`Session ${sessionId} was still ${session.status} after ${timeoutS} s`);
+            await sleep((options.pollS ?? 0.5) * 1000);
+        }
+    }
+    stop(sessionId) { return this.c.request("POST", `/v1/sessions/${seg(sessionId)}/stop`); }
+    async delete(sessionId) { await this.c.request("DELETE", `/v1/sessions/${seg(sessionId)}`); }
+    keepalive(sessionId) { return this.c.request("POST", `/v1/sessions/${seg(sessionId)}/keepalive`); }
+    takeover(sessionId) { return this.c.request("POST", `/v1/sessions/${seg(sessionId)}/takeover`); }
+    /** Give control back. The waiting agent receives `outcome` and `note`. */
+    handback(sessionId, input = {}) {
+        return this.c.request("POST", `/v1/sessions/${seg(sessionId)}/handback`, { json: clean(input) });
+    }
+    /** 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, rules) { return this.c.request("PUT", `/v1/sessions/${seg(sessionId)}/action-guard`, { json: { rules } }); }
+    getActionGuard(sessionId) { return this.c.request("GET", `/v1/sessions/${seg(sessionId)}/action-guard`); }
+    async removeActionGuard(sessionId) { await this.c.request("DELETE", `/v1/sessions/${seg(sessionId)}/action-guard`); }
+    /** 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, options = {}) {
+        return this.c.request("POST", `/v1/sessions/${seg(sessionId)}/action-guard/unlock`, { json: clean({ rule_id: options.ruleId, ttl_s: options.ttlS }) });
+    }
+    /** 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, options = {}) {
+        return this.c.request("POST", `/v1/sessions/${seg(sessionId)}/captcha/solve`, {
+            json: clean({ on_failure: options.onFailure, max_reloads: options.maxReloads, model: options.model, captcha_image_selector: options.captchaImageSelector, captcha_input_selector: options.captchaInputSelector }),
+            timeoutMs: Math.max(this.c.timeoutMs, 90_000),
+        });
+    }
+    /** Ask a person for help. The agent goes on hold, and `agent.human_help_requested` fires. */
+    requestHelp(sessionId, input) {
+        return this.c.request("POST", `/v1/sessions/${seg(sessionId)}/help-requests`, { json: { message: "", ...input } });
+    }
+    /** Long-poll until the human hands back. `status` is `handed_back`, `timeout` (call again) or `stopped`. */
+    waitForHuman(sessionId, options = {}) {
+        const timeoutS = options.timeoutS ?? 30;
+        return this.c.request("GET", `/v1/sessions/${seg(sessionId)}/help-requests/${seg(options.requestId ?? "latest")}/wait`, {
+            params: { timeout_s: timeoutS }, timeoutMs: Math.max(this.c.timeoutMs, (timeoutS + 30) * 1000),
+        });
+    }
+    events(sessionId, params = {}) { return this.c.request("GET", `/v1/sessions/${seg(sessionId)}/events`, { params }); }
+    files(sessionId) { return this.c.request("GET", `/v1/sessions/${seg(sessionId)}/files`); }
+    /** Pack what the session downloaded into one ZIP in the file store. */
+    zipFiles(sessionId) { return this.c.request("POST", `/v1/sessions/${seg(sessionId)}/files/zip`); }
+}
+class Profiles {
+    c;
+    constructor(c) {
+        this.c = c;
+    }
+    list(params = {}) { return this.c.request("GET", "/v1/profiles", { params }); }
+    get(profileId) { return this.c.request("GET", `/v1/profiles/${seg(profileId)}`); }
+    /** `fields` include `end_user_id` to give the profile to one of your end users. */
+    create(name, fields = {}) { return this.c.request("POST", "/v1/profiles", { json: { name, ...clean(fields) } }); }
+    update(profileId, fields) { return this.c.request("PATCH", `/v1/profiles/${seg(profileId)}`, { json: fields }); }
+    async delete(profileId) { await this.c.request("DELETE", `/v1/profiles/${seg(profileId)}`); }
+    clone(profileId) { return this.c.request("POST", `/v1/profiles/${seg(profileId)}/clone`); }
+    /** Really load each signed-in site with the profile's state, and report whether it is still signed in. */
+    verify(profileId, input = {}) { return this.c.request("POST", `/v1/profiles/${seg(profileId)}/verify`, { json: clean(input), timeoutMs: Math.max(this.c.timeoutMs, 90_000) }); }
+    lock(profileId) { return this.c.request("GET", `/v1/profiles/${seg(profileId)}/lock`); }
+    importCookies(profileId, cookies) { return this.c.request("POST", `/v1/profiles/${seg(profileId)}/cookies/import`, { json: { cookies } }); }
+}
+/** Your own customers. Profiles and sessions can belong to one; a session only uses profiles of its own end user. */
+class EndUsers {
+    c;
+    constructor(c) {
+        this.c = c;
+    }
+    /** Idempotent on `external_id`: calling it again returns the existing end user unchanged. */
+    create(externalId, fields = {}) {
+        return this.c.request("POST", "/v1/end-users", { json: clean({ external_id: externalId, ...fields }) });
+    }
+    list(params = {}) { return this.c.request("GET", "/v1/end-users", { params }); }
+    get(endUserId) { return this.c.request("GET", `/v1/end-users/${seg(endUserId)}`); }
+    update(endUserId, fields) {
+        return this.c.request("PATCH", `/v1/end-users/${seg(endUserId)}`, { json: clean(fields) });
+    }
+    /** 409 while it owns profiles or live sessions; `cascade: true` deletes its profiles too (never while a session is live). */
+    async delete(endUserId, options = {}) {
+        await this.c.request("DELETE", `/v1/end-users/${seg(endUserId)}`, { params: options.cascade ? { cascade: "true" } : {} });
+    }
+    /** 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) { return this.c.request("POST", `/v1/end-users/${seg(endUserId)}/device-pairing-codes`); }
+}
+/** Computers that run sessions: yours, shared ones, and your end users'. Answers 404 while devices are off for the service. */
+class Devices {
+    c;
+    constructor(c) {
+        this.c = c;
+    }
+    /** `scope` is `user`, `org` or `end_user`; `end_user_id` narrows to one end user's devices. Capped at 200, no cursor. */
+    list(params = {}) { return this.c.request("GET", "/v1/devices", { params }); }
+    get(deviceId) { return this.c.request("GET", `/v1/devices/${seg(deviceId)}`); }
+}
+/** Hosted agent runs. These use your organization's own model key. */
+class Runs {
+    c;
+    constructor(c) {
+        this.c = c;
+    }
+    /** `fields`: `profile_id`, `agent_id`, `model`, `max_steps`, `max_cost_usd`, `max_duration_s`, `result_schema`, `variables`, `project_id`. */
+    create(task, fields = {}, options = {}) {
+        return this.c.request("POST", "/v1/agents/runs", { json: { task, ...clean(fields) }, headers: { "Idempotency-Key": options.idempotencyKey ?? crypto.randomUUID() } });
+    }
+    get(runId) { return this.c.request("GET", `/v1/agents/runs/${seg(runId)}`); }
+    list(params = {}) { return this.c.request("GET", "/v1/agents/runs", { params }); }
+    messages(runId) { return this.c.request("GET", `/v1/agents/runs/${seg(runId)}/messages`); }
+    cancel(runId) { return this.c.request("POST", `/v1/agents/runs/${seg(runId)}/cancel`); }
+    /** Poll until the run finishes. Returns the run whatever its outcome, so check `status`. */
+    async wait(runId, options = {}) {
+        const timeoutS = options.timeoutS ?? 600;
+        const deadline = Date.now() + timeoutS * 1000;
+        for (;;) {
+            const run = await this.get(runId);
+            if (run.status === "completed" || run.status === "failed" || run.status === "cancelled")
+                return run;
+            if (Date.now() >= deadline)
+                throw new SteerpaneError(`Run ${runId} had not finished after ${timeoutS} s (status ${run.status})`);
+            await sleep((options.pollS ?? 2) * 1000);
+        }
+    }
+}
+class Files {
+    c;
+    constructor(c) {
+        this.c = c;
+    }
+    /** Store a file: a path, or bytes with `name`. The result's `id` goes straight into `actions.uploadFile(sessionId, { file_id })`. */
+    async upload(file, options = {}) {
+        const bytes = typeof file === "string" ? await readFile(file) : file;
+        const filename = options.name ?? (typeof file === "string" ? basename(file) : "file");
+        const form = new FormData();
+        form.append("file", new Blob([bytes], { type: options.mime ?? "application/octet-stream" }), filename);
+        if (options.name)
+            form.append("name", options.name);
+        if (options.ttlHours !== undefined)
+            form.append("ttl_hours", String(options.ttlHours));
+        return this.c.request("POST", "/v1/files", { body: form });
+    }
+    createUploadUrl(name, fields = {}) { return this.c.request("POST", "/v1/files/uploads", { json: { name, ...clean(fields) } }); }
+    list(params = {}) { return this.c.request("GET", "/v1/files", { params }); }
+    get(fileId) { return this.c.request("GET", `/v1/files/${seg(fileId)}`); }
+    /** The file's bytes. On S3 storage the API redirects to a presigned URL, which `fetch` follows without your token. */
+    async download(fileId) {
+        const res = await this.c.rawRequest("GET", `/v1/files/${seg(fileId)}/content`);
+        if (!res.ok)
+            throw errorFromResponse(res.status, await parse(res), retryAfterOf(res));
+        return new Uint8Array(await res.arrayBuffer());
+    }
+    async delete(fileId) { await this.c.request("DELETE", `/v1/files/${seg(fileId)}`); }
+}
+/** Links that show a session inside your own product. Scale and Enterprise plans. The URL is a credential: keep it out of logs. */
+class Embeds {
+    c;
+    constructor(c) {
+        this.c = c;
+    }
+    create(sessionId, config = {}) {
+        return this.c.request("POST", `/v1/sessions/${seg(sessionId)}/embed`, { json: { expires_in_min: 30, ...clean(config) } });
+    }
+    list(params = {}) { return this.c.request("GET", "/v1/embed-links", { params }); }
+    /** Closes open iframes at once, and returns control to the agent if this link held it. */
+    revoke(linkId) { return this.c.request("POST", `/v1/embed-links/${seg(linkId)}/revoke`); }
+}
+/** Endpoint management. To check a delivery's signature use `verifySignature`, which needs no client. */
+class Webhooks {
+    c;
+    constructor(c) {
+        this.c = c;
+    }
+    list() { return this.c.request("GET", "/v1/webhooks"); }
+    create(url, events, fields = {}) { return this.c.request("POST", "/v1/webhooks", { json: { url, events, ...clean(fields) } }); }
+    get(webhookId) { return this.c.request("GET", `/v1/webhooks/${seg(webhookId)}`); }
+    async delete(webhookId) { await this.c.request("DELETE", `/v1/webhooks/${seg(webhookId)}`); }
+    sendTest(webhookId, input = {}) { return this.c.request("POST", `/v1/webhooks/${seg(webhookId)}/test`, { json: clean(input) }); }
+}
+/** Stored logins. Passwords and TOTP secrets go in and never come back to an API token. */
+class Vault {
+    c;
+    constructor(c) {
+        this.c = c;
+    }
+    list() { return this.c.request("GET", "/v1/vault/credentials"); }
+    create(input) { return this.c.request("POST", "/v1/vault/credentials", { json: clean(input) }); }
+    async delete(credentialId) { await this.c.request("DELETE", `/v1/vault/credentials/${seg(credentialId)}`); }
+}
+class Crawls {
+    c;
+    constructor(c) {
+        this.c = c;
+    }
+    /** `options`: `limit`, `max_depth`, `mode`, `formats`, `include_paths`, `exclude_paths`, `check_links`, `same_site`, ... */
+    start(url, options = {}) { return this.c.request("POST", "/v1/crawl", { json: { url, ...clean(options) } }); }
+    get(jobId, params = {}) { return this.c.request("GET", `/v1/crawl/${seg(jobId)}`, { params }); }
+    cancel(jobId) { return this.c.request("DELETE", `/v1/crawl/${seg(jobId)}`); }
+    async wait(jobId, options = {}) {
+        const timeoutS = options.timeoutS ?? 300;
+        const deadline = Date.now() + timeoutS * 1000;
+        for (;;) {
+            const job = await this.get(jobId, { include_content: false });
+            if (job.status === "completed" || job.status === "failed" || job.status === "cancelled")
+                return job;
+            if (Date.now() >= deadline)
+                throw new SteerpaneError(`Crawl ${jobId} had not finished after ${timeoutS} s`);
+            await sleep((options.pollS ?? 2) * 1000);
+        }
+    }
+}
+/** Call MCP tools over the API's Streamable HTTP endpoint. A few tools are MCP only, such as `act`, `observe` and `wait_for_code`. */
+class Mcp {
+    c;
+    sessionId = null;
+    nextId = 0;
+    constructor(c) {
+        this.c = c;
+    }
+    async post(method, params, options = {}) {
+        const id = options.notify ? undefined : ++this.nextId;
+        const headers = { Accept: "application/json, text/event-stream", "Mcp-Protocol-Version": MCP_PROTOCOL };
+        if (this.sessionId)
+            headers["Mcp-Session-Id"] = this.sessionId;
+        const res = await this.c.rawRequest("POST", "/mcp", { json: { jsonrpc: "2.0", method, params, ...(id ? { id } : {}) }, headers, timeoutMs: options.timeoutMs });
+        if (res.status >= 400)
+            throw errorFromResponse(res.status, await parse(res), retryAfterOf(res));
+        this.sessionId = res.headers.get("mcp-session-id") ?? this.sessionId;
+        if (options.notify)
+            return null;
+        const text = await res.text();
+        let reply;
+        if ((res.headers.get("content-type") ?? "").includes("event-stream")) {
+            const frames = text.split(/\r?\n/).filter((l) => l.startsWith("data:")).map((l) => l.slice(5).trim()).filter(Boolean);
+            reply = frames.map((f) => JSON.parse(f)).find((m) => m.id === id);
+        }
+        else {
+            reply = JSON.parse(text);
+        }
+        if (!reply)
+            throw new SteerpaneError(`MCP ${method}: the server sent no reply`);
+        if (reply.error)
+            throw new SteerpaneError(`MCP ${method}: ${reply.error.message}`);
+        return reply.result ?? null;
+    }
+    async ensureSession() {
+        if (this.sessionId)
+            return;
+        await this.post("initialize", { protocolVersion: MCP_PROTOCOL, capabilities: {}, clientInfo: { name: "steerpane-sdk-node", version: VERSION } });
+        await this.post("notifications/initialized", {}, { notify: true });
+    }
+    /** The default list: core tools plus `search_tools` and `call_tool`. Any tool still runs by name with `call`. */
+    async listTools() {
+        await this.ensureSession();
+        return (await this.post("tools/list", {}))?.tools ?? [];
+    }
+    /** Run a tool and return its JSON result. A tool failure throws `ToolError` with the API's error code. */
+    async call(tool, args = {}, options = {}) {
+        await this.ensureSession();
+        const result = await this.post("tools/call", { name: tool, arguments: clean(args) }, { timeoutMs: (options.timeoutS ?? 120) * 1000 });
+        const text = result?.content?.find((c) => c.type === "text")?.text;
+        let payload = result?.structuredContent;
+        if (payload === undefined && text) {
+            try {
+                payload = JSON.parse(text);
+            }
+            catch {
+                payload = text;
+            }
+        }
+        if (result?.isError) {
+            const err = payload?.error;
+            throw new ToolError(tool, err?.code ?? "tool_error", err?.message ?? text ?? "Tool failed", err?.details ?? {});
+        }
+        return payload;
+    }
+    /** 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. */
+    async waitForCode(options = {}) {
+        const args = {
+            session_id: options.sessionId, profile_id: options.profileId, credential_id: options.credentialId, site: options.site, sender: options.sender, subject: options.subject,
+            timeout_s: options.timeoutS, max_age_s: options.maxAgeS, selector: options.selector, frame: options.frame, submit: options.submit, return_code: options.returnCode, code_id: options.codeId,
+        };
+        const timeoutS = options.timeoutS ?? 120;
+        for (let round = 0;; round++) {
+            const result = await this.call("wait_for_code", args, { timeoutS: 90 });
+            if (result.status !== "waiting")
+                return result;
+            if (round > timeoutS)
+                throw new SteerpaneError("wait_for_code kept answering 'waiting' past its own timeout");
+            args["started_at"] = result["started_at"];
+        }
+    }
+}
+/** Client for the Steerpane API. */
+export class Steerpane {
+    baseUrl;
+    timeoutMs;
+    maxRetries;
+    /** Sent as X-Steerpane-Agent: the name the dashboard shows for this program. */
+    agentName;
+    fetchImpl;
+    sessions = new Sessions(this);
+    actions = new Actions(this);
+    profiles = new Profiles(this);
+    endUsers = new EndUsers(this);
+    devices = new Devices(this);
+    runs = new Runs(this);
+    files = new Files(this);
+    embeds = new Embeds(this);
+    webhooks = new Webhooks(this);
+    vault = new Vault(this);
+    crawls = new Crawls(this);
+    mcp = new Mcp(this);
+    constructor(options = {}) {
+        const token = options.token ?? process.env["STEERPANE_API_TOKEN"];
+        if (!token)
+            throw new SteerpaneError("No API token. Pass token or set STEERPANE_API_TOKEN.");
+        Object.defineProperty(this, "token", { value: token, enumerable: false });
+        this.baseUrl = (options.baseUrl ?? process.env["STEERPANE_API_URL"] ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+        let url;
+        try {
+            url = new URL(this.baseUrl);
+        }
+        catch {
+            throw new SteerpaneError(`Invalid API URL: ${this.baseUrl}`);
+        }
+        if (url.protocol !== "https:" && url.protocol !== "http:")
+            throw new SteerpaneError(`Invalid API URL: ${this.baseUrl}`);
+        if (url.protocol === "http:" && !LOCAL_HOSTS.has(url.hostname) && !options.allowInsecureHttp) {
+            throw new SteerpaneError("Refusing to send an API token over plain http. Use https, or pass allowInsecureHttp: true.");
+        }
+        this.timeoutMs = options.timeoutMs ?? 60_000;
+        this.maxRetries = options.maxRetries ?? 2;
+        this.fetchImpl = options.fetch ?? fetch;
+        this.agentName = (options.agentName ?? process.env["STEERPANE_AGENT_NAME"] ?? "").trim().slice(0, 80) || undefined;
+    }
+    /** One HTTP call with your token and the retry rules. Doesn't throw on an error status. */
+    async rawRequest(method, path, options = {}) {
+        const query = new URLSearchParams();
+        for (const [k, v] of Object.entries(options.params ?? {}))
+            if (v !== undefined && v !== null)
+                query.set(k, String(v));
+        const url = this.baseUrl + path + (query.size ? `?${query}` : "");
+        const headers = {
+            Authorization: `Bearer ${this.token}`, "User-Agent": `steerpane-sdk-node/${VERSION}`,
+            ...(this.agentName ? { "X-Steerpane-Agent": this.agentName } : {}), ...options.headers,
+        };
+        if (options.json !== undefined)
+            headers["Content-Type"] = "application/json";
+        const body = options.body ?? (options.json !== undefined ? JSON.stringify(options.json) : undefined);
+        const keyed = "Idempotency-Key" in headers;
+        const noRetry = path.split("?")[0].replace(/\/+$/, "").endsWith("/secret-fill"); // typing a secret twice can't be undone: never retried, whatever the error
+        const idempotent = method === "GET" || method === "HEAD" || method === "DELETE" || keyed;
+        for (let attempt = 0;; attempt++) {
+            let delay;
+            try {
+                const res = await this.fetchImpl(url, { method, headers, body, signal: AbortSignal.timeout(options.timeoutMs ?? this.timeoutMs) });
+                // A stored 429 replays under an Idempotency-Key, so a keyed POST isn't retried on it. A rate-limited request never ran.
+                const rateLimited = !noRetry && res.status === 429 && !keyed && (await isRateLimited(res));
+                if (!((!noRetry && idempotent && RETRY_STATUSES.has(res.status)) || rateLimited) || attempt >= this.maxRetries)
+                    return res;
+                delay = retryAfterOf(res) ?? 0.5 * 2 ** attempt;
+            }
+            catch (e) {
+                const timedOut = e instanceof Error && e.name === "TimeoutError";
+                if (noRetry || !idempotent || timedOut || attempt >= this.maxRetries)
+                    throw e;
+                delay = 0.5 * 2 ** attempt;
+            }
+            await sleep(Math.min(delay, 30) * 1000);
+        }
+    }
+    /** Call any endpoint, for what this client has no method for. Returns the parsed body, or throws `APIError`. */
+    async request(method, path, options = {}) {
+        const res = await this.rawRequest(method, path, options);
+        const parsed = await parse(res);
+        if (res.status >= 300)
+            throw errorFromResponse(res.status, parsed, retryAfterOf(res));
+        return parsed;
+    }
+    /** Every item across pages: `for await (const s of client.paginate((p) => client.sessions.list({ ...p, status: "live" })))`. */
+    async *paginate(listCall) {
+        let cursor = null;
+        do {
+            const page = await listCall({ cursor });
+            yield* page.data;
+            cursor = page.next_cursor ?? null;
+        } while (cursor);
+    }
+    /** 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, options = {}) { return this.request("POST", "/v1/fetch", { json: { url, ...clean(options) } }); }
+    fetchBatch(urls, options = {}) { return this.request("POST", "/v1/fetch/batch", { json: { urls, ...clean(options) }, timeoutMs: Math.max(this.timeoutMs, 180_000) }); }
+    search(query, options = {}) { return this.request("POST", "/v1/search", { json: { query, ...clean(options) } }); }
+    screenshot(url, options = {}) { return this.request("POST", "/v1/screenshot", { json: { url, ...clean(options) }, timeoutMs: Math.max(this.timeoutMs, 120_000) }); }
+    pdf(url, options = {}) { return this.request("POST", "/v1/pdf", { json: { url, ...clean(options) }, timeoutMs: Math.max(this.timeoutMs, 120_000) }); }
+    map(url, options = {}) { return this.request("POST", "/v1/map", { json: { url, ...clean(options) }, timeoutMs: Math.max(this.timeoutMs, 120_000) }); }
+    /** Structured data from up to 10 URLs. Needs a model key on the organization. */
+    extract(input) { return this.request("POST", "/v1/extract", { json: clean(input), timeoutMs: Math.max(this.timeoutMs, 180_000) }); }
+}
+async function isRateLimited(res) {
+    try {
+        const body = (await res.clone().json());
+        return body.error?.code === "rate_limited";
+    }
+    catch {
+        return false;
+    }
+}
+export { APIError };

package/dist/errors.d.ts

@@ -0,0 +1,28 @@
+/** Everything this package raises on purpose. */
+export declare class SteerpaneError extends Error {
+    name: string;
+}
+/** The API answered with an error. `code` is the stable value to branch on; `message` is written for people. */
+export declare class APIError extends SteerpaneError {
+    readonly status: number;
+    readonly code: string;
+    readonly message: string;
+    readonly details: Record<string, unknown>;
+    readonly retryAfter: number | null;
+    name: string;
+    constructor(status: number, code: string, message: string, details?: Record<string, unknown>, retryAfter?: number | null);
+}
+/** 409 `human_in_control`. The command was queued; wait for the human with `sessions.waitForHuman`. */
+export declare class HumanInControlError extends APIError {
+    name: string;
+}
+/** An MCP tool answered with `isError`. `code` and `details` come from the same envelope as REST errors. */
+export declare class ToolError extends SteerpaneError {
+    readonly tool: string;
+    readonly code: string;
+    readonly message: string;
+    readonly details: Record<string, unknown>;
+    name: string;
+    constructor(tool: string, code: string, message: string, details?: Record<string, unknown>);
+}
+export declare function errorFromResponse(status: number, body: unknown, retryAfter: number | null): APIError;

package/dist/errors.js

@@ -0,0 +1,49 @@
+/** Everything this package raises on purpose. */
+export class SteerpaneError extends Error {
+    name = "SteerpaneError";
+}
+/** The API answered with an error. `code` is the stable value to branch on; `message` is written for people. */
+export class APIError extends SteerpaneError {
+    status;
+    code;
+    message;
+    details;
+    retryAfter;
+    name = "APIError";
+    constructor(status, code, message, details = {}, retryAfter = null) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.message = message;
+        this.details = details;
+        this.retryAfter = retryAfter;
+    }
+}
+/** 409 `human_in_control`. The command was queued; wait for the human with `sessions.waitForHuman`. */
+export class HumanInControlError extends APIError {
+    name = "HumanInControlError";
+}
+/** An MCP tool answered with `isError`. `code` and `details` come from the same envelope as REST errors. */
+export class ToolError extends SteerpaneError {
+    tool;
+    code;
+    message;
+    details;
+    name = "ToolError";
+    constructor(tool, code, message, details = {}) {
+        super(message);
+        this.tool = tool;
+        this.code = code;
+        this.message = message;
+        this.details = details;
+    }
+}
+export function errorFromResponse(status, body, retryAfter) {
+    const envelope = typeof body === "object" && body !== null ? body.error : undefined;
+    const err = (typeof envelope === "object" && envelope !== null ? envelope : {});
+    const code = typeof err.code === "string" && err.code ? err.code : `http_${status}`;
+    const message = String(err.message || (typeof body === "string" && body ? body : `HTTP ${status}`)).slice(0, 2000);
+    const details = (err.details ?? {});
+    const Cls = code === "human_in_control" ? HumanInControlError : APIError;
+    return new Cls(status, code, message, details, retryAfter);
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { DEFAULT_BASE_URL, Steerpane, type SteerpaneOptions } from "./client.js";
+export { APIError, HumanInControlError, SteerpaneError, ToolError } from "./errors.js";
+export { connectPlaywright, type ConnectOptions } from "./playwright.js";
+export type * from "./types.js";
+export { VERSION } from "./version.js";
+export { constructEvent, DELIVERY_HEADER, SIGNATURE_HEADER, verifySignature, WebhookSignatureError, type SignatureSource, type VerifyOptions } from "./webhooks.js";

package/dist/index.js

@@ -0,0 +1,5 @@
+export { DEFAULT_BASE_URL, Steerpane } from "./client.js";
+export { APIError, HumanInControlError, SteerpaneError, ToolError } from "./errors.js";
+export { connectPlaywright } from "./playwright.js";
+export { VERSION } from "./version.js";
+export { constructEvent, DELIVERY_HEADER, SIGNATURE_HEADER, verifySignature, WebhookSignatureError } from "./webhooks.js";

package/dist/playwright.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Connect Playwright to a Steerpane session over CDP. Needs `playwright` or `playwright-core` installed alongside this package.
+ *
+ * The token travels in a header, never in the URL, so it stays out of proxy and server logs. Closing the connection leaves the session
+ * running: stop it with `client.sessions.stop(id)` when you are finished.
+ */
+import type { Browser } from "playwright-core";
+import type { Steerpane } from "./client.js";
+import type { Session } from "./types.js";
+export interface ConnectOptions {
+    /** Shown as the agent's name in the dashboard. */
+    agent?: string;
+    timeoutMs?: number;
+}
+/** Waits for the browser to be ready and connects. The open tab is `browser.contexts()[0].pages()[0]`. */
+export declare function connectPlaywright(client: Steerpane, session: string | Pick<Session, "id">, options?: ConnectOptions): Promise<Browser>;

package/dist/playwright.js

@@ -0,0 +1,20 @@
+import { SteerpaneError } from "./errors.js";
+async function loadChromium() {
+    for (const name of ["playwright-core", "playwright"]) {
+        try {
+            return (await import(name)).chromium;
+        }
+        catch (e) {
+            if (e.code !== "ERR_MODULE_NOT_FOUND")
+                throw e;
+        }
+    }
+    throw new SteerpaneError("Playwright is not installed. Run: npm install playwright-core");
+}
+/** Waits for the browser to be ready and connects. The open tab is `browser.contexts()[0].pages()[0]`. */
+export async function connectPlaywright(client, session, options = {}) {
+    const chromium = await loadChromium();
+    const ready = await client.sessions.waitUntilReady(typeof session === "string" ? session : session.id);
+    const url = options.agent ? `${ready.cdp_url}?agent=${encodeURIComponent(options.agent)}` : ready.cdp_url;
+    return chromium.connectOverCDP(url, { headers: { Authorization: `Bearer ${client.token}` }, timeout: options.timeoutMs ?? 30_000 });
+}