@ledewire/browser 0.6.1 → 0.8.0

package/README.md

@@ -16,7 +16,7 @@ Browser SDK for the [LedeWire](https://api.ledewire.com/api-docs/index.html) con
   // Determine what the visitor needs to do next
   const state = await lw.checkout.state('content-id')
   // state.checkout_state.next_required_action:
-  //   'authenticate' | 'fund_wallet' | 'purchase' | 'view_content'
+  //   'authenticate' | 'fund_wallet' | 'purchase'
 </script>
 ```
 
@@ -48,6 +48,8 @@ const lw = init({
 | `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.user.spendCap`  | Buyer's daily spend cap — read and update the ceiling                           |
+| `lw.user.mcpKeys`   | Manage buyer MCP API keys for the Ledewire MCP server                           |
 | `lw.seller.content` | List, search, and get store content (API key auth)                              |
 
 ## Example: Fetch Google OAuth Client ID Before Sign-In
@@ -63,6 +65,11 @@ google.accounts.id.renderButton(document.getElementById('signin-btn'), { theme:
 
 ## Example: Full Checkout Flow
 
+Purchases are single-use: a completed purchase does not by itself grant access
+again later. `has_purchased` means only "has ever bought" — buying delivers the
+content directly in the `purchases.create()` response, and that response is the
+only place `content_body` / `content_uri` ever appear for a purchase.
+
 ```ts
 const lw = Ledewire.init({ apiKey: 'your_api_key' })
 
@@ -76,21 +83,56 @@ switch (checkout_state.next_required_action) {
     const session = await lw.wallet.createPaymentSession({ amount_cents: 500 })
     // redirect to session.payment_url
     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') {
-      // 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
+  case 'purchase': {
+    // Buying is how the buyer receives the content — the delivery comes back
+    // directly in this response, never from a later GET. Persist it now:
+    // there is no route that serves the same delivery again.
+    const purchase = await lw.purchases.create({ content_id: 'article-123' })
+    await saveDeliveredContent(purchase) // your own persistence, e.g. IndexedDB
+
+    if (purchase.content_body) {
+      // content_body is always plain UTF-8 text on the wire — never
+      // base64-encoded — so no decoding step is needed. What it contains
+      // depends on purchase.content.content_type.
+      if (purchase.content.content_type === 'markdown') {
+        renderMarkdown(purchase.content_body)
+      } else if (purchase.content.content_type === 'html') {
+        // Inline HTML content is seller-supplied and must be sanitised
+        // before insertion — never assign it to innerHTML directly.
+        container.innerHTML = DOMPurify.sanitize(purchase.content_body)
+      }
+    } else if (purchase.content_uri) {
+      // content_uri points at a remote resource (video, PDF, image, or
+      // remote HTML). Check the scheme before navigating or linking to it —
+      // the URI is seller-supplied and a non-http(s) scheme should not be
+      // followed automatically.
+      const uri = new URL(purchase.content_uri)
+      if (['https:', 'http:'].includes(uri.protocol)) {
+        window.location.href = purchase.content_uri
+      }
     }
     break
+  }
+}
+```
+
+## Example: Spend Cap & MCP API Keys
+
+```ts
+// Every buyer starts with a default daily spend cap governing every wallet
+// debit. Exceeding it throws SpendCapReachedError (402) from
+// lw.purchases.create() — funding the wallet does not clear it.
+const cap = await lw.user.spendCap.get()
+if (cap.remaining_cents !== null && cap.remaining_cents < 500) {
+  console.warn(`Only ${cap.remaining_cents}c left before the cap resets at ${cap.resets_at}`)
 }
+await lw.user.spendCap.update({ daily_spend_limit_cents: 2000 }) // raise to $20/day
+
+// MCP API keys authenticate agent requests to the Ledewire MCP server. The
+// secret is shown once at creation — store it immediately.
+const { key, secret } = await lw.user.mcpKeys.create({ label: 'my-agent', can_search: true })
+const keys = await lw.user.mcpKeys.list() // secrets never included
+await lw.user.mcpKeys.revoke(keys[0].id) // to change scopes: revoke + recreate
 ```
 
 ## Example: Seller Content Discovery