@unbrowse/sdk 12.0.1 → 12.1.1

package/README.md

@@ -37,6 +37,17 @@ an OAuth access token); `baseUrl` takes an origin or an `/api/v1` URL and defaul
 | `answer(runId, { field: value })` | `GET /runs/:id`, `POST /runs/:id/responses`, `GET /runs/:id` |
 | `resume(runId, expectedStateRevision, responses)` | `POST /runs/:id/responses` |
 | `cancel(runId)` | `POST /runs/:id/cancel` |
+| `runOnClient(request, { fetch?, onRequest?, timeoutMs? })` | `POST /runs` with `egress: "client"`, then `POST /egress/:id` per request |
+| `egress(egressId)` / `answerEgress(egressId, requestId, { response } \| { error })` / `closeEgress(egressId)` | `GET` / `POST` / `DELETE /egress/:id` |
+
+`runOnClient` sends the run's requests to the website from this machine, so the site sees your IP;
+Unbrowse decides each request and reads each response, and never contacts the site itself:
+
+```ts
+const run = await unbrowse.runOnClient({ capability: "hn.top_stories", input: { limit: 3 } });
+// Your own network stack or proxy, and a look at each request before it leaves:
+await unbrowse.runOnClient({ task: "search eatigo for italian" }, { fetch: myFetch, onRequest: (r) => allowed(r.url) });
+```
 
 A run is `succeeded` only when its result is verified (`verified: true`). `input_required` is not a
 failure: answer on the same run. `outcome_unknown` means a change may have happened; do not retry

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import type { Json, RunRequest, RunView } from "./types.ts";
+import type { EgressRequest, EgressResponse, EgressStep, Json, RunRequest, RunView } from "./types.ts";
 export declare const DEFAULT_BASE_URL = "https://unbrowse.ai/api/v1";
 export type UnbrowseOptions = {
     /** API key (`ub_live_…`) or OAuth access token. Defaults to `UNBROWSE_API_KEY`. Public routes need none. */
@@ -43,6 +43,29 @@ export declare class Unbrowse {
         timeoutMs?: number;
     }): Promise<RunView>;
     cancel(runId: string): Promise<any>;
+    /**
+     * Run with the site requests sent from this machine. Unbrowse chooses each request and reads each response;
+     * this sends them with `fetch` (yours by default) and posts the raw responses back until the run finishes.
+     * `onRequest` sees each request first; return `false` to refuse it (the run gets a network error).
+     */
+    runOnClient(request: Omit<RunRequest, "egress">, opts?: {
+        fetch?: typeof globalThis.fetch;
+        onRequest?: (req: EgressRequest) => boolean | void | Promise<boolean | void>;
+        timeoutMs?: number;
+    }): Promise<RunView>;
+    /** What a client-egress run is waiting for: the next request(s), or the finished run. */
+    egress(egressId: string): Promise<RunView | EgressStep>;
+    /** Post the site's response (or why it could not be sent) for one request; returns what comes next. */
+    answerEgress(egressId: string, requestId: string, answer: {
+        response: EgressResponse;
+    } | {
+        error: string;
+    }): Promise<RunView | EgressStep>;
+    /** Abandon a client-egress run. */
+    closeEgress(egressId: string): Promise<{
+        egressId: string;
+        status: "closed";
+    }>;
     /** Your private capabilities first, then the public registry. */
     discover(query: string): Promise<any>;
     capability(id: string): Promise<any>;
@@ -125,3 +148,5 @@ export type LoginView = {
     createdAt: number;
     rotatedAt?: number;
 };
+/** Whether a run answer is a client-egress step (requests to send) rather than a run. */
+export declare function isEgressStep(v: unknown): v is EgressStep;

package/dist/index.d.ts

@@ -1,4 +1,6 @@
-export { DEFAULT_BASE_URL, Unbrowse, UnbrowseError, normalizeHost } from "./client.ts";
+export { DEFAULT_BASE_URL, Unbrowse, UnbrowseError, isEgressStep, normalizeHost } from "./client.ts";
 export type { LoginView, UnbrowseOptions } from "./client.ts";
 export type * from "./types.ts";
 export { cursorInstallLink, mcpCommands, vscodeInstallLink } from "./mcp-install.ts";
+export { DEFAULT_MCP_URL, MCP_PROTOCOL_VERSION, UnbrowseMcp, parseRpcBody, resultText } from "./mcp.ts";
+export type { McpContent, McpOptions, McpTool, McpToolResult } from "./mcp.ts";

package/dist/index.js

@@ -100,6 +100,43 @@ class Unbrowse {
   cancel(runId) {
     return this.req(`/runs/${runId}/cancel`, { method: "POST" });
   }
+  async runOnClient(request, opts = {}) {
+    const send = opts.fetch ?? ((...a) => globalThis.fetch(...a));
+    const deadline = Date.now() + (opts.timeoutMs ?? 600000);
+    let step = await this.run({ ...request, egress: "client" });
+    while (isEgressStep(step)) {
+      if (Date.now() > deadline) {
+        await this.closeEgress(step.egressId).catch(() => {
+          return;
+        });
+        throw new UnbrowseError("client-egress run did not finish in time", 408, "timeout");
+      }
+      const { egressId } = step;
+      for (const req of step.requests) {
+        let answer;
+        try {
+          if (await opts.onRequest?.(req) === false)
+            throw new Error("refused by onRequest");
+          answer = { response: await sendEgress(send, req) };
+        } catch (err) {
+          answer = { error: err instanceof Error ? err.message : String(err) };
+        }
+        step = await this.answerEgress(egressId, req.id, answer);
+        if (!isEgressStep(step))
+          break;
+      }
+    }
+    return step;
+  }
+  egress(egressId) {
+    return this.req(`/egress/${egressId}`);
+  }
+  answerEgress(egressId, requestId, answer) {
+    return this.post(`/egress/${egressId}`, { requestId, ...answer });
+  }
+  closeEgress(egressId) {
+    return this.req(`/egress/${egressId}`, { method: "DELETE" });
+  }
   discover(query) {
     return this.post("/capabilities/search", { query });
   }
@@ -161,6 +198,32 @@ function normalizeHost(site) {
     host = new URL(host).hostname;
   return host.replace(/\/.*$/, "").replace(/^www\./, "");
 }
+function isEgressStep(v) {
+  return !!v && typeof v === "object" && v.status === "egress_required";
+}
+async function sendEgress(send, req) {
+  const body = req.body === undefined ? undefined : req.bodyEncoding === "base64" ? base64ToBytes(req.body) : req.body;
+  const res = await send(req.url, { method: req.method, headers: req.headers, redirect: req.redirect, ...body !== undefined ? { body } : {} });
+  const headers = [];
+  res.headers.forEach((value, name) => headers.push([name, value]));
+  const cookies = res.headers.getSetCookie?.();
+  const pairs = cookies?.length ? [...headers.filter(([n]) => n.toLowerCase() !== "set-cookie"), ...cookies.map((c) => ["set-cookie", c])] : headers;
+  const bytes = new Uint8Array(await res.arrayBuffer());
+  return { status: res.status, headers: pairs, body: bytesToBase64(bytes), bodyEncoding: "base64", ...res.url ? { url: res.url } : {} };
+}
+function base64ToBytes(b64) {
+  const bin = atob(b64);
+  const out = new Uint8Array(bin.length);
+  for (let i = 0;i < bin.length; i++)
+    out[i] = bin.charCodeAt(i);
+  return out;
+}
+function bytesToBase64(bytes) {
+  let bin = "";
+  for (let i = 0;i < bytes.length; i += 32768)
+    bin += String.fromCharCode(...bytes.subarray(i, i + 32768));
+  return btoa(bin);
+}
 // src/mcp-install.ts
 function cursorInstallLink(url) {
   return `cursor://anysphere.cursor-deeplink/mcp/install?name=unbrowse&config=${encodeURIComponent(btoa(JSON.stringify({ url })))}`;
@@ -175,12 +238,97 @@ function mcpCommands(url) {
     json: JSON.stringify({ mcpServers: { unbrowse: { url } } }, null, 2)
   };
 }
+// src/mcp.ts
+var DEFAULT_MCP_URL = "https://unbrowse.ai/mcp";
+var MCP_PROTOCOL_VERSION = "2025-11-25";
+var env2 = (name) => (typeof process !== "undefined" ? process.env?.[name] : undefined) || undefined;
+function parseRpcBody(text) {
+  const trimmed = text.trim();
+  if (trimmed.startsWith("{"))
+    return JSON.parse(trimmed);
+  const events = trimmed.split(/\n\n+/).flatMap((block) => {
+    const data = block.split(`
+`).filter((l) => l.startsWith("data:")).map((l) => l.slice(5).trimStart()).join(`
+`);
+    return data ? [data] : [];
+  });
+  if (!events.length)
+    throw new UnbrowseError("Empty MCP response", 502, "mcp_empty");
+  return JSON.parse(events[events.length - 1]);
+}
+function resultText(result) {
+  const text = result.content?.filter((c) => c.type === "text" && typeof c.text === "string").map((c) => c.text).join(`
+`);
+  return text || (result.structuredContent === undefined ? "" : JSON.stringify(result.structuredContent));
+}
+
+class UnbrowseMcp {
+  url;
+  apiKey;
+  endUser;
+  client;
+  fetchImpl;
+  nextId = 1;
+  constructor(opts = {}) {
+    this.url = (opts.url ?? env2("UNBROWSE_MCP_URL") ?? DEFAULT_MCP_URL).replace(/\/+$/, "");
+    this.apiKey = opts.apiKey ?? env2("UNBROWSE_API_KEY");
+    this.endUser = opts.endUser ?? env2("UNBROWSE_END_USER");
+    this.client = opts.client ?? "sdk";
+    this.fetchImpl = opts.fetch ?? ((...a) => globalThis.fetch(...a));
+  }
+  async rpc(method, params) {
+    const res = await this.fetchImpl(this.url, {
+      method: "POST",
+      headers: {
+        ...this.apiKey ? { authorization: `Bearer ${this.apiKey}` } : {},
+        ...this.endUser ? { "x-unbrowse-end-user": this.endUser } : {},
+        "content-type": "application/json",
+        accept: "application/json, text/event-stream",
+        "mcp-protocol-version": MCP_PROTOCOL_VERSION,
+        "user-agent": `unbrowse-${this.client}`
+      },
+      body: JSON.stringify({ jsonrpc: "2.0", id: this.nextId++, method, ...params ? { params } : {} })
+    });
+    const text = await res.text();
+    if (!res.ok) {
+      let body = {};
+      try {
+        body = JSON.parse(text);
+      } catch {}
+      const err = typeof body.error === "object" ? body.error : undefined;
+      throw new UnbrowseError(err?.message ?? body.error_description ?? (res.statusText || `HTTP ${res.status}`), res.status, err?.code ?? (typeof body.error === "string" ? body.error : "http_error"), body);
+    }
+    const msg = parseRpcBody(text);
+    if (msg.error)
+      throw new UnbrowseError(msg.error.message, 200, msg.error.data?.code ?? `rpc_${msg.error.code}`, msg.error);
+    return msg.result;
+  }
+  async listTools() {
+    const tools = [];
+    let cursor;
+    do {
+      const page = await this.rpc("tools/list", cursor ? { cursor } : undefined);
+      tools.push(...page.tools);
+      cursor = page.nextCursor;
+    } while (cursor);
+    return tools;
+  }
+  callTool(name, args = {}) {
+    return this.rpc("tools/call", { name, arguments: args });
+  }
+}
 export {
   DEFAULT_BASE_URL,
+  DEFAULT_MCP_URL,
+  MCP_PROTOCOL_VERSION,
   Unbrowse,
   UnbrowseError,
+  UnbrowseMcp,
   cursorInstallLink,
+  isEgressStep,
   mcpCommands,
   normalizeHost,
+  parseRpcBody,
+  resultText,
   vscodeInstallLink
 };

package/dist/mcp.d.ts

@@ -0,0 +1,60 @@
+import type { Json } from "./types.ts";
+export declare const DEFAULT_MCP_URL = "https://unbrowse.ai/mcp";
+/** Sent as `Mcp-Protocol-Version`. The hosted server refuses 2025-06-18 on its streaming path. */
+export declare const MCP_PROTOCOL_VERSION = "2025-11-25";
+export type McpOptions = {
+    /** API key (`ub_live_…`) or OAuth access token. Defaults to `UNBROWSE_API_KEY`. */
+    apiKey?: string;
+    /** Defaults to `UNBROWSE_MCP_URL`, then https://unbrowse.ai/mcp. */
+    url?: string;
+    /** Org keys: the end user the call is for (`X-Unbrowse-End-User`). */
+    endUser?: string;
+    fetch?: typeof globalThis.fetch;
+    /** Client name sent on the wire (User-Agent suffix). */
+    client?: string;
+};
+export type McpTool = {
+    name: string;
+    description?: string;
+    inputSchema: {
+        type: "object";
+        properties?: Record<string, Json>;
+        required?: string[];
+    } & Record<string, unknown>;
+};
+export type McpContent = {
+    type: string;
+    text?: string;
+} & Record<string, unknown>;
+export type McpToolResult = {
+    content: McpContent[];
+    structuredContent?: Json;
+    isError?: boolean;
+};
+/** The JSON-RPC message in a response body: plain JSON, or the last `data:` event of an SSE stream. */
+export declare function parseRpcBody(text: string): {
+    result?: unknown;
+    error?: {
+        code: number;
+        message: string;
+        data?: {
+            code?: string;
+        } & Record<string, unknown>;
+    };
+};
+/** Plain text of a tool result: its text parts, else its structured content as JSON. */
+export declare function resultText(result: McpToolResult): string;
+export declare class UnbrowseMcp {
+    readonly url: string;
+    private apiKey?;
+    private endUser?;
+    private client;
+    private fetchImpl;
+    private nextId;
+    constructor(opts?: McpOptions);
+    /** One JSON-RPC call. MCP errors become UnbrowseError with the server's `data.code` (e.g. `browser_capacity`). */
+    rpc<T>(method: string, params?: Record<string, unknown>): Promise<T>;
+    /** Every tool this key can call: the core tools plus the workspace's learned and indexed ones. */
+    listTools(): Promise<McpTool[]>;
+    callTool(name: string, args?: Record<string, unknown>): Promise<McpToolResult>;
+}

package/dist/types.d.ts

@@ -55,6 +55,39 @@ export type RunRequest = {
         maxOperations?: number;
     };
     executionPlane?: DeploymentProfile;
+    /** `client`: you send the site requests from your own IP (see `Unbrowse.runOnClient`). Default `server`. */
+    egress?: "server" | "client";
+};
+/** A site request for you to send, in a client-egress run. */
+export type EgressRequest = {
+    /** Answer with this as `requestId`. */
+    id: string;
+    method: string;
+    url: string;
+    headers: Record<string, string>;
+    body?: string;
+    bodyEncoding?: "text" | "base64";
+    /** `manual`: do not follow redirects; return the 3xx as it came. */
+    redirect: "follow" | "manual";
+    /** The same request as a curl command. */
+    curl: string;
+};
+/** A client-egress run waiting for you to send its next site request(s). */
+export type EgressStep = {
+    status: "egress_required";
+    egressId: string;
+    requests: EgressRequest[];
+};
+/** The site's response to one request, as you got it. */
+export type EgressResponse = {
+    status: number;
+    /** `[name, value]` pairs keep repeated headers (set-cookie). */
+    headers?: [string, string][] | Record<string, string | string[]>;
+    /** Decoded body (after gzip/brotli): text, or base64 with `bodyEncoding: "base64"`. Up to 10 MB. */
+    body?: string;
+    bodyEncoding?: "text" | "base64";
+    /** The final URL, if you followed redirects. */
+    url?: string;
 };
 export type RunView = {
     runId: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrowse/sdk",
-  "version": "12.0.1",
+  "version": "12.1.1",
   "description": "TypeScript client for the Unbrowse API (unbrowse.ai/api/v1): runs, capabilities, learning, logins and the public site registry.",
   "license": "MIT",
   "type": "module",