@ledewire/browser 0.6.0 → 0.7.0

package/dist/index.d.ts

@@ -50,6 +50,9 @@ export declare class AuthError extends LedewireError {
 /** 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 +133,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.
      *
@@ -175,9 +198,9 @@ declare class BrowserAuthNamespace {
  * Instantiate with {@link init} rather than constructing directly.
  */
 declare class BrowserClient {
-    readonly _http: HttpClient;
-    readonly _tokenManager: TokenManager;
-    readonly _config: BrowserClientConfig;
+    private readonly _http;
+    private readonly _tokenManager;
+    private readonly _config;
     /** Platform-level public configuration (no auth required) */
     readonly config: BrowserConfigNamespace;
     /** Buyer authentication: email/password signup/login, Google OAuth, password reset */
@@ -192,6 +215,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 */
 }
 
@@ -646,6 +671,40 @@ 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;
+        };
         AuthTokenRefreshRequest: {
             refresh_token?: string;
         };
@@ -789,7 +848,7 @@ declare interface components {
             title?: string;
             /**
              * Format: byte
-             * @description Full article body in markdown, base64 encoded. For `markdown` content only.
+             * @description Full article body in markdown, base64 encoded. For `markdown` content only. Must be base64-encoded before sending (e.g. `btoa(markdownText)`).
              */
             content_body?: string;
             /**
@@ -804,7 +863,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) */
@@ -1036,7 +1095,7 @@ declare interface components {
             title: string;
             /**
              * Format: byte
-             * @description Full article body in markdown, base64 encoded. Required when `content_type` is `markdown`.
+             * @description Full article body in markdown, base64 encoded. Required when `content_type` is `markdown`. Must be base64-encoded before sending (e.g. `btoa(markdownText)`).
              */
             content_body?: string;
             /**
@@ -1051,7 +1110,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. */
@@ -1083,7 +1142,7 @@ declare interface components {
             title: string;
             /**
              * Format: byte
-             * @description Full article body in markdown, base64 encoded. Present when `content_type` is `markdown`.
+             * @description Full article body in markdown, base64 encoded. Present when `content_type` is `markdown`. Must be base64-decoded before rendering (e.g. `atob(content.content_body ?? '')`).
              */
             content_body?: string | null;
             /**
@@ -1096,9 +1155,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. */
@@ -1194,7 +1255,7 @@ declare interface components {
             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,6 +1266,8 @@ 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.
@@ -1329,6 +1392,126 @@ declare interface components {
                 };
             };
         };
+        /** @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`; `content_uri` is present when `content_type` is `external_ref`. `purchase_id` is the UUID of the settled Purchase record (null for free content). */
+        X402ContentResponse: {
+            id: string;
+            /** @enum {string} */
+            content_type: 'markdown' | 'external_ref';
+            title: string;
+            price_cents: number;
+            /** Format: byte */
+            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;
+            /**
+             * Format: byte
+             * @description Full article body in markdown. Present when content_type is markdown.
+             */
+            content_body?: string | null;
+            /** @description URI of the external resource. Present when content_type is external_ref. */
+            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 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;
+        };
     };
     responses: never;
     parameters: never;
@@ -1419,15 +1602,16 @@ declare class HttpClient {
     /**
      * GET request with optional query parameters.
      * @param path - API path (e.g. `/v1/wallet/balance`)
-     * @param params - Query string parameters
+     * @param params - Query string parameters. `undefined` values are omitted; numbers are coerced to strings.
      */
-    get<T>(path: string, params?: Record<string, string>): Promise<T>;
+    get<T>(path: string, params?: Record<string, string | number | undefined>): Promise<T>;
     /**
      * POST request.
      * @param path - API path
      * @param body - Request body (JSON-serialized)
+     * @param params - Optional query string parameters. `undefined` values are omitted; numbers are coerced to strings.
      */
-    post<T>(path: string, body?: unknown): Promise<T>;
+    post<T>(path: string, body?: unknown, params?: Record<string, string | number | undefined>): Promise<T>;
     /**
      * PUT request.
      * @param path - API path
@@ -1562,6 +1746,21 @@ export declare class NotFoundError extends LedewireError {
     constructor(message: string, code?: number);
 }
 
+/**
+ * Pagination parameters accepted by paginated list endpoints.
+ *
+ * Pass as the final argument to any `list()` or `search()` method that
+ * accepts optional pagination. Omitting either field defers to the server
+ * default (page 1, 25 items per page).
+ */
+export declare interface PaginationParams {
+    /** Page number (1-based). Defaults to 1. */
+    page?: number;
+    /** Items per page. Maximum 100. Defaults to 25. */
+    per_page?: number;
+    [key: string]: number | undefined;
+}
+
 /**
  * Converts an `expires_at` ISO 8601 string from an API auth response
  * into a Unix timestamp (milliseconds) for use in `StoredTokens.expiresAt`.
@@ -1749,6 +1948,106 @@ 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>;
+}
+
+/**
+ * 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;
+    /* Excluded from this release type: __constructor */
+}
+
 /** Current wallet balance for the authenticated buyer. */
 export declare type WalletBalanceResponse = components['schemas']['WalletBalanceResponse'];