@ledewire/browser 0.3.0 → 0.5.0

package/llms.txt

@@ -0,0 +1,290 @@
+# @ledewire/browser
+
+> LedeWire Browser SDK — buyer authentication, checkout, wallet, and purchases for web apps.
+> Works as a CDN script tag (no build step) or as an ESM npm package.
+> npm install @ledewire/browser
+> Source: https://github.com/ledewire/ledewire-js-sdk
+> API docs: https://ledewire.github.io/ledewire-js-sdk/api/
+
+## CDN (no install required)
+
+```html
+<!-- Pin to a major version in production -->
+<script src="https://cdn.jsdelivr.net/npm/@ledewire/browser@0/dist/ledewire.min.js"></script>
+<script>
+  const lw = Ledewire.init({ apiKey: 'your_api_key' })
+</script>
+```
+
+The global is `Ledewire`. All methods return Promises — use async/await or `.then()`.
+
+## npm / ESM install
+
+```bash
+npm install @ledewire/browser
+```
+
+```ts
+import { init, localStorageAdapter } from '@ledewire/browser'
+```
+
+## init() configuration
+
+```ts
+import { init } from '@ledewire/browser'
+import type { BrowserClientConfig } from '@ledewire/browser'
+
+const lw = init({
+  apiKey: string,           // required — your LedeWire platform API key
+
+  baseUrl?: string,         // defaults to 'https://api.ledewire.com'
+
+  // Token persistence — defaults to MemoryTokenStorage (cleared on page unload)
+  storage?: TokenStorage,
+
+  onTokenRefreshed?: (tokens: StoredTokens) => void,
+  onAuthExpired?: () => void,  // called when refresh fails — show login UI
+})
+```
+
+Token refresh is automatic — never call a refresh method manually.
+
+## localStorageAdapter
+
+Persist sessions across page reloads using `localStorage`:
+
+```ts
+import { init, localStorageAdapter } from '@ledewire/browser'
+
+const lw = init({
+  apiKey: 'your_api_key',
+  storage: localStorageAdapter(),     // persists under 'lw_tokens' key
+  onAuthExpired: () => showLoginModal(),
+})
+```
+
+Use `MemoryTokenStorage` (default) for highest security — tokens are never written
+to disk and are cleared when the page unloads.
+
+## Field naming convention
+
+All API response types use `snake_case` field names (`access_token`, `price_cents`,
+`content_uri`), matching the wire format exactly.
+
+SDK-owned types use `camelCase` where they do not map 1:1 to a raw API response
+field: `StoredTokens.accessToken`, `StoredTokens.expiresAt: number` (a converted
+Unix ms timestamp, not the raw `expires_at: string`).
+
+Do not attempt to remap snake_case fields — the SDK has no `transformKeys` option.
+
+## Complete method reference
+
+### lw.config
+
+```ts
+lw.config.getPublic() → Promise<PublicConfigResponse>
+// { google_client_id: string, ... }
+// Safe to call before authentication — use to get the Google Client ID for sign-in UI.
+```
+
+### lw.auth (buyer and seller auth)
+
+```ts
+lw.auth.signup(body)                           → Promise<AuthenticationResponse>
+lw.auth.loginWithEmail({ email, password })    → Promise<AuthenticationResponse>
+lw.auth.loginWithGoogle({ id_token })          → Promise<AuthenticationResponse>
+lw.auth.loginWithApiKey({ key, secret? })      → Promise<AuthenticationResponse>
+// key-only → view permission (read-only, sufficient for lw.seller.content.*)
+// key + secret → full permission (read/write)
+lw.auth.logout()                               → Promise<void>
+lw.auth.requestPasswordReset({ email })        → Promise<AuthPasswordResetResponse>
+lw.auth.resetPassword({ email, reset_code, password }) → Promise<AuthPasswordResetResponse>
+```
+
+Tokens are stored automatically after every successful login.
+
+### lw.checkout
+
+```ts
+lw.checkout.state(contentId: string)  → Promise<CheckoutStateResponse>
+```
+
+Use this to determine what the current visitor needs to do before accessing content:
+
+```ts
+const { checkout_state } = await lw.checkout.state('article-id')
+
+switch (checkout_state.next_required_action) {
+  case 'authenticate':
+    // Show login/signup UI
+    break
+  case 'fund_wallet':
+    // Show wallet funding UI (checkout_state.has_sufficient_funds === false)
+    break
+  case 'purchase':
+    // Show purchase confirmation UI
+    break
+  case 'view_content':
+    // User has access — fetch and render the content
+    break
+}
+```
+
+### lw.wallet
+
+```ts
+lw.wallet.balance()                                    → Promise<WalletBalanceResponse>
+// { balance_cents: number }
+
+lw.wallet.transactions(params?: PaginationParams)      → Promise<{ data: WalletTransactionItem[], pagination: PaginationMeta }>
+
+lw.wallet.createPaymentSession({ amount_cents: number }) → Promise<WalletPaymentSessionResponse>
+// { payment_url: string, session_id: string, ... } — redirect user to payment_url
+
+lw.wallet.getPaymentStatus(sessionId: string)          → Promise<WalletPaymentStatusResponse>
+// Poll after return from payment redirect to confirm funding
+```
+
+### lw.purchases
+
+```ts
+lw.purchases.create({ content_id: string })           → Promise<PurchaseResponse>
+lw.purchases.list(params?: PaginationParams)          → Promise<{ data: PurchaseResponse[], pagination: PaginationMeta }>
+lw.purchases.get(purchaseId: string)                  → Promise<PurchaseResponse>
+```
+
+### lw.content
+
+```ts
+lw.content.getWithAccess(contentId: string, options?) → Promise<ContentWithAccessResponse>
+// Returns content payload + access info. Requires a valid buyer session.
+// content_type: 'markdown' | 'external_ref'
+// content_body: base64-encoded string (use atob() to decode markdown)
+// content_uri: URL for external_ref content (Vimeo, YouTube, PDF, etc.)
+```
+
+### lw.seller.content (requires API key login)
+
+Read-only operations scoped to the authenticated seller's store.
+Store identity is derived server-side from the token — no `store_id` needed.
+
+```ts
+// 1. Obtain a view token (key-only is sufficient)
+await lw.auth.loginWithApiKey({ key: 'your_api_key' })
+
+// 2. List all store content
+lw.seller.content.list()                              → Promise<ContentResponse[]>
+
+// 3. Search by title, URI, or metadata (AND logic — at least one field required)
+lw.seller.content.search({ title?: string, uri?: string, metadata?: Record<string, unknown> })
+                                                      → Promise<ContentResponse[]>
+
+// 4. Fetch a single item
+lw.seller.content.get(contentId: string)              → Promise<ContentResponse>
+```
+
+## Full checkout flow example
+
+```ts
+const lw = Ledewire.init({ apiKey: 'your_api_key' })
+
+const { checkout_state } = await lw.checkout.state('article-123')
+
+switch (checkout_state.next_required_action) {
+  case 'authenticate':
+    await lw.auth.loginWithEmail({ email, password })
+    break
+
+  case 'fund_wallet':
+    const session = await lw.wallet.createPaymentSession({ amount_cents: 500 })
+    window.location.href = session.payment_url  // Stripe checkout
+    break
+
+  case 'purchase':
+    await lw.purchases.create({ content_id: 'article-123' })
+    break
+
+  case 'view_content':
+    const { content_type, content_body, content_uri } =
+      await lw.content.getWithAccess('article-123')
+    if (content_type === 'markdown') {
+      renderMarkdown(atob(content_body))  // base64-decode then render
+    } else {
+      window.location.href = content_uri  // redirect to gated video/PDF
+    }
+    break
+}
+```
+
+## Google OAuth sign-in setup
+
+```ts
+// Fetch the platform's Google Client ID before the user signs in:
+const { google_client_id } = await lw.config.getPublic()
+google.accounts.id.initialize({
+  client_id: google_client_id,
+  callback: async ({ credential }) => {
+    await lw.auth.loginWithGoogle({ id_token: credential })
+  },
+})
+google.accounts.id.renderButton(document.getElementById('signin-btn'), { theme: 'outline' })
+```
+
+## Key types
+
+```ts
+interface CheckoutStateResponse {
+  content_id: string
+  content_title: string
+  price_cents: number
+  checkout_state: {
+    is_authenticated: boolean
+    has_sufficient_funds: boolean | null  // null when not authenticated
+    has_purchased: boolean
+    next_required_action: 'authenticate' | 'fund_wallet' | 'purchase' | 'view_content'
+  }
+}
+
+interface StoredTokens {
+  accessToken: string
+  refreshToken: string
+  expiresAt: number  // Unix timestamp (ms)
+}
+
+interface TokenStorage {
+  getTokens(): Promise<StoredTokens | null>
+  setTokens(tokens: StoredTokens): Promise<void>
+  clearTokens(): Promise<void>
+}
+```
+
+## Error classes
+
+All errors extend `LedewireError`. Import named subclasses for actionable handling:
+
+```ts
+import { LedewireError, AuthError, ForbiddenError, NotFoundError, PurchaseError } from '@ledewire/browser'
+
+class LedewireError extends Error {
+  statusCode: number        // HTTP status code
+  code: number | undefined  // machine-readable code from API body
+  message: string           // human-readable description from API body
+}
+
+class AuthError extends LedewireError {}       // 401 — bad credentials / session expired
+class ForbiddenError extends LedewireError {}  // 403 — authenticated but access denied
+class NotFoundError extends LedewireError {}   // 404 — resource not found
+class PurchaseError extends LedewireError {}   // 409/422 — purchase validation failure
+```
+
+```ts
+try {
+  await lw.purchases.create({ content_id: 'article-123' })
+} catch (err) {
+  if (err instanceof AuthError) {
+    showLoginModal()
+  } else if (err instanceof PurchaseError) {
+    showError('Purchase failed: ' + err.message)
+  }
+}
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ledewire/browser",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "LedeWire SDK for browsers — embed a paywall with a single script tag",
   "type": "module",
   "exports": {
@@ -15,7 +15,8 @@
   "types": "./dist/index.d.ts",
   "files": [
     "dist",
-    "README.md"
+    "README.md",
+    "llms.txt"
   ],
   "keywords": [
     "ledewire",