@ledewire/browser 0.6.1 → 0.8.0

package/dist/index.d.ts

@@ -12,7 +12,7 @@
  *   const lw = Ledewire.init({ apiKey: 'your_api_key' })
  *   const state = await lw.checkout.state('content-id')
  *   // state.checkout_state.next_required_action:
- *   //   'authenticate' | 'fund_wallet' | 'purchase' | 'view_content'
+ *   //   'authenticate' | 'fund_wallet' | 'purchase'
  * </script>
  * ```
  *
@@ -44,12 +44,16 @@ export declare type AuthenticationResponse = components['schemas']['Authenticati
  * or when a token refresh fails and re-authentication is required.
  */
 export declare class AuthError extends LedewireError {
-    constructor(message: string, code?: number);
+    static readonly brand: string;
+    constructor(message: string, code?: number, type?: ErrorTypeValue, details?: Record<string, unknown>);
 }
 
 /** Request body for API key authentication (seller). */
 declare type AuthLoginApiKeyRequest = components['schemas']['AuthLoginApiKeyRequest'];
 
+/** Request body for authenticating as a buyer using a named API key + secret. */
+declare type AuthLoginBuyerApiKeyRequest = components['schemas']['AuthLoginBuyerApiKeyRequest'];
+
 /** Request body for buyer email/password login. */
 declare type AuthLoginEmailRequest = components['schemas']['AuthLoginEmailRequest'];
 
@@ -130,6 +134,26 @@ declare class BrowserAuthNamespace {
      * @returns The authentication token response.
      */
     loginWithGoogle(body: AuthLoginOAuthRequest): Promise<AuthenticationResponse>;
+    /**
+     * Log in using a buyer API key and secret.
+     * Returns a buyer-scoped JWT, stored automatically after successful authentication.
+     *
+     * Primarily useful when building buyer-facing dashboards where the user
+     * has created a named API key and wishes to authenticate with it programmatically,
+     * or for agent workflows running inside a browser context.
+     *
+     * @param body - The buyer API key and secret.
+     * @returns The authentication token response.
+     *
+     * @example
+     * ```ts
+     * await lw.auth.loginWithBuyerApiKey({
+     *   key: 'bktst_abc123',
+     *   secret: 'deadbeef...',
+     * })
+     * ```
+     */
+    loginWithBuyerApiKey(body: AuthLoginBuyerApiKeyRequest): Promise<AuthenticationResponse>;
     /**
      * Request a password reset code to be sent to the buyer's email address.
      *
@@ -192,6 +216,8 @@ declare class BrowserClient {
     readonly content: BrowserContentNamespace;
     /** Seller operations: API key login, content list/search/get */
     readonly seller: BrowserSellerNamespace;
+    /** Authenticated buyer account: API key management */
+    readonly user: UserNamespace;
     /* Excluded from this release type: __constructor */
 }
 
@@ -266,8 +292,10 @@ declare class BrowserConfigNamespace {
  * @example
  * ```ts
  * const result = await lw.content.getWithAccess('content-id')
- * if (result.access_info.next_required_action === 'view_content') {
- *   renderMarkdown(result.content_body ?? '')
+ * if (result.access_info.has_purchased) {
+ *   // Note: single-use — a past purchase does not imply access. Buy again
+ *   // via lw.purchases.create() to receive the content; the delivery comes
+ *   // back directly in that response, not from this endpoint.
  * }
  * ```
  */
@@ -286,8 +314,10 @@ declare class BrowserContentNamespace {
      * @example
      * ```ts
      * const result = await lw.content.getWithAccess('article-123')
-     * if (result.access_info.next_required_action === 'view_content') {
-     *   renderMarkdown(result.content_body ?? '')
+     * if (result.access_info.next_required_action === 'purchase') {
+     *   // Buy (or re-buy) via lw.purchases.create() — the response carries
+     *   // content_body / content_uri directly. has_purchased means only
+     *   // "has ever bought" and does not by itself grant access.
      * }
      * ```
      */
@@ -297,6 +327,11 @@ declare class BrowserContentNamespace {
 /**
  * Buyer purchases namespace — create and retrieve content purchases.
  *
+ * **Single-use purchase model:** a completed purchase does not imply
+ * standing access. `has_purchased` on other endpoints means only "has ever
+ * bought" — it is not a re-access grant. Buying again is how the buyer
+ * receives the content a second time; see {@link BrowserPurchasesNamespace.create}.
+ *
  * Obtain via `lw.purchases` — do not construct directly.
  *
  * @example
@@ -309,10 +344,50 @@ declare class BrowserPurchasesNamespace {
     protected readonly http: HttpClient;
     constructor(http: HttpClient);
     /**
-     * Completes a content purchase using the buyer's wallet balance.
+     * Completes a content purchase using the buyer's wallet balance and
+     * delivers the content in the same response.
+     *
+     * **This response is the only place the delivered content ever arrives.**
+     * For a deliverable LedeWire holds, `content_body` carries the full body as
+     * plain UTF-8 text — it is never base64-encoded on the wire, so no
+     * `atob()` or decoding step is needed. For a deliverable hosted elsewhere,
+     * `content_uri` carries its URL instead. Neither field is present on
+     * {@link BrowserPurchasesNamespace.get} or {@link BrowserPurchasesNamespace.list}
+     * — there is no route that serves the same content a second time — so
+     * persist `content_body` / `content_uri` immediately if you need it later.
+     * A past purchase does not grant re-access: buying the same content again
+     * is a new charge that delivers it again.
      *
      * @param body - The content ID and expected price in cents.
-     * @returns The completed purchase record.
+     * @returns The completed purchase record, including the delivered content.
+     * @throws {SpendCapReachedError} `402` — the buyer's daily spend cap has
+     *   been reached. There is no funding URL for this refusal: adding money
+     *   to the wallet does not clear it. It clears only when the spend window
+     *   rolls over at `resetsAt`, or when the cap is raised via
+     *   `lw.user.spendCap.update()`.
+     * @throws {NotFoundError} `404` — the content does not exist, or its
+     *   visibility is `unlisted` (non-public) and this buyer has no standing
+     *   grant to see it. Non-public content is not purchasable through this
+     *   endpoint.
+     *
+     * @example
+     * ```ts
+     * const purchase = await lw.purchases.create({ content_id: 'content-id' })
+     * await saveDeliveredContent(purchase) // persist now — one-time delivery
+     *
+     * if (purchase.content_body && purchase.content.content_type === 'markdown') {
+     *   renderMarkdown(purchase.content_body)
+     * } else if (purchase.content_body && purchase.content.content_type === 'html') {
+     *   // Inline HTML is seller-supplied — sanitise before inserting it.
+     *   container.innerHTML = DOMPurify.sanitize(purchase.content_body)
+     * } else if (purchase.content_uri) {
+     *   // Seller-supplied URI — check the scheme before navigating to it.
+     *   const uri = new URL(purchase.content_uri)
+     *   if (['https:', 'http:'].includes(uri.protocol)) {
+     *     window.location.href = purchase.content_uri
+     *   }
+     * }
+     * ```
      */
     create(body: PurchaseCreateRequest): Promise<PurchaseResponse>;
     /**
@@ -457,12 +532,33 @@ declare class BrowserWalletNamespace {
     /**
      * Returns the authenticated buyer's current wallet balance.
      *
-     * @returns The current wallet balance in cents.
+     * `balance_cents` and `spendable_cents` are always the same number —
+     * `balance_cents` has always meant "what you can spend," and money committed to
+     * a bulk acquisition is a hold, which moves it out of the wallet rather than
+     * annotating it. `held_cents` is the total currently committed to active bulk
+     * acquisitions and not yet spent or released, and `holds` lists one entry per
+     * such acquisition (`acquisition_id`, `held_cents`, `authorized_at`) so a buyer
+     * mid-acquisition can see why their balance is lower than their purchase
+     * history explains.
+     *
+     * @returns The current wallet balance in cents, including held funds detail.
      */
     balance(): Promise<WalletBalanceResponse>;
     /**
      * Returns the authenticated buyer's wallet transaction history, newest first.
      *
+     * `bulk_acquisition` and `bulk_hold` are each a single entry for a whole bulk
+     * acquisition — its per-work purchases are deliberately not listed here,
+     * because one acquisition can hold tens of thousands of them and they describe
+     * one decision. A `bulk_hold` entry is an acquisition still holding funds (money
+     * left the wallet but has not been spent); it becomes a `bulk_acquisition` entry
+     * for the amount actually captured once the acquisition ends, and an
+     * acquisition never produces both. Note that a bulk acquisition's per-work
+     * purchases each carry a display `price_cents` that is **not summable** — bulk
+     * prices at micro precision and rounds to cents once, on the acquisition total,
+     * so `amount_cents` on the `bulk_acquisition` / `bulk_hold` entry is the figure
+     * to read.
+     *
      * @returns A list of completed wallet transaction entries.
      */
     transactions(): Promise<WalletTransactionItem[]>;
@@ -491,7 +587,12 @@ declare class BrowserWalletNamespace {
  * ```ts
  * const state = await lw.checkout.state('content-id')
  * // state.checkout_state.next_required_action:
- * // 'authenticate' | 'fund_wallet' | 'purchase' | 'view_content'
+ * // 'authenticate' | 'fund_wallet' | 'purchase'
+ * //
+ * // Single-use model: a completed purchase does not imply access, so
+ * // 'purchase' can still be the next action even when has_purchased is
+ * // true. Buying delivers the content directly in the POST /v1/purchases
+ * // response — there is no separate "view content" step.
  * ```
  */
 declare class CheckoutNamespace {
@@ -512,11 +613,18 @@ declare class CheckoutNamespace {
 }
 
 /**
- * Next step in a content checkout flow.
- * Extends `NextRequiredAction` with the terminal `view_content` state
- * (returned once the buyer has purchased and can view the content).
+ * Next step in a content checkout flow. Consumer-facing alias for
+ * `CheckoutStateResponse['checkout_state']['next_required_action']`.
+ *
+ * **Single-use purchase model:** there is no terminal "you have access" state.
+ * A completed purchase does not imply access — `has_purchased` means only "has ever
+ * bought" — so `next_required_action` can still read `'purchase'` for content the
+ * buyer already bought once. Buying again is how the buyer receives the content:
+ * the delivery (`content_body` / `content_uri`) is returned directly in the
+ * response to `POST /v1/purchases`, and nowhere else — not on `GET`/list, and not
+ * via a since-withdrawn `'view_content'` state.
  */
-export declare type CheckoutNextAction = 'authenticate' | 'fund_wallet' | 'purchase' | 'view_content';
+export declare type CheckoutNextAction = 'authenticate' | 'fund_wallet' | 'purchase';
 
 /**
  * Checkout state machine result for a specific content item, as returned by
@@ -548,7 +656,7 @@ declare interface components {
             has_sufficient_funds: boolean;
             wallet_balance_cents: number;
             /** @enum {string} */
-            next_required_action: 'authenticate' | 'fund_wallet' | 'purchase' | 'none';
+            next_required_action: 'authenticate' | 'fund_wallet' | 'purchase';
         };
         AuthenticationResponse: {
             /** @enum {string} */
@@ -621,6 +729,11 @@ declare interface components {
             error: {
                 code: number;
                 message: string;
+                /**
+                 * @description Machine-readable reason, present on refusals that carry one. Branch on this rather than on `message`, which is prose and may be reworded. `retrieval_failed` is transient and worth retrying; `not_licensable` means report it undelivered; `price_drifted` means re-quote; `client_error` is ours to fix and must never be retried unchanged; `insufficient_funds` is cleared by funding the wallet and `daily_spend_cap_reached` deliberately is not.
+                 * @enum {string}
+                 */
+                type?: 'retrieval_failed' | 'not_licensable' | 'price_drifted' | 'client_error' | 'insufficient_funds' | 'daily_spend_cap_reached';
             };
         };
         AuthSignupRequest: {
@@ -646,6 +759,430 @@ declare interface components {
             key: string;
             secret?: string;
         };
+        AuthLoginBuyerApiKeyRequest: {
+            /** @description Structured buyer API key (e.g. bktst_abc123) */
+            key: string;
+            /** @description 64-char hex secret, shown once at creation */
+            secret: string;
+        };
+        UserApiKey: {
+            /** Format: uuid */
+            id: string;
+            name: string;
+            /** @description Structured public identifier (e.g. bktst_abc123) */
+            key: string;
+            /** Format: date-time */
+            last_used_at?: string | null;
+            /** @description Maximum cumulative spend in cents. null = no limit. */
+            spending_limit_cents?: number | null;
+            /** Format: date-time */
+            created_at: string;
+        };
+        UserApiKeyCreateRequest: {
+            /** @description Human-readable label for the key */
+            name: string;
+            /** @description Optional spend ceiling in cents */
+            spending_limit_cents?: number | null;
+        };
+        /** @description Returned once only at creation. The secret is not stored and cannot be retrieved again. */
+        UserApiKeyCreateResponse: {
+            /** Format: uuid */
+            id: string;
+            /** @description Structured public identifier (e.g. bktst_abc123) */
+            key: string;
+            /** @description 64-char hex authentication secret. Store immediately — shown once only. */
+            secret: string;
+        };
+        /** @description The authenticated buyer's daily spend cap, read against the current spend window. The cap governs every wallet debit the buyer makes — MCP, REST, or the web payment gate — and spend is derived from completed purchases, so a refund returns allowance. cap_cents, spent_cents, remaining_cents and resets_at are spelled exactly as they are in DailySpendCapReachedError, so a refusal and this resource describe the same numbers. */
+        UserSpendCap: {
+            /** @description The daily spend cap in cents. null means uncapped. */
+            cap_cents: number | null;
+            /** @description IANA timezone whose calendar day bounds the spend window. Defaults to UTC. Reports the zone actually used, so an unrecognised stored value reads back as UTC. */
+            spend_window_timezone: string;
+            /** @description Total spent so far in the current spend window, summed over completed purchases by any path. */
+            spent_cents: number;
+            /** @description Cap minus spend so far, floored at zero. null when the buyer is uncapped — there is no ceiling to subtract from. Zero after the cap is lowered below spend already made. */
+            remaining_cents: number | null;
+            /**
+             * Format: date-time
+             * @description The instant the current spend window rolls, in UTC.
+             */
+            resets_at: string;
+            /** @description Whether this buyer's bulk acquisitions are exempt from the cap. When true, spent_cents and remaining_cents describe ordinary spend only — an authorized bulk acquisition does not consume them — so a client presenting remaining_cents must say which number it is. */
+            bulk_exempt: boolean;
+        };
+        /** @description Sets the buyer's cap. The field is required and nullable: null is how a buyer becomes uncapped, and an omitted field is treated as a client error rather than as a request to be uncapped. A cap below spend already made in the current window is accepted — it simply leaves remaining_cents at zero until the window rolls. Zero is a valid cap and refuses every priced purchase. */
+        UserSpendCapUpdateRequest: {
+            /** @description New cap in whole cents, or null to remove the cap. Negative and fractional values are rejected with 422. */
+            daily_spend_limit_cents: number | null;
+        };
+        McpApiKeyCreateRequest: {
+            /** @description Human-readable name for the key */
+            label: string;
+            /** @description Grants access to search and read-only MCP tools. Defaults to true. */
+            can_search?: boolean;
+            /** @description Grants access to payment submission via MCP. Defaults to false. */
+            can_purchase?: boolean;
+            /**
+             * Format: uuid
+             * @description Scopes the key to a specific store. User must be an owner or author of that store.
+             */
+            store_id?: string | null;
+            /** @description Grants access to seller content management tools. Defaults to false. */
+            can_manage_content?: boolean;
+            /** @description Grants access to seller analytics tools. Defaults to false. */
+            can_read_analytics?: boolean;
+        };
+        /** @description Returned once only at creation. The secret cannot be retrieved again. */
+        McpApiKeyCreateResponse: {
+            /** Format: uuid */
+            id: string;
+            /** @description Public identifier used to look up the key */
+            key: string;
+            /** @description Authentication secret. Store immediately — shown once only. */
+            secret: string;
+            label: string;
+            can_search: boolean;
+            can_purchase: boolean;
+            /** Format: uuid */
+            store_id?: string | null;
+            can_manage_content: boolean;
+            can_read_analytics: boolean;
+        };
+        McpApiKey: {
+            /** Format: uuid */
+            id: string;
+            label: string;
+            key: string;
+            can_search: boolean;
+            can_purchase: boolean;
+            /** Format: uuid */
+            store_id?: string | null;
+            can_manage_content: boolean;
+            can_read_analytics: boolean;
+            /** Format: date-time */
+            last_used_at?: string | null;
+            /** Format: date-time */
+            created_at: string;
+        };
+        McpContentSearchResult: {
+            /** Format: uuid */
+            id: string;
+            title: string;
+            /** @description Plain UTF-8 text preview. Never base64. */
+            teaser: string;
+            price_cents: number;
+            /** @enum {string} */
+            content_type: 'markdown' | 'html' | 'pdf' | 'image' | 'video' | 'external_ref' | 'brokered';
+            /** Format: uuid */
+            store_id: string;
+            store_name: string;
+            tags: string[];
+            /** @description Canonical article URL. Populated for Tollbit results; null for Ledewire items unless resource_url is set. */
+            url?: string | null;
+            /** @description Academic author display names. Null for non-academic content or unknown values. */
+            authors: string[] | null;
+            /** @description Academic abstract text. Null for non-academic content or when unavailable. */
+            abstract: string | null;
+            /** @description DOI URL for academic works. Null for non-academic content or unknown values. */
+            doi: string | null;
+            /** @description Academic publication date. Null for non-academic content or unknown values. */
+            publication_date: string | null;
+            /** @description Academic citation count from source metadata. Null for non-academic content or unknown values. */
+            citation_count: number | null;
+        };
+        /** @description Content returned to a store team member (owner or author) accessing their own content without a purchase. */
+        McpSellerContent: components['schemas']['McpContentSearchResult'] & {
+            /** @description Article body. Present when content_type is `markdown` or inline `html`. */
+            content_body?: string | null;
+            /** @description External content URI. Present when content_type is `external_ref`, `pdf`, `image`, `video`, or remote `html`. */
+            content_uri?: string | null;
+        };
+        McpFullContent: components['schemas']['McpContentSearchResult'] & {
+            /** @description Article body. Present when content_type is `markdown` or inline `html`. */
+            content_body?: string | null;
+            /** @description External content URI. Present when content_type is `external_ref`, `pdf`, `image`, `video`, or remote `html`. */
+            content_uri?: string | null;
+            /** Format: date-time */
+            purchased_at: string;
+            /** @description The licence the broker granted for this work, as returned on the retrieval — not the one we requested. Null when no grant was recorded: every non-brokered purchase, and brokered purchases made before the grant was captured. Null means "not recorded", never "no rights granted". */
+            license?: {
+                /**
+                 * @description The broker's licence type, e.g. `ON_DEMAND_LICENSE` or `ON_DEMAND_FULL_USE_LICENSE`. Which one is minted depends on the rates the property publishes, so it varies per work.
+                 * @example ON_DEMAND_LICENSE
+                 */
+                type: string;
+                /**
+                 * @description The rights granted. `ON_DEMAND_LICENSE` carries `PARTIAL_USE` alone; `ON_DEMAND_FULL_USE_LICENSE` carries `FULL_USE` and `PARTIAL_USE`.
+                 * @example [
+                 *       "PARTIAL_USE"
+                 *     ]
+                 */
+                permissions: string[];
+                /** @description The broker-hosted licence document for this grant. */
+                document_url: string | null;
+            } | null;
+            _meta: {
+                'x402/payment-response': {
+                    success: boolean;
+                    transaction: string;
+                    network: string;
+                    payer: string;
+                    accessToken: string;
+                };
+            };
+        };
+        /** @description A record that a purchase happened: what was bought, when, at what price, and under which licence. Deliberately **not** a content schema. `list_purchases` used to return `McpFullContent`, which carries the article body, so a Buyer could re-read the full text of every work they had ever bought, free, 20 per call. Under single use (#939) a purchase is one licensed delivery, so purchase history is a receipt and the body is not part of it. Use `get_content` to buy a work — including one bought before. */
+        McpPurchaseReceipt: {
+            /** @description The purchase this receipt records. Distinct per purchase, so repeat buys of one work are distinguishable. */
+            purchase_id: string;
+            content_id: string;
+            title: string;
+            /** @description Where the work lives. Not a way to read it — a brokered URL serves a paywall to an unlicensed caller. */
+            url?: string | null;
+            store_id: string;
+            store_name: string;
+            /** @description What this purchase was charged, at the price in force when it was made. */
+            price_cents: number;
+            /** Format: date-time */
+            purchased_at: string;
+            /** @description The licence the broker granted for this purchase, as returned on the retrieval. Null when no grant was recorded: every non-brokered purchase, and brokered purchases made before the grant was captured. Null means "not recorded", never "no rights granted". */
+            license?: {
+                /** @example ON_DEMAND_LICENSE */
+                type: string;
+                /**
+                 * @example [
+                 *       "PARTIAL_USE"
+                 *     ]
+                 */
+                permissions: string[];
+                document_url: string | null;
+            } | null;
+        };
+        McpGetWalletBalanceResult: {
+            /** @description Current wallet balance in cents for the authenticated MCP key owner. */
+            wallet_balance_cents: number;
+        };
+        McpRegisterResult: {
+            /** @description The API key identifier (not secret). */
+            key: string;
+            /** @description The API key secret — returned once, never retrievable again. */
+            secret: string;
+            label: string;
+            can_search: boolean;
+            can_purchase: boolean;
+        };
+        McpGetContentDetailsResult: {
+            content: components['schemas']['McpContentSearchResult'];
+            /** @description Whether the authenticated user has a completed purchase for this content. */
+            has_purchased: boolean;
+            /** @description Current wallet balance in cents for the authenticated MCP key owner. */
+            wallet_balance_cents: number;
+        };
+        McpListPurchasesResult: {
+            /** @description Receipts, newest first, one per purchase and never collapsed — a Buyer may hold several purchases of one work, each at the price in force when it was made. These were `McpFullContent` until #939, which meant this endpoint returned the body of every article the Buyer had ever bought. */
+            purchases: components['schemas']['McpPurchaseReceipt'][];
+            /** @description Total number of completed purchases. */
+            total_count: number;
+            offset: number;
+            limit: number;
+        };
+        /** @description Returned as structuredContent when a get_content payment attempt fails due to insufficient wallet balance. Always accompanied by isError: true. */
+        McpInsufficientFundsError: {
+            /** @enum {string} */
+            error: 'insufficient_funds';
+            /** @description Current wallet balance in cents. */
+            wallet_balance_cents: number;
+            /** @description Price of the content in cents. */
+            required_cents: number;
+            /** @description Amount needed to top up the wallet to cover this purchase (required_cents - wallet_balance_cents). */
+            shortfall_cents: number;
+            /**
+             * Format: uri
+             * @description Direct link to the Ledewire wallet funding page, pre-filled with the shortfall amount.
+             */
+            funding_url: string;
+        };
+        /** @description Returned as structuredContent when a get_content call is refused because the buyer's daily spend cap would be exceeded. Always accompanied by isError: true. Deliberately carries no funding_url — adding money to the wallet cannot raise a cap, and a payload resembling McpInsufficientFundsError would send agents to the wrong remedy. The cap resets at resets_at; until then the only remedies are raising the cap or waiting. */
+        McpDailySpendCapReachedError: {
+            /** @enum {string} */
+            error: 'daily_spend_cap_reached';
+            /** @description The buyer's daily spend cap in cents. */
+            cap_cents: number;
+            /** @description Total spent so far in the current spend window. Ordinary completed purchases are summed per row; a bulk acquisition contributes its total, never its per-work purchases. */
+            spent_cents: number;
+            /** @description Cap minus spend so far, floored at zero — what the buyer may still spend in this window. */
+            remaining_cents: number;
+            /**
+             * Format: date-time
+             * @description The instant the current spend window rolls, in UTC. One calendar day boundary in the buyer's own timezone.
+             */
+            resets_at: string;
+            /** @description Whether this buyer's bulk acquisitions are exempt from the cap. When true, spent_cents and remaining_cents describe ordinary spend only — an authorized bulk acquisition does not consume them — so a client presenting remaining_cents must say which number it is. */
+            bulk_exempt: boolean;
+        };
+        /** @description The REST and x402 web-gate form of the same refusal, returned with HTTP 402 Payment Required by POST /v1/purchases and GET /v1/x402/contents/{id}. Carries the same fields as McpDailySpendCapReachedError alongside the standard error envelope, and the same absence of a funding URL. `error.type` is the machine-readable discriminator. */
+        DailySpendCapReachedError: {
+            error: {
+                /** @enum {integer} */
+                code: 402;
+                message: string;
+                /** @enum {string} */
+                type: 'daily_spend_cap_reached';
+            };
+            /** @description The buyer's daily spend cap in cents. */
+            cap_cents: number;
+            /** @description Total spent so far in the current spend window, summed over completed purchases by any path. */
+            spent_cents: number;
+            /** @description Cap minus spend so far, floored at zero — what the buyer may still spend in this window. */
+            remaining_cents: number;
+            /**
+             * Format: date-time
+             * @description The instant the current spend window rolls, in UTC.
+             */
+            resets_at: string;
+            /** @description Whether this buyer's bulk acquisitions are exempt from the cap. When true, spent_cents and remaining_cents describe ordinary spend only. */
+            bulk_exempt: boolean;
+        };
+        /** @description Returned by the fund_wallet tool. Contains the buyer portal wallet URL. Open this link in a browser to add funds using the Ledewire wallet funding page. */
+        McpFundWalletResult: {
+            /**
+             * Format: uri
+             * @description Buyer portal wallet URL. Includes an `amount` query param when amount_cents was provided.
+             */
+            url: string;
+        };
+        /** @description One JSON-RPC 2.0 request envelope. `id` is omitted for notifications (`notifications/initialized`), which are acknowledged with HTTP 202 and no body. */
+        McpJsonRpcRequest: {
+            /** @enum {string} */
+            jsonrpc: '2.0';
+            /** @enum {string} */
+            method: 'initialize' | 'notifications/initialized' | 'ping' | 'tools/list' | 'tools/call' | 'resources/list' | 'resources/read' | 'prompts/list' | 'prompts/get';
+            /** @description Client-supplied request identifier. Echoed back in the response. Omitted for notifications. */
+            id?: number | string;
+            /** @description Shape depends on `method`. `initialize`: `{ protocolVersion, capabilities, clientInfo }` — all three required. `tools/call`: `{ name: "<tool_name>", arguments: { ... } }`; call `tools/list` for each tool's full `inputSchema`. `resources/read`: `{ uri: "ledewire://..." }`. `prompts/get`: `{ name: "<prompt_name>", arguments: { ... } }`. `tools/list`, `resources/list`, `prompts/list` and `ping` take no parameters. */
+            params?: {
+                /**
+                 * @description Tool name for `tools/call`, prompt name for `prompts/get`.
+                 * @enum {string}
+                 */
+                name?: 'search_content' | 'list_publications' | 'list_publication_works' | 'register' | 'get_wallet_balance' | 'get_content_details' | 'get_content' | 'list_purchases' | 'list_my_stores' | 'fund_wallet' | 'list_my_content' | 'search_my_content' | 'register_content' | 'update_content' | 'check_content_status' | 'get_sales_summary' | 'get_content_sales' | 'get_buyer_insights' | 'onboarding_checklist' | 'troubleshoot_integration' | 'optimize_pricing';
+                arguments?: {
+                    [key: string]: unknown;
+                };
+                /**
+                 * @description Resource URI for `resources/read`.
+                 * @enum {string}
+                 */
+                uri?: 'ledewire://docs/overview' | 'ledewire://docs/pricing-guidelines' | 'ledewire://seller/context';
+                /** @description Requested revision for `initialize`. See the negotiation note on the endpoint. */
+                protocolVersion?: string;
+                capabilities?: Record<string, never>;
+                clientInfo?: Record<string, never>;
+            };
+        };
+        /** @description Returned by the list_my_stores tool. Every store the authenticated key's owner holds owner or author access to, with that store's non-archived content count. */
+        McpListMyStoresResult: {
+            stores: {
+                /** Format: uuid */
+                store_id: string;
+                store_name: string;
+                /**
+                 * @description Highest access the key owner holds on this store.
+                 * @enum {string}
+                 */
+                role: 'owner' | 'author';
+                /** @description Non-archived content items in the store. */
+                content_count: number;
+            }[];
+        };
+        /** @description Returned by the list_my_content tool. A page of the connected store's catalog, including items no buyer can see. Pagination follows the standard `offset`/`limit` contract shared with search_content and list_purchases; the `total`, `page` and `per_page` fields are retained for clients written against the tool's original contract and describe the same window. */
+        McpListMyContentResult: {
+            contents: {
+                /** Format: uuid */
+                id: string;
+                title: string;
+                teaser?: string | null;
+                price_cents: number;
+                /** @description `public`, `unlisted`, or `archived`. */
+                visibility: string;
+                /** @enum {string} */
+                content_type: 'markdown' | 'html' | 'pdf' | 'image' | 'video' | 'external_ref' | 'brokered';
+                tags: string[];
+                /** Format: date-time */
+                created_at: string;
+            }[];
+            /** @description Total matching items across all pages, before pagination. */
+            total_count: number;
+            /** @description Number of records skipped to produce this page. */
+            offset: number;
+            /** @description Maximum records this page could contain. */
+            limit: number;
+            /** @description Legacy, superseded by `total_count`. Identical value, retained for existing clients. */
+            total: number;
+            /** @description Legacy, superseded by `offset`. One-based page number of the page *containing* the first record returned, derived from the window actually applied. When `offset` is not a multiple of `limit` there is no exact page number and this page's own span only overlaps the records returned — `offset: 25, limit: 10` returns records 25-34 and reports page 3, which spans 20-29. Paginate by `offset`, not by incrementing this field. */
+            page: number;
+            /** @description Legacy, superseded by `limit`. Identical value, retained for existing clients. */
+            per_page: number;
+        };
+        /** @description Returned by the search_my_content tool. Deliberately narrower than McpListMyContentResult — it is a lookup aid for finding a content_id, not a catalog view. */
+        McpSearchMyContentResult: {
+            contents: {
+                /** Format: uuid */
+                id: string;
+                title: string;
+                teaser?: string | null;
+                /** @enum {string} */
+                content_type: 'markdown' | 'html' | 'pdf' | 'image' | 'video' | 'external_ref' | 'brokered';
+                tags: string[];
+            }[];
+        };
+        /** @description Returned by both register_content and update_content on success. The two tools share one shape: the identifying fields of the content item as it now stands. Neither returns the body — read it back with get_content if you need it. */
+        McpContentMutationResult: {
+            /** Format: uuid */
+            id?: string;
+            title?: string;
+            /** @enum {string} */
+            content_type?: 'markdown' | 'html' | 'pdf' | 'image' | 'video' | 'external_ref' | 'brokered';
+            /** @description `public`, `unlisted`, or `archived`. */
+            visibility?: string;
+            price_cents?: number;
+        };
+        /** @description Returned by the check_content_status tool. Read-only diagnosis of one content item — `issues` is empty exactly when `is_healthy` is true. */
+        McpCheckContentStatusResult: {
+            /** Format: uuid */
+            content_id: string;
+            title: string;
+            /** @description Problems found, in plain English. Empty when the item is healthy. */
+            issues: string[];
+            /** @description Suggested next steps, one per issue where a fix is known. */
+            recommendations: string[];
+            is_healthy: boolean;
+        };
+        /** @description One row of the get_content_sales tool's result — a single content item's sales performance. */
+        McpContentSalesRow: {
+            /** Format: uuid */
+            content_id: string;
+            title: string;
+            purchase_count: number;
+            revenue_cents: number;
+        };
+        /** @description Result of the get_content_sales tool — one page of the store's per-content sales ranking. Carried identically in structuredContent and in the double-encoded text block. */
+        McpGetContentSalesResult: {
+            content_sales: components['schemas']['McpContentSalesRow'][];
+            /** @description Number of content items in the whole ranking, not in the returned page. Scoped the same way the rows are — an author key counts only their attributed content. */
+            total_count: number;
+            offset: number;
+            limit: number;
+        };
+        /** @description Result of the get_buyer_insights tool — one page of the store's buyers, ranked by total spend descending. Carried identically in structuredContent and in the text block. */
+        McpGetBuyerInsightsResult: {
+            buyer_insights: components['schemas']['BuyerStatisticsItem'][];
+            /** @description Number of buyers in the whole ranking, not in the returned page. Scoped the same way the rows are — an author key counts only buyers of their attributed content. */
+            total_count: number;
+            offset: number;
+            limit: number;
+        };
         AuthTokenRefreshRequest: {
             refresh_token?: string;
         };
@@ -735,8 +1272,26 @@ declare interface components {
                 [key: string]: unknown;
             };
         };
+        /** @description The buyer's wallet. balance_cents and spendable_cents are the same number and always will be — balance_cents has always meant "what you can spend", and money committed to a bulk acquisition is a hold, which moves it out of the wallet rather than annotating it. held_cents and holds exist so a buyer mid-acquisition can see why their balance is lower than their purchase history explains. */
         WalletBalanceResponse: {
+            /** @description Spendable balance in cents. Excludes funds held against a bulk acquisition. */
             balance_cents: number;
+            /** @description The same figure as balance_cents, named in the vocabulary holds require. */
+            spendable_cents: number;
+            /** @description Total committed to active bulk acquisitions and not yet spent or released. */
+            held_cents: number;
+            /** @description One entry per bulk acquisition currently holding funds. Empty when none is. */
+            holds: {
+                /** Format: uuid */
+                acquisition_id: string;
+                /** @description What this acquisition is currently holding. */
+                held_cents: number;
+                /**
+                 * Format: date-time
+                 * @description When the hold was placed.
+                 */
+                authorized_at: string;
+            }[];
         };
         WalletTransactionItem: {
             /** @description ID of the transaction entry (matches the source record) */
@@ -747,17 +1302,20 @@ declare interface components {
              */
             type: 'credit' | 'debit';
             /**
-             * @description What caused this wallet movement
+             * @description What caused this wallet movement. bulk_acquisition and bulk_hold are each one entry for a whole bulk acquisition — its per-work purchases are deliberately not listed here, because one acquisition can hold tens of thousands of them and they describe one decision. bulk_hold is an acquisition still holding funds: the money has left the wallet but has not been spent, and it becomes a bulk_acquisition entry for the amount actually captured once the acquisition ends. An acquisition never produces both.
              * @enum {string}
              */
-            reason: 'wallet_funding' | 'purchase' | 'refund';
-            /** @description Always positive; direction expressed by `type` */
+            reason: 'wallet_funding' | 'purchase' | 'refund' | 'bulk_acquisition' | 'bulk_hold';
+            /** @description Always positive; direction expressed by `type`. For a bulk_hold entry this is what is currently held; for a bulk_acquisition entry it is what was captured, not what was held — the uncaptured remainder was released, never charged. Note that a bulk acquisition's per-work purchases each carry a price_cents that is a rounded display value and is NOT summable: bulk prices at micro precision and rounds to cents once, on the acquisition total, so this aggregate is the figure to read. */
             amount_cents: number;
             /** @description Running wallet balance immediately after this event */
             balance_after_cents: number;
-            /** @enum {string} */
-            status: 'completed' | 'pending' | 'failed' | 'cancelled';
-            /** @description ID of the source record (Purchase or FundingTransfer) */
+            /**
+             * @description Status of the source record. authorized/acquiring/settled/cancelled/failed are bulk acquisition states; the rest are purchase and funding transfer states.
+             * @enum {string}
+             */
+            status: 'completed' | 'pending' | 'failed' | 'cancelled' | 'settled' | 'reverted' | 'refunded' | 'authorized' | 'acquiring';
+            /** @description ID of the source record (Purchase, FundingTransfer or Acquisition) */
             reference_id: string;
             /** @description Human-readable label suitable for display */
             description: string;
@@ -783,17 +1341,17 @@ declare interface components {
                 has_sufficient_funds?: boolean;
             };
         };
-        /** @description Update request for content. `content_body` applies to `markdown` content; `content_uri` and `external_identifier` apply to `external_ref` content. */
+        /** @description Update request for content. `content_body` applies to `markdown` and inline `html` content; `content_uri` applies to `external_ref` and remote `html` content. For `html`, submitting both `content_body` and `content_uri` in the same request is rejected with `400`. */
         ContentUpdateRequest: {
             /** @description Content title */
             title?: string;
             /**
              * Format: byte
-             * @description Full article body in markdown, base64 encoded. For `markdown` content only.
+             * @description Full article body, base64 encoded. For `markdown` and inline `html` content. Must be base64-encoded before sending (e.g. `btoa(bodyText)`).
              */
             content_body?: string;
             /**
-             * @description URI of the resource. Required for `external_ref` content; optional for `markdown` content.
+             * @description URI of the resource. For `external_ref` and remote `html` content.
              * @example https://vimeo.com/123456789
              */
             content_uri?: string;
@@ -804,7 +1362,7 @@ declare interface components {
             external_identifier?: string | null;
             /**
              * Format: byte
-             * @description Content teaser, base64 encoded
+             * @description Content teaser, base64 encoded. Must be base64-encoded before sending (e.g. `btoa(teaserText)`)
              */
             teaser?: string;
             /** @description Price in cents (must be greater than 0) */
@@ -1025,22 +1583,22 @@ declare interface components {
              */
             started_at?: string;
         };
-        /** @description Create request body for content. Required fields vary by `content_type`: `markdown` requires `content_body`; `external_ref` requires `content_uri`. Both types accept an optional `content_uri` link. */
+        /** @description Create request body for content. Required fields vary by `content_type`: `markdown` requires `content_body`; `html` requires exactly one of `content_body` (inline) or `content_uri` (remote); `external_ref`, `pdf`, `image`, and `video` require `content_uri` (`content_body` is not accepted). */
         Content: {
             /**
-             * @description The type of content being created.
+             * @description The type of content being created. `pdf`, `image`, and `video` require `content_uri`; `content_body` is not accepted for these types.
              * @enum {string}
              */
-            content_type: 'markdown' | 'external_ref';
+            content_type: 'markdown' | 'html' | 'pdf' | 'image' | 'video' | 'external_ref';
             /** @description Content title */
             title: string;
             /**
              * Format: byte
-             * @description Full article body in markdown, base64 encoded. Required when `content_type` is `markdown`.
+             * @description Full article body, base64 encoded. Required when `content_type` is `markdown`. For `html` content, provide either `content_body` (inline) or `content_uri` (remote) — not both. Must be base64-encoded before sending (e.g. `btoa(htmlText)`). Note: HTML special characters (`<`, `>`, `&`) should be unicode-escaped when embedding the JSON response in a `<script>` tag.
              */
             content_body?: string;
             /**
-             * @description URI of the resource. Required when `content_type` is `external_ref`; optional for `markdown` content.
+             * @description URI of the resource. Required when `content_type` is `external_ref`, `pdf`, `image`, `video`, or remote `html`.
              * @example https://vimeo.com/123456789
              */
             content_uri?: string;
@@ -1051,7 +1609,7 @@ declare interface components {
             external_identifier?: string;
             /**
              * Format: byte
-             * @description (Optional) Article teaser, written in markdown and base64 encoded.
+             * @description (Optional) Article teaser, written in markdown and base64 encoded. Must be base64-encoded before sending (e.g. `btoa(teaserText)`).
              */
             teaser?: string;
             /** @description Price for the content in cents. */
@@ -1071,23 +1629,23 @@ declare interface components {
                 [key: string]: unknown;
             };
         };
-        /** @description Response shape for a single content item. The presence of `content_body` vs `content_uri` depends on `content_type`: `markdown` includes `content_body`; `external_ref` includes `content_uri` (the external URI) and optionally `external_identifier`. */
+        /** @description Response shape for a single content item. The presence of `content_body` vs `content_uri` depends on `content_type` and storage mode: `markdown`, `brokered`, and inline `html` include `content_body`; `external_ref`, `pdf`, `image`, `video`, and remote `html` include `content_uri`. */
         ContentResponse: {
             id: string;
             /**
-             * @description The type of content.
+             * @description The type of content. `pdf`, `image`, and `video` are remote-only types; `content_uri` is withheld until purchase. `brokered` is system-managed (e.g. Tollbit-sourced) and cannot be created directly via this API.
              * @enum {string}
              */
-            content_type: 'markdown' | 'external_ref';
+            content_type: 'markdown' | 'html' | 'pdf' | 'image' | 'video' | 'external_ref' | 'brokered';
             /** @description Content title */
             title: string;
             /**
              * Format: byte
-             * @description Full article body in markdown, base64 encoded. Present when `content_type` is `markdown`.
+             * @description Full article body, base64 encoded. Present when `content_type` is `markdown` or inline `html`. Must be base64-decoded before rendering (e.g. `atob(content.content_body ?? '')`). Note: HTML special characters (`<`, `>`, `&`) must be unicode-escaped when embedding the JSON in a `<script>` tag.
              */
             content_body?: string | null;
             /**
-             * @description URI of the external resource. Present when `content_type` is `external_ref`.
+             * @description URI of the external resource. Present when `content_type` is `external_ref`, `pdf`, `image`, `video`, or remote `html`.
              * @example https://vimeo.com/123456789
              */
             content_uri?: string | null;
@@ -1096,9 +1654,11 @@ declare interface components {
              * @example vimeo:123456789
              */
             external_identifier?: string | null;
+            /** @description Canonical URL of this content on its origin site. Used by the x402 verify-origin endpoint to bind a third-party page to a Ledewire content record. */
+            resource_url?: string | null;
             /**
              * Format: byte
-             * @description Article teaser, base64 encoded.
+             * @description Article teaser, base64 encoded. Must be base64-decoded before rendering (e.g. `atob(content.teaser ?? '')`).
              */
             teaser: string;
             /** @description Price for the content in cents. */
@@ -1189,12 +1749,12 @@ declare interface components {
         ContentListItem: {
             id: string;
             /** @enum {string} */
-            content_type: 'markdown' | 'external_ref';
+            content_type: 'markdown' | 'html' | 'pdf' | 'image' | 'video' | 'external_ref' | 'brokered';
             title: string;
             price_cents: number;
             /**
              * Format: byte
-             * @description Article teaser, base64 encoded. Null when not set.
+             * @description Article teaser, base64 encoded. Null when not set. Must be base64-decoded before rendering (e.g. `atob(item.teaser ?? '')`).
              */
             teaser: string | null;
             /** @enum {string} */
@@ -1205,11 +1765,13 @@ declare interface components {
             content_uri: string | null;
             /** @description Namespaced platform ID for `external_ref` content. Null for other types. */
             external_identifier?: string | null;
+            /** @description Canonical URL of this content on its origin site. Used by the x402 verify-origin endpoint. */
+            resource_url?: string | null;
         };
         /**
          * @description Full content detail plus real-time access and wallet context for a specific user. Returned by the buyer-facing `GET /v1/content/:id/with-access` endpoint.
          *
-         *     **URI gating for `external_ref` content:** `content_uri` (the external URI) is only present in the response when `access_info.has_purchased` is `true`. For all other states (unauthenticated, insufficient funds, not yet purchased) it is omitted, ensuring buyers cannot access the Vimeo link, PDF URI, or other external resource without completing a purchase.
+         *     **URI gating for remote content:** `content_uri` is only present in the response when `access_info.has_purchased` is `true`. This applies to `external_ref` content and remote-mode `html` content (where the payload is a URI rather than an inline body). For all other states (unauthenticated, insufficient funds, not yet purchased) it is omitted, ensuring buyers cannot access the Vimeo link, PDF URI, or other external resource without completing a purchase.
          */
         ContentWithAccessResponse: components['schemas']['ContentResponse'] & {
             access_info: components['schemas']['ContentAccessInfo'];
@@ -1245,6 +1807,17 @@ declare interface components {
             /** Format: date-time */
             timestamp: string;
             status: components['schemas']['PurchaseStatus'];
+            /**
+             * @description The delivered work, present **only** on the response to `POST /v1/purchases` and only when the deliverable is something we hold. It is the delivery, not a field of the purchase record: the same purchase read back from `GET /v1/purchases/{id}` or listed from `GET /v1/purchases` does not carry it, and there is no route that serves it again.
+             *
+             *     That asymmetry is the rule rather than an omission. A Buyer keeps what they were given — single use is non-transferable, not read-once — but LedeWire does not hand the same bytes over a second time without a second grant, and every read from LedeWire is a purchase.
+             */
+            content_body?: string;
+            /**
+             * Format: uri
+             * @description Where the work lives, in place of `content_body`, for a deliverable hosted elsewhere. Same rule: present only on the response to the purchase that paid for it.
+             */
+            content_uri?: string;
         };
         MerchantSaleResponse: {
             id: string;
@@ -1301,7 +1874,7 @@ declare interface components {
                 has_sufficient_funds?: boolean | null;
                 has_purchased: boolean;
                 /** @enum {string} */
-                next_required_action: 'authenticate' | 'fund_wallet' | 'purchase' | 'view_content';
+                next_required_action: 'authenticate' | 'fund_wallet' | 'purchase';
             };
         };
         WalletPaymentStatusResponse: {
@@ -1329,6 +1902,491 @@ declare interface components {
                 };
             };
         };
+        /** @description A single x402 v2 resource entry returned by the Bazaar discovery endpoint. */
+        X402BazaarResource: {
+            /** @description Canonical URL for this content. Equal to `resource_url` when the content has one; otherwise constructed as `{base_url}/v1/x402/contents/{id}`. */
+            resource: string;
+            /** @enum {string} */
+            type: 'http';
+            /** @enum {integer} */
+            x402Version: 2;
+            accepts: {
+                /** @example ledewire-wallet */
+                scheme: string;
+                /** @example ledewire:v1 */
+                network: string;
+            }[];
+            /** @description Unix timestamp (seconds) of the content's last update. */
+            lastUpdated: number;
+            metadata: {
+                title: string;
+                /** @description Plain UTF-8 preview text. Never base64. */
+                teaser: string;
+                store_name: string;
+                /** @description `metadata["category"]` when present; otherwise falls back to `content_type`. Never null. */
+                category: string;
+            };
+        };
+        /** @description Response from the x402 Bazaar discovery endpoint. */
+        X402BazaarDiscoveryResponse: {
+            /** @description Total number of public resources (ignores pagination). */
+            total: number;
+            resources: components['schemas']['X402BazaarResource'][];
+        };
+        /** @description Response body returned by the x402 content endpoint on a successful `200`. Delivers the purchased content directly in the settlement response. `content_body` is present when `content_type` is `markdown`, `brokered`, or inline `html`; `content_uri` is present when `content_type` is `external_ref`, `pdf`, `image`, `video`, or remote `html`. `purchase_id` is the UUID of the settled Purchase record (null for free content). */
+        X402ContentResponse: {
+            id: string;
+            /** @enum {string} */
+            content_type: 'markdown' | 'html' | 'pdf' | 'image' | 'video' | 'external_ref' | 'brokered';
+            title: string;
+            price_cents: number;
+            /** @description Plain UTF-8 text preview. */
+            teaser: string;
+            /** @enum {string} */
+            visibility: 'public' | 'unlisted' | 'private';
+            metadata?: {
+                [key: string]: unknown;
+            };
+            external_identifier?: string | null;
+            /** @description UUID of the settled Purchase record. Null for free content. */
+            purchase_id?: string | null;
+            /** @description Canonical URL of this content on its origin site. Set when content was registered via a pricing rule or manual resource_url assignment. */
+            resource_url?: string | null;
+            /** @description Full article body in plain UTF-8 markdown. Present when content_type is markdown. */
+            content_body?: string | null;
+            /** @description URI of the external resource. Present when content_type is `external_ref`, `pdf`, `image`, or `video`. */
+            content_uri?: string | null;
+        };
+        /** @description Returned when the URL matches a registered Ledewire content item. */
+        VerifyOriginVerified: {
+            /** @enum {boolean} */
+            verified: true;
+            /** @description UUID of the matching Content record. */
+            content_id: string;
+            /** @description UUID of the store that owns this content. */
+            store_id: string;
+            /** @description Price in cents as a string (e.g. "10" = $0.10). */
+            amount: string;
+            /** @description Content title. */
+            title: string;
+        };
+        /** @description Returned when the URL is not registered or the URL is invalid. */
+        VerifyOriginUnverified: {
+            /** @enum {boolean} */
+            verified: false;
+        };
+        /** @description JSON Web Key Set (RFC 7517) containing the RS256 public key for x402 accessToken verification. */
+        JwksResponse: {
+            keys: {
+                /** @enum {string} */
+                kty: 'RSA';
+                /** @enum {string} */
+                use: 'sig';
+                /** @enum {string} */
+                alg: 'RS256';
+                /** @description Key ID. Matches the `kid` header claim in minted access tokens. */
+                kid: string;
+                /** @description RSA modulus (Base64url-encoded). */
+                n: string;
+                /** @description RSA public exponent (Base64url-encoded). */
+                e: string;
+            }[];
+        };
+        /**
+         * @description One work in a Selection, and what happened to it. Every submitted row appears, including the ones we refused — a malformed line and a duplicate spelling are dispositions rather than omissions, and a row that vanished silently between upload and quote is the failure the acknowledgement step exists to prevent.
+         *
+         *     `line_state`, `purchased` and `delivery_state` answer three different questions and none implies another. A work can be quoted and never reached, purchased and not delivered, or excluded and therefore never attempted.
+         */
+        AcquisitionWork: {
+            /** @description 1-based place in the submitted file, so a Buyer can find the row they wrote. */
+            position: number;
+            /** @description The address exactly as submitted. */
+            submitted_url: string;
+            /** @description The address after canonicalization — the identity function for a brokered work. Two rows that differ only in `www.`, a query string or a fragment name one work, and the second is excluded as a duplicate rather than bought twice. */
+            canonical_url?: string | null;
+            /**
+             * @description What the quote said. `firm` was priced from a rate the broker answered with; `estimated` from a rate we already held because the broker could not be asked; `excluded` will not be bought.
+             * @enum {string}
+             */
+            line_state: 'pending' | 'firm' | 'estimated' | 'excluded';
+            /**
+             * @description Present only on an excluded line. `excluded_rate_unavailable` is the one transient reason.
+             * @enum {string|null}
+             */
+            exclusion_reason?: 'excluded_malformed' | 'excluded_duplicate' | 'excluded_no_rate' | 'excluded_free_not_supported' | 'excluded_not_deliverable' | 'excluded_insufficient_rights' | 'excluded_above_price_ceiling' | 'excluded_rate_unavailable' | null;
+            /** @description What this work was quoted at, in micros. **Never published in cents.** Per-work cents are display-only and non-summable for a Bulk acquisition — the authoritative figure is micros and the acquisition total is what reconciles, so a client is given nothing here that invites adding up to the charge. */
+            price_micros?: number | null;
+            /**
+             * @description Whether a Purchase was made for this work.
+             *
+             *     **History, not access.** Under single use a completed Purchase is a receipt for a delivery that has already happened; it grants nothing further, and is never a reason to serve a body again. Reported so a Buyer can tell "we bought this and the bytes did not arrive" — a delivery we owe — from "we never bought it".
+             */
+            purchased: boolean;
+            /**
+             * @description What the run did. `pending` means not yet attempted — which is also what an excluded work reads, because it was never attempted and `undelivered` would claim we tried and failed. Those are different answers to a Buyer and only the second is worth a retry.
+             * @enum {string}
+             */
+            delivery_state: 'pending' | 'delivered' | 'undelivered';
+            /**
+             * @description Why an attempted work did not arrive, as a type rather than prose. Only `retrieval_failed` is transient; the rest fail identically on every attempt, so retrying one spends a run's budget on works that need re-pricing, a fix, or money.
+             * @enum {string|null}
+             */
+            failure_reason?: 'retrieval_failed' | 'not_licensable' | 'price_drifted' | 'client_error' | 'insufficient_funds' | 'cap_refused' | null;
+            /** @description How many times retrieval was tried, the successful attempt included. */
+            attempts?: number | null;
+        };
+        /**
+         * @description A Publication a Buyer can license from — the title a Bulk acquisition is organised around. Listed from our own registry, which is reconciled daily against the Broker's directory, rather than from a live call.
+         *
+         *     Licensability is a rights answer, not a quality one. A publication that publishes no `FULL_USE` rate is still listed, with `bulk_licensable: false`: its works can be bought one at a time but are excluded from a corpus as `excluded_insufficient_rights`.
+         */
+        Publication: {
+            /** Format: uuid */
+            id: string;
+            /** @description The Broker's display name for the publication. */
+            name: string;
+            /** @description The domains the publication is listed under, spelled as the Broker spells them — including a `www.` prefix where it has one. */
+            domains: string[];
+            /** @description Whether works from this publication can come back in a Bulk acquisition's corpus — true when it publishes a `FULL_USE` rate. */
+            bulk_licensable: boolean;
+        };
+        /** @description Every Publication the Broker reports as ready to license, paginated. */
+        PublicationListResponse: {
+            data: components['schemas']['Publication'][];
+            pagination: components['schemas']['PaginationMeta'];
+        };
+        /** @description The MCP `list_publications` result: one page of the Publications a Buyer can license from, paged by offset and limit as `search_content` is. */
+        McpListPublicationsResult: {
+            publications: components['schemas']['Publication'][];
+            total_count: number;
+            offset: number;
+            limit: number;
+        };
+        /** @description A work a Publication has available to license, as the Broker's catalog lists it. `url` is exactly what a Selection takes. */
+        PublicationWork: {
+            /** Format: uri */
+            url: string;
+            /**
+             * Format: date-time
+             * @description When the Broker says the work was last modified. Null where it supplies none, which on some publications is every work.
+             */
+            last_mod: string | null;
+        };
+        /** @description One page of a Publication's works, read live from the Broker's catalog. Unpriced: pricing happens when a Selection of these URLs is quoted. */
+        PublicationWorkListResponse: {
+            /** Format: uuid */
+            publication_id: string;
+            /** @description The Publication domain this page was read from, in the Broker's spelling. A publication with several domains is walked one domain after another. Null only when the publication has no live domain to read. */
+            domain: string | null;
+            /**
+             * @description How `from`/`to` applied to this page's domain. `applied` means the Broker filtered and every work is in range. `unsupported` means the filtered query returned nothing while the same domain unfiltered does not: the domain's catalog carries no modification dates, so the range cannot be answered. That is not the same as having no works in the range. The unfiltered works are deliberately not returned in their place, because they are not known to fall inside the range.
+             * @enum {string}
+             */
+            date_filter: 'not_requested' | 'applied' | 'unsupported';
+            works: components['schemas']['PublicationWork'][];
+            /** @description Opaque. Pass it back as `cursor` with the same `from`/`to` for the next page. Null means the walk is over; an empty page with a cursor is not the end. */
+            next_cursor: string | null;
+        };
+        /** @description The MCP `list_publication_works` result. It is the same page as `GET /v1/publications/{id}/works` returns, by reference, so the two cannot drift. */
+        McpListPublicationWorksResult: components['schemas']['PublicationWorkListResponse'];
+        /** @description Per-work dispositions for a Bulk acquisition, paginated. Its own endpoint rather than a field on the acquisition because a Selection may name 10,000 works and the acquisition resource has to stay cheap enough to poll for hours. */
+        PaginatedAcquisitionWorkList: {
+            data: components['schemas']['AcquisitionWork'][];
+            pagination: components['schemas']['PaginationMeta'];
+        };
+        /**
+         * @description A Bulk acquisition — the one resource the whole flow hangs off. The Buyer holds this id from the moment they submit a Selection, and every later step reads or advances it: the quote arrives on it, the acknowledgement is a timestamp on it, the hold is sized from its total, and the run writes its outcome back to it.
+         *
+         *     `status` and `quote_state` are two independent state machines and are not collapsible. `status` is the money — `quoted` holds nothing, `authorized` and `acquiring` hold funds, and every terminal state releases what is left. `quote_state` is whether the prices are in. A `quoted` acquisition whose quote is still `pending` has a snapshot and no prices, and a client that read one field would mis-read exactly that case.
+         */
+        AcquisitionResponse: {
+            /** Format: uuid */
+            id: string;
+            /**
+             * @description Where the money is. `quoted` reserves nothing; `authorized` and `acquiring` hold the stated maximum chargeable total; `settled`, `cancelled` and `failed` are terminal and have released whatever was not captured.
+             * @enum {string}
+             */
+            status: 'quoted' | 'authorized' | 'acquiring' | 'settled' | 'cancelled' | 'failed';
+            /**
+             * @description Whether the Selection has been priced. Pricing is asynchronous — resolving rates for 10,000 works is ~200 upstream batch calls under undocumented limits — so a submitted Selection comes back `pending` and the client polls this.
+             * @enum {string}
+             */
+            quote_state: 'pending' | 'ready' | 'failed';
+            /** @description How many distinct publications the Selection spans. Nothing in a Bulk acquisition is keyed on a single publication. */
+            publication_count: number;
+            /** @description How many rows the upload named and we accepted. Published alongside `work_count` because until pricing finishes the two differ and only this one is known: nothing carries a price while `quote_state` is `pending`, so a freshly submitted 10,000-row Selection reports `work_count: 0` and would otherwise read exactly like an empty one. */
+            submitted_work_count: number;
+            /** @description Works that carry a price — firm or estimated. Excluded rows are not counted here, and neither is anything still waiting to be priced. */
+            work_count: number;
+            quote: components['schemas']['AcquisitionQuote'];
+            /** @description What we cannot sell, grouped by reason and counted. Grouped rather than enumerated because a 10,000-work Selection can exclude thousands of rows and the acknowledgement step asks the Buyer to register what kinds of thing are not coming; the per-work detail is `GET /v1/acquisitions/{id}/works`, which paginates. */
+            exclusions: {
+                /**
+                 * @description Six of these are the Buyer's to act on and one is ours. `excluded_rate_unavailable` is the only transient one — it says we could not reach the broker to ask, and is the only reason here worth asking us to retry. `excluded_not_deliverable` is a broker failure we observed; `excluded_insufficient_rights` is a rights decision we made; `excluded_above_price_ceiling` is a price we declined. Those three are the ones most easily collapsed and must not be.
+                 * @enum {string}
+                 */
+                reason: 'excluded_malformed' | 'excluded_duplicate' | 'excluded_no_rate' | 'excluded_free_not_supported' | 'excluded_not_deliverable' | 'excluded_insufficient_rights' | 'excluded_above_price_ceiling' | 'excluded_rate_unavailable';
+                count: number;
+            }[];
+            /** @description What the run has done. `purchased` and `delivered` are separate facts and both are reported, because a Purchase can complete and its body fail to arrive — a delivery LedeWire owes, and not a reason to charge again. An acquisition with 10,000 purchases and 9,700 deliveries has 300 outstanding, which no single number says. */
+            delivery: {
+                /** @description Works a Purchase was made for. History, not an entitlement to re-read. */
+                purchased: number;
+                delivered: number;
+                /** @description Attempted and not delivered. An excluded work is not counted here — it was never attempted, and "not in your corpus because we refused to quote it" is a different answer from "not in your corpus because retrieval failed". */
+                undelivered: number;
+                /** @description Quoted and not yet reached. What a resumed run will attempt. */
+                outstanding: number;
+            };
+            /** Format: date-time */
+            created_at: string;
+        };
+        /** @description The priced Selection, and the promise made about it. */
+        AcquisitionQuote: {
+            /** @enum {string} */
+            state: 'pending' | 'ready' | 'failed';
+            /** @description Subtotal of works priced from a rate the broker answered with, in micros (millionths of a dollar). */
+            firm_micros: number;
+            /** @description Subtotal of works priced from a rate we already held, because the broker could not be asked. Estimated, never firm — the price may have moved, and observed broker prices move materially in both directions. What protects the Buyer is `maximum_chargeable_total_cents`. */
+            estimated_micros: number;
+            /**
+             * @description The most this acquisition can charge. Settlement clamps captures to it and absorbs any drift above it from margin, so it is a ceiling rather than an estimate — an acquisition that cannot deliver every work charges less.
+             *
+             *     Subtotals are published in micros and the ceiling in cents deliberately: rounding happens **once**, on the total. Two rounded cent subtotals would not reliably sum to the rounded total, and publishing them that way would invite a client to add them up and disagree with the figure we charge. Per-work prices never sum to this either.
+             */
+            maximum_chargeable_total_cents: number;
+            /** Format: date-time */
+            quoted_at?: string | null;
+            /**
+             * Format: date-time
+             * @description When the stated maximum chargeable total stops standing — 24 hours after pricing. Published rather than left to the client to compute, so the window is not hard-coded against a constant of ours. Re-pricing is cheap: it re-prices the snapshot without re-resolving it, so the Buyer gets the same works at today's prices without uploading anything again.
+             */
+            expires_at?: string | null;
+            /**
+             * Format: date-time
+             * @description When the Buyer registered what we cannot sell them. Withdrawn on every re-quote, so it always refers to the current set of exclusions and never to a previous one — an acknowledgement carried forward would be a Buyer authorizing a list they never saw.
+             */
+            exclusions_acknowledged_at?: string | null;
+        };
+        /**
+         * @description Where a Bulk acquisition's Corpus is — a **state**, never an error.
+         *
+         *     A corpus is a rendering of Purchases the Buyer already holds, not an entitlement of its own, which is what makes everything about it cheap: it can be discarded and rebuilt, and rebuilding grants nothing that was not already granted. So a blob past its 30-day retention answers `rebuild_required` at 200 rather than 404 or 410 — those would tell the Buyer something was lost, and nothing was.
+         *
+         *     `rebuild_required` covers "never assembled" as well as "expired", on purpose: from the Buyer's side they are one situation — there is no file, ask for one — and splitting them would put our bookkeeping into their contract.
+         */
+        CorpusResponse: {
+            /**
+             * @description `ready` is downloadable now. `assembling` means a run is in flight and `pending` that one is queued — poll either. `rebuild_required` means ask for it again, with `POST /v1/acquisitions/{id}/corpus`. `failed` carries a reason.
+             * @enum {string}
+             */
+            state: 'pending' | 'assembling' | 'ready' | 'rebuild_required' | 'failed';
+            /**
+             * @description The archive rendering. There is no size-conditional switching — a client never branches on how big its corpus is.
+             * @enum {string|null}
+             */
+            format?: 'tar_gz' | 'jsonl_gz' | null;
+            /** @description Size of the assembled archive. Null unless `ready`. */
+            byte_size?: number | null;
+            /**
+             * Format: date-time
+             * @description When the blob is retired, 30 days after assembly. The signed Manifest has no expiry and is served separately from `/v1/acquisitions/{id}/manifest`, because an auditor years later must be able to obtain the record without the corpus.
+             */
+            expires_at?: string | null;
+            /** @description Why assembly broke. Present only when `state` is `failed`. */
+            failure_reason?: string | null;
+            /**
+             * @description Where to fetch the archive, relative to this API, and null in every state but `ready`.
+             *
+             *     An authenticated route of ours rather than a presigned store URL. Fetch it with the same bearer token as this request and the response is the archive itself — there is no redirect to follow and no second URL to capture. A link to the object store handed out here would stand whether or not its reader could authenticate, and a client may log, cache or forward a poll response. The corpus is the most sensitive thing this API serves, so the authorization decision belongs on every request for it.
+             */
+            download_url?: string | null;
+        };
+        /**
+         * @description The signed Manifest of a Bulk acquisition — the audit record itself, not a summary of one. There is no separate receipt: two representations of the same facts eventually disagree, and a manifest that disagrees with the signed record is worse than no manifest.
+         *
+         *     Served verbatim from the bytes stored at first assembly. It is **not** re-derived from the rows it was generated from, because the signature covers bytes rather than meaning — a re-derived document would read the same, hash differently, and fail its own signature. A row edited in 2029 therefore cannot change a document written in 2026.
+         *
+         *     Permanent. The corpus blob expires 30 days after assembly; this does not, because an auditor years later must be able to obtain the record without the corpus.
+         */
+        CorpusManifestResponse: {
+            /** @description The manifest document. Every work in the Selection appears with a disposition — `delivered`, `undelivered`, or the name of its exclusion reason — because silent omission is a defect. A delivered entry additionally carries a content hash computed at capture, the licence asked for and the licence granted with its permission set, the captured licence document's path and hash, and what the Buyer was charged in micros. Cost columns are never in here. */
+            manifest: {
+                [key: string]: unknown;
+            };
+            /** @description A detached JWS (RFC 7515 with RFC 7797 `b64:false`) over the manifest's exact canonical bytes — a protected header, two dots and a signature. Detached so the manifest stays a plain readable file that a compliance tool can ingest without a crypto library. */
+            signature: string;
+            /** @description SHA-256 of the canonical manifest bytes, hex-encoded. */
+            digest: string;
+            /** @description Which key history entry to resolve. An index, never a credential — it is a 96-bit truncation, so a verifier matches on all 32 raw public-key bytes. */
+            signing_kid: string;
+            /** @description The head of the key history at signing time. A verifier checks that this digest appears somewhere in the chain being served — not that it equals the present head, since the history grows. What it catches is truncation or a fork since this manifest was issued, which needs no key at all, only control of the document. */
+            key_history_head_digest: string;
+            /**
+             * Format: date-time
+             * @description When the manifest was signed. Our own assertion until #989's RFC 3161 token lands, and the compromise rule is only as trustworthy as this field.
+             */
+            signed_at: string;
+            /** @description Where a verifier resolves `signing_kid`. */
+            key_history_url?: string;
+        };
+        /**
+         * @description The append-only, hash-chained log of every Ed25519 key that has signed an audit-export manifest. This is the trust anchor a verifier resolves a manifest's `kid` through.
+         *     It is a log of *events*, not a table of keys: there is no `valid_until` or `retired_reason` field. A key's window closes at the `valid_from` of the next `activate` entry, and it is compromised if a `revoke` entry names it. Those are derived by the reader, because an entry that could be edited after a later one chained to it would break the chain. See docs/audit-export-key-history.md.
+         */
+        SigningKeyHistoryResponse: {
+            /** @description Bumped when the document's shape changes in a way a reader must notice. */
+            schema_version: number;
+            /** @description Every entry, in chain order, starting at sequence 0. */
+            entries: {
+                /**
+                 * @description `activate` brings a key into service and carries `public_key` and `valid_from`. `revoke` records that the key named by `kid` was stolen and carries `compromised_at`.
+                 * @enum {string}
+                 */
+                kind: 'activate' | 'revoke';
+                /** @description base64url(SHA-256(raw public key))[0, 16]. An index into this document, never a credential — it is a 96-bit truncation, so a verifier matches on all 32 raw public-key bytes instead. */
+                kid: string;
+                /** @description Monotonic and gapless, starting at 0. */
+                sequence: number;
+                /** @description The raw 32-byte Ed25519 public key, base64url-encoded without padding. Present on `activate` entries only. */
+                public_key?: string;
+                /**
+                 * Format: date-time
+                 * @description When this key entered service. Present on `activate` entries only.
+                 */
+                valid_from?: string;
+                /**
+                 * Format: date-time
+                 * @description When the key named by `kid` is believed to have been stolen — ordinarily earlier than when it was discovered. Signatures dated before it stand; those at or after it are void. Present on `revoke` entries only.
+                 */
+                compromised_at?: string;
+                /** @description SHA-256 (hex) of the previous entry's RFC 8785 canonical JSON, including its signature. Absent on the root entry alone. */
+                previous_entry_digest?: string;
+                /** @description base64url Ed25519 signature over this entry's canonical JSON excluding this field, made by the key in service before it — which, for a `revoke`, is not the key it names. Absent on the root entry alone. */
+                signature?: string;
+            }[];
+        };
+        /** @description x402 v2 settlement result. Base64-encoded JSON returned in the `PAYMENT-RESPONSE` header on a successful `200`. `accessToken` is present when an RS256 signing key is configured; omitted in environments without credentials. */
+        SettlementResponse: {
+            /** @enum {boolean} */
+            success: true;
+            /** @description UUID of the settled Purchase record. */
+            transaction: string;
+            /** @enum {string} */
+            network: 'ledewire:v1';
+            /** @description UUID of the buying user. */
+            payer: string;
+            /** @description Short-lived RS256-signed JWT for offline entitlement verification. Verifiable via `/.well-known/x402-jwks.json`. Omitted if signing key is not configured. */
+            accessToken?: string | null;
+        };
+        MerchantPricingRule: {
+            /** @description UUID of the pricing rule. */
+            id: string;
+            /** @description UUID of the owning store. */
+            store_id: string;
+            /** @description Glob URL pattern (supports * and ** wildcards). Must start with http:// or https://. */
+            url_pattern: string;
+            /** @description Price in cents applied to content matching this pattern. */
+            price_cents: number;
+            /** @description Whether the rule is currently active. Inactive rules are ignored during URL matching. */
+            active: boolean;
+            /** Format: date-time */
+            created_at: string;
+            /** Format: date-time */
+            updated_at: string;
+        };
+        MerchantDomainVerification: {
+            /** @description UUID of the domain verification record. */
+            id: string;
+            /** @description UUID of the owning store. */
+            store_id: string;
+            /** @description The verified domain (www. prefix is stripped on creation). */
+            domain: string;
+            /**
+             * @description Verification status updated by DomainVerifyJob.
+             * @enum {string}
+             */
+            status: 'pending' | 'verified' | 'failed';
+            /** @description DNS TXT record name the merchant must add (e.g. _ledewire-verify.example.com). */
+            txt_record_name: string;
+            /** @description DNS TXT record value the merchant must set. */
+            txt_record_value: string;
+            /**
+             * Format: date-time
+             * @description Timestamp of successful verification. Null until verified.
+             */
+            verified_at?: string | null;
+            /**
+             * Format: date-time
+             * @description Timestamp of the most recent verification check (success or failure).
+             */
+            checked_at?: string | null;
+            /** Format: date-time */
+            created_at: string;
+        };
+        /** @description RFC 8414 Authorization Server Metadata. MCP clients fetch this to discover the authorization flow. `registration_endpoint` is what tells a client that Dynamic Client Registration is available at all — without it, clients that do not speak CIMD fall back to asking a human for a client id. */
+        OauthAuthorizationServerMetadata: {
+            issuer: string;
+            authorization_endpoint: string;
+            token_endpoint: string;
+            revocation_endpoint?: string;
+            /** @description RFC 7591 Dynamic Client Registration endpoint. */
+            registration_endpoint: string;
+            scopes_supported: string[];
+            response_types_supported: string[];
+            code_challenge_methods_supported: string[];
+            client_id_metadata_document_supported?: boolean;
+            token_endpoint_auth_methods_supported?: string[];
+        };
+        /** @description RFC 7591 client metadata. Only `redirect_uris` is required; unrecognised members are ignored rather than rejected, so clients sending extensions this server does not implement still register successfully. */
+        OauthClientRegistrationRequest: {
+            /** @description Must be https, or http on a loopback host (`localhost`, `127.0.0.1`, `[::1]`). Fragments are not permitted. These become the allowlist for the issued client_id. */
+            redirect_uris: string[];
+            client_name?: string;
+            client_uri?: string;
+            logo_uri?: string;
+            tos_uri?: string;
+            policy_uri?: string;
+            contacts?: string[];
+            software_id?: string;
+            software_version?: string;
+            /** @description Space-delimited. Scopes this server does not support are filtered out, and the response omits `scope` entirely when none was requested — registration decides nothing about what a token later grants. */
+            scope?: string;
+            grant_types?: ('authorization_code' | 'refresh_token')[];
+            response_types?: 'code'[];
+            /**
+             * @description Optional, and may only be `none`. Registered clients are public — no client_secret is issued, and PKCE protects the code exchange.
+             * @enum {string}
+             */
+            token_endpoint_auth_method?: 'none';
+        };
+        /** @description RFC 7591 §3.2.1 client information response. Carries no `client_secret`: a registered client is public and authenticates at the token endpoint with PKCE alone. */
+        OauthClientRegistrationResponse: {
+            /** @description Server-assigned, opaque, `lwc_`-prefixed. Deliberately not a URL, so it is never mistaken for a Client ID Metadata Document. */
+            client_id: string;
+            /** @description Seconds since the Unix epoch. */
+            client_id_issued_at: number;
+            redirect_uris: string[];
+            /** @enum {string} */
+            token_endpoint_auth_method: 'none';
+            grant_types?: string[];
+            response_types?: string[];
+            scope?: string;
+            client_name?: string;
+            client_uri?: string;
+            logo_uri?: string;
+            tos_uri?: string;
+            policy_uri?: string;
+            contacts?: string[];
+            software_id?: string;
+            software_version?: string;
+        };
+        /** @description RFC 7591 §3.2.2 client registration error response. */
+        OauthClientRegistrationErrorResponse: {
+            /** @enum {string} */
+            error: 'invalid_redirect_uri' | 'invalid_client_metadata';
+            error_description?: string;
+        };
     };
     responses: never;
     parameters: never;
@@ -1346,6 +2404,37 @@ export declare type ContentResponse = components['schemas']['ContentResponse'];
 /** A piece of content with buyer access information. */
 export declare type ContentWithAccessResponse = components['schemas']['ContentWithAccessResponse'];
 
+/**
+ * The REST and x402 web-gate form of a daily-spend-cap refusal, returned with HTTP
+ * `402 Payment Required` by `POST /v1/purchases`, `GET /v1/x402/contents/{id}`, and
+ * acquisition authorization. This is the raw wire shape; the SDK throws it as
+ * {@link SpendCapReachedError} rather than handing back the JSON body directly.
+ */
+export declare type DailySpendCapReachedErrorBody = components['schemas']['DailySpendCapReachedError'];
+
+/**
+ * Machine-readable reason on an API error envelope, present on refusals that carry one.
+ * Branch on this rather than on `message`, which is prose and may be reworded.
+ *
+ * - `retrieval_failed` — transient; worth retrying.
+ * - `not_licensable` — report the work as undelivered.
+ * - `price_drifted` — re-quote before retrying.
+ * - `client_error` — ours to fix; must never be retried unchanged.
+ * - `insufficient_funds` — cleared by funding the wallet.
+ * - `daily_spend_cap_reached` — deliberately **not** cleared by funding the wallet; see
+ *   {@link SpendCapReachedError}.
+ */
+export declare type ErrorType = NonNullable<components['schemas']['ErrorResponse']['error']['type']>;
+
+/**
+ * Known {@link ErrorType} values, widened to accept any other string the API
+ * may introduce. `ErrorType` still drives editor autocomplete; a value the API
+ * emits that isn't (yet) in the spec's enum — e.g. `selection_too_large` on
+ * `POST /v1/acquisitions` — still type-checks and survives on {@link
+ * LedewireError.type} instead of being narrowed away.
+ */
+declare type ErrorTypeValue = ErrorType | (string & {});
+
 /**
  * Thrown when the authenticated user does not have permission
  * to perform the requested operation.
@@ -1397,7 +2486,8 @@ export declare type ContentWithAccessResponse = components['schemas']['ContentWi
  * ```
  */
 export declare class ForbiddenError extends LedewireError {
-    constructor(message: string, code?: number);
+    static readonly brand: string;
+    constructor(message: string, code?: number, type?: ErrorTypeValue, details?: Record<string, unknown>);
 }
 
 /**
@@ -1407,6 +2497,8 @@ export declare class ForbiddenError extends LedewireError {
  * - Injects `Authorization: Bearer <token>` headers automatically
  * - Maps HTTP error responses to typed `LedewireError` subclasses
  * - On receiving a 401, calls `onUnauthorized` once and retries the request
+ * - Per-request `{ auth: false }` (see {@link RequestOptions}) skips all of
+ *   the above for public endpoints
  *
  * This is an internal class - consumers should use the
  * package-level client factories (`init` / `createClient`) instead.
@@ -1420,8 +2512,9 @@ declare class HttpClient {
      * GET request with optional query parameters.
      * @param path - API path (e.g. `/v1/wallet/balance`)
      * @param params - Query string parameters. `undefined` values are omitted; numbers are coerced to strings.
+     * @param options - Per-request overrides. Pass `{ auth: false }` for public endpoints.
      */
-    get<T>(path: string, params?: Record<string, string | number | undefined>): Promise<T>;
+    get<T>(path: string, params?: Record<string, string | number | undefined>, options?: RequestOptions): Promise<T>;
     /**
      * POST request.
      * @param path - API path
@@ -1446,8 +2539,28 @@ declare class HttpClient {
      * @param path - API path
      */
     delete<T = void>(path: string): Promise<T>;
+    /**
+     * GET request that returns the raw, unparsed `Response` instead of decoded JSON.
+     * Used for binary downloads (e.g. `GET /v1/acquisitions/{id}/corpus/download`,
+     * which streams a gzip archive when the corpus is ready, or a JSON
+     * `CorpusResponse` body otherwise).
+     *
+     * Applies the same `Authorization` header injection and single-retry-on-401
+     * behaviour as {@link HttpClient.get}, and maps a non-2xx response to the same
+     * typed errors — it just skips the `response.json()` decode step so the caller
+     * can read the body as a stream, blob, or array buffer.
+     *
+     * @param path - API path (e.g. `/v1/acquisitions/{id}/corpus/download`)
+     * @returns The raw `Response`. Callers are responsible for reading its body.
+     */
+    getRaw(path: string): Promise<Response>;
     private buildUrl;
     private request;
+    /**
+     * Shared auth-injection, single-401-retry, and error-mapping logic behind both
+     * `request()` (JSON in, JSON out) and `getRaw()` (JSON in, raw `Response` out).
+     */
+    private performRequest;
     private throwApiError;
 }
 
@@ -1496,6 +2609,11 @@ export declare function init(config: BrowserClientConfig): BrowserClient;
  * All errors thrown by the SDK are instances of this class,
  * making it safe to use `err instanceof LedewireError` as a type guard.
  *
+ * `instanceof` works even when `err` was constructed by a different bundled
+ * copy of this class — e.g. an error thrown by `@ledewire/x402-client`
+ * checked with the `SpendCapReachedError` bundled into `@ledewire/node`. See
+ * {@link LedewireError[Symbol.hasInstance]}.
+ *
  * @example
  * ```ts
  * try {
@@ -1508,11 +2626,48 @@ export declare function init(config: BrowserClientConfig): BrowserClient;
  * ```
  */
 export declare class LedewireError extends Error {
+    /**
+     * Class-identity brand used for cross-bundle `instanceof` (see {@link
+     * LedewireError[Symbol.hasInstance]}). Hardcoded per class — never derived
+     * from `constructor.name` or `this.name`, either of which a minifier can
+     * rewrite, silently breaking the brand match.
+     */
+    static readonly brand: string;
     /** HTTP status code returned by the API (e.g. 400, 401, 404, 422). */
     readonly statusCode: number;
     /** Machine-readable error code from the API error body, if present. */
     readonly code: number | undefined;
-    constructor(message: string, statusCode: number, code?: number);
+    /**
+     * Machine-readable reason from the API error body's `error.type`, if present.
+     * See {@link ErrorType} for the documented values and how to branch on them —
+     * the API may emit other values it hasn't documented yet, which still land
+     * here as a plain string rather than being dropped.
+     */
+    readonly type: ErrorTypeValue | undefined;
+    /**
+     * Extra top-level fields from the API error response body, excluding
+     * `error` itself. For example, a `selection_too_large` refusal from `POST
+     * /v1/acquisitions` (422) carries `maximum` and `submitted` alongside
+     * `error`. `undefined` when the body carried no other top-level fields,
+     * which is the common case.
+     */
+    readonly details: Readonly<Record<string, unknown>> | undefined;
+    constructor(message: string, statusCode: number, code?: number, type?: ErrorTypeValue, details?: Record<string, unknown>);
+    /**
+     * Makes `err instanceof LedewireError` (and every subclass below) true even
+     * when `err` was constructed by a *different* bundled copy of this module.
+     * Each published package (`@ledewire/node`, `@ledewire/browser`,
+     * `@ledewire/x402-client`) bundles its own copy of `@ledewire/core` via
+     * tsup, so the classes are distinct objects with unrelated prototypes —
+     * the plain prototype-chain check `instanceof` normally does would fail.
+     *
+     * Falls back to the brand list every instance carries under a
+     * `Symbol.for('@ledewire/error-brands')` key (collected from the `brand`
+     * static along the constructing class's prototype chain): true when the
+     * ordinary check passes, OR the instance's brand list includes this
+     * class's own `brand`.
+     */
+    static [Symbol.hasInstance](instance: unknown): boolean;
 }
 
 /**
@@ -1541,6 +2696,18 @@ export declare class LedewireError extends Error {
  */
 export declare function localStorageAdapter(key?: string): TokenStorage;
 
+/** An MCP API key record (secret is never included after creation). */
+export declare type McpApiKey = components['schemas']['McpApiKey'];
+
+/** Request body for creating a new MCP API key. */
+export declare type McpApiKeyCreateRequest = components['schemas']['McpApiKeyCreateRequest'];
+
+/**
+ * Response returned once when an MCP API key is created.
+ * The `secret` is shown exactly once and cannot be retrieved again.
+ */
+export declare type McpApiKeyCreateResponse = components['schemas']['McpApiKeyCreateResponse'];
+
 /**
  * In-memory token storage (default for both packages).
  * Tokens are cleared when the page unloads or the process exits.
@@ -1560,7 +2727,8 @@ export declare type NextRequiredAction = ContentAccessInfo['next_required_action
  * Thrown when the requested resource does not exist.
  */
 export declare class NotFoundError extends LedewireError {
-    constructor(message: string, code?: number);
+    static readonly brand: string;
+    constructor(message: string, code?: number, type?: ErrorTypeValue, details?: Record<string, unknown>);
 }
 
 /**
@@ -1602,12 +2770,26 @@ export declare type PurchaseCreateRequest = components['schemas']['PurchaseCreat
  * failure, such as a price mismatch or a duplicate purchase.
  */
 export declare class PurchaseError extends LedewireError {
-    constructor(message: string, statusCode: number, code?: number);
+    static readonly brand: string;
+    constructor(message: string, statusCode: number, code?: number, type?: ErrorTypeValue, details?: Record<string, unknown>);
 }
 
 /** A purchase record. */
 export declare type PurchaseResponse = components['schemas']['PurchaseResponse'];
 
+/**
+ * Per-request overrides accepted by {@link HttpClient} methods.
+ */
+declare interface RequestOptions {
+    /**
+     * Whether to attach authentication to this request. Defaults to `true`.
+     * Pass `false` for public endpoints: skips `getAccessToken`, sends no
+     * `Authorization` header, and maps a `401` straight to an {@link AuthError}
+     * without invoking `onUnauthorized`.
+     */
+    auth?: boolean;
+}
+
 /**
  * Search criteria for seller content search.
  * At least one field must be supplied. All supplied fields must match (AND logic).
@@ -1656,6 +2838,59 @@ export declare interface SellerContentSearchRequest {
  */
 export declare function sessionStorageAdapter(key?: string): TokenStorage;
 
+/**
+ * Thrown when the buyer's daily spend cap has been reached. Returned as HTTP `402`
+ * by `POST /v1/purchases`, `GET /v1/x402/contents/{id}`, and acquisition
+ * authorization, whenever the API error body's `error.type` is
+ * `'daily_spend_cap_reached'`.
+ *
+ * **Funding the wallet does not clear this.** Unlike a plain `insufficient_funds`
+ * 402 — where adding money to the wallet is enough to retry — a spend cap refusal
+ * is a daily policy limit on the buyer's account (every new buyer starts with a
+ * default cap). It clears only when the spend window rolls over at {@link
+ * SpendCapReachedError.resetsAt}, or when the buyer raises or removes the cap via
+ * `user.spendCap.update()`.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await client.purchases.create({ content_id })
+ * } catch (err) {
+ *   if (err instanceof SpendCapReachedError) {
+ *     // Do NOT prompt the buyer to fund their wallet — that won't help.
+ *     console.error(
+ *       `Spend cap reached: spent ${err.spentCents} of ${err.capCents} cents. ` +
+ *         `Resets at ${err.resetsAt}.`,
+ *     )
+ *   }
+ * }
+ * ```
+ */
+export declare class SpendCapReachedError extends LedewireError {
+    static readonly brand: string;
+    /** The buyer's daily spend cap in cents. */
+    readonly capCents: number;
+    /** Total spent so far in the current spend window. */
+    readonly spentCents: number;
+    /** Cap minus spend so far, floored at zero — what the buyer may still spend in this window. */
+    readonly remainingCents: number;
+    /** ISO 8601 timestamp (UTC) of the instant the current spend window rolls. */
+    readonly resetsAt: string;
+    /**
+     * Whether this buyer's bulk acquisitions are exempt from the cap. When `true`,
+     * `spentCents` and `remainingCents` describe ordinary spend only — an authorized
+     * bulk acquisition does not consume them.
+     */
+    readonly bulkExempt: boolean;
+    constructor(message: string, capInfo: {
+        capCents: number;
+        spentCents: number;
+        remainingCents: number;
+        resetsAt: string;
+        bulkExempt: boolean;
+    }, code?: number);
+}
+
 /** Internal representation of stored authentication tokens. */
 export declare interface StoredTokens {
     accessToken: string;
@@ -1765,6 +3000,271 @@ export declare interface TokenStorage {
     clearTokens(): void | Promise<void>;
 }
 
+/** A buyer API key record (secret is never included after creation). */
+declare type UserApiKey = components['schemas']['UserApiKey'];
+
+/** Request body for creating a new buyer API key. */
+declare type UserApiKeyCreateRequest = components['schemas']['UserApiKeyCreateRequest'];
+
+/**
+ * Response returned once when a buyer API key is created.
+ * The `secret` is shown exactly once and cannot be retrieved again.
+ * Store it immediately in a secrets manager.
+ */
+declare type UserApiKeyCreateResponse = components['schemas']['UserApiKeyCreateResponse'];
+
+/**
+ * Manage buyer API keys for the authenticated user.
+ *
+ * Buyer API keys are the authentication credential for autonomous agents — they
+ * allow an agent to obtain a buyer JWT via `auth.loginWithBuyerApiKey()` without
+ * requiring a username and password. Each key is named, independently revocable,
+ * and can carry an optional `spending_limit_cents` ceiling.
+ *
+ * **Secret handling:** `create()` returns the `secret` exactly once. It is never
+ * retrievable again after the response is received — store it immediately in a
+ * secrets manager (e.g. environment variable, Vault, AWS Secrets Manager).
+ *
+ * Obtain via `client.user.apiKeys` — do not construct directly.
+ *
+ * @example
+ * ```ts
+ * // Create a key for an agent, with a $10 spend ceiling
+ * const { key, secret } = await client.user.apiKeys.create({
+ *   name: 'my-rag-agent',
+ *   spending_limit_cents: 1000,
+ * })
+ * // Store secret immediately — it cannot be retrieved again
+ * await secretsManager.put('LEDEWIRE_BUYER_SECRET', secret)
+ *
+ * // List all keys (secrets never included)
+ * const keys = await client.user.apiKeys.list()
+ *
+ * // Revoke a compromised key
+ * await client.user.apiKeys.revoke(keys[0].id)
+ * ```
+ */
+declare class UserApiKeysNamespace {
+    private readonly http;
+    /* Excluded from this release type: __constructor */
+    /**
+     * Returns all buyer API keys for the authenticated user.
+     * The `secret` is never included in list responses.
+     *
+     * @returns Array of API key records.
+     */
+    list(): Promise<UserApiKey[]>;
+    /**
+     * Creates a new buyer API key.
+     *
+     * The `secret` in the response is shown exactly once and cannot be retrieved
+     * again. Store it immediately in a secrets manager before discarding the
+     * response object.
+     *
+     * @param body - Name and optional spend ceiling for the new key.
+     * @returns The new key's public identifier and one-time secret.
+     *
+     * @example
+     * ```ts
+     * const { key, secret } = await client.user.apiKeys.create({
+     *   name: 'production-agent',
+     *   spending_limit_cents: 5000, // $50 cap
+     * })
+     * // ⚠️ Store secret NOW — it is shown once only
+     * process.env.LEDEWIRE_BUYER_SECRET = secret
+     * ```
+     */
+    create(body: UserApiKeyCreateRequest): Promise<UserApiKeyCreateResponse>;
+    /**
+     * Revokes (permanently deletes) a buyer API key by ID.
+     *
+     * Any agent currently using this key will receive `401` on its next
+     * token refresh. Revocation takes effect immediately.
+     *
+     * @param id - UUID of the API key to revoke.
+     */
+    revoke(id: string): Promise<void>;
+}
+
+/**
+ * Manage the authenticated buyer's MCP API keys.
+ *
+ * MCP API keys authenticate agent requests against the Ledewire MCP server, sent
+ * as `Authorization: Bearer <key>:<secret>`. Each key carries an explicit set of
+ * scopes — `can_search` (default `true`), `can_purchase` (default `false`), and
+ * the seller-tier `can_manage_content` / `can_read_analytics`, which additionally
+ * require `store_id` to be set to a store the user owns or authors.
+ *
+ * **Secret handling:** `create()` returns the `secret` exactly once. It is never
+ * retrievable again — store it immediately, alongside the `key`, in a secrets
+ * manager.
+ *
+ * **Changing permissions:** scopes are fixed at creation. To change what a key
+ * can do, revoke it and create a replacement with the desired scopes.
+ *
+ * Obtain via `client.user.mcpKeys` — do not construct directly.
+ *
+ * @example
+ * ```ts
+ * // Create a search+purchase key for an autonomous agent
+ * const { key, secret } = await client.user.mcpKeys.create({
+ *   label: 'my-rag-agent',
+ *   can_search: true,
+ *   can_purchase: true,
+ * })
+ * // Store immediately — the secret cannot be retrieved again
+ * await secretsManager.put('LEDEWIRE_MCP_CREDENTIAL', `${key}:${secret}`)
+ *
+ * // List all keys (secrets never included)
+ * const keys = await client.user.mcpKeys.list()
+ *
+ * // To change permissions: revoke and recreate
+ * await client.user.mcpKeys.revoke(keys[0].id)
+ * ```
+ */
+declare class UserMcpKeysNamespace {
+    private readonly http;
+    /* Excluded from this release type: __constructor */
+    /**
+     * Returns all MCP API keys for the authenticated user.
+     * The `secret` is never included in list responses.
+     *
+     * @returns Array of MCP API key records.
+     */
+    list(): Promise<McpApiKey[]>;
+    /**
+     * Creates a new MCP API key.
+     *
+     * The `secret` in the response is shown exactly once and cannot be retrieved
+     * again. Store it immediately alongside `key` — the pair is used together as
+     * `Authorization: Bearer <key>:<secret>` against the Ledewire MCP server.
+     *
+     * @param body - Label and scopes for the new key.
+     * @returns The new key's public identifier, scopes, and one-time secret.
+     *
+     * @example
+     * ```ts
+     * const { key, secret } = await client.user.mcpKeys.create({
+     *   label: 'production-agent',
+     *   can_search: true,
+     *   can_purchase: true,
+     * })
+     * ```
+     */
+    create(body: McpApiKeyCreateRequest): Promise<McpApiKeyCreateResponse>;
+    /**
+     * Revokes (permanently deletes) an MCP API key by ID.
+     *
+     * To change a key's permissions, revoke it and create a replacement with the
+     * desired scopes — scopes cannot be edited in place.
+     *
+     * @param id - UUID of the MCP API key to revoke.
+     */
+    revoke(id: string): Promise<void>;
+}
+
+/**
+ * Authenticated buyer account operations.
+ *
+ * Obtain via `client.user` — do not construct directly.
+ */
+declare class UserNamespace {
+    /**
+     * Buyer API key management: create, list, and revoke named API keys.
+     * Keys are used by autonomous agents to authenticate without a username/password.
+     */
+    readonly apiKeys: UserApiKeysNamespace;
+    /**
+     * The authenticated buyer's daily spend cap: read and update the ceiling that
+     * governs every wallet debit (MCP, REST, and the web payment gate).
+     */
+    readonly spendCap: UserSpendCapNamespace;
+    /**
+     * MCP API key management: create, list, and revoke keys scoped for use against
+     * the Ledewire MCP server.
+     */
+    readonly mcpKeys: UserMcpKeysNamespace;
+    /* Excluded from this release type: __constructor */
+}
+
+/**
+ * The authenticated buyer's daily spend cap, read against the current spend window.
+ * The cap governs every wallet debit the buyer makes — MCP, REST, or the web payment
+ * gate — and spend is derived from completed purchases, so a refund returns allowance.
+ *
+ * `cap_cents`, `spent_cents`, `remaining_cents` and `resets_at` are spelled exactly as
+ * they are in {@link DailySpendCapReachedErrorBody}, so a refusal and this resource
+ * describe the same numbers.
+ */
+export declare type UserSpendCap = components['schemas']['UserSpendCap'];
+
+/**
+ * Manage the authenticated buyer's daily spend cap.
+ *
+ * Every new buyer starts with a default cap, so `null` on {@link
+ * UserSpendCapNamespace.update} is the only way to become uncapped — there is no
+ * separate "remove the cap" call. While capped, `cap_cents` and `remaining_cents`
+ * are numbers; once uncapped, both read back as `null` because there is no ceiling
+ * to report or subtract from.
+ *
+ * The cap governs every wallet debit the buyer makes — MCP, REST, or the web
+ * payment gate — over a rolling window bounded by `spend_window_timezone` (an IANA
+ * zone, UTC by default) and reset at `resets_at`. `bulk_exempt` says whether this
+ * buyer's bulk acquisitions are excluded from that spend, in which case
+ * `spent_cents` / `remaining_cents` describe ordinary purchases only.
+ *
+ * **Exceeding the cap throws {@link SpendCapReachedError}** (HTTP 402) from
+ * `client.purchases.create()` and the x402 content gate. Funding the wallet does not
+ * clear it — the buyer must wait for the window to roll at `resets_at`, or the cap
+ * must be raised or cleared here.
+ *
+ * Obtain via `client.user.spendCap` — do not construct directly.
+ *
+ * @example
+ * ```ts
+ * const cap = await client.user.spendCap.get()
+ * if (cap.remaining_cents !== null && cap.remaining_cents < 500) {
+ *   console.warn(`Only ${cap.remaining_cents}c left before the cap resets at ${cap.resets_at}`)
+ * }
+ *
+ * // Raise the cap to $20/day
+ * await client.user.spendCap.update({ daily_spend_limit_cents: 2000 })
+ *
+ * // Remove the cap entirely (become uncapped)
+ * await client.user.spendCap.update({ daily_spend_limit_cents: null })
+ * ```
+ */
+declare class UserSpendCapNamespace {
+    private readonly http;
+    /* Excluded from this release type: __constructor */
+    /**
+     * Returns the authenticated buyer's spend cap, read against the current spend
+     * window.
+     *
+     * @returns The current spend cap, spend-to-date, and reset time.
+     */
+    get(): Promise<UserSpendCap>;
+    /**
+     * Sets or clears the authenticated buyer's daily spend cap.
+     *
+     * `daily_spend_limit_cents` is required and nullable: pass a number to set the
+     * cap, or `null` to remove it (the only way to become uncapped). A cap set below
+     * spend already made in the current window is accepted — it just leaves
+     * `remaining_cents` at zero until the window rolls.
+     *
+     * @param body - The new cap in whole cents, or `null` to remove it.
+     * @returns The updated spend cap.
+     */
+    update(body: UserSpendCapUpdateRequest): Promise<UserSpendCap>;
+}
+
+/**
+ * Request body for `PATCH /v1/user/spend-cap`. `daily_spend_limit_cents` is required
+ * and nullable: `null` is how a buyer becomes uncapped, and an omitted field is a
+ * client error rather than a request to be uncapped.
+ */
+export declare type UserSpendCapUpdateRequest = components['schemas']['UserSpendCapUpdateRequest'];
+
 /** Current wallet balance for the authenticated buyer. */
 export declare type WalletBalanceResponse = components['schemas']['WalletBalanceResponse'];