@steerpane/sdk 0.1.0 → 0.2.0

package/dist/types.d.ts

@@ -1,6 +1,6 @@
 /** 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 = "starting" | "running" | "idle" | "human_control" | "awaiting_help" | "stopped" | "error";
+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> {
@@ -14,76 +14,178 @@ export interface Failure {
 }
 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";
-    profile_id: string | null;
-    current_url: string | null;
-    page_title: string | null;
+    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;
-    title: string | null;
     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;
-    base64?: string;
+    /** 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[];
-    next_cursor?: string | number | null;
+    /** 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;
@@ -96,67 +198,257 @@ export interface CrawlJob extends Json {
             status: number | null;
             error: string | null;
         }[];
-    } | 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;
-    secret?: string;
+    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/version.d.ts

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

package/dist/version.js

@@ -1 +1 @@
-export const VERSION = "0.1.0";
+export const VERSION = "0.2.0";

package/package.json

@@ -1,31 +1,31 @@
-{
-  "name": "@steerpane/sdk",
-  "version": "0.1.0",
-  "description": "Node client for Steerpane: remote browsers for AI agents, with human takeover.",
-  "license": "Apache-2.0",
+{
+  "name": "@steerpane/sdk",
+  "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"
-  }
-}
+  "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"
+  }
+}