@unbrowse/sdk 12.1.0 → 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,4 @@
-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";

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 })))}`;
@@ -262,6 +325,7 @@ export {
   UnbrowseError,
   UnbrowseMcp,
   cursorInstallLink,
+  isEgressStep,
   mcpCommands,
   normalizeHost,
   parseRpcBody,

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.1.0",
+  "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",