@ledewire/browser 0.2.2 → 0.4.0

package/README.md

@@ -3,7 +3,7 @@
 [![npm](https://img.shields.io/npm/v/@ledewire/browser)](https://www.npmjs.com/package/@ledewire/browser)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](../../LICENSE)
 
-Browser SDK for the [LedeWire](https://api.ledewire.com/api-docs/index.html) content marketplace — embed buyer authentication, wallet funding, and content purchases on any website with a single script tag.
+Browser SDK for the [LedeWire](https://api.ledewire.com/api-docs/index.html) content marketplace — embed buyer authentication, wallet funding, content purchases, and seller content discovery on any website with a single script tag.
 
 ## CDN — No Install Required
 
@@ -40,13 +40,26 @@ const lw = init({
 
 ## Client Namespaces
 
-| Namespace      | Description                                      |
-| -------------- | ------------------------------------------------ |
-| `lw.auth`      | Buyer signup, email/password login, Google OAuth |
-| `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    |
+| 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)              |
+
+## Example: Fetch Google OAuth Client ID Before Sign-In
+
+```ts
+const lw = Ledewire.init({ apiKey: 'your_api_key' })
+
+// No login needed — safe to call on page load
+const { google_client_id } = await lw.config.getPublic()
+google.accounts.id.initialize({ client_id: google_client_id, callback: handleCredential })
+google.accounts.id.renderButton(document.getElementById('signin-btn'), { theme: 'outline' })
+```
 
 ## Example: Full Checkout Flow
 
@@ -80,6 +93,28 @@ switch (checkout_state.next_required_action) {
 }
 ```
 
+## Example: Seller Content Discovery
+
+Use `lw.auth.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' })
+
+// List all content
+const items = await lw.seller.content.list()
+
+// Search by title, URI, or metadata
+const results = await lw.seller.content.search({ title: 'intro' })
+const byMeta = await lw.seller.content.search({ metadata: { author: 'Alice' } })
+
+// Fetch a single item
+const item = await lw.seller.content.get('content-id')
+```
+
 ## Token Storage
 
 By default tokens are stored **in memory** (most secure — cleared on page unload).

package/dist/index.d.ts

@@ -47,6 +47,9 @@ export declare class AuthError extends LedewireError {
     constructor(message: string, code?: number);
 }
 
+/** Request body for API key authentication (seller). */
+declare type AuthLoginApiKeyRequest = components['schemas']['AuthLoginApiKeyRequest'];
+
 /** Request body for buyer email/password login. */
 declare type AuthLoginEmailRequest = components['schemas']['AuthLoginEmailRequest'];
 
@@ -95,6 +98,27 @@ 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>;
     private storeTokens;
 }
 
@@ -109,6 +133,8 @@ declare class BrowserClient {
     readonly _http: HttpClient;
     readonly _tokenManager: TokenManager;
     readonly _config: BrowserClientConfig;
+    /** Platform-level public configuration (no auth required) */
+    readonly config: BrowserConfigNamespace;
     /** Buyer authentication: email/password signup/login, Google, password reset */
     readonly auth: BrowserAuthNamespace;
     /** Checkout state machine: determines next action for a piece of content */
@@ -119,6 +145,8 @@ 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) */
+    readonly seller: BrowserSellerNamespace;
     /* Excluded from this release type: __constructor */
 }
 
@@ -160,6 +188,31 @@ export declare interface BrowserClientConfig {
     onAuthExpired?: () => void;
 }
 
+/**
+ * Platform-level configuration for browser clients.
+ *
+ * Obtain via `client.config` — do not construct directly.
+ */
+declare class BrowserConfigNamespace {
+    protected readonly http: HttpClient;
+    /* Excluded from this release type: __constructor */
+    /**
+     * Returns platform-level public configuration.
+     * No authentication required — safe to call before the user has signed in.
+     *
+     * Use `google_client_id` to initialise the Google Identity Services library
+     * on the storefront login page without requiring a prior authenticated call.
+     *
+     * @example
+     * ```ts
+     * const lw = init({ apiKey: 'your_api_key' })
+     * const { google_client_id } = await lw.config.getPublic()
+     * google.accounts.id.initialize({ client_id: google_client_id, callback })
+     * ```
+     */
+    getPublic(): Promise<PublicConfigResponse>;
+}
+
 /**
  * Buyer content namespace — fetch content with real-time access information.
  *
@@ -221,6 +274,85 @@ declare class BrowserPurchasesNamespace {
     get(id: string): Promise<PurchaseResponse>;
 }
 
+/**
+ * Seller content namespace — list, search, and fetch store content by API key.
+ *
+ * Obtain via `lw.seller.content` — do not construct directly.
+ *
+ * @example
+ * ```ts
+ * const lw = Ledewire.init({ apiKey: 'your_api_key' })
+ * await lw.auth.loginWithApiKey({ key: 'your_api_key' })
+ *
+ * const items = await lw.seller.content.list()
+ * const results = await lw.seller.content.search({ title: 'intro' })
+ * const item = await lw.seller.content.get('content-id')
+ * ```
+ */
+declare class BrowserSellerContentNamespace {
+    private readonly http;
+    /* Excluded from this release type: __constructor */
+    /**
+     * List all content for the authenticated seller's store.
+     * Requires a token with at least `view` permission.
+     *
+     * @returns Array of content items.
+     *
+     * @example
+     * ```ts
+     * const items = await lw.seller.content.list()
+     * ```
+     */
+    list(): Promise<ContentResponse[]>;
+    /**
+     * Search content by title, URI, and/or metadata (AND logic).
+     * At least one criterion must be supplied.
+     * Requires a token with at least `view` permission.
+     *
+     * @param body - Search criteria (title, uri, and/or metadata).
+     * @returns Array of matching content items.
+     *
+     * @example
+     * ```ts
+     * const results = await lw.seller.content.search({ title: 'intro' })
+     * const byUri = await lw.seller.content.search({ uri: 'vimeo.com' })
+     * const byMeta = await lw.seller.content.search({ metadata: { author: 'Alice' } })
+     * ```
+     */
+    search(body: SellerContentSearchRequest): Promise<ContentResponse[]>;
+    /**
+     * Get a single content item by ID.
+     * Requires a token with at least `view` permission.
+     *
+     * @param id - The content ID.
+     * @returns The content item.
+     *
+     * @example
+     * ```ts
+     * const item = await lw.seller.content.get('content-id')
+     * ```
+     */
+    get(id: string): Promise<ContentResponse>;
+}
+
+/**
+ * Seller operations accessible with a view-permission API key token.
+ *
+ * Obtain via `lw.seller` — do not construct directly.
+ *
+ * @example
+ * ```ts
+ * const lw = Ledewire.init({ apiKey: 'your_api_key' })
+ * await lw.auth.loginWithApiKey({ key: 'your_api_key' })
+ * const items = await lw.seller.content.list()
+ * ```
+ */
+declare class BrowserSellerNamespace {
+    /** Seller content: list, search, and get by API key. */
+    readonly content: BrowserSellerContentNamespace;
+    /* Excluded from this release type: __constructor */
+}
+
 /**
  * Buyer wallet namespace — balance, transactions, and payment session management.
  *
@@ -315,6 +447,11 @@ export declare type CheckoutStateResponse = components['schemas']['CheckoutState
 
 declare interface components {
     schemas: {
+        /** @description Platform-level public configuration. No authentication required. */
+        PublicConfigResponse: {
+            /** @description Google OAuth client ID for initialising the Google Identity Services library. */
+            google_client_id: string;
+        };
         ContentAccessInfo: {
             user_id: string | null;
             has_purchased: boolean;
@@ -335,7 +472,7 @@ declare interface components {
              */
             expires_at: string;
         };
-        /** @description Token response for merchant authentication. Tokens are store-agnostic — no store_context is embedded. */
+        /** @description Token response for merchant authentication. Includes stores the user has access to so the client can prompt for store selection. */
         MerchantAuthenticationResponse: {
             /** @enum {string} */
             token_type: 'Bearer';
@@ -343,6 +480,18 @@ declare interface components {
             refresh_token: string;
             /** Format: date-time */
             expires_at: string;
+            /** @description Stores the authenticated user can manage, for store-selection on the client. */
+            stores: components['schemas']['MerchantLoginStore'][];
+        };
+        /** @description A store the authenticated merchant user has access to. */
+        MerchantLoginStore: {
+            id: string;
+            name: string;
+            /**
+             * @description Derived role. `owner` if the user owns this store; `author` if they have author permissions only.
+             * @enum {string}
+             */
+            role: 'owner' | 'author';
         };
         JWTClaims: {
             /** @description User or Store identifier */
@@ -411,11 +560,14 @@ declare interface components {
             refresh_token?: string;
         };
         ManageableStore: {
-            store_id: string;
-            store_name: string;
+            id: string;
+            name: string;
             store_key: string;
-            /** @enum {string|null} */
-            role: 'owner' | null;
+            /**
+             * @description Derived role. `owner` if the user owns this store; `author` if they have author permissions only.
+             * @enum {string}
+             */
+            role: 'owner' | 'author';
             /** @description Whether the authenticated user has author permissions for this store. */
             is_author: boolean;
             logo: string | null;
@@ -425,12 +577,14 @@ declare interface components {
             user_id: string | null;
             store_id: string;
             /**
-             * @description Named role. `owner` is the only valid named role; non-owner authors have a null role.
+             * @description Ownership flag expressed as a string. `owner` when `is_owner` is true; `null` for non-owner members (authors or uninvited users).
              * @enum {string|null}
              */
             role: 'owner' | null;
             /** @description Whether this user can create and manage their own content. */
             is_author: boolean;
+            /** @description Per-author fee override in basis points (1/100th of a percent). Overrides the store's `default_author_fee_bps` when set. `null` means the store default applies. */
+            author_fee_bps: number | null;
             /** Format: date-time */
             invited_at: string | null;
             /** Format: date-time */
@@ -445,6 +599,8 @@ declare interface components {
              * @default true
              */
             is_author: boolean;
+            /** @description Per-author fee override in basis points (0–10000). Overrides the store's `default_author_fee_bps`. `null` or omitted means the store default applies. */
+            author_fee_bps?: number | null;
         };
         MerchantInviteResponse: {
             invitation_token: string;
@@ -452,6 +608,8 @@ declare interface components {
             /** @enum {string|null} */
             role: 'owner' | null;
             is_author: boolean;
+            /** @description Per-author fee override set at invitation time. */
+            author_fee_bps?: number | null;
             /** Format: date-time */
             expires_at: string;
         };
@@ -541,7 +699,7 @@ declare interface components {
              */
             content_body?: string;
             /**
-             * @description URI of the external resource. For `external_ref` content only.
+             * @description URI of the resource. Required for `external_ref` content; optional for `markdown` content.
              * @example https://vimeo.com/123456789
              */
             content_uri?: string;
@@ -773,7 +931,7 @@ declare interface components {
              */
             started_at?: string;
         };
-        /** @description Create request body for content. Required fields vary by `content_type`: `markdown` requires `content_body`; `external_ref` requires `content_uri`. */
+        /** @description Create request body for content. Required fields vary by `content_type`: `markdown` requires `content_body`; `external_ref` requires `content_uri`. Both types accept an optional `content_uri` link. */
         Content: {
             /**
              * @description The type of content being created.
@@ -788,7 +946,7 @@ declare interface components {
              */
             content_body?: string;
             /**
-             * @description URI of the external resource (Vimeo, YouTube, PDF, etc.). Required when `content_type` is `external_ref`.
+             * @description URI of the resource. Required when `content_type` is `external_ref`; optional for `markdown` content.
              * @example https://vimeo.com/123456789
              */
             content_uri?: string;
@@ -880,7 +1038,60 @@ declare interface components {
                 [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. */
+        /** @description Pagination metadata returned on all paginated list endpoints. */
+        PaginationMeta: {
+            /**
+             * @description Total number of records matching the query.
+             * @example 84
+             */
+            total: number;
+            /**
+             * @description Maximum number of records returned per page.
+             * @example 25
+             */
+            per_page: number;
+            /**
+             * @description The current page number (1-based).
+             * @example 2
+             */
+            current_page: number;
+            /**
+             * @description Total number of pages.
+             * @example 4
+             */
+            total_pages: number;
+            /**
+             * @description Next page number, or null if on the last page.
+             * @example 3
+             */
+            next_page?: number | null;
+            /**
+             * @description Previous page number, or null if on the first page.
+             * @example 1
+             */
+            prev_page?: number | null;
+        };
+        /** @description Paginated list of content items. */
+        PaginatedContentList: {
+            data: components['schemas']['ContentListItem'][];
+            pagination: components['schemas']['PaginationMeta'];
+        };
+        /** @description Paginated list of content sales statistics. */
+        PaginatedSalesList: {
+            data: components['schemas']['SalesStatisticsItem'][];
+            pagination: components['schemas']['PaginationMeta'];
+        };
+        /** @description Paginated list of anonymised buyer statistics. */
+        PaginatedBuyersList: {
+            data: components['schemas']['BuyerStatisticsItem'][];
+            pagination: components['schemas']['PaginationMeta'];
+        };
+        /** @description Paginated list of store members. */
+        PaginatedUsersList: {
+            data: components['schemas']['MerchantUser'][];
+            pagination: components['schemas']['PaginationMeta'];
+        };
+        /** @description Lightweight content representation returned by list and search endpoints. Omits `content_body` to keep list payloads small. Use the detail endpoint (`GET /v1/merchant/:store_id/content/:id`) to retrieve the full body. */
         ContentListItem: {
             id: string;
             /** @enum {string} */
@@ -896,6 +1107,8 @@ declare interface components {
             visibility: 'public' | 'unlisted' | 'private';
             /** Format: date-time */
             created_at: string;
+            /** @description External URI for `external_ref` content; optional supplementary link for `markdown` content. Null when not set. */
+            content_uri: string | null;
             /** @description Namespaced platform ID for `external_ref` content. Null for other types. */
             external_identifier?: string | null;
         };
@@ -1033,12 +1246,42 @@ declare interface components {
 /** Checkout state for a specific piece of content and user. */
 export declare type ContentAccessInfo = components['schemas']['ContentAccessInfo'];
 
+/** Full content item returned by all seller content endpoints. */
+declare type ContentResponse = components['schemas']['ContentResponse'];
+
 /** 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.
+ *
+ * **Common cause — merchant login with the wrong account role:**
+ * `POST /v1/auth/merchant/login/email` and `POST /v1/auth/merchant/login/google`
+ * return `403 Forbidden` (not `401`) when the credentials are valid but the
+ * account has no merchant store associations (e.g. a buyer account used on the
+ * merchant endpoint). The `err.message` will be:
+ * `"This account does not have merchant access. Use a merchant or owner account."`
+ *
+ * Use a different account or ask a store owner to add your account as a member.
+ *
+ * @example
+ * ```ts
+ * import { ForbiddenError, AuthError } from '@ledewire/node'
+ *
+ * try {
+ *   await client.merchant.auth.loginWithGoogle({ id_token })
+ * } catch (err) {
+ *   if (err instanceof ForbiddenError) {
+ *     // Credentials were valid but account has no merchant store access.
+ *     // err.message → "This account does not have merchant access. Use a merchant or owner account."
+ *     console.error('Wrong account role:', err.message)
+ *   } else if (err instanceof AuthError) {
+ *     // Bad credentials or expired token — re-authenticate.
+ *     console.error('Authentication failed:', err.message)
+ *   }
+ * }
+ * ```
  */
 export declare class ForbiddenError extends LedewireError {
     constructor(message: string, code?: number);
@@ -1215,6 +1458,13 @@ export declare class NotFoundError extends LedewireError {
  */
 export declare function parseExpiresAt(expiresAt: string): number;
 
+/**
+ * Platform-level public configuration returned by `GET /v1/config/public`.
+ * No authentication required. Use this to get the Google OAuth client ID
+ * before the user has signed in.
+ */
+export declare type PublicConfigResponse = components['schemas']['PublicConfigResponse'];
+
 /** Request body for creating a purchase. */
 export declare type PurchaseCreateRequest = components['schemas']['PurchaseCreateRequest'];
 
@@ -1229,6 +1479,19 @@ export declare class PurchaseError extends LedewireError {
 /** A purchase record. */
 export declare type PurchaseResponse = components['schemas']['PurchaseResponse'];
 
+/**
+ * Search criteria for seller content search.
+ * At least one field must be supplied. All supplied fields must match (AND logic).
+ */
+export declare interface SellerContentSearchRequest {
+    /** Case-insensitive partial match against the content title. */
+    title?: string;
+    /** Case-insensitive partial match against the content URI (`external_ref` content only). */
+    uri?: string;
+    /** Exact key/value pairs to AND-match against content metadata. */
+    metadata?: Record<string, unknown>;
+}
+
 /** Internal representation of stored authentication tokens. */
 export declare interface StoredTokens {
     accessToken: string;
@@ -1283,13 +1546,18 @@ declare interface TokenManagerOptions {
      */
     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.
+     * Called after a successful background token refresh (not on initial login).
+     * Use for side-effects only — e.g. audit logging, cache invalidation, or
+     * notifying a secondary system when tokens rotate.
+     *
+     * **Do not use this for token persistence.** The `storage` adapter's
+     * `setTokens` is the canonical persistence hook and is already called on
+     * every refresh. Providing both will result in double-writes.
      *
      * @example
      * ```ts
      * onTokenRefreshed: async (tokens) => {
-     *   await redis.set('session:tokens', JSON.stringify(tokens))
+     *   await auditLog.record('token_refreshed', { expiresAt: tokens.expiresAt })
      * }
      * ```
      */