@invonetwork/web-sdk 1.2.0 → 2.0.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,41 @@ 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.0.0] — 2026-07-02
8
+
9
+ **BREAKING — `mintPlayerToken` now requires `playerPhone` (E.164).** Requested by the INVO
10
+ backend after a live incident: a player registered email-only couldn't receive a cross-game
11
+ transfer (incoming transfers are matched by phone) and never got the account-linking consent
12
+ SMS (also phone-triggered). The network identity is derived from **email + phone together**,
13
+ so the phone must be present on the FIRST registration call — attaching it later changes the
14
+ identity and forces device re-enrollment.
15
+
16
+ - `mintPlayerToken({ playerEmail, playerPhone })` — `playerPhone` is required and validated
17
+ as E.164 (`+15555550100`: leading `+`, country code, digits only) before any network call;
18
+ the body now posts `player_phone` alongside `player_email`.
19
+ - **Pending approval is surfaced, not an error to swallow:** minting with a phone that
20
+ already belongs to another INVO account (same person, new email) throws the existing
21
+ `isPhoneShareApprovalRequired` 409 — the phone holder got a consent SMS. New
22
+ `InvoError.phoneShareApprovalId` exposes the `approval_id` from the 409 body for the
23
+ `phoneShareApprove` OTP fallback. Docs updated to cover the registration path (previously
24
+ documented for claims only).
25
+ - README: new "Player registration (email + phone, required)" section; examples updated
26
+ (`proxy-server.ts` token route now rejects a phoneless actor with a clear 400).
27
+
28
+ **Migration:** collect the player's phone in your enrollment UI before the first
29
+ `mintPlayerToken` call and pass it as `playerPhone` in E.164. Handle the
30
+ `isPhoneShareApprovalRequired` error as a "pending approval" UI state.
31
+
32
+ ## [1.2.1] — 2026-07-01
33
+
34
+ **Fix — browser "Illegal invocation".** The SDK invoked its fetch as `this.fetchImpl(...)`,
35
+ so the browser's native `fetch` ran with the wrong `this` and threw
36
+ `TypeError: Illegal invocation` — breaking every browser `InvoClient` read
37
+ (balance/destinations/pending) and the passkey ceremonies when using the default global
38
+ `fetch` (retries then made it slow on top). The fetch impl is now bound to `globalThis`
39
+ (harmless for a custom `fetch`). No API change. Node/tests were unaffected, which is why it
40
+ slipped through — added a `this`-sensitive regression test.
41
+
7
42
  ## [1.2.0] — 2026-07-01
8
43
 
9
44
  Two more server-side capabilities on `InvoServer`.
@@ -73,7 +108,7 @@ Start of the **discovery layer** for send/transfer UIs.
73
108
 
74
109
  ## [0.6.0] — 2026-07-01
75
110
 
76
- Three additive browser flows the dashboard needed, built to the live backend contracts.
111
+ Three additive browser flows for partner front-ends, built to the live backend contracts.
77
112
 
78
113
  - **`InvoClient.getPendingCollect()`** — the player's own pending-to-collect list
79
114
  (player-token `GET /api/sdk/transfers/pending`), PII-free. Each row's `kind`
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:** `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.
5
+ > **Status:** `v2.0.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. **v2.0.0 is a major (breaking) release:** `mintPlayerToken` now requires `playerPhone` (E.164) — see the [CHANGELOG](CHANGELOG.md) migration note.
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,6 +82,27 @@ 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)
86
+
87
+ `mintPlayerToken` is the player **registration** call, and it requires **both** `playerEmail` and `playerPhone`:
88
+
89
+ ```ts
90
+ // 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
+ });
95
+ ```
96
+
97
+ Why phone is not optional on the INVO network:
98
+
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.
103
+
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.
105
+
85
106
  ### Token bootstrap (both modes)
86
107
 
87
108
  Expose one small backend endpoint that calls `mintPlayerToken` (server-side, with the game secret) and hand the token to the browser:
@@ -117,6 +138,11 @@ const client = new InvoClient({
117
138
 
118
139
  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.
119
140
 
141
+ **Running `InvoServer` in the proxy** (for the game-secret writes — initiate, checkout, purchase — so the secret leaves the browser): see the drop-in reference at [`examples/proxy-server.ts`](examples/proxy-server.ts). Its actor resolver is pluggable:
142
+
143
+ - **Real partner** (one login = one player) — derive the acting player from your **session**.
144
+ - **Trusted first-party rig** (an internal tool that impersonates arbitrary test players) — the caller names `playerEmail`, guarded by a shared-secret header (`INVO_PROXY_TRUSTED_SECRET`), the same trusted pattern as a `player_email` token minter. Never expose this mode to end-user browsers.
145
+
120
146
  > **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).
121
147
 
122
148
  ## Before you go live
@@ -124,6 +150,7 @@ The WebAuthn ceremony still runs in the browser (it must — it's `navigator.cre
124
150
  INVO enables each flow for your tenant in the [console](#get-your-account--game-secret-invo-console). What you need to do:
125
151
 
126
152
  - **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)).
127
154
  - **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.)
128
155
  - **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.)
129
156
  - **For currency purchase:** card checkout works out of the box; ask INVO to enable the `game`/`steam` rails if you need them.
@@ -346,7 +373,10 @@ try {
346
373
 
347
374
  **"You have X to collect"**
348
375
 
349
- - **Browser (player-token):** `client.getPendingCollect()` returns the player's own pending items. Each row's `kind` tells you the action — `"identity_gate"` → `approve*` (they initiated), `"receiving_confirm"` → `confirmReceipt*` (a peer sent to them). PII-free (no claim code / phone).
376
+ - **Browser (player-token):** `client.getPendingCollect()` returns the player's own pending items. Each row's `kind` tells you the action:
377
+ - `"receiving_confirm"` → a peer/another game **sent value TO this player** (incoming) → call `confirmReceiptSend`/`confirmReceiptTransfer`.
378
+ - `"identity_gate"` → **this player initiated** and it's awaiting them → call `approveSend`/`approveTransfer`.
379
+ > **Seeing incoming transfers from other games?** They come back as **`kind: "receiving_confirm"`** — render **both** kinds (a UI that only shows `identity_gate` will miss all inbound). The list is scoped to the token's player, so mint the token for the **recipient**. PII-free (no claim code / phone).
350
380
  - **Server (game-secret):** `server.getInboundPending({ playerEmail | playerPhone })` — richer, includes `toPhone`/`toIdentityId` for routing a notification to the right account. Match `toPhone` to the player (`toIdentityId` is null when the phone maps to >1 of your players).
351
381
 
352
382
  ---
@@ -519,7 +549,7 @@ try {
519
549
 
520
550
  | Method | Returns |
521
551
  |---|---|
522
- | `mintPlayerToken({ playerEmail })` | `{ token, expiresAt, identityId }` |
552
+ | `mintPlayerToken({ playerEmail, playerPhone })` | `{ token, expiresAt, identityId }` — **both required**; `playerPhone` must be E.164 (see [Player registration](#player-registration-email--phone-required)) |
523
553
  | `initiateSend(input)` | `{ transactionId, verificationMethod, guardianApproval?, raw }` |
524
554
  | `initiateTransfer(input)` | `{ transactionId, verificationMethod, guardianApproval?, raw }` |
525
555
  | `createCheckout(input)` | `{ sessionId, checkoutUrl, expiresAt, raw }` |
@@ -36,10 +36,22 @@ var InvoError = class _InvoError extends Error {
36
36
  const b = this.bodyObject();
37
37
  return this.code === "INSUFFICIENT_BALANCE" || "required_amount" in b || /insufficient[_ ]balance/i.test(this.message);
38
38
  }
39
- /** True if a claim needs phone-share approval before it can complete (claim → 409). */
39
+ /**
40
+ * True if the call needs phone-share approval before it can complete (409). Raised by
41
+ * registration/token-mint and by claims when the phone already belongs to another INVO
42
+ * account (same person, new email — expected, not a failure). The phone holder gets a
43
+ * consent SMS; show "pending approval", then re-issue the identical call once approved
44
+ * (poll `phoneShareStatus`, or use `phoneShareInitiate`/`phoneShareApprove` for the OTP
45
+ * fallback). `phoneShareApprovalId` carries the id from the 409 body.
46
+ */
40
47
  get isPhoneShareApprovalRequired() {
41
48
  return this.code === "PHONE_SHARE_APPROVAL_REQUIRED";
42
49
  }
50
+ /** The `approval_id` from a phone-share 409 body, for `phoneShareApprove`. */
51
+ get phoneShareApprovalId() {
52
+ const v = this.bodyObject()["approval_id"];
53
+ return typeof v === "string" && v ? v : void 0;
54
+ }
43
55
  /** True if the phone-share (phone, requesting_email) pair was already approved. */
44
56
  get isPhoneShareAlreadyApproved() {
45
57
  return this.code === "PHONE_SHARE_ALREADY_APPROVED";
@@ -104,7 +116,7 @@ var _Http = class _Http {
104
116
  "No fetch implementation available. Use Node >=18, or pass `fetch` in the config."
105
117
  );
106
118
  }
107
- this.fetchImpl = f;
119
+ this.fetchImpl = f.bind(globalThis);
108
120
  this.userAgent = opts.userAgent;
109
121
  this.maxRetries = Math.max(0, opts.maxRetries ?? 2);
110
122
  this.retryBaseDelayMs = opts.retryBaseDelayMs ?? 250;
@@ -308,5 +320,5 @@ function toDestinationsResult(raw, direction) {
308
320
  }
309
321
 
310
322
  export { Http, InvoError, assertSecureBaseUrl, toDestinationsResult };
311
- //# sourceMappingURL=chunk-P65XQ6VF.js.map
312
- //# sourceMappingURL=chunk-P65XQ6VF.js.map
323
+ //# sourceMappingURL=chunk-6XCI53XJ.js.map
324
+ //# sourceMappingURL=chunk-6XCI53XJ.js.map
package/dist/index.cjs CHANGED
@@ -38,10 +38,22 @@ var InvoError = class _InvoError extends Error {
38
38
  const b = this.bodyObject();
39
39
  return this.code === "INSUFFICIENT_BALANCE" || "required_amount" in b || /insufficient[_ ]balance/i.test(this.message);
40
40
  }
41
- /** True if a claim needs phone-share approval before it can complete (claim → 409). */
41
+ /**
42
+ * True if the call needs phone-share approval before it can complete (409). Raised by
43
+ * registration/token-mint and by claims when the phone already belongs to another INVO
44
+ * account (same person, new email — expected, not a failure). The phone holder gets a
45
+ * consent SMS; show "pending approval", then re-issue the identical call once approved
46
+ * (poll `phoneShareStatus`, or use `phoneShareInitiate`/`phoneShareApprove` for the OTP
47
+ * fallback). `phoneShareApprovalId` carries the id from the 409 body.
48
+ */
42
49
  get isPhoneShareApprovalRequired() {
43
50
  return this.code === "PHONE_SHARE_APPROVAL_REQUIRED";
44
51
  }
52
+ /** The `approval_id` from a phone-share 409 body, for `phoneShareApprove`. */
53
+ get phoneShareApprovalId() {
54
+ const v = this.bodyObject()["approval_id"];
55
+ return typeof v === "string" && v ? v : void 0;
56
+ }
45
57
  /** True if the phone-share (phone, requesting_email) pair was already approved. */
46
58
  get isPhoneShareAlreadyApproved() {
47
59
  return this.code === "PHONE_SHARE_ALREADY_APPROVED";
@@ -106,7 +118,7 @@ var _Http = class _Http {
106
118
  "No fetch implementation available. Use Node >=18, or pass `fetch` in the config."
107
119
  );
108
120
  }
109
- this.fetchImpl = f;
121
+ this.fetchImpl = f.bind(globalThis);
110
122
  this.userAgent = opts.userAgent;
111
123
  this.maxRetries = Math.max(0, opts.maxRetries ?? 2);
112
124
  this.retryBaseDelayMs = opts.retryBaseDelayMs ?? 250;
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 } from './types-DTAmriOB.cjs';
2
- 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-DTAmriOB.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 } from './types-bp0UtN_N.cjs';
2
+ 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-bp0UtN_N.cjs';
3
3
 
4
4
  declare class InvoClient {
5
5
  private readonly http;
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 } from './types-DTAmriOB.js';
2
- 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-DTAmriOB.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 } from './types-bp0UtN_N.js';
2
+ 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-bp0UtN_N.js';
3
3
 
4
4
  declare class InvoClient {
5
5
  private readonly http;
package/dist/index.js CHANGED
@@ -1,5 +1,5 @@
1
- import { assertSecureBaseUrl, Http, toDestinationsResult, InvoError } from './chunk-P65XQ6VF.js';
2
- export { InvoError } from './chunk-P65XQ6VF.js';
1
+ import { assertSecureBaseUrl, Http, toDestinationsResult, InvoError } from './chunk-6XCI53XJ.js';
2
+ export { InvoError } from './chunk-6XCI53XJ.js';
3
3
 
4
4
  // src/shared/webauthn.ts
5
5
  function b64urlToBuffer(value) {
package/dist/server.cjs CHANGED
@@ -40,10 +40,22 @@ var InvoError = class _InvoError extends Error {
40
40
  const b = this.bodyObject();
41
41
  return this.code === "INSUFFICIENT_BALANCE" || "required_amount" in b || /insufficient[_ ]balance/i.test(this.message);
42
42
  }
43
- /** True if a claim needs phone-share approval before it can complete (claim → 409). */
43
+ /**
44
+ * True if the call needs phone-share approval before it can complete (409). Raised by
45
+ * registration/token-mint and by claims when the phone already belongs to another INVO
46
+ * account (same person, new email — expected, not a failure). The phone holder gets a
47
+ * consent SMS; show "pending approval", then re-issue the identical call once approved
48
+ * (poll `phoneShareStatus`, or use `phoneShareInitiate`/`phoneShareApprove` for the OTP
49
+ * fallback). `phoneShareApprovalId` carries the id from the 409 body.
50
+ */
44
51
  get isPhoneShareApprovalRequired() {
45
52
  return this.code === "PHONE_SHARE_APPROVAL_REQUIRED";
46
53
  }
54
+ /** The `approval_id` from a phone-share 409 body, for `phoneShareApprove`. */
55
+ get phoneShareApprovalId() {
56
+ const v = this.bodyObject()["approval_id"];
57
+ return typeof v === "string" && v ? v : void 0;
58
+ }
47
59
  /** True if the phone-share (phone, requesting_email) pair was already approved. */
48
60
  get isPhoneShareAlreadyApproved() {
49
61
  return this.code === "PHONE_SHARE_ALREADY_APPROVED";
@@ -108,7 +120,7 @@ var _Http = class _Http {
108
120
  "No fetch implementation available. Use Node >=18, or pass `fetch` in the config."
109
121
  );
110
122
  }
111
- this.fetchImpl = f;
123
+ this.fetchImpl = f.bind(globalThis);
112
124
  this.userAgent = opts.userAgent;
113
125
  this.maxRetries = Math.max(0, opts.maxRetries ?? 2);
114
126
  this.retryBaseDelayMs = opts.retryBaseDelayMs ?? 250;
@@ -469,7 +481,7 @@ async function hmacHexSubtle(secret, message) {
469
481
  }
470
482
 
471
483
  // src/server.ts
472
- var DEFAULT_UA = "invonetwork-web-sdk/1.2.0 (+https://invo.network)";
484
+ var DEFAULT_UA = "invonetwork-web-sdk/2.0.0 (+https://invo.network)";
473
485
  var MAX_USD_AMOUNT = 999.99;
474
486
  var MAX_ITEM_PRICE = 999999.99;
475
487
  function invalidInput(label, value, why) {
@@ -501,6 +513,12 @@ function parseMoney(value, max, label) {
501
513
  function assertUsdAmount(usdAmount) {
502
514
  parseMoney(usdAmount, MAX_USD_AMOUNT, "usdAmount");
503
515
  }
516
+ var E164 = /^\+[1-9]\d{1,14}$/;
517
+ function assertE164(value, label) {
518
+ if (typeof value !== "string" || !E164.test(value)) {
519
+ throw invalidInput(label, value, 'must be an E.164 phone number, e.g. "+15555550100"');
520
+ }
521
+ }
504
522
  function toOrderDetails(raw) {
505
523
  return {
506
524
  order: raw["order"] ?? {},
@@ -641,14 +659,31 @@ var InvoServer = class {
641
659
  });
642
660
  this.auth = { kind: "game-secret", secret: config.gameSecret };
643
661
  }
644
- /** Mint a short-lived, game-scoped player token to hand to the browser InvoClient. */
662
+ /**
663
+ * Mint a short-lived, game-scoped player token to hand to the browser InvoClient.
664
+ *
665
+ * This is the player REGISTRATION call: the network identity is derived from
666
+ * `email + phone` TOGETHER, so both are required. Registering email-only and
667
+ * attaching the phone later changes the identity and forces device re-enrollment —
668
+ * collect the phone before the first mint. `playerPhone` must be E.164
669
+ * (e.g. "+15555550100"); incoming cross-game transfers and the account-linking
670
+ * consent SMS are both matched by phone, so an account without one can't receive
671
+ * either.
672
+ *
673
+ * If the phone already belongs to another INVO account (same person, new email),
674
+ * this throws an InvoError with `isPhoneShareApprovalRequired` — NOT a failure:
675
+ * the phone holder was sent a consent SMS. Surface "pending approval" to the user,
676
+ * then re-issue the same call once approved (poll `phoneShareStatus`, or use
677
+ * `phoneShareInitiate`/`phoneShareApprove` for the in-app OTP fallback).
678
+ */
645
679
  async mintPlayerToken(input, opts) {
646
680
  if (typeof input.playerEmail !== "string" || !input.playerEmail.trim()) {
647
681
  throw invalidInput("playerEmail", input.playerEmail, "is required");
648
682
  }
683
+ assertE164(input.playerPhone, "playerPhone");
649
684
  const raw = await this.http.post(
650
685
  "/api/sdk/player-token",
651
- { player_email: input.playerEmail },
686
+ { player_email: input.playerEmail, player_phone: input.playerPhone },
652
687
  this.auth,
653
688
  { idempotent: true, signal: opts?.signal }
654
689
  // safe to retry: re-mint just issues a fresh token
package/dist/server.d.cts CHANGED
@@ -1,5 +1,5 @@
1
- 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, M as SmsVerifyResult, N as ClaimTransferInput, Q as ClaimResult, T as ClaimCurrencyInput, U as TransactionStatusResult, W as GuardianApprovalStatusResult, X as ServerDestinationsQuery, c as DestinationsResult, Y as PhoneShareContact, Z as PhoneShareInitiateResult, _ as PhoneShareApproveInput, $ as PhoneShareApproveResult, a0 as PhoneShareStatusResult } from './types-DTAmriOB.cjs';
2
- export { a1 as CurrencyBalance, f as DestinationGame, a2 as InboundPendingItem, g as InvoErrorInfo, h as InvoHooks, i as InvoRequestInfo, j as InvoResponseInfo, a3 as LinkedIdentityEmail, R as Rail, V as VerificationMethod } from './types-DTAmriOB.cjs';
1
+ 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, M as SmsVerifyResult, N as ClaimTransferInput, Q as ClaimResult, T as ClaimCurrencyInput, U as TransactionStatusResult, W as GuardianApprovalStatusResult, X as ServerDestinationsQuery, c as DestinationsResult, Y as PhoneShareContact, Z as PhoneShareInitiateResult, _ as PhoneShareApproveInput, $ as PhoneShareApproveResult, a0 as PhoneShareStatusResult } from './types-bp0UtN_N.cjs';
2
+ export { a1 as CurrencyBalance, f as DestinationGame, a2 as InboundPendingItem, g as InvoErrorInfo, h as InvoHooks, i as InvoRequestInfo, j as InvoResponseInfo, a3 as LinkedIdentityEmail, R as Rail, V as VerificationMethod } from './types-bp0UtN_N.cjs';
3
3
 
4
4
  interface VerifyWebhookOptions {
5
5
  /** Max age of the signed timestamp, in seconds. Default 300 (5 min). */
@@ -149,9 +149,26 @@ declare class InvoServer {
149
149
  private readonly http;
150
150
  private readonly auth;
151
151
  constructor(config: ServerConfig);
152
- /** Mint a short-lived, game-scoped player token to hand to the browser InvoClient. */
152
+ /**
153
+ * Mint a short-lived, game-scoped player token to hand to the browser InvoClient.
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.
162
+ *
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).
168
+ */
153
169
  mintPlayerToken(input: {
154
170
  playerEmail: string;
171
+ playerPhone: string;
155
172
  }, opts?: CallOptions): Promise<PlayerToken>;
156
173
  /** Initiate a cross-game currency SEND. Inspect result.verificationMethod. */
157
174
  initiateSend(input: InitiateSendInput, opts?: CallOptions): Promise<InitiateResult>;
package/dist/server.d.ts CHANGED
@@ -1,5 +1,5 @@
1
- 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, M as SmsVerifyResult, N as ClaimTransferInput, Q as ClaimResult, T as ClaimCurrencyInput, U as TransactionStatusResult, W as GuardianApprovalStatusResult, X as ServerDestinationsQuery, c as DestinationsResult, Y as PhoneShareContact, Z as PhoneShareInitiateResult, _ as PhoneShareApproveInput, $ as PhoneShareApproveResult, a0 as PhoneShareStatusResult } from './types-DTAmriOB.js';
2
- export { a1 as CurrencyBalance, f as DestinationGame, a2 as InboundPendingItem, g as InvoErrorInfo, h as InvoHooks, i as InvoRequestInfo, j as InvoResponseInfo, a3 as LinkedIdentityEmail, R as Rail, V as VerificationMethod } from './types-DTAmriOB.js';
1
+ 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, M as SmsVerifyResult, N as ClaimTransferInput, Q as ClaimResult, T as ClaimCurrencyInput, U as TransactionStatusResult, W as GuardianApprovalStatusResult, X as ServerDestinationsQuery, c as DestinationsResult, Y as PhoneShareContact, Z as PhoneShareInitiateResult, _ as PhoneShareApproveInput, $ as PhoneShareApproveResult, a0 as PhoneShareStatusResult } from './types-bp0UtN_N.js';
2
+ export { a1 as CurrencyBalance, f as DestinationGame, a2 as InboundPendingItem, g as InvoErrorInfo, h as InvoHooks, i as InvoRequestInfo, j as InvoResponseInfo, a3 as LinkedIdentityEmail, R as Rail, V as VerificationMethod } from './types-bp0UtN_N.js';
3
3
 
4
4
  interface VerifyWebhookOptions {
5
5
  /** Max age of the signed timestamp, in seconds. Default 300 (5 min). */
@@ -149,9 +149,26 @@ declare class InvoServer {
149
149
  private readonly http;
150
150
  private readonly auth;
151
151
  constructor(config: ServerConfig);
152
- /** Mint a short-lived, game-scoped player token to hand to the browser InvoClient. */
152
+ /**
153
+ * Mint a short-lived, game-scoped player token to hand to the browser InvoClient.
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.
162
+ *
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).
168
+ */
153
169
  mintPlayerToken(input: {
154
170
  playerEmail: string;
171
+ playerPhone: string;
155
172
  }, opts?: CallOptions): Promise<PlayerToken>;
156
173
  /** Initiate a cross-game currency SEND. Inspect result.verificationMethod. */
157
174
  initiateSend(input: InitiateSendInput, opts?: CallOptions): Promise<InitiateResult>;
package/dist/server.js CHANGED
@@ -1,5 +1,5 @@
1
- import { InvoError, assertSecureBaseUrl, Http, toDestinationsResult } from './chunk-P65XQ6VF.js';
2
- export { InvoError } from './chunk-P65XQ6VF.js';
1
+ import { InvoError, assertSecureBaseUrl, Http, toDestinationsResult } from './chunk-6XCI53XJ.js';
2
+ export { InvoError } from './chunk-6XCI53XJ.js';
3
3
  import { createHmac } from 'crypto';
4
4
 
5
5
  var DEFAULT_TOLERANCE_SEC = 300;
@@ -161,7 +161,7 @@ async function hmacHexSubtle(secret, message) {
161
161
  }
162
162
 
163
163
  // src/server.ts
164
- var DEFAULT_UA = "invonetwork-web-sdk/1.2.0 (+https://invo.network)";
164
+ var DEFAULT_UA = "invonetwork-web-sdk/2.0.0 (+https://invo.network)";
165
165
  var MAX_USD_AMOUNT = 999.99;
166
166
  var MAX_ITEM_PRICE = 999999.99;
167
167
  function invalidInput(label, value, why) {
@@ -193,6 +193,12 @@ function parseMoney(value, max, label) {
193
193
  function assertUsdAmount(usdAmount) {
194
194
  parseMoney(usdAmount, MAX_USD_AMOUNT, "usdAmount");
195
195
  }
196
+ var E164 = /^\+[1-9]\d{1,14}$/;
197
+ function assertE164(value, label) {
198
+ if (typeof value !== "string" || !E164.test(value)) {
199
+ throw invalidInput(label, value, 'must be an E.164 phone number, e.g. "+15555550100"');
200
+ }
201
+ }
196
202
  function toOrderDetails(raw) {
197
203
  return {
198
204
  order: raw["order"] ?? {},
@@ -333,14 +339,31 @@ var InvoServer = class {
333
339
  });
334
340
  this.auth = { kind: "game-secret", secret: config.gameSecret };
335
341
  }
336
- /** Mint a short-lived, game-scoped player token to hand to the browser InvoClient. */
342
+ /**
343
+ * Mint a short-lived, game-scoped player token to hand to the browser InvoClient.
344
+ *
345
+ * This is the player REGISTRATION call: the network identity is derived from
346
+ * `email + phone` TOGETHER, so both are required. Registering email-only and
347
+ * attaching the phone later changes the identity and forces device re-enrollment —
348
+ * collect the phone before the first mint. `playerPhone` must be E.164
349
+ * (e.g. "+15555550100"); incoming cross-game transfers and the account-linking
350
+ * consent SMS are both matched by phone, so an account without one can't receive
351
+ * either.
352
+ *
353
+ * If the phone already belongs to another INVO account (same person, new email),
354
+ * this throws an InvoError with `isPhoneShareApprovalRequired` — NOT a failure:
355
+ * the phone holder was sent a consent SMS. Surface "pending approval" to the user,
356
+ * then re-issue the same call once approved (poll `phoneShareStatus`, or use
357
+ * `phoneShareInitiate`/`phoneShareApprove` for the in-app OTP fallback).
358
+ */
337
359
  async mintPlayerToken(input, opts) {
338
360
  if (typeof input.playerEmail !== "string" || !input.playerEmail.trim()) {
339
361
  throw invalidInput("playerEmail", input.playerEmail, "is required");
340
362
  }
363
+ assertE164(input.playerPhone, "playerPhone");
341
364
  const raw = await this.http.post(
342
365
  "/api/sdk/player-token",
343
- { player_email: input.playerEmail },
366
+ { player_email: input.playerEmail, player_phone: input.playerPhone },
344
367
  this.auth,
345
368
  { idempotent: true, signal: opts?.signal }
346
369
  // safe to retry: re-mint just issues a fresh token
@@ -37,8 +37,17 @@ declare class InvoError extends Error {
37
37
  * is a rate-limit, not a top-up condition) is NOT misclassified as this.
38
38
  */
39
39
  get isInsufficientBalance(): boolean;
40
- /** True if a claim needs phone-share approval before it can complete (claim → 409). */
40
+ /**
41
+ * True if the call needs phone-share approval before it can complete (409). Raised by
42
+ * registration/token-mint and by claims when the phone already belongs to another INVO
43
+ * account (same person, new email — expected, not a failure). The phone holder gets a
44
+ * consent SMS; show "pending approval", then re-issue the identical call once approved
45
+ * (poll `phoneShareStatus`, or use `phoneShareInitiate`/`phoneShareApprove` for the OTP
46
+ * fallback). `phoneShareApprovalId` carries the id from the 409 body.
47
+ */
41
48
  get isPhoneShareApprovalRequired(): boolean;
49
+ /** The `approval_id` from a phone-share 409 body, for `phoneShareApprove`. */
50
+ get phoneShareApprovalId(): string | undefined;
42
51
  /** True if the phone-share (phone, requesting_email) pair was already approved. */
43
52
  get isPhoneShareAlreadyApproved(): boolean;
44
53
  /** True if an idempotency-keyed request was a duplicate (item purchase → 409). */
@@ -37,8 +37,17 @@ declare class InvoError extends Error {
37
37
  * is a rate-limit, not a top-up condition) is NOT misclassified as this.
38
38
  */
39
39
  get isInsufficientBalance(): boolean;
40
- /** True if a claim needs phone-share approval before it can complete (claim → 409). */
40
+ /**
41
+ * True if the call needs phone-share approval before it can complete (409). Raised by
42
+ * registration/token-mint and by claims when the phone already belongs to another INVO
43
+ * account (same person, new email — expected, not a failure). The phone holder gets a
44
+ * consent SMS; show "pending approval", then re-issue the identical call once approved
45
+ * (poll `phoneShareStatus`, or use `phoneShareInitiate`/`phoneShareApprove` for the OTP
46
+ * fallback). `phoneShareApprovalId` carries the id from the 409 body.
47
+ */
41
48
  get isPhoneShareApprovalRequired(): boolean;
49
+ /** The `approval_id` from a phone-share 409 body, for `phoneShareApprove`. */
50
+ get phoneShareApprovalId(): string | undefined;
42
51
  /** True if the phone-share (phone, requesting_email) pair was already approved. */
43
52
  get isPhoneShareAlreadyApproved(): boolean;
44
53
  /** True if an idempotency-keyed request was a duplicate (item purchase → 409). */
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@invonetwork/web-sdk",
3
- "version": "1.2.0",
3
+ "version": "2.0.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,