@invonetwork/web-sdk 0.7.0 → 1.0.0

package/CHANGELOG.md

@@ -1,179 +1,208 @@
-# 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.7.0] — 2026-07-01
-
-Start of the **discovery layer** for send/transfer UIs.
-
-- **`InvoClient.getDestinations({ direction })`** — one player-token call
-  (`GET /api/sdk/destinations`) returns every game the player can send/transfer to, with
-  all display metadata **inline** (game name, icon, currency name/symbol, min/max transfer
-  limits) — no per-game lookup. Includes source game/currency info and `transferMode`
-  (`universal`/`linked` + `linkedGameIds`).
-- _(Coming in 0.7.x: `getBalance` single-game player-token read; `getLinkedIdentities`
-  server-side.)_
-
-## [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).
+# 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).
+
+## [1.0.0] — 2026-07-01
+
+**1.0 — stable.** The public API is now covered by a stability commitment: it follows
+semver and no breaking change ships without a major bump + migration note. This is a
+milestone release, **not a breaking change** — code on `0.8.x` continues to work unchanged.
+
+Also in this release (docs + DX):
+
+- **Integration modes** documented — **browser-direct** (default) and **behind your proxy**
+  (keep the INVO player token server-side via a custom `baseUrl`/`fetch`; no CORS or
+  security-posture change). Plus a token-bootstrap example and a CORS + RP-ID/origins
+  go-live checklist.
+- `linkDevice` called out as the lowest-risk first adoption (additive, no refactor).
+
+## [0.8.0] — 2026-07-01
+
+Completes the **discovery layer** for send/transfer UIs.
+
+- **`InvoClient.getBalance()`** (browser, player-token, `GET /api/sdk/balance`) — the
+  player's balances for the token's game: `balances[]` (`currencyId`, `currencyName`,
+  `currencySymbol`/`currencySymbolUrl` (nullable), `availableBalance`/`reservedBalance`/
+  `totalBalance` as decimal strings) plus `totalValue` / `currencyCount` / `hasFunds`. A
+  player who hasn't transacted here yet returns an empty `balances` array (a `200`, not an
+  error); `404 GAME_NOT_FOUND` throws.
+- **`InvoServer.getLinkedIdentities({ playerEmail | playerPhone })`** (server-only,
+  game-secret) — a player's linked wallet identities (game-scoped). Provide one identifier
+  (phone wins if both); no in-game match returns `notFound: true` with empty `emails`
+  instead of throwing. **Returns first-party PII — never expose to the browser.**
+
+## [0.7.0] — 2026-07-01
+
+Start of the **discovery layer** for send/transfer UIs.
+
+- **`InvoClient.getDestinations({ direction })`** — one player-token call
+  (`GET /api/sdk/destinations`) returns every game the player can send/transfer to, with
+  all display metadata **inline** (game name, icon, currency name/symbol, min/max transfer
+  limits) — no per-game lookup. Includes source game/currency info and `transferMode`
+  (`universal`/`linked` + `linkedGameIds`).
+- _(Coming in 0.7.x: `getBalance` single-game player-token read; `getLinkedIdentities`
+  server-side.)_
+
+## [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

@@ -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.7.0`, published on npm. The backend it wraps is **live** on sandbox + production, so you can build and test against sandbox today.
+> **Status:** `v1.0.0` — stable, published on npm. The backend it wraps is **live** on sandbox + production. The API is now covered by a [stability commitment](#stability): no breaking changes without a major bump.
 > Canonical partner reference: **https://docs.invo.network/docs/currency-purchase** and **https://docs.invo.network/docs/game-developer-integration**.
 
 ## What it does
@@ -78,12 +78,54 @@ Build and test against the **dev console + sandbox** first, then switch to the *
 
 **Never import `/server` into browser code** — it carries the game secret. The two entries are built separately for exactly this reason.
 
+## Integration modes
+
+`InvoClient` needs a `token` and a `baseUrl` — which lets you adopt it **two ways**. Same SDK, same code in your components; only the config differs.
+
+### Token bootstrap (both modes)
+
+Expose one small backend endpoint that calls `mintPlayerToken` (server-side, with the game secret) and hand the token to the browser:
+
+```ts
+// browser
+const client = new InvoClient({
+  baseUrl: "https://api.invo.network",
+  token: await fetch("/your/sdk-token").then((r) => r.json()).then((j) => j.token),
+  // Called automatically on SDK_TOKEN_EXPIRED (~15 min TTL) — just re-fetch from your backend:
+  refreshToken: () => fetch("/your/sdk-token").then((r) => r.json()).then((j) => j.token),
+});
+```
+
+### Mode A — browser-direct (default)
+
+The browser holds the short-lived, game-scoped player token and calls INVO directly (`baseUrl` = the INVO API). Fewer moving parts. Requires INVO to **CORS-allow your web origin** and to have your **RP ID / origins** set up for passkeys (see [Before you go live](#before-you-go-live)).
+
+### Mode B — behind your proxy (keep the token server-side)
+
+If your architecture requires the INVO player token to **never reach the browser**, route the SDK through your own backend — **no CORS setup needed, and no security-posture change**:
+
+- Set `baseUrl` to your proxy (e.g. `https://yourgame.com/invo`), which forwards to the INVO API and **injects the real `Authorization` header server-side**.
+- Give the browser a short-lived **session/CSRF token** (not the INVO token) as `token`; your proxy validates it and swaps in the real player token. Or use cookie auth with a custom `fetch`:
+
+```ts
+const client = new InvoClient({
+  baseUrl: "https://yourgame.com/invo",   // your proxy → INVO
+  token: sessionToken,                     // your token; the proxy swaps in the real one
+  fetch: (url, init) => fetch(url, { ...init, credentials: "include" }), // send your cookie
+});
+```
+
+The WebAuthn ceremony still runs in the browser (it must — it's `navigator.credentials`), but transport/auth stays behind your proxy. You keep the SDK's ceremony handling, token-refresh, typed holds, and error classifiers either way.
+
+> **Lowest-risk first step:** adopt just `linkDevice` (passkey ↔ app device interchange) — it's purely additive and needs no refactor. See [Passkeys](#passkeys-enroll-approve-link).
+
 ## Before you go live
 
 INVO enables each flow for your tenant in the [console](#get-your-account--game-secret-invo-console). What you need to do:
 
 - **Store the game secret server-side** and expose a small endpoint that calls `mintPlayerToken` so the browser can fetch/refresh its token. Never ship the secret to the browser.
-- **For passkeys (sends/transfers):** give INVO the **web origin(s)** you'll serve from. Passkeys only validate on approved origins — if a call returns `WEBAUTHN_NOT_ENABLED_FOR_TENANT`, your origins aren't set up yet; contact INVO. (Until enrolled, the sender falls back to the SMS-PIN path automatically.)
+- **If you use browser-direct ([Mode A](#mode-a--browser-direct-default)):** ask INVO to **CORS-allow your web origin(s)** so the browser can call the API directly. (Not needed for [Mode B / proxy](#mode-b--behind-your-proxy-keep-the-token-server-side) — those requests are same-origin to your backend.)
+- **For passkeys (sends/transfers):** give INVO the **RP ID + web origin(s)** you'll serve from. Passkeys only validate on approved origins — if a call returns `WEBAUTHN_NOT_ENABLED_FOR_TENANT`, your origins aren't set up yet; contact INVO. (Until enrolled, the sender falls back to the SMS-PIN path automatically.)
 - **For currency purchase:** card checkout works out of the box; ask INVO to enable the `game`/`steam` rails if you need them.
 - **For item purchase:** nothing extra — it's a currency-balance debit.
 
@@ -258,6 +300,13 @@ const { availableGames, sourceCurrencyName } = await client.getDestinations({ di
 // each: { gameId, gameName, gameIcon, currencyName, currencySymbol, minimumTransfer, maximumTransfer, … }
 ```
 
+**What do I have? (browser, v0.8.0+)** — `client.getBalance()` returns the player's balances for this game (amounts are decimal strings; rows carry `currencySymbol`/`currencySymbolUrl`). A player who hasn't transacted here yet returns an empty `balances` array (show 0.00) — not an error:
+
+```ts
+const { balances, hasFunds, totalValue } = await client.getBalance();
+// each: { currencyId, currencyName, currencySymbol, availableBalance, reservedBalance, totalBalance }
+```
+
 ```ts
 // 1. SERVER — initiate, then branch on how the sender must verify
 const t = await server.initiateTransfer({
@@ -480,6 +529,7 @@ try {
 | `getItemOrderDetails({ orderId? \| transactionId? \| clientRequestId? })` | `{ order, financialSummary, statusTimeline, raw }` |
 | `getPlayerBalance({ playerEmail? \| playerId? })` | `{ player, balances, summary, raw }` |
 | `getInboundPending({ playerEmail? \| playerPhone? })` | `{ inboundPending, raw }` — live unclaimed inbound sends/transfers |
+| `getLinkedIdentities({ playerEmail? \| playerPhone? })` | `{ walletUserId, primaryEmail, primaryPhone, isMinor, emails, notFound, raw }` — **server-only** (returns PII) |
 | `iterateItemPurchaseHistory({ playerEmail, pageSize? })` | async iterator over all history rows |
 | `verifyWebhook(rawBody, signatureHeader, secret \| secrets, opts?)` | typed `InvoWebhookEvent` (throws on bad signature) |
 | `verifyWebhookAsync(...)` | same as `verifyWebhook`, Web Crypto (edge/Workers/Deno/Bun) |
@@ -498,6 +548,7 @@ Every method also accepts an optional final `{ signal }` (`AbortSignal`) for can
 | `linkDevice(linkId)` | `{ status, raw }` |
 | `getPendingCollect()` | `{ pending, raw }` — the player's own pending-to-collect list (player-token) |
 | `getDestinations({ direction? })` | `{ availableGames, sourceGameName, transferMode, … }` — where the player can send/transfer, metadata inline |
+| `getBalance()` | `{ gameId, gameName, balances, totalValue, currencyCount, hasFunds, raw }` — the player's balances for this game |
 
 Every method throws `InvoError` on failure and takes an optional final `{ signal }`. Full inline types ship with the package.
 
@@ -511,7 +562,11 @@ 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. 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`).
+### Stability
+
+As of **`1.0.0`** the public API is **stable**: it follows [semver](https://semver.org/), and **no breaking change ships without a major version bump + a migration note**. Patch = fixes, minor = additive surface (new methods/fields, backward-compatible), major = breaking changes (rare). The wire contract is the same live INVO API you'd call directly, and it's backward-compatible within a major — so a pinned SDK keeps working. Safe to depend on in production; pin a version and watch [releases](https://github.com/Invo-Technologies/invo-web-sdk/releases) 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/index.cjs

@@ -355,6 +355,18 @@ function toPendingCollectItem(row) {
     raw: row
   };
 }
+function toBalanceRow(row) {
+  return {
+    currencyId: row["currency_id"] ?? "",
+    currencyName: String(row["currency_name"] ?? ""),
+    currencySymbol: row["currency_symbol"] ?? null,
+    currencySymbolUrl: row["currency_symbol_url"] ?? null,
+    availableBalance: String(row["available_balance"] ?? ""),
+    reservedBalance: String(row["reserved_balance"] ?? ""),
+    totalBalance: String(row["total_balance"] ?? ""),
+    raw: row
+  };
+}
 function toDestinationGame(row) {
   const s = (k) => row[k] === void 0 || row[k] === null ? void 0 : String(row[k]);
   return {
@@ -516,6 +528,28 @@ var InvoClient = class {
       };
     });
   }
+  /**
+   * The player's balances for the token's game (browser, player-token). Amounts are
+   * decimal strings. A player who hasn't transacted here yet returns `200` with an empty
+   * `balances` array (show 0.00) — not an error; a `404 GAME_NOT_FOUND` (bad game/token)
+   * throws. Rows include the currency symbol + icon URL (each may be null).
+   */
+  async getBalance(opts) {
+    return this.withTokenRetry(async () => {
+      const raw = await this.get("/api/sdk/balance", opts?.signal);
+      const rows = Array.isArray(raw["balances"]) ? raw["balances"] : [];
+      const summary = raw["summary"] ?? {};
+      return {
+        gameId: raw["game_id"] ?? "",
+        gameName: String(raw["game_name"] ?? ""),
+        balances: rows.map(toBalanceRow),
+        totalValue: String(summary["total_value"] ?? "0"),
+        currencyCount: Number(summary["currency_count"] ?? rows.length),
+        hasFunds: summary["has_funds"] === true,
+        raw
+      };
+    });
+  }
   /**
    * First-enrollment OTP grant (§4.2). When `enrollPasskey()` throws
    * `ENROLLMENT_REQUIRES_AUTHORIZATION` (`err.isEnrollmentAuthorizationRequired`), call

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-import { C as ClientConfig, a as CallOptions, A as ApproveResult, b as ConfirmReceiptResult, L as LinkDeviceResult, P as PendingCollectResult, D as DestinationsQuery, c as DestinationsResult, E as EnrollmentBeginResult, d as EnrollmentVerifyResult } from './types-Bi_NMSkN.cjs';
-export { e as DestinationGame, I as InvoError, f as InvoErrorInfo, g as InvoHooks, h as InvoRequestInfo, i as InvoResponseInfo, j as PendingCollectItem, R as Rail, V as VerificationMethod } from './types-Bi_NMSkN.cjs';
+import { C as ClientConfig, a as CallOptions, A as ApproveResult, b as ConfirmReceiptResult, L as LinkDeviceResult, P as PendingCollectResult, D as DestinationsQuery, c as DestinationsResult, B as BalanceResult, E as EnrollmentBeginResult, d as EnrollmentVerifyResult } from './types-DLSCxpoT.cjs';
+export { e as BalanceRow, f as DestinationGame, I as InvoError, g as InvoErrorInfo, h as InvoHooks, i as InvoRequestInfo, j as InvoResponseInfo, k as PendingCollectItem, R as Rail, V as VerificationMethod } from './types-DLSCxpoT.cjs';
 
 declare class InvoClient {
     private readonly http;
@@ -45,6 +45,13 @@ declare class InvoClient {
      * Source game is the token's own game. Player-token (browser).
      */
     getDestinations(query?: DestinationsQuery, opts?: CallOptions): Promise<DestinationsResult>;
+    /**
+     * The player's balances for the token's game (browser, player-token). Amounts are
+     * decimal strings. A player who hasn't transacted here yet returns `200` with an empty
+     * `balances` array (show 0.00) — not an error; a `404 GAME_NOT_FOUND` (bad game/token)
+     * throws. Rows include the currency symbol + icon URL (each may be null).
+     */
+    getBalance(opts?: CallOptions): Promise<BalanceResult>;
     /**
      * First-enrollment OTP grant (§4.2). When `enrollPasskey()` throws
      * `ENROLLMENT_REQUIRES_AUTHORIZATION` (`err.isEnrollmentAuthorizationRequired`), call
@@ -74,4 +81,4 @@ declare class InvoClient {
     private confirmReceipt;
 }
 
-export { ApproveResult, CallOptions, ClientConfig, ConfirmReceiptResult, DestinationsQuery, DestinationsResult, EnrollmentBeginResult, EnrollmentVerifyResult, InvoClient, LinkDeviceResult, PendingCollectResult };
+export { ApproveResult, BalanceResult, CallOptions, ClientConfig, ConfirmReceiptResult, DestinationsQuery, DestinationsResult, EnrollmentBeginResult, EnrollmentVerifyResult, InvoClient, LinkDeviceResult, PendingCollectResult };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { C as ClientConfig, a as CallOptions, A as ApproveResult, b as ConfirmReceiptResult, L as LinkDeviceResult, P as PendingCollectResult, D as DestinationsQuery, c as DestinationsResult, E as EnrollmentBeginResult, d as EnrollmentVerifyResult } from './types-Bi_NMSkN.js';
-export { e as DestinationGame, I as InvoError, f as InvoErrorInfo, g as InvoHooks, h as InvoRequestInfo, i as InvoResponseInfo, j as PendingCollectItem, R as Rail, V as VerificationMethod } from './types-Bi_NMSkN.js';
+import { C as ClientConfig, a as CallOptions, A as ApproveResult, b as ConfirmReceiptResult, L as LinkDeviceResult, P as PendingCollectResult, D as DestinationsQuery, c as DestinationsResult, B as BalanceResult, E as EnrollmentBeginResult, d as EnrollmentVerifyResult } from './types-DLSCxpoT.js';
+export { e as BalanceRow, f as DestinationGame, I as InvoError, g as InvoErrorInfo, h as InvoHooks, i as InvoRequestInfo, j as InvoResponseInfo, k as PendingCollectItem, R as Rail, V as VerificationMethod } from './types-DLSCxpoT.js';
 
 declare class InvoClient {
     private readonly http;
@@ -45,6 +45,13 @@ declare class InvoClient {
      * Source game is the token's own game. Player-token (browser).
      */
     getDestinations(query?: DestinationsQuery, opts?: CallOptions): Promise<DestinationsResult>;
+    /**
+     * The player's balances for the token's game (browser, player-token). Amounts are
+     * decimal strings. A player who hasn't transacted here yet returns `200` with an empty
+     * `balances` array (show 0.00) — not an error; a `404 GAME_NOT_FOUND` (bad game/token)
+     * throws. Rows include the currency symbol + icon URL (each may be null).
+     */
+    getBalance(opts?: CallOptions): Promise<BalanceResult>;
     /**
      * First-enrollment OTP grant (§4.2). When `enrollPasskey()` throws
      * `ENROLLMENT_REQUIRES_AUTHORIZATION` (`err.isEnrollmentAuthorizationRequired`), call
@@ -74,4 +81,4 @@ declare class InvoClient {
     private confirmReceipt;
 }
 
-export { ApproveResult, CallOptions, ClientConfig, ConfirmReceiptResult, DestinationsQuery, DestinationsResult, EnrollmentBeginResult, EnrollmentVerifyResult, InvoClient, LinkDeviceResult, PendingCollectResult };
+export { ApproveResult, BalanceResult, CallOptions, ClientConfig, ConfirmReceiptResult, DestinationsQuery, DestinationsResult, EnrollmentBeginResult, EnrollmentVerifyResult, InvoClient, LinkDeviceResult, PendingCollectResult };

package/dist/index.js

@@ -98,6 +98,18 @@ function toPendingCollectItem(row) {
     raw: row
   };
 }
+function toBalanceRow(row) {
+  return {
+    currencyId: row["currency_id"] ?? "",
+    currencyName: String(row["currency_name"] ?? ""),
+    currencySymbol: row["currency_symbol"] ?? null,
+    currencySymbolUrl: row["currency_symbol_url"] ?? null,
+    availableBalance: String(row["available_balance"] ?? ""),
+    reservedBalance: String(row["reserved_balance"] ?? ""),
+    totalBalance: String(row["total_balance"] ?? ""),
+    raw: row
+  };
+}
 function toDestinationGame(row) {
   const s = (k) => row[k] === void 0 || row[k] === null ? void 0 : String(row[k]);
   return {
@@ -259,6 +271,28 @@ var InvoClient = class {
       };
     });
   }
+  /**
+   * The player's balances for the token's game (browser, player-token). Amounts are
+   * decimal strings. A player who hasn't transacted here yet returns `200` with an empty
+   * `balances` array (show 0.00) — not an error; a `404 GAME_NOT_FOUND` (bad game/token)
+   * throws. Rows include the currency symbol + icon URL (each may be null).
+   */
+  async getBalance(opts) {
+    return this.withTokenRetry(async () => {
+      const raw = await this.get("/api/sdk/balance", opts?.signal);
+      const rows = Array.isArray(raw["balances"]) ? raw["balances"] : [];
+      const summary = raw["summary"] ?? {};
+      return {
+        gameId: raw["game_id"] ?? "",
+        gameName: String(raw["game_name"] ?? ""),
+        balances: rows.map(toBalanceRow),
+        totalValue: String(summary["total_value"] ?? "0"),
+        currencyCount: Number(summary["currency_count"] ?? rows.length),
+        hasFunds: summary["has_funds"] === true,
+        raw
+      };
+    });
+  }
   /**
    * First-enrollment OTP grant (§4.2). When `enrollPasskey()` throws
    * `ENROLLMENT_REQUIRES_AUTHORIZATION` (`err.isEnrollmentAuthorizationRequired`), call

package/dist/server.cjs

@@ -418,7 +418,7 @@ async function hmacHexSubtle(secret, message) {
 }
 
 // src/server.ts
-var DEFAULT_UA = "invonetwork-web-sdk/0.4.0 (+https://invo.network)";
+var DEFAULT_UA = "invonetwork-web-sdk/1.0.0 (+https://invo.network)";
 var MAX_USD_AMOUNT = 999.99;
 var MAX_ITEM_PRICE = 999999.99;
 function invalidInput(label, value, why) {
@@ -458,6 +458,13 @@ function toOrderDetails(raw) {
     raw
   };
 }
+function toLinkedEmail(row) {
+  return {
+    email: String(row["email"] ?? ""),
+    primary: row["primary"] === true,
+    verifiedAt: row["verified_at"] ?? null
+  };
+}
 function toInboundPendingItem(row) {
   return {
     transactionId: String(row["transaction_id"] ?? ""),
@@ -877,6 +884,48 @@ var InvoServer = class {
     const rows = Array.isArray(raw["inbound_pending"]) ? raw["inbound_pending"] : [];
     return { inboundPending: rows.map(toInboundPendingItem), raw };
   }
+  /**
+   * Look up a player's linked wallet identities (SERVER-only, game-secret). Game-scoped:
+   * returns wallet members that also have a Player row on this game. Provide a `playerEmail`
+   * or `playerPhone` (phone wins if both). No in-game match (backend 404) returns
+   * `notFound: true` with empty `emails` — not an error.
+   *
+   * ⚠️ Returns first-party PII (emails/phones) — never expose this to the browser.
+   */
+  async getLinkedIdentities(query, opts) {
+    const phone = typeof query.playerPhone === "string" && query.playerPhone.trim() ? query.playerPhone.trim() : "";
+    const email = typeof query.playerEmail === "string" && query.playerEmail.trim() ? query.playerEmail.trim() : "";
+    if (!phone && !email) {
+      throw invalidInput("query", query, "requires a playerEmail or playerPhone");
+    }
+    const q = new URLSearchParams();
+    if (phone) q.set("player_phone", phone);
+    else q.set("player_email", email);
+    let raw;
+    try {
+      raw = await this.http.get(
+        `/api/wallet/identities?${q.toString()}`,
+        this.auth,
+        { signal: opts?.signal }
+      );
+    } catch (e) {
+      if (e instanceof InvoError && e.status === 404) {
+        const raw404 = e.body && typeof e.body === "object" ? e.body : {};
+        return { walletUserId: null, primaryEmail: "", primaryPhone: "", isMinor: false, emails: [], notFound: true, raw: raw404 };
+      }
+      throw e;
+    }
+    const emails = Array.isArray(raw["emails"]) ? raw["emails"].map(toLinkedEmail) : [];
+    return {
+      walletUserId: raw["wallet_user_id"] ?? null,
+      primaryEmail: String(raw["primary_email"] ?? ""),
+      primaryPhone: String(raw["primary_phone"] ?? ""),
+      isMinor: raw["is_minor"] === true,
+      emails,
+      notFound: false,
+      raw
+    };
+  }
   toInitiateResult(raw) {
     const vm = raw["verification_method"];
     const guardian = raw["guardian_approval"];

package/dist/server.d.cts

@@ -1,5 +1,5 @@
-import { I as InvoError, S as ServerConfig, a as CallOptions, k as PlayerToken, l as InitiateSendInput, m as InitiateResult, n as InitiateTransferInput, o as CreateCheckoutInput, p as CreateCheckoutResult, q as PurchaseInput, r as PurchaseResult, s as ConfirmPaymentResult, O as OrderDetailsResult, t as PurchaseItemInput, u as PurchaseItemResult, v as ItemHistoryQuery, w as ItemHistoryResult, x as ItemOrderQuery, y as PlayerBalanceQuery, z as PlayerBalanceResult, B as InboundPendingQuery, F as InboundPendingResult } from './types-Bi_NMSkN.cjs';
-export { G as CurrencyBalance, H as InboundPendingItem, f as InvoErrorInfo, g as InvoHooks, h as InvoRequestInfo, i as InvoResponseInfo, R as Rail, V as VerificationMethod } from './types-Bi_NMSkN.cjs';
+import { I as InvoError, S as ServerConfig, a as CallOptions, l as PlayerToken, m as InitiateSendInput, n as InitiateResult, o as InitiateTransferInput, p as CreateCheckoutInput, q as CreateCheckoutResult, r as PurchaseInput, s as PurchaseResult, t as ConfirmPaymentResult, O as OrderDetailsResult, u as PurchaseItemInput, v as PurchaseItemResult, w as ItemHistoryQuery, x as ItemHistoryResult, y as ItemOrderQuery, z as PlayerBalanceQuery, F as PlayerBalanceResult, G as InboundPendingQuery, H as InboundPendingResult, J as LinkedIdentitiesQuery, K as LinkedIdentitiesResult } from './types-DLSCxpoT.cjs';
+export { M as CurrencyBalance, N as InboundPendingItem, g as InvoErrorInfo, h as InvoHooks, i as InvoRequestInfo, j as InvoResponseInfo, Q as LinkedIdentityEmail, R as Rail, V as VerificationMethod } from './types-DLSCxpoT.cjs';
 
 interface VerifyWebhookOptions {
     /** Max age of the signed timestamp, in seconds. Default 300 (5 min). */
@@ -216,7 +216,16 @@ declare class InvoServer {
      * `transfer.claim_pending` webhook (the webhook is the wake-up; this is the list).
      */
     getInboundPending(query: InboundPendingQuery, opts?: CallOptions): Promise<InboundPendingResult>;
+    /**
+     * Look up a player's linked wallet identities (SERVER-only, game-secret). Game-scoped:
+     * returns wallet members that also have a Player row on this game. Provide a `playerEmail`
+     * or `playerPhone` (phone wins if both). No in-game match (backend 404) returns
+     * `notFound: true` with empty `emails` — not an error.
+     *
+     * ⚠️ Returns first-party PII (emails/phones) — never expose this to the browser.
+     */
+    getLinkedIdentities(query: LinkedIdentitiesQuery, opts?: CallOptions): Promise<LinkedIdentitiesResult>;
     private toInitiateResult;
 }
 
-export { CallOptions, ConfirmPaymentResult, CreateCheckoutInput, CreateCheckoutResult, InboundPendingQuery, InboundPendingResult, InitiateResult, InitiateSendInput, InitiateTransferInput, InvoError, InvoServer, type InvoWebhookEvent, ItemHistoryQuery, ItemHistoryResult, ItemOrderQuery, type ItemPurchasedData, OrderDetailsResult, PlayerBalanceQuery, PlayerBalanceResult, PlayerToken, type PurchaseCompletedData, type PurchaseEventData, PurchaseInput, PurchaseItemInput, PurchaseItemResult, PurchaseResult, ServerConfig, type TransferEventData, type VerifyWebhookOptions, type WebhookHandlerOptions, createWebhookHandler, verifyWebhook, verifyWebhookAsync };
+export { CallOptions, ConfirmPaymentResult, CreateCheckoutInput, CreateCheckoutResult, InboundPendingQuery, InboundPendingResult, InitiateResult, InitiateSendInput, InitiateTransferInput, InvoError, InvoServer, type InvoWebhookEvent, ItemHistoryQuery, ItemHistoryResult, ItemOrderQuery, type ItemPurchasedData, LinkedIdentitiesQuery, LinkedIdentitiesResult, OrderDetailsResult, PlayerBalanceQuery, PlayerBalanceResult, PlayerToken, type PurchaseCompletedData, type PurchaseEventData, PurchaseInput, PurchaseItemInput, PurchaseItemResult, PurchaseResult, ServerConfig, type TransferEventData, type VerifyWebhookOptions, type WebhookHandlerOptions, createWebhookHandler, verifyWebhook, verifyWebhookAsync };

package/dist/server.d.ts

@@ -1,5 +1,5 @@
-import { I as InvoError, S as ServerConfig, a as CallOptions, k as PlayerToken, l as InitiateSendInput, m as InitiateResult, n as InitiateTransferInput, o as CreateCheckoutInput, p as CreateCheckoutResult, q as PurchaseInput, r as PurchaseResult, s as ConfirmPaymentResult, O as OrderDetailsResult, t as PurchaseItemInput, u as PurchaseItemResult, v as ItemHistoryQuery, w as ItemHistoryResult, x as ItemOrderQuery, y as PlayerBalanceQuery, z as PlayerBalanceResult, B as InboundPendingQuery, F as InboundPendingResult } from './types-Bi_NMSkN.js';
-export { G as CurrencyBalance, H as InboundPendingItem, f as InvoErrorInfo, g as InvoHooks, h as InvoRequestInfo, i as InvoResponseInfo, R as Rail, V as VerificationMethod } from './types-Bi_NMSkN.js';
+import { I as InvoError, S as ServerConfig, a as CallOptions, l as PlayerToken, m as InitiateSendInput, n as InitiateResult, o as InitiateTransferInput, p as CreateCheckoutInput, q as CreateCheckoutResult, r as PurchaseInput, s as PurchaseResult, t as ConfirmPaymentResult, O as OrderDetailsResult, u as PurchaseItemInput, v as PurchaseItemResult, w as ItemHistoryQuery, x as ItemHistoryResult, y as ItemOrderQuery, z as PlayerBalanceQuery, F as PlayerBalanceResult, G as InboundPendingQuery, H as InboundPendingResult, J as LinkedIdentitiesQuery, K as LinkedIdentitiesResult } from './types-DLSCxpoT.js';
+export { M as CurrencyBalance, N as InboundPendingItem, g as InvoErrorInfo, h as InvoHooks, i as InvoRequestInfo, j as InvoResponseInfo, Q as LinkedIdentityEmail, R as Rail, V as VerificationMethod } from './types-DLSCxpoT.js';
 
 interface VerifyWebhookOptions {
     /** Max age of the signed timestamp, in seconds. Default 300 (5 min). */
@@ -216,7 +216,16 @@ declare class InvoServer {
      * `transfer.claim_pending` webhook (the webhook is the wake-up; this is the list).
      */
     getInboundPending(query: InboundPendingQuery, opts?: CallOptions): Promise<InboundPendingResult>;
+    /**
+     * Look up a player's linked wallet identities (SERVER-only, game-secret). Game-scoped:
+     * returns wallet members that also have a Player row on this game. Provide a `playerEmail`
+     * or `playerPhone` (phone wins if both). No in-game match (backend 404) returns
+     * `notFound: true` with empty `emails` — not an error.
+     *
+     * ⚠️ Returns first-party PII (emails/phones) — never expose this to the browser.
+     */
+    getLinkedIdentities(query: LinkedIdentitiesQuery, opts?: CallOptions): Promise<LinkedIdentitiesResult>;
     private toInitiateResult;
 }
 
-export { CallOptions, ConfirmPaymentResult, CreateCheckoutInput, CreateCheckoutResult, InboundPendingQuery, InboundPendingResult, InitiateResult, InitiateSendInput, InitiateTransferInput, InvoError, InvoServer, type InvoWebhookEvent, ItemHistoryQuery, ItemHistoryResult, ItemOrderQuery, type ItemPurchasedData, OrderDetailsResult, PlayerBalanceQuery, PlayerBalanceResult, PlayerToken, type PurchaseCompletedData, type PurchaseEventData, PurchaseInput, PurchaseItemInput, PurchaseItemResult, PurchaseResult, ServerConfig, type TransferEventData, type VerifyWebhookOptions, type WebhookHandlerOptions, createWebhookHandler, verifyWebhook, verifyWebhookAsync };
+export { CallOptions, ConfirmPaymentResult, CreateCheckoutInput, CreateCheckoutResult, InboundPendingQuery, InboundPendingResult, InitiateResult, InitiateSendInput, InitiateTransferInput, InvoError, InvoServer, type InvoWebhookEvent, ItemHistoryQuery, ItemHistoryResult, ItemOrderQuery, type ItemPurchasedData, LinkedIdentitiesQuery, LinkedIdentitiesResult, OrderDetailsResult, PlayerBalanceQuery, PlayerBalanceResult, PlayerToken, type PurchaseCompletedData, type PurchaseEventData, PurchaseInput, PurchaseItemInput, PurchaseItemResult, PurchaseResult, ServerConfig, type TransferEventData, type VerifyWebhookOptions, type WebhookHandlerOptions, createWebhookHandler, verifyWebhook, verifyWebhookAsync };

package/dist/server.js

@@ -161,7 +161,7 @@ async function hmacHexSubtle(secret, message) {
 }
 
 // src/server.ts
-var DEFAULT_UA = "invonetwork-web-sdk/0.4.0 (+https://invo.network)";
+var DEFAULT_UA = "invonetwork-web-sdk/1.0.0 (+https://invo.network)";
 var MAX_USD_AMOUNT = 999.99;
 var MAX_ITEM_PRICE = 999999.99;
 function invalidInput(label, value, why) {
@@ -201,6 +201,13 @@ function toOrderDetails(raw) {
     raw
   };
 }
+function toLinkedEmail(row) {
+  return {
+    email: String(row["email"] ?? ""),
+    primary: row["primary"] === true,
+    verifiedAt: row["verified_at"] ?? null
+  };
+}
 function toInboundPendingItem(row) {
   return {
     transactionId: String(row["transaction_id"] ?? ""),
@@ -620,6 +627,48 @@ var InvoServer = class {
     const rows = Array.isArray(raw["inbound_pending"]) ? raw["inbound_pending"] : [];
     return { inboundPending: rows.map(toInboundPendingItem), raw };
   }
+  /**
+   * Look up a player's linked wallet identities (SERVER-only, game-secret). Game-scoped:
+   * returns wallet members that also have a Player row on this game. Provide a `playerEmail`
+   * or `playerPhone` (phone wins if both). No in-game match (backend 404) returns
+   * `notFound: true` with empty `emails` — not an error.
+   *
+   * ⚠️ Returns first-party PII (emails/phones) — never expose this to the browser.
+   */
+  async getLinkedIdentities(query, opts) {
+    const phone = typeof query.playerPhone === "string" && query.playerPhone.trim() ? query.playerPhone.trim() : "";
+    const email = typeof query.playerEmail === "string" && query.playerEmail.trim() ? query.playerEmail.trim() : "";
+    if (!phone && !email) {
+      throw invalidInput("query", query, "requires a playerEmail or playerPhone");
+    }
+    const q = new URLSearchParams();
+    if (phone) q.set("player_phone", phone);
+    else q.set("player_email", email);
+    let raw;
+    try {
+      raw = await this.http.get(
+        `/api/wallet/identities?${q.toString()}`,
+        this.auth,
+        { signal: opts?.signal }
+      );
+    } catch (e) {
+      if (e instanceof InvoError && e.status === 404) {
+        const raw404 = e.body && typeof e.body === "object" ? e.body : {};
+        return { walletUserId: null, primaryEmail: "", primaryPhone: "", isMinor: false, emails: [], notFound: true, raw: raw404 };
+      }
+      throw e;
+    }
+    const emails = Array.isArray(raw["emails"]) ? raw["emails"].map(toLinkedEmail) : [];
+    return {
+      walletUserId: raw["wallet_user_id"] ?? null,
+      primaryEmail: String(raw["primary_email"] ?? ""),
+      primaryPhone: String(raw["primary_phone"] ?? ""),
+      isMinor: raw["is_minor"] === true,
+      emails,
+      notFound: false,
+      raw
+    };
+  }
   toInitiateResult(raw) {
     const vm = raw["verification_method"];
     const guardian = raw["guardian_approval"];

package/dist/{types-Bi_NMSkN.d.cts → types-DLSCxpoT.d.cts}

@@ -357,6 +357,50 @@ interface PendingCollectResult {
     pending: PendingCollectItem[];
     raw: Record<string, unknown>;
 }
+interface BalanceRow {
+    currencyId: string | number;
+    currencyName: string;
+    /** Short symbol (may be null). */
+    currencySymbol: string | null;
+    /** Icon URL (may be null). */
+    currencySymbolUrl: string | null;
+    /** Decimal strings (parseFloat as needed). */
+    availableBalance: string;
+    reservedBalance: string;
+    totalBalance: string;
+    raw: Record<string, unknown>;
+}
+interface BalanceResult {
+    gameId: string | number;
+    gameName: string;
+    /** Empty for a player who hasn't transacted on this game yet (a 200, not an error). */
+    balances: BalanceRow[];
+    /** Sum of total_balance across rows (decimal string). */
+    totalValue: string;
+    currencyCount: number;
+    hasFunds: boolean;
+    raw: Record<string, unknown>;
+}
+interface LinkedIdentitiesQuery {
+    /** Provide one; phone wins if both are given. */
+    playerEmail?: string;
+    playerPhone?: string;
+}
+interface LinkedIdentityEmail {
+    email: string;
+    primary: boolean;
+    verifiedAt: string | null;
+}
+interface LinkedIdentitiesResult {
+    walletUserId: string | null;
+    primaryEmail: string;
+    primaryPhone: string;
+    isMinor: boolean;
+    emails: LinkedIdentityEmail[];
+    /** true when there was no in-game match (backend 404) — treat as "no linked identities". */
+    notFound: boolean;
+    raw: Record<string, unknown>;
+}
 interface DestinationsQuery {
     /** "transfer" | "send". Defaults "transfer" (the set is identical for both today). */
     direction?: "transfer" | "send";
@@ -416,4 +460,4 @@ interface LinkDeviceResult {
     raw: Record<string, unknown>;
 }
 
-export { type ApproveResult as A, type InboundPendingQuery as B, type ClientConfig as C, type DestinationsQuery as D, type EnrollmentBeginResult as E, type InboundPendingResult as F, type CurrencyBalance as G, type InboundPendingItem as H, 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 DestinationsResult as c, type EnrollmentVerifyResult as d, type DestinationGame as e, type InvoErrorInfo as f, type InvoHooks as g, type InvoRequestInfo as h, type InvoResponseInfo as i, type PendingCollectItem as j, type PlayerToken as k, type InitiateSendInput as l, type InitiateResult as m, type InitiateTransferInput as n, type CreateCheckoutInput as o, type CreateCheckoutResult as p, type PurchaseInput as q, type PurchaseResult as r, type ConfirmPaymentResult as s, type PurchaseItemInput as t, type PurchaseItemResult as u, type ItemHistoryQuery as v, type ItemHistoryResult as w, type ItemOrderQuery as x, type PlayerBalanceQuery as y, type PlayerBalanceResult as z };
+export { type ApproveResult as A, type BalanceResult as B, type ClientConfig as C, type DestinationsQuery as D, type EnrollmentBeginResult as E, type PlayerBalanceResult as F, type InboundPendingQuery as G, type InboundPendingResult as H, InvoError as I, type LinkedIdentitiesQuery as J, type LinkedIdentitiesResult as K, type LinkDeviceResult as L, type CurrencyBalance as M, type InboundPendingItem as N, type OrderDetailsResult as O, type PendingCollectResult as P, type LinkedIdentityEmail as Q, type Rail as R, type ServerConfig as S, type VerificationMethod as V, type CallOptions as a, type ConfirmReceiptResult as b, type DestinationsResult as c, type EnrollmentVerifyResult as d, type BalanceRow as e, type DestinationGame as f, type InvoErrorInfo as g, type InvoHooks as h, type InvoRequestInfo as i, type InvoResponseInfo as j, type PendingCollectItem as k, type PlayerToken as l, type InitiateSendInput as m, type InitiateResult as n, type InitiateTransferInput as o, type CreateCheckoutInput as p, type CreateCheckoutResult as q, type PurchaseInput as r, type PurchaseResult as s, type ConfirmPaymentResult as t, type PurchaseItemInput as u, type PurchaseItemResult as v, type ItemHistoryQuery as w, type ItemHistoryResult as x, type ItemOrderQuery as y, type PlayerBalanceQuery as z };

package/dist/{types-Bi_NMSkN.d.ts → types-DLSCxpoT.d.ts}

@@ -357,6 +357,50 @@ interface PendingCollectResult {
     pending: PendingCollectItem[];
     raw: Record<string, unknown>;
 }
+interface BalanceRow {
+    currencyId: string | number;
+    currencyName: string;
+    /** Short symbol (may be null). */
+    currencySymbol: string | null;
+    /** Icon URL (may be null). */
+    currencySymbolUrl: string | null;
+    /** Decimal strings (parseFloat as needed). */
+    availableBalance: string;
+    reservedBalance: string;
+    totalBalance: string;
+    raw: Record<string, unknown>;
+}
+interface BalanceResult {
+    gameId: string | number;
+    gameName: string;
+    /** Empty for a player who hasn't transacted on this game yet (a 200, not an error). */
+    balances: BalanceRow[];
+    /** Sum of total_balance across rows (decimal string). */
+    totalValue: string;
+    currencyCount: number;
+    hasFunds: boolean;
+    raw: Record<string, unknown>;
+}
+interface LinkedIdentitiesQuery {
+    /** Provide one; phone wins if both are given. */
+    playerEmail?: string;
+    playerPhone?: string;
+}
+interface LinkedIdentityEmail {
+    email: string;
+    primary: boolean;
+    verifiedAt: string | null;
+}
+interface LinkedIdentitiesResult {
+    walletUserId: string | null;
+    primaryEmail: string;
+    primaryPhone: string;
+    isMinor: boolean;
+    emails: LinkedIdentityEmail[];
+    /** true when there was no in-game match (backend 404) — treat as "no linked identities". */
+    notFound: boolean;
+    raw: Record<string, unknown>;
+}
 interface DestinationsQuery {
     /** "transfer" | "send". Defaults "transfer" (the set is identical for both today). */
     direction?: "transfer" | "send";
@@ -416,4 +460,4 @@ interface LinkDeviceResult {
     raw: Record<string, unknown>;
 }
 
-export { type ApproveResult as A, type InboundPendingQuery as B, type ClientConfig as C, type DestinationsQuery as D, type EnrollmentBeginResult as E, type InboundPendingResult as F, type CurrencyBalance as G, type InboundPendingItem as H, 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 DestinationsResult as c, type EnrollmentVerifyResult as d, type DestinationGame as e, type InvoErrorInfo as f, type InvoHooks as g, type InvoRequestInfo as h, type InvoResponseInfo as i, type PendingCollectItem as j, type PlayerToken as k, type InitiateSendInput as l, type InitiateResult as m, type InitiateTransferInput as n, type CreateCheckoutInput as o, type CreateCheckoutResult as p, type PurchaseInput as q, type PurchaseResult as r, type ConfirmPaymentResult as s, type PurchaseItemInput as t, type PurchaseItemResult as u, type ItemHistoryQuery as v, type ItemHistoryResult as w, type ItemOrderQuery as x, type PlayerBalanceQuery as y, type PlayerBalanceResult as z };
+export { type ApproveResult as A, type BalanceResult as B, type ClientConfig as C, type DestinationsQuery as D, type EnrollmentBeginResult as E, type PlayerBalanceResult as F, type InboundPendingQuery as G, type InboundPendingResult as H, InvoError as I, type LinkedIdentitiesQuery as J, type LinkedIdentitiesResult as K, type LinkDeviceResult as L, type CurrencyBalance as M, type InboundPendingItem as N, type OrderDetailsResult as O, type PendingCollectResult as P, type LinkedIdentityEmail as Q, type Rail as R, type ServerConfig as S, type VerificationMethod as V, type CallOptions as a, type ConfirmReceiptResult as b, type DestinationsResult as c, type EnrollmentVerifyResult as d, type BalanceRow as e, type DestinationGame as f, type InvoErrorInfo as g, type InvoHooks as h, type InvoRequestInfo as i, type InvoResponseInfo as j, type PendingCollectItem as k, type PlayerToken as l, type InitiateSendInput as m, type InitiateResult as n, type InitiateTransferInput as o, type CreateCheckoutInput as p, type CreateCheckoutResult as q, type PurchaseInput as r, type PurchaseResult as s, type ConfirmPaymentResult as t, type PurchaseItemInput as u, type PurchaseItemResult as v, type ItemHistoryQuery as w, type ItemHistoryResult as x, type ItemOrderQuery as y, type PlayerBalanceQuery as z };

package/package.json

@@ -1,76 +1,76 @@
-{
-  "name": "@invonetwork/web-sdk",
-  "version": "0.7.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"
-  }
-}
+{
+  "name": "@invonetwork/web-sdk",
+  "version": "1.0.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"
+  }
+}