@ledewire/browser 0.2.1 → 0.2.2

package/dist/index.d.ts

@@ -1,33 +1,1344 @@
-/**
- * @ledewire/browser
- *
- * LedeWire SDK for browser environments.
- * Enables buyer authentication, content checkout, wallet funding,
- * and purchases — embeddable with a single `<script>` tag.
- *
- * **CDN usage (no build step required):**
- * ```html
- * <script src="https://cdn.jsdelivr.net/npm/@ledewire/browser@1/dist/ledewire.min.js"></script>
- * <script>
- *   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'
- * </script>
- * ```
- *
- * **npm / bundler usage:**
- * ```ts
- * import { init } from '@ledewire/browser'
- * const lw = init({ apiKey: 'your_api_key' })
- * ```
- *
- * @see {@link https://docs.ledewire.org} for guides and examples
- * @packageDocumentation
- */
-export type { AuthenticationResponse, CheckoutNextAction, CheckoutState, CheckoutStateResponse, ContentAccessInfo, ContentWithAccessResponse, NextRequiredAction, PurchaseCreateRequest, PurchaseResponse, StoredTokens, TokenStorage, WalletBalanceResponse, WalletPaymentSessionRequest, WalletPaymentSessionResponse, WalletPaymentStatusResponse, WalletTransactionItem, } from '@ledewire/core';
-export { AuthError, ForbiddenError, LedewireError, MemoryTokenStorage, NotFoundError, PurchaseError, parseExpiresAt, } from '@ledewire/core';
-export { init } from './client.js';
-export type { BrowserClientConfig } from './client.js';
-export { localStorageAdapter } from './local-storage-adapter.js';
-//# sourceMappingURL=index.d.ts.map
+/**
+ * @ledewire/browser
+ *
+ * LedeWire SDK for browser environments.
+ * Enables buyer authentication, content checkout, wallet funding,
+ * and purchases — embeddable with a single `<script>` tag.
+ *
+ * **CDN usage (no build step required):**
+ * ```html
+ * <script src="https://cdn.jsdelivr.net/npm/@ledewire/browser@1/dist/ledewire.min.js"></script>
+ * <script>
+ *   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'
+ * </script>
+ * ```
+ *
+ * **npm / bundler usage:**
+ * ```ts
+ * import { init } from '@ledewire/browser'
+ * const lw = init({ apiKey: 'your_api_key' })
+ * ```
+ *
+ * @see {@link https://docs.ledewire.org} for guides and examples
+ * @packageDocumentation
+ */
+
+/**
+ * Core TypeScript types for the LedeWire SDK.
+ *
+ * API shape types are generated from `ledewire.yml`
+ * (run `pnpm --filter @ledewire/core generate:types` to regenerate).
+ * SDK-internal types (token storage, stored tokens) are hand-written below.
+ *
+ * @module
+ */
+
+/** JWT bearer token response returned by all buyer authentication endpoints. */
+export declare type AuthenticationResponse = components['schemas']['AuthenticationResponse'];
+
+/**
+ * Thrown when the request lacks valid authentication credentials,
+ * or when a token refresh fails and re-authentication is required.
+ */
+export declare class AuthError extends LedewireError {
+    constructor(message: string, code?: number);
+}
+
+/** Request body for buyer email/password login. */
+declare type AuthLoginEmailRequest = components['schemas']['AuthLoginEmailRequest'];
+
+/** Request body for buyer Google OAuth login. */
+declare type AuthLoginOAuthRequest = components['schemas']['AuthLoginOAuthRequest'];
+
+/** Request body for buyer email/password signup. */
+declare type AuthSignupRequest = components['schemas']['AuthSignupRequest'];
+
+/**
+ * Buyer authentication: signup, email/password login, Google OAuth.
+ *
+ * Obtain via `lw.auth` — do not construct directly.
+ *
+ * @example
+ * ```ts
+ * const lw = Ledewire.init({ apiKey: 'your_api_key' })
+ * await lw.auth.loginWithEmail({ email: 'u@example.com', password: 'pw' })
+ * ```
+ */
+declare class BrowserAuthNamespace {
+    private readonly http;
+    private readonly tokenManager;
+    /* Excluded from this release type: __constructor */
+    /**
+     * Register a new buyer account with email and password.
+     * Tokens are stored automatically after successful signup.
+     *
+     * @param body - Signup credentials and display name.
+     * @returns The authentication token response.
+     */
+    signup(body: AuthSignupRequest): Promise<AuthenticationResponse>;
+    /**
+     * Log in with email and password.
+     * Tokens are stored automatically after successful login.
+     *
+     * @param body - Email and password credentials.
+     * @returns The authentication token response.
+     */
+    loginWithEmail(body: AuthLoginEmailRequest): Promise<AuthenticationResponse>;
+    /**
+     * Log in with a Google ID token obtained from the Google OAuth flow.
+     * Tokens are stored automatically after successful login.
+     *
+     * @param body - The Google ID token.
+     * @returns The authentication token response.
+     */
+    loginWithGoogle(body: AuthLoginOAuthRequest): Promise<AuthenticationResponse>;
+    private storeTokens;
+}
+
+/**
+ * The LedeWire browser client.
+ * Access buyer flows through the namespaced properties.
+ *
+ * @remarks
+ * Instantiate with {@link init} rather than constructing directly.
+ */
+declare class BrowserClient {
+    readonly _http: HttpClient;
+    readonly _tokenManager: TokenManager;
+    readonly _config: BrowserClientConfig;
+    /** Buyer authentication: email/password signup/login, Google, password reset */
+    readonly auth: BrowserAuthNamespace;
+    /** Checkout state machine: determines next action for a piece of content */
+    readonly checkout: CheckoutNamespace;
+    /** Wallet: balance, fund via payment session, transaction history */
+    readonly wallet: BrowserWalletNamespace;
+    /** Content purchases for the authenticated buyer */
+    readonly purchases: BrowserPurchasesNamespace;
+    /** Public content with per-user access information */
+    readonly content: BrowserContentNamespace;
+    /* Excluded from this release type: __constructor */
+}
+
+/**
+ * Configuration options for the LedeWire browser client.
+ */
+export declare interface BrowserClientConfig {
+    /**
+     * LedeWire API key that identifies the store.
+     * Obtained from the LedeWire merchant dashboard.
+     */
+    apiKey: string;
+    /**
+     * Override the API base URL.
+     * Defaults to `https://api.ledewire.com`.
+     */
+    baseUrl?: string;
+    /**
+     * Token storage adapter.
+     * Defaults to {@link MemoryTokenStorage} (in-memory, most secure).
+     *
+     * To persist sessions across page reloads, use the built-in
+     * `localStorageAdapter`:
+     * ```ts
+     * import { init, localStorageAdapter } from '@ledewire/browser'
+     * const lw = init({ apiKey: '...', storage: localStorageAdapter() })
+     * ```
+     */
+    storage?: TokenStorage;
+    /**
+     * Called when the user's session expires and cannot be refreshed.
+     * Use this to show a re-authentication prompt.
+     *
+     * @example
+     * ```ts
+     * onAuthExpired: () => showLoginModal()
+     * ```
+     */
+    onAuthExpired?: () => void;
+}
+
+/**
+ * Buyer content namespace — fetch content with real-time access information.
+ *
+ * Obtain via `lw.content` — do not construct directly.
+ *
+ * @example
+ * ```ts
+ * const { content, access } = await lw.content.getWithAccess('content-id')
+ * if (access.has_access) showFullContent(content)
+ * ```
+ */
+declare class BrowserContentNamespace {
+    protected readonly http: HttpClient;
+    constructor(http: HttpClient);
+    /**
+     * Returns a content item together with access information for the
+     * authenticated buyer (or a generic access response when unauthenticated).
+     *
+     * @param id - The content ID.
+     * @param userId - Optional user ID to check a specific user's access status.
+     * @returns The content item with access information.
+     */
+    getWithAccess(id: string, userId?: string): Promise<ContentWithAccessResponse>;
+}
+
+/**
+ * Buyer purchases namespace — create and retrieve content purchases.
+ *
+ * Obtain via `lw.purchases` — do not construct directly.
+ *
+ * @example
+ * ```ts
+ * await lw.purchases.create({ content_id: 'content-id' })
+ * const all = await lw.purchases.list()
+ * ```
+ */
+declare class BrowserPurchasesNamespace {
+    protected readonly http: HttpClient;
+    constructor(http: HttpClient);
+    /**
+     * Completes a content purchase using the buyer's wallet balance.
+     *
+     * @param body - The content ID and expected price in cents.
+     * @returns The completed purchase record.
+     */
+    create(body: PurchaseCreateRequest): Promise<PurchaseResponse>;
+    /**
+     * Returns all purchases made by the authenticated buyer.
+     *
+     * @returns A list of purchase records, newest first.
+     */
+    list(): Promise<PurchaseResponse[]>;
+    /**
+     * Returns a single purchase by ID.
+     *
+     * @param id - The purchase ID.
+     * @returns The purchase record.
+     */
+    get(id: string): Promise<PurchaseResponse>;
+}
+
+/**
+ * Buyer wallet namespace — balance, transactions, and payment session management.
+ *
+ * Obtain via `lw.wallet` — do not construct directly.
+ *
+ * @example
+ * ```ts
+ * const { balance_cents } = await lw.wallet.balance()
+ * const session = await lw.wallet.createPaymentSession({ amount_cents: 500 })
+ * ```
+ */
+declare class BrowserWalletNamespace {
+    protected readonly http: HttpClient;
+    constructor(http: HttpClient);
+    /**
+     * Returns the authenticated buyer's current wallet balance.
+     *
+     * @returns The current wallet balance in cents.
+     */
+    balance(): Promise<WalletBalanceResponse>;
+    /**
+     * Returns the authenticated buyer's wallet transaction history, newest first.
+     *
+     * @returns A list of completed wallet transaction entries.
+     */
+    transactions(): Promise<WalletTransactionItem[]>;
+    /**
+     * Creates a payment session for funding the buyer's wallet.
+     *
+     * @param body - The amount and currency to fund.
+     * @returns Payment session details for use with the payment provider widget.
+     */
+    createPaymentSession(body: WalletPaymentSessionRequest): Promise<WalletPaymentSessionResponse>;
+    /**
+     * Polls the status of a wallet funding payment session.
+     *
+     * @param sessionId - The session ID returned by `createPaymentSession`.
+     * @returns The current payment status.
+     */
+    getPaymentStatus(sessionId: string): Promise<WalletPaymentStatusResponse>;
+}
+
+/**
+ * Checkout namespace — buyer checkout state for a specific content item.
+ *
+ * Obtain via `lw.checkout` — do not construct directly.
+ *
+ * @example
+ * ```ts
+ * const state = await lw.checkout.state('content-id')
+ * // state.checkout_state.next_required_action:
+ * // 'authenticate' | 'fund_wallet' | 'purchase' | 'view_content'
+ * ```
+ */
+declare class CheckoutNamespace {
+    protected readonly http: HttpClient;
+    constructor(http: HttpClient);
+    /**
+     * Returns the authenticated buyer's checkout readiness for a given piece of
+     * content. Indicates whether the buyer needs to authenticate, fund their
+     * wallet, or purchase before accessing the content.
+     *
+     * Works without authentication — returns anonymous checkout state when the
+     * buyer is not logged in.
+     *
+     * @param contentId - The content item ID.
+     * @returns The checkout state, including what action is required next.
+     */
+    state(contentId: string): Promise<CheckoutStateResponse>;
+}
+
+/**
+ * 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).
+ */
+export declare type CheckoutNextAction = 'authenticate' | 'fund_wallet' | 'purchase' | 'view_content';
+
+/** Checkout state machine result for a specific content item. */
+export declare interface CheckoutState {
+    content_id: string;
+    checkout_state: {
+        is_authenticated: boolean;
+        has_sufficient_funds: boolean;
+        has_purchased: boolean;
+        next_required_action: CheckoutNextAction;
+    };
+}
+
+/** Full checkout state for a buyer/content pair, including auth and fund status. */
+export declare type CheckoutStateResponse = components['schemas']['CheckoutStateResponse'];
+
+declare interface components {
+    schemas: {
+        ContentAccessInfo: {
+            user_id: string | null;
+            has_purchased: boolean;
+            has_sufficient_funds: boolean;
+            wallet_balance_cents: number;
+            /** @enum {string} */
+            next_required_action: 'authenticate' | 'fund_wallet' | 'purchase' | 'none';
+        };
+        AuthenticationResponse: {
+            /** @enum {string} */
+            token_type: 'Bearer';
+            /** @example eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIwOTM1N2MyMi0zODlhLTRmYWItYjE2Ni04MjJlNTJhNWJmNWUiLCJyb2xlIjoiYnV5ZXIiLCJidXllcl9jbGFpbXMiOnsidXNlcl9pZCI6IjA5MzU3YzIyLTM4OWEtNGZhYi1iMTY2LTgyMmU1MmE1YmY1ZSIsImVtYWlsIjoidGVzdC0xM0BleGFtcGxlLmNvbSJ9LCJpc3MiOiJMZWRlV2lyZSBBUEkiLCJhdWQiOiJ3ZWIiLCJleHAiOjE3NDc0OTk5NzMsImlhdCI6MTc0NzQ5ODE3MywibmJmIjoxNzQ3NDk4MTczLCJqdGkiOiIwZTMyYzNkNi02OWQwLTRmNTItYTczNS1hZTJiOGNlMmY1MmQiLCJ0b2tlbl9tZXRhZGF0YSI6eyJjcmVhdGVkX2F0IjoiMjAyNS0wNS0xN1QxNjowOTozM1oiLCJleHBpcmVzX2F0IjoiMjAyNS0wNS0xN1QxNjozOTozM1oiLCJ0b2tlbl9pZCI6IjBlMzJjM2Q2LTY5ZDAtNGY1Mi1hNzM1LWFlMmI4Y2UyZjUyZCJ9fQ.VSFsm5ysjtZLheVfhv6DWwH1A9zn_WA6rnGOlPR1R3U */
+            access_token: string;
+            refresh_token: string;
+            /**
+             * Format: date-time
+             * @description When the Access Token expires
+             */
+            expires_at: string;
+        };
+        /** @description Token response for merchant authentication. Tokens are store-agnostic — no store_context is embedded. */
+        MerchantAuthenticationResponse: {
+            /** @enum {string} */
+            token_type: 'Bearer';
+            access_token: string;
+            refresh_token: string;
+            /** Format: date-time */
+            expires_at: string;
+        };
+        JWTClaims: {
+            /** @description User or Store identifier */
+            sub?: string;
+            /** @enum {string} */
+            role?: 'buyer' | 'seller-view' | 'seller-full' | 'merchant';
+            seller_claims?: {
+                seller_id?: string;
+            };
+            buyer_claims?: {
+                user_id?: string;
+                email?: string;
+            };
+            /** @description Present on merchant tokens */
+            user_claims?: {
+                id?: string;
+                email?: string;
+                full_name?: string;
+            };
+            iat?: number;
+            exp?: number;
+            nbf?: number;
+            iss?: string;
+            aud?: string;
+            token_metadata?: {
+                /** Format: date-time */
+                created_at?: string;
+                /** Format: date-time */
+                expires_at?: string;
+                token_id?: string;
+            };
+        };
+        MessageResponse: {
+            message: string;
+        };
+        ErrorResponse: {
+            error: {
+                code: number;
+                message: string;
+            };
+        };
+        AuthSignupRequest: {
+            email: string;
+            password: string;
+            name: string;
+        };
+        AuthLoginEmailRequest: {
+            email?: string;
+            password?: string;
+        };
+        AuthLoginOAuthRequest: {
+            id_token?: string;
+        };
+        MerchantEmailLoginRequest: {
+            email: string;
+            password: string;
+        };
+        MerchantGoogleLoginRequest: {
+            id_token: string;
+        };
+        AuthLoginApiKeyRequest: {
+            key: string;
+            secret?: string;
+        };
+        AuthTokenRefreshRequest: {
+            refresh_token?: string;
+        };
+        ManageableStore: {
+            store_id: string;
+            store_name: string;
+            store_key: string;
+            /** @enum {string|null} */
+            role: 'owner' | null;
+            /** @description Whether the authenticated user has author permissions for this store. */
+            is_author: boolean;
+            logo: string | null;
+        };
+        MerchantUser: {
+            id: string;
+            user_id: string | null;
+            store_id: string;
+            /**
+             * @description Named role. `owner` is the only valid named role; non-owner authors have a null role.
+             * @enum {string|null}
+             */
+            role: 'owner' | null;
+            /** @description Whether this user can create and manage their own content. */
+            is_author: boolean;
+            /** Format: date-time */
+            invited_at: string | null;
+            /** Format: date-time */
+            accepted_at: string | null;
+            email: string | null;
+        };
+        MerchantInviteRequest: {
+            /** @description Email address of the user to invite to the store. */
+            email: string;
+            /**
+             * @description Whether to grant author permissions. Defaults to `true`.
+             * @default true
+             */
+            is_author: boolean;
+        };
+        MerchantInviteResponse: {
+            invitation_token: string;
+            email: string;
+            /** @enum {string|null} */
+            role: 'owner' | null;
+            is_author: boolean;
+            /** Format: date-time */
+            expires_at: string;
+        };
+        WalletPaymentSessionRequest: {
+            /** @description Amount to fund the wallet in cents */
+            amount_cents: number;
+            /**
+             * @description Currency code (defaults to USD)
+             * @default usd
+             */
+            currency: string;
+            /** @description Additional metadata to include with the payment session */
+            metadata?: Record<string, never>;
+        };
+        WalletPaymentSessionResponse: {
+            /** @description The client secret used by the payment widget to confirm the payment */
+            client_secret: string;
+            /** @description The ID of the created payment session */
+            session_id: string;
+            /** @description The payment public key to be used during the payment processing */
+            public_key: string;
+        };
+        /** @description A payment provider webhook event object */
+        PaymentWebhookEvent: {
+            /** @description Unique identifier for the event */
+            id?: string;
+            /** @description Type of event (e.g., payment_intent.succeeded, payment_intent.payment_failed) */
+            type?: string;
+            /** @description Event data containing the object that triggered the event */
+            data?: Record<string, never>;
+        };
+        WalletBalanceResponse: {
+            balance_cents: number;
+        };
+        WalletTransactionItem: {
+            /** @description ID of the transaction entry (matches the source record) */
+            id: string;
+            /**
+             * @description Direction relative to the user's wallet
+             * @enum {string}
+             */
+            type: 'credit' | 'debit';
+            /**
+             * @description What caused this wallet movement
+             * @enum {string}
+             */
+            reason: 'wallet_funding' | 'purchase' | 'refund';
+            /** @description Always positive; direction expressed by `type` */
+            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) */
+            reference_id: string;
+            /** @description Human-readable label suitable for display */
+            description: string;
+            /**
+             * Format: date-time
+             * @description created_at of the source record
+             */
+            occurred_at: string;
+        };
+        PurchaseCreateRequest: {
+            content_id?: string;
+            price_cents?: number;
+        };
+        PurchaseVerifyResponse: {
+            has_purchased: boolean;
+            purchase_details?: {
+                purchase_id?: string;
+                /** Format: date-time */
+                purchase_date?: string;
+            };
+            checkout_readiness?: {
+                is_authenticated?: boolean;
+                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. */
+        ContentUpdateRequest: {
+            /** @description Content title */
+            title?: string;
+            /**
+             * Format: byte
+             * @description Full article body in markdown, base64 encoded. For `markdown` content only.
+             */
+            content_body?: string;
+            /**
+             * @description URI of the external resource. For `external_ref` content only.
+             * @example https://vimeo.com/123456789
+             */
+            content_uri?: string;
+            /**
+             * @description Namespaced platform ID, e.g. `vimeo:123456789`. For `external_ref` content only.
+             * @example vimeo:123456789
+             */
+            external_identifier?: string | null;
+            /**
+             * Format: byte
+             * @description Content teaser, base64 encoded
+             */
+            teaser?: string;
+            /** @description Price in cents (must be greater than 0) */
+            price_cents?: number;
+            /** @enum {string} */
+            visibility?: 'public' | 'unlisted';
+            metadata?: {
+                [key: string]: unknown;
+            };
+            /** @description Assign or clear content authorship. Provide the `id` of a `StoreUser` from `GET /v1/merchant/{store_id}/users` to assign an author, or `null` to clear attribution. Only available to `owner` role and API key auth. Users with `is_author: true` (non-owner) cannot reassign their own content. */
+            store_user_id?: string | null;
+        };
+        SalesStatisticsItem: {
+            content_id: string;
+            title: string;
+            total_sales: number;
+            total_revenue_cents: number;
+        };
+        /**
+         * @description Seller-scoped buyer aggregate statistics for reporting.
+         *
+         *     Prefer `buyer_ref` over any global buyer identifier.
+         */
+        BuyerStatisticsItem: {
+            /** @description Opaque, seller-scoped identifier for a buyer (not the global user id). */
+            buyer_ref: string;
+            /** @description Number of completed purchases by this buyer for this seller. */
+            purchases_count: number;
+            /** @description Total amount spent by this buyer for this seller, in cents. */
+            total_spent_cents: number;
+            /**
+             * Format: date-time
+             * @description Timestamp of the buyer's first completed purchase for this seller.
+             */
+            first_purchase_at: string;
+            /**
+             * Format: date-time
+             * @description Timestamp of the buyer's most recent completed purchase for this seller.
+             */
+            last_purchase_at: string;
+            /**
+             * @description Coarse segmentation label derived by the platform.
+             * @enum {string}
+             */
+            buyer_status: 'new' | 'repeat' | 'inactive';
+        };
+        AhoyEvent: {
+            /** @description Name of the event being tracked */
+            name?: string;
+            /** @description Additional properties for the event */
+            properties?: {
+                [key: string]: unknown;
+            };
+            /**
+             * Format: date-time
+             * @description When the event occurred
+             */
+            time?: string;
+            /**
+             * Format: uuid
+             * @description ID of the user associated with the event
+             */
+            user_id?: string;
+            /**
+             * Format: uuid
+             * @description ID of the visit associated with the event
+             */
+            visit_id?: string;
+        };
+        AhoyVisit: {
+            /** @description Unique token for this visit */
+            visit_token?: string;
+            /** @description Token identifying the visitor */
+            visitor_token?: string;
+            /**
+             * Format: uuid
+             * @description ID of the user associated with the visit
+             */
+            user_id?: string;
+            /** @description IP address of the visitor */
+            ip?: string;
+            /** @description User agent string */
+            user_agent?: string;
+            /** @description Referrer URL */
+            referrer?: string;
+            /** @description Domain of the referrer */
+            referring_domain?: string;
+            /** @description Landing page URL */
+            landing_page?: string;
+            /** @description Browser name */
+            browser?: string;
+            /** @description Operating system */
+            os?: string;
+            /** @description Type of device */
+            device_type?: string;
+            /** @description Country of the visitor */
+            country?: string;
+            /** @description Region of the visitor */
+            region?: string;
+            /** @description City of the visitor */
+            city?: string;
+            /**
+             * Format: float
+             * @description Latitude coordinate
+             */
+            latitude?: number;
+            /**
+             * Format: float
+             * @description Longitude coordinate
+             */
+            longitude?: number;
+            /** @description UTM source parameter */
+            utm_source?: string;
+            /** @description UTM medium parameter */
+            utm_medium?: string;
+            /** @description UTM term parameter */
+            utm_term?: string;
+            /** @description UTM content parameter */
+            utm_content?: string;
+            /** @description UTM campaign parameter */
+            utm_campaign?: string;
+            /** @description App version (for native apps) */
+            app_version?: string;
+            /** @description OS version (for native apps) */
+            os_version?: string;
+            /** @description Platform (for native apps) */
+            platform?: string;
+            /**
+             * Format: date-time
+             * @description When the visit started
+             */
+            started_at?: string;
+        };
+        AhoyEventRequest: {
+            /** @description Name of the event being tracked */
+            name: string;
+            /** @description Additional properties for the event */
+            properties?: {
+                [key: string]: unknown;
+            };
+            /**
+             * Format: date-time
+             * @description When the event occurred (defaults to current time)
+             */
+            time?: string;
+            /**
+             * Format: uuid
+             * @description ID of the user associated with the event
+             */
+            user_id?: string;
+            /**
+             * Format: uuid
+             * @description ID of the visit associated with the event
+             */
+            visit_id?: string;
+        };
+        AhoyVisitRequest: {
+            /** @description Unique token for this visit */
+            visit_token?: string;
+            /** @description Token identifying the visitor */
+            visitor_token?: string;
+            /**
+             * Format: uuid
+             * @description ID of the user associated with the visit
+             */
+            user_id?: string;
+            /** @description IP address of the visitor */
+            ip?: string;
+            /** @description User agent string */
+            user_agent?: string;
+            /** @description Referrer URL */
+            referrer?: string;
+            /** @description Domain of the referrer */
+            referring_domain?: string;
+            /** @description Landing page URL */
+            landing_page?: string;
+            /** @description Browser name */
+            browser?: string;
+            /** @description Operating system */
+            os?: string;
+            /** @description Type of device */
+            device_type?: string;
+            /** @description Country of the visitor */
+            country?: string;
+            /** @description Region of the visitor */
+            region?: string;
+            /** @description City of the visitor */
+            city?: string;
+            /**
+             * Format: float
+             * @description Latitude coordinate
+             */
+            latitude?: number;
+            /**
+             * Format: float
+             * @description Longitude coordinate
+             */
+            longitude?: number;
+            /** @description UTM source parameter */
+            utm_source?: string;
+            /** @description UTM medium parameter */
+            utm_medium?: string;
+            /** @description UTM term parameter */
+            utm_term?: string;
+            /** @description UTM content parameter */
+            utm_content?: string;
+            /** @description UTM campaign parameter */
+            utm_campaign?: string;
+            /** @description App version (for native apps) */
+            app_version?: string;
+            /** @description OS version (for native apps) */
+            os_version?: string;
+            /** @description Platform (for native apps) */
+            platform?: string;
+            /**
+             * Format: date-time
+             * @description When the visit started (defaults to current time)
+             */
+            started_at?: string;
+        };
+        /** @description Create request body for content. Required fields vary by `content_type`: `markdown` requires `content_body`; `external_ref` requires `content_uri`. */
+        Content: {
+            /**
+             * @description The type of content being created.
+             * @enum {string}
+             */
+            content_type: 'markdown' | 'external_ref';
+            /** @description Content title */
+            title: string;
+            /**
+             * Format: byte
+             * @description Full article body in markdown, base64 encoded. Required when `content_type` is `markdown`.
+             */
+            content_body?: string;
+            /**
+             * @description URI of the external resource (Vimeo, YouTube, PDF, etc.). Required when `content_type` is `external_ref`.
+             * @example https://vimeo.com/123456789
+             */
+            content_uri?: string;
+            /**
+             * @description Optional namespaced platform ID, e.g. `vimeo:123456789` or `youtube:dQw4w9WgXcQ`.
+             * @example vimeo:123456789
+             */
+            external_identifier?: string;
+            /**
+             * Format: byte
+             * @description (Optional) Article teaser, written in markdown and base64 encoded.
+             */
+            teaser?: string;
+            /** @description Price for the content in cents. */
+            price_cents: number;
+            /**
+             * @default public
+             * @enum {string}
+             */
+            visibility: 'public' | 'unlisted';
+            /** @description Flexible metadata for additional context */
+            metadata?: {
+                author?: string;
+                /** Format: date-time */
+                publication_date?: string;
+                reading_time?: string;
+            } & {
+                [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`. */
+        ContentResponse: {
+            id: string;
+            /**
+             * @description The type of content.
+             * @enum {string}
+             */
+            content_type: 'markdown' | 'external_ref';
+            /** @description Content title */
+            title: string;
+            /**
+             * Format: byte
+             * @description Full article body in markdown, base64 encoded. Present when `content_type` is `markdown`.
+             */
+            content_body?: string | null;
+            /**
+             * @description URI of the external resource. Present when `content_type` is `external_ref`.
+             * @example https://vimeo.com/123456789
+             */
+            content_uri?: string | null;
+            /**
+             * @description Namespaced platform ID, e.g. `vimeo:123456789`. Present on `external_ref` content.
+             * @example vimeo:123456789
+             */
+            external_identifier?: string | null;
+            /**
+             * Format: byte
+             * @description Article teaser, base64 encoded.
+             */
+            teaser: string;
+            /** @description Price for the content in cents. */
+            price_cents: number;
+            /**
+             * @default public
+             * @enum {string}
+             */
+            visibility: 'public' | 'unlisted' | 'private';
+            /** @description Flexible metadata for additional context */
+            metadata?: {
+                author?: string;
+                /** Format: date-time */
+                publication_date?: string;
+                reading_time?: string;
+                /** Format: string */
+                tags?: unknown[];
+                /** @description flexible data for managing paywall location */
+                paywall?: {
+                    /** @description Character position of the paywall */
+                    position?: number;
+                    /**
+                     * @description The mechanism for determining how positioning is calculated
+                     * @enum {string}
+                     */
+                    positioning_type?: 'character' | 'paragraph';
+                    /** @description Hash anchor of nearby text */
+                    anchor?: string;
+                };
+            } & {
+                [key: string]: unknown;
+            };
+        };
+        /** @description Lightweight content representation returned by list and search endpoints. Omits body fields to keep list payloads small. Use the detail endpoint (`GET /v1/merchant/:store_id/content/:id`) to retrieve the full body or URI. */
+        ContentListItem: {
+            id: string;
+            /** @enum {string} */
+            content_type: 'markdown' | 'external_ref';
+            title: string;
+            price_cents: number;
+            /**
+             * Format: byte
+             * @description Article teaser, base64 encoded. Null when not set.
+             */
+            teaser: string | null;
+            /** @enum {string} */
+            visibility: 'public' | 'unlisted' | 'private';
+            /** Format: date-time */
+            created_at: string;
+            /** @description Namespaced platform ID for `external_ref` content. Null for other types. */
+            external_identifier?: 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.
+         */
+        ContentWithAccessResponse: components['schemas']['ContentResponse'] & {
+            access_info: components['schemas']['ContentAccessInfo'];
+        };
+        User: {
+            id?: string;
+            name?: string;
+            email?: string;
+            /** @enum {string} */
+            role?: 'buyer' | 'seller';
+        };
+        /** @enum {string} */
+        PurchaseStatus: 'completed' | 'refunded' | 'pending' | 'reverted' | 'failed';
+        PurchaseResponse: {
+            id: string;
+            content_id: string;
+            content: {
+                id: string;
+                content_type: string;
+                title: string;
+            };
+            buyer_id: string;
+            buyer: {
+                id: string;
+                name: string;
+            };
+            seller_id: string;
+            seller: {
+                id: string;
+                name: string;
+            };
+            amount_cents: number;
+            /** Format: date-time */
+            timestamp: string;
+            status: components['schemas']['PurchaseStatus'];
+        };
+        MerchantSaleResponse: {
+            id: string;
+            content_id: string;
+            content: {
+                id: string;
+                content_type: string;
+                title: string;
+            };
+            buyer_id: string;
+            buyer: {
+                id: string;
+                name: string;
+            };
+            seller_id: string;
+            seller: {
+                id: string;
+                name: string;
+            };
+            amount_cents: number;
+            /** @description Platform fee split. Values are 0 (not null) on non-completed purchases. */
+            fees: {
+                platform_fee_cents: number;
+                store_net_cents: number;
+                /** @description 0 for content without an author */
+                author_net_cents: number;
+            };
+            status: components['schemas']['PurchaseStatus'];
+            /** Format: date-time */
+            timestamp: string;
+        };
+        MonthlyData: {
+            [key: string]: {
+                [key: string]: {
+                    cents?: number;
+                    currency_iso?: string;
+                };
+            };
+        };
+        InviteInfoResponse: {
+            invited_email: string;
+            store_name: string;
+            /** @enum {string|null} */
+            role: 'owner' | null;
+            /** Format: date-time */
+            expires_at: string;
+        };
+        CheckoutStateResponse: {
+            content_id: string;
+            content_title: string;
+            price_cents: number;
+            checkout_state: {
+                is_authenticated: boolean;
+                has_sufficient_funds?: boolean | null;
+                has_purchased: boolean;
+                /** @enum {string} */
+                next_required_action: 'authenticate' | 'fund_wallet' | 'purchase' | 'view_content';
+            };
+        };
+        WalletPaymentStatusResponse: {
+            /** @enum {string} */
+            status: 'pending' | 'completed' | 'failed';
+            /** Format: date-time */
+            updated_at: string;
+            balance_cents: number;
+        };
+        SalesSummaryResponse: {
+            /** @description Amount in cents */
+            total_revenue_cents: number;
+            /** @description Total number of sales */
+            total_sales: number;
+            /** @description Monthly revenue data grouped by year and month. First level key is year (string), second level key is month number (string, 1-12) */
+            monthly_revenue_cents: {
+                [key: string]: {
+                    [key: string]: number;
+                };
+            };
+            /** @description Monthly sales count data grouped by year and month. First level key is year (string), second level key is month number (string, 1-12) */
+            monthly_sales: {
+                [key: string]: {
+                    [key: string]: number;
+                };
+            };
+        };
+    };
+    responses: never;
+    parameters: never;
+    requestBodies: never;
+    headers: never;
+    pathItems: never;
+}
+
+/** Checkout state for a specific piece of content and user. */
+export declare type ContentAccessInfo = components['schemas']['ContentAccessInfo'];
+
+/** A piece of content with buyer access information. */
+export declare type ContentWithAccessResponse = components['schemas']['ContentWithAccessResponse'];
+
+/**
+ * Thrown when the authenticated user does not have permission
+ * to perform the requested operation.
+ */
+export declare class ForbiddenError extends LedewireError {
+    constructor(message: string, code?: number);
+}
+
+/**
+ * Core HTTP client used by all SDK packages.
+ *
+ * Features:
+ * - 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
+ *
+ * This is an internal class - consumers should use the
+ * package-level client factories (`init` / `createClient`) instead.
+ */
+declare class HttpClient {
+    private readonly baseUrl;
+    private readonly getAccessToken;
+    private readonly onUnauthorized;
+    constructor(config?: HttpClientConfig);
+    /**
+     * GET request with optional query parameters.
+     * @param path - API path (e.g. `/v1/wallet/balance`)
+     * @param params - Query string parameters
+     */
+    get<T>(path: string, params?: Record<string, string>): Promise<T>;
+    /**
+     * POST request.
+     * @param path - API path
+     * @param body - Request body (JSON-serialized)
+     */
+    post<T>(path: string, body?: unknown): Promise<T>;
+    /**
+     * PUT request.
+     * @param path - API path
+     * @param body - Request body (JSON-serialized)
+     */
+    put<T>(path: string, body?: unknown): Promise<T>;
+    /**
+     * PATCH request.
+     * @param path - API path
+     * @param body - Partial update body (JSON-serialized)
+     */
+    patch<T>(path: string, body?: unknown): Promise<T>;
+    /**
+     * DELETE request.
+     * @param path - API path
+     */
+    delete<T = void>(path: string): Promise<T>;
+    private buildUrl;
+    private request;
+    private throwApiError;
+}
+
+/**
+ * Configuration options for `HttpClient`.
+ */
+declare interface HttpClientConfig {
+    /** API base URL. Defaults to the production API. */
+    baseUrl?: string;
+    /**
+     * Returns the current access token (or null) before each request.
+     * If null, requests are sent without an Authorization header.
+     */
+    getAccessToken?: () => string | null | Promise<string | null>;
+    /**
+     * Called when a 401 is received on the first attempt.
+     * Should refresh and return the new access token, or null to propagate
+     * an `AuthError` to the caller.
+     */
+    onUnauthorized?: () => string | null | Promise<string | null>;
+}
+
+/**
+ * Initialises a LedeWire browser client.
+ * This is the primary entry point for the browser SDK.
+ *
+ * @example CDN usage:
+ * ```html
+ * <script src="https://cdn.jsdelivr.net/npm/@ledewire/browser@1/dist/ledewire.min.js"></script>
+ * <script>
+ *   const lw = Ledewire.init({ apiKey: 'your_api_key' })
+ *   const state = await lw.checkout.state('content-id')
+ * </script>
+ * ```
+ *
+ * @example npm usage:
+ * ```ts
+ * import { init } from '@ledewire/browser'
+ * const lw = init({ apiKey: 'your_api_key' })
+ * ```
+ */
+export declare function init(config: BrowserClientConfig): BrowserClient;
+
+/**
+ * Base error class for all LedeWire SDK errors.
+ * All errors thrown by the SDK are instances of this class,
+ * making it safe to use `err instanceof LedewireError` as a type guard.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await client.purchases.create({ contentId: '...' })
+ * } catch (err) {
+ *   if (err instanceof LedewireError) {
+ *     console.error(err.statusCode, err.message)
+ *   }
+ * }
+ * ```
+ */
+export declare class LedewireError extends Error {
+    /** 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);
+}
+
+/**
+ * A {@link TokenStorage} adapter that persists tokens in `localStorage`.
+ *
+ * Tokens survive page reloads and browser restarts, which is convenient
+ * for sites where users expect persistent sessions.
+ *
+ * **Security note:** `localStorage` is accessible to any JavaScript on the
+ * same origin. Only use this adapter on sites you fully control and trust.
+ * The default in-memory storage is safer for high-security use cases.
+ *
+ * @param key - The `localStorage` key used to store tokens.
+ *   Defaults to `'lw:tokens'`. Override this if you have multiple
+ *   LedeWire integrations on the same origin.
+ *
+ * @example
+ * ```ts
+ * import { init, localStorageAdapter } from '@ledewire/browser'
+ *
+ * const lw = init({
+ *   apiKey: 'your_api_key',
+ *   storage: localStorageAdapter(),
+ * })
+ * ```
+ */
+export declare function localStorageAdapter(key?: string): TokenStorage;
+
+/**
+ * In-memory token storage (default for both packages).
+ * Tokens are cleared when the page unloads or the process exits.
+ * This is the most secure default for browser environments.
+ */
+export declare class MemoryTokenStorage implements TokenStorage {
+    private tokens;
+    getTokens(): StoredTokens | null;
+    setTokens(tokens: StoredTokens): void;
+    clearTokens(): void;
+}
+
+/** The next action a buyer must take in the checkout flow. */
+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);
+}
+
+/**
+ * Converts an `expires_at` ISO 8601 string from an API auth response
+ * into a Unix timestamp (milliseconds) for use in `StoredTokens.expiresAt`.
+ *
+ * @param expiresAt - ISO 8601 datetime string, e.g. `"2026-01-01T12:00:00Z"`
+ * @returns Unix timestamp in milliseconds
+ */
+export declare function parseExpiresAt(expiresAt: string): number;
+
+/** Request body for creating a purchase. */
+export declare type PurchaseCreateRequest = components['schemas']['PurchaseCreateRequest'];
+
+/**
+ * Thrown when the purchase cannot be completed due to a validation
+ * failure, such as a price mismatch or a duplicate purchase.
+ */
+export declare class PurchaseError extends LedewireError {
+    constructor(message: string, statusCode: number, code?: number);
+}
+
+/** A purchase record. */
+export declare type PurchaseResponse = components['schemas']['PurchaseResponse'];
+
+/** Internal representation of stored authentication tokens. */
+export declare interface StoredTokens {
+    accessToken: string;
+    refreshToken: string;
+    /** Unix timestamp (ms) when the access token expires. */
+    expiresAt: number;
+}
+
+/**
+ * Manages the JWT token lifecycle transparently.
+ *
+ * - Proactively refreshes the access token when it expires within 60 seconds
+ * - Handles reactive refresh on 401 responses from the HTTP client
+ * - Deduplicates concurrent refresh calls (only one in-flight refresh at a time)
+ * - Fires `onAuthExpired` when refresh fails so the UI can prompt re-login
+ *
+ * This is an internal class - use the package-level client factories instead.
+ */
+declare class TokenManager {
+    private readonly storage;
+    private readonly refreshFn;
+    private readonly onTokenRefreshed;
+    private readonly onAuthExpired;
+    private refreshPromise;
+    constructor(options: TokenManagerOptions);
+    /**
+     * Returns a valid access token, refreshing proactively if needed.
+     * Returns `null` if no tokens are stored (user not authenticated).
+     */
+    getAccessToken(): Promise<string | null>;
+    /**
+     * Called by `HttpClient` when a 401 is received.
+     * Attempts one refresh; returns the new access token or null.
+     */
+    handleUnauthorized(): Promise<string | null>;
+    /** Store new tokens after a successful login or signup. */
+    setTokens(tokens: StoredTokens): Promise<void>;
+    /** Clear all stored tokens (call on logout). */
+    clearTokens(): Promise<void>;
+    private performRefresh;
+}
+
+/**
+ * Options for constructing a `TokenManager`.
+ */
+declare interface TokenManagerOptions {
+    storage: TokenStorage;
+    /**
+     * Exchanges a refresh token for a new token pair.
+     * Implemented by each package's client factory using the
+     * `/v1/auth/token/refresh` endpoint.
+     */
+    refreshFn: (refreshToken: string) => Promise<StoredTokens>;
+    /**
+     * Called after a successful token refresh.
+     * Use in server environments to persist the new tokens to a database or cache.
+     *
+     * @example
+     * ```ts
+     * onTokenRefreshed: async (tokens) => {
+     *   await redis.set('session:tokens', JSON.stringify(tokens))
+     * }
+     * ```
+     */
+    onTokenRefreshed?: (tokens: StoredTokens) => void | Promise<void>;
+    /**
+     * Called when a refresh attempt fails and the user must re-authenticate.
+     * Typically used to redirect to login or emit a UI event.
+     *
+     * @example
+     * ```ts
+     * onAuthExpired: () => { window.location.href = '/login' }
+     * ```
+     */
+    onAuthExpired?: () => void | Promise<void>;
+}
+
+/**
+ * Interface for pluggable token storage adapters.
+ * Implement this to persist tokens across page loads or in a server-side store.
+ *
+ * @example
+ * ```ts
+ * // Built-in localStorage adapter (browser only)
+ * import { localStorageAdapter } from '@ledewire/browser'
+ * const client = createBrowserClient({ apiKey, storage: localStorageAdapter() })
+ * ```
+ */
+export declare interface TokenStorage {
+    /** Retrieve stored token data, or null if none. */
+    getTokens(): StoredTokens | null | Promise<StoredTokens | null>;
+    /** Persist token data. */
+    setTokens(tokens: StoredTokens): void | Promise<void>;
+    /** Clear all stored token data (called on logout). */
+    clearTokens(): void | Promise<void>;
+}
+
+/** Current wallet balance for the authenticated buyer. */
+export declare type WalletBalanceResponse = components['schemas']['WalletBalanceResponse'];
+
+/** Request body for creating a wallet payment session. */
+export declare type WalletPaymentSessionRequest = components['schemas']['WalletPaymentSessionRequest'];
+
+/** Response from creating a wallet payment session. */
+export declare type WalletPaymentSessionResponse = components['schemas']['WalletPaymentSessionResponse'];
+
+/** Status of a wallet payment session. */
+export declare type WalletPaymentStatusResponse = components['schemas']['WalletPaymentStatusResponse'];
+
+/** A single wallet transaction entry. */
+export declare type WalletTransactionItem = components['schemas']['WalletTransactionItem'];
+
+export { }