@unbrowse/sdk 11.7.1 → 12.0.0-preview.2

package/README.md

@@ -1,54 +1,80 @@
 # @unbrowse/sdk
 
-Clients submit tasks to your Unbrowse API. The server indexes a site with Browser Use on the first request and replays observed HTTP reads afterward. The SDK never reverse-engineers a site or starts a local browser.
+TypeScript client for the Unbrowse API (`https://unbrowse.ai/api/v1`). Node 18.17+, Bun, Deno,
+or any runtime with `fetch`. No dependencies. The `unbrowse` CLI is built on it.
+
+```bash
+npm install https://github.com/unbrowse-ai/unbrowse-skill/releases/download/v12.0.0-alpha.1/unbrowse-sdk-12.0.0-alpha.1.tgz
+```
 
 ```ts
-import { Unbrowse } from '@unbrowse/sdk';
-
-const client = new Unbrowse({
-  baseUrl: process.env.UNBROWSE_API_URL,
-  apiKey: process.env.UNBROWSE_API_KEY,
-});
-const result = await client.run({
-  url: 'https://example.com/products',
-  intent: 'Find matching products',
-  params: { q: 'books' },
-});
+import { Unbrowse } from "@unbrowse/sdk";
+
+const ub = new Unbrowse(); // UNBROWSE_API_KEY, https://unbrowse.ai/api/v1
+
+let run = await ub.run({ task: "top stories on Hacker News", idempotencyKey: crypto.randomUUID() });
+run = await ub.wait(run.runId);                         // until it leaves accepted/working
+
+// Discover actual capabilities and schemas before selecting a site-specific run.
+console.log(await ub.discover("flight search"));
 ```
 
-Deploy the Worker and private executor before using the new API. The default hosted URL has not been cut over. See [server execution](../../docs/server-execution.md) for deployment and measured proof.
+Pass an `idempotencyKey` when you may retry: the same key returns the same run instead of starting
+a second one.
 
-## Credentials
+`new Unbrowse({ apiKey, baseUrl, fetch })`: `apiKey` defaults to `UNBROWSE_API_KEY` (an API key or
+an OAuth access token); `baseUrl` takes an origin or an `/api/v1` URL and defaults to
+`UNBROWSE_BASE_URL`, then v3. Public registry reads need no key.
 
-Provide transient origin-scoped headers with `credentials: { storage: 'local', origin, headers }`, or use `storeCredential(id, { origin, headers })` and pass `credentials: { storage: 'remote', id }`. The server encrypts remote credentials per tenant. `deleteCredential(id)` removes them. No plaintext credential-read endpoint exists.
+## Runs
 
-Both modes send requests through the API. Local custody means your application retains the credential between calls; the server necessarily processes it during execution. Never paste credentials into prompts or URLs.
+| Method | Route |
+|---|---|
+| `run({ task \| capability, targetUrl?, input?, interactionMode?, idempotencyKey? })` | `POST /runs` (key sent as `idempotency_key` + `Idempotency-Key`) |
+| `inspect(runId)` | `GET /runs/:id` |
+| `wait(runId, { timeoutMs? })` | polls `GET /runs/:id` |
+| `events(runId)` | `GET /runs/:id/events` |
+| `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` |
 
-## Explicit requests and retries
+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
+blindly. A run whose site needs a login nobody saved carries `signIn.url`: give it to the person.
 
-```ts
-const operationKey = crypto.randomUUID(); // retain for this intended operation
-await client.run({
-  url: 'https://example.com/api/items',
-  intent: 'Create the item requested by the user',
-  request: { method: 'POST', body: JSON.stringify({ name: 'Example' }) },
-}, { headers: { 'Idempotency-Key': operationKey } });
-```
+## Capabilities and learning
 
-Writes require an explicit method and retained key. The SDK does not retry execution automatically. An uncertain dispatch stays indeterminate; changed content under the same key is rejected. A completed duplicate returns the saved result. These rules do not guarantee exactly-once effects in an external system.
+| Method | Route |
+|---|---|
+| `discover(query)` | `POST /capabilities/search` |
+| `capability(id)`, `skills()` | `GET /capabilities/:id`, `GET /skills` |
+| `learn({ har \| traces, goal?, title? })` | `POST /learn` |
+| `learned(id?)`, `harnessYaml(id)`, `skillMd(id)` | `GET /learned[/:id[/harness.yaml\|/skill.md]]` |
 
-`resolve` requires a target URL and executes through the gateway. `execute` requires explicit URL and method; an old skill ID alone does not authorize a request. Search methods remain free discovery.
+## Account, logins, vault
 
-## Payments
+| Method | Route |
+|---|---|
+| `me()`, `usage()` | `GET /me`, `GET /usage` |
+| `logins.list()`, `.save(login)`, `.remove({ origin } \| { ref })` | `/logins` — values in, masked hints out |
+| `accounts.connect({ origin, username, password })`, `accounts.register({ origin, username })` | `/accounts/connections`, `/accounts/register` |
+| `vault()` | `GET /vault` — refs and audit, never secrets |
 
-Execution is free by default. No payment provider is required. Optional server configuration supports x402 Base USDC with Stripe transaction verification, Stripe MPP for Link Agent Wallet, and verified Stripe Billing subscription admission. Link agent payments use MPP; subscriptions use Billing.
+## Public registry
 
-A payment-required error contains response headers, the complete challenge, the operation key and `retryWithPayment(headers)`. Obtain a proof with an official payment client under explicit spending authority, then pass `PAYMENT-SIGNATURE` or `Authorization: Payment …` to that closure. It preserves request body and operation identity. The retained legacy `payAndRetry` helper does not implement this new protocol.
+| Method | Route |
+|---|---|
+| `sites(query?)`, `site(host)` | `GET /sites`, `GET /sites/:host` (no key) |
+| `openapi(host)` | `GET /sites/:host/openapi.json` |
+| `callTool(host, tool, input)` | `POST /sites/:host/call/:tool` (metered like a run) |
+| `siteMcpUrl(host)` | the site as its own MCP server |
 
-No paid mode is enabled automatically. Live Stripe/Link settlement requires configured provider accounts and independent validation. See [payment setup](../../docs/machine-payments.md).
+## Errors
 
-## Browser choices and limits
+Every failure throws `UnbrowseError` with `status`, `code` (the server's, e.g. `quota_exceeded`,
+`unknown_argument`) and `body`.
 
-Server-owned Chromium is the default. Remote Browser Use Cloud is explicit opt-in. `browser: 'disabled'` permits known-route replay but rejects a cache miss.
+## Install helpers
 
-Current learned routes are single observed JSON reads. Browser form interactions, multi-step DAGs, automatic password login/session refresh, binary downloads and streaming are outside this gateway. Local HTML parsing and research formatting may still run client-side; upstream execution goes through your API.
+`mcpCommands(url)`, `cursorInstallLink(url)`, `vscodeInstallLink(url)` build install commands and
+links for the hosted MCP (`https://unbrowse.ai/mcp`). They never carry a key.

package/dist/client.d.ts

@@ -1,190 +1,127 @@
-import type { AttributionLedger, AvailableEndpoint, CreatorTransactionsResponse, Dashboard, ExecuteInput, ExecuteResponse, FeedbackInput, FeedbackResponse, HealthResponse, LoginInput, LoginResponse, RequestOptions, ResolveInput, ResolveResponse, SearchDomainInput, SearchInput, SearchResponse, SearchEndpointsInput, SearchEndpointsResponse, SkillManifest, StatsResponse, StealAuthInput, StealAuthResponse, UnbrowseClientOptions, PublishSkillInput, PublishResponse, AnnotateInput, AnnotateResponse, PaymentProvider, PaymentProviderResponse } from "./contracts.js";
-import type { ServerRunInput, ServerRunResult, ServerRegistry, ServerPrimitiveCall, ServerPrimitiveSelection, ServerWorkflow, ServerWorkflowResult } from "./server-types.js";
-import { type SpawnRuntimeOptions } from "./runtime.js";
-export declare function telemetryEnvDisabled(value: string | undefined): boolean;
-/** A first visit learns with the server browser for up to 8 minutes; wait longer than the server's deadline. */
-export declare const RUN_TIMEOUT_MS = 600000;
-/** Collapse an SDK route to a fixed category without retaining path parameters. */
-export declare function sdkUsageOperationForPath(path: string, method?: string): string;
+import type { 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. */
+    apiKey?: string;
+    /** Defaults to `UNBROWSE_BASE_URL` (origin or `/api/v1` URL), then https://unbrowse.ai/api/v1. */
+    baseUrl?: string;
+    fetch?: typeof globalThis.fetch;
+};
+/** An API error: the HTTP status, the server's error code and its body. */
+export declare class UnbrowseError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly body?: unknown | undefined;
+    constructor(message: string, status: number, code: string, body?: unknown | undefined);
+}
 export declare class Unbrowse {
     readonly baseUrl: string;
-    readonly apiKey?: string;
-    readonly clientId?: string;
-    private readonly defaultHeaders?;
-    private readonly fetchImpl;
-    private readonly timeoutMs?;
-    private readonly telemetryEnabled;
-    private readonly telemetryEndpoint;
-    private _runtimeHandle;
-    constructor(options?: UnbrowseClientOptions);
-    /**
-     * Build a `params` object from an `AvailableEndpoint.input_params` spec, using
-     * the `example_value` of each declared key. Skips keys without an example.
-     */
-    static paramsFromInputSpec(spec: AvailableEndpoint["input_params"] | undefined): Record<string, unknown>;
-    /**
-     * Point at an already-running Unbrowse runtime. No probe, no spawn.
-     * `.close()` is a no-op for the runtime (the caller owns it).
-     */
-    static connect(baseUrl: string, opts?: Omit<UnbrowseClientOptions, "baseUrl">): Promise<Unbrowse>;
-    /**
-     * Spawn a co-located Unbrowse runtime and return a client pointed at it.
-     * The client takes ownership of the child process: `.close()` will tear
-     * it down.
-     */
-    static spawn(opts?: SpawnRuntimeOptions & Omit<UnbrowseClientOptions, "baseUrl">): Promise<Unbrowse>;
-    /**
-     * Probe 127.0.0.1 on the requested port (default 6969). Adopts a live
-     * runtime via `connect`; spawns a new one via `spawn` if dead. The
-     * resulting client only owns the runtime if it had to spawn.
-     */
-    static local(opts?: SpawnRuntimeOptions & Omit<UnbrowseClientOptions, "baseUrl">): Promise<Unbrowse>;
-    /**
-     * Release any resources owned by this client. If the client spawned its
-     * own runtime, this kills the child process. Otherwise no-op.
-     */
-    close(): Promise<void>;
-    private reportUsage;
-    request<T>(method: string, path: string, body?: unknown, options?: RequestOptions): Promise<T>;
-    run(input: ServerRunInput, options?: RequestOptions): Promise<ServerRunResult>;
-    registry(options?: RequestOptions): Promise<ServerRegistry>;
-    selectPrimitive(goal: string, options?: RequestOptions): Promise<ServerPrimitiveSelection>;
-    callPrimitive(input: ServerPrimitiveCall, options?: RequestOptions): Promise<ServerRunResult>;
-    runWorkflow(input: ServerWorkflow, options?: RequestOptions): Promise<ServerWorkflowResult>;
-    storeCredential(id: string, credential: import("./server-types.js").ServerCredential, options?: RequestOptions): Promise<{
-        id: string;
-        origin: string;
-        storage: "remote";
-    }>;
-    deleteCredential(id: string, options?: RequestOptions): Promise<{
-        deleted: true;
+    private apiKey?;
+    private fetchImpl;
+    constructor(opts?: UnbrowseOptions);
+    private send;
+    private req;
+    private post;
+    /**
+     * Start a run by capability id or plain-language task. `idempotencyKey` makes retries safe; the route
+     * reads it as `idempotency_key` or an `Idempotency-Key` header (camelCase in the body is ignored).
+     */
+    run(request: RunRequest): Promise<RunView>;
+    inspect(runId: string): Promise<RunView>;
+    events(runId: string): Promise<{
+        events: RunView["events"];
     }>;
-    resolve(input: ResolveInput, options?: RequestOptions): Promise<ResolveResponse>;
-    execute(skill: string | ExecuteInput | ResolveResponse, input?: Omit<ExecuteInput, "skillId">, options?: RequestOptions): Promise<ExecuteResponse>;
-    getSkill(skillId: string, options?: RequestOptions): Promise<SkillManifest>;
-    login(input: LoginInput, options?: RequestOptions): Promise<LoginResponse>;
-    importAuth(input: StealAuthInput, options?: RequestOptions): Promise<StealAuthResponse>;
-    stealAuth(input: StealAuthInput, options?: RequestOptions): Promise<StealAuthResponse>;
-    search(input: SearchInput, options?: RequestOptions): Promise<SearchResponse>;
-    searchDomain(input: SearchDomainInput, options?: RequestOptions): Promise<SearchResponse>;
-    /**
-     * Semantic search across ALL indexed endpoints (flat shape).
-     *
-     * Returns one row per endpoint, ranked by semantic match against the
-     * intent string. Use this when you want to pick endpoints across many
-     * skills (vs `search()` which groups by skill).
-     *
-     * Optional `domain` scopes the search to one host's endpoints; omit for
-     * cross-marketplace search. Authenticated agents are charged the
-     * standard search fee per the existing x402 economics; anonymous
-     * callers get free rate-limited public discovery.
-     *
-     * @example
-     * ```ts
-     * const { endpoints } = await u.searchEndpoints({ intent: "trending repositories", k: 5 });
-     * for (const ep of endpoints) {
-     *   console.log(ep.score, ep.skill_id, ep.endpoint_id, ep.description);
-     * }
-     * ```
-     */
-    searchEndpoints(input: SearchEndpointsInput, options?: RequestOptions): Promise<SearchEndpointsResponse>;
-    feedback(input: FeedbackInput, options?: RequestOptions): Promise<FeedbackResponse>;
-    stats(options?: RequestOptions): Promise<StatsResponse>;
-    health(options?: RequestOptions): Promise<HealthResponse>;
-    /**
-     * Earnings/spending dashboard for the authenticated agent.
-     * Requires `apiKey` set on the client. Backend: `GET /v1/dashboard/me`.
-     */
-    dashboard(options?: RequestOptions): Promise<Dashboard>;
-    /**
-     * Public dashboard for any wallet address. Backend: `GET /v1/dashboard/wallet/:walletAddress`.
-     */
-    dashboardByWallet(walletAddress: string, options?: RequestOptions): Promise<Dashboard>;
     /**
-     * Per-transaction earnings ledger for a creator agent.
-     * Backend: `GET /v1/transactions/creator/:agentId`.
-     */
-    creatorTransactions(agentId: string, options?: RequestOptions): Promise<CreatorTransactionsResponse>;
-    /**
-     * Fund a Flex escrow on the caller's behalf. Thin wrapper around
-     * `fundEscrow` in `./flex.ts` — requires the caller to pass
-     * `signer` + `rpc` for v6.16-preview.0 (until SDK ships its own
-     * @solana/kit pipeline). For pure tx construction without sending,
-     * import `buildEscrowCreationTx` from the package root.
-     */
-    fundEscrow(params: {
-        amountUsdc: string;
-        walletAddress?: string;
-        facilitatorAddress?: string;
-        mint?: string;
-        refundTimeoutSlots?: number;
-        deadmanTimeoutSlots?: number;
-        signer?: unknown;
-        rpc?: unknown;
-    }): Promise<{
-        escrowAddress: string;
-        txSignature: string;
-    }>;
-    /**
-     * Register a session key against the caller's existing Flex escrow.
-     * Thin wrapper around `registerSessionKey` in `./flex.ts`.
-     */
-    registerSessionKey(params: {
-        sessionKeyAddress: string;
-        walletAddress?: string;
-        escrowAddress?: string;
-        expiresAtSlot?: string;
-        revocationGracePeriodSlots?: number;
-        signer?: unknown;
-        rpc?: unknown;
-    }): Promise<{
-        txSignature: string;
-    }>;
-    /**
-     * Execute a skill against a Flex-metered route. preview.0/preview.1 stub:
-     * the backend metered-execute route (`POST /v1/skills/:id/execute` with
-     * Flex-shaped 402 + usage_units settlement) ships in v6.16.0-preview.2.
-     * Callers must use `Unbrowse#execute` against fixed-price skills until
-     * then. The method signature stays for forward compat; the body refuses
-     * with a precise version-targeted error.
-     */
-    executeMetered<T = unknown>(_skillOrId: string | {
-        skill_id: string;
-    }, _input: unknown, _opts?: {
-        onUsage?: (units: number) => void;
-        wallet?: import("./flex.js").FlexWalletLike;
-    }, _options?: RequestOptions): Promise<T>;
-    /**
-     * Indexer earnings via delta-based attribution.
-     * Backend: `GET /v1/attribution/indexer/:indexerId`.
-     */
-    indexerAttribution(indexerId: string, options?: RequestOptions): Promise<AttributionLedger>;
-    /**
-     * Publish a captured skill to the marketplace.
-     * Backend: `POST /v1/skills`.
-     *
-     * SDK gap-fill (Wave 2 of rebuild-the-unbrowse-sdk-as-a-thin-http-first-ty
-     * + the parity gate from tests/cli-mcp-sdk-parity.test.ts). Mirrors the
-     * CLI `unbrowse publish` and the MCP `unbrowse_publish` tool.
-     */
-    publish(skill: PublishSkillInput, options?: RequestOptions): Promise<PublishResponse>;
-    /**
-     * Annotate an endpoint with a tip, constraint, or gotcha.
-     * Backend: `POST /v1/skills/:id/endpoints/:eid/annotate`.
-     *
-     * SDK gap-fill. Mirrors CLI `unbrowse annotate` + MCP `unbrowse_annotate`.
-     */
-    annotate(input: AnnotateInput, options?: RequestOptions): Promise<AnnotateResponse>;
-    /**
-     * Persist the agent's chosen x402 payment rail on the backend.
-     * Backend: `POST /v1/account/payment-provider` (shipped in #691).
-     *
-     * SDK gap-fill: surface the Wave 2 backend route as a typed SDK
-     * method so SDK callers can sync provider choice without rolling
-     * a raw fetch. Allowed values are the same six the route whitelists:
-     * pay_sh / lobster_cash / external_solana / privy_embedded /
-     * privy_embedded_solana / skip.
-     */
-    paymentProvider(provider: PaymentProvider, options?: RequestOptions): Promise<PaymentProviderResponse>;
+     * Answer a run's open requirements. The route reads snake_case (`requirement_id`, `expected_revision`);
+     * the documented camelCase (`requirementId`, `expectedRevision`) is converted here.
+     */
+    resume(runId: string, expectedStateRevision: number, responses: Json[]): Promise<any>;
+    /** Answer open requirements by field name — `{ origin: "SIN" }` — and return the updated run. */
+    answer(runId: string, answers: Record<string, Json>): Promise<RunView>;
+    /** Poll a run until it leaves `accepted`/`working` (or the timeout passes). */
+    wait(runId: string, opts?: {
+        timeoutMs?: number;
+    }): Promise<RunView>;
+    cancel(runId: string): Promise<any>;
+    /** Your private capabilities first, then the public registry. */
+    discover(query: string): Promise<any>;
+    capability(id: string): Promise<any>;
+    skills(): Promise<any>;
+    /** Compile HAR files or traces of a task done by hand into a one-call capability. */
+    learn(body: {
+        har?: Json;
+        traces?: Json[];
+        goal?: string;
+        title?: string;
+    }): Promise<any>;
+    learned(id?: string): Promise<any>;
+    harnessYaml(id: string): Promise<string>;
+    skillMd(id: string): Promise<string>;
+    usage(): Promise<any>;
+    me(): Promise<any>;
+    /**
+     * The password manager, for services that keep their own "save your login" page (e.g. Kata): values go in,
+     * only masked hints come back. One login per site; saving again for the same origin updates it.
+     */
+    logins: {
+        list: () => Promise<{
+            logins: LoginView[];
+        }>;
+        save: (login: {
+            origin: string;
+            label?: string;
+            username?: string;
+            email?: string;
+            password?: string;
+            totp?: string;
+        }) => Promise<{
+            login: LoginView;
+            updated: boolean;
+        }>;
+        remove: (by: {
+            origin: string;
+        } | {
+            ref: string;
+        }) => Promise<{
+            removed: number;
+        }>;
+    };
+    accounts: {
+        /** Store a password in the vault; returns a `vault://` ref. */
+        connect: (a: {
+            origin: string;
+            username?: string;
+            password?: string;
+            label?: string;
+        }) => Promise<any>;
+        /** Generate and vault a password for a new account. */
+        register: (a: {
+            origin: string;
+            username: string;
+            label?: string;
+        }) => Promise<any>;
+    };
+    /** Vault refs and audit, never secrets. */
+    vault(): Promise<any>;
+    sites(query?: string): Promise<any>;
+    site(host: string): Promise<any>;
+    openapi(host: string): Promise<any>;
+    /** Run one site tool (metered like a run). */
+    callTool(host: string, tool: string, input?: Record<string, Json>): Promise<any>;
+    /** One site as its own MCP server: its compiled tools, a plain-words task, and the recorded browser on that site. */
+    siteMcpUrl(host: string): string;
 }
-//# sourceMappingURL=client.d.ts.map
+export declare function normalizeHost(site: string): string;
+/** A saved login as anyone but the vault sees it: never a value. */
+export type LoginView = {
+    ref: string;
+    origin: string;
+    label?: string;
+    hints: {
+        username?: string;
+        email?: string;
+    };
+    fields: string[];
+    createdAt: number;
+    rotatedAt?: number;
+};

package/dist/index.d.ts

@@ -1,11 +1,4 @@
-export { Unbrowse } from "./client.js";
-export type { ServerRunInput, ServerRunResult, ServerCredential, ServerSessionCookie, ServerPrimitive, ServerRegistry, ServerPrimitiveCall, ServerPrimitiveSelection, ServerWorkflowNode, ServerWorkflow, ServerWorkflowResult } from "./server-types.js";
-export { PaymentRequiredError, RuntimeUnavailableError, SponsorExhaustedError, UnbrowseApiError, } from "./errors.js";
-export { locateUnbrowseBinary, probeUnbrowseRuntime, spawnUnbrowseRuntime, } from "./runtime.js";
-export type { RuntimeHandle, SpawnRuntimeOptions } from "./runtime.js";
-export { payAndRetry } from "./x402.js";
-export type { WalletLike, X402PaymentPayload, X402PaymentRequirement, } from "./x402.js";
-export { buildEscrowCreationTx, buildFlexAuthorization, buildSessionKeyRegistrationTx, fundEscrow, payAndRetryFlex, registerSessionKey, setupDelegation, USDC_MINT_DEVNET, USDC_MINT_MAINNET, } from "./flex.js";
-export type { BuiltFlexTx, DelegationClientLike, DelegationSessionKeyResponse, FlexAuthorization, FlexFundEscrowParams, FlexRegisterSessionKeyParams, FlexWalletLike, SetupDelegationParams, SetupDelegationResult, TransactionSignerOpaque, } from "./flex.js";
-export type { AttributionLedger, AvailableEndpoint, CreatorTransaction, CreatorTransactionsResponse, Dashboard, DashboardContributions, DashboardEarnings, DashboardSpending, EndpointAnnotation, EndpointConstraint, EndpointDescriptor, ExecuteInput, ExecuteResponse, ExecutionTrace, FeedbackInput, FeedbackResponse, HealthResponse, LoginInput, LoginResponse, OrchestrationTiming, ProjectionOptions, RequestOptions, ResolveInput, ResolveResponse, ResponseSchema, SearchDomainInput, SearchHit, SearchInput, SearchResponse, SearchEndpointsInput, SearchEndpointsResponse, EndpointSearchHit, SkillManifest, StatsResponse, StealAuthInput, StealAuthResponse, UnbrowseClientOptions, WalletInfo, } from "./contracts.js";
-//# sourceMappingURL=index.d.ts.map
+export { DEFAULT_BASE_URL, Unbrowse, UnbrowseError, 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

@@ -1,6 +1,186 @@
-export { Unbrowse } from "./client.js";
-export { PaymentRequiredError, RuntimeUnavailableError, SponsorExhaustedError, UnbrowseApiError, } from "./errors.js";
-export { locateUnbrowseBinary, probeUnbrowseRuntime, spawnUnbrowseRuntime, } from "./runtime.js";
-export { payAndRetry } from "./x402.js";
-export { buildEscrowCreationTx, buildFlexAuthorization, buildSessionKeyRegistrationTx, fundEscrow, payAndRetryFlex, registerSessionKey, setupDelegation, USDC_MINT_DEVNET, USDC_MINT_MAINNET, } from "./flex.js";
-//# sourceMappingURL=index.js.map
+// src/client.ts
+var DEFAULT_BASE_URL = "https://unbrowse.ai/api/v1";
+
+class UnbrowseError extends Error {
+  status;
+  code;
+  body;
+  constructor(message, status, code, body) {
+    super(message);
+    this.status = status;
+    this.code = code;
+    this.body = body;
+    this.name = "UnbrowseError";
+  }
+}
+var env = (name) => (typeof process !== "undefined" ? process.env?.[name] : undefined) || undefined;
+function apiBase(url) {
+  const u = url.replace(/\/+$/, "");
+  return /\/api\/v1$/.test(u) ? u : `${u}/api/v1`;
+}
+
+class Unbrowse {
+  baseUrl;
+  apiKey;
+  fetchImpl;
+  constructor(opts = {}) {
+    this.baseUrl = apiBase(opts.baseUrl ?? env("UNBROWSE_BASE_URL") ?? DEFAULT_BASE_URL);
+    this.apiKey = opts.apiKey ?? env("UNBROWSE_API_KEY");
+    this.fetchImpl = opts.fetch ?? ((...a) => globalThis.fetch(...a));
+  }
+  async send(path, init) {
+    const res = await this.fetchImpl(`${this.baseUrl}${path}`, {
+      ...init,
+      headers: {
+        ...this.apiKey ? { authorization: `Bearer ${this.apiKey}` } : {},
+        "content-type": "application/json",
+        ...init?.headers ?? {}
+      }
+    });
+    if (!res.ok) {
+      const body = await res.json().catch(() => ({}));
+      const err = typeof body.error === "object" ? body.error : undefined;
+      throw new UnbrowseError(err?.message ?? body.error_description ?? res.statusText, res.status, err?.code ?? (typeof body.error === "string" ? body.error : "http_error"), body);
+    }
+    return res;
+  }
+  async req(path, init) {
+    return (await this.send(path, init)).json();
+  }
+  post(path, body) {
+    return this.req(path, { method: "POST", body: JSON.stringify(body) });
+  }
+  run(request) {
+    const { idempotencyKey, ...rest } = request;
+    return this.req("/runs", {
+      method: "POST",
+      body: JSON.stringify(idempotencyKey ? { ...rest, idempotency_key: idempotencyKey } : rest),
+      ...idempotencyKey ? { headers: { "idempotency-key": idempotencyKey } } : {}
+    });
+  }
+  inspect(runId) {
+    return this.req(`/runs/${runId}`);
+  }
+  events(runId) {
+    return this.req(`/runs/${runId}/events`);
+  }
+  resume(runId, expectedStateRevision, responses) {
+    const wire = responses.map((r) => {
+      const x = r ?? {};
+      return {
+        requirement_id: x.requirement_id ?? x.requirementId,
+        expected_revision: x.expected_revision ?? x.expectedRevision,
+        action: x.action ?? "accept",
+        ...x.values !== undefined ? { values: x.values } : {}
+      };
+    });
+    return this.post(`/runs/${runId}/responses`, { expected_state_revision: expectedStateRevision, responses: wire });
+  }
+  async answer(runId, answers) {
+    const view = await this.inspect(runId);
+    const open = view.requirements.filter((r) => r.state === "open");
+    const responses = Object.entries(answers).map(([field, value]) => {
+      const req = open.find((r) => r.affectedAction === field || r.id === field);
+      if (!req)
+        throw new UnbrowseError(`${field} is not an open requirement. Open: ${open.map((r) => r.affectedAction).join(", ") || "none"}`, 422, "invalid_answer");
+      return { requirementId: req.id, expectedRevision: req.revision, action: "accept", values: { [req.affectedAction]: value } };
+    });
+    await this.resume(runId, view.stateRevision, responses);
+    return this.inspect(runId);
+  }
+  async wait(runId, opts = {}) {
+    const deadline = Date.now() + (opts.timeoutMs ?? 600000);
+    let view = await this.inspect(runId);
+    for (let delay = 500;(view.status === "accepted" || view.status === "working") && Date.now() < deadline; delay = Math.min(delay * 2, 5000)) {
+      await new Promise((r) => setTimeout(r, delay));
+      view = await this.inspect(runId);
+    }
+    return view;
+  }
+  cancel(runId) {
+    return this.req(`/runs/${runId}/cancel`, { method: "POST" });
+  }
+  discover(query) {
+    return this.post("/capabilities/search", { query });
+  }
+  capability(id) {
+    return this.req(`/capabilities/${encodeURIComponent(id)}`);
+  }
+  skills() {
+    return this.req("/skills");
+  }
+  learn(body) {
+    return this.post("/learn", body);
+  }
+  learned(id) {
+    return this.req(id ? `/learned/${encodeURIComponent(id)}` : "/learned");
+  }
+  async harnessYaml(id) {
+    return (await this.send(`/learned/${encodeURIComponent(id)}/harness.yaml`)).text();
+  }
+  async skillMd(id) {
+    return (await this.send(`/learned/${encodeURIComponent(id)}/skill.md`)).text();
+  }
+  usage() {
+    return this.req("/usage");
+  }
+  me() {
+    return this.req("/me");
+  }
+  logins = {
+    list: () => this.req("/logins"),
+    save: (login) => this.post("/logins", login),
+    remove: (by) => this.post("/logins/remove", by)
+  };
+  accounts = {
+    connect: (a) => this.post("/accounts/connections", a),
+    register: (a) => this.post("/accounts/register", a)
+  };
+  vault() {
+    return this.req("/vault");
+  }
+  sites(query = "") {
+    return this.req(`/sites${query ? `?q=${encodeURIComponent(query)}` : ""}`);
+  }
+  site(host) {
+    return this.req(`/sites/${normalizeHost(host)}`);
+  }
+  openapi(host) {
+    return this.req(`/sites/${normalizeHost(host)}/openapi.json`);
+  }
+  callTool(host, tool, input = {}) {
+    return this.post(`/sites/${normalizeHost(host)}/call/${encodeURIComponent(tool)}`, input);
+  }
+  siteMcpUrl(host) {
+    return `${this.baseUrl}/sites/${normalizeHost(host)}/mcp`;
+  }
+}
+function normalizeHost(site) {
+  let host = site.trim().toLowerCase();
+  if (/^[a-z]+:\/\//.test(host))
+    host = new URL(host).hostname;
+  return host.replace(/\/.*$/, "").replace(/^www\./, "");
+}
+// src/mcp-install.ts
+function cursorInstallLink(url) {
+  return `cursor://anysphere.cursor-deeplink/mcp/install?name=unbrowse&config=${encodeURIComponent(btoa(JSON.stringify({ url })))}`;
+}
+function vscodeInstallLink(url, insiders = false) {
+  return `${insiders ? "vscode-insiders" : "vscode"}:mcp/install?${encodeURIComponent(JSON.stringify({ name: "unbrowse", type: "http", url }))}`;
+}
+function mcpCommands(url) {
+  return {
+    claudeCode: `claude mcp add --transport http unbrowse ${url}`,
+    codex: `codex mcp add unbrowse --url ${url} && codex mcp login unbrowse`,
+    json: JSON.stringify({ mcpServers: { unbrowse: { url } } }, null, 2)
+  };
+}
+export {
+  DEFAULT_BASE_URL,
+  Unbrowse,
+  UnbrowseError,
+  cursorInstallLink,
+  mcpCommands,
+  normalizeHost,
+  vscodeInstallLink
+};