@invonetwork/web-sdk 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -1,39 +1,58 @@
-# Changelog
-
-All notable changes to `@invonetwork/web-sdk` are documented here. This project follows
-[Semantic Versioning](https://semver.org/).
-
-## [0.1.0] — 2026-06-30
-
-Initial scaffold.
-
-- `InvoServer` (`/server`): `mintPlayerToken`, `initiateSend`, `initiateTransfer`,
-  `createCheckout`, `purchaseCurrency`, `confirmPayment`, `getOrderDetails`.
-  - Client-side purchase guards (§4.7): USD amount `0 < x ≤ 999.99`, required
-    `purchaseReference`, and `rail:"steam"` rejected before the network call
-    (`INVALID_INPUT` / `MISSING_PURCHASE_REFERENCE` / `WRONG_RAIL_ENDPOINT`).
-- `InvoClient` (browser): `enrollPasskey`, `approveSend`/`approveTransfer`,
-  `confirmReceiptSend`/`confirmReceiptTransfer`, and `linkDevice` for the
-  interchangeable-methods flow (§4.6).
-  - Optional `refreshToken` hook: transparently re-mints and retries once on
-    `SDK_TOKEN_EXPIRED` (§11.2).
-- Shared: typed `InvoError`, isomorphic HTTP client, WebAuthn JSON⇄binary helpers.
-- Tests: HTTP layer, server request mapping + purchase guards, browser client
-  flows (enroll/approve/link/token-refresh), and WebAuthn serialization.
-- Contracts extracted + auditor-verified against the INVO backend.
-
-### Hardening (independent red-team pass)
-- **Guardian/minor `202` path no longer mismapped to `verificationMethod:"sms"`** —
-  `initiateSend`/`initiateTransfer` now return `verificationMethod: undefined` and a
-  `guardianApproval` block on the guardian path, so callers don't route into the
-  PIN UI by mistake (§4.3).
-- `usdAmount` validation tightened: rejects non-plain-decimal strings
-  (`"0x10"`, `"1e2"`, whitespace) and >2 decimal places before any network call.
-- Load-bearing response fields (`token`, `checkout_url`) now throw `INVALID_RESPONSE`
-  instead of silently surfacing as empty strings.
-- `getOrderDetails` requires at least one of `orderId`/`transactionId`.
-- Token refresh now re-runs the **whole** passkey ceremony on `SDK_TOKEN_EXPIRED`
-  (never replays a single-use assertion) and single-flights concurrent refreshes.
-- `baseUrl` must be `https://` (localhost exempt) so the token/secret can't travel
-  in cleartext.
-- Published tarball excludes sourcemaps (no proprietary source shipped).
+# Changelog
+
+All notable changes to `@invonetwork/web-sdk` are documented here. This project follows
+[Semantic Versioning](https://semver.org/).
+
+## [0.2.0] — 2026-06-30
+
+Adds **item purchase** (spend existing game currency on an in-game item, §4.8) — an
+additive, server-only surface.
+
+- `InvoServer` (`/server`): `purchaseItem`, `getItemPurchaseHistory`, `getItemOrderDetails`.
+  - Server-side, game-secret auth — no passkey, no real money, no payment rail (it's a
+    balance debit). Grant the item off the `item.purchased` webhook.
+  - Client-side guards: required fields (trim-checked), `itemQuantity` integer `1..1000`,
+    prices `> 0` and `<= 999999.99` (magnitude-safe 2-decimal check), and
+    `totalPrice == unitPrice × itemQuantity (±0.01)` compared in integer cents.
+  - Load-bearing response fields (`transaction_id`, `order_id`) throw `INVALID_RESPONSE`
+    if missing on a 200.
+- `InvoError` helpers: `isInsufficientBalance` (gated to 400; not the `429` throttle),
+  `isDuplicateRequest` (409), `retryAfter` (numeric or string `retry_after`); all
+  null-safe against non-JSON error bodies.
+- Independently audited (2 agents) against handoff doc §4.8/§6/§8; contract verified,
+  error-classification edge cases fixed.
+
+## [0.1.0] — 2026-06-30
+
+Initial scaffold.
+
+- `InvoServer` (`/server`): `mintPlayerToken`, `initiateSend`, `initiateTransfer`,
+  `createCheckout`, `purchaseCurrency`, `confirmPayment`, `getOrderDetails`.
+  - Client-side purchase guards (§4.7): USD amount `0 < x ≤ 999.99`, required
+    `purchaseReference`, and `rail:"steam"` rejected before the network call
+    (`INVALID_INPUT` / `MISSING_PURCHASE_REFERENCE` / `WRONG_RAIL_ENDPOINT`).
+- `InvoClient` (browser): `enrollPasskey`, `approveSend`/`approveTransfer`,
+  `confirmReceiptSend`/`confirmReceiptTransfer`, and `linkDevice` for the
+  interchangeable-methods flow (§4.6).
+  - Optional `refreshToken` hook: transparently re-mints and retries once on
+    `SDK_TOKEN_EXPIRED` (§11.2).
+- Shared: typed `InvoError`, isomorphic HTTP client, WebAuthn JSON⇄binary helpers.
+- Tests: HTTP layer, server request mapping + purchase guards, browser client
+  flows (enroll/approve/link/token-refresh), and WebAuthn serialization.
+- Contracts extracted + auditor-verified against the INVO backend.
+
+### Hardening (independent red-team pass)
+- **Guardian/minor `202` path no longer mismapped to `verificationMethod:"sms"`** —
+  `initiateSend`/`initiateTransfer` now return `verificationMethod: undefined` and a
+  `guardianApproval` block on the guardian path, so callers don't route into the
+  PIN UI by mistake (§4.3).
+- `usdAmount` validation tightened: rejects non-plain-decimal strings
+  (`"0x10"`, `"1e2"`, whitespace) and >2 decimal places before any network call.
+- Load-bearing response fields (`token`, `checkout_url`) now throw `INVALID_RESPONSE`
+  instead of silently surfacing as empty strings.
+- `getOrderDetails` requires at least one of `orderId`/`transactionId`.
+- Token refresh now re-runs the **whole** passkey ceremony on `SDK_TOKEN_EXPIRED`
+  (never replays a single-use assertion) and single-flights concurrent refreshes.
+- `baseUrl` must be `https://` (localhost exempt) so the token/secret can't travel
+  in cleartext.
+- Published tarball excludes sourcemaps (no proprietary source shipped).

package/README.md

@@ -1,142 +1,219 @@
-# @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.
-
-> **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**.
-
-## Install
-
-```bash
-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.)
-
-## Two entry points (the game secret never reaches the browser)
-
-| Import | Runs | Holds | Does |
-|---|---|---|---|
-| `@invonetwork/web-sdk/server` | your server (Node ≥18) | the **game secret** | mint player token, initiate send/transfer, currency purchase |
-| `@invonetwork/web-sdk` | the browser | a short-lived **player token** | enroll passkey, approve, self-claim |
-
-## Base URLs
-
-- Production: `https://invo.network`
-- Sandbox: `https://sandbox.invo.network/sandbox`
-
-`baseUrl` must be `https://` (the game secret and player token travel in request headers); `http://localhost` is allowed for local development only.
-
-## Server (Node)
-
-```ts
-import { InvoServer } from "@invonetwork/web-sdk/server";
-
-const invo = new InvoServer({
-  gameSecret: process.env.INVO_GAME_SECRET!,   // server-side only
-  baseUrl: "https://sandbox.invo.network/sandbox",
-});
-
-// 1. mint a short-lived token for the browser
-const { token } = await invo.mintPlayerToken({ playerEmail: "p@example.com" });
-
-// 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")
-
-// 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
-}
-```
-
-## Browser
-
-```ts
-import { InvoClient } from "@invonetwork/web-sdk";
-
-const invo = new InvoClient({
-  token,
-  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),
-});
-
-await invo.enrollPasskey();                       // once per user
-await invo.approveSend(transactionId);            // or approveTransfer(...)
-await invo.confirmReceiptSend(transactionId);     // recipient self-claim
-
-// 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();
-```
-
-Currency purchase has **no browser SDK method** — the server mints `checkoutUrl`; the browser just opens it.
-
-## Consuming the checkout (browser)
-
-`createCheckout` returns a `checkoutUrl` (15-min, single-use). Open it either way:
-
-- **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.
-
-```ts
-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:'success', 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.
-
-**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).
-
-## Payment rails (neutral names)
-
-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.
-
-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`.)
-
-## 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.
-
-## Scripts
-
-```bash
-npm run build       # tsup → dist (ESM + CJS + d.ts)
-npm run typecheck   # tsc --noEmit
-npm test            # vitest
-```
-
-## License
-
-Proprietary — © Invo Tech Inc. See `LICENSE` (the partner-distribution license is a business decision; swap to MIT/Apache-2.0 if preferred).
+# @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.
+
+> **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**.
+
+## Install
+
+```bash
+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.)
+
+## Two entry points (the game secret never reaches the browser)
+
+| 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 |
+
+## Base URLs
+
+- Production: `https://invo.network`
+- Sandbox: `https://sandbox.invo.network/sandbox`
+
+`baseUrl` must be `https://` (the game secret and player token travel in request headers); `http://localhost` is allowed for local development only.
+
+## Server (Node)
+
+```ts
+import { InvoServer } from "@invonetwork/web-sdk/server";
+
+const invo = new InvoServer({
+  gameSecret: process.env.INVO_GAME_SECRET!,   // server-side only
+  baseUrl: "https://sandbox.invo.network/sandbox",
+});
+
+// 1. mint a short-lived token for the browser
+const { token } = await invo.mintPlayerToken({ playerEmail: "p@example.com" });
+
+// 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")
+
+// 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
+}
+```
+
+## Browser
+
+```ts
+import { InvoClient } from "@invonetwork/web-sdk";
+
+const invo = new InvoClient({
+  token,
+  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),
+});
+
+await invo.enrollPasskey();                       // once per user
+await invo.approveSend(transactionId);            // or approveTransfer(...)
+await invo.confirmReceiptSend(transactionId);     // recipient self-claim
+
+// 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();
+```
+
+Currency purchase has **no browser SDK method** — the server mints `checkoutUrl`; the browser just opens it.
+
+## Consuming the checkout (browser)
+
+`createCheckout` returns a `checkoutUrl` (15-min, single-use). Open it either way:
+
+- **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.
+
+```ts
+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:'success', 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.
+
+**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).
+
+## Payment rails (neutral names)
+
+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.
+
+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)
+
+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:
+
+| | 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**) |
+| 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({
+  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)
+
+// 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
+
+// 3. BROWSER — the recipient claims. If they have a passkey, self-claim; else fall back to the claim code.
+try {
+  await invo.confirmReceiptTransfer(t.transactionId);
+} catch (e) {
+  if (e instanceof InvoError && e.isReceiverNotEnrolled) {
+    // recipient has no passkey here → show a claim-code entry UI 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.
+
+## Item purchase (spend game currency on an in-game item)
+
+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).
+
+```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
+});
+// 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).
+
+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.
+
+## Scripts
+
+```bash
+npm run build       # tsup → dist (ESM + CJS + d.ts)
+npm run typecheck   # tsc --noEmit
+npm test            # vitest
+```
+
+## License
+
+Proprietary — © Invo Tech Inc. See `LICENSE` (the partner-distribution license is a business decision; swap to MIT/Apache-2.0 if preferred).

package/dist/{chunk-KUQVVH2P.js → chunk-A44O4KC3.js}

@@ -16,6 +16,32 @@ var InvoError = class _InvoError extends Error {
   get isTokenExpired() {
     return this.code === "SDK_TOKEN_EXPIRED";
   }
+  /**
+   * True if an item purchase failed because the player's balance was too low (§4.8 → 400).
+   * The backend carries `required_amount` + `current_balance` on the body for the UI.
+   * Gated to status 400 so the `429 insufficient_balance_blocked` abuse throttle (which
+   * is a rate-limit, not a top-up condition) is NOT misclassified as this.
+   */
+  get isInsufficientBalance() {
+    if (this.status !== 400) return false;
+    const b = this.bodyObject();
+    return this.code === "INSUFFICIENT_BALANCE" || "required_amount" in b || /insufficient[_ ]balance/i.test(this.message);
+  }
+  /** True if an idempotency-keyed request was a duplicate (item purchase → 409). */
+  get isDuplicateRequest() {
+    return this.code === "DUPLICATE_REQUEST" || this.status === 409 && /duplicate/i.test(this.message);
+  }
+  /** Seconds to wait before retrying, when the backend throttled the call (429 `retry_after`). */
+  get retryAfter() {
+    const v = this.bodyObject()["retry_after"];
+    const n = typeof v === "string" ? Number(v) : v;
+    return typeof n === "number" && Number.isFinite(n) && n >= 0 ? n : void 0;
+  }
+  /** `body` as a plain object, or `{}` if it's a string/number/null (non-JSON responses).
+   *  The `in` operator throws on primitives, so callers must go through this. */
+  bodyObject() {
+    return this.body && typeof this.body === "object" ? this.body : {};
+  }
 };
 function errorFromResponse(status, body) {
   let message = `INVO request failed (HTTP ${status})`;
@@ -117,5 +143,5 @@ var Http = class {
 };
 
 export { Http, InvoError, assertSecureBaseUrl };
-//# sourceMappingURL=chunk-KUQVVH2P.js.map
-//# sourceMappingURL=chunk-KUQVVH2P.js.map
+//# sourceMappingURL=chunk-A44O4KC3.js.map
+//# sourceMappingURL=chunk-A44O4KC3.js.map

package/dist/{errors-B7rVID2r.d.cts → errors-DV5QsftP.d.cts}

@@ -107,6 +107,47 @@ interface PurchaseResult {
     newBalance?: string | number | null;
     raw: Record<string, unknown>;
 }
+interface PurchaseItemInput {
+    /** Idempotency key, unique per game. Required. A duplicate returns 409. */
+    clientRequestId: string;
+    playerEmail: string;
+    playerName: string;
+    itemId: string;
+    itemName: string;
+    /** Integer quantity, 1..1000. */
+    itemQuantity: number;
+    /** Price PER UNIT, in game-currency units (not USD). > 0 and <= 999999.99. */
+    unitPrice: string | number;
+    /** Must equal unitPrice × itemQuantity (±0.01). > 0 and <= 999999.99. */
+    totalPrice: string | number;
+    playerPhone?: string;
+    itemDescription?: string;
+    itemCategory?: string;
+}
+interface PurchaseItemResult {
+    /** "success" on a completed spend. */
+    status: string;
+    transactionId: string;
+    orderId: string;
+    /** Canonical balance AFTER the spend (game-currency units). */
+    newBalance: string | number | null;
+    previousBalance: string | number | null;
+    currencyName: string;
+    /** { total_paid, developer_revenue, platform_fee } when present. */
+    financialBreakdown?: Record<string, unknown>;
+    raw: Record<string, unknown>;
+}
+interface ItemHistoryQuery {
+    playerEmail: string;
+    limit?: number;
+    offset?: number;
+}
+/** Look up an item order by EXACTLY ONE of these. */
+interface ItemOrderQuery {
+    orderId?: string;
+    transactionId?: string;
+    clientRequestId?: string;
+}
 interface ApproveResult {
     status: string;
     next: string;
@@ -151,6 +192,20 @@ declare class InvoError extends Error {
     get isReceiverNotEnrolled(): boolean;
     /** True if the session/SDK token has expired and the caller should re-mint + retry. */
     get isTokenExpired(): boolean;
+    /**
+     * True if an item purchase failed because the player's balance was too low (§4.8 → 400).
+     * The backend carries `required_amount` + `current_balance` on the body for the UI.
+     * Gated to status 400 so the `429 insufficient_balance_blocked` abuse throttle (which
+     * is a rate-limit, not a top-up condition) is NOT misclassified as this.
+     */
+    get isInsufficientBalance(): boolean;
+    /** True if an idempotency-keyed request was a duplicate (item purchase → 409). */
+    get isDuplicateRequest(): boolean;
+    /** Seconds to wait before retrying, when the backend throttled the call (429 `retry_after`). */
+    get retryAfter(): number | undefined;
+    /** `body` as a plain object, or `{}` if it's a string/number/null (non-JSON responses).
+     *  The `in` operator throws on primitives, so callers must go through this. */
+    private bodyObject;
 }
 
-export { type ApproveResult as A, type ClientConfig as C, InvoError as I, type LinkDeviceResult as L, type PlayerToken as P, type Rail as R, type ServerConfig as S, type VerificationMethod as V, type ConfirmReceiptResult as a, type InitiateSendInput as b, type InitiateResult as c, type InitiateTransferInput as d, type CreateCheckoutInput as e, type CreateCheckoutResult as f, type PurchaseInput as g, type PurchaseResult as h };
+export { type ApproveResult as A, type ClientConfig as C, InvoError as I, type LinkDeviceResult as L, type PlayerToken as P, type Rail as R, type ServerConfig as S, type VerificationMethod as V, type ConfirmReceiptResult as a, type InitiateSendInput as b, type InitiateResult as c, type InitiateTransferInput as d, type CreateCheckoutInput as e, type CreateCheckoutResult as f, type PurchaseInput as g, type PurchaseResult as h, type PurchaseItemInput as i, type PurchaseItemResult as j, type ItemHistoryQuery as k, type ItemOrderQuery as l };

package/dist/{errors-B7rVID2r.d.ts → errors-DV5QsftP.d.ts}

@@ -107,6 +107,47 @@ interface PurchaseResult {
     newBalance?: string | number | null;
     raw: Record<string, unknown>;
 }
+interface PurchaseItemInput {
+    /** Idempotency key, unique per game. Required. A duplicate returns 409. */
+    clientRequestId: string;
+    playerEmail: string;
+    playerName: string;
+    itemId: string;
+    itemName: string;
+    /** Integer quantity, 1..1000. */
+    itemQuantity: number;
+    /** Price PER UNIT, in game-currency units (not USD). > 0 and <= 999999.99. */
+    unitPrice: string | number;
+    /** Must equal unitPrice × itemQuantity (±0.01). > 0 and <= 999999.99. */
+    totalPrice: string | number;
+    playerPhone?: string;
+    itemDescription?: string;
+    itemCategory?: string;
+}
+interface PurchaseItemResult {
+    /** "success" on a completed spend. */
+    status: string;
+    transactionId: string;
+    orderId: string;
+    /** Canonical balance AFTER the spend (game-currency units). */
+    newBalance: string | number | null;
+    previousBalance: string | number | null;
+    currencyName: string;
+    /** { total_paid, developer_revenue, platform_fee } when present. */
+    financialBreakdown?: Record<string, unknown>;
+    raw: Record<string, unknown>;
+}
+interface ItemHistoryQuery {
+    playerEmail: string;
+    limit?: number;
+    offset?: number;
+}
+/** Look up an item order by EXACTLY ONE of these. */
+interface ItemOrderQuery {
+    orderId?: string;
+    transactionId?: string;
+    clientRequestId?: string;
+}
 interface ApproveResult {
     status: string;
     next: string;
@@ -151,6 +192,20 @@ declare class InvoError extends Error {
     get isReceiverNotEnrolled(): boolean;
     /** True if the session/SDK token has expired and the caller should re-mint + retry. */
     get isTokenExpired(): boolean;
+    /**
+     * True if an item purchase failed because the player's balance was too low (§4.8 → 400).
+     * The backend carries `required_amount` + `current_balance` on the body for the UI.
+     * Gated to status 400 so the `429 insufficient_balance_blocked` abuse throttle (which
+     * is a rate-limit, not a top-up condition) is NOT misclassified as this.
+     */
+    get isInsufficientBalance(): boolean;
+    /** True if an idempotency-keyed request was a duplicate (item purchase → 409). */
+    get isDuplicateRequest(): boolean;
+    /** Seconds to wait before retrying, when the backend throttled the call (429 `retry_after`). */
+    get retryAfter(): number | undefined;
+    /** `body` as a plain object, or `{}` if it's a string/number/null (non-JSON responses).
+     *  The `in` operator throws on primitives, so callers must go through this. */
+    private bodyObject;
 }
 
-export { type ApproveResult as A, type ClientConfig as C, InvoError as I, type LinkDeviceResult as L, type PlayerToken as P, type Rail as R, type ServerConfig as S, type VerificationMethod as V, type ConfirmReceiptResult as a, type InitiateSendInput as b, type InitiateResult as c, type InitiateTransferInput as d, type CreateCheckoutInput as e, type CreateCheckoutResult as f, type PurchaseInput as g, type PurchaseResult as h };
+export { type ApproveResult as A, type ClientConfig as C, InvoError as I, type LinkDeviceResult as L, type PlayerToken as P, type Rail as R, type ServerConfig as S, type VerificationMethod as V, type ConfirmReceiptResult as a, type InitiateSendInput as b, type InitiateResult as c, type InitiateTransferInput as d, type CreateCheckoutInput as e, type CreateCheckoutResult as f, type PurchaseInput as g, type PurchaseResult as h, type PurchaseItemInput as i, type PurchaseItemResult as j, type ItemHistoryQuery as k, type ItemOrderQuery as l };

package/dist/index.cjs

@@ -18,6 +18,32 @@ var InvoError = class _InvoError extends Error {
   get isTokenExpired() {
     return this.code === "SDK_TOKEN_EXPIRED";
   }
+  /**
+   * True if an item purchase failed because the player's balance was too low (§4.8 → 400).
+   * The backend carries `required_amount` + `current_balance` on the body for the UI.
+   * Gated to status 400 so the `429 insufficient_balance_blocked` abuse throttle (which
+   * is a rate-limit, not a top-up condition) is NOT misclassified as this.
+   */
+  get isInsufficientBalance() {
+    if (this.status !== 400) return false;
+    const b = this.bodyObject();
+    return this.code === "INSUFFICIENT_BALANCE" || "required_amount" in b || /insufficient[_ ]balance/i.test(this.message);
+  }
+  /** True if an idempotency-keyed request was a duplicate (item purchase → 409). */
+  get isDuplicateRequest() {
+    return this.code === "DUPLICATE_REQUEST" || this.status === 409 && /duplicate/i.test(this.message);
+  }
+  /** Seconds to wait before retrying, when the backend throttled the call (429 `retry_after`). */
+  get retryAfter() {
+    const v = this.bodyObject()["retry_after"];
+    const n = typeof v === "string" ? Number(v) : v;
+    return typeof n === "number" && Number.isFinite(n) && n >= 0 ? n : void 0;
+  }
+  /** `body` as a plain object, or `{}` if it's a string/number/null (non-JSON responses).
+   *  The `in` operator throws on primitives, so callers must go through this. */
+  bodyObject() {
+    return this.body && typeof this.body === "object" ? this.body : {};
+  }
 };
 function errorFromResponse(status, body) {
   let message = `INVO request failed (HTTP ${status})`;

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-import { C as ClientConfig, A as ApproveResult, a as ConfirmReceiptResult, L as LinkDeviceResult } from './errors-B7rVID2r.cjs';
-export { I as InvoError, R as Rail, V as VerificationMethod } from './errors-B7rVID2r.cjs';
+import { C as ClientConfig, A as ApproveResult, a as ConfirmReceiptResult, L as LinkDeviceResult } from './errors-DV5QsftP.cjs';
+export { I as InvoError, R as Rail, V as VerificationMethod } from './errors-DV5QsftP.cjs';
 
 declare class InvoClient {
     private readonly http;

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { C as ClientConfig, A as ApproveResult, a as ConfirmReceiptResult, L as LinkDeviceResult } from './errors-B7rVID2r.js';
-export { I as InvoError, R as Rail, V as VerificationMethod } from './errors-B7rVID2r.js';
+import { C as ClientConfig, A as ApproveResult, a as ConfirmReceiptResult, L as LinkDeviceResult } from './errors-DV5QsftP.js';
+export { I as InvoError, R as Rail, V as VerificationMethod } from './errors-DV5QsftP.js';
 
 declare class InvoClient {
     private readonly http;

package/dist/index.js

@@ -1,5 +1,5 @@
-import { assertSecureBaseUrl, Http, InvoError } from './chunk-KUQVVH2P.js';
-export { InvoError } from './chunk-KUQVVH2P.js';
+import { assertSecureBaseUrl, Http, InvoError } from './chunk-A44O4KC3.js';
+export { InvoError } from './chunk-A44O4KC3.js';
 
 // src/shared/webauthn.ts
 function b64urlToBuffer(value) {

package/dist/server.cjs

@@ -18,6 +18,32 @@ var InvoError = class _InvoError extends Error {
   get isTokenExpired() {
     return this.code === "SDK_TOKEN_EXPIRED";
   }
+  /**
+   * True if an item purchase failed because the player's balance was too low (§4.8 → 400).
+   * The backend carries `required_amount` + `current_balance` on the body for the UI.
+   * Gated to status 400 so the `429 insufficient_balance_blocked` abuse throttle (which
+   * is a rate-limit, not a top-up condition) is NOT misclassified as this.
+   */
+  get isInsufficientBalance() {
+    if (this.status !== 400) return false;
+    const b = this.bodyObject();
+    return this.code === "INSUFFICIENT_BALANCE" || "required_amount" in b || /insufficient[_ ]balance/i.test(this.message);
+  }
+  /** True if an idempotency-keyed request was a duplicate (item purchase → 409). */
+  get isDuplicateRequest() {
+    return this.code === "DUPLICATE_REQUEST" || this.status === 409 && /duplicate/i.test(this.message);
+  }
+  /** Seconds to wait before retrying, when the backend throttled the call (429 `retry_after`). */
+  get retryAfter() {
+    const v = this.bodyObject()["retry_after"];
+    const n = typeof v === "string" ? Number(v) : v;
+    return typeof n === "number" && Number.isFinite(n) && n >= 0 ? n : void 0;
+  }
+  /** `body` as a plain object, or `{}` if it's a string/number/null (non-JSON responses).
+   *  The `in` operator throws on primitives, so callers must go through this. */
+  bodyObject() {
+    return this.body && typeof this.body === "object" ? this.body : {};
+  }
 };
 function errorFromResponse(status, body) {
   let message = `INVO request failed (HTTP ${status})`;
@@ -121,29 +147,35 @@ var Http = class {
 // src/server.ts
 var DEFAULT_UA = "invonetwork-web-sdk/0.1.0 (+https://invo.network)";
 var MAX_USD_AMOUNT = 999.99;
-function invalidAmount(usdAmount, why) {
+var MAX_ITEM_PRICE = 999999.99;
+function invalidInput(label, value, why) {
   return new InvoError({
-    message: `usdAmount ${why} (got ${JSON.stringify(usdAmount)}).`,
+    message: `${label} ${why} (got ${JSON.stringify(value)}).`,
     code: "INVALID_INPUT",
     status: 0
   });
 }
-function assertUsdAmount(usdAmount) {
+var PLAIN_DECIMAL = /^\d+(\.\d{1,2})?$/;
+function parseMoney(value, max, label) {
   let n;
-  if (typeof usdAmount === "number") {
-    n = usdAmount;
-    if (Number.isFinite(n) && Math.abs(n * 100 - Math.round(n * 100)) > 1e-9) {
-      throw invalidAmount(usdAmount, "must have at most 2 decimal places");
+  if (typeof value === "number") {
+    if (!Number.isFinite(value) || !PLAIN_DECIMAL.test(String(value))) {
+      throw invalidInput(label, value, "must be a positive decimal with at most 2 places");
     }
+    n = value;
   } else {
-    if (!/^\d+(\.\d{1,2})?$/.test(usdAmount)) {
-      throw invalidAmount(usdAmount, "must be a plain decimal USD value with at most 2 places");
+    if (!PLAIN_DECIMAL.test(value)) {
+      throw invalidInput(label, value, "must be a plain decimal value with at most 2 places");
     }
-    n = Number(usdAmount);
+    n = Number(value);
   }
-  if (!Number.isFinite(n) || n <= 0 || n > MAX_USD_AMOUNT) {
-    throw invalidAmount(usdAmount, `must be > 0 and <= ${MAX_USD_AMOUNT}`);
+  if (!Number.isFinite(n) || n <= 0 || n > max) {
+    throw invalidInput(label, value, `must be > 0 and <= ${max}`);
   }
+  return n;
+}
+function assertUsdAmount(usdAmount) {
+  parseMoney(usdAmount, MAX_USD_AMOUNT, "usdAmount");
 }
 function requireField(value, field, raw) {
   const s = value == null ? "" : String(value);
@@ -322,6 +354,104 @@ var InvoServer = class {
       this.auth
     );
   }
+  /**
+   * Buy an in-game item by SPENDING the player's existing game currency (§4.8).
+   * No real money, no payment rail, no passkey — it's a balance debit, authenticated
+   * server-side by the game secret. Idempotent on clientRequestId (a duplicate throws
+   * a 409 InvoError; check err.isDuplicateRequest). Insufficient balance throws a 400
+   * (err.isInsufficientBalance; required_amount/current_balance on err.body). Grant the
+   * item to your inventory off the `item.purchased` webhook, not just this response.
+   */
+  async purchaseItem(input) {
+    const required = [
+      ["clientRequestId", input.clientRequestId],
+      ["playerEmail", input.playerEmail],
+      ["playerName", input.playerName],
+      ["itemId", input.itemId],
+      ["itemName", input.itemName]
+    ];
+    for (const [k, v] of required) {
+      if (typeof v !== "string" || !v.trim()) throw invalidInput(k, v, "is required");
+    }
+    if (!Number.isInteger(input.itemQuantity) || input.itemQuantity < 1 || input.itemQuantity > 1e3) {
+      throw invalidInput("itemQuantity", input.itemQuantity, "must be an integer 1..1000");
+    }
+    const unit = parseMoney(input.unitPrice, MAX_ITEM_PRICE, "unitPrice");
+    const total = parseMoney(input.totalPrice, MAX_ITEM_PRICE, "totalPrice");
+    const expectedCents = Math.round(unit * input.itemQuantity * 100);
+    const totalCents = Math.round(total * 100);
+    if (Math.abs(totalCents - expectedCents) > 1) {
+      throw invalidInput(
+        "totalPrice",
+        input.totalPrice,
+        `must equal unitPrice \xD7 itemQuantity (\xB10.01): ${unit} \xD7 ${input.itemQuantity}`
+      );
+    }
+    const body = {
+      client_request_id: input.clientRequestId,
+      player_email: input.playerEmail,
+      player_name: input.playerName,
+      item_id: input.itemId,
+      item_name: input.itemName,
+      item_quantity: input.itemQuantity,
+      unit_price: input.unitPrice,
+      total_price: input.totalPrice
+    };
+    if (input.playerPhone) body["player_phone"] = input.playerPhone;
+    if (input.itemDescription) body["item_description"] = input.itemDescription;
+    if (input.itemCategory) body["item_category"] = input.itemCategory;
+    const raw = await this.http.post(
+      "/api/item-purchases/purchase-item",
+      body,
+      this.auth
+    );
+    return {
+      status: String(raw["status"] ?? ""),
+      transactionId: requireField(raw["transaction_id"], "transaction_id", raw),
+      orderId: requireField(raw["order_id"], "order_id", raw),
+      newBalance: raw["new_balance"] ?? null,
+      previousBalance: raw["previous_balance"] ?? null,
+      currencyName: String(raw["currency_name"] ?? ""),
+      financialBreakdown: raw["financial_breakdown"],
+      raw
+    };
+  }
+  /** Paginated item-purchase history for a player (§4.8 companion read). */
+  async getItemPurchaseHistory(query) {
+    if (typeof query.playerEmail !== "string" || !query.playerEmail.trim()) {
+      throw invalidInput("playerEmail", query.playerEmail, "is required");
+    }
+    const q = new URLSearchParams();
+    q.set("player_email", query.playerEmail);
+    if (query.limit != null) q.set("limit", String(query.limit));
+    if (query.offset != null) q.set("offset", String(query.offset));
+    return this.http.get(
+      `/api/item-purchases/player-purchase-history?${q.toString()}`,
+      this.auth
+    );
+  }
+  /** Look up one item order by EXACTLY ONE of orderId | transactionId | clientRequestId
+   *  (§4.8). Use clientRequestId for saga/recovery: "did this purchase actually complete?" */
+  async getItemOrderDetails(query) {
+    const provided = [query.orderId, query.transactionId, query.clientRequestId].filter(
+      (v) => typeof v === "string" && v.trim()
+    );
+    if (provided.length !== 1) {
+      throw new InvoError({
+        message: "getItemOrderDetails requires EXACTLY ONE of orderId, transactionId, or clientRequestId.",
+        code: "INVALID_INPUT",
+        status: 0
+      });
+    }
+    const q = new URLSearchParams();
+    if (query.orderId) q.set("order_id", query.orderId);
+    if (query.transactionId) q.set("transaction_id", query.transactionId);
+    if (query.clientRequestId) q.set("client_request_id", query.clientRequestId);
+    return this.http.get(
+      `/api/item-purchases/order-details?${q.toString()}`,
+      this.auth
+    );
+  }
   toInitiateResult(raw) {
     const vm = raw["verification_method"];
     const guardian = raw["guardian_approval"];

package/dist/server.d.cts

@@ -1,5 +1,5 @@
-import { S as ServerConfig, P as PlayerToken, b as InitiateSendInput, c as InitiateResult, d as InitiateTransferInput, e as CreateCheckoutInput, f as CreateCheckoutResult, g as PurchaseInput, h as PurchaseResult } from './errors-B7rVID2r.cjs';
-export { I as InvoError, R as Rail, V as VerificationMethod } from './errors-B7rVID2r.cjs';
+import { S as ServerConfig, P as PlayerToken, b as InitiateSendInput, c as InitiateResult, d as InitiateTransferInput, e as CreateCheckoutInput, f as CreateCheckoutResult, g as PurchaseInput, h as PurchaseResult, i as PurchaseItemInput, j as PurchaseItemResult, k as ItemHistoryQuery, l as ItemOrderQuery } from './errors-DV5QsftP.cjs';
+export { I as InvoError, R as Rail, V as VerificationMethod } from './errors-DV5QsftP.cjs';
 
 declare class InvoServer {
     private readonly http;
@@ -36,7 +36,21 @@ declare class InvoServer {
         orderId?: string;
         transactionId?: string;
     }): Promise<Record<string, unknown>>;
+    /**
+     * Buy an in-game item by SPENDING the player's existing game currency (§4.8).
+     * No real money, no payment rail, no passkey — it's a balance debit, authenticated
+     * server-side by the game secret. Idempotent on clientRequestId (a duplicate throws
+     * a 409 InvoError; check err.isDuplicateRequest). Insufficient balance throws a 400
+     * (err.isInsufficientBalance; required_amount/current_balance on err.body). Grant the
+     * item to your inventory off the `item.purchased` webhook, not just this response.
+     */
+    purchaseItem(input: PurchaseItemInput): Promise<PurchaseItemResult>;
+    /** Paginated item-purchase history for a player (§4.8 companion read). */
+    getItemPurchaseHistory(query: ItemHistoryQuery): Promise<Record<string, unknown>>;
+    /** Look up one item order by EXACTLY ONE of orderId | transactionId | clientRequestId
+     *  (§4.8). Use clientRequestId for saga/recovery: "did this purchase actually complete?" */
+    getItemOrderDetails(query: ItemOrderQuery): Promise<Record<string, unknown>>;
     private toInitiateResult;
 }
 
-export { CreateCheckoutInput, CreateCheckoutResult, InitiateResult, InitiateSendInput, InitiateTransferInput, InvoServer, PlayerToken, PurchaseInput, PurchaseResult, ServerConfig };
+export { CreateCheckoutInput, CreateCheckoutResult, InitiateResult, InitiateSendInput, InitiateTransferInput, InvoServer, ItemHistoryQuery, ItemOrderQuery, PlayerToken, PurchaseInput, PurchaseItemInput, PurchaseItemResult, PurchaseResult, ServerConfig };

package/dist/server.d.ts

@@ -1,5 +1,5 @@
-import { S as ServerConfig, P as PlayerToken, b as InitiateSendInput, c as InitiateResult, d as InitiateTransferInput, e as CreateCheckoutInput, f as CreateCheckoutResult, g as PurchaseInput, h as PurchaseResult } from './errors-B7rVID2r.js';
-export { I as InvoError, R as Rail, V as VerificationMethod } from './errors-B7rVID2r.js';
+import { S as ServerConfig, P as PlayerToken, b as InitiateSendInput, c as InitiateResult, d as InitiateTransferInput, e as CreateCheckoutInput, f as CreateCheckoutResult, g as PurchaseInput, h as PurchaseResult, i as PurchaseItemInput, j as PurchaseItemResult, k as ItemHistoryQuery, l as ItemOrderQuery } from './errors-DV5QsftP.js';
+export { I as InvoError, R as Rail, V as VerificationMethod } from './errors-DV5QsftP.js';
 
 declare class InvoServer {
     private readonly http;
@@ -36,7 +36,21 @@ declare class InvoServer {
         orderId?: string;
         transactionId?: string;
     }): Promise<Record<string, unknown>>;
+    /**
+     * Buy an in-game item by SPENDING the player's existing game currency (§4.8).
+     * No real money, no payment rail, no passkey — it's a balance debit, authenticated
+     * server-side by the game secret. Idempotent on clientRequestId (a duplicate throws
+     * a 409 InvoError; check err.isDuplicateRequest). Insufficient balance throws a 400
+     * (err.isInsufficientBalance; required_amount/current_balance on err.body). Grant the
+     * item to your inventory off the `item.purchased` webhook, not just this response.
+     */
+    purchaseItem(input: PurchaseItemInput): Promise<PurchaseItemResult>;
+    /** Paginated item-purchase history for a player (§4.8 companion read). */
+    getItemPurchaseHistory(query: ItemHistoryQuery): Promise<Record<string, unknown>>;
+    /** Look up one item order by EXACTLY ONE of orderId | transactionId | clientRequestId
+     *  (§4.8). Use clientRequestId for saga/recovery: "did this purchase actually complete?" */
+    getItemOrderDetails(query: ItemOrderQuery): Promise<Record<string, unknown>>;
     private toInitiateResult;
 }
 
-export { CreateCheckoutInput, CreateCheckoutResult, InitiateResult, InitiateSendInput, InitiateTransferInput, InvoServer, PlayerToken, PurchaseInput, PurchaseResult, ServerConfig };
+export { CreateCheckoutInput, CreateCheckoutResult, InitiateResult, InitiateSendInput, InitiateTransferInput, InvoServer, ItemHistoryQuery, ItemOrderQuery, PlayerToken, PurchaseInput, PurchaseItemInput, PurchaseItemResult, PurchaseResult, ServerConfig };

package/dist/server.js

@@ -1,32 +1,38 @@
-import { assertSecureBaseUrl, Http, InvoError } from './chunk-KUQVVH2P.js';
-export { InvoError } from './chunk-KUQVVH2P.js';
+import { assertSecureBaseUrl, Http, InvoError } from './chunk-A44O4KC3.js';
+export { InvoError } from './chunk-A44O4KC3.js';
 
 // src/server.ts
 var DEFAULT_UA = "invonetwork-web-sdk/0.1.0 (+https://invo.network)";
 var MAX_USD_AMOUNT = 999.99;
-function invalidAmount(usdAmount, why) {
+var MAX_ITEM_PRICE = 999999.99;
+function invalidInput(label, value, why) {
   return new InvoError({
-    message: `usdAmount ${why} (got ${JSON.stringify(usdAmount)}).`,
+    message: `${label} ${why} (got ${JSON.stringify(value)}).`,
     code: "INVALID_INPUT",
     status: 0
   });
 }
-function assertUsdAmount(usdAmount) {
+var PLAIN_DECIMAL = /^\d+(\.\d{1,2})?$/;
+function parseMoney(value, max, label) {
   let n;
-  if (typeof usdAmount === "number") {
-    n = usdAmount;
-    if (Number.isFinite(n) && Math.abs(n * 100 - Math.round(n * 100)) > 1e-9) {
-      throw invalidAmount(usdAmount, "must have at most 2 decimal places");
+  if (typeof value === "number") {
+    if (!Number.isFinite(value) || !PLAIN_DECIMAL.test(String(value))) {
+      throw invalidInput(label, value, "must be a positive decimal with at most 2 places");
     }
+    n = value;
   } else {
-    if (!/^\d+(\.\d{1,2})?$/.test(usdAmount)) {
-      throw invalidAmount(usdAmount, "must be a plain decimal USD value with at most 2 places");
+    if (!PLAIN_DECIMAL.test(value)) {
+      throw invalidInput(label, value, "must be a plain decimal value with at most 2 places");
     }
-    n = Number(usdAmount);
+    n = Number(value);
   }
-  if (!Number.isFinite(n) || n <= 0 || n > MAX_USD_AMOUNT) {
-    throw invalidAmount(usdAmount, `must be > 0 and <= ${MAX_USD_AMOUNT}`);
+  if (!Number.isFinite(n) || n <= 0 || n > max) {
+    throw invalidInput(label, value, `must be > 0 and <= ${max}`);
   }
+  return n;
+}
+function assertUsdAmount(usdAmount) {
+  parseMoney(usdAmount, MAX_USD_AMOUNT, "usdAmount");
 }
 function requireField(value, field, raw) {
   const s = value == null ? "" : String(value);
@@ -205,6 +211,104 @@ var InvoServer = class {
       this.auth
     );
   }
+  /**
+   * Buy an in-game item by SPENDING the player's existing game currency (§4.8).
+   * No real money, no payment rail, no passkey — it's a balance debit, authenticated
+   * server-side by the game secret. Idempotent on clientRequestId (a duplicate throws
+   * a 409 InvoError; check err.isDuplicateRequest). Insufficient balance throws a 400
+   * (err.isInsufficientBalance; required_amount/current_balance on err.body). Grant the
+   * item to your inventory off the `item.purchased` webhook, not just this response.
+   */
+  async purchaseItem(input) {
+    const required = [
+      ["clientRequestId", input.clientRequestId],
+      ["playerEmail", input.playerEmail],
+      ["playerName", input.playerName],
+      ["itemId", input.itemId],
+      ["itemName", input.itemName]
+    ];
+    for (const [k, v] of required) {
+      if (typeof v !== "string" || !v.trim()) throw invalidInput(k, v, "is required");
+    }
+    if (!Number.isInteger(input.itemQuantity) || input.itemQuantity < 1 || input.itemQuantity > 1e3) {
+      throw invalidInput("itemQuantity", input.itemQuantity, "must be an integer 1..1000");
+    }
+    const unit = parseMoney(input.unitPrice, MAX_ITEM_PRICE, "unitPrice");
+    const total = parseMoney(input.totalPrice, MAX_ITEM_PRICE, "totalPrice");
+    const expectedCents = Math.round(unit * input.itemQuantity * 100);
+    const totalCents = Math.round(total * 100);
+    if (Math.abs(totalCents - expectedCents) > 1) {
+      throw invalidInput(
+        "totalPrice",
+        input.totalPrice,
+        `must equal unitPrice \xD7 itemQuantity (\xB10.01): ${unit} \xD7 ${input.itemQuantity}`
+      );
+    }
+    const body = {
+      client_request_id: input.clientRequestId,
+      player_email: input.playerEmail,
+      player_name: input.playerName,
+      item_id: input.itemId,
+      item_name: input.itemName,
+      item_quantity: input.itemQuantity,
+      unit_price: input.unitPrice,
+      total_price: input.totalPrice
+    };
+    if (input.playerPhone) body["player_phone"] = input.playerPhone;
+    if (input.itemDescription) body["item_description"] = input.itemDescription;
+    if (input.itemCategory) body["item_category"] = input.itemCategory;
+    const raw = await this.http.post(
+      "/api/item-purchases/purchase-item",
+      body,
+      this.auth
+    );
+    return {
+      status: String(raw["status"] ?? ""),
+      transactionId: requireField(raw["transaction_id"], "transaction_id", raw),
+      orderId: requireField(raw["order_id"], "order_id", raw),
+      newBalance: raw["new_balance"] ?? null,
+      previousBalance: raw["previous_balance"] ?? null,
+      currencyName: String(raw["currency_name"] ?? ""),
+      financialBreakdown: raw["financial_breakdown"],
+      raw
+    };
+  }
+  /** Paginated item-purchase history for a player (§4.8 companion read). */
+  async getItemPurchaseHistory(query) {
+    if (typeof query.playerEmail !== "string" || !query.playerEmail.trim()) {
+      throw invalidInput("playerEmail", query.playerEmail, "is required");
+    }
+    const q = new URLSearchParams();
+    q.set("player_email", query.playerEmail);
+    if (query.limit != null) q.set("limit", String(query.limit));
+    if (query.offset != null) q.set("offset", String(query.offset));
+    return this.http.get(
+      `/api/item-purchases/player-purchase-history?${q.toString()}`,
+      this.auth
+    );
+  }
+  /** Look up one item order by EXACTLY ONE of orderId | transactionId | clientRequestId
+   *  (§4.8). Use clientRequestId for saga/recovery: "did this purchase actually complete?" */
+  async getItemOrderDetails(query) {
+    const provided = [query.orderId, query.transactionId, query.clientRequestId].filter(
+      (v) => typeof v === "string" && v.trim()
+    );
+    if (provided.length !== 1) {
+      throw new InvoError({
+        message: "getItemOrderDetails requires EXACTLY ONE of orderId, transactionId, or clientRequestId.",
+        code: "INVALID_INPUT",
+        status: 0
+      });
+    }
+    const q = new URLSearchParams();
+    if (query.orderId) q.set("order_id", query.orderId);
+    if (query.transactionId) q.set("transaction_id", query.transactionId);
+    if (query.clientRequestId) q.set("client_request_id", query.clientRequestId);
+    return this.http.get(
+      `/api/item-purchases/order-details?${q.toString()}`,
+      this.auth
+    );
+  }
   toInitiateResult(raw) {
     const vm = raw["verification_method"];
     const guardian = raw["guardian_approval"];

package/package.json

@@ -1,68 +1,68 @@
-{
-  "name": "@invonetwork/web-sdk",
-  "version": "0.1.0",
-  "description": "INVO Web SDK — currency purchase + passkey (WebAuthn) verification for partner web platforms.",
-  "license": "UNLICENSED",
-  "private": false,
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/Invo-Technologies/invo-web-sdk.git"
-  },
-  "homepage": "https://docs.invo.network",
-  "bugs": {
-    "url": "https://github.com/Invo-Technologies/invo-web-sdk/issues"
-  },
-  "type": "module",
-  "engines": {
-    "node": ">=18"
-  },
-  "sideEffects": false,
-  "files": [
-    "dist",
-    "!dist/**/*.map",
-    "README.md",
-    "LICENSE",
-    "CHANGELOG.md"
-  ],
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js",
-      "require": "./dist/index.cjs"
-    },
-    "./server": {
-      "types": "./dist/server.d.ts",
-      "import": "./dist/server.js",
-      "require": "./dist/server.cjs"
-    }
-  },
-  "main": "./dist/index.cjs",
-  "module": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "scripts": {
-    "build": "tsup",
-    "dev": "tsup --watch",
-    "typecheck": "tsc --noEmit",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "clean": "rimraf dist",
-    "prepublishOnly": "npm run clean && npm run build"
-  },
-  "keywords": [
-    "invo",
-    "webauthn",
-    "passkey",
-    "payments",
-    "game-currency",
-    "sdk"
-  ],
-  "publishConfig": {
-    "access": "public"
-  },
-  "devDependencies": {
-    "rimraf": "^5.0.5",
-    "tsup": "^8.0.1",
-    "typescript": "^5.4.5",
-    "vitest": "^1.5.0"
-  }
-}
+{
+  "name": "@invonetwork/web-sdk",
+  "version": "0.2.0",
+  "description": "INVO Web SDK — currency purchase + passkey (WebAuthn) verification for partner web platforms.",
+  "license": "UNLICENSED",
+  "private": false,
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Invo-Technologies/invo-web-sdk.git"
+  },
+  "homepage": "https://docs.invo.network",
+  "bugs": {
+    "url": "https://github.com/Invo-Technologies/invo-web-sdk/issues"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=18"
+  },
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "!dist/**/*.map",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "import": "./dist/server.js",
+      "require": "./dist/server.cjs"
+    }
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "clean": "rimraf dist",
+    "prepublishOnly": "npm run clean && npm run build"
+  },
+  "keywords": [
+    "invo",
+    "webauthn",
+    "passkey",
+    "payments",
+    "game-currency",
+    "sdk"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "rimraf": "^5.0.5",
+    "tsup": "^8.0.1",
+    "typescript": "^5.4.5",
+    "vitest": "^1.5.0"
+  }
+}