@unbrowse/sdk 6.17.0-preview.6

package/dist/runtime.js

@@ -0,0 +1,326 @@
+/**
+ * Local-binary lifecycle for `@unbrowse/sdk`.
+ *
+ * The SDK talks to a co-located `unbrowse` runtime over loopback HTTP.
+ * `runtime.ts` owns the contract for locating, probing, and spawning that
+ * runtime so `client.ts` can stay a pure HTTP transport.
+ *
+ * Tree-shaking note: heavy Node-only imports (`child_process`) are pulled
+ * in lazily inside `spawnUnbrowseRuntime`. Callers that only use
+ * `Unbrowse.connect` never pay for them.
+ */
+import { RuntimeUnavailableError } from "./errors.js";
+import { createRequire } from "node:module";
+// Under Node ESM (`"type": "module"` + tsc `module: ESNext`), bare `require`
+// is undefined and the lazy `require("node:fs")` / `require("node:path")`
+// calls below would throw `ReferenceError`, get swallowed by their try/catch,
+// and silently return false/null. Bind a CommonJS-style require to this
+// module's URL so all the lazy `require(...)` sites in this file resolve.
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+const require = createRequire(import.meta.url);
+const DEFAULT_PORT = 6969;
+const DEFAULT_READY_TIMEOUT_MS = 10_000;
+const DEFAULT_PROBE_TIMEOUT_MS = 1_000;
+/**
+ * Probe an already-running runtime by hitting `/health`. Returns true iff
+ * the response status is 2xx. Never throws — connection refused, timeout,
+ * DNS failures, and non-2xx all resolve to `false`.
+ */
+export async function probeUnbrowseRuntime(baseUrl, timeoutMs = DEFAULT_PROBE_TIMEOUT_MS) {
+    const url = `${baseUrl.replace(/\/+$/, "")}/health`;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const res = await fetch(url, { method: "GET", signal: controller.signal });
+        return res.ok;
+    }
+    catch {
+        return false;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * Locate the `unbrowse` binary by walking, in order:
+ *   1. `UNBROWSE_BIN` env var
+ *   2. `require.resolve('unbrowse/package.json')` -> derived `bin/unbrowse-wrapper.mjs`
+ *   3. `Bun.which('unbrowse')` if running under Bun
+ * Returns null when nothing is wired.
+ */
+export function locateUnbrowseBinary() {
+    // 1. Explicit env override.
+    const fromEnv = readEnv("UNBROWSE_BIN");
+    if (fromEnv && fileExists(fromEnv))
+        return fromEnv;
+    // 2. require.resolve('unbrowse/package.json') -> bin/unbrowse-wrapper.mjs.
+    //    Only honor this when the resolved package looks like a real install
+    //    (the wrapper has a sibling native binary or compiled launcher). A
+    //    bare workspace tree with no postinstall artifacts would set us up to
+    //    spawn-and-fail; fall through to PATH lookup in that case.
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const { createRequire } = require("node:module");
+        const requireFn = createRequire(import.meta.url);
+        const pkgPath = requireFn.resolve("unbrowse/package.json");
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const path = require("node:path");
+        const binDir = path.join(path.dirname(pkgPath), "bin");
+        const wrapper = path.join(binDir, "unbrowse-wrapper.mjs");
+        if (fileExists(wrapper) && hasNativeSibling(binDir))
+            return wrapper;
+    }
+    catch {
+        // peer dep not installed — fall through
+    }
+    // 3. Bun.which / PATH lookup. Bun gives us a one-liner; under raw Node
+    //    we do the PATH walk ourselves so `npx node smoke.mjs` against a
+    //    globally-installed `unbrowse` works the same as `bun smoke.ts`.
+    const bunWhich = globalThis.Bun?.which;
+    if (typeof bunWhich === "function") {
+        const onPath = bunWhich("unbrowse");
+        if (onPath && fileExists(onPath))
+            return onPath;
+    }
+    const fromPath = findOnPath("unbrowse");
+    if (fromPath)
+        return fromPath;
+    return null;
+}
+function hasNativeSibling(binDir) {
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const fs = require("node:fs");
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const path = require("node:path");
+        return fs.existsSync(path.join(binDir, "unbrowse"))
+            || fs.existsSync(path.join(binDir, "unbrowse.exe"));
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * In-flight spawn promises keyed by port. When two callers race to spawn on
+ * the same port, the second one awaits the first's promise instead of
+ * launching a competing child that would lose the bind and exit with code=1.
+ *
+ * Each caller gets its own `RuntimeHandle` view: the *winner* of the race
+ * keeps `owned=true` so its `.close()` actually kills the child; subsequent
+ * `Unbrowse.local()` callers that joined the in-flight wait get an adopted
+ * (`owned=false`) handle so they don't double-kill the shared child.
+ */
+const inFlightSpawns = new Map();
+/**
+ * Spawn (or adopt) a co-located `unbrowse` runtime and wait for it to
+ * answer `/health`. Returns a `RuntimeHandle` whose `.kill()` tears the
+ * child down. Throws `RuntimeUnavailableError` on failure modes.
+ *
+ * Concurrency: if two callers race on the same port, only one spawn is
+ * launched. The second caller awaits the first's promise and gets an
+ * adopted (`owned=false`) view of the same handle so it cannot
+ * double-kill the child.
+ */
+export async function spawnUnbrowseRuntime(opts = {}) {
+    const port = opts.port ?? DEFAULT_PORT;
+    // If another caller is mid-spawn on this port, join their promise
+    // instead of competing for the bind. The joiner receives an adopted
+    // view (owned=false) so the winner's .close() / .kill() is the only
+    // one that actually tears the child down.
+    const existing = inFlightSpawns.get(port);
+    if (existing) {
+        const winner = await existing;
+        return {
+            baseUrl: winner.baseUrl,
+            pid: winner.pid,
+            kill: async () => { },
+            ready: Promise.resolve(),
+            owned: false,
+        };
+    }
+    const spawnPromise = spawnUnbrowseRuntimeInternal(opts);
+    inFlightSpawns.set(port, spawnPromise);
+    try {
+        return await spawnPromise;
+    }
+    finally {
+        // Clear the slot once the spawn settles (success or failure) so a
+        // subsequent .close()-then-spawn cycle re-enters the spawn path.
+        if (inFlightSpawns.get(port) === spawnPromise) {
+            inFlightSpawns.delete(port);
+        }
+    }
+}
+async function spawnUnbrowseRuntimeInternal(opts) {
+    const port = opts.port ?? DEFAULT_PORT;
+    const baseUrl = `http://127.0.0.1:${port}`;
+    const readyTimeoutMs = opts.readyTimeoutMs ?? DEFAULT_READY_TIMEOUT_MS;
+    // 1. If a runtime is already alive on the requested port, adopt it.
+    if (await probeUnbrowseRuntime(baseUrl, DEFAULT_PROBE_TIMEOUT_MS)) {
+        return {
+            baseUrl,
+            pid: -1,
+            kill: async () => { },
+            ready: Promise.resolve(),
+            owned: false,
+        };
+    }
+    // 2. Locate the binary.
+    const binary = opts.binaryPath ?? locateUnbrowseBinary();
+    if (!binary || !fileExists(binary)) {
+        throw new RuntimeUnavailableError(`unbrowse binary not found${opts.binaryPath ? ` at ${opts.binaryPath}` : ""}. Install with: npm i -g unbrowse`, "binary_missing", port);
+    }
+    // 3. Spawn via Node's child_process (cross-runtime; Bun shims this).
+    //    Lazy import keeps the connect-only path tree-shakeable.
+    const childProcess = await import("node:child_process");
+    const env = {
+        ...sanitizeEnv(process.env),
+        ...(opts.env ?? {}),
+        PORT: String(port),
+        HOST: "127.0.0.1",
+    };
+    // `unbrowse-wrapper.mjs` is a node script; the global `unbrowse` binary
+    // may be a wrapper or a compiled single-binary. Pass `serve` as argv[0]
+    // either way — `src/single-binary.ts:106` keys on it, and the wrapper
+    // forwards argv unchanged.
+    const isJsLauncher = binary.endsWith(".mjs") || binary.endsWith(".js");
+    const command = isJsLauncher ? process.execPath : binary;
+    const args = isJsLauncher ? [binary, "serve"] : ["serve"];
+    // `detached: true` puts the child in its own process group so we can
+    // signal the entire group at teardown. The unbrowse wrapper fork-execs
+    // a node grandchild that wouldn't otherwise receive our SIGTERM.
+    const isPosix = process.platform !== "win32";
+    const child = childProcess.spawn(command, args, {
+        cwd: opts.cwd,
+        env,
+        stdio: ["ignore", "pipe", "pipe"],
+        detached: isPosix,
+    });
+    // Prevent the detached child from keeping the parent event loop alive.
+    if (isPosix)
+        child.unref();
+    const signalGroup = (signal) => {
+        if (child.pid && isPosix) {
+            try {
+                process.kill(-child.pid, signal);
+                return;
+            }
+            catch { /* fall through */ }
+        }
+        try {
+            child.kill(signal);
+        }
+        catch { /* ignore */ }
+    };
+    // 4. Poll readiness up to readyTimeoutMs.
+    const ready = (async () => {
+        const deadline = Date.now() + readyTimeoutMs;
+        while (Date.now() < deadline) {
+            if (child.exitCode !== null) {
+                throw new RuntimeUnavailableError(`unbrowse exited (code=${child.exitCode}) before reaching ready state on port ${port}`, "spawn_failed", port);
+            }
+            if (await probeUnbrowseRuntime(baseUrl, 250))
+                return;
+            await sleep(100);
+        }
+        // Timeout — tear the orphan down and surface the failure.
+        signalGroup("SIGTERM");
+        throw new RuntimeUnavailableError(`unbrowse runtime on port ${port} did not become ready within ${readyTimeoutMs}ms`, "spawn_failed", port);
+    })();
+    try {
+        await ready;
+    }
+    catch (e) {
+        if (child.exitCode === null)
+            signalGroup("SIGTERM");
+        throw e;
+    }
+    return {
+        baseUrl,
+        pid: child.pid ?? -1,
+        kill: async () => {
+            if (child.exitCode !== null)
+                return;
+            signalGroup("SIGTERM");
+            // Wait up to 2s for graceful exit; fastify close + browser shutdown
+            // can take a moment.
+            for (let i = 0; i < 20; i++) {
+                if (child.exitCode !== null)
+                    return;
+                await sleep(100);
+            }
+            if (child.exitCode === null) {
+                signalGroup("SIGKILL");
+                // Give the kernel a beat to release the listener.
+                await sleep(100);
+            }
+        },
+        ready: Promise.resolve(),
+        owned: true,
+    };
+}
+// ---- internal helpers ----
+function readEnv(name) {
+    const p = globalThis.process;
+    if (!p?.env)
+        return undefined;
+    const v = p.env[name];
+    return typeof v === "string" && v.length > 0 ? v : undefined;
+}
+function fileExists(p) {
+    try {
+        // Lazy require keeps this file safe in non-Node runtimes that import
+        // only the type definitions. `node:fs` is available wherever spawn
+        // matters, so this branch is gated by the caller.
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const fs = require("node:fs");
+        return fs.existsSync(p);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * PATH walk for raw Node (no Bun.which). Walks `process.env.PATH`, joins each
+ * entry with `name` (+ `.exe` on Windows), and returns the first hit. Honors
+ * `PATHEXT` on Windows so `unbrowse.cmd` / `unbrowse.bat` resolve too.
+ */
+function findOnPath(name) {
+    try {
+        const proc = globalThis.process;
+        const pathEnv = proc?.env?.PATH ?? proc?.env?.Path;
+        if (!pathEnv)
+            return null;
+        const path = require("node:path");
+        const isWin = proc?.platform === "win32";
+        const sep = isWin ? ";" : ":";
+        const exts = isWin
+            ? (proc?.env?.PATHEXT ?? ".COM;.EXE;.BAT;.CMD").split(";").map((e) => e.toLowerCase())
+            : [""];
+        for (const dir of pathEnv.split(sep)) {
+            if (!dir)
+                continue;
+            for (const ext of exts) {
+                const candidate = path.join(dir, name + ext);
+                if (fileExists(candidate))
+                    return candidate;
+            }
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+function sleep(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}
+function sanitizeEnv(env) {
+    const out = {};
+    for (const [k, v] of Object.entries(env)) {
+        if (typeof v === "string")
+            out[k] = v;
+    }
+    return out;
+}
+//# sourceMappingURL=runtime.js.map

package/dist/runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.js","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"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"}

package/dist/x402.d.ts

@@ -0,0 +1,75 @@
+/**
+ * x402 payment primitives — typed shapes the SDK and a wallet agree on.
+ *
+ * Mirrors the canonical x402 protocol shape (resource-URL flavor) so a generic
+ * x402 wallet client can sign these without an Unbrowse-specific adapter. The
+ * backend (`backend/src/middleware/x402-gate.ts:X402PaymentRequirementV2`) is
+ * the producer; this is the consumer-side declaration.
+ *
+ * IMPORTANT: this file MUST NOT import from `./client.js` — keep payment
+ * helpers tree-shakeable so callers who do not pay can drop the wallet code.
+ */
+import type { PaymentRequiredError } from "./errors.js";
+/**
+ * One acceptable payment route returned by a 402 response. The server may
+ * present several (different chains, schemes, prices). The wallet picks one.
+ */
+export interface X402PaymentRequirement {
+    /** Settlement scheme, e.g. "exact" for the standard x402 exact-amount path. */
+    scheme: string;
+    /** Chain identifier, e.g. "base-sepolia", "base", "solana". */
+    network: string;
+    /** Address that receives the payment. */
+    payTo: string;
+    /** Atomic-unit amount required (e.g. "1000" for 1000 atomic USDC = $0.001). */
+    maxAmountRequired: string;
+    /** Resource URL the payment unlocks; agent should not mutate this. */
+    resource: string;
+    /** Media type expected on success (typically "application/json"). */
+    mimeType: string;
+    /** Optional human-readable hint. */
+    description?: string;
+    /** Optional response schema the resource will return after settlement. */
+    outputSchema?: unknown;
+    /** Scheme-specific extras (token contract address, decimals, EIP-712 domain, etc.). */
+    extra?: Record<string, unknown>;
+}
+/**
+ * Payload format the wallet emits and the gateway verifies. Stored
+ * base64-encoded in the `X-PAYMENT` request header.
+ */
+export interface X402PaymentPayload {
+    /** Protocol version, currently 1. */
+    x402Version: number;
+    /** Echoes the scheme of the selected `X402PaymentRequirement`. */
+    scheme: string;
+    /** Echoes the network of the selected `X402PaymentRequirement`. */
+    network: string;
+    /** Scheme-specific signed payload (typed-data signature, tx hash, etc.). */
+    payload: unknown;
+}
+/**
+ * Minimal contract a caller's wallet must satisfy to settle x402 payments.
+ * Implementations live outside the SDK (CDP, viem, solana web3.js, x402-axios).
+ */
+export interface WalletLike {
+    /** Public address used in `accepts[].payTo` matching when relevant. */
+    address: string;
+    /**
+     * Sign the chosen payment requirement and return the base64-encoded
+     * `X-PAYMENT` header value the SDK will attach to the retry request.
+     */
+    signX402Payload(req: X402PaymentRequirement): Promise<string>;
+}
+/**
+ * Settle a `PaymentRequiredError` with the given wallet and replay the
+ * request via `retry(paymentHeader)`. Picks the first acceptable
+ * requirement from `error.accepts`; the wallet decides whether to sign or
+ * reject. If `error.accepts` is empty, the original error propagates.
+ *
+ * Dep-light by design: no signing libs, no fetch deps — the wallet does
+ * the cryptography. The retry's failure (including a second 402)
+ * propagates unchanged.
+ */
+export declare function payAndRetry<T>(error: PaymentRequiredError, wallet: WalletLike, retry: (paymentHeader: string) => Promise<T>): Promise<T>;
+//# sourceMappingURL=x402.d.ts.map

package/dist/x402.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"x402.d.ts","sourceRoot":"","sources":["../src/x402.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAExD;;;GAGG;AACH,MAAM,WAAW,sBAAsB;IACrC,+EAA+E;IAC/E,MAAM,EAAE,MAAM,CAAC;IACf,+DAA+D;IAC/D,OAAO,EAAE,MAAM,CAAC;IAChB,yCAAyC;IACzC,KAAK,EAAE,MAAM,CAAC;IACd,+EAA+E;IAC/E,iBAAiB,EAAE,MAAM,CAAC;IAC1B,sEAAsE;IACtE,QAAQ,EAAE,MAAM,CAAC;IACjB,qEAAqE;IACrE,QAAQ,EAAE,MAAM,CAAC;IACjB,oCAAoC;IACpC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,0EAA0E;IAC1E,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,uFAAuF;IACvF,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACjC;AAED;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC,qCAAqC;IACrC,WAAW,EAAE,MAAM,CAAC;IACpB,kEAAkE;IAClE,MAAM,EAAE,MAAM,CAAC;IACf,mEAAmE;IACnE,OAAO,EAAE,MAAM,CAAC;IAChB,4EAA4E;IAC5E,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB,uEAAuE;IACvE,OAAO,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,eAAe,CAAC,GAAG,EAAE,sBAAsB,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CAC/D;AAED;;;;;;;;;GASG;AACH,wBAAsB,WAAW,CAAC,CAAC,EACjC,KAAK,EAAE,oBAAoB,EAC3B,MAAM,EAAE,UAAU,EAClB,KAAK,EAAE,CAAC,aAAa,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,GAC3C,OAAO,CAAC,CAAC,CAAC,CAKZ"}

package/dist/x402.js

@@ -0,0 +1,29 @@
+/**
+ * x402 payment primitives — typed shapes the SDK and a wallet agree on.
+ *
+ * Mirrors the canonical x402 protocol shape (resource-URL flavor) so a generic
+ * x402 wallet client can sign these without an Unbrowse-specific adapter. The
+ * backend (`backend/src/middleware/x402-gate.ts:X402PaymentRequirementV2`) is
+ * the producer; this is the consumer-side declaration.
+ *
+ * IMPORTANT: this file MUST NOT import from `./client.js` — keep payment
+ * helpers tree-shakeable so callers who do not pay can drop the wallet code.
+ */
+/**
+ * Settle a `PaymentRequiredError` with the given wallet and replay the
+ * request via `retry(paymentHeader)`. Picks the first acceptable
+ * requirement from `error.accepts`; the wallet decides whether to sign or
+ * reject. If `error.accepts` is empty, the original error propagates.
+ *
+ * Dep-light by design: no signing libs, no fetch deps — the wallet does
+ * the cryptography. The retry's failure (including a second 402)
+ * propagates unchanged.
+ */
+export async function payAndRetry(error, wallet, retry) {
+    const requirement = error.accepts?.[0];
+    if (!requirement)
+        throw error;
+    const paymentHeader = await wallet.signX402Payload(requirement);
+    return retry(paymentHeader);
+}
+//# sourceMappingURL=x402.js.map

package/dist/x402.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"x402.js","sourceRoot":"","sources":["../src/x402.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AA0DH;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,KAA2B,EAC3B,MAAkB,EAClB,KAA4C;IAE5C,MAAM,WAAW,GAAG,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC;IACvC,IAAI,CAAC,WAAW;QAAE,MAAM,KAAK,CAAC;IAC9B,MAAM,aAAa,GAAG,MAAM,MAAM,CAAC,eAAe,CAAC,WAAW,CAAC,CAAC;IAChE,OAAO,KAAK,CAAC,aAAa,CAAC,CAAC;AAC9B,CAAC"}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@unbrowse/sdk",
+  "version": "6.17.0-preview.6",
+  "description": "Thin TypeScript SDK for the canonical Unbrowse local server API.",
+  "type": "module",
+  "license": "MIT",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test:smoke": "bun test test/integration.smoke.test.ts",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "prepack": "npm run build",
+    "docs:validate": "node scripts/validate-docs.js",
+    "docs:validate:links": "node scripts/validate-links-deep.js",
+    "docs:validate:examples": "node scripts/validate-examples.js",
+    "docs:validate:quality": "node scripts/validate-content-quality.js",
+    "docs:validate:all": "npm run docs:validate && npm run docs:validate:examples && npm run docs:validate:quality",
+    "docs:lint": "npm run docs:validate:all",
+    "test:docs": "npm run docs:validate:all"
+  },
+  "peerDependencies": {
+    "unbrowse": ">=6.15.0"
+  },
+  "peerDependenciesMeta": {
+    "unbrowse": {
+      "optional": true
+    }
+  },
+  "optionalDependencies": {
+    "unbrowse": "^6.15.0"
+  },
+  "devDependencies": {
+    "typescript": "^6.0.2"
+  }
+}