@ledewire/browser 0.4.0 → 0.6.0

package/README.md

@@ -40,15 +40,15 @@ const lw = init({
 
 ## Client Namespaces
 
-| Namespace           | Description                                                     |
-| ------------------- | --------------------------------------------------------------- |
-| `lw.config`         | Platform public config (no auth required)                       |
-| `lw.auth`           | Buyer signup, email/password login, Google OAuth, API key login |
-| `lw.wallet`         | Wallet balance, fund wallet via payment session                 |
-| `lw.purchases`      | List and create content purchases                               |
-| `lw.content`        | Fetch content with buyer access info                            |
-| `lw.checkout`       | Checkout state — what action is required next                   |
-| `lw.seller.content` | List, search, and get store content (API key auth)              |
+| Namespace           | Description                                                                     |
+| ------------------- | ------------------------------------------------------------------------------- |
+| `lw.config`         | Platform public config (no auth required)                                       |
+| `lw.auth`           | Buyer signup, email/password login, Google OAuth, API key login, password reset |
+| `lw.wallet`         | Wallet balance, fund wallet via payment session                                 |
+| `lw.purchases`      | List and create content purchases                                               |
+| `lw.content`        | Fetch content with buyer access info                                            |
+| `lw.checkout`       | Checkout state — what action is required next                                   |
+| `lw.seller.content` | List, search, and get store content (API key auth)                              |
 
 ## Example: Fetch Google OAuth Client ID Before Sign-In
 
@@ -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

@@ -56,11 +56,43 @@ declare type AuthLoginEmailRequest = components['schemas']['AuthLoginEmailReques
 /** Request body for buyer Google OAuth login. */
 declare type AuthLoginOAuthRequest = components['schemas']['AuthLoginOAuthRequest'];
 
+/**
+ * Request body for completing a buyer password reset.
+ * Sent to `POST /v1/auth/password/reset`.
+ */
+export declare interface AuthPasswordResetBody {
+    /** The buyer's registered email address. */
+    email: string;
+    /** 6-digit numeric code delivered to the buyer's email. */
+    reset_code: string;
+    /** New password (minimum 6 characters). */
+    password: string;
+}
+
+/**
+ * Request body for initiating a buyer password reset.
+ * Sent to `POST /v1/auth/password/reset-request`.
+ */
+export declare interface AuthPasswordResetRequestBody {
+    /** The buyer's registered email address. */
+    email: string;
+}
+
+/**
+ * Response returned by both password reset endpoints.
+ * Contains a human-readable confirmation message.
+ */
+export declare interface AuthPasswordResetResponse {
+    data?: {
+        message?: string;
+    };
+}
+
 /** Request body for buyer email/password signup. */
 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.
  *
@@ -99,26 +131,39 @@ declare class BrowserAuthNamespace {
      */
     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.
+     * Request a password reset code to be sent to the buyer's email address.
      *
-     * Use this before calling `lw.seller.content.*` methods.
+     * The response is intentionally ambiguous — if the email does not exist,
+     * the API returns the same success message to prevent account enumeration.
      *
-     * @param body - API key credentials.
-     * @returns The authentication token response.
+     * @param body - The buyer's email address.
+     * @returns A response with a confirmation message.
      *
      * @example
      * ```ts
-     * // View access (read-only) — sufficient for seller.content.list/search/get
-     * await lw.auth.loginWithApiKey({ key: 'your_api_key' })
+     * await lw.auth.requestPasswordReset({ email: 'buyer@example.com' })
+     * // → { data: { message: 'If an account with this email exists, a reset code has been sent.' } }
+     * ```
+     */
+    requestPasswordReset(body: AuthPasswordResetRequestBody): Promise<AuthPasswordResetResponse>;
+    /**
+     * Reset a buyer's password using the code delivered to their email.
      *
-     * // Full access (read/write)
-     * await lw.auth.loginWithApiKey({ key: 'your_api_key', secret: 'your_secret' })
+     * Obtain the reset code first by calling `requestPasswordReset()`.
+     *
+     * @param body - Email address, 6-digit reset code, and the new password.
+     * @returns A response with a confirmation message.
+     *
+     * @example
+     * ```ts
+     * await lw.auth.resetPassword({
+     *   email: 'buyer@example.com',
+     *   reset_code: '123456',
+     *   password: 'new-secure-password',
+     * })
      * ```
      */
-    loginWithApiKey(body: AuthLoginApiKeyRequest): Promise<AuthenticationResponse>;
+    resetPassword(body: AuthPasswordResetBody): Promise<AuthPasswordResetResponse>;
     private storeTokens;
 }
 
@@ -135,7 +180,7 @@ declare class BrowserClient {
     readonly _config: BrowserClientConfig;
     /** 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;
@@ -145,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 */
 }
@@ -220,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 {
@@ -232,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>;
 }
 
 /**
@@ -282,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' })
@@ -296,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
@@ -310,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' } })
      * ```
      */
@@ -325,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>;
@@ -343,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>;
 }
 
 /**
@@ -431,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'];
@@ -622,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 */
@@ -639,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;
@@ -1247,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'];
@@ -1267,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 {
@@ -1488,10 +1601,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;
@@ -1580,9 +1728,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 {