@steerpane/sdk 0.0.0-stage → 0.1.0

package/dist/types.d.ts

@@ -0,0 +1,162 @@
+/** 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 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;
+    status: SessionStatus;
+    controller: "agent" | "human";
+    profile_id: string | null;
+    current_url: string | null;
+    page_title: string | null;
+    agent_name: string | null;
+    queued_commands: number;
+    help_request: Json | null;
+    error_message: string | null;
+    config: Json;
+    cdp_url: string;
+    live_url: string;
+    watch_url: string;
+    always_on: boolean;
+    last_handback: {
+        outcome: HandbackOutcome | null;
+        note: string | null;
+        at: string;
+    } | null;
+    failure: Failure | null;
+}
+export interface Profile extends Json {
+    id: string;
+    name: string;
+    tags: string[];
+    logged_in_sites: Json[];
+    cookie_count: number;
+}
+export interface FetchResult extends Json {
+    url: string;
+    final_url: string;
+    status: number;
+    format: string;
+    content: string;
+    engine: string;
+    title: string | null;
+    links?: string[];
+    metadata?: Json;
+}
+export interface SearchResponse extends Json {
+    query: string;
+    results: {
+        title: string;
+        url: string;
+        snippet: string;
+    }[];
+    provider: string;
+}
+export interface Capture extends Json {
+    id: string;
+    kind: "screenshot" | "pdf";
+    file_id: string;
+    url: string;
+    name: string;
+    mime: string;
+    size: number;
+    base64?: string;
+}
+export interface CrawlJob extends Json {
+    id: string;
+    url: string;
+    status: "queued" | "running" | "completed" | "failed" | "cancelled";
+    progress: {
+        done: number;
+        total: number;
+        failed: number;
+    };
+    error: string | null;
+    pages?: Json[];
+    next_cursor?: string | number | 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;
+        }[];
+    } | null;
+}
+export interface AgentRun extends Json {
+    id: string;
+    task: string;
+    status: RunStatus;
+    session_id: string | null;
+    model: string;
+    max_steps: number;
+    step_count: number;
+    cost_usd: number;
+    result: unknown;
+    error: string | null;
+    failure: Failure | null;
+}
+export interface StoredFile extends Json {
+    id: string;
+    name: string;
+    mime: string;
+    size_bytes: number;
+    source: "upload" | "download" | "api" | "embed";
+    status: "pending" | "ready";
+    session_id: string | null;
+    expires_at: string | null;
+}
+export interface UploadUrl extends Json {
+    file_id: string;
+    upload_url: string;
+    method: string;
+    headers: Record<string, string>;
+    expires_at: string;
+    curl: string;
+    requires_complete: boolean;
+}
+export interface EmbedLink extends Json {
+    id: string;
+    url: string;
+    expires_at: string | null;
+    mode: "read_only" | "interactive" | "interactive_takeover";
+}
+export interface Webhook extends Json {
+    id: string;
+    url: string;
+    events: string[];
+    enabled: boolean;
+    secret?: string;
+}
+export interface Credential extends Json {
+    id: string;
+    name: string;
+    domain: string;
+    username: string;
+    has_totp: boolean;
+}
+export interface HumanResult extends Json {
+    status: "handed_back" | "timeout" | "stopped";
+    note: string | null;
+    outcome: HandbackOutcome | null;
+}
+export interface HelpRequest extends Json {
+    request_id: string;
+    status: string;
+    session_id: string;
+}

package/dist/types.js

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

package/dist/version.d.ts

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

package/dist/version.js

@@ -0,0 +1 @@
+export const VERSION = "0.1.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"
-}
+{
+  "name": "@steerpane/sdk",
+  "version": "0.1.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"
+  }
+}