@steerpane/sdk 0.0.0-stage → 0.2.0

package/dist/types.d.ts

@@ -0,0 +1,454 @@
+/** Response shapes. Field names are the API's own, and fields the API adds later pass straight through. */
+export type Json = Record<string, unknown>;
+export type SessionStatus = "queued" | "starting" | "running" | "idle" | "human_control" | "awaiting_help" | "stopped" | "error";
+export type RunStatus = "queued" | "running" | "awaiting_human" | "completed" | "failed" | "cancelled";
+export type HandbackOutcome = "done" | "not_done";
+export interface Page<T> {
+    data: T[];
+    next_cursor: string | null;
+}
+export interface Failure {
+    category: string;
+    retryable: boolean;
+    message: string;
+}
+export interface Session extends Json {
+    id: string;
+    org_id: string;
+    project_id: string | null;
+    profile_id: string | null;
+    profile_name: string;
+    end_user_id: string | null;
+    status: SessionStatus;
+    controller: "agent" | "human";
+    controller_user_id: string | null;
+    agent_paused: boolean;
+    agent_name: string | null;
+    connected_via: string | null;
+    agent_client: Json | null;
+    current_url: string;
+    page_title: string;
+    region: string;
+    node_id: string;
+    container_id: string;
+    started_at: string | null;
+    ended_at: string | null;
+    cpu: number;
+    memory_mb: number;
+    network_kbps: number;
+    action_count: number;
+    queued_commands: number;
+    /** Only in the dashboard's (cookie) view, never for API tokens. */
+    queue?: Json[];
+    /** Only while `status` is "queued" (a `profile_wait` session waiting for its profile); 1 is next. */
+    queue_position?: number | null;
+    help_request: Json | null;
+    error_message: string | null;
+    recording: boolean;
+    thumbnail_hue: number;
+    profile_color: unknown;
+    config: Json;
+    cdp_url: string;
+    live_url: string;
+    watch_url: string;
+    always_on: boolean;
+    restarting: boolean;
+    restart_at: string | null;
+    last_handback: {
+        outcome: HandbackOutcome | null;
+        note: string | null;
+        queued?: "replay" | "discard" | null;
+        at: string;
+    } | null;
+    failure: Failure | null;
+}
+export interface EndUser extends Json {
+    id: string;
+    org_id: string;
+    external_id: string;
+    name: string | null;
+    metadata: Record<string, string>;
+    disabled: boolean;
+    disabled_at: string | null;
+    created_at: string | null;
+    updated_at: string | null;
+}
+export interface Profile extends Json {
+    id: string;
+    org_id: string;
+    end_user_id: string | null;
+    name: string;
+    description: string | null;
+    icon: string;
+    color: number;
+    /** The saved proxy settings without the password; `has_password` says whether one is stored. */
+    proxy: Json;
+    region: string;
+    fingerprint: Json;
+    user_agent: string;
+    behaviour: Json;
+    extensions: string[];
+    tags: string[];
+    logged_in_sites: Json[];
+    /** Always `[]` in lists; the cookies of one profile come with `get`. */
+    cookies: Json[];
+    storage_bytes: number;
+    cookie_count: number;
+    last_used_at: string | null;
+    created_at: string | null;
+    created_by: string;
+    session_count: number;
+}
+export interface FetchResult extends Json {
+    id: string;
+    url: string;
+    final_url: string;
+    status: number;
+    format: string;
+    content_type: string;
+    /** "" when the page has no title; never null. */
+    title: string;
+    content: string;
+    headers: Record<string, string>;
+    size_bytes: number;
+    latency_ms: number;
+    redirects: string[];
+    created_at: string;
+    mode: string;
+    engine: string;
+    links?: string[];
+    metadata?: Json;
+    /** Set when the page was a wall (consent, bot check, CAPTCHA) rather than content. */
+    blocked_by?: string | null;
+    next_step?: string | null;
+    degraded?: boolean | null;
+    degraded_reason?: string | null;
+    deep_reason?: string | null;
+    rendered_by?: string | null;
+}
+export interface SearchResponse extends Json {
+    id: string;
+    query: string;
+    results: {
+        title: string;
+        url: string;
+        snippet: string;
+        published_at?: string | null;
+    }[];
+    provider: string;
+    latency_ms: number;
+    created_at: string;
+}
+export interface Capture extends Json {
+    id: string;
+    kind: "screenshot" | "pdf";
+    file_id: string;
+    /** Authenticated URL of the stored file. */
+    url: string;
+    /** Signed link that needs no token. */
+    download_url: string;
+    download_expires_at: string;
+    download_curl: string;
+    name: string;
+    mime: string;
+    size: number;
+    /** null for PDFs. */
+    width: number | null;
+    height: number | null;
+    page_url: string;
+    final_url: string;
+    title: string;
+    status: number | null;
+    engine: string;
+    latency_ms: number;
+    created_at: string;
+    expires_at: string | null;
+    base64?: string | null;
+}
+export interface CrawlJob extends Json {
+    id: string;
+    url: string;
+    status: "queued" | "running" | "completed" | "failed" | "cancelled";
+    engine: string;
+    options: Json;
+    progress: {
+        done: number;
+        total: number;
+        failed: number;
+    };
+    error: string | null;
+    project_id: string | null;
+    created_at: string | null;
+    started_at: string | null;
+    finished_at: string | null;
+    /** Only on `get` (the page of results); the list and `start` leave these out. */
+    pages?: Json[];
+    /** Pass back to `get` for the next page of `pages`. A string, or null on the last page. */
+    next_cursor?: string | null;
+    /** Left out until a `check_links` crawl has stored its report; never null. */
+    link_check?: {
+        checked: number;
+        ok: number;
+        unverified: number;
+        blocked: number;
+        truncated: boolean;
+        broken: {
+            url: string;
+            found_on: string;
+            status: number | null;
+            error: string | null;
+        }[];
+    };
+}
+export interface AgentRun extends Json {
+    id: string;
+    agent_id: string | null;
+    agent_name: string;
+    task: string;
+    status: RunStatus;
+    session_id: string | null;
+    profile_id: string | null;
+    project_id: string | null;
+    model: string;
+    max_steps: number;
+    step_count: number;
+    tokens_in: number;
+    tokens_out: number;
+    cost_usd: number;
+    started_at: string;
+    ended_at: string | null;
+    duration_sec: number;
+    variables: Json;
+    limits: Json;
+    result: unknown;
+    error: string | null;
+    failure: Failure | null;
+    /** Only when the run was read with its steps. */
+    steps?: Json[] | null;
+}
+export interface StoredFile extends Json {
+    id: string;
+    name: string;
+    mime: string;
+    size_bytes: number;
+    /** null while an upload is still pending. */
+    sha256: string | null;
+    source: "upload" | "download" | "api" | "embed";
+    status: "pending" | "ready";
+    session_id: string | null;
+    project_id: string | null;
+    created_by_user_id: string | null;
+    created_by_name: string | null;
+    token_id: string | null;
+    created_at: string;
+    expires_at: string | null;
+    content_url: string;
+}
+export interface UploadUrl extends Json {
+    file: StoredFile;
+    file_id: string;
+    upload_url: string;
+    method: string;
+    headers: Record<string, string>;
+    expires_at: string;
+    curl: string;
+    complete_url: string;
+    requires_complete: boolean;
+    max_bytes: number;
+}
+export interface EmbedLink extends Json {
+    id: string;
+    url: string;
+    expires_at: string | null;
+    mode: "read_only" | "interactive" | "interactive_takeover";
+    /** The fields below come with `list` and `revoke`; a freshly made link has just the four above. */
+    name?: string;
+    session_id?: string;
+    allowed_origins?: string[];
+    hide_toolbar?: boolean;
+    show_control?: boolean;
+    end_user?: Json | null;
+    theme?: string;
+    revoked_at?: string | null;
+    created_at?: string;
+    created_by?: string;
+    views?: number;
+    status?: string;
+}
+export interface Webhook extends Json {
+    id: string;
+    org_id: string;
+    project_id: string | null;
+    url: string;
+    description: string | null;
+    events: string[];
+    headers: {
+        key: string;
+        value: string;
+    }[];
+    enabled: boolean;
+    disabled_reason: string | null;
+    success_rate: number;
+    last_delivery_at: string | null;
+    created_at: string | null;
+    /** On create and rotate, and for callers who may change webhooks; not in lists. */
+    secret?: string | null;
+}
+export interface WebhookDelivery extends Json {
+    id: string;
+    webhook_id: string;
+    event: string;
+    event_id: string;
+    /** 0 when the request never got an answer. */
+    status_code: number;
+    success: boolean;
+    duration_ms: number;
+    attempt: number;
+    delivered_at: string | null;
+    next_attempt_at: string | null;
+    request_headers: Json;
+    request_body: Json;
+    response_body: string;
+    error: string | null;
+    test: boolean;
+}
+export interface Credential extends Json {
+    id: string;
+    org_id: string;
+    name: string;
+    domain: string;
+    username: string;
+    has_totp: boolean;
+    profile_ids: string[];
+    token_ids: string[];
+    last_used_at: string | null;
+    created_at: string | null;
+}
+export interface HumanResult extends Json {
+    status: "handed_back" | "timeout" | "stopped";
+    note: string | null;
+    outcome: HandbackOutcome | null;
+}
+/** A rule of the action guard. `id` is yours; give at least one of `selector`, `role`, `name` (a case-insensitive regex on the accessible name or visible text). */
+export interface ActionGuardRule {
+    id: string;
+    selector?: string;
+    role?: string;
+    name?: string;
+    frames?: "all" | "top";
+}
+export interface ActionGuard extends Json {
+    rules: ActionGuardRule[];
+}
+export interface ActionGuardUnlock extends Json {
+    token: string;
+    expires_at: string;
+    /** Frames whose document had already started when the guard was installed (or that have no guard): a page script may have registered a listener ahead of it. Optional: older servers omit it. */
+    late_targets?: number;
+}
+export interface HelpRequest extends Json {
+    request_id: string;
+    status: string;
+    session_id: string;
+}
+/** A computer (or shared machine) that runs sessions for you. `scope` is `user`, `org` or `end_user`. */
+export interface Device extends Json {
+    id: string;
+    name: string;
+    scope: "user" | "org" | "end_user";
+    owner_user_id: string | null;
+    end_user_id: string | null;
+    platform: string;
+    agent_version: string;
+    chrome_version: string;
+    modes: string[];
+    capacity: number;
+    connected: boolean;
+    extension_connected: boolean;
+    last_seen_at: string | null;
+    created_at: string | null;
+    revoked_at: string | null;
+}
+/** A single-use code, shown once, that pairs a device agent (`XXXX-XXXX`). */
+export interface DevicePairingCode extends Json {
+    code: string;
+    expires_at: string | null;
+    scope: string;
+    end_user_id: string | null;
+}
+/** What `sessions.solveCaptcha` returns. `status` is `solved`, `unsolved`, `none` (no CAPTCHA found), `no_model`, `browser_unavailable`, `in_progress` (call again), or a human-help status when `onFailure` handed it to a person. */
+export interface CaptchaSolveResult extends Json {
+    status: string;
+}
+/** Arguments of the MCP tool `wait_for_code`. Pass `sessionId` to have the code typed into the page without it passing through you, or `returnCode` to get it back. */
+export interface WaitForCodeOptions {
+    sessionId?: string;
+    profileId?: string;
+    credentialId?: string;
+    /** The site the code is for, such as `acme.com`. Needed unless the code source or the credential names it. */
+    site?: string;
+    sender?: string;
+    subject?: string;
+    /** Overall wait, up to 600 (default 120). */
+    timeoutS?: number;
+    /** Also accept a code received up to this long before the wait began, up to 600 (default 120). */
+    maxAgeS?: number;
+    /** The code field, or the boxes when there is one per digit. Default: the page's one-time-code field. */
+    selector?: string;
+    frame?: string;
+    /** Press Enter after entering the code. */
+    submit?: boolean;
+    /** Return the code to you instead of entering it. Without `sessionId` this is the only way to use a code. */
+    returnCode?: boolean;
+    /** A code held from an earlier `received_not_entered` result: try entering it again. */
+    codeId?: string;
+}
+/** `wait_for_code` result. `waitForCode` keeps calling while the status is `waiting`, so these are the final ones. */
+export type WaitForCodeResult = (Json & {
+    status: "entered";
+    code_id: string;
+    code_returned: false;
+    sender?: string;
+    channel?: string;
+    received_at?: string;
+    expires_at?: string;
+    next_step?: string;
+}) | (Json & {
+    status: "received";
+    code: string;
+    code_id: string;
+    code_returned: true;
+    sender?: string;
+    channel?: string;
+    received_at?: string;
+    expires_at?: string;
+}) | (Json & {
+    status: "received_not_entered";
+    code_id: string;
+    error: {
+        code: string;
+        message: string;
+    };
+    next_step?: string;
+}) | (Json & {
+    status: "timeout";
+    started_at?: string;
+    source_problems?: unknown;
+    next_step?: string;
+}) | (Json & {
+    status: "session_ended" | "no_source";
+    next_step?: string;
+});
+/** Result of `actions.secretFill`. `value` is always `"••••••"`. `typed: true` (or a 409 whose `details.typed` is set) means the value is already in the page: do not send it again.
+ *  `warning` says why when the call succeeded but a later step (Enter, the action guard) failed. */
+export interface SecretFillResult extends Json {
+    ok: boolean;
+    kind: "password" | "code";
+    site: string;
+    selector: string;
+    value: string;
+    submitted: boolean;
+    frame_origin: string;
+    typed?: boolean;
+    warning?: string;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/version.d.ts

@@ -0,0 +1 @@
+export declare const VERSION = "0.2.0";

package/dist/version.js

@@ -0,0 +1 @@
+export const VERSION = "0.2.0";

package/dist/webhooks.d.ts

@@ -0,0 +1,17 @@
+import { SteerpaneError } from "./errors.js";
+export declare const SIGNATURE_HEADER = "Steerpane-Signature";
+export declare const DELIVERY_HEADER = "Steerpane-Delivery";
+export declare class WebhookSignatureError extends SteerpaneError {
+    name: string;
+}
+export interface VerifyOptions {
+    toleranceS?: number;
+    /** Unix seconds; for tests. */
+    now?: number;
+}
+/** The signature header's value, or a request's headers: a `Headers` object, or Node's `req.headers`. */
+export type SignatureSource = string | null | undefined | Headers | Record<string, string | string[] | undefined>;
+/** True when `source` holds a fresh, valid signature of `rawBody`. Pass the body as received, not re-encoded JSON. */
+export declare function verifySignature(rawBody: string | Uint8Array, source: SignatureSource, secret: string, options?: VerifyOptions): boolean;
+/** Check the signature and return the parsed event, or throw `WebhookSignatureError`. */
+export declare function constructEvent<T = Record<string, unknown>>(rawBody: string | Uint8Array, source: SignatureSource, secret: string, options?: VerifyOptions): T;

package/dist/webhooks.js

@@ -0,0 +1,64 @@
+/**
+ * Check a webhook's `Steerpane-Signature` header.
+ *
+ * The header is `t=<unix seconds>,v1=<hex>`, where the hex is HMAC-SHA256 of `<t>.<raw body>` with the endpoint's secret. For 24 hours after
+ * a secret rotation it carries one `v1` per secret, and any match is good. Deliveries can repeat: deduplicate on the event's `id`.
+ */
+import { createHmac, timingSafeEqual } from "node:crypto";
+import { SteerpaneError } from "./errors.js";
+export const SIGNATURE_HEADER = "Steerpane-Signature";
+export const DELIVERY_HEADER = "Steerpane-Delivery";
+/** What the header was called before the rename. Read only when `SIGNATURE_HEADER` is absent. */
+const LEGACY_SIGNATURE_HEADER = "Conduit-Signature";
+const DEFAULT_TOLERANCE_S = 300;
+export class WebhookSignatureError extends SteerpaneError {
+    name = "WebhookSignatureError";
+}
+function signatureValue(source) {
+    if (source === null || source === undefined || typeof source === "string")
+        return source;
+    const names = [SIGNATURE_HEADER, LEGACY_SIGNATURE_HEADER];
+    if (typeof Headers !== "undefined" && source instanceof Headers) {
+        for (const name of names) {
+            const value = source.get(name);
+            if (value)
+                return value;
+        }
+        return null;
+    }
+    const lowered = new Map(Object.entries(source).map(([k, v]) => [k.toLowerCase(), v]));
+    for (const name of names) {
+        const value = lowered.get(name.toLowerCase());
+        if (value)
+            return Array.isArray(value) ? value[0] : value;
+    }
+    return null;
+}
+/** True when `source` holds a fresh, valid signature of `rawBody`. Pass the body as received, not re-encoded JSON. */
+export function verifySignature(rawBody, source, secret, options = {}) {
+    const header = signatureValue(source);
+    if (!header || !secret)
+        return false;
+    const pairs = header.split(",").map((p) => {
+        const i = p.indexOf("=");
+        return i < 0 ? ["", ""] : [p.slice(0, i).trim(), p.slice(i + 1).trim()];
+    });
+    const timestamp = pairs.find(([k]) => k === "t")?.[1];
+    const signatures = pairs.filter(([k]) => k === "v1").map(([, v]) => v);
+    if (!timestamp || !/^\d+$/.test(timestamp) || signatures.length === 0)
+        return false;
+    const now = options.now ?? Date.now() / 1000;
+    if (Math.abs(now - Number(timestamp)) > (options.toleranceS ?? DEFAULT_TOLERANCE_S))
+        return false;
+    const expected = createHmac("sha256", secret).update(`${timestamp}.`).update(rawBody).digest();
+    return signatures.some((signature) => {
+        const given = Buffer.from(signature, "hex");
+        return given.length === expected.length && timingSafeEqual(given, expected);
+    });
+}
+/** Check the signature and return the parsed event, or throw `WebhookSignatureError`. */
+export function constructEvent(rawBody, source, secret, options = {}) {
+    if (!verifySignature(rawBody, source, secret, options))
+        throw new WebhookSignatureError("Webhook signature is missing, invalid or too old");
+    return JSON.parse(typeof rawBody === "string" ? rawBody : Buffer.from(rawBody).toString("utf8"));
+}

package/package.json

@@ -1,6 +1,31 @@
 {
   "name": "@steerpane/sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Node client for Steerpane: remote browsers for AI agents, with human takeover.",
+  "license": "Apache-2.0",
+  "homepage": "https://steerpane.app",
+  "repository": { "type": "git", "url": "git+https://github.com/Steerpane/sdks.git", "directory": "node" },
+  "keywords": ["browser", "automation", "agents", "playwright", "cdp", "mcp"],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": { "types": "./dist/index.d.ts", "default": "./dist/index.js" },
+    "./package.json": "./package.json"
+  },
+  "files": ["dist", "README.md", "LICENSE"],
+  "engines": { "node": ">=20" },
+  "publishConfig": { "access": "public" },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "node --test test/*.test.mjs",
+    "prepack": "npm run build"
+  },
+  "peerDependencies": { "playwright-core": ">=1.45" },
+  "peerDependenciesMeta": { "playwright-core": { "optional": true } },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "playwright-core": "^1.50.0",
+    "typescript": "^5.6.0"
+  }
+}