@unbrowse/sdk 6.17.0-preview.6

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Unbrowse AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,156 @@
+# @unbrowse/sdk
+
+TypeScript SDK for Unbrowse — the local agent browser that turns any website into reusable, payable API routes.
+
+The SDK auto-spawns the `unbrowse` binary if it isn't already running, so a single `await Unbrowse.local()` is all you need to go from `npm install` to your first resolve.
+
+Current version: **6.16.0-preview.0**.
+
+> The SDK (this package) is MIT-licensed. The `unbrowse` runtime binary it talks to is distributed via npm. See [`OPEN-SOURCE-NOTICE.md`](../../docs/OPEN-SOURCE-NOTICE.md).
+
+## Install
+
+```bash
+npm install @unbrowse/sdk
+```
+
+The SDK ships the spawn path lazily — `Unbrowse.connect()` callers never pull `child_process`, so it stays tree-shakeable in serverless and edge bundles.
+
+## Quick start
+
+```ts
+import { Unbrowse } from "@unbrowse/sdk";
+
+const u = await Unbrowse.local();
+const r = await u.resolve({ intent: "list tomorrow's events", url: "https://calendar.google.com" });
+console.log(r.result);
+```
+
+That's it — `Unbrowse.local()` probes `127.0.0.1:6969`, connects if a daemon is alive, and spawns the `unbrowse` CLI as a child process if not. The spawned daemon's lifecycle is owned by your process; it shuts down cleanly on exit.
+
+## Three factories, three lifecycles
+
+```ts
+// 1. Common case — probe then spawn. The right answer 95% of the time.
+const u = await Unbrowse.local();
+
+// 2. External daemon already running (Docker, sidecar, dev server).
+const u = await Unbrowse.connect("http://localhost:6969");
+
+// 3. Always spawn fresh — owned lifecycle, useful for tests and isolated workers.
+const u = await Unbrowse.spawn({ port: 7969 });
+```
+
+All three return the same `Unbrowse` client interface. Pass `{ apiKey }` to any factory to override the auto-generated marketplace key.
+
+## Resolve and execute
+
+```ts
+const resolved = await u.resolve({
+  intent: "get feed posts",
+  url: "https://news.ycombinator.com",
+});
+
+// Re-run later with explicit projection
+const rerun = await u.execute(resolved, { projection: { raw: true } });
+
+// Or by skill id, with params
+const quote = await u.execute("skill_123", { params: { symbol: "NVDA" } });
+```
+
+## Payments
+
+Unbrowse routes monetize on use via [x402](https://www.x402.org). Every paid execute (priced skills, `search`, `resolve` over a priced shortlist) is gated by a `402 Payment Required` flow. The SDK turns that into a typed error you can catch and retry. v6.16 settles on [Faremeter Flex](https://docs.faremeter.xyz/flex/overview) — your wallet signs an off-chain authorization with a session key, the facilitator settles on-chain in batches, and splits to contributors land atomically.
+
+```ts
+import { Unbrowse, PaymentRequiredError, payAndRetryFlex } from "@unbrowse/sdk";
+
+try {
+  await u.execute("skill_premium_123", { params: { ticker: "NVDA" } });
+} catch (err) {
+  if (err instanceof PaymentRequiredError) {
+    await payAndRetryFlex(err, wallet, (header) =>
+      u.execute(
+        "skill_premium_123",
+        { params: { ticker: "NVDA" } },
+        { headers: { "X-PAYMENT": header } },
+      ),
+    ); // signs the Flex authorization, retries with proof attached
+  }
+}
+```
+
+`PaymentRequiredError` is thrown at the HTTP-parser layer and carries `accepts[]` — the canonical x402 terms array. `payAndRetryFlex(error, wallet, retry)` is a free function exported from `@unbrowse/sdk`; it picks `accepts[0]`, has your session key sign it, and calls your `retry(paymentHeader)` to replay the original request with `X-PAYMENT` attached.
+
+For metered routes there's a higher-level helper that handles the catch + retry for you:
+
+```ts
+const result = await u.executeMetered<{ data: string; usage_units: number }>(
+  "skill_id",
+  input,
+  { wallet, onUsage: (units) => console.log("consumed", units, "units") },
+);
+```
+
+### Sponsor mode — first calls covered by the platform
+
+Brand-new agents get a daily allowance of platform-sponsored execute calls before they need to fund a wallet, so creators start earning USDC the moment their captured routes are reused. Sponsored responses include `X-Sponsored: <ledger_id>`.
+
+When the daily allowance is exhausted you get `SponsorExhaustedError` — pair a wallet and switch to `payAndRetryFlex`. Opt out per-request by passing `{ headers: { "X-No-Sponsor": "1" } }` if you'd rather pay yourself from the first call.
+
+Full payment docs and worked examples: [`docs/payments/`](./docs/payments/). Wallet + escrow + session-key setup: [`../../docs/wallets.md`](../../docs/wallets.md). Upgrading from v6.15's `exact`-scheme integration: [`../../docs/x402-flex-migration.md`](../../docs/x402-flex-migration.md).
+
+## Auth
+
+```ts
+// Interactive login — opens a real browser window for first-time auth.
+await u.login({ url: "https://calendar.google.com" });
+
+// Or import cookies from your local browser storage.
+await u.importAuth({ url: "https://x.com/home", browser: "auto" });
+```
+
+## Search
+
+```ts
+const global = await u.search({ intent: "get stock prices", k: 5 });
+
+const domain = await u.searchDomain({
+  intent: "find trending repositories",
+  domain: "github.com",
+  k: 3,
+});
+```
+
+## Error handling
+
+```ts
+import { Unbrowse, UnbrowseApiError } from "@unbrowse/sdk";
+
+try {
+  await u.resolve({ intent: "get inbox", url: "https://mail.google.com" });
+} catch (err) {
+  if (err instanceof UnbrowseApiError) {
+    console.error(err.status, err.path, err.data);
+  }
+  throw err;
+}
+```
+
+`UnbrowseApiError` is the generic wrapper. `PaymentRequiredError` and `SponsorExhaustedError` are payment-specific subclasses; both expose `accepts[]` so you can introspect what the gate wants.
+
+## Notes
+
+- Default `baseUrl` is `http://localhost:6969`. `Unbrowse.local()` picks this up automatically.
+- Default `apiKey` reads from `UNBROWSE_API_KEY` when present.
+- `resolve({ url })` maps the URL into both `params.url` and `context.url`, matching the CLI path.
+- Response types are strongest on inputs and core trace/skill metadata, lighter on payload bodies, because endpoint payload shape varies by site.
+
+## More
+
+- Complete docs: [`docs/`](./docs/)
+- Use case recipes: [`docs/examples/`](./docs/examples/)
+- API reference: [`docs/api-reference/`](./docs/api-reference/)
+- Payment surface: [`docs/payments/`](./docs/payments/)
+
+_Audited Day 6 (Dominion): 2026-05-14_

package/dist/client.d.ts

@@ -0,0 +1,120 @@
+import type { AttributionLedger, AvailableEndpoint, CreatorTransactionsResponse, Dashboard, ExecuteInput, ExecuteResponse, FeedbackInput, FeedbackResponse, HealthResponse, LoginInput, LoginResponse, RequestOptions, ResolveInput, ResolveResponse, SearchDomainInput, SearchInput, SearchResponse, SkillManifest, StatsResponse, StealAuthInput, StealAuthResponse, UnbrowseClientOptions } from "./contracts.js";
+import { type SpawnRuntimeOptions } from "./runtime.js";
+export declare class Unbrowse {
+    readonly baseUrl: string;
+    readonly apiKey?: string;
+    readonly clientId?: string;
+    private readonly defaultHeaders?;
+    private readonly fetchImpl;
+    private readonly timeoutMs?;
+    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>;
+    request<T>(method: string, path: string, body?: unknown, options?: RequestOptions): Promise<T>;
+    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>;
+    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>;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

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