unbrowse 7.2.0 → 8.1.1

package/bin/unbrowse-wrapper.mjs

@@ -1,12 +1,13 @@
 #!/usr/bin/env node
 
 /**
- * Thin wrapper — execs the compiled binary if available,
- * falls back to the package-managed Node launcher if not.
+ * Thin wrapper — runs an explicitly-provided compiled binary if present (the
+ * UNBROWSE_INSTALL_BINARY_PATH opt-in, used by CI smoke tests), else the package's
+ * readable, unsigned runtime via the launcher. There is NO auto-download fallback —
+ * the readable runtime is the default; the runtime IS the client.
  */
 
 import { existsSync, readFileSync } from "node:fs";
-import { createRequire } from "node:module";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { spawn } from "node:child_process";
@@ -14,22 +15,8 @@ import { unbrowseBinaryName } from "../scripts/release-assets.mjs";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const packageRoot = join(__dirname, "..");
-// Windows ships `unbrowse.exe`; postinstall installs it under that name, so the
-// wrapper must look for the same name (a plain `unbrowse` never exists on win).
 const binaryPath = join(__dirname, unbrowseBinaryName(process.platform));
 const launcherPath = join(__dirname, "unbrowse.js");
-const require = createRequire(import.meta.url);
-
-const REQUIRED_FALLBACK_PACKAGES = [
-  "tsx",
-  "bs58",
-  "@solana/kit",
-  "@cascade-fyi/splits-sdk",
-];
-
-const KNOWN_BAD_FALLBACK_VERSIONS = new Set([
-  "2.10.2",
-]);
 
 function readInstalledVersion() {
   try {
@@ -55,18 +42,6 @@ function failInstall(reason, exitCode = 1) {
   process.exit(exitCode);
 }
 
-function missingFallbackPackages() {
-  const missing = [];
-  for (const specifier of REQUIRED_FALLBACK_PACKAGES) {
-    try {
-      require.resolve(specifier);
-    } catch {
-      missing.push(specifier);
-    }
-  }
-  return missing;
-}
-
 function spawnEntrypoint(command, args) {
   const child = spawn(command, args, {
     stdio: "inherit",
@@ -92,19 +67,11 @@ if (process.argv.includes("--version") || process.argv.includes("-v")) {
 }
 
 if (existsSync(binaryPath)) {
+  // an explicitly-injected binary (UNBROWSE_INSTALL_BINARY_PATH) — not a fallback
   spawnEntrypoint(binaryPath, process.argv.slice(2));
 } else {
-  const installedVersion = readInstalledVersion();
-  if (KNOWN_BAD_FALLBACK_VERSIONS.has(installedVersion)) {
-    failInstall(
-      `Installed package version ${installedVersion} is known-bad in source fallback mode and shipped an incomplete runtime dependency set.`,
-    );
-  }
-
-  const missing = missingFallbackPackages();
-  if (missing.length > 0) {
-    failInstall(`Fallback runtime is missing required packages: ${missing.join(", ")}.`);
-  }
-
+  // the default: the readable, unsigned runtime via the launcher. The source IS the
+  // runtime, so the client is auditable on disk — security lives in the wallet-sealed
+  // crypto, not in hiding the client. The hole fills any internet gap.
   spawnEntrypoint(process.execPath, [launcherPath, ...process.argv.slice(2)]);
 }

package/bin/unbrowse.js

@@ -1,50 +1,63 @@
 #!/usr/bin/env node
 
-// Fallback stub. The real runtime is the native binary at bin/unbrowse,
-// downloaded by scripts/postinstall.mjs from the GitHub release. This file
-// only runs if the wrapper could not find that binary, which means either:
-//   1. The postinstall download was skipped (CI / UNBROWSE_SKIP_BINARY_DOWNLOAD).
-//   2. The download failed (network issue, GH release unavailable).
-//   3. The platform is not in SUPPORTED_TARGETS (rare).
-//
-// In all three cases, the npm tarball intentionally does NOT ship the JS
-// runtime, so there is nothing to fall back to. Print a clear repair message
-// and exit; users should re-run install or build from source.
-
-import { readFileSync } from "node:fs";
+/**
+ * Auditable runtime launcher.
+ *
+ * The package ships a READABLE, UNSIGNED runtime at `runtime/cli.js` (an
+ * unminified Bun bundle of the source) and runs it here. The source IS the
+ * runtime, so the client — including the zk/crypto verification path — is fully
+ * auditable on disk. There is nothing to hide: every secret is wallet-sealed
+ * (AES-GCM under a key only the holder derives), so reverse-engineering the
+ * client yields nothing. Security lives in the wallet, not in obfuscation.
+ *
+ * The runtime requires Bun. If a compiled binary was downloaded post-install,
+ * the wrapper runs that instead and never reaches this launcher.
+ */
+
+import { existsSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
+import { spawnSync } from "node:child_process";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const runtime = join(here, "..", "runtime", "cli.js");
 
-const packageRoot = dirname(dirname(fileURLToPath(import.meta.url)));
+function fail(msg, code = 1) {
+  process.stderr.write(`[unbrowse] ${msg}\n`);
+  process.exit(code);
+}
 
-function readVersion() {
-  try {
-    const pkg = JSON.parse(readFileSync(join(packageRoot, "package.json"), "utf8"));
-    return typeof pkg.version === "string" ? pkg.version : "unknown";
-  } catch {
-    return "unknown";
+function findBun() {
+  const candidates = [
+    process.env.UNBROWSE_BUN_BIN,
+    "bun",
+    join(process.env.HOME || "", ".bun", "bin", "bun"),
+  ].filter(Boolean);
+  for (const candidate of candidates) {
+    try {
+      const probe = spawnSync(candidate, ["--version"], { stdio: "ignore" });
+      if (probe.status === 0) return candidate;
+    } catch {
+      /* try the next candidate */
+    }
   }
+  return null;
+}
+
+if (!existsSync(runtime)) {
+  fail("readable runtime missing (runtime/cli.js). Reinstall: npm install -g unbrowse@latest");
+}
+
+const bun = findBun();
+if (!bun) {
+  fail("this build runs on Bun. Install it from https://bun.sh, then re-run (or set UNBROWSE_BUN_BIN).");
 }
 
-const version = readVersion();
-const target = `${process.platform}-${process.arch}`;
-
-process.stderr.write(
-  [
-    "[unbrowse] native binary not installed",
-    `[unbrowse] package version: ${version}`,
-    `[unbrowse] platform: ${target}`,
-    "",
-    "[unbrowse] The npm package ships only the native binary downloaded on",
-    "[unbrowse] postinstall. Possible causes:",
-    "[unbrowse]   - postinstall was skipped (CI / UNBROWSE_SKIP_BINARY_DOWNLOAD)",
-    "[unbrowse]   - download failed (check stderr from `npm install`)",
-    "[unbrowse]   - platform is not in the prebuilt set",
-    "",
-    "[unbrowse] Repair:",
-    "[unbrowse]   node packages/skill/scripts/postinstall.mjs   # retry download",
-    "[unbrowse]   npm uninstall -g unbrowse && npm install -g unbrowse@latest",
-    "[unbrowse]   build from source: https://github.com/unbrowse-ai/unbrowse",
-  ].join("\n") + "\n",
-);
-process.exit(1);
+const child = spawnSync(bun, [runtime, ...process.argv.slice(2)], {
+  stdio: "inherit",
+  cwd: process.cwd(),
+  env: process.env,
+});
+if (child.error) fail(`failed to launch runtime: ${child.error.message}`);
+if (child.signal) process.kill(process.pid, child.signal);
+process.exit(child.status ?? 1);

package/dist-sdk/adapters/browser-use.d.ts

@@ -0,0 +1,28 @@
+/**
+ * src/sdk/adapters/browser-use.ts — drop-in shape for the `browser-use` Agent.
+ *
+ * Same construction (`new Agent({ task, llm })`) and `.run()` — but the task is filled
+ * through the wallet-sealed unbrowse hole (resolve → execute → capture) instead of a
+ * driven headful browser. `llm` is accepted for signature compatibility; the hole
+ * decides when a real browser is actually needed (browser-open is the fallback, not the
+ * substrate).
+ */
+import { type HoleItem, type HoleOptions } from "../hole.js";
+export interface AgentOptions extends HoleOptions {
+    task: string;
+    llm?: unknown;
+    maxSteps?: number;
+}
+export interface AgentResult {
+    task: string;
+    done: boolean;
+    result: string;
+    items: HoleItem[];
+}
+export declare class Agent {
+    private readonly hole;
+    private readonly task;
+    constructor(options: AgentOptions);
+    run(): Promise<AgentResult>;
+}
+export default Agent;

package/dist-sdk/adapters/browser-use.js

@@ -0,0 +1,28 @@
+/**
+ * src/sdk/adapters/browser-use.ts — drop-in shape for the `browser-use` Agent.
+ *
+ * Same construction (`new Agent({ task, llm })`) and `.run()` — but the task is filled
+ * through the wallet-sealed unbrowse hole (resolve → execute → capture) instead of a
+ * driven headful browser. `llm` is accepted for signature compatibility; the hole
+ * decides when a real browser is actually needed (browser-open is the fallback, not the
+ * substrate).
+ */
+import { createHole } from "../hole.js";
+export class Agent {
+    hole;
+    task;
+    constructor(options) {
+        this.task = options.task;
+        this.hole = createHole(options);
+    }
+    async run() {
+        const r = await this.hole.fill({ intent: this.task });
+        return {
+            task: this.task,
+            done: r.ok,
+            result: r.answer ?? r.items[0]?.text ?? "",
+            items: r.items,
+        };
+    }
+}
+export default Agent;

package/dist-sdk/adapters/exa.d.ts

@@ -0,0 +1,49 @@
+/**
+ * src/sdk/adapters/exa.ts — drop-in replacement for the `exa-js` client.
+ *
+ * Same construction (`new Exa(apiKey)`) and the same method shapes (`search`,
+ * `searchAndContents`, `getContents`, `answer`) returning exa-shaped results — but every
+ * call routes through the wallet-sealed unbrowse hole instead of Exa's API. Swap the
+ * import, keep your code. Inject a `transport`/`wallet` (HoleOptions) for tests or to
+ * bind the hole to a wallet.
+ */
+import { type HoleOptions } from "../hole.js";
+export interface ExaSearchOptions {
+    numResults?: number;
+    type?: string;
+    includeDomains?: string[];
+    startPublishedDate?: string;
+    contents?: {
+        text?: boolean;
+        highlights?: boolean;
+        summary?: boolean;
+    };
+    [key: string]: unknown;
+}
+export interface ExaResult {
+    title: string | null;
+    url: string;
+    publishedDate?: string;
+    score?: number;
+    text?: string;
+    highlights?: string[];
+    summary?: string;
+}
+export interface ExaSearchResponse {
+    results: ExaResult[];
+    autopromptString?: string;
+}
+export declare class Exa {
+    private readonly hole;
+    constructor(_apiKey?: string, opts?: HoleOptions);
+    search(query: string, options?: ExaSearchOptions): Promise<ExaSearchResponse>;
+    searchAndContents(query: string, options?: ExaSearchOptions): Promise<ExaSearchResponse>;
+    getContents(urls: string[], _options?: {
+        text?: boolean;
+        highlights?: boolean;
+    }): Promise<ExaSearchResponse>;
+    answer(question: string): Promise<{
+        answer: string;
+    }>;
+}
+export default Exa;

package/dist-sdk/adapters/exa.js

@@ -0,0 +1,50 @@
+/**
+ * src/sdk/adapters/exa.ts — drop-in replacement for the `exa-js` client.
+ *
+ * Same construction (`new Exa(apiKey)`) and the same method shapes (`search`,
+ * `searchAndContents`, `getContents`, `answer`) returning exa-shaped results — but every
+ * call routes through the wallet-sealed unbrowse hole instead of Exa's API. Swap the
+ * import, keep your code. Inject a `transport`/`wallet` (HoleOptions) for tests or to
+ * bind the hole to a wallet.
+ */
+import { createHole } from "../hole.js";
+function toExa(it) {
+    return {
+        title: it.title ?? null,
+        url: it.url ?? "",
+        publishedDate: it.publishedDate,
+        score: it.score,
+        text: typeof it.text === "string" ? it.text : undefined,
+        highlights: Array.isArray(it.highlights) ? it.highlights : undefined,
+        summary: typeof it.summary === "string" ? it.summary : undefined,
+    };
+}
+export class Exa {
+    hole;
+    constructor(_apiKey, opts = {}) {
+        this.hole = createHole(opts);
+    }
+    async search(query, options = {}) {
+        const r = await this.hole.fill({ intent: query, params: options });
+        const n = options.numResults ?? r.items.length;
+        return { results: r.items.slice(0, n).map(toExa) };
+    }
+    async searchAndContents(query, options = {}) {
+        return this.search(query, { ...options, contents: { text: true, ...(options.contents ?? {}) } });
+    }
+    async getContents(urls, _options = {}) {
+        const results = [];
+        for (const url of urls) {
+            const r = await this.hole.fill({ intent: `contents of ${url}`, url });
+            const first = r.items[0];
+            if (first)
+                results.push(toExa({ ...first, url }));
+        }
+        return { results };
+    }
+    async answer(question) {
+        const r = await this.hole.fill({ intent: question });
+        return { answer: r.answer ?? r.items[0]?.text ?? "" };
+    }
+}
+export default Exa;

package/dist-sdk/adapters/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * src/sdk/adapters/index.ts — drop-in client adapters over the unbrowse hole.
+ *
+ * Each adapter mirrors a popular client's construction + method shapes, so swapping the
+ * import is the only change needed:
+ *
+ *   import Exa from "@unbrowse/sdk/adapters/exa";          // was: import Exa from "exa-js"
+ *   import { tavily } from "@unbrowse/sdk/adapters/tavily"; // was: from "@tavily/core"
+ *   import { Agent } from "@unbrowse/sdk/adapters/browser-use";
+ *
+ * All of them wrap the same wallet-sealed streaming hole (`../hole.ts`).
+ */
+export { Exa, type ExaResult, type ExaSearchResponse, type ExaSearchOptions } from "./exa.js";
+export { tavily, type TavilyClient, type TavilyResult, type TavilySearchResponse } from "./tavily.js";
+export { Agent, type AgentOptions, type AgentResult } from "./browser-use.js";
+export { createHole, Hole, type HoleRequest, type HoleResult, type HoleItem, type HoleOptions, type HoleTransport, type WalletSeal, } from "../hole.js";

package/dist-sdk/adapters/index.js

@@ -0,0 +1,16 @@
+/**
+ * src/sdk/adapters/index.ts — drop-in client adapters over the unbrowse hole.
+ *
+ * Each adapter mirrors a popular client's construction + method shapes, so swapping the
+ * import is the only change needed:
+ *
+ *   import Exa from "@unbrowse/sdk/adapters/exa";          // was: import Exa from "exa-js"
+ *   import { tavily } from "@unbrowse/sdk/adapters/tavily"; // was: from "@tavily/core"
+ *   import { Agent } from "@unbrowse/sdk/adapters/browser-use";
+ *
+ * All of them wrap the same wallet-sealed streaming hole (`../hole.ts`).
+ */
+export { Exa } from "./exa.js";
+export { tavily } from "./tavily.js";
+export { Agent } from "./browser-use.js";
+export { createHole, Hole, } from "../hole.js";

package/dist-sdk/adapters/tavily.d.ts

@@ -0,0 +1,36 @@
+/**
+ * src/sdk/adapters/tavily.ts — drop-in replacement for the `@tavily/core` client.
+ *
+ * Same construction (`tavily({ apiKey })`) and the same methods (`search`, `extract`)
+ * returning tavily-shaped responses — routed through the wallet-sealed unbrowse hole.
+ */
+import { type HoleOptions } from "../hole.js";
+export interface TavilyResult {
+    title: string;
+    url: string;
+    content: string;
+    score: number;
+    rawContent?: string;
+}
+export interface TavilySearchResponse {
+    query: string;
+    answer?: string;
+    results: TavilyResult[];
+    responseTime?: number;
+}
+export interface TavilyExtractResponse {
+    results: Array<{
+        url: string;
+        rawContent: string;
+    }>;
+    failedResults: string[];
+}
+export interface TavilyOptions extends HoleOptions {
+    apiKey?: string;
+}
+export interface TavilyClient {
+    search(query: string, options?: Record<string, unknown>): Promise<TavilySearchResponse>;
+    extract(urls: string[]): Promise<TavilyExtractResponse>;
+}
+export declare function tavily(options?: TavilyOptions): TavilyClient;
+export default tavily;

package/dist-sdk/adapters/tavily.js

@@ -0,0 +1,39 @@
+/**
+ * src/sdk/adapters/tavily.ts — drop-in replacement for the `@tavily/core` client.
+ *
+ * Same construction (`tavily({ apiKey })`) and the same methods (`search`, `extract`)
+ * returning tavily-shaped responses — routed through the wallet-sealed unbrowse hole.
+ */
+import { createHole } from "../hole.js";
+function toTavily(it) {
+    return {
+        title: it.title ?? "",
+        url: it.url ?? "",
+        content: typeof it.text === "string" ? it.text : "",
+        score: typeof it.score === "number" ? it.score : 0,
+        rawContent: typeof it.rawContent === "string" ? it.rawContent : undefined,
+    };
+}
+export function tavily(options = {}) {
+    const hole = createHole(options);
+    return {
+        async search(query, opts = {}) {
+            const r = await hole.fill({ intent: query, params: opts });
+            return { query, answer: r.answer, results: r.items.map(toTavily) };
+        },
+        async extract(urls) {
+            const results = [];
+            const failedResults = [];
+            for (const url of urls) {
+                const r = await hole.fill({ intent: `extract ${url}`, url });
+                const text = r.items[0]?.text;
+                if (typeof text === "string" && text)
+                    results.push({ url, rawContent: text });
+                else
+                    failedResults.push(url);
+            }
+            return { results, failedResults };
+        },
+    };
+}
+export default tavily;

package/dist-sdk/client.d.ts

@@ -0,0 +1,43 @@
+import type { AccountMe, AccountCredits, ApiKeyCreateInput, ApiKeyCreateResponse, ApiKeyListResponse, ApiKeyRevokeResponse, ExecuteInput, ExecuteResponse, HealthResponse, RequestOptions, ResolveInput, ResolveResponse, SearchInput, SearchResponse, SponsorStatus, UnbrowseClientOptions } from "./types.js";
+import type { WorkerProxyCapabilities, WorkerProxyRequest, WorkerProxyResponse } from "./proxy-types.js";
+export declare class Unbrowse {
+    readonly apiKey: string | undefined;
+    readonly baseURL: string;
+    readonly timeout: number;
+    readonly maxRetries: number;
+    readonly logLevel: NonNullable<UnbrowseClientOptions["logLevel"]>;
+    private readonly _fetch;
+    private readonly defaultHeaders;
+    readonly account: AccountResource;
+    readonly keys: KeysResource;
+    readonly proxy: ProxyResource;
+    constructor(opts?: UnbrowseClientOptions);
+    resolve(input: ResolveInput, opts?: RequestOptions): Promise<ResolveResponse>;
+    execute(input: ExecuteInput, opts?: RequestOptions): Promise<ExecuteResponse>;
+    search(input: SearchInput, opts?: RequestOptions): Promise<SearchResponse>;
+    health(opts?: RequestOptions): Promise<HealthResponse>;
+    request<T>(method: string, path: string, body: unknown, opts: RequestOptions): Promise<T>;
+    private debug;
+}
+declare class AccountResource {
+    private readonly client;
+    constructor(client: Unbrowse);
+    me(opts?: RequestOptions): Promise<AccountMe>;
+    credits(opts?: RequestOptions): Promise<AccountCredits>;
+    sponsorStatus(opts?: RequestOptions): Promise<SponsorStatus>;
+}
+declare class KeysResource {
+    private readonly client;
+    constructor(client: Unbrowse);
+    list(opts?: RequestOptions): Promise<ApiKeyListResponse>;
+    create(input?: ApiKeyCreateInput, opts?: RequestOptions): Promise<ApiKeyCreateResponse>;
+    revoke(keyId: string, opts?: RequestOptions): Promise<ApiKeyRevokeResponse>;
+    rotate(keyId: string, opts?: RequestOptions): Promise<ApiKeyCreateResponse>;
+}
+declare class ProxyResource {
+    private readonly client;
+    constructor(client: Unbrowse);
+    fetch(req: WorkerProxyRequest, opts?: RequestOptions): Promise<WorkerProxyResponse>;
+    capabilities(opts?: RequestOptions): Promise<WorkerProxyCapabilities>;
+}
+export {};