@ledewire/browser 0.6.1 → 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.
      *
@@ -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;
@@ -1765,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'];