@ledewire/browser 0.5.0 → 0.6.1

package/README.md

@@ -83,8 +83,8 @@ switch (checkout_state.next_required_action) {
     const { content_type, content_body, content_uri } =
       await lw.content.getWithAccess('article-123')
     if (content_type === 'markdown') {
-      // render decoded markdown
-      renderMarkdown(atob(content_body))
+      // content_body is plain text — the SDK decodes base64 automatically
+      renderMarkdown(content_body)
     } else {
       // redirect to the gated external URI (Vimeo, PDF, etc.)
       window.location.href = content_uri
@@ -95,14 +95,14 @@ switch (checkout_state.next_required_action) {
 
 ## Example: Seller Content Discovery
 
-Use `lw.auth.loginWithApiKey` with only the `key` to obtain a read-only token,
+Use `lw.seller.loginWithApiKey` with only the `key` to obtain a read-only token,
 then browse your store's content catalogue directly from the browser:
 
 ```ts
 const lw = Ledewire.init({ apiKey: 'your_api_key' })
 
 // Obtain a view-only seller token (key only — no secret needed)
-await lw.auth.loginWithApiKey({ key: 'your_api_key' })
+await lw.seller.loginWithApiKey({ key: 'your_api_key' })
 
 // List all content
 const items = await lw.seller.content.list()
@@ -118,11 +118,16 @@ const item = await lw.seller.content.get('content-id')
 ## Token Storage
 
 By default tokens are stored **in memory** (most secure — cleared on page unload).
-Use the built-in `localStorageAdapter` to persist sessions across reloads:
+Two built-in adapters are available for persistent sessions:
 
 ```ts
-import { init, localStorageAdapter } from '@ledewire/browser'
+import { init, localStorageAdapter, sessionStorageAdapter } from '@ledewire/browser'
+
+// Persists across tabs and browser restarts
 const lw = init({ apiKey: '...', storage: localStorageAdapter() })
+
+// Persists within the current tab only (cleared on tab close)
+const lw = init({ apiKey: '...', storage: sessionStorageAdapter() })
 ```
 
 Token refresh is handled automatically — you never need to call a refresh method manually.

package/dist/index.d.ts

@@ -92,7 +92,7 @@ export declare interface AuthPasswordResetResponse {
 declare type AuthSignupRequest = components['schemas']['AuthSignupRequest'];
 
 /**
- * Buyer authentication: signup, email/password login, Google OAuth.
+ * Buyer authentication: signup, email/password login, Google OAuth, password reset.
  *
  * Obtain via `lw.auth` — do not construct directly.
  *
@@ -130,27 +130,6 @@ declare class BrowserAuthNamespace {
      * @returns The authentication token response.
      */
     loginWithGoogle(body: AuthLoginOAuthRequest): Promise<AuthenticationResponse>;
-    /**
-     * Log in using an API key to obtain a seller token.
-     * Provide only `key` for read-only (`view`) access.
-     * Provide both `key` and `secret` for read/write (`full`) access.
-     * Tokens are stored automatically after successful authentication.
-     *
-     * Use this before calling `lw.seller.content.*` methods.
-     *
-     * @param body - API key credentials.
-     * @returns The authentication token response.
-     *
-     * @example
-     * ```ts
-     * // View access (read-only) — sufficient for seller.content.list/search/get
-     * await lw.auth.loginWithApiKey({ key: 'your_api_key' })
-     *
-     * // Full access (read/write)
-     * await lw.auth.loginWithApiKey({ key: 'your_api_key', secret: 'your_secret' })
-     * ```
-     */
-    loginWithApiKey(body: AuthLoginApiKeyRequest): Promise<AuthenticationResponse>;
     /**
      * Request a password reset code to be sent to the buyer's email address.
      *
@@ -196,12 +175,12 @@ 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, password reset */
+    /** Buyer authentication: email/password signup/login, Google OAuth, password reset */
     readonly auth: BrowserAuthNamespace;
     /** Checkout state machine: determines next action for a piece of content */
     readonly checkout: CheckoutNamespace;
@@ -211,7 +190,7 @@ declare class BrowserClient {
     readonly purchases: BrowserPurchasesNamespace;
     /** Public content with per-user access information */
     readonly content: BrowserContentNamespace;
-    /** Seller content: list, search, and get (requires API key view token) */
+    /** Seller operations: API key login, content list/search/get */
     readonly seller: BrowserSellerNamespace;
     /* Excluded from this release type: __constructor */
 }
@@ -286,8 +265,10 @@ declare class BrowserConfigNamespace {
  *
  * @example
  * ```ts
- * const { content, access } = await lw.content.getWithAccess('content-id')
- * if (access.has_access) showFullContent(content)
+ * const result = await lw.content.getWithAccess('content-id')
+ * if (result.access_info.next_required_action === 'view_content') {
+ *   renderMarkdown(result.content_body ?? '')
+ * }
  * ```
  */
 declare class BrowserContentNamespace {
@@ -298,10 +279,19 @@ declare class BrowserContentNamespace {
      * 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.
+     * @returns The content item with access information. `content_body` and
+     * `teaser` are returned as plain UTF-8 text — the SDK decodes base64
+     * transparently so you can render them directly.
+     *
+     * @example
+     * ```ts
+     * const result = await lw.content.getWithAccess('article-123')
+     * if (result.access_info.next_required_action === 'view_content') {
+     *   renderMarkdown(result.content_body ?? '')
+     * }
+     * ```
      */
-    getWithAccess(id: string, userId?: string): Promise<ContentWithAccessResponse>;
+    getWithAccess(id: string): Promise<ContentWithAccessResponse>;
 }
 
 /**
@@ -348,7 +338,7 @@ declare class BrowserPurchasesNamespace {
  * @example
  * ```ts
  * const lw = Ledewire.init({ apiKey: 'your_api_key' })
- * await lw.auth.loginWithApiKey({ key: 'your_api_key' })
+ * await lw.seller.loginWithApiKey({ key: 'your_api_key' })
  *
  * const items = await lw.seller.content.list()
  * const results = await lw.seller.content.search({ title: 'intro' })
@@ -362,7 +352,8 @@ declare class BrowserSellerContentNamespace {
      * List all content for the authenticated seller's store.
      * Requires a token with at least `view` permission.
      *
-     * @returns Array of content items.
+     * @returns Array of content items. `teaser` is returned as plain text —
+     * the SDK decodes base64 automatically.
      *
      * @example
      * ```ts
@@ -376,12 +367,14 @@ declare class BrowserSellerContentNamespace {
      * Requires a token with at least `view` permission.
      *
      * @param body - Search criteria (title, uri, and/or metadata).
-     * @returns Array of matching content items.
+     * @returns Array of matching content items. `teaser` is returned as plain
+     * text — the SDK decodes base64 automatically.
      *
      * @example
      * ```ts
      * const results = await lw.seller.content.search({ title: 'intro' })
      * const byUri = await lw.seller.content.search({ uri: 'vimeo.com' })
+     * const byId = await lw.seller.content.search({ external_identifier: 'vimeo:123456789' })
      * const byMeta = await lw.seller.content.search({ metadata: { author: 'Alice' } })
      * ```
      */
@@ -391,11 +384,14 @@ declare class BrowserSellerContentNamespace {
      * Requires a token with at least `view` permission.
      *
      * @param id - The content ID.
-     * @returns The content item.
+     * @returns The content item. `content_body` and `teaser` are returned as
+     * plain UTF-8 text — the SDK decodes base64 automatically so you can render
+     * them directly without calling `atob()`.
      *
      * @example
      * ```ts
      * const item = await lw.seller.content.get('content-id')
+     * // item.content_body is plain markdown — no atob() needed
      * ```
      */
     get(id: string): Promise<ContentResponse>;
@@ -409,14 +405,39 @@ declare class BrowserSellerContentNamespace {
  * @example
  * ```ts
  * const lw = Ledewire.init({ apiKey: 'your_api_key' })
- * await lw.auth.loginWithApiKey({ key: 'your_api_key' })
+ *
+ * // Authenticate as a seller (key-only = view; key+secret = full)
+ * await lw.seller.loginWithApiKey({ key: 'your_api_key' })
  * const items = await lw.seller.content.list()
  * ```
  */
 declare class BrowserSellerNamespace {
+    private readonly http;
+    private readonly tokenManager;
     /** Seller content: list, search, and get by API key. */
     readonly content: BrowserSellerContentNamespace;
     /* Excluded from this release type: __constructor */
+    /**
+     * Log in using an API key to obtain a seller token.
+     * Provide only `key` for read-only (`view`) access.
+     * Provide both `key` and `secret` for read/write (`full`) access.
+     * Tokens are stored automatically after successful authentication.
+     *
+     * Use this before calling `lw.seller.content.*` methods.
+     *
+     * @param body - API key credentials.
+     * @returns The authentication token response.
+     *
+     * @example
+     * ```ts
+     * // View access (read-only) — sufficient for seller.content.list/search/get
+     * await lw.seller.loginWithApiKey({ key: 'your_api_key' })
+     *
+     * // Full access (read/write)
+     * await lw.seller.loginWithApiKey({ key: 'your_api_key', secret: 'your_secret' })
+     * ```
+     */
+    loginWithApiKey(body: AuthLoginApiKeyRequest): Promise<AuthenticationResponse>;
 }
 
 /**
@@ -497,16 +518,19 @@ declare class CheckoutNamespace {
  */
 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;
-    };
-}
+/**
+ * Checkout state machine result for a specific content item, as returned by
+ * `lw.checkout.state()`.
+ *
+ * This is a consumer-facing alias for {@link CheckoutStateResponse} — the two
+ * types are identical. Prefer `CheckoutState` in application code; use
+ * `CheckoutStateResponse` when you need to explicitly reference the OpenAPI
+ * schema name.
+ *
+ * Note: `checkout_state.has_sufficient_funds` is `boolean | null` because the
+ * API omits or nulls the field when the buyer is unauthenticated.
+ */
+export declare type CheckoutState = CheckoutStateResponse;
 
 /** Full checkout state for a buyer/content pair, including auth and fund status. */
 export declare type CheckoutStateResponse = components['schemas']['CheckoutStateResponse'];
@@ -688,7 +712,9 @@ declare interface components {
              */
             currency: string;
             /** @description Additional metadata to include with the payment session */
-            metadata?: Record<string, never>;
+            metadata?: {
+                [key: string]: unknown;
+            };
         };
         WalletPaymentSessionResponse: {
             /** @description The client secret used by the payment widget to confirm the payment */
@@ -705,7 +731,9 @@ declare interface components {
             /** @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>;
+            data?: {
+                [key: string]: unknown;
+            };
         };
         WalletBalanceResponse: {
             balance_cents: number;
@@ -1313,7 +1341,7 @@ declare interface components {
 export declare type ContentAccessInfo = components['schemas']['ContentAccessInfo'];
 
 /** Full content item returned by all seller content endpoints. */
-declare type ContentResponse = components['schemas']['ContentResponse'];
+export declare type ContentResponse = components['schemas']['ContentResponse'];
 
 /** A piece of content with buyer access information. */
 export declare type ContentWithAccessResponse = components['schemas']['ContentWithAccessResponse'];
@@ -1333,6 +1361,25 @@ export declare type ContentWithAccessResponse = components['schemas']['ContentWi
  *
  * @example
  * ```ts
+ * // Browser
+ * import { ForbiddenError, AuthError } from '@ledewire/browser'
+ *
+ * try {
+ *   await lw.auth.loginWithGoogle({ id_token })
+ * } catch (err) {
+ *   if (err instanceof ForbiddenError) {
+ *     // Credentials were valid but account lacks the required role.
+ *     console.error('Access denied:', err.message)
+ *   } else if (err instanceof AuthError) {
+ *     // Bad credentials or expired token — re-authenticate.
+ *     console.error('Authentication failed:', err.message)
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Node
  * import { ForbiddenError, AuthError } from '@ledewire/node'
  *
  * try {
@@ -1372,15 +1419,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
@@ -1515,6 +1563,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`.
@@ -1554,10 +1617,45 @@ export declare interface SellerContentSearchRequest {
     title?: string;
     /** Case-insensitive partial match against the content URI (`external_ref` content only). */
     uri?: string;
+    /**
+     * Exact match against the content's external identifier.
+     * Use the full formatted value as it appears in `ContentResponse.external_identifier`,
+     * e.g. `'vimeo:123456789'`.
+     */
+    external_identifier?: string;
     /** Exact key/value pairs to AND-match against content metadata. */
     metadata?: Record<string, unknown>;
 }
 
+/**
+ * A {@link TokenStorage} adapter that persists tokens in `sessionStorage`.
+ *
+ * Tokens survive page reloads within the same tab but are cleared when the
+ * tab is closed or the session ends.  This prevents token leakage across
+ * tabs and is a good default for sites where users do not expect persistent
+ * sessions (e.g. embedded checkout widgets, kiosk-mode UIs).
+ *
+ * **Security note:** `sessionStorage` is accessible to any JavaScript on the
+ * same origin and tab.  It is more isolated than `localStorage` (no
+ * cross-tab sharing), but the default in-memory storage is still safer for
+ * high-security use cases.
+ *
+ * @param key - The `sessionStorage` 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, sessionStorageAdapter } from '@ledewire/browser'
+ *
+ * const lw = init({
+ *   apiKey: 'your_api_key',
+ *   storage: sessionStorageAdapter(),
+ * })
+ * ```
+ */
+export declare function sessionStorageAdapter(key?: string): TokenStorage;
+
 /** Internal representation of stored authentication tokens. */
 export declare interface StoredTokens {
     accessToken: string;
@@ -1646,9 +1744,16 @@ declare interface TokenManagerOptions {
  *
  * @example
  * ```ts
- * // Built-in localStorage adapter (browser only)
+ * // Persist across tabs and browser restarts (browser only)
  * import { localStorageAdapter } from '@ledewire/browser'
- * const client = createBrowserClient({ apiKey, storage: localStorageAdapter() })
+ * const lw = init({ apiKey, storage: localStorageAdapter() })
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Persist within the current tab only — cleared on tab close (browser only)
+ * import { sessionStorageAdapter } from '@ledewire/browser'
+ * const lw = init({ apiKey, storage: sessionStorageAdapter() })
  * ```
  */
 export declare interface TokenStorage {