@invonetwork/web-sdk 0.2.1 → 0.3.0

package/README.md

@@ -1,393 +1,464 @@
-# @invonetwork/web-sdk
-
-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.2.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)
-- [Sends & transfers (move currency between players)](#sends--transfers-move-currency-between-players)
-- [Passkeys (enroll, approve, link)](#passkeys-enroll-approve-link)
-- [Webhooks](#webhooks)
-- [Errors](#errors)
-- [API reference](#api-reference)
-- [Scripts & versioning](#scripts--versioning)
-
-## Install
-
-```bash
-npm install @invonetwork/web-sdk
-```
-
-Node ≥ 18 on the server (uses the global `fetch`). The browser build ships ESM + CJS + types.
-
-## Get your account & game secret (INVO console)
-
-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:
-
-| 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` |
-
-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.
-
-## Architecture & the two entry points
-
-```
-┌──────────────────────────────┐         ┌──────────────────────────────┐
-│  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 ◄────────────┘
-```
-
-| 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 |
-
-**Never import `/server` into browser code** — it carries the game secret. The two entries are built separately for exactly this reason.
-
-## Deployment prerequisites
-
-INVO provisions these per tenant before the flows go live (most are super_admin-only, set by INVO — coordinate with your INVO contact):
-
-**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).
-
-**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 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
-  // fetch: customFetch,                            // optional override
-});
-
-const client = new InvoClient({
-  token,                                           // from your /mint endpoint
-  baseUrl: "https://sandbox.invo.network/sandbox",
-  refreshToken: () =>                              // optional: auto re-mint + retry on token expiry
-    fetch("/invo/token", { method: "POST" }).then((r) => r.json()).then((j) => j.token),
-});
-```
-
-**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`)
-
-`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.
-
-**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).
-
----
-
-## Currency purchase (real money in)
-
-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.data?.type === "INVO_CHECKOUT_COMPLETE") {
-    // 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 (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?").
-
----
-
-## Sends & transfers (move currency between players)
-
-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` | `initiateTransfer` |
-| Parties | `sender*` / `receiver*` + `receivingGameId` | `source*` / `target*` + `targetGameId` |
-| Approve (browser) | `approveSend` | `approveTransfer` — also returns the sender's **claim code** |
-| Recipient claim (browser) | `confirmReceiptSend` | `confirmReceiptTransfer` |
-
-```ts
-// 1. SERVER — initiate, then branch on how the sender must verify
-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",
-});
-// (initiateSend uses sender*/receiver* + receivingGameId instead)
-
-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
-}
-
-// 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 client.confirmReceiptTransfer(t.transactionId);           // or confirmReceiptSend(...)
-} catch (e) {
-  if (e instanceof InvoError && e.isReceiverNotEnrolled) {
-    // recipient has no passkey here → show claim-code entry using approved.claimCode
-  } else throw e;
-}
-```
-
-- **`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.
-
----
-
-## Passkeys (enroll, approve, link)
-
-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
-// 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).
-
-| 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.
-
----
-
-## Errors
-
-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 |
-
-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? })` | raw backend body |
-| `getOrderDetails({ orderId? \| transactionId? })` | raw backend body |
-| `purchaseItem(input)` | `{ status, transactionId, orderId, newBalance, previousBalance, currencyName, financialBreakdown?, raw }` |
-| `getItemPurchaseHistory({ playerEmail, limit?, offset? })` | raw backend body |
-| `getItemOrderDetails({ orderId? \| transactionId? \| clientRequestId? })` | raw backend body |
-
-### `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)
-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`](LICENSE).
+# @invonetwork/web-sdk
+
+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.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
+
+```bash
+npm install @invonetwork/web-sdk
+```
+
+Node ≥ 18 on the server (uses the global `fetch`). The browser build ships ESM + CJS + types.
+
+## Get your account & game secret (INVO console)
+
+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:
+
+| 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` |
+
+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.
+
+## Architecture & the two entry points
+
+```
+┌──────────────────────────────┐         ┌──────────────────────────────┐
+│  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 ◄────────────┘
+```
+
+| 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 |
+
+**Never import `/server` into browser code** — it carries the game secret. The two entries are built separately for exactly this reason.
+
+## Deployment prerequisites
+
+INVO provisions these per tenant before the flows go live (most are super_admin-only, set by INVO — coordinate with your INVO contact):
+
+**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).
+
+**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 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",
+  refreshToken: () =>                              // optional: auto re-mint + retry on token expiry
+    fetch("/invo/token", { method: "POST" }).then((r) => r.json()).then((j) => j.token),
+});
+```
+
+**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`)
+
+`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.
+
+**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).
+
+---
+
+## Currency purchase (real money in)
+
+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.data?.type === "INVO_CHECKOUT_COMPLETE") {
+    // 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 (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?").
+
+---
+
+## Player balance
+
+Read a player's currency balances (server-side, game-secret) by email or player id:
+
+```ts
+const { balances, summary } = await server.getPlayerBalance({ playerEmail: "p@example.com" });
+// balances: [{ currencyName, availableBalance, reservedBalance, totalBalance, currencySymbol, raw }]
+// or: server.getPlayerBalance({ playerId: 12345 })
+```
+
+---
+
+## Sends & transfers (move currency between players)
+
+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` | `initiateTransfer` |
+| Parties | `sender*` / `receiver*` + `receivingGameId` | `source*` / `target*` + `targetGameId` |
+| Approve (browser) | `approveSend` | `approveTransfer` — also returns the sender's **claim code** |
+| Recipient claim (browser) | `confirmReceiptSend` | `confirmReceiptTransfer` |
+
+```ts
+// 1. SERVER — initiate, then branch on how the sender must verify
+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",
+});
+// (initiateSend uses sender*/receiver* + receivingGameId instead)
+
+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
+}
+
+// 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 client.confirmReceiptTransfer(t.transactionId);           // or confirmReceiptSend(...)
+} catch (e) {
+  if (e instanceof InvoError && e.isReceiverNotEnrolled) {
+    // recipient has no passkey here → show claim-code entry using approved.claimCode
+  } else throw e;
+}
+```
+
+- **`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.
+
+---
+
+## Passkeys (enroll, approve, link)
+
+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
+// 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 }) => {},
+  },
+});
+```
+
+  > 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.
+
+---
+
+## Errors
+
+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 |
+
+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)
+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`](LICENSE).