@invonetwork/web-sdk 0.2.0 → 0.3.0

package/README.md

@@ -1,8 +1,39 @@
 # @invonetwork/web-sdk
 
-INVO Web SDK for partner **web** platforms — **currency purchase** + **passkey (WebAuthn)** verification for cross-game **sends/transfers**. The web analog of the Unity/UE plugins.
+First-party TypeScript SDK for integrating **INVO** into partner **web** platforms (storefronts, web games, dashboards). It wraps INVO's web money flows behind a typed, versioned API — the web analog of the Unity/Unreal plugins.
 
-> **Status:** v0.1.0. The backend this wraps is **live** — the INVO-hosted checkout page, sessions, rails, and webhooks are deployed on sandbox + production, so you can build and test against sandbox today. Full, current API reference + flow docs: **https://docs.invo.network/docs/currency-purchase** and **https://docs.invo.network/docs/game-developer-integration**.
+> **Status:** `v0.3.0`, published on npm. The backend it wraps is **live** on sandbox + production, so you can build and test against sandbox today.
+> Canonical partner reference: **https://docs.invo.network/docs/currency-purchase** and **https://docs.invo.network/docs/game-developer-integration**.
+
+## What it does
+
+Four money flows plus passkey (WebAuthn) authentication, split across a trusted server entry and an untrusted browser entry:
+
+| Flow | Direction | Real money? | Passkey? | Where |
+|---|---|---|---|---|
+| **Currency purchase** | real money **→** game currency | yes (card/rails) | no | server initiates, browser opens hosted checkout |
+| **Item purchase** | game currency **→** in-game item | no (balance debit) | no | server only |
+| **Send** | currency **→** another player (cross-game) | no | yes (sender approves) | server initiates, browser approves/claims |
+| **Transfer** | currency **→** another player (transfer rail) | no | yes (sender approves) | server initiates, browser approves/claims |
+
+The **game secret stays on your server**; the browser only ever holds a short-lived, game-scoped **player token**.
+
+## Contents
+
+- [Install](#install)
+- [Architecture & the two entry points](#architecture--the-two-entry-points)
+- [Deployment prerequisites](#deployment-prerequisites)
+- [Configuration](#configuration)
+- [Currency purchase (real money in)](#currency-purchase-real-money-in)
+- [Item purchase (spend game currency)](#item-purchase-spend-game-currency)
+- [Player balance](#player-balance)
+- [Sends & transfers (move currency between players)](#sends--transfers-move-currency-between-players)
+- [Passkeys (enroll, approve, link)](#passkeys-enroll-approve-link)
+- [Webhooks](#webhooks)
+- [Resilience & observability](#resilience--observability)
+- [Errors](#errors)
+- [API reference](#api-reference)
+- [Scripts & versioning](#scripts--versioning)
 
 ## Install
 
@@ -10,203 +41,415 @@ INVO Web SDK for partner **web** platforms — **currency purchase** + **passkey
 npm install @invonetwork/web-sdk
 ```
 
-> Published under the INVO-owned `@invonetwork` npm org. (Until the first `npm publish`, develop with `npm link` or a local install.)
+Node ≥ 18 on the server (uses the global `fetch`). The browser build ships ESM + CJS + types.
 
-## Two entry points (the game secret never reaches the browser)
+## Get your account & game secret (INVO console)
 
-| Import | Runs | Holds | Does |
-|---|---|---|---|
-| `@invonetwork/web-sdk/server` | your server (Node ≥18) | the **game secret** | mint player token, initiate send/transfer, currency purchase, item purchase |
-| `@invonetwork/web-sdk` | the browser | a short-lived **player token** | enroll passkey, approve, self-claim |
+Sign up, create your game, and copy its credentials (the **game secret**, plus your WebAuthn **RP ID / origins**) in the INVO console. Use the console that matches the environment you're building against:
 
-## Base URLs
+| Environment | Console — sign up, manage games, copy your game secret | API `baseUrl` |
+|---|---|---|
+| **Testing / sandbox** | **https://dev.console.invo.network** | `https://sandbox.invo.network/sandbox` |
+| **Production** | **https://console.invo.network** | `https://invo.network` |
 
-- Production: `https://invo.network`
-- Sandbox: `https://sandbox.invo.network/sandbox`
+Build and test against the **dev console + sandbox** first, then switch to the **production console + `https://invo.network`** for launch. **Each environment has its own game secret — never mix them**, and keep the secret server-side only.
 
-`baseUrl` must be `https://` (the game secret and player token travel in request headers); `http://localhost` is allowed for local development only.
+## Architecture & the two entry points
 
-## Server (Node)
+```
+┌──────────────────────────────┐         ┌──────────────────────────────┐
+│  YOUR SERVER (trusted)        │         │  THE BROWSER (untrusted)      │
+│  @invonetwork/web-sdk/server  │         │  @invonetwork/web-sdk         │
+│                               │ mint    │                               │
+│  • holds X-Game-Secret-Key    │ ──────► │  • holds short-lived token    │
+│  • mintPlayerToken()          │ token   │    (~15 min, game-scoped)     │
+│  • initiateSend/Transfer()    │         │  • enrollPasskey()            │
+│  • createCheckout()           │         │  • approveSend/Transfer()     │
+│  • purchaseCurrency()         │         │  • confirmReceipt*()          │
+│  • purchaseItem()             │         │  • linkDevice()               │
+└───────────────┬───────────────┘         └───────────────┬──────────────┘
+                └──────────────► INVO BACKEND ◄────────────┘
+```
 
-```ts
-import { InvoServer } from "@invonetwork/web-sdk/server";
+| Import | Runs on | Holds | Responsibilities |
+|---|---|---|---|
+| `@invonetwork/web-sdk/server` | your backend (Node ≥18) | the **game secret** | mint player tokens; initiate sends/transfers; currency purchase; item purchase |
+| `@invonetwork/web-sdk` | the browser | a short-lived **player token** | passkey enroll, approve, self-claim, device link |
 
-const invo = new InvoServer({
-  gameSecret: process.env.INVO_GAME_SECRET!,   // server-side only
-  baseUrl: "https://sandbox.invo.network/sandbox",
-});
+**Never import `/server` into browser code** — it carries the game secret. The two entries are built separately for exactly this reason.
 
-// 1. mint a short-lived token for the browser
-const { token } = await invo.mintPlayerToken({ playerEmail: "p@example.com" });
+## Deployment prerequisites
 
-// 2a. buy currency — hosted checkout (recommended; INVO's page handles the processor)
-const { checkoutUrl } = await invo.createCheckout({
-  playerEmail: "p@example.com",
-  usdAmount: "20.00",
-  rail: "platform",   // optional: "platform" (card, default) | "game" | "steam"
-  metadata: { yourOrderId: "ord_42" },  // echoed back on the purchase.completed webhook
-});
-// → open checkoutUrl in a WebView/redirect or an iframe (see "Consuming the checkout")
+INVO provisions these per tenant before the flows go live (most are super_admin-only, set by INVO — coordinate with your INVO contact):
 
-// 2b. or initiate a send; inspect verificationMethod
-const send = await invo.initiateSend({
-  clientRequestId: crypto.randomUUID(),
-  senderPlayerName: "P", senderPlayerEmail: "p@example.com", senderPlayerPhone: "+15555550100",
-  receiverPlayerEmail: "q@example.com", receiverPlayerPhone: "+15555550111",
-  receivingGameId: 123456, amount: "50",
-});
-if (send.verificationMethod === "in_app") {
-  // hand send.transactionId + the player token to the browser to approve via passkey
-} else if (send.verificationMethod === "sms") {
-  // sender not enrolled — fall back to the SMS-PIN UI
-} else if (send.guardianApproval) {
-  // minor/guardian path (HTTP 202): pending guardian approval — do NOT show the PIN UI
-}
-```
+**For sends/transfers + passkeys**
+- `SDK_TRANSFER_VERIFICATION_ENABLED` (master) — on.
+- `SDK_WEBAUTHN_ENABLED` (master) — on.
+- `SDK_TRANSFER_CONFIRM_RECEIPT_ENABLED` — required for **transfer** self-claim.
+- Tenant migrated (`games.sdk_verification_enabled`).
+- **Per-tenant RP ID + origins** (`webauthn_rp_id`, `webauthn_origins`). There's no separate "webauthn on" flag — *the presence of a valid RP ID is the gate*. Until it's set, WebAuthn endpoints return `403 WEBAUTHN_NOT_ENABLED_FOR_TENANT`. **You must serve your integration from an origin listed in `webauthn_origins`,** or passkeys won't validate.
+
+**For currency purchase**
+- `platform` (card) rail is always on; `game`/`steam` rails are off by default and each gated by their own flag + per-game config.
+- Honors the platform `purchases` kill switch (`503 flow_paused` when paused).
 
-## Browser
+**For item purchase**
+- The game must be in `live` or `testing` state (else `403`). No passkey/payment flags involved — it's a balance debit.
+
+**On your side:** store the game secret in server-side config/secrets (never ship it to the browser), and expose a small endpoint that calls `mintPlayerToken` so the browser can fetch/refresh its token.
+
+## Configuration
 
 ```ts
+import { InvoServer } from "@invonetwork/web-sdk/server";
 import { InvoClient } from "@invonetwork/web-sdk";
 
-const invo = new InvoClient({
-  token,
+const server = new InvoServer({
+  gameSecret: process.env.INVO_GAME_SECRET!,       // server-side only
+  baseUrl: "https://sandbox.invo.network/sandbox", // prod: "https://invo.network"
+  timeoutMs: 30_000,                               // optional, default 30s
+  maxRetries: 2,                                   // optional, default 2 (0 disables)
+  // retryBaseDelayMs: 250,                          // optional backoff base
+  // fetch: customFetch,                            // optional override
+  // hooks: { onRequest, onResponse, onError },     // optional observability (see below)
+});
+
+const client = new InvoClient({
+  token,                                           // from your /mint endpoint
   baseUrl: "https://sandbox.invo.network/sandbox",
-  // Optional: player tokens live ~15 min. If a call fails with SDK_TOKEN_EXPIRED,
-  // the SDK calls this once for a fresh token (re-minted by your backend) and
-  // retries the request transparently.
-  refreshToken: () => fetch("/invo/token").then((r) => r.json()).then((j) => j.token),
+  refreshToken: () =>                              // optional: auto re-mint + retry on token expiry
+    fetch("/invo/token", { method: "POST" }).then((r) => r.json()).then((j) => j.token),
 });
+```
 
-await invo.enrollPasskey();                       // once per user
-await invo.approveSend(transactionId);            // or approveTransfer(...)
-await invo.confirmReceiptSend(transactionId);     // recipient self-claim
+**Base URLs** (manage each environment in its [console](#get-your-account--game-secret-invo-console))
+- Production: `https://invo.network` — console: `https://console.invo.network`
+- Sandbox / testing: `https://sandbox.invo.network/sandbox` — console: `https://dev.console.invo.network` (sandbox prepends the `/sandbox` prefix; the SDK absorbs it via `baseUrl`)
 
-// Interchangeable methods (optional): prove an already-enrolled method (e.g. the
-// INVO app device key) to authorize adding this passkey, then enroll it.
-await invo.linkDevice(linkId);                     // → { status: "authorized" }
-await invo.enrollPasskey();
-```
+`baseUrl` must be `https://` — the game secret and player token travel in request headers, so plaintext is rejected. `http://localhost` is allowed for local dev only.
 
-Currency purchase has **no browser SDK method** — the server mints `checkoutUrl`; the browser just opens it.
+**Player tokens** live ~15 minutes and are game-scoped. Mint one per browser session. If you pass `refreshToken` to `InvoClient`, the SDK transparently re-mints and retries once on `SDK_TOKEN_EXPIRED` (it re-runs the whole passkey ceremony so it never replays a single-use challenge).
 
-## Consuming the checkout (browser)
+---
 
-`createCheckout` returns a `checkoutUrl` (15-min, single-use). Open it either way:
+## Currency purchase (real money in)
 
-- **WebView / full-page redirect** (works everywhere, no setup): on success the page redirects to your `successUrl`.
-- **Embedded `<iframe>`** — **works by default** (any https origin may frame it; no allow-listing): the page does *not* redirect your top window — listen for the `INVO_CHECKOUT_COMPLETE` postMessage.
+Buy game currency with real money. Authenticated by the **payment rail**, not a passkey — there's no WebAuthn step. Two paths:
+
+### Hosted checkout (recommended — PCI-light, you never touch card data)
+
+```ts
+// SERVER
+const { checkoutUrl, sessionId, expiresAt } = await server.createCheckout({
+  playerEmail: "p@example.com",
+  usdAmount: "20.00",                  // USD, 0 < x ≤ 999.99
+  rail: "platform",                    // optional: "platform" (default) | "game" | "steam"
+  successUrl: "https://you/buy/ok",
+  cancelUrl: "https://you/buy/cancel",
+  metadata: { yourOrderId: "ord_42" }, // echoed on the purchase.completed webhook
+});
+// → send the browser to checkoutUrl (single-use, ~15 min)
+```
+
+Open `checkoutUrl` either way:
+
+- **Full-page redirect / WebView** — works everywhere; on success the page redirects to your `successUrl`.
+- **Embedded `<iframe>`** — works by default from any https origin (no allow-listing). The page does *not* redirect your top window; listen for the `INVO_CHECKOUT_COMPLETE` postMessage:
 
 ```ts
+// BROWSER
 const iframe = document.createElement("iframe");
 iframe.src = checkoutUrl;
 iframe.style.cssText = "width:440px;height:720px;border:0";
 document.body.appendChild(iframe);
 
 window.addEventListener("message", (e) => {
-  if (e.origin !== "https://invo.network") return;      // sandbox: "https://sandbox.invo.network"
+  if (e.origin !== "https://invo.network") return;   // sandbox: "https://sandbox.invo.network"
   if (e.data?.type === "INVO_CHECKOUT_COMPLETE") {
-    // UX hint only (unsigned). data = { status:'success', new_balance, currency_name, transaction_id }
+    // UX hint ONLY (unsigned). data = { status, new_balance, currency_name, transaction_id }
     refreshBalanceOptimistically(e.data.data.new_balance);
   }
 });
 ```
 
-The hosted page handles **card entry, saved cards, and 3-D Secure** (including a top-level break-out when embedded). You build no payment UI and never touch card data.
+The hosted page handles card entry, saved cards, and 3-D Secure (with a top-level break-out when framed). **Grant currency off the `purchase.completed` webhook**, not the postMessage hint. Currency purchase has **no browser SDK method** — the browser only opens the URL.
+
+### Payment rails (neutral names)
+
+The `rail` selects the in-page experience — all branded INVO, no visible redirect:
+- `"platform"` (default) — card checkout.
+- `"game"` — regional / game-store methods.
+- `"steam"` — Steam titles hand off to the in-client Steam flow.
+
+Provider/processor names are an internal detail and never appear in the API.
+
+### Direct rail (advanced — you tokenize the card yourself)
+
+```ts
+const purchase = await server.purchaseCurrency({
+  playerEmail: "p@example.com",
+  usdAmount: "20.00",
+  purchaseReference: crypto.randomUUID(), // idempotency key, required
+  rail: "platform",
+  paymentMethodId: "pm_...",              // a tokenized payment method
+});
+// purchase.status:
+//   "success"          → captured, purchase.newBalance updated
+//   "requires_action"  → 3-D Secure: run the client action with purchase.clientSecret,
+//                        then call server.confirmPayment({ paymentIntentId })
+//   "pending_payment"  → redirect the browser to purchase.paymentUrl (game rail)
+```
+`rail: "steam"` is rejected here (`WRONG_RAIL_ENDPOINT`) — Steam uses its own in-client flow. Reconcile with `server.getOrderDetails({ orderId })`. Most browser integrations should use hosted checkout instead.
+
+---
+
+## Item purchase (spend game currency)
+
+Spend the currency a player **already owns** to buy an in-game item. A balance debit — **no real money, no payment rail, no passkey** — server-side only. Amounts are in **game-currency units** (not USD).
+
+```ts
+const item = await server.purchaseItem({
+  clientRequestId: crypto.randomUUID(),   // idempotency key, unique per game
+  playerEmail: "p@example.com",
+  playerName: "P",
+  itemId: "sword_001",
+  itemName: "Legendary Sword",
+  itemQuantity: 1,                        // integer 1..1000
+  unitPrice: "100.00",                    // > 0 and ≤ 999999.99
+  totalPrice: "100.00",                   // must equal unitPrice × itemQuantity (±0.01)
+  // optional: playerPhone, itemDescription, itemCategory
+});
+// item.status === "success"
+// item.newBalance / item.previousBalance / item.currencyName
+// item.transactionId / item.orderId
+// item.financialBreakdown { total_paid, developer_revenue, platform_fee }
+```
+
+- **Grant the item off the `item.purchased` webhook**, not just this response. INVO debits currency and records the purchase; **your game owns the item catalog and grants the item.** The webhook fires atomically with the spend.
+- **Idempotent** on `clientRequestId` — a duplicate throws `409` (`err.isDuplicateRequest`).
+- **Insufficient balance** throws `400` (`err.isInsufficientBalance`; `required_amount` + `current_balance` on `err.body`).
+- **Throttled** calls throw `429` with `err.retryAfter` (seconds).
+- Client-side validation (missing fields, quantity outside `1..1000`, bad price, total ≠ unit×qty) throws `INVALID_INPUT` **before** any network call.
+- Fee split: **90% developer / 10% INVO** by default (per-partner override). Not guardian-gated.
+
+**Companion reads:** `server.getItemPurchaseHistory({ playerEmail, limit?, offset? })` and `server.getItemOrderDetails({ orderId | transactionId | clientRequestId })` (pass **exactly one** id — use `clientRequestId` for recovery: "did this purchase complete?").
+
+---
 
-**Completion is authoritative via the `purchase.completed` webhook** (HMAC-signed). **Dedupe on `X-Invo-Idempotency-Key`** (stable across retries/replays — *not* `X-Invo-Event-Id`, which changes per delivery). Treat `INVO_CHECKOUT_COMPLETE` as a UX hint; grant currency off the webhook (or re-read the balance).
+## Player balance
 
-## Payment rails (neutral names)
+Read a player's currency balances (server-side, game-secret) by email or player id:
 
-The `rail` passed to `createCheckout` selects the in-page experience — all branded as INVO, no visible redirect:
-- `"platform"` (default) — card checkout on the hosted page.
-- `"game"` — regional / game-store methods, embedded in-page.
-- `"steam"` — Steam titles use the dedicated Steam flow; a `steam` session only shows an in-client hand-off, it doesn't drive the purchase.
+```ts
+const { balances, summary } = await server.getPlayerBalance({ playerEmail: "p@example.com" });
+// balances: [{ currencyName, availableBalance, reservedBalance, totalBalance, currencySymbol, raw }]
+// or: server.getPlayerBalance({ playerId: 12345 })
+```
 
-Provider/processor names are an internal backend detail and never appear in the API. (`purchaseCurrency()` on the server is an advanced direct path for partners who tokenize cards themselves — most integrations should use `createCheckout`.)
+---
 
-## Sends & transfers (move existing game currency, no real money)
+## Sends & transfers (move currency between players)
 
-Distinct from *purchase* (which brings real money in), **sends** and **transfers** move
-already-owned game currency from one player to another and are authorized by the
-sender's **passkey** (or an SMS PIN if they aren't enrolled). The two are parallel
-flows with the same shape:
+Move already-owned game currency from one player to another, authorized by the **sender's passkey** (or an SMS PIN if they aren't enrolled). **Send** and **transfer** are parallel flows:
 
 | | Send | Transfer |
 |---|---|---|
-| Initiate (server) | `initiateSend` → `/api/currency-sends/initiate-send` | `initiateTransfer` → `/api/transfers/initiate-transfer` |
-| Parties | `sender*` / `receiver*`, `receivingGameId` | `source*` / `target*`, `targetGameId` |
-| Approve (browser) | `approveSend` | `approveTransfer` (also returns the sender's **claim code**) |
+| Initiate (server) | `initiateSend` | `initiateTransfer` |
+| Parties | `sender*` / `receiver*` + `receivingGameId` | `source*` / `target*` + `targetGameId` |
+| Approve (browser) | `approveSend` | `approveTransfer` — also returns the sender's **claim code** |
 | Recipient claim (browser) | `confirmReceiptSend` | `confirmReceiptTransfer` |
 
-### End-to-end (transfer shown; send is identical with `*Send` methods)
-
 ```ts
 // 1. SERVER — initiate, then branch on how the sender must verify
-const t = await invo.initiateTransfer({
+const t = await server.initiateTransfer({
   clientRequestId: crypto.randomUUID(),
   sourcePlayerName: "P", sourcePlayerEmail: "p@example.com", sourcePlayerPhone: "+15555550100",
   targetPlayerEmail: "q@example.com", targetPlayerPhone: "+15555550111",
   targetGameId: 123456, amount: "50",
 });
-// t.verificationMethod: "in_app" (passkey) | "sms" (PIN fallback) | undefined (+ t.guardianApproval on the minor/guardian path)
+// (initiateSend uses sender*/receiver* + receivingGameId instead)
 
-// 2. BROWSER — the sender approves with their passkey (hand them t.transactionId + the player token)
-const approved = await invo.approveTransfer(t.transactionId);
-// approved.claimCode + approved.claimCodeExpiresAt — deliver to the recipient if they can't self-claim
+switch (true) {
+  case t.verificationMethod === "in_app":     // sender is passkey-enrolled → approve in the browser
+  case t.verificationMethod === "sms":        // not enrolled, a PIN was sent → show a PIN-entry fallback
+  case !!t.guardianApproval:                  // minor/guardian path (HTTP 202) → do NOT show the PIN UI
+}
 
-// 3. BROWSER — the recipient claims. If they have a passkey, self-claim; else fall back to the claim code.
+// 2. BROWSER — the sender approves with their passkey (give them t.transactionId + the player token)
+const approved = await client.approveTransfer(t.transactionId);   // or approveSend(...)
+// approved.claimCode + approved.claimCodeExpiresAt (transfer only) — deliver if the recipient can't self-claim
+
+// 3. BROWSER — the recipient claims with their passkey; fall back to the claim code if not enrolled
 try {
-  await invo.confirmReceiptTransfer(t.transactionId);
+  await client.confirmReceiptTransfer(t.transactionId);           // or confirmReceiptSend(...)
 } catch (e) {
   if (e instanceof InvoError && e.isReceiverNotEnrolled) {
-    // recipient has no passkey here → show a claim-code entry UI using approved.claimCode
+    // recipient has no passkey here → show claim-code entry using approved.claimCode
   } else throw e;
 }
 ```
 
-- **`verificationMethod`** comes from initiate: `"in_app"` → passkey approve; `"sms"` → the sender wasn't enrolled and a PIN was sent (build a PIN-entry fallback); `undefined` with `guardianApproval` → minor/guardian path (do **not** show the PIN UI).
-- **Claim codes** are only returned by `approveTransfer` (transfer flow). They're the out-of-band fallback when the recipient isn't passkey-enrolled.
-- **`isReceiverNotEnrolled`** on the `confirmReceipt*` error is the explicit signal to switch to claim-code entry.
-- Transfer self-claim additionally requires the tenant's `SDK_TRANSFER_CONFIRM_RECEIPT_ENABLED` flag; if it's off, surface the claim-code path instead.
+- **`verificationMethod`** (from initiate): `"in_app"` → passkey approve; `"sms"` → un-enrolled, PIN sent; `undefined` + `guardianApproval` → minor/guardian (HTTP 202), do **not** show the PIN UI.
+- **Claim codes** are returned only by `approveTransfer`; they're the out-of-band fallback when the recipient isn't enrolled.
+- **`err.isReceiverNotEnrolled`** on `confirmReceipt*` is the explicit signal to switch to claim-code entry.
+- Transfer self-claim additionally requires `SDK_TRANSFER_CONFIRM_RECEIPT_ENABLED`; if it's off, surface the claim-code path.
+
+---
 
-## Item purchase (spend game currency on an in-game item)
+## Passkeys (enroll, approve, link)
 
-Distinct from *currency purchase* (real money **in**): an **item purchase spends the
-currency a player already owns** to buy an in-game item. It's a balance debit — **no
-real money, no payment rail, no passkey** — authenticated server-side by the game
-secret, so it lives on the **`/server`** entry. Amounts are in **game-currency units**
-(not USD).
+Passkeys (WebAuthn) replace the SMS PIN for approving sends/transfers. The browser SDK wraps `navigator.credentials.create/get`, base64url encoding, challenge round-trips, and error mapping.
 
 ```ts
-const item = await invo.purchaseItem({
-  clientRequestId: crypto.randomUUID(),  // idempotency key, unique per game
-  playerEmail: "p@example.com",
-  playerName: "P",
-  itemId: "sword_001",
-  itemName: "Legendary Sword",
-  itemQuantity: 1,
-  unitPrice: "100.00",
-  totalPrice: "100.00",                  // must equal unitPrice × itemQuantity (±0.01)
-  // optional: playerPhone, itemDescription, itemCategory
+// Enroll once per user (no-op to call again — the backend excludes already-enrolled credentials)
+await client.enrollPasskey();
+
+// Interchangeable methods (optional): prove an already-enrolled method (e.g. the INVO app
+// device key) to authorize adding THIS passkey, then enroll. Without this, enrolling a second
+// method is blocked with ENROLLMENT_REQUIRES_PROOF.
+await client.linkDevice(linkId);   // → { status: "authorized" }
+await client.enrollPasskey();
+```
+
+- **User verification is required** on every approve/claim (a missing-UV assertion fails closed).
+- Challenges are single-use and bound to `{flow}:{transactionId}`.
+- The SDK passes the backend's WebAuthn options through unchanged (it does not hard-code `pubKeyCredParams`/`timeout`/`attestation`).
+
+---
+
+## Webhooks
+
+The synchronous responses are for UX; **reconcile and grant value off webhooks.** They're HMAC-signed; **dedupe on the `X-Invo-Idempotency-Key` header** (stable across retries/replays — *not* `X-Invo-Event-Id`, which changes per delivery).
+
+### Verify a webhook (server)
+
+The SDK ships the signature check so you don't hand-roll HMAC. Pass the **raw** request bytes (never a re-serialized object) and the `X-Invo-Signature` header:
+
+```ts
+import { verifyWebhook, InvoError } from "@invonetwork/web-sdk/server";
+
+// e.g. Express: app.post("/invo/webhooks", express.raw({ type: "application/json" }), handler)
+function handler(req, res) {
+  let event;
+  try {
+    event = verifyWebhook(req.body, req.get("X-Invo-Signature"), process.env.INVO_WEBHOOK_SECRET!);
+  } catch (e) {
+    return res.status(400).send((e as InvoError).code); // bad signature / stale / malformed
+  }
+  if (alreadyProcessed(req.get("X-Invo-Idempotency-Key"))) return res.status(200).end(); // dedupe
+
+  switch (event.event_type) {
+    case "purchase.completed": grantCurrency(event.data); break; // event.data is typed
+    case "item.purchased":     grantItem(event.data);     break;
+    // transfer.* , payout.status_changed , …
+  }
+  res.status(200).end(); // 2xx fast; offload slow work
+}
+```
+
+`verifyWebhook` does constant-time HMAC-SHA256 over `${t}.${rawBody}`, enforces a 5-minute replay window, and accepts an **array of secrets** during rotation (`verifyWebhook(body, sig, [oldSecret, newSecret])`). It returns a typed `InvoWebhookEvent` (discriminate on `event_type`) and throws `InvoError` (`WEBHOOK_SIGNATURE_INVALID` / `WEBHOOK_TIMESTAMP_EXPIRED` / `WEBHOOK_MALFORMED` / `WEBHOOK_SECRET_MISSING`) on any failure. **De-dupe yourself on `X-Invo-Idempotency-Key`** — the SDK verifies, it doesn't track delivery.
+
+### Event types
+
+| Event | Fires for | Use it to |
+|---|---|---|
+| `purchase.completed` | every currency-purchase rail | grant currency (payload: `transaction_id, order_id, player_email, identity_id, usd_amount, currency_amount, currency_name, new_balance, rail`) |
+| `purchase.failed` / `purchase.disputed` | `platform` rail only | handle failures/disputes |
+| `purchase.refunded` | `game` / `steam` rails | handle refunds |
+| `item.purchased` | every item purchase | **grant the in-game item** (payload includes `transaction_id, order_id, player_email, identity_id, item_id, item_name, item_quantity, unit_price, total_price, currency_name, new_balance, fee_breakdown`) |
+
+Don't block waiting on `purchase.failed` for the `game`/`steam` rails — they only emit `completed`/`refunded`. Reconcile off `*.completed` + the status endpoints.
+
+---
+
+## Resilience & observability
+
+- **Automatic retries.** Transient failures — network errors/timeouts, `429` (honoring `retry_after`), and `5xx` — are retried with exponential backoff + jitter. Configure with `maxRetries` (default `2`, set `0` to disable) and `retryBaseDelayMs` (default `250`). Mutating calls carry idempotency keys, so retries are safe; set `maxRetries: 0` if you'd rather handle `429` abuse-throttles yourself.
+- **Hooks.** Pass `hooks` to either client for tracing/metrics — all best-effort (a throwing hook never breaks a request):
+
+```ts
+new InvoServer({
+  /* … */,
+  hooks: {
+    onRequest:  ({ method, url, attempt }) => {},
+    onResponse: ({ status, durationMs, requestId, attempt }) => {},
+    onError:    ({ error, willRetry, attempt }) => {},
+  },
 });
-// item.status === "success", item.newBalance (post-spend), item.previousBalance,
-// item.transactionId, item.orderId, item.financialBreakdown { total_paid, developer_revenue, platform_fee }
 ```
 
-- **Grant the item off the `item.purchased` webhook**, not just this response — the webhook fires atomically with the spend (dedupe on `X-Invo-Idempotency-Key`). INVO debits currency; your game owns the catalog and grants the item.
-- **Idempotent** on `clientRequestId` — a duplicate throws a `409` `InvoError` (`err.isDuplicateRequest`).
-- **Insufficient balance** throws a `400` (`err.isInsufficientBalance`; `required_amount` + `current_balance` on `err.body`).
-- **Throttles** return `429` with `err.retryAfter` (seconds). Validation (missing fields, quantity outside `1..1000`, price `≤0`/`>999999.99`/non-decimal, total ≠ unit×qty) throws `INVALID_INPUT` **before** any network call.
-- Fee split is **90% developer / 10% INVO** by default (per-partner override). Not guardian-gated (the currency was already guardian-approved when it entered the wallet).
+  > Note: hook payloads include the request `url`, which for some calls embeds a player email (e.g. balance-by-email). Tokens and the game secret are sent as headers and are **never** passed to hooks — but redact the `url` if you log hook payloads.
+
+- **Request ids.** `InvoError.requestId` carries the backend request id (from `x-invo-request-id` / `x-request-id`) — quote it in support tickets.
 
-Companion reads (server): `invo.getItemPurchaseHistory({ playerEmail, limit?, offset? })` and `invo.getItemOrderDetails({ orderId | transactionId | clientRequestId })` — pass **exactly one** id; use `clientRequestId` for recovery ("did this purchase complete?").
+---
 
 ## Errors
 
-Every failure throws `InvoError` with `.code` (when present), `.status`, `.message`, `.body`. Branch on `.code`; for the handful of state errors with no `code` (e.g. `receiver_not_enrolled_use_claim_code`), use `.message` / the `.isReceiverNotEnrolled` helper. `.isTokenExpired` flags an expired token — if you pass `refreshToken` to `InvoClient` the SDK handles this for you (one re-mint + retry); otherwise re-mint server-side and retry. Client-side input guards (e.g. a USD amount outside `0 < x ≤ 999.99`, a missing `purchaseReference`, or `rail:"steam"` on `purchaseCurrency`) also throw `InvoError` with `.status === 0` before any network call.
+Every failure throws **`InvoError`** with:
+- `.code` — stable machine code when present (some txn-state errors have none — branch on `.message` for those)
+- `.status` — HTTP status (`0` for client-side validation and network errors)
+- `.message` — human-readable
+- `.body` — the raw parsed response
+
+Helpers:
+
+| Helper | Meaning |
+|---|---|
+| `.isTokenExpired` | player token expired — re-mint + retry (automatic if `refreshToken` is set) |
+| `.isReceiverNotEnrolled` | recipient has no passkey → switch to claim-code entry |
+| `.isInsufficientBalance` | item purchase failed (400); `required_amount` + `current_balance` on `.body` |
+| `.isDuplicateRequest` | idempotency-keyed request was a duplicate (409) |
+| `.retryAfter` | seconds to back off on a 429 throttle |
 
-## Scripts
+Client-side guards (bad amount, missing idempotency key, `rail:"steam"` on `purchaseCurrency`, item validation) throw `InvoError` with `.status === 0` **before** any network call. Notable backend codes: `SDK_TOKEN_EXPIRED`, `TENANT_NOT_MIGRATED`, `WEBAUTHN_NOT_ENABLED_FOR_TENANT`, `WEBAUTHN_UV_REQUIRED`, `ENROLLMENT_REQUIRES_PROOF`, `WRONG_RAIL_ENDPOINT`, `flow_paused`.
+
+```ts
+import { InvoError } from "@invonetwork/web-sdk";          // or "@invonetwork/web-sdk/server"
+try {
+  await server.purchaseItem(/* … */);
+} catch (e) {
+  if (e instanceof InvoError && e.isInsufficientBalance) {
+    showTopUp(e.body); // { required_amount, current_balance }
+  } else throw e;
+}
+```
+
+---
+
+## API reference
+
+### `InvoServer` (`@invonetwork/web-sdk/server`)
+
+| Method | Returns |
+|---|---|
+| `mintPlayerToken({ playerEmail })` | `{ token, expiresAt, identityId }` |
+| `initiateSend(input)` | `{ transactionId, verificationMethod, guardianApproval?, raw }` |
+| `initiateTransfer(input)` | `{ transactionId, verificationMethod, guardianApproval?, raw }` |
+| `createCheckout(input)` | `{ sessionId, checkoutUrl, expiresAt, raw }` |
+| `purchaseCurrency(input)` | `{ status, clientSecret?, paymentIntentId?, paymentUrl?, transactionId?, orderId?, newBalance?, raw }` |
+| `confirmPayment({ paymentIntentId, orderId? })` | `{ status, transactionId?, newBalance?, raw }` |
+| `getOrderDetails({ orderId? \| transactionId? })` | `{ order, financialSummary, statusTimeline, raw }` |
+| `purchaseItem(input)` | `{ status, transactionId, orderId, newBalance, previousBalance, currencyName, financialBreakdown?, raw }` |
+| `getItemPurchaseHistory({ playerEmail, limit?, offset? })` | `{ history, pagination, raw }` |
+| `getItemOrderDetails({ orderId? \| transactionId? \| clientRequestId? })` | `{ order, financialSummary, statusTimeline, raw }` |
+| `getPlayerBalance({ playerEmail? \| playerId? })` | `{ player, balances, summary, raw }` |
+| `verifyWebhook(rawBody, signatureHeader, secret \| secrets, opts?)` | typed `InvoWebhookEvent` (throws on bad signature) |
+
+### `InvoClient` (`@invonetwork/web-sdk`)
+
+| Method | Returns |
+|---|---|
+| `enrollPasskey()` | `{ status, device, raw }` |
+| `approveSend(txnId)` / `approveTransfer(txnId)` | `{ status, next, transactionId, claimCode?, claimCodeExpiresAt?, raw }` |
+| `confirmReceiptSend(txnId)` / `confirmReceiptTransfer(txnId)` | `{ status, raw }` |
+| `linkDevice(linkId)` | `{ status, raw }` |
+
+Every method throws `InvoError` on failure. Full inline types ship with the package.
+
+---
+
+## Scripts & versioning
 
 ```bash
 npm run build       # tsup → dist (ESM + CJS + d.ts)
@@ -214,6 +457,8 @@ npm run typecheck   # tsc --noEmit
 npm test            # vitest
 ```
 
+The package follows **semver**: patch = fixes, minor = additive surface, major = breaking changes (rare, with a migration note). The server contract is backward-compatible within a major, so an old pinned SDK keeps working. Pin a version and subscribe to release notes for security updates. See [`CHANGELOG.md`](CHANGELOG.md).
+
 ## License
 
-Proprietary — © Invo Tech Inc. See `LICENSE` (the partner-distribution license is a business decision; swap to MIT/Apache-2.0 if preferred).
+Proprietary — © Invo Tech Inc. See [`LICENSE`](LICENSE).