@invonetwork/web-sdk 2.1.2 → 2.3.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.
package/CHANGELOG.md CHANGED
@@ -4,6 +4,51 @@ All notable changes to `@invonetwork/web-sdk` are documented here. This project
4
4
  [Semantic Versioning](https://semver.org/). Releases are managed with
5
5
  [changesets](https://github.com/changesets/changesets).
6
6
 
7
+ ## [2.3.0] — 2026-07-07
8
+
9
+ **Claim-time phone-share approval.** The backend closed a security gap: claiming/collecting a
10
+ phone-routed transfer now authorizes the collecting identity against the receiver phone before
11
+ crediting. So `confirmReceiptSend`/`confirmReceiptTransfer` and `claimTransfer`/`claimCurrency`
12
+ can now return the phone-share `409 PHONE_SHARE_APPROVAL_REQUIRED` (previously only
13
+ registration/mint did). The existing `InvoError.isPhoneShareApprovalRequired` already classifies
14
+ it — no consumer code must change — but:
15
+
16
+ - New **`InvoError.phoneShareLast4`** surfaces the `phone_last4` from the 409 body for the UI
17
+ ("we texted the phone ending 1234").
18
+ - `isPhoneShareApprovalRequired` docs + the `confirmReceipt*`/claim method docs + README now
19
+ spell out the claim-time path: it's **not a failure** — the funds are held and the phone owner
20
+ is texted; show `err.message` verbatim, then **retry the same call** once approved (it succeeds
21
+ idempotently); on denial/expiry the sender is refunded.
22
+
23
+ Additive, no breaking changes; affects all rails' claim paths (transfer, currency send, amazon).
24
+
25
+ ## [2.2.0] — 2026-07-07
26
+
27
+ **Backend reconciliation** — a full audit of the SDK against the live backend surfaced three
28
+ places the SDK didn't match reality. All changes are backward-compatible (relaxing required
29
+ inputs / adding surface); no working call breaks.
30
+
31
+ - **`mintPlayerToken` no longer requires `playerPhone`.** `/api/sdk/player-token` is a
32
+ session-token mint for an **existing** player (looked up by email) — not a registration call.
33
+ It reads only `player_email` and ignores `player_phone`. The 2.0.0 hard E.164 requirement was
34
+ a bug: it could **block a valid token mint for an existing email-only player**. `playerPhone`
35
+ is now optional and validated only if provided. Phone stays enforced where it matters — the
36
+ sender's phone on `initiateSend`/`initiateTransfer`, and at player creation.
37
+ - **Send by phone alone.** `receiverPlayerEmail` (send) and `targetPlayerEmail` (transfer) are
38
+ now **optional** — you can send to a recipient's phone; they supply their email at claim
39
+ (claim still requires it, since that's where the recipient establishes identity).
40
+ - **`getPlayerBalance` is by email only.** There is no by-`playerId` balance route on the
41
+ backend, so passing `playerId` threw a confusing 404. It now throws a clear `INVALID_INPUT`
42
+ pointing you to `InvoClient.getBalance()` (client-side) or `playerEmail` (server-side).
43
+ - **New `InvoError.isUserVerificationRequired`** for the `WEBAUTHN_UV_REQUIRED` (401) approve
44
+ failure — re-run the passkey ceremony requiring UV.
45
+ - Fixed `iterateItemPurchaseHistory` to read the backend's `total_count` pagination key (was
46
+ `total`; the loop already terminated via the short-page guard, so behavior is unchanged).
47
+
48
+ **Migration:** none required. If you were passing `playerPhone` to `mintPlayerToken` it still
49
+ works; you can now also omit it. Replace any `getPlayerBalance({ playerId })` with an email
50
+ lookup or `InvoClient.getBalance()`.
51
+
7
52
  ## [2.1.2] — 2026-07-07
8
53
 
9
54
  **Hosted-checkout reconciliation** (the create-session API contract is unchanged; the hosted
package/README.md CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  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.
4
4
 
5
- > **Status:** `v2.1.1` — stable, published on npm. The backend it wraps is **live** on sandbox + production. The API is covered by a [stability commitment](#stability): no breaking changes without a major bump. **Since 2.0.0 (breaking):** `mintPlayerToken` requires `playerPhone` (E.164) — see the [CHANGELOG](CHANGELOG.md) migration note. **2.1.0 adds** self-serve passkey recovery (`recoveryBegin`/`recoveryComplete`); **2.1.1** is a security/correctness hardening patch; **2.1.2** surfaces `expiresInSeconds` on `createCheckout`.
5
+ > **Status:** `v2.3.0` — stable, published on npm. The backend it wraps is **live** on sandbox + production. The API is covered by a [stability commitment](#stability): no breaking changes without a major bump. Recent highlights: **2.2.0** reconciled with the backend (`mintPlayerToken` is a session mint — `playerPhone` optional; send-by-phone-alone; email-only `getPlayerBalance`); **2.3.0** surfaces the claim-time phone-share `409` on `confirmReceipt*`/`claim*` (+ `err.phoneShareLast4`). Full history in the [CHANGELOG](CHANGELOG.md).
6
6
  > Canonical partner reference: **https://docs.invo.network/docs/currency-purchase** and **https://docs.invo.network/docs/game-developer-integration**.
7
7
 
8
8
  ## What it does
@@ -82,26 +82,30 @@ Build and test against the **dev console + sandbox** first, then switch to the *
82
82
 
83
83
  `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.
84
84
 
85
- ### Player registration (email + phone, required)
85
+ ### Player token (session mint for an existing player)
86
86
 
87
- `mintPlayerToken` is the player **registration** call, and it requires **both** `playerEmail` and `playerPhone`:
87
+ `mintPlayerToken` mints a short-lived, game-scoped **session token** for a player who
88
+ **already exists** on your game. It is *not* a registration call — the backend looks the
89
+ player up by `playerEmail` and returns a token for their existing identity (or `404` if no
90
+ such player exists). It only needs `playerEmail`:
88
91
 
89
92
  ```ts
90
93
  // your backend
91
- const { token } = await invo.mintPlayerToken({
92
- playerEmail: "player@example.com",
93
- playerPhone: "+15555550100", // REQUIRED — E.164: leading "+", country code, digits only
94
- });
94
+ const { token } = await invo.mintPlayerToken({ playerEmail: "player@example.com" });
95
95
  ```
96
96
 
97
- Why phone is not optional on the INVO network:
97
+ `playerPhone` is **optional** here (validated as E.164 only if you pass it, and ignored by this
98
+ endpoint) — an existing email-only player still mints a token.
98
99
 
99
- - **Identity is derived from email + phone together.** Registering email-only and adding the phone later **changes the identity and forces device re-enrollment** — collect the phone in your enrollment UI *before* the first mint.
100
- - **Incoming cross-game transfers are matched by phone.** An account without a phone can never see money sent to it.
101
- - **The account-linking consent SMS is triggered by phone.** Without one, the "add this email to your account?" flow can't run.
102
- - **Format is E.164** (`+15555550100`) — the SDK rejects anything else before it reaches the wire. Don't send national/local formats.
100
+ **Where phone actually matters.** A player's INVO identity encodes their phone, and cross-game
101
+ money routing keys off it — but that's enforced on the money calls, not the token mint:
103
102
 
104
- **Same person, new email, same phone is expected and supported.** When the phone already belongs to another INVO account, the mint throws an `InvoError` with `isPhoneShareApprovalRequired` (409) — this is **not a failure**: INVO sent the phone holder a consent SMS. Show the player a "pending approval" state, then re-issue the same mint once approved. Poll `phoneShareStatus({ phone, email })`, or use `phoneShareInitiate`/`phoneShareApprove` (the error's `phoneShareApprovalId` carries the id) for the in-app OTP fallback.
103
+ - **`initiateSend` / `initiateTransfer`** require the **sender's** phone (E.164), and take the
104
+ **recipient's** phone. You can send by the recipient's **phone alone** — they supply their
105
+ email when they claim.
106
+ - An account with no phone can't receive cross-game money and can't take part in the
107
+ account-linking consent SMS, so make sure players have a phone at **creation / enrollment**
108
+ (in your own player system), before they transact.
105
109
 
106
110
  ### Token bootstrap (both modes)
107
111
 
@@ -150,7 +154,7 @@ The WebAuthn ceremony still runs in the browser (it must — it's `navigator.cre
150
154
  INVO enables each flow for your tenant in the [console](#get-your-account--game-secret-invo-console). What you need to do:
151
155
 
152
156
  - **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.
153
- - **Collect a phone number (E.164) in your enrollment flow** — `mintPlayerToken` requires it alongside the email (see [Player registration](#player-registration-email--phone-required)).
157
+ - **Make sure players have a phone (E.164) at creation/enrollment** — it's required on the money calls (`initiateSend`/`initiateTransfer`) and for cross-game receive, though not on the token mint itself (see [Player token](#player-token-session-mint-for-an-existing-player)).
154
158
  - **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.)
155
159
  - **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.)
156
160
  - **For currency purchase:** card checkout works out of the box; ask INVO to enable the `game`/`steam` rails if you need them.
@@ -301,14 +305,17 @@ const item = await server.purchaseItem({
301
305
 
302
306
  ## Player balance
303
307
 
304
- Read a player's currency balances (server-side, game-secret) by email or player id:
308
+ Read a player's currency balances (server-side, game-secret) **by email**:
305
309
 
306
310
  ```ts
307
311
  const { balances, summary } = await server.getPlayerBalance({ playerEmail: "p@example.com" });
308
312
  // balances: [{ currencyName, availableBalance, reservedBalance, totalBalance, currencySymbol, raw }]
309
- // or: server.getPlayerBalance({ playerId: 12345 })
310
313
  ```
311
314
 
315
+ Lookup is by email only — there is no by-`playerId` balance route (a `playerId` is a per-game
316
+ internal id). For a **client-side** read, use `InvoClient.getBalance()` (player-token; identity
317
+ comes from the token, no PII).
318
+
312
319
  ---
313
320
 
314
321
  ## Sends & transfers (move currency between players)
@@ -363,6 +370,10 @@ try {
363
370
  } catch (e) {
364
371
  if (e instanceof InvoError && e.isReceiverNotEnrolled) {
365
372
  // recipient has no passkey here → show claim-code entry using approved.claimCode
373
+ } else if (e instanceof InvoError && e.isPhoneShareApprovalRequired) {
374
+ // receiver phone is contested → funds held, phone owner texted to approve.
375
+ showPending(e.message, e.phoneShareLast4); // show e.message verbatim; last4 names the phone
376
+ // …then RETRY the same confirmReceipt*/claim call once approved (succeeds idempotently).
366
377
  } else throw e;
367
378
  }
368
379
  ```
@@ -370,6 +381,7 @@ try {
370
381
  - **`verificationMethod`** (from initiate): `"in_app"` → passkey approve; `"sms"` → un-enrolled, PIN sent; `undefined` + `guardianApproval` → minor/guardian (HTTP 202), do **not** show the PIN UI. On the guardian path the SDK reports `verificationMethod: undefined` (even though the raw 202 body also carries `"sms"`) so `guardianApproval` wins — but branch on it first to be safe.
371
382
  - **Claim codes** are returned only by `approveTransfer`; they're the out-of-band fallback when the recipient isn't enrolled.
372
383
  - **`err.isReceiverNotEnrolled`** on `confirmReceipt*` is the explicit signal to switch to claim-code entry.
384
+ - **`err.isPhoneShareApprovalRequired` on `confirmReceipt*` / `claimTransfer` / `claimCurrency`** (409): the receiver phone is contested, so INVO **holds the money** and texts the phone owner to approve. Not a failure — show `err.message` verbatim (`err.phoneShareLast4` names the phone), then **retry the same call** once approved (it succeeds idempotently); on denial/expiry the sender is refunded. Same handling as the initiate-time phone-share 409.
373
385
  - Transfer self-claim may be disabled for your tenant; if it is, surface the claim-code path instead.
374
386
  - **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`).
375
387
 
@@ -560,7 +572,7 @@ Helpers:
560
572
  | `.retryAfter` | seconds to back off on a 429 throttle |
561
573
  | `.isEnrollmentAuthorizationRequired` | first-enrollment needs the OTP grant → `enrollmentBegin`/`enrollmentVerify` |
562
574
  | `.isEnrollmentProofRequired` | another method exists → prove it via `linkDevice` |
563
- | `.isPhoneShareApprovalRequired` | a new-account phone needs owner approval → run the `phoneShare*` handshake, then retry |
575
+ | `.isPhoneShareApprovalRequired` | phone needs owner approval — at register/mint **or** at claim/`confirmReceipt*` (contested receiver phone) → show `.message` (+ `.phoneShareLast4`), retry the same call after approval |
564
576
  | `.isPhoneShareAlreadyApproved` | phone-share was already approved (e.g. from a `/reject`) |
565
577
 
566
578
  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`, `ENROLLMENT_CODE_INVALID`, `PASSKEY_RECOVERY_COOLDOWN` (403, `retryAfterAt`), `no_channel_on_file`, `rate_limited`, `WRONG_RAIL_ENDPOINT`, `flow_paused`.
@@ -584,7 +596,7 @@ try {
584
596
 
585
597
  | Method | Returns |
586
598
  |---|---|
587
- | `mintPlayerToken({ playerEmail, playerPhone })` | `{ token, expiresAt, identityId }` — **both required**; `playerPhone` must be E.164 (see [Player registration](#player-registration-email--phone-required)) |
599
+ | `mintPlayerToken({ playerEmail, playerPhone? })` | `{ token, expiresAt, identityId }` — session mint for an **existing** player (404 if unknown); `playerPhone` optional/validated-if-present (see [Player token](#player-token-session-mint-for-an-existing-player)) |
588
600
  | `initiateSend(input)` | `{ transactionId, verificationMethod, guardianApproval?, raw }` |
589
601
  | `initiateTransfer(input)` | `{ transactionId, verificationMethod, guardianApproval?, raw }` |
590
602
  | `createCheckout(input)` | `{ sessionId, checkoutUrl, expiresAt, expiresInSeconds, raw }` |
@@ -594,7 +606,7 @@ try {
594
606
  | `purchaseItem(input)` | `{ status, transactionId, orderId, newBalance, previousBalance, currencyName, financialBreakdown?, raw }` |
595
607
  | `getItemPurchaseHistory({ playerEmail, limit?, offset? })` | `{ history, pagination, raw }` |
596
608
  | `getItemOrderDetails({ orderId? \| transactionId? \| clientRequestId? })` | `{ order, financialSummary, statusTimeline, raw }` |
597
- | `getPlayerBalance({ playerEmail? \| playerId? })` | `{ player, balances, summary, raw }` |
609
+ | `getPlayerBalance({ playerEmail })` | `{ player, balances, summary, raw }` — **by email only** (no by-id route; use `InvoClient.getBalance()` client-side) |
598
610
  | `getInboundPending({ playerEmail? \| playerPhone? })` | `{ inboundPending, raw }` — live unclaimed inbound sends/transfers |
599
611
  | `getLinkedIdentities({ playerEmail? \| playerPhone? })` | `{ walletUserId, primaryEmail, primaryPhone, isMinor, emails, notFound, raw }` — **server-only** (returns PII) |
600
612
  | `verifySmsTransfer(txnId, smsPin)` / `verifySmsSend(txnId, smsPin)` | `SmsVerifyResult` — complete the SMS-PIN path when `verificationMethod: "sms"` |
@@ -21,6 +21,14 @@ var InvoError = class _InvoError extends Error {
21
21
  get isEnrollmentAuthorizationRequired() {
22
22
  return this.code === "ENROLLMENT_REQUIRES_AUTHORIZATION";
23
23
  }
24
+ /**
25
+ * True if a passkey approve/confirm was rejected because the assertion lacked user
26
+ * verification (`WEBAUTHN_UV_REQUIRED`, 401). Re-run the ceremony requiring UV
27
+ * (biometric/PIN) — the backend treats a UV-satisfied assertion as the signed step-up.
28
+ */
29
+ get isUserVerificationRequired() {
30
+ return this.code === "WEBAUTHN_UV_REQUIRED";
31
+ }
24
32
  /**
25
33
  * True if enrolling is blocked because the identity already has an enrolled method
26
34
  * (anti-takeover gate, register/complete → 409). Two ways forward: `linkDevice` when
@@ -62,12 +70,19 @@ var InvoError = class _InvoError extends Error {
62
70
  return this.code === "INSUFFICIENT_BALANCE" || "required_amount" in b || /insufficient[_ ]balance/i.test(this.message);
63
71
  }
64
72
  /**
65
- * True if the call needs phone-share approval before it can complete (409). Raised by
66
- * registration/token-mint and by claims when the phone already belongs to another INVO
67
- * account (same person, new email — expected, not a failure). The phone holder gets a
68
- * consent SMS; show "pending approval", then re-issue the identical call once approved
69
- * (poll `phoneShareStatus`, or use `phoneShareInitiate`/`phoneShareApprove` for the OTP
70
- * fallback). `phoneShareApprovalId` carries the id from the 409 body.
73
+ * True if the call needs phone-share approval before it can complete (409) — the
74
+ * collecting/registering identity isn't yet authorized for the phone on file. Raised by:
75
+ * - registration/token-mint (phone already on another INVO account), and
76
+ * - **claim + confirm-receipt** (`claimTransfer`/`claimCurrency`,
77
+ * `confirmReceiptSend`/`confirmReceiptTransfer`) — the receiver phone is contested,
78
+ * so INVO holds the money and texts the phone owner to approve.
79
+ *
80
+ * NOT a failure. Show `err.message` verbatim (the backend supplies the user-facing text;
81
+ * `phoneShareLast4` tells the UI which phone), keep the funds pending, and **retry the same
82
+ * call** once the phone owner approves — an approved consent makes the retry succeed
83
+ * idempotently. On denial/expiry the backend refunds the sender. (`phoneShareApprovalId`
84
+ * carries the id when the 409 came from the OTP-handshake path;
85
+ * `phoneShareInitiate`/`phoneShareApprove`/`phoneShareStatus` drive that fallback.)
71
86
  */
72
87
  get isPhoneShareApprovalRequired() {
73
88
  return this.code === "PHONE_SHARE_APPROVAL_REQUIRED";
@@ -77,6 +92,11 @@ var InvoError = class _InvoError extends Error {
77
92
  const v = this.bodyObject()["approval_id"];
78
93
  return typeof v === "string" && v ? v : void 0;
79
94
  }
95
+ /** Last 4 digits of the phone that must approve (`phone_last4`), for the UI message. */
96
+ get phoneShareLast4() {
97
+ const v = this.bodyObject()["phone_last4"];
98
+ return typeof v === "string" && v ? v : void 0;
99
+ }
80
100
  /** True if the phone-share (phone, requesting_email) pair was already approved. */
81
101
  get isPhoneShareAlreadyApproved() {
82
102
  return this.code === "PHONE_SHARE_ALREADY_APPROVED";
@@ -361,5 +381,5 @@ function toDestinationsResult(raw, direction) {
361
381
  }
362
382
 
363
383
  export { Http, InvoError, assertSecureBaseUrl, toDestinationsResult };
364
- //# sourceMappingURL=chunk-4GNJIQY2.js.map
365
- //# sourceMappingURL=chunk-4GNJIQY2.js.map
384
+ //# sourceMappingURL=chunk-SNFO5THM.js.map
385
+ //# sourceMappingURL=chunk-SNFO5THM.js.map
package/dist/index.cjs CHANGED
@@ -23,6 +23,14 @@ var InvoError = class _InvoError extends Error {
23
23
  get isEnrollmentAuthorizationRequired() {
24
24
  return this.code === "ENROLLMENT_REQUIRES_AUTHORIZATION";
25
25
  }
26
+ /**
27
+ * True if a passkey approve/confirm was rejected because the assertion lacked user
28
+ * verification (`WEBAUTHN_UV_REQUIRED`, 401). Re-run the ceremony requiring UV
29
+ * (biometric/PIN) — the backend treats a UV-satisfied assertion as the signed step-up.
30
+ */
31
+ get isUserVerificationRequired() {
32
+ return this.code === "WEBAUTHN_UV_REQUIRED";
33
+ }
26
34
  /**
27
35
  * True if enrolling is blocked because the identity already has an enrolled method
28
36
  * (anti-takeover gate, register/complete → 409). Two ways forward: `linkDevice` when
@@ -64,12 +72,19 @@ var InvoError = class _InvoError extends Error {
64
72
  return this.code === "INSUFFICIENT_BALANCE" || "required_amount" in b || /insufficient[_ ]balance/i.test(this.message);
65
73
  }
66
74
  /**
67
- * True if the call needs phone-share approval before it can complete (409). Raised by
68
- * registration/token-mint and by claims when the phone already belongs to another INVO
69
- * account (same person, new email — expected, not a failure). The phone holder gets a
70
- * consent SMS; show "pending approval", then re-issue the identical call once approved
71
- * (poll `phoneShareStatus`, or use `phoneShareInitiate`/`phoneShareApprove` for the OTP
72
- * fallback). `phoneShareApprovalId` carries the id from the 409 body.
75
+ * True if the call needs phone-share approval before it can complete (409) — the
76
+ * collecting/registering identity isn't yet authorized for the phone on file. Raised by:
77
+ * - registration/token-mint (phone already on another INVO account), and
78
+ * - **claim + confirm-receipt** (`claimTransfer`/`claimCurrency`,
79
+ * `confirmReceiptSend`/`confirmReceiptTransfer`) — the receiver phone is contested,
80
+ * so INVO holds the money and texts the phone owner to approve.
81
+ *
82
+ * NOT a failure. Show `err.message` verbatim (the backend supplies the user-facing text;
83
+ * `phoneShareLast4` tells the UI which phone), keep the funds pending, and **retry the same
84
+ * call** once the phone owner approves — an approved consent makes the retry succeed
85
+ * idempotently. On denial/expiry the backend refunds the sender. (`phoneShareApprovalId`
86
+ * carries the id when the 409 came from the OTP-handshake path;
87
+ * `phoneShareInitiate`/`phoneShareApprove`/`phoneShareStatus` drive that fallback.)
73
88
  */
74
89
  get isPhoneShareApprovalRequired() {
75
90
  return this.code === "PHONE_SHARE_APPROVAL_REQUIRED";
@@ -79,6 +94,11 @@ var InvoError = class _InvoError extends Error {
79
94
  const v = this.bodyObject()["approval_id"];
80
95
  return typeof v === "string" && v ? v : void 0;
81
96
  }
97
+ /** Last 4 digits of the phone that must approve (`phone_last4`), for the UI message. */
98
+ get phoneShareLast4() {
99
+ const v = this.bodyObject()["phone_last4"];
100
+ return typeof v === "string" && v ? v : void 0;
101
+ }
82
102
  /** True if the phone-share (phone, requesting_email) pair was already approved. */
83
103
  get isPhoneShareAlreadyApproved() {
84
104
  return this.code === "PHONE_SHARE_ALREADY_APPROVED";
@@ -539,11 +559,21 @@ var InvoClient = class {
539
559
  async approveTransfer(transactionId, opts) {
540
560
  return this.approve("transfers", transactionId, opts);
541
561
  }
542
- /** Recipient self-claims a SEND with their passkey. */
562
+ /**
563
+ * Recipient self-claims a SEND with their passkey.
564
+ *
565
+ * May throw a 409 with `err.isPhoneShareApprovalRequired` when the receiver phone is
566
+ * contested (the collecting identity isn't yet authorized for it). NOT a failure — the
567
+ * money is held and the phone owner is texted to approve. Show `err.message`
568
+ * (`err.phoneShareLast4` names the phone), then **retry this same call** once approved
569
+ * (it then succeeds idempotently); on denial/expiry the backend refunds the sender.
570
+ */
543
571
  async confirmReceiptSend(transactionId, opts) {
544
572
  return this.confirmReceipt("send", transactionId, opts);
545
573
  }
546
- /** Recipient self-claims a TRANSFER with their passkey. */
574
+ /** Recipient self-claims a TRANSFER with their passkey. Can throw the same phone-share
575
+ * 409 as {@link confirmReceiptSend} (`err.isPhoneShareApprovalRequired`) — handle it the
576
+ * same way: show `err.message`, retry after the phone owner approves. */
547
577
  async confirmReceiptTransfer(transactionId, opts) {
548
578
  return this.confirmReceipt("transfers", transactionId, opts);
549
579
  }
package/dist/index.d.cts CHANGED
@@ -1,5 +1,5 @@
1
- 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, R as RecoveryBeginResult, e as RecoveryCompleteResult } from './types-CU2BqbHN.cjs';
2
- export { f as BalanceRow, g as DestinationGame, I as InvoError, h as InvoErrorInfo, i as InvoHooks, j as InvoRequestInfo, k as InvoResponseInfo, l as PendingCollectItem, m as Rail, V as VerificationMethod } from './types-CU2BqbHN.cjs';
1
+ 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, R as RecoveryBeginResult, e as RecoveryCompleteResult } from './types-Cpo5Fvf9.cjs';
2
+ export { f as BalanceRow, g as DestinationGame, I as InvoError, h as InvoErrorInfo, i as InvoHooks, j as InvoRequestInfo, k as InvoResponseInfo, l as PendingCollectItem, m as Rail, V as VerificationMethod } from './types-Cpo5Fvf9.cjs';
3
3
 
4
4
  declare class InvoClient {
5
5
  private readonly http;
@@ -24,9 +24,19 @@ declare class InvoClient {
24
24
  approveSend(transactionId: string, opts?: CallOptions): Promise<ApproveResult>;
25
25
  /** Approve a TRANSFER with the player's passkey (returns the sender's claim code). */
26
26
  approveTransfer(transactionId: string, opts?: CallOptions): Promise<ApproveResult>;
27
- /** Recipient self-claims a SEND with their passkey. */
27
+ /**
28
+ * Recipient self-claims a SEND with their passkey.
29
+ *
30
+ * May throw a 409 with `err.isPhoneShareApprovalRequired` when the receiver phone is
31
+ * contested (the collecting identity isn't yet authorized for it). NOT a failure — the
32
+ * money is held and the phone owner is texted to approve. Show `err.message`
33
+ * (`err.phoneShareLast4` names the phone), then **retry this same call** once approved
34
+ * (it then succeeds idempotently); on denial/expiry the backend refunds the sender.
35
+ */
28
36
  confirmReceiptSend(transactionId: string, opts?: CallOptions): Promise<ConfirmReceiptResult>;
29
- /** Recipient self-claims a TRANSFER with their passkey. */
37
+ /** Recipient self-claims a TRANSFER with their passkey. Can throw the same phone-share
38
+ * 409 as {@link confirmReceiptSend} (`err.isPhoneShareApprovalRequired`) — handle it the
39
+ * same way: show `err.message`, retry after the phone owner approves. */
30
40
  confirmReceiptTransfer(transactionId: string, opts?: CallOptions): Promise<ConfirmReceiptResult>;
31
41
  /**
32
42
  * Interchangeable methods (§4.6): prove an *already-enrolled* method (e.g. the
package/dist/index.d.ts CHANGED
@@ -1,5 +1,5 @@
1
- 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, R as RecoveryBeginResult, e as RecoveryCompleteResult } from './types-CU2BqbHN.js';
2
- export { f as BalanceRow, g as DestinationGame, I as InvoError, h as InvoErrorInfo, i as InvoHooks, j as InvoRequestInfo, k as InvoResponseInfo, l as PendingCollectItem, m as Rail, V as VerificationMethod } from './types-CU2BqbHN.js';
1
+ 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, R as RecoveryBeginResult, e as RecoveryCompleteResult } from './types-Cpo5Fvf9.js';
2
+ export { f as BalanceRow, g as DestinationGame, I as InvoError, h as InvoErrorInfo, i as InvoHooks, j as InvoRequestInfo, k as InvoResponseInfo, l as PendingCollectItem, m as Rail, V as VerificationMethod } from './types-Cpo5Fvf9.js';
3
3
 
4
4
  declare class InvoClient {
5
5
  private readonly http;
@@ -24,9 +24,19 @@ declare class InvoClient {
24
24
  approveSend(transactionId: string, opts?: CallOptions): Promise<ApproveResult>;
25
25
  /** Approve a TRANSFER with the player's passkey (returns the sender's claim code). */
26
26
  approveTransfer(transactionId: string, opts?: CallOptions): Promise<ApproveResult>;
27
- /** Recipient self-claims a SEND with their passkey. */
27
+ /**
28
+ * Recipient self-claims a SEND with their passkey.
29
+ *
30
+ * May throw a 409 with `err.isPhoneShareApprovalRequired` when the receiver phone is
31
+ * contested (the collecting identity isn't yet authorized for it). NOT a failure — the
32
+ * money is held and the phone owner is texted to approve. Show `err.message`
33
+ * (`err.phoneShareLast4` names the phone), then **retry this same call** once approved
34
+ * (it then succeeds idempotently); on denial/expiry the backend refunds the sender.
35
+ */
28
36
  confirmReceiptSend(transactionId: string, opts?: CallOptions): Promise<ConfirmReceiptResult>;
29
- /** Recipient self-claims a TRANSFER with their passkey. */
37
+ /** Recipient self-claims a TRANSFER with their passkey. Can throw the same phone-share
38
+ * 409 as {@link confirmReceiptSend} (`err.isPhoneShareApprovalRequired`) — handle it the
39
+ * same way: show `err.message`, retry after the phone owner approves. */
30
40
  confirmReceiptTransfer(transactionId: string, opts?: CallOptions): Promise<ConfirmReceiptResult>;
31
41
  /**
32
42
  * Interchangeable methods (§4.6): prove an *already-enrolled* method (e.g. the
package/dist/index.js CHANGED
@@ -1,5 +1,5 @@
1
- import { assertSecureBaseUrl, Http, toDestinationsResult, InvoError } from './chunk-4GNJIQY2.js';
2
- export { InvoError } from './chunk-4GNJIQY2.js';
1
+ import { assertSecureBaseUrl, Http, toDestinationsResult, InvoError } from './chunk-SNFO5THM.js';
2
+ export { InvoError } from './chunk-SNFO5THM.js';
3
3
 
4
4
  // src/shared/webauthn.ts
5
5
  function malformedOptions(field) {
@@ -178,11 +178,21 @@ var InvoClient = class {
178
178
  async approveTransfer(transactionId, opts) {
179
179
  return this.approve("transfers", transactionId, opts);
180
180
  }
181
- /** Recipient self-claims a SEND with their passkey. */
181
+ /**
182
+ * Recipient self-claims a SEND with their passkey.
183
+ *
184
+ * May throw a 409 with `err.isPhoneShareApprovalRequired` when the receiver phone is
185
+ * contested (the collecting identity isn't yet authorized for it). NOT a failure — the
186
+ * money is held and the phone owner is texted to approve. Show `err.message`
187
+ * (`err.phoneShareLast4` names the phone), then **retry this same call** once approved
188
+ * (it then succeeds idempotently); on denial/expiry the backend refunds the sender.
189
+ */
182
190
  async confirmReceiptSend(transactionId, opts) {
183
191
  return this.confirmReceipt("send", transactionId, opts);
184
192
  }
185
- /** Recipient self-claims a TRANSFER with their passkey. */
193
+ /** Recipient self-claims a TRANSFER with their passkey. Can throw the same phone-share
194
+ * 409 as {@link confirmReceiptSend} (`err.isPhoneShareApprovalRequired`) — handle it the
195
+ * same way: show `err.message`, retry after the phone owner approves. */
186
196
  async confirmReceiptTransfer(transactionId, opts) {
187
197
  return this.confirmReceipt("transfers", transactionId, opts);
188
198
  }
package/dist/server.cjs CHANGED
@@ -25,6 +25,14 @@ var InvoError = class _InvoError extends Error {
25
25
  get isEnrollmentAuthorizationRequired() {
26
26
  return this.code === "ENROLLMENT_REQUIRES_AUTHORIZATION";
27
27
  }
28
+ /**
29
+ * True if a passkey approve/confirm was rejected because the assertion lacked user
30
+ * verification (`WEBAUTHN_UV_REQUIRED`, 401). Re-run the ceremony requiring UV
31
+ * (biometric/PIN) — the backend treats a UV-satisfied assertion as the signed step-up.
32
+ */
33
+ get isUserVerificationRequired() {
34
+ return this.code === "WEBAUTHN_UV_REQUIRED";
35
+ }
28
36
  /**
29
37
  * True if enrolling is blocked because the identity already has an enrolled method
30
38
  * (anti-takeover gate, register/complete → 409). Two ways forward: `linkDevice` when
@@ -66,12 +74,19 @@ var InvoError = class _InvoError extends Error {
66
74
  return this.code === "INSUFFICIENT_BALANCE" || "required_amount" in b || /insufficient[_ ]balance/i.test(this.message);
67
75
  }
68
76
  /**
69
- * True if the call needs phone-share approval before it can complete (409). Raised by
70
- * registration/token-mint and by claims when the phone already belongs to another INVO
71
- * account (same person, new email — expected, not a failure). The phone holder gets a
72
- * consent SMS; show "pending approval", then re-issue the identical call once approved
73
- * (poll `phoneShareStatus`, or use `phoneShareInitiate`/`phoneShareApprove` for the OTP
74
- * fallback). `phoneShareApprovalId` carries the id from the 409 body.
77
+ * True if the call needs phone-share approval before it can complete (409) — the
78
+ * collecting/registering identity isn't yet authorized for the phone on file. Raised by:
79
+ * - registration/token-mint (phone already on another INVO account), and
80
+ * - **claim + confirm-receipt** (`claimTransfer`/`claimCurrency`,
81
+ * `confirmReceiptSend`/`confirmReceiptTransfer`) — the receiver phone is contested,
82
+ * so INVO holds the money and texts the phone owner to approve.
83
+ *
84
+ * NOT a failure. Show `err.message` verbatim (the backend supplies the user-facing text;
85
+ * `phoneShareLast4` tells the UI which phone), keep the funds pending, and **retry the same
86
+ * call** once the phone owner approves — an approved consent makes the retry succeed
87
+ * idempotently. On denial/expiry the backend refunds the sender. (`phoneShareApprovalId`
88
+ * carries the id when the 409 came from the OTP-handshake path;
89
+ * `phoneShareInitiate`/`phoneShareApprove`/`phoneShareStatus` drive that fallback.)
75
90
  */
76
91
  get isPhoneShareApprovalRequired() {
77
92
  return this.code === "PHONE_SHARE_APPROVAL_REQUIRED";
@@ -81,6 +96,11 @@ var InvoError = class _InvoError extends Error {
81
96
  const v = this.bodyObject()["approval_id"];
82
97
  return typeof v === "string" && v ? v : void 0;
83
98
  }
99
+ /** Last 4 digits of the phone that must approve (`phone_last4`), for the UI message. */
100
+ get phoneShareLast4() {
101
+ const v = this.bodyObject()["phone_last4"];
102
+ return typeof v === "string" && v ? v : void 0;
103
+ }
84
104
  /** True if the phone-share (phone, requesting_email) pair was already approved. */
85
105
  get isPhoneShareAlreadyApproved() {
86
106
  return this.code === "PHONE_SHARE_ALREADY_APPROVED";
@@ -528,7 +548,7 @@ async function hmacHexSubtle(secret, message) {
528
548
  }
529
549
 
530
550
  // src/server.ts
531
- var DEFAULT_UA = "invonetwork-web-sdk/2.1.2 (+https://invo.network)";
551
+ var DEFAULT_UA = "invonetwork-web-sdk/2.3.0 (+https://invo.network)";
532
552
  var MAX_USD_AMOUNT = 999.99;
533
553
  var MAX_ITEM_PRICE = 999999.99;
534
554
  function invalidInput(label, value, why) {
@@ -709,28 +729,29 @@ var InvoServer = class {
709
729
  /**
710
730
  * Mint a short-lived, game-scoped player token to hand to the browser InvoClient.
711
731
  *
712
- * This is the player REGISTRATION call: the network identity is derived from
713
- * `email + phone` TOGETHER, so both are required. Registering email-only and
714
- * attaching the phone later changes the identity and forces device re-enrollment —
715
- * collect the phone before the first mint. `playerPhone` must be E.164
716
- * (e.g. "+15555550100"); incoming cross-game transfers and the account-linking
717
- * consent SMS are both matched by phone, so an account without one can't receive
718
- * either.
732
+ * This is a SESSION-TOKEN mint for a player who ALREADY EXISTS on the game — not a
733
+ * registration call. The backend looks the player up by `playerEmail` and returns a
734
+ * token for their existing identity; if no such player exists it responds 404. The
735
+ * network identity (which encodes the player's phone) is established when the player
736
+ * is created and on the money-routing calls, so phone is NOT required or read here.
719
737
  *
720
- * If the phone already belongs to another INVO account (same person, new email),
721
- * this throws an InvoError with `isPhoneShareApprovalRequired` — NOT a failure:
722
- * the phone holder was sent a consent SMS. Surface "pending approval" to the user,
723
- * then re-issue the same call once approved (poll `phoneShareStatus`, or use
724
- * `phoneShareInitiate`/`phoneShareApprove` for the in-app OTP fallback).
738
+ * `playerPhone` is optional and only validated (E.164) if you pass it — the backend
739
+ * ignores it on this endpoint, so an existing email-only player can still mint a token.
740
+ * Phone is enforced where it actually matters: `initiateSend`/`initiateTransfer` (the
741
+ * sender's phone, and the recipient's when known) and at player creation.
725
742
  */
726
743
  async mintPlayerToken(input, opts) {
727
744
  if (typeof input.playerEmail !== "string" || !input.playerEmail.trim()) {
728
745
  throw invalidInput("playerEmail", input.playerEmail, "is required");
729
746
  }
730
- assertE164(input.playerPhone, "playerPhone");
747
+ const body = { player_email: input.playerEmail };
748
+ if (input.playerPhone !== void 0) {
749
+ assertE164(input.playerPhone, "playerPhone");
750
+ body["player_phone"] = input.playerPhone;
751
+ }
731
752
  const raw = await this.http.post(
732
753
  "/api/sdk/player-token",
733
- { player_email: input.playerEmail, player_phone: input.playerPhone },
754
+ body,
734
755
  this.auth,
735
756
  { idempotent: true, signal: opts?.signal }
736
757
  // safe to retry: re-mint just issues a fresh token
@@ -1036,20 +1057,32 @@ var InvoServer = class {
1036
1057
  for (const row of history) yield row;
1037
1058
  yielded += history.length;
1038
1059
  if (history.length < pageSize) return;
1039
- const total = Number(pagination?.["total"]);
1060
+ const p = pagination;
1061
+ const total = Number(p?.["total_count"] ?? p?.["total"]);
1040
1062
  if (Number.isFinite(total) && yielded >= total) return;
1041
1063
  }
1042
1064
  }
1043
- /** Read a player's currency balances, by email or playerId (game-secret). */
1065
+ /**
1066
+ * Read a player's currency balances by email (server-side, game-secret).
1067
+ *
1068
+ * NOTE: lookup is by EMAIL only. There is no by-id balance route on the backend
1069
+ * (`playerId` is a per-game internal id), so passing `playerId` throws — use the
1070
+ * browser `InvoClient.getBalance()` (token-authed, identity from the token) for a
1071
+ * client-side read, or `playerEmail` here server-side.
1072
+ */
1044
1073
  async getPlayerBalance(query, opts) {
1045
1074
  let path;
1046
- if (query.playerId != null && String(query.playerId).trim()) {
1047
- path = `/api/player-balances/player/${encodeURIComponent(String(query.playerId))}`;
1048
- } else if (typeof query.playerEmail === "string" && query.playerEmail.trim()) {
1075
+ if (typeof query.playerEmail === "string" && query.playerEmail.trim()) {
1049
1076
  path = `/api/player-balances/player/by-email/${encodeURIComponent(query.playerEmail)}`;
1077
+ } else if (query.playerId != null && String(query.playerId).trim()) {
1078
+ throw new InvoError({
1079
+ message: "getPlayerBalance is by playerEmail only \u2014 there is no by-id balance route. Use InvoClient.getBalance() client-side (player token), or pass playerEmail here.",
1080
+ code: "INVALID_INPUT",
1081
+ status: 0
1082
+ });
1050
1083
  } else {
1051
1084
  throw new InvoError({
1052
- message: "getPlayerBalance requires a playerEmail or playerId.",
1085
+ message: "getPlayerBalance requires a playerEmail.",
1053
1086
  code: "INVALID_INPUT",
1054
1087
  status: 0
1055
1088
  });
package/dist/server.d.cts CHANGED
@@ -1,5 +1,5 @@
1
- import { I as InvoError, S as ServerConfig, a as CallOptions, n as PlayerToken, o as InitiateSendInput, p as InitiateResult, q as InitiateTransferInput, r as CreateCheckoutInput, s as CreateCheckoutResult, t as PurchaseInput, u as PurchaseResult, v as ConfirmPaymentResult, O as OrderDetailsResult, w as PurchaseItemInput, x as PurchaseItemResult, y as ItemHistoryQuery, z as ItemHistoryResult, F as ItemOrderQuery, G as PlayerBalanceQuery, H as PlayerBalanceResult, J as InboundPendingQuery, K as InboundPendingResult, M as LinkedIdentitiesQuery, N as LinkedIdentitiesResult, Q as SmsVerifyResult, T as ClaimTransferInput, U as ClaimResult, W as ClaimCurrencyInput, X as TransactionStatusResult, Y as GuardianApprovalStatusResult, Z as ServerDestinationsQuery, c as DestinationsResult, _ as PhoneShareContact, $ as PhoneShareInitiateResult, a0 as PhoneShareApproveInput, a1 as PhoneShareApproveResult, a2 as PhoneShareStatusResult } from './types-CU2BqbHN.cjs';
2
- export { a3 as CurrencyBalance, g as DestinationGame, a4 as InboundPendingItem, h as InvoErrorInfo, i as InvoHooks, j as InvoRequestInfo, k as InvoResponseInfo, a5 as LinkedIdentityEmail, m as Rail, V as VerificationMethod } from './types-CU2BqbHN.cjs';
1
+ import { I as InvoError, S as ServerConfig, a as CallOptions, n as PlayerToken, o as InitiateSendInput, p as InitiateResult, q as InitiateTransferInput, r as CreateCheckoutInput, s as CreateCheckoutResult, t as PurchaseInput, u as PurchaseResult, v as ConfirmPaymentResult, O as OrderDetailsResult, w as PurchaseItemInput, x as PurchaseItemResult, y as ItemHistoryQuery, z as ItemHistoryResult, F as ItemOrderQuery, G as PlayerBalanceQuery, H as PlayerBalanceResult, J as InboundPendingQuery, K as InboundPendingResult, M as LinkedIdentitiesQuery, N as LinkedIdentitiesResult, Q as SmsVerifyResult, T as ClaimTransferInput, U as ClaimResult, W as ClaimCurrencyInput, X as TransactionStatusResult, Y as GuardianApprovalStatusResult, Z as ServerDestinationsQuery, c as DestinationsResult, _ as PhoneShareContact, $ as PhoneShareInitiateResult, a0 as PhoneShareApproveInput, a1 as PhoneShareApproveResult, a2 as PhoneShareStatusResult } from './types-Cpo5Fvf9.cjs';
2
+ export { a3 as CurrencyBalance, g as DestinationGame, a4 as InboundPendingItem, h as InvoErrorInfo, i as InvoHooks, j as InvoRequestInfo, k as InvoResponseInfo, a5 as LinkedIdentityEmail, m as Rail, V as VerificationMethod } from './types-Cpo5Fvf9.cjs';
3
3
 
4
4
  interface VerifyWebhookOptions {
5
5
  /** Max age of the signed timestamp, in seconds. Default 300 (5 min). */
@@ -152,23 +152,20 @@ declare class InvoServer {
152
152
  /**
153
153
  * Mint a short-lived, game-scoped player token to hand to the browser InvoClient.
154
154
  *
155
- * This is the player REGISTRATION call: the network identity is derived from
156
- * `email + phone` TOGETHER, so both are required. Registering email-only and
157
- * attaching the phone later changes the identity and forces device re-enrollment —
158
- * collect the phone before the first mint. `playerPhone` must be E.164
159
- * (e.g. "+15555550100"); incoming cross-game transfers and the account-linking
160
- * consent SMS are both matched by phone, so an account without one can't receive
161
- * either.
155
+ * This is a SESSION-TOKEN mint for a player who ALREADY EXISTS on the game — not a
156
+ * registration call. The backend looks the player up by `playerEmail` and returns a
157
+ * token for their existing identity; if no such player exists it responds 404. The
158
+ * network identity (which encodes the player's phone) is established when the player
159
+ * is created and on the money-routing calls, so phone is NOT required or read here.
162
160
  *
163
- * If the phone already belongs to another INVO account (same person, new email),
164
- * this throws an InvoError with `isPhoneShareApprovalRequired` — NOT a failure:
165
- * the phone holder was sent a consent SMS. Surface "pending approval" to the user,
166
- * then re-issue the same call once approved (poll `phoneShareStatus`, or use
167
- * `phoneShareInitiate`/`phoneShareApprove` for the in-app OTP fallback).
161
+ * `playerPhone` is optional and only validated (E.164) if you pass it — the backend
162
+ * ignores it on this endpoint, so an existing email-only player can still mint a token.
163
+ * Phone is enforced where it actually matters: `initiateSend`/`initiateTransfer` (the
164
+ * sender's phone, and the recipient's when known) and at player creation.
168
165
  */
169
166
  mintPlayerToken(input: {
170
167
  playerEmail: string;
171
- playerPhone: string;
168
+ playerPhone?: string;
172
169
  }, opts?: CallOptions): Promise<PlayerToken>;
173
170
  /** Initiate a cross-game currency SEND. Inspect result.verificationMethod. */
174
171
  initiateSend(input: InitiateSendInput, opts?: CallOptions): Promise<InitiateResult>;
@@ -223,7 +220,14 @@ declare class InvoServer {
223
220
  playerEmail: string;
224
221
  pageSize?: number;
225
222
  }, opts?: CallOptions): AsyncGenerator<Record<string, unknown>, void, unknown>;
226
- /** Read a player's currency balances, by email or playerId (game-secret). */
223
+ /**
224
+ * Read a player's currency balances by email (server-side, game-secret).
225
+ *
226
+ * NOTE: lookup is by EMAIL only. There is no by-id balance route on the backend
227
+ * (`playerId` is a per-game internal id), so passing `playerId` throws — use the
228
+ * browser `InvoClient.getBalance()` (token-authed, identity from the token) for a
229
+ * client-side read, or `playerEmail` here server-side.
230
+ */
227
231
  getPlayerBalance(query: PlayerBalanceQuery, opts?: CallOptions): Promise<PlayerBalanceResult>;
228
232
  /**
229
233
  * List LIVE, unclaimed inbound sends/transfers addressed to a player at YOUR game —
package/dist/server.d.ts CHANGED
@@ -1,5 +1,5 @@
1
- import { I as InvoError, S as ServerConfig, a as CallOptions, n as PlayerToken, o as InitiateSendInput, p as InitiateResult, q as InitiateTransferInput, r as CreateCheckoutInput, s as CreateCheckoutResult, t as PurchaseInput, u as PurchaseResult, v as ConfirmPaymentResult, O as OrderDetailsResult, w as PurchaseItemInput, x as PurchaseItemResult, y as ItemHistoryQuery, z as ItemHistoryResult, F as ItemOrderQuery, G as PlayerBalanceQuery, H as PlayerBalanceResult, J as InboundPendingQuery, K as InboundPendingResult, M as LinkedIdentitiesQuery, N as LinkedIdentitiesResult, Q as SmsVerifyResult, T as ClaimTransferInput, U as ClaimResult, W as ClaimCurrencyInput, X as TransactionStatusResult, Y as GuardianApprovalStatusResult, Z as ServerDestinationsQuery, c as DestinationsResult, _ as PhoneShareContact, $ as PhoneShareInitiateResult, a0 as PhoneShareApproveInput, a1 as PhoneShareApproveResult, a2 as PhoneShareStatusResult } from './types-CU2BqbHN.js';
2
- export { a3 as CurrencyBalance, g as DestinationGame, a4 as InboundPendingItem, h as InvoErrorInfo, i as InvoHooks, j as InvoRequestInfo, k as InvoResponseInfo, a5 as LinkedIdentityEmail, m as Rail, V as VerificationMethod } from './types-CU2BqbHN.js';
1
+ import { I as InvoError, S as ServerConfig, a as CallOptions, n as PlayerToken, o as InitiateSendInput, p as InitiateResult, q as InitiateTransferInput, r as CreateCheckoutInput, s as CreateCheckoutResult, t as PurchaseInput, u as PurchaseResult, v as ConfirmPaymentResult, O as OrderDetailsResult, w as PurchaseItemInput, x as PurchaseItemResult, y as ItemHistoryQuery, z as ItemHistoryResult, F as ItemOrderQuery, G as PlayerBalanceQuery, H as PlayerBalanceResult, J as InboundPendingQuery, K as InboundPendingResult, M as LinkedIdentitiesQuery, N as LinkedIdentitiesResult, Q as SmsVerifyResult, T as ClaimTransferInput, U as ClaimResult, W as ClaimCurrencyInput, X as TransactionStatusResult, Y as GuardianApprovalStatusResult, Z as ServerDestinationsQuery, c as DestinationsResult, _ as PhoneShareContact, $ as PhoneShareInitiateResult, a0 as PhoneShareApproveInput, a1 as PhoneShareApproveResult, a2 as PhoneShareStatusResult } from './types-Cpo5Fvf9.js';
2
+ export { a3 as CurrencyBalance, g as DestinationGame, a4 as InboundPendingItem, h as InvoErrorInfo, i as InvoHooks, j as InvoRequestInfo, k as InvoResponseInfo, a5 as LinkedIdentityEmail, m as Rail, V as VerificationMethod } from './types-Cpo5Fvf9.js';
3
3
 
4
4
  interface VerifyWebhookOptions {
5
5
  /** Max age of the signed timestamp, in seconds. Default 300 (5 min). */
@@ -152,23 +152,20 @@ declare class InvoServer {
152
152
  /**
153
153
  * Mint a short-lived, game-scoped player token to hand to the browser InvoClient.
154
154
  *
155
- * This is the player REGISTRATION call: the network identity is derived from
156
- * `email + phone` TOGETHER, so both are required. Registering email-only and
157
- * attaching the phone later changes the identity and forces device re-enrollment —
158
- * collect the phone before the first mint. `playerPhone` must be E.164
159
- * (e.g. "+15555550100"); incoming cross-game transfers and the account-linking
160
- * consent SMS are both matched by phone, so an account without one can't receive
161
- * either.
155
+ * This is a SESSION-TOKEN mint for a player who ALREADY EXISTS on the game — not a
156
+ * registration call. The backend looks the player up by `playerEmail` and returns a
157
+ * token for their existing identity; if no such player exists it responds 404. The
158
+ * network identity (which encodes the player's phone) is established when the player
159
+ * is created and on the money-routing calls, so phone is NOT required or read here.
162
160
  *
163
- * If the phone already belongs to another INVO account (same person, new email),
164
- * this throws an InvoError with `isPhoneShareApprovalRequired` — NOT a failure:
165
- * the phone holder was sent a consent SMS. Surface "pending approval" to the user,
166
- * then re-issue the same call once approved (poll `phoneShareStatus`, or use
167
- * `phoneShareInitiate`/`phoneShareApprove` for the in-app OTP fallback).
161
+ * `playerPhone` is optional and only validated (E.164) if you pass it — the backend
162
+ * ignores it on this endpoint, so an existing email-only player can still mint a token.
163
+ * Phone is enforced where it actually matters: `initiateSend`/`initiateTransfer` (the
164
+ * sender's phone, and the recipient's when known) and at player creation.
168
165
  */
169
166
  mintPlayerToken(input: {
170
167
  playerEmail: string;
171
- playerPhone: string;
168
+ playerPhone?: string;
172
169
  }, opts?: CallOptions): Promise<PlayerToken>;
173
170
  /** Initiate a cross-game currency SEND. Inspect result.verificationMethod. */
174
171
  initiateSend(input: InitiateSendInput, opts?: CallOptions): Promise<InitiateResult>;
@@ -223,7 +220,14 @@ declare class InvoServer {
223
220
  playerEmail: string;
224
221
  pageSize?: number;
225
222
  }, opts?: CallOptions): AsyncGenerator<Record<string, unknown>, void, unknown>;
226
- /** Read a player's currency balances, by email or playerId (game-secret). */
223
+ /**
224
+ * Read a player's currency balances by email (server-side, game-secret).
225
+ *
226
+ * NOTE: lookup is by EMAIL only. There is no by-id balance route on the backend
227
+ * (`playerId` is a per-game internal id), so passing `playerId` throws — use the
228
+ * browser `InvoClient.getBalance()` (token-authed, identity from the token) for a
229
+ * client-side read, or `playerEmail` here server-side.
230
+ */
227
231
  getPlayerBalance(query: PlayerBalanceQuery, opts?: CallOptions): Promise<PlayerBalanceResult>;
228
232
  /**
229
233
  * List LIVE, unclaimed inbound sends/transfers addressed to a player at YOUR game —
package/dist/server.js CHANGED
@@ -1,5 +1,5 @@
1
- import { InvoError, assertSecureBaseUrl, Http, toDestinationsResult } from './chunk-4GNJIQY2.js';
2
- export { InvoError } from './chunk-4GNJIQY2.js';
1
+ import { InvoError, assertSecureBaseUrl, Http, toDestinationsResult } from './chunk-SNFO5THM.js';
2
+ export { InvoError } from './chunk-SNFO5THM.js';
3
3
  import { createHmac, timingSafeEqual } from 'crypto';
4
4
 
5
5
  var DEFAULT_TOLERANCE_SEC = 300;
@@ -167,7 +167,7 @@ async function hmacHexSubtle(secret, message) {
167
167
  }
168
168
 
169
169
  // src/server.ts
170
- var DEFAULT_UA = "invonetwork-web-sdk/2.1.2 (+https://invo.network)";
170
+ var DEFAULT_UA = "invonetwork-web-sdk/2.3.0 (+https://invo.network)";
171
171
  var MAX_USD_AMOUNT = 999.99;
172
172
  var MAX_ITEM_PRICE = 999999.99;
173
173
  function invalidInput(label, value, why) {
@@ -348,28 +348,29 @@ var InvoServer = class {
348
348
  /**
349
349
  * Mint a short-lived, game-scoped player token to hand to the browser InvoClient.
350
350
  *
351
- * This is the player REGISTRATION call: the network identity is derived from
352
- * `email + phone` TOGETHER, so both are required. Registering email-only and
353
- * attaching the phone later changes the identity and forces device re-enrollment —
354
- * collect the phone before the first mint. `playerPhone` must be E.164
355
- * (e.g. "+15555550100"); incoming cross-game transfers and the account-linking
356
- * consent SMS are both matched by phone, so an account without one can't receive
357
- * either.
351
+ * This is a SESSION-TOKEN mint for a player who ALREADY EXISTS on the game — not a
352
+ * registration call. The backend looks the player up by `playerEmail` and returns a
353
+ * token for their existing identity; if no such player exists it responds 404. The
354
+ * network identity (which encodes the player's phone) is established when the player
355
+ * is created and on the money-routing calls, so phone is NOT required or read here.
358
356
  *
359
- * If the phone already belongs to another INVO account (same person, new email),
360
- * this throws an InvoError with `isPhoneShareApprovalRequired` — NOT a failure:
361
- * the phone holder was sent a consent SMS. Surface "pending approval" to the user,
362
- * then re-issue the same call once approved (poll `phoneShareStatus`, or use
363
- * `phoneShareInitiate`/`phoneShareApprove` for the in-app OTP fallback).
357
+ * `playerPhone` is optional and only validated (E.164) if you pass it — the backend
358
+ * ignores it on this endpoint, so an existing email-only player can still mint a token.
359
+ * Phone is enforced where it actually matters: `initiateSend`/`initiateTransfer` (the
360
+ * sender's phone, and the recipient's when known) and at player creation.
364
361
  */
365
362
  async mintPlayerToken(input, opts) {
366
363
  if (typeof input.playerEmail !== "string" || !input.playerEmail.trim()) {
367
364
  throw invalidInput("playerEmail", input.playerEmail, "is required");
368
365
  }
369
- assertE164(input.playerPhone, "playerPhone");
366
+ const body = { player_email: input.playerEmail };
367
+ if (input.playerPhone !== void 0) {
368
+ assertE164(input.playerPhone, "playerPhone");
369
+ body["player_phone"] = input.playerPhone;
370
+ }
370
371
  const raw = await this.http.post(
371
372
  "/api/sdk/player-token",
372
- { player_email: input.playerEmail, player_phone: input.playerPhone },
373
+ body,
373
374
  this.auth,
374
375
  { idempotent: true, signal: opts?.signal }
375
376
  // safe to retry: re-mint just issues a fresh token
@@ -675,20 +676,32 @@ var InvoServer = class {
675
676
  for (const row of history) yield row;
676
677
  yielded += history.length;
677
678
  if (history.length < pageSize) return;
678
- const total = Number(pagination?.["total"]);
679
+ const p = pagination;
680
+ const total = Number(p?.["total_count"] ?? p?.["total"]);
679
681
  if (Number.isFinite(total) && yielded >= total) return;
680
682
  }
681
683
  }
682
- /** Read a player's currency balances, by email or playerId (game-secret). */
684
+ /**
685
+ * Read a player's currency balances by email (server-side, game-secret).
686
+ *
687
+ * NOTE: lookup is by EMAIL only. There is no by-id balance route on the backend
688
+ * (`playerId` is a per-game internal id), so passing `playerId` throws — use the
689
+ * browser `InvoClient.getBalance()` (token-authed, identity from the token) for a
690
+ * client-side read, or `playerEmail` here server-side.
691
+ */
683
692
  async getPlayerBalance(query, opts) {
684
693
  let path;
685
- if (query.playerId != null && String(query.playerId).trim()) {
686
- path = `/api/player-balances/player/${encodeURIComponent(String(query.playerId))}`;
687
- } else if (typeof query.playerEmail === "string" && query.playerEmail.trim()) {
694
+ if (typeof query.playerEmail === "string" && query.playerEmail.trim()) {
688
695
  path = `/api/player-balances/player/by-email/${encodeURIComponent(query.playerEmail)}`;
696
+ } else if (query.playerId != null && String(query.playerId).trim()) {
697
+ throw new InvoError({
698
+ message: "getPlayerBalance is by playerEmail only \u2014 there is no by-id balance route. Use InvoClient.getBalance() client-side (player token), or pass playerEmail here.",
699
+ code: "INVALID_INPUT",
700
+ status: 0
701
+ });
689
702
  } else {
690
703
  throw new InvoError({
691
- message: "getPlayerBalance requires a playerEmail or playerId.",
704
+ message: "getPlayerBalance requires a playerEmail.",
692
705
  code: "INVALID_INPUT",
693
706
  status: 0
694
707
  });
@@ -28,6 +28,12 @@ declare class InvoError extends Error {
28
28
  get isTokenExpired(): boolean;
29
29
  /** True if `enrollPasskey()` needs the OTP-grant flow (`enrollmentBegin`/`enrollmentVerify`). */
30
30
  get isEnrollmentAuthorizationRequired(): boolean;
31
+ /**
32
+ * True if a passkey approve/confirm was rejected because the assertion lacked user
33
+ * verification (`WEBAUTHN_UV_REQUIRED`, 401). Re-run the ceremony requiring UV
34
+ * (biometric/PIN) — the backend treats a UV-satisfied assertion as the signed step-up.
35
+ */
36
+ get isUserVerificationRequired(): boolean;
31
37
  /**
32
38
  * True if enrolling is blocked because the identity already has an enrolled method
33
39
  * (anti-takeover gate, register/complete → 409). Two ways forward: `linkDevice` when
@@ -56,16 +62,25 @@ declare class InvoError extends Error {
56
62
  */
57
63
  get isInsufficientBalance(): boolean;
58
64
  /**
59
- * True if the call needs phone-share approval before it can complete (409). Raised by
60
- * registration/token-mint and by claims when the phone already belongs to another INVO
61
- * account (same person, new email — expected, not a failure). The phone holder gets a
62
- * consent SMS; show "pending approval", then re-issue the identical call once approved
63
- * (poll `phoneShareStatus`, or use `phoneShareInitiate`/`phoneShareApprove` for the OTP
64
- * fallback). `phoneShareApprovalId` carries the id from the 409 body.
65
+ * True if the call needs phone-share approval before it can complete (409) — the
66
+ * collecting/registering identity isn't yet authorized for the phone on file. Raised by:
67
+ * - registration/token-mint (phone already on another INVO account), and
68
+ * - **claim + confirm-receipt** (`claimTransfer`/`claimCurrency`,
69
+ * `confirmReceiptSend`/`confirmReceiptTransfer`) — the receiver phone is contested,
70
+ * so INVO holds the money and texts the phone owner to approve.
71
+ *
72
+ * NOT a failure. Show `err.message` verbatim (the backend supplies the user-facing text;
73
+ * `phoneShareLast4` tells the UI which phone), keep the funds pending, and **retry the same
74
+ * call** once the phone owner approves — an approved consent makes the retry succeed
75
+ * idempotently. On denial/expiry the backend refunds the sender. (`phoneShareApprovalId`
76
+ * carries the id when the 409 came from the OTP-handshake path;
77
+ * `phoneShareInitiate`/`phoneShareApprove`/`phoneShareStatus` drive that fallback.)
65
78
  */
66
79
  get isPhoneShareApprovalRequired(): boolean;
67
80
  /** The `approval_id` from a phone-share 409 body, for `phoneShareApprove`. */
68
81
  get phoneShareApprovalId(): string | undefined;
82
+ /** Last 4 digits of the phone that must approve (`phone_last4`), for the UI message. */
83
+ get phoneShareLast4(): string | undefined;
69
84
  /** True if the phone-share (phone, requesting_email) pair was already approved. */
70
85
  get isPhoneShareAlreadyApproved(): boolean;
71
86
  /** True if an idempotency-keyed request was a duplicate (item purchase → 409). */
@@ -154,7 +169,8 @@ interface InitiateSendInput {
154
169
  senderPlayerName: string;
155
170
  senderPlayerEmail: string;
156
171
  senderPlayerPhone: string;
157
- receiverPlayerEmail: string;
172
+ /** Optional — you can send by the recipient's PHONE alone; they supply their email at claim. */
173
+ receiverPlayerEmail?: string;
158
174
  receiverPlayerPhone: string;
159
175
  receivingGameId: string | number;
160
176
  amount: string | number;
@@ -164,7 +180,8 @@ interface InitiateTransferInput {
164
180
  sourcePlayerName: string;
165
181
  sourcePlayerEmail: string;
166
182
  sourcePlayerPhone: string;
167
- targetPlayerEmail: string;
183
+ /** Optional — you can transfer by the recipient's PHONE alone; they supply their email at claim. */
184
+ targetPlayerEmail?: string;
168
185
  targetPlayerPhone: string;
169
186
  targetGameId: string | number;
170
187
  amount: string | number;
@@ -28,6 +28,12 @@ declare class InvoError extends Error {
28
28
  get isTokenExpired(): boolean;
29
29
  /** True if `enrollPasskey()` needs the OTP-grant flow (`enrollmentBegin`/`enrollmentVerify`). */
30
30
  get isEnrollmentAuthorizationRequired(): boolean;
31
+ /**
32
+ * True if a passkey approve/confirm was rejected because the assertion lacked user
33
+ * verification (`WEBAUTHN_UV_REQUIRED`, 401). Re-run the ceremony requiring UV
34
+ * (biometric/PIN) — the backend treats a UV-satisfied assertion as the signed step-up.
35
+ */
36
+ get isUserVerificationRequired(): boolean;
31
37
  /**
32
38
  * True if enrolling is blocked because the identity already has an enrolled method
33
39
  * (anti-takeover gate, register/complete → 409). Two ways forward: `linkDevice` when
@@ -56,16 +62,25 @@ declare class InvoError extends Error {
56
62
  */
57
63
  get isInsufficientBalance(): boolean;
58
64
  /**
59
- * True if the call needs phone-share approval before it can complete (409). Raised by
60
- * registration/token-mint and by claims when the phone already belongs to another INVO
61
- * account (same person, new email — expected, not a failure). The phone holder gets a
62
- * consent SMS; show "pending approval", then re-issue the identical call once approved
63
- * (poll `phoneShareStatus`, or use `phoneShareInitiate`/`phoneShareApprove` for the OTP
64
- * fallback). `phoneShareApprovalId` carries the id from the 409 body.
65
+ * True if the call needs phone-share approval before it can complete (409) — the
66
+ * collecting/registering identity isn't yet authorized for the phone on file. Raised by:
67
+ * - registration/token-mint (phone already on another INVO account), and
68
+ * - **claim + confirm-receipt** (`claimTransfer`/`claimCurrency`,
69
+ * `confirmReceiptSend`/`confirmReceiptTransfer`) — the receiver phone is contested,
70
+ * so INVO holds the money and texts the phone owner to approve.
71
+ *
72
+ * NOT a failure. Show `err.message` verbatim (the backend supplies the user-facing text;
73
+ * `phoneShareLast4` tells the UI which phone), keep the funds pending, and **retry the same
74
+ * call** once the phone owner approves — an approved consent makes the retry succeed
75
+ * idempotently. On denial/expiry the backend refunds the sender. (`phoneShareApprovalId`
76
+ * carries the id when the 409 came from the OTP-handshake path;
77
+ * `phoneShareInitiate`/`phoneShareApprove`/`phoneShareStatus` drive that fallback.)
65
78
  */
66
79
  get isPhoneShareApprovalRequired(): boolean;
67
80
  /** The `approval_id` from a phone-share 409 body, for `phoneShareApprove`. */
68
81
  get phoneShareApprovalId(): string | undefined;
82
+ /** Last 4 digits of the phone that must approve (`phone_last4`), for the UI message. */
83
+ get phoneShareLast4(): string | undefined;
69
84
  /** True if the phone-share (phone, requesting_email) pair was already approved. */
70
85
  get isPhoneShareAlreadyApproved(): boolean;
71
86
  /** True if an idempotency-keyed request was a duplicate (item purchase → 409). */
@@ -154,7 +169,8 @@ interface InitiateSendInput {
154
169
  senderPlayerName: string;
155
170
  senderPlayerEmail: string;
156
171
  senderPlayerPhone: string;
157
- receiverPlayerEmail: string;
172
+ /** Optional — you can send by the recipient's PHONE alone; they supply their email at claim. */
173
+ receiverPlayerEmail?: string;
158
174
  receiverPlayerPhone: string;
159
175
  receivingGameId: string | number;
160
176
  amount: string | number;
@@ -164,7 +180,8 @@ interface InitiateTransferInput {
164
180
  sourcePlayerName: string;
165
181
  sourcePlayerEmail: string;
166
182
  sourcePlayerPhone: string;
167
- targetPlayerEmail: string;
183
+ /** Optional — you can transfer by the recipient's PHONE alone; they supply their email at claim. */
184
+ targetPlayerEmail?: string;
168
185
  targetPlayerPhone: string;
169
186
  targetGameId: string | number;
170
187
  amount: string | number;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@invonetwork/web-sdk",
3
- "version": "2.1.2",
3
+ "version": "2.3.0",
4
4
  "description": "INVO Web SDK — currency purchase + passkey (WebAuthn) verification for partner web platforms.",
5
5
  "license": "SEE LICENSE IN LICENSE",
6
6
  "private": false,