npm - @invonetwork/web-sdk - Versions diffs - 0.4.2 → 0.6.0 - Mend

@invonetwork/web-sdk 0.4.2 → 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (14) hide show

package/CHANGELOG.md +167 -141
package/README.md +35 -12
package/dist/{chunk-JOVATUDY.js → chunk-D3XBTH4C.js} +10 -2
package/dist/index.cjs +87 -1
package/dist/index.d.cts +22 -3
package/dist/index.d.ts +22 -3
package/dist/index.js +81 -3
package/dist/server.cjs +9 -0
package/dist/server.d.cts +4 -2
package/dist/server.d.ts +4 -2
package/dist/server.js +3 -2
package/dist/{types-CBMLNwbe.d.cts → types-v8bDu2_p.d.cts} +56 -1
package/dist/{types-CBMLNwbe.d.ts → types-v8bDu2_p.d.ts} +56 -1
package/package.json +76 -76

package/CHANGELOG.md CHANGED Viewed

@@ -1,141 +1,167 @@
-# Changelog
-All notable changes to `@invonetwork/web-sdk` are documented here. This project follows
-[Semantic Versioning](https://semver.org/). Releases are managed with
-[changesets](https://github.com/changesets/changesets).
-## [0.4.2] — 2026-06-30
-Fixes from an independent line-by-line audit against the live backend.
-- **`linkDevice` now works.** `device/link/webauthn/begin` returns a wrapped
-  `{ link_id, options }` body (challenge nested under `options`) and binds the
-  challenge to a server-generated `link_id`. The client now unwraps `options` and
-  echoes the server's `link_id` to `/complete` (it previously threw on an undefined
-  challenge and sent the wrong id).
-- **`InvoError.code` is now populated for the direct purchase rail + guardian flows.**
-  `errorFromResponse` reads `error_code` (SecureErrorHandler + `/purchase-currency`)
-  in addition to `code`, and promotes known no-code tokens (`flow_paused`,
-  `spending_limit_exceeded`, `receiver_not_enrolled_use_claim_code`) to `.code`. Fixes
-  `isDuplicateRequest` on the direct rail.
-- **Guardian/minor routing.** The 202 guardian body also carries
-  `verification_method:"sms"`; the SDK now suppresses it (reports
-  `verificationMethod: undefined`) so a guardian-pending minor isn't routed into the
-  SMS-PIN UI. README example reordered to branch on `guardianApproval` first.
-## [0.4.1] — 2026-06-30
-Docs only — replaced the README's internal-leaking "Deployment prerequisites"
-(backend flag names, DB columns, gating mechanics) with a partner-facing
-"Before you go live"; republished so the npm page README is current.
-## [0.4.0] — 2026-06-30
-Additive release — more server reads, edge-ready webhooks, cancellation, and tooling.
-- **`getInboundPending({ playerEmail | playerPhone })`** — live, unclaimed inbound
-  sends/transfers for a player (the source of truth behind the "you have X to collect"
-  badge; pairs with `transfer.claim_pending`).
-- **`verifyWebhookAsync`** — Web Crypto variant of `verifyWebhook` that runs on
-  Cloudflare Workers / Deno / Vercel+Netlify Edge / Bun / browsers; and
-  **`createWebhookHandler`** — a zero-dep Fetch-API `(Request) => Promise<Response>`
-  webhook route handler (Next.js App Router, Workers, Deno, Hono, Bun).
-- **`iterateItemPurchaseHistory`** — async iterator that pages through a player's
-  full item-purchase history.
-- **Per-call `AbortSignal`** — every method accepts an optional `{ signal }`; an
-  aborted call throws `InvoError` code `ABORTED` and is never retried.
-- **Tooling**: ESLint (+ lint in CI), changesets release automation, `SECURITY.md`,
-  and `CODEOWNERS`.
-## [0.3.0] — 2026-06-30
-Additive release — new server capabilities plus transport resilience/observability.
-- **Webhook verification** (`/server`): `verifyWebhook(rawBody, signatureHeader, secret | secrets, opts?)`
-  — constant-time HMAC-SHA256 over `${t}.${rawBody}`, 5-minute replay window,
-  multi-secret rotation; returns a typed `InvoWebhookEvent` discriminated union
-  (`purchase.*`, `item.purchased`, `transfer.*`, `payout.status_changed`, `webhook.test`).
-  Throws `InvoError` (`WEBHOOK_SIGNATURE_INVALID` / `WEBHOOK_TIMESTAMP_EXPIRED` /
-  `WEBHOOK_MALFORMED` / `WEBHOOK_SECRET_MISSING`). Server-only; the browser bundle
-  stays crypto-free. Independently security-audited.
-- **`getPlayerBalance({ playerEmail | playerId })`** (`/server`): typed `player` / `balances` / `summary`.
-- **Automatic retries**: network errors/timeouts, `429` (honoring `retry_after`), and
-  `5xx` are retried with exponential backoff + jitter. New config `maxRetries`
-  (default 2, `0` disables) and `retryBaseDelayMs` (default 250).
-- **Observability hooks**: optional `onRequest` / `onResponse` / `onError` on both
-  entries (best-effort/non-throwing); `InvoError.requestId` carries the backend
-  request id for support/tracing.
-- **Typed reads**: `confirmPayment` → `ConfirmPaymentResult`; `getOrderDetails` /
-  `getItemOrderDetails` → `OrderDetailsResult`; `getItemPurchaseHistory` →
-  `ItemHistoryResult` (previously untyped `Record`). All keep `raw`.
-- **Light validation**: `mintPlayerToken` and `createCheckout` require a non-blank
-  `playerEmail` (throws `INVALID_INPUT` before the network call).
-- **License**: `package.json` `license` is now `SEE LICENSE IN LICENSE` (was
-  `UNLICENSED`); `LICENSE` rewritten as an explicit install-and-use grant for
-  building INVO integrations.
-## [0.2.1] — 2026-06-30
-Docs only — no code change (republished so the npm page README is current).
-- Rewrote the README into a complete integration/deployment guide: capability
-  overview, architecture, deployment prerequisites, per-flow sections (currency
-  purchase, item purchase, sends, transfers, passkeys), webhooks, errors, and a
-  full API reference for both entries.
-- Added INVO console onboarding: `https://console.invo.network` (production) and
-  `https://dev.console.invo.network` (testing/sandbox), mapped to their API base URLs.
-## [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).
+# Changelog
+All notable changes to `@invonetwork/web-sdk` are documented here. This project follows
+[Semantic Versioning](https://semver.org/). Releases are managed with
+[changesets](https://github.com/changesets/changesets).
+## [0.6.0] — 2026-07-01
+Three additive browser flows the dashboard needed, built to the live backend contracts.
+- **`InvoClient.getPendingCollect()`** — the player's own pending-to-collect list
+  (player-token `GET /api/sdk/transfers/pending`), PII-free. Each row's `kind`
+  (`identity_gate` → `approve*`, `receiving_confirm` → `confirmReceipt*`) tells you the
+  action; typed fields incl. `held` / `holdReason` / `stepUpRequired`.
+- **First-enrollment OTP grant** — `enrollmentBegin()` / `enrollmentVerify(code)` for
+  `ENROLLMENT_REQUIRES_AUTHORIZATION` (send OTP to phone+email, verify, then retry the
+  same `enrollPasskey()` — the server grant is auto-consumed). New `InvoError` helpers
+  `isEnrollmentAuthorizationRequired` / `isEnrollmentProofRequired`.
+- **Typed approve/confirm holds** — `approve*`/`confirmReceipt*` now surface a typed
+  `holdReason` (from `error_code ?? code`) on HTTP 202 holds, plus `risk` /
+  `guardianApproval` / `pollEndpoint` on approve. `RECIPIENT_IDENTITY_PENDING` correctly
+  surfaces on confirm-receipt. Success carries no `holdReason`.
+## [0.5.0] — 2026-07-01
+Support partner `metadata` end-to-end on the purchase flow (additive, backward-compatible).
+- **`PurchaseCompletedData.metadata?`** — the `purchase.completed` webhook now echoes your
+  metadata back (all rails); `event.data.metadata` is typed.
+- **`purchaseCurrency`** now accepts and forwards `metadata` (the direct `/purchase-currency`
+  endpoint accepts it too, matching `createCheckout`).
+## [0.4.2] — 2026-06-30
+Fixes from an independent line-by-line audit against the live backend.
+- **`linkDevice` now works.** `device/link/webauthn/begin` returns a wrapped
+  `{ link_id, options }` body (challenge nested under `options`) and binds the
+  challenge to a server-generated `link_id`. The client now unwraps `options` and
+  echoes the server's `link_id` to `/complete` (it previously threw on an undefined
+  challenge and sent the wrong id).
+- **`InvoError.code` is now populated for the direct purchase rail + guardian flows.**
+  `errorFromResponse` reads `error_code` (SecureErrorHandler + `/purchase-currency`)
+  in addition to `code`, and promotes known no-code tokens (`flow_paused`,
+  `spending_limit_exceeded`, `receiver_not_enrolled_use_claim_code`) to `.code`. Fixes
+  `isDuplicateRequest` on the direct rail.
+- **Guardian/minor routing.** The 202 guardian body also carries
+  `verification_method:"sms"`; the SDK now suppresses it (reports
+  `verificationMethod: undefined`) so a guardian-pending minor isn't routed into the
+  SMS-PIN UI. README example reordered to branch on `guardianApproval` first.
+## [0.4.1] — 2026-06-30
+Docs only — replaced the README's internal-leaking "Deployment prerequisites"
+(backend flag names, DB columns, gating mechanics) with a partner-facing
+"Before you go live"; republished so the npm page README is current.
+## [0.4.0] — 2026-06-30
+Additive release — more server reads, edge-ready webhooks, cancellation, and tooling.
+- **`getInboundPending({ playerEmail | playerPhone })`** — live, unclaimed inbound
+  sends/transfers for a player (the source of truth behind the "you have X to collect"
+  badge; pairs with `transfer.claim_pending`).
+- **`verifyWebhookAsync`** — Web Crypto variant of `verifyWebhook` that runs on
+  Cloudflare Workers / Deno / Vercel+Netlify Edge / Bun / browsers; and
+  **`createWebhookHandler`** — a zero-dep Fetch-API `(Request) => Promise<Response>`
+  webhook route handler (Next.js App Router, Workers, Deno, Hono, Bun).
+- **`iterateItemPurchaseHistory`** — async iterator that pages through a player's
+  full item-purchase history.
+- **Per-call `AbortSignal`** — every method accepts an optional `{ signal }`; an
+  aborted call throws `InvoError` code `ABORTED` and is never retried.
+- **Tooling**: ESLint (+ lint in CI), changesets release automation, `SECURITY.md`,
+  and `CODEOWNERS`.
+## [0.3.0] — 2026-06-30
+Additive release — new server capabilities plus transport resilience/observability.
+- **Webhook verification** (`/server`): `verifyWebhook(rawBody, signatureHeader, secret | secrets, opts?)`
+  — constant-time HMAC-SHA256 over `${t}.${rawBody}`, 5-minute replay window,
+  multi-secret rotation; returns a typed `InvoWebhookEvent` discriminated union
+  (`purchase.*`, `item.purchased`, `transfer.*`, `payout.status_changed`, `webhook.test`).
+  Throws `InvoError` (`WEBHOOK_SIGNATURE_INVALID` / `WEBHOOK_TIMESTAMP_EXPIRED` /
+  `WEBHOOK_MALFORMED` / `WEBHOOK_SECRET_MISSING`). Server-only; the browser bundle
+  stays crypto-free. Independently security-audited.
+- **`getPlayerBalance({ playerEmail | playerId })`** (`/server`): typed `player` / `balances` / `summary`.
+- **Automatic retries**: network errors/timeouts, `429` (honoring `retry_after`), and
+  `5xx` are retried with exponential backoff + jitter. New config `maxRetries`
+  (default 2, `0` disables) and `retryBaseDelayMs` (default 250).
+- **Observability hooks**: optional `onRequest` / `onResponse` / `onError` on both
+  entries (best-effort/non-throwing); `InvoError.requestId` carries the backend
+  request id for support/tracing.
+- **Typed reads**: `confirmPayment` → `ConfirmPaymentResult`; `getOrderDetails` /
+  `getItemOrderDetails` → `OrderDetailsResult`; `getItemPurchaseHistory` →
+  `ItemHistoryResult` (previously untyped `Record`). All keep `raw`.
+- **Light validation**: `mintPlayerToken` and `createCheckout` require a non-blank
+  `playerEmail` (throws `INVALID_INPUT` before the network call).
+- **License**: `package.json` `license` is now `SEE LICENSE IN LICENSE` (was
+  `UNLICENSED`); `LICENSE` rewritten as an explicit install-and-use grant for
+  building INVO integrations.
+## [0.2.1] — 2026-06-30
+Docs only — no code change (republished so the npm page README is current).
+- Rewrote the README into a complete integration/deployment guide: capability
+  overview, architecture, deployment prerequisites, per-flow sections (currency
+  purchase, item purchase, sends, transfers, passkeys), webhooks, errors, and a
+  full API reference for both entries.
+- Added INVO console onboarding: `https://console.invo.network` (production) and
+  `https://dev.console.invo.network` (testing/sandbox), mapped to their API base URLs.
+## [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 CHANGED Viewed

@@ -2,7 +2,7 @@
 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.4.0`, published on npm. The backend it wraps is **live** on sandbox + production, so you can build and test against sandbox today.
+> **Status:** `v0.6.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
@@ -183,6 +183,7 @@ const purchase = await server.purchaseCurrency({
   purchaseReference: crypto.randomUUID(), // idempotency key, required
   rail: "platform",
   paymentMethodId: "pm_...",              // a tokenized payment method
+  metadata: { yourOrderId: "ord_42" },    // echoed back on the purchase.completed webhook
 });
 // purchase.status:
 //   "success"          → captured, purchase.newBalance updated
@@ -285,14 +286,12 @@ try {
 - **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 may be disabled for your tenant; if it is, surface the claim-code path instead.
+- **Holds:** an approve/claim can return an HTTP 202 hold instead of success — inspect `result.holdReason` (`"RISK_HOLD"`, `"GUARDIAN_APPROVAL_PENDING"`, and on confirm-receipt `"RECIPIENT_IDENTITY_PENDING"`); success has no `holdReason` (and `next: "pending_claim"`). Terminal guardian outcomes throw (`GUARDIAN_APPROVAL_REJECTED`/`_EXPIRED`).
-**"You have X to collect"** — to render a collect badge, list a player's live, unclaimed inbound sends/transfers (the source of truth behind the `transfer.claim_pending` webhook):
+**"You have X to collect"**
-```ts
-const { inboundPending } = await server.getInboundPending({ playerEmail: "q@example.com" });
-// each row: { transactionId, flow, amount, netAmount, sourceGame, toPhone, toIdentityId, claimCodeExpiresAt }
-// match toPhone to the logged-in player (toIdentityId is null when the phone maps to >1 of your players)
-```
+- **Browser (player-token):** `client.getPendingCollect()` returns the player's own pending items. Each row's `kind` tells you the action — `"identity_gate"` → `approve*` (they initiated), `"receiving_confirm"` → `confirmReceipt*` (a peer sent to them). PII-free (no claim code / phone).
+- **Server (game-secret):** `server.getInboundPending({ playerEmail | playerPhone })` — richer, includes `toPhone`/`toIdentityId` for routing a notification to the right account. Match `toPhone` to the player (`toIdentityId` is null when the phone maps to >1 of your players).
 ---
@@ -311,6 +310,26 @@ await client.linkDevice(linkId);   // → { status: "authorized" }
 await client.enrollPasskey();
 ```
+**First-enrollment OTP grant.** For tenants that require it, the first `enrollPasskey()`
+throws `ENROLLMENT_REQUIRES_AUTHORIZATION`. Send a one-time code (to the player's phone +
+email on file), verify it, then **retry the same `enrollPasskey()`** — the server-side
+grant is consumed automatically:
+```ts
+try {
+  await client.enrollPasskey();
+} catch (e) {
+  if (e instanceof InvoError && e.isEnrollmentAuthorizationRequired) {
+    await client.enrollmentBegin();                 // → { status: "sent", channels: ["sms","email"] }
+    await client.enrollmentVerify(codeFromUser);    // 6-digit OTP
+    await client.enrollPasskey();                   // retry — grant auto-consumed
+  } else if (e instanceof InvoError && e.isEnrollmentProofRequired) {
+    await client.linkDevice(linkId);                // a different method already exists
+    await client.enrollPasskey();
+  } else throw e;
+}
+```
 - **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`).
@@ -369,7 +388,7 @@ export const POST = createWebhookHandler({
 | 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.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, metadata`) — `metadata` echoes what you passed to `createCheckout`/`purchaseCurrency` |
 | `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`) |
@@ -418,6 +437,8 @@ Helpers:
 | `.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 |
+| `.isEnrollmentAuthorizationRequired` | first-enrollment needs the OTP grant → `enrollmentBegin`/`enrollmentVerify` |
+| `.isEnrollmentProofRequired` | another method exists → prove it via `linkDevice` |
 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`.
@@ -464,11 +485,13 @@ Every method also accepts an optional final `{ signal }` (`AbortSignal`) for can
 | Method | Returns |
 |---|---|
 | `enrollPasskey()` | `{ status, device, raw }` |
-| `approveSend(txnId)` / `approveTransfer(txnId)` | `{ status, next, transactionId, claimCode?, claimCodeExpiresAt?, raw }` |
-| `confirmReceiptSend(txnId)` / `confirmReceiptTransfer(txnId)` | `{ status, raw }` |
+| `enrollmentBegin()` / `enrollmentVerify(code)` | OTP grant for `ENROLLMENT_REQUIRES_AUTHORIZATION` (then retry `enrollPasskey`) |
+| `approveSend(txnId)` / `approveTransfer(txnId)` | `{ status, next, transactionId, claimCode?, claimCodeExpiresAt?, holdReason?, risk?, guardianApproval?, pollEndpoint?, raw }` |
+| `confirmReceiptSend(txnId)` / `confirmReceiptTransfer(txnId)` | `{ status, holdReason?, raw }` |
 | `linkDevice(linkId)` | `{ status, raw }` |
+| `getPendingCollect()` | `{ pending, raw }` — the player's own pending-to-collect list (player-token) |
-Every method throws `InvoError` on failure. Full inline types ship with the package.
+Every method throws `InvoError` on failure and takes an optional final `{ signal }`. Full inline types ship with the package.
 ---
@@ -480,7 +503,7 @@ 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).
+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. Full history: [CHANGELOG](https://github.com/Invo-Technologies/invo-web-sdk/blob/main/CHANGELOG.md) · [release notes](https://github.com/Invo-Technologies/invo-web-sdk/blob/main/docs/RELEASES.md) (absolute links to `main`).
 ## License

package/dist/{chunk-JOVATUDY.js → chunk-D3XBTH4C.js} RENAMED Viewed

@@ -17,6 +17,14 @@ var InvoError = class _InvoError extends Error {
   get isTokenExpired() {
     return this.code === "SDK_TOKEN_EXPIRED";
   }
+  /** True if `enrollPasskey()` needs the OTP-grant flow (`enrollmentBegin`/`enrollmentVerify`). */
+  get isEnrollmentAuthorizationRequired() {
+    return this.code === "ENROLLMENT_REQUIRES_AUTHORIZATION";
+  }
+  /** True if enrolling is blocked because another method exists — use `linkDevice`. */
+  get isEnrollmentProofRequired() {
+    return this.code === "ENROLLMENT_REQUIRES_PROOF";
+  }
   /**
    * 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.
@@ -249,5 +257,5 @@ function retryAfterMs(parsed, headers) {
 }
 export { Http, InvoError, assertSecureBaseUrl };
-//# sourceMappingURL=chunk-JOVATUDY.js.map
-//# sourceMappingURL=chunk-JOVATUDY.js.map
+//# sourceMappingURL=chunk-D3XBTH4C.js.map
+//# sourceMappingURL=chunk-D3XBTH4C.js.map

package/dist/index.cjs CHANGED Viewed

@@ -19,6 +19,14 @@ var InvoError = class _InvoError extends Error {
   get isTokenExpired() {
     return this.code === "SDK_TOKEN_EXPIRED";
   }
+  /** True if `enrollPasskey()` needs the OTP-grant flow (`enrollmentBegin`/`enrollmentVerify`). */
+  get isEnrollmentAuthorizationRequired() {
+    return this.code === "ENROLLMENT_REQUIRES_AUTHORIZATION";
+  }
+  /** True if enrolling is blocked because another method exists — use `linkDevice`. */
+  get isEnrollmentProofRequired() {
+    return this.code === "ENROLLMENT_REQUIRES_PROOF";
+  }
   /**
    * 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.
@@ -332,6 +340,21 @@ function assertionToJSON(cred) {
 }
 // src/index.ts
+function toPendingCollectItem(row) {
+  return {
+    transferId: String(row["transfer_id"] ?? ""),
+    kind: String(row["kind"] ?? ""),
+    flow: String(row["flow"] ?? ""),
+    amount: row["amount"] ?? null,
+    currency: String(row["currency"] ?? ""),
+    counterpartyGame: String(row["counterparty_game"] ?? ""),
+    expiresAt: row["expires_at"] ?? null,
+    stepUpRequired: row["step_up_required"] === true,
+    held: row["held"] === true,
+    holdReason: row["hold_reason"] ?? null,
+    raw: row
+  };
+}
 var InvoClient = class {
   constructor(config) {
     if (!config.token) throw new Error("InvoClient requires a player `token`.");
@@ -424,12 +447,65 @@ var InvoClient = class {
       return { status: String(raw["status"] ?? ""), raw };
     });
   }
+  /**
+   * List the player's own pending items to collect (browser, player-token). Each row's
+   * `kind` tells you which action to call: `"identity_gate"` → `approve*` (you initiated);
+   * `"receiving_confirm"` → `confirmReceipt*` (a peer sent to you). PII-free — no claim
+   * code or phone (those are only on the server-side `getInboundPending`).
+   */
+  async getPendingCollect(opts) {
+    return this.withTokenRetry(async () => {
+      const raw = await this.get(
+        "/api/sdk/transfers/pending",
+        opts?.signal
+      );
+      const rows = Array.isArray(raw["pending"]) ? raw["pending"] : [];
+      return { pending: rows.map(toPendingCollectItem), raw };
+    });
+  }
+  /**
+   * First-enrollment OTP grant (§4.2). When `enrollPasskey()` throws
+   * `ENROLLMENT_REQUIRES_AUTHORIZATION` (`err.isEnrollmentAuthorizationRequired`), call
+   * this to send a 6-digit code to the player's phone + email on file, collect the code,
+   * call `enrollmentVerify(code)`, then RETRY the SAME `enrollPasskey()` —
+   * `register/complete` auto-consumes the server-side grant (30-min TTL). For
+   * `ENROLLMENT_REQUIRES_PROOF` (`err.isEnrollmentProofRequired`) use `linkDevice` instead.
+   */
+  async enrollmentBegin(opts) {
+    return this.withTokenRetry(async () => {
+      const raw = await this.post(
+        "/api/sdk/device/enrollment/begin",
+        void 0,
+        opts?.signal
+      );
+      return {
+        status: String(raw["status"] ?? ""),
+        channels: Array.isArray(raw["channels"]) ? raw["channels"] : [],
+        raw
+      };
+    });
+  }
+  /** Verify the enrollment OTP (see {@link enrollmentBegin}); on success, retry `enrollPasskey()`. */
+  async enrollmentVerify(code, opts) {
+    if (!code) throw new Error("enrollmentVerify requires the OTP `code`.");
+    return this.withTokenRetry(async () => {
+      const raw = await this.post(
+        "/api/sdk/device/enrollment/verify",
+        { code },
+        opts?.signal
+      );
+      return { status: String(raw["status"] ?? ""), raw };
+    });
+  }
   // --- internals ---
   /** POST with the current player token. Token-expiry retry is handled one level
    *  up by withTokenRetry (which re-runs the whole ceremony, not a single call). */
   async post(path, body, signal) {
     return this.http.post(path, body, this.auth, { signal });
   }
+  async get(path, signal) {
+    return this.http.get(path, this.auth, { signal });
+  }
   /**
    * Run a whole flow, retrying it ONCE if any call fails with SDK_TOKEN_EXPIRED
    * and a `refreshToken` hook is configured. We re-run the entire begin→get→
@@ -483,12 +559,17 @@ var InvoClient = class {
         { webauthn_assertion: assertion },
         signal
       );
+      const holdReason = raw["error_code"] ?? raw["code"];
       return {
         status: String(raw["status"] ?? ""),
         next: String(raw["next"] ?? ""),
         transactionId: String(raw["transaction_id"] ?? transactionId),
         claimCode: raw["claim_code"],
         claimCodeExpiresAt: raw["claim_code_expires_at"],
+        holdReason: typeof holdReason === "string" ? holdReason : void 0,
+        risk: raw["risk"],
+        guardianApproval: raw["guardian_approval"] ?? void 0,
+        pollEndpoint: raw["poll_endpoint"],
         raw
       };
     });
@@ -507,7 +588,12 @@ var InvoClient = class {
         { webauthn_assertion: assertion },
         signal
       );
-      return { status: String(raw["status"] ?? ""), raw };
+      const holdReason = raw["error_code"] ?? raw["code"];
+      return {
+        status: String(raw["status"] ?? ""),
+        holdReason: typeof holdReason === "string" ? holdReason : void 0,
+        raw
+      };
     });
   }
 };

package/dist/index.d.cts CHANGED Viewed

@@ -1,5 +1,5 @@
-import { C as ClientConfig, a as CallOptions, A as ApproveResult, b as ConfirmReceiptResult, L as LinkDeviceResult } from './types-CBMLNwbe.cjs';
-export { I as InvoError, c as InvoErrorInfo, d as InvoHooks, e as InvoRequestInfo, f as InvoResponseInfo, R as Rail, V as VerificationMethod } from './types-CBMLNwbe.cjs';
+import { C as ClientConfig, a as CallOptions, A as ApproveResult, b as ConfirmReceiptResult, L as LinkDeviceResult, P as PendingCollectResult, E as EnrollmentBeginResult, c as EnrollmentVerifyResult } from './types-v8bDu2_p.cjs';
+export { I as InvoError, d as InvoErrorInfo, e as InvoHooks, f as InvoRequestInfo, g as InvoResponseInfo, h as PendingCollectItem, R as Rail, V as VerificationMethod } from './types-v8bDu2_p.cjs';
 declare class InvoClient {
     private readonly http;
@@ -32,9 +32,28 @@ declare class InvoClient {
      * begin -> navigator.credentials.get() -> complete with { link_id, webauthn_assertion }.
      */
     linkDevice(linkId: string, opts?: CallOptions): Promise<LinkDeviceResult>;
+    /**
+     * List the player's own pending items to collect (browser, player-token). Each row's
+     * `kind` tells you which action to call: `"identity_gate"` → `approve*` (you initiated);
+     * `"receiving_confirm"` → `confirmReceipt*` (a peer sent to you). PII-free — no claim
+     * code or phone (those are only on the server-side `getInboundPending`).
+     */
+    getPendingCollect(opts?: CallOptions): Promise<PendingCollectResult>;
+    /**
+     * First-enrollment OTP grant (§4.2). When `enrollPasskey()` throws
+     * `ENROLLMENT_REQUIRES_AUTHORIZATION` (`err.isEnrollmentAuthorizationRequired`), call
+     * this to send a 6-digit code to the player's phone + email on file, collect the code,
+     * call `enrollmentVerify(code)`, then RETRY the SAME `enrollPasskey()` —
+     * `register/complete` auto-consumes the server-side grant (30-min TTL). For
+     * `ENROLLMENT_REQUIRES_PROOF` (`err.isEnrollmentProofRequired`) use `linkDevice` instead.
+     */
+    enrollmentBegin(opts?: CallOptions): Promise<EnrollmentBeginResult>;
+    /** Verify the enrollment OTP (see {@link enrollmentBegin}); on success, retry `enrollPasskey()`. */
+    enrollmentVerify(code: string, opts?: CallOptions): Promise<EnrollmentVerifyResult>;
     /** POST with the current player token. Token-expiry retry is handled one level
      *  up by withTokenRetry (which re-runs the whole ceremony, not a single call). */
     private post;
+    private get;
     /**
      * Run a whole flow, retrying it ONCE if any call fails with SDK_TOKEN_EXPIRED
      * and a `refreshToken` hook is configured. We re-run the entire begin→get→
@@ -49,4 +68,4 @@ declare class InvoClient {
     private confirmReceipt;
 }
-export { ApproveResult, CallOptions, ClientConfig, ConfirmReceiptResult, InvoClient, LinkDeviceResult };
+export { ApproveResult, CallOptions, ClientConfig, ConfirmReceiptResult, EnrollmentBeginResult, EnrollmentVerifyResult, InvoClient, LinkDeviceResult, PendingCollectResult };

package/dist/index.d.ts CHANGED Viewed

@@ -1,5 +1,5 @@
-import { C as ClientConfig, a as CallOptions, A as ApproveResult, b as ConfirmReceiptResult, L as LinkDeviceResult } from './types-CBMLNwbe.js';
-export { I as InvoError, c as InvoErrorInfo, d as InvoHooks, e as InvoRequestInfo, f as InvoResponseInfo, R as Rail, V as VerificationMethod } from './types-CBMLNwbe.js';
+import { C as ClientConfig, a as CallOptions, A as ApproveResult, b as ConfirmReceiptResult, L as LinkDeviceResult, P as PendingCollectResult, E as EnrollmentBeginResult, c as EnrollmentVerifyResult } from './types-v8bDu2_p.js';
+export { I as InvoError, d as InvoErrorInfo, e as InvoHooks, f as InvoRequestInfo, g as InvoResponseInfo, h as PendingCollectItem, R as Rail, V as VerificationMethod } from './types-v8bDu2_p.js';
 declare class InvoClient {
     private readonly http;
@@ -32,9 +32,28 @@ declare class InvoClient {
      * begin -> navigator.credentials.get() -> complete with { link_id, webauthn_assertion }.
      */
     linkDevice(linkId: string, opts?: CallOptions): Promise<LinkDeviceResult>;
+    /**
+     * List the player's own pending items to collect (browser, player-token). Each row's
+     * `kind` tells you which action to call: `"identity_gate"` → `approve*` (you initiated);
+     * `"receiving_confirm"` → `confirmReceipt*` (a peer sent to you). PII-free — no claim
+     * code or phone (those are only on the server-side `getInboundPending`).
+     */
+    getPendingCollect(opts?: CallOptions): Promise<PendingCollectResult>;
+    /**
+     * First-enrollment OTP grant (§4.2). When `enrollPasskey()` throws
+     * `ENROLLMENT_REQUIRES_AUTHORIZATION` (`err.isEnrollmentAuthorizationRequired`), call
+     * this to send a 6-digit code to the player's phone + email on file, collect the code,
+     * call `enrollmentVerify(code)`, then RETRY the SAME `enrollPasskey()` —
+     * `register/complete` auto-consumes the server-side grant (30-min TTL). For
+     * `ENROLLMENT_REQUIRES_PROOF` (`err.isEnrollmentProofRequired`) use `linkDevice` instead.
+     */
+    enrollmentBegin(opts?: CallOptions): Promise<EnrollmentBeginResult>;
+    /** Verify the enrollment OTP (see {@link enrollmentBegin}); on success, retry `enrollPasskey()`. */
+    enrollmentVerify(code: string, opts?: CallOptions): Promise<EnrollmentVerifyResult>;
     /** POST with the current player token. Token-expiry retry is handled one level
      *  up by withTokenRetry (which re-runs the whole ceremony, not a single call). */
     private post;
+    private get;
     /**
      * Run a whole flow, retrying it ONCE if any call fails with SDK_TOKEN_EXPIRED
      * and a `refreshToken` hook is configured. We re-run the entire begin→get→
@@ -49,4 +68,4 @@ declare class InvoClient {
     private confirmReceipt;
 }
-export { ApproveResult, CallOptions, ClientConfig, ConfirmReceiptResult, InvoClient, LinkDeviceResult };
+export { ApproveResult, CallOptions, ClientConfig, ConfirmReceiptResult, EnrollmentBeginResult, EnrollmentVerifyResult, InvoClient, LinkDeviceResult, PendingCollectResult };

package/dist/index.js CHANGED Viewed

@@ -1,5 +1,5 @@
-import { assertSecureBaseUrl, Http, InvoError } from './chunk-JOVATUDY.js';
-export { InvoError } from './chunk-JOVATUDY.js';
+import { assertSecureBaseUrl, Http, InvoError } from './chunk-D3XBTH4C.js';
+export { InvoError } from './chunk-D3XBTH4C.js';
 // src/shared/webauthn.ts
 function b64urlToBuffer(value) {
@@ -83,6 +83,21 @@ function assertionToJSON(cred) {
 }
 // src/index.ts
+function toPendingCollectItem(row) {
+  return {
+    transferId: String(row["transfer_id"] ?? ""),
+    kind: String(row["kind"] ?? ""),
+    flow: String(row["flow"] ?? ""),
+    amount: row["amount"] ?? null,
+    currency: String(row["currency"] ?? ""),
+    counterpartyGame: String(row["counterparty_game"] ?? ""),
+    expiresAt: row["expires_at"] ?? null,
+    stepUpRequired: row["step_up_required"] === true,
+    held: row["held"] === true,
+    holdReason: row["hold_reason"] ?? null,
+    raw: row
+  };
+}
 var InvoClient = class {
   constructor(config) {
     if (!config.token) throw new Error("InvoClient requires a player `token`.");
@@ -175,12 +190,65 @@ var InvoClient = class {
       return { status: String(raw["status"] ?? ""), raw };
     });
   }
+  /**
+   * List the player's own pending items to collect (browser, player-token). Each row's
+   * `kind` tells you which action to call: `"identity_gate"` → `approve*` (you initiated);
+   * `"receiving_confirm"` → `confirmReceipt*` (a peer sent to you). PII-free — no claim
+   * code or phone (those are only on the server-side `getInboundPending`).
+   */
+  async getPendingCollect(opts) {
+    return this.withTokenRetry(async () => {
+      const raw = await this.get(
+        "/api/sdk/transfers/pending",
+        opts?.signal
+      );
+      const rows = Array.isArray(raw["pending"]) ? raw["pending"] : [];
+      return { pending: rows.map(toPendingCollectItem), raw };
+    });
+  }
+  /**
+   * First-enrollment OTP grant (§4.2). When `enrollPasskey()` throws
+   * `ENROLLMENT_REQUIRES_AUTHORIZATION` (`err.isEnrollmentAuthorizationRequired`), call
+   * this to send a 6-digit code to the player's phone + email on file, collect the code,
+   * call `enrollmentVerify(code)`, then RETRY the SAME `enrollPasskey()` —
+   * `register/complete` auto-consumes the server-side grant (30-min TTL). For
+   * `ENROLLMENT_REQUIRES_PROOF` (`err.isEnrollmentProofRequired`) use `linkDevice` instead.
+   */
+  async enrollmentBegin(opts) {
+    return this.withTokenRetry(async () => {
+      const raw = await this.post(
+        "/api/sdk/device/enrollment/begin",
+        void 0,
+        opts?.signal
+      );
+      return {
+        status: String(raw["status"] ?? ""),
+        channels: Array.isArray(raw["channels"]) ? raw["channels"] : [],
+        raw
+      };
+    });
+  }
+  /** Verify the enrollment OTP (see {@link enrollmentBegin}); on success, retry `enrollPasskey()`. */
+  async enrollmentVerify(code, opts) {
+    if (!code) throw new Error("enrollmentVerify requires the OTP `code`.");
+    return this.withTokenRetry(async () => {
+      const raw = await this.post(
+        "/api/sdk/device/enrollment/verify",
+        { code },
+        opts?.signal
+      );
+      return { status: String(raw["status"] ?? ""), raw };
+    });
+  }
   // --- internals ---
   /** POST with the current player token. Token-expiry retry is handled one level
    *  up by withTokenRetry (which re-runs the whole ceremony, not a single call). */
   async post(path, body, signal) {
     return this.http.post(path, body, this.auth, { signal });
   }
+  async get(path, signal) {
+    return this.http.get(path, this.auth, { signal });
+  }
   /**
    * Run a whole flow, retrying it ONCE if any call fails with SDK_TOKEN_EXPIRED
    * and a `refreshToken` hook is configured. We re-run the entire begin→get→
@@ -234,12 +302,17 @@ var InvoClient = class {
         { webauthn_assertion: assertion },
         signal
       );
+      const holdReason = raw["error_code"] ?? raw["code"];
       return {
         status: String(raw["status"] ?? ""),
         next: String(raw["next"] ?? ""),
         transactionId: String(raw["transaction_id"] ?? transactionId),
         claimCode: raw["claim_code"],
         claimCodeExpiresAt: raw["claim_code_expires_at"],
+        holdReason: typeof holdReason === "string" ? holdReason : void 0,
+        risk: raw["risk"],
+        guardianApproval: raw["guardian_approval"] ?? void 0,
+        pollEndpoint: raw["poll_endpoint"],
         raw
       };
     });
@@ -258,7 +331,12 @@ var InvoClient = class {
         { webauthn_assertion: assertion },
         signal
       );
-      return { status: String(raw["status"] ?? ""), raw };
+      const holdReason = raw["error_code"] ?? raw["code"];
+      return {
+        status: String(raw["status"] ?? ""),
+        holdReason: typeof holdReason === "string" ? holdReason : void 0,
+        raw
+      };
     });
   }
 };

package/dist/server.cjs CHANGED Viewed

@@ -21,6 +21,14 @@ var InvoError = class _InvoError extends Error {
   get isTokenExpired() {
     return this.code === "SDK_TOKEN_EXPIRED";
   }
+  /** True if `enrollPasskey()` needs the OTP-grant flow (`enrollmentBegin`/`enrollmentVerify`). */
+  get isEnrollmentAuthorizationRequired() {
+    return this.code === "ENROLLMENT_REQUIRES_AUTHORIZATION";
+  }
+  /** True if enrolling is blocked because another method exists — use `linkDevice`. */
+  get isEnrollmentProofRequired() {
+    return this.code === "ENROLLMENT_REQUIRES_PROOF";
+  }
   /**
    * 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.
@@ -631,6 +639,7 @@ var InvoServer = class {
     if (input.savedCardId) body["saved_card_id"] = input.savedCardId;
     if (input.playerName) body["player_name"] = input.playerName;
     if (input.playerPhone) body["player_phone"] = input.playerPhone;
+    if (input.metadata) body["metadata"] = input.metadata;
     const raw = await this.http.post(
       "/api/currency-purchases/purchase-currency",
       body,

package/dist/server.d.cts CHANGED Viewed

@@ -1,5 +1,5 @@
-import { I as InvoError, S as ServerConfig, a as CallOptions, P as PlayerToken, g as InitiateSendInput, h as InitiateResult, i as InitiateTransferInput, j as CreateCheckoutInput, k as CreateCheckoutResult, l as PurchaseInput, m as PurchaseResult, n as ConfirmPaymentResult, O as OrderDetailsResult, o as PurchaseItemInput, p as PurchaseItemResult, q as ItemHistoryQuery, r as ItemHistoryResult, s as ItemOrderQuery, t as PlayerBalanceQuery, u as PlayerBalanceResult, v as InboundPendingQuery, w as InboundPendingResult } from './types-CBMLNwbe.cjs';
-export { x as CurrencyBalance, y as InboundPendingItem, c as InvoErrorInfo, d as InvoHooks, e as InvoRequestInfo, f as InvoResponseInfo, R as Rail, V as VerificationMethod } from './types-CBMLNwbe.cjs';
+import { I as InvoError, S as ServerConfig, a as CallOptions, i as PlayerToken, j as InitiateSendInput, k as InitiateResult, l as InitiateTransferInput, m as CreateCheckoutInput, n as CreateCheckoutResult, o as PurchaseInput, p as PurchaseResult, q as ConfirmPaymentResult, O as OrderDetailsResult, r as PurchaseItemInput, s as PurchaseItemResult, t as ItemHistoryQuery, u as ItemHistoryResult, v as ItemOrderQuery, w as PlayerBalanceQuery, x as PlayerBalanceResult, y as InboundPendingQuery, z as InboundPendingResult } from './types-v8bDu2_p.cjs';
+export { B as CurrencyBalance, D as InboundPendingItem, d as InvoErrorInfo, e as InvoHooks, f as InvoRequestInfo, g as InvoResponseInfo, R as Rail, V as VerificationMethod } from './types-v8bDu2_p.cjs';
 interface VerifyWebhookOptions {
     /** Max age of the signed timestamp, in seconds. Default 300 (5 min). */
@@ -25,6 +25,8 @@ interface PurchaseCompletedData {
     currency_name: string;
     new_balance: string;
     rail: string;
+    /** The metadata you passed to createCheckout/purchaseCurrency, echoed back (all rails). */
+    metadata?: Record<string, unknown>;
     [key: string]: unknown;
 }
 interface PurchaseEventData {

package/dist/server.d.ts CHANGED Viewed

@@ -1,5 +1,5 @@
-import { I as InvoError, S as ServerConfig, a as CallOptions, P as PlayerToken, g as InitiateSendInput, h as InitiateResult, i as InitiateTransferInput, j as CreateCheckoutInput, k as CreateCheckoutResult, l as PurchaseInput, m as PurchaseResult, n as ConfirmPaymentResult, O as OrderDetailsResult, o as PurchaseItemInput, p as PurchaseItemResult, q as ItemHistoryQuery, r as ItemHistoryResult, s as ItemOrderQuery, t as PlayerBalanceQuery, u as PlayerBalanceResult, v as InboundPendingQuery, w as InboundPendingResult } from './types-CBMLNwbe.js';
-export { x as CurrencyBalance, y as InboundPendingItem, c as InvoErrorInfo, d as InvoHooks, e as InvoRequestInfo, f as InvoResponseInfo, R as Rail, V as VerificationMethod } from './types-CBMLNwbe.js';
+import { I as InvoError, S as ServerConfig, a as CallOptions, i as PlayerToken, j as InitiateSendInput, k as InitiateResult, l as InitiateTransferInput, m as CreateCheckoutInput, n as CreateCheckoutResult, o as PurchaseInput, p as PurchaseResult, q as ConfirmPaymentResult, O as OrderDetailsResult, r as PurchaseItemInput, s as PurchaseItemResult, t as ItemHistoryQuery, u as ItemHistoryResult, v as ItemOrderQuery, w as PlayerBalanceQuery, x as PlayerBalanceResult, y as InboundPendingQuery, z as InboundPendingResult } from './types-v8bDu2_p.js';
+export { B as CurrencyBalance, D as InboundPendingItem, d as InvoErrorInfo, e as InvoHooks, f as InvoRequestInfo, g as InvoResponseInfo, R as Rail, V as VerificationMethod } from './types-v8bDu2_p.js';
 interface VerifyWebhookOptions {
     /** Max age of the signed timestamp, in seconds. Default 300 (5 min). */
@@ -25,6 +25,8 @@ interface PurchaseCompletedData {
     currency_name: string;
     new_balance: string;
     rail: string;
+    /** The metadata you passed to createCheckout/purchaseCurrency, echoed back (all rails). */
+    metadata?: Record<string, unknown>;
     [key: string]: unknown;
 }
 interface PurchaseEventData {

package/dist/server.js CHANGED Viewed

@@ -1,5 +1,5 @@
-import { InvoError, assertSecureBaseUrl, Http } from './chunk-JOVATUDY.js';
-export { InvoError } from './chunk-JOVATUDY.js';
+import { InvoError, assertSecureBaseUrl, Http } from './chunk-D3XBTH4C.js';
+export { InvoError } from './chunk-D3XBTH4C.js';
 import { createHmac } from 'crypto';
 var DEFAULT_TOLERANCE_SEC = 300;
@@ -382,6 +382,7 @@ var InvoServer = class {
     if (input.savedCardId) body["saved_card_id"] = input.savedCardId;
     if (input.playerName) body["player_name"] = input.playerName;
     if (input.playerPhone) body["player_phone"] = input.playerPhone;
+    if (input.metadata) body["metadata"] = input.metadata;
     const raw = await this.http.post(
       "/api/currency-purchases/purchase-currency",
       body,

package/dist/{types-CBMLNwbe.d.cts → types-v8bDu2_p.d.cts} RENAMED Viewed

@@ -26,6 +26,10 @@ 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 `enrollPasskey()` needs the OTP-grant flow (`enrollmentBegin`/`enrollmentVerify`). */
+    get isEnrollmentAuthorizationRequired(): boolean;
+    /** True if enrolling is blocked because another method exists — use `linkDevice`. */
+    get isEnrollmentProofRequired(): 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.
@@ -176,6 +180,8 @@ interface PurchaseInput {
     savedCardId?: string;
     playerName?: string;
     playerPhone?: string;
+    /** Arbitrary metadata echoed back on the purchase.completed webhook (data.metadata). */
+    metadata?: Record<string, unknown>;
 }
 type PurchaseStatus = "success" | "requires_action" | "pending_payment";
 interface PurchaseResult {
@@ -306,9 +312,58 @@ interface ApproveResult {
     /** transfer-approve returns the sender's claim code; send-approve does not. */
     claimCode?: string;
     claimCodeExpiresAt?: string;
+    /**
+     * Present when the approve came back as an HTTP 202 **hold** rather than success —
+     * e.g. `"RISK_HOLD"`, `"GUARDIAN_APPROVAL_PENDING"`, `"STEP_UP_REQUIRED"` (the last
+     * only on non-passkey approvals). Success carries no holdReason. Terminal guardian
+     * outcomes (`GUARDIAN_APPROVAL_REJECTED`/`_EXPIRED` 410, `..._CHECK_UNAVAILABLE` 503)
+     * are thrown as `InvoError` instead.
+     */
+    holdReason?: string;
+    /** Risk-engine detail on a RISK_HOLD: `{ decision, reasons[] }`. */
+    risk?: Record<string, unknown>;
+    /** The guardian_approval audit object on GUARDIAN_APPROVAL_PENDING. */
+    guardianApproval?: unknown;
+    /** Poll endpoint for guardian status (transfer holds only). */
+    pollEndpoint?: string;
     raw: Record<string, unknown>;
 }
 interface ConfirmReceiptResult {
+    status: string;
+    /** Present on a 202 hold — e.g. `"RECIPIENT_IDENTITY_PENDING"`. */
+    holdReason?: string;
+    raw: Record<string, unknown>;
+}
+interface PendingCollectItem {
+    /** The transaction id — note the backend key is `transfer_id`. */
+    transferId: string;
+    /** "identity_gate" (you initiated → call approve*) | "receiving_confirm" (peer send → call confirmReceipt*). */
+    kind: string;
+    /** "transfer" | "send". */
+    flow: string;
+    amount: string | null;
+    /** Currency name (not id). */
+    currency: string;
+    /** Tenant name — destination (identity_gate) or source (receiving_confirm). */
+    counterpartyGame: string;
+    expiresAt: string | null;
+    stepUpRequired: boolean;
+    held: boolean;
+    /** "guardian_pending" | "device_requires_elevation" | null. */
+    holdReason: string | null;
+    raw: Record<string, unknown>;
+}
+interface PendingCollectResult {
+    pending: PendingCollectItem[];
+    raw: Record<string, unknown>;
+}
+interface EnrollmentBeginResult {
+    status: string;
+    /** Channels the OTP was sent to, e.g. ["sms","email"]. */
+    channels: string[];
+    raw: Record<string, unknown>;
+}
+interface EnrollmentVerifyResult {
     status: string;
     raw: Record<string, unknown>;
 }
@@ -318,4 +373,4 @@ interface LinkDeviceResult {
     raw: Record<string, unknown>;
 }
-export { type ApproveResult as A, type ClientConfig as C, InvoError as I, type LinkDeviceResult as L, type OrderDetailsResult as O, type PlayerToken as P, type Rail as R, type ServerConfig as S, type VerificationMethod as V, type CallOptions as a, type ConfirmReceiptResult as b, type InvoErrorInfo as c, type InvoHooks as d, type InvoRequestInfo as e, type InvoResponseInfo as f, type InitiateSendInput as g, type InitiateResult as h, type InitiateTransferInput as i, type CreateCheckoutInput as j, type CreateCheckoutResult as k, type PurchaseInput as l, type PurchaseResult as m, type ConfirmPaymentResult as n, type PurchaseItemInput as o, type PurchaseItemResult as p, type ItemHistoryQuery as q, type ItemHistoryResult as r, type ItemOrderQuery as s, type PlayerBalanceQuery as t, type PlayerBalanceResult as u, type InboundPendingQuery as v, type InboundPendingResult as w, type CurrencyBalance as x, type InboundPendingItem as y };
+export { type ApproveResult as A, type CurrencyBalance as B, type ClientConfig as C, type InboundPendingItem as D, type EnrollmentBeginResult as E, InvoError as I, type LinkDeviceResult as L, type OrderDetailsResult as O, type PendingCollectResult as P, type Rail as R, type ServerConfig as S, type VerificationMethod as V, type CallOptions as a, type ConfirmReceiptResult as b, type EnrollmentVerifyResult as c, type InvoErrorInfo as d, type InvoHooks as e, type InvoRequestInfo as f, type InvoResponseInfo as g, type PendingCollectItem as h, type PlayerToken as i, type InitiateSendInput as j, type InitiateResult as k, type InitiateTransferInput as l, type CreateCheckoutInput as m, type CreateCheckoutResult as n, type PurchaseInput as o, type PurchaseResult as p, type ConfirmPaymentResult as q, type PurchaseItemInput as r, type PurchaseItemResult as s, type ItemHistoryQuery as t, type ItemHistoryResult as u, type ItemOrderQuery as v, type PlayerBalanceQuery as w, type PlayerBalanceResult as x, type InboundPendingQuery as y, type InboundPendingResult as z };

package/dist/{types-CBMLNwbe.d.ts → types-v8bDu2_p.d.ts} RENAMED Viewed

@@ -26,6 +26,10 @@ 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 `enrollPasskey()` needs the OTP-grant flow (`enrollmentBegin`/`enrollmentVerify`). */
+    get isEnrollmentAuthorizationRequired(): boolean;
+    /** True if enrolling is blocked because another method exists — use `linkDevice`. */
+    get isEnrollmentProofRequired(): 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.
@@ -176,6 +180,8 @@ interface PurchaseInput {
     savedCardId?: string;
     playerName?: string;
     playerPhone?: string;
+    /** Arbitrary metadata echoed back on the purchase.completed webhook (data.metadata). */
+    metadata?: Record<string, unknown>;
 }
 type PurchaseStatus = "success" | "requires_action" | "pending_payment";
 interface PurchaseResult {
@@ -306,9 +312,58 @@ interface ApproveResult {
     /** transfer-approve returns the sender's claim code; send-approve does not. */
     claimCode?: string;
     claimCodeExpiresAt?: string;
+    /**
+     * Present when the approve came back as an HTTP 202 **hold** rather than success —
+     * e.g. `"RISK_HOLD"`, `"GUARDIAN_APPROVAL_PENDING"`, `"STEP_UP_REQUIRED"` (the last
+     * only on non-passkey approvals). Success carries no holdReason. Terminal guardian
+     * outcomes (`GUARDIAN_APPROVAL_REJECTED`/`_EXPIRED` 410, `..._CHECK_UNAVAILABLE` 503)
+     * are thrown as `InvoError` instead.
+     */
+    holdReason?: string;
+    /** Risk-engine detail on a RISK_HOLD: `{ decision, reasons[] }`. */
+    risk?: Record<string, unknown>;
+    /** The guardian_approval audit object on GUARDIAN_APPROVAL_PENDING. */
+    guardianApproval?: unknown;
+    /** Poll endpoint for guardian status (transfer holds only). */
+    pollEndpoint?: string;
     raw: Record<string, unknown>;
 }
 interface ConfirmReceiptResult {
+    status: string;
+    /** Present on a 202 hold — e.g. `"RECIPIENT_IDENTITY_PENDING"`. */
+    holdReason?: string;
+    raw: Record<string, unknown>;
+}
+interface PendingCollectItem {
+    /** The transaction id — note the backend key is `transfer_id`. */
+    transferId: string;
+    /** "identity_gate" (you initiated → call approve*) | "receiving_confirm" (peer send → call confirmReceipt*). */
+    kind: string;
+    /** "transfer" | "send". */
+    flow: string;
+    amount: string | null;
+    /** Currency name (not id). */
+    currency: string;
+    /** Tenant name — destination (identity_gate) or source (receiving_confirm). */
+    counterpartyGame: string;
+    expiresAt: string | null;
+    stepUpRequired: boolean;
+    held: boolean;
+    /** "guardian_pending" | "device_requires_elevation" | null. */
+    holdReason: string | null;
+    raw: Record<string, unknown>;
+}
+interface PendingCollectResult {
+    pending: PendingCollectItem[];
+    raw: Record<string, unknown>;
+}
+interface EnrollmentBeginResult {
+    status: string;
+    /** Channels the OTP was sent to, e.g. ["sms","email"]. */
+    channels: string[];
+    raw: Record<string, unknown>;
+}
+interface EnrollmentVerifyResult {
     status: string;
     raw: Record<string, unknown>;
 }
@@ -318,4 +373,4 @@ interface LinkDeviceResult {
     raw: Record<string, unknown>;
 }
-export { type ApproveResult as A, type ClientConfig as C, InvoError as I, type LinkDeviceResult as L, type OrderDetailsResult as O, type PlayerToken as P, type Rail as R, type ServerConfig as S, type VerificationMethod as V, type CallOptions as a, type ConfirmReceiptResult as b, type InvoErrorInfo as c, type InvoHooks as d, type InvoRequestInfo as e, type InvoResponseInfo as f, type InitiateSendInput as g, type InitiateResult as h, type InitiateTransferInput as i, type CreateCheckoutInput as j, type CreateCheckoutResult as k, type PurchaseInput as l, type PurchaseResult as m, type ConfirmPaymentResult as n, type PurchaseItemInput as o, type PurchaseItemResult as p, type ItemHistoryQuery as q, type ItemHistoryResult as r, type ItemOrderQuery as s, type PlayerBalanceQuery as t, type PlayerBalanceResult as u, type InboundPendingQuery as v, type InboundPendingResult as w, type CurrencyBalance as x, type InboundPendingItem as y };
+export { type ApproveResult as A, type CurrencyBalance as B, type ClientConfig as C, type InboundPendingItem as D, type EnrollmentBeginResult as E, InvoError as I, type LinkDeviceResult as L, type OrderDetailsResult as O, type PendingCollectResult as P, type Rail as R, type ServerConfig as S, type VerificationMethod as V, type CallOptions as a, type ConfirmReceiptResult as b, type EnrollmentVerifyResult as c, type InvoErrorInfo as d, type InvoHooks as e, type InvoRequestInfo as f, type InvoResponseInfo as g, type PendingCollectItem as h, type PlayerToken as i, type InitiateSendInput as j, type InitiateResult as k, type InitiateTransferInput as l, type CreateCheckoutInput as m, type CreateCheckoutResult as n, type PurchaseInput as o, type PurchaseResult as p, type ConfirmPaymentResult as q, type PurchaseItemInput as r, type PurchaseItemResult as s, type ItemHistoryQuery as t, type ItemHistoryResult as u, type ItemOrderQuery as v, type PlayerBalanceQuery as w, type PlayerBalanceResult as x, type InboundPendingQuery as y, type InboundPendingResult as z };

package/package.json CHANGED Viewed

@@ -1,76 +1,76 @@
-{
-  "name": "@invonetwork/web-sdk",
-  "version": "0.4.2",
-  "description": "INVO Web SDK — currency purchase + passkey (WebAuthn) verification for partner web platforms.",
-  "license": "SEE LICENSE IN LICENSE",
-  "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",
-    "lint": "eslint .",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "clean": "rimraf dist",
-    "changeset": "changeset",
-    "version-packages": "changeset version",
-    "release": "npm run build && changeset publish",
-    "prepublishOnly": "npm run clean && npm run build"
-  },
-  "keywords": [
-    "invo",
-    "webauthn",
-    "passkey",
-    "payments",
-    "game-currency",
-    "sdk"
-  ],
-  "publishConfig": {
-    "access": "public"
-  },
-  "devDependencies": {
-    "@changesets/cli": "^2.31.0",
-    "@eslint/js": "^10.0.1",
-    "eslint": "^10.6.0",
-    "rimraf": "^5.0.5",
-    "tsup": "^8.0.1",
-    "typescript": "^5.4.5",
-    "typescript-eslint": "^8.62.1",
-    "vitest": "^1.5.0"
-  }
-}
+{
+  "name": "@invonetwork/web-sdk",
+  "version": "0.6.0",
+  "description": "INVO Web SDK — currency purchase + passkey (WebAuthn) verification for partner web platforms.",
+  "license": "SEE LICENSE IN LICENSE",
+  "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",
+    "lint": "eslint .",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "clean": "rimraf dist",
+    "changeset": "changeset",
+    "version-packages": "changeset version",
+    "release": "npm run build && changeset publish",
+    "prepublishOnly": "npm run clean && npm run build"
+  },
+  "keywords": [
+    "invo",
+    "webauthn",
+    "passkey",
+    "payments",
+    "game-currency",
+    "sdk"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@changesets/cli": "^2.31.0",
+    "@eslint/js": "^10.0.1",
+    "eslint": "^10.6.0",
+    "rimraf": "^5.0.5",
+    "tsup": "^8.0.1",
+    "typescript": "^5.4.5",
+    "typescript-eslint": "^8.62.1",
+    "vitest": "^1.5.0"
+  }
+}