@invonetwork/web-sdk 1.2.1 → 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,31 @@ 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
+
7
32
  ## [1.2.1] — 2026-07-01
8
33
 
9
34
  **Fix — browser "Illegal invocation".** The SDK invoked its fetch as `this.fetchImpl(...)`,
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:
@@ -129,6 +150,7 @@ The WebAuthn ceremony still runs in the browser (it must — it's `navigator.cre
129
150
  INVO enables each flow for your tenant in the [console](#get-your-account--game-secret-invo-console). What you need to do:
130
151
 
131
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)).
132
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.)
133
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.)
134
156
  - **For currency purchase:** card checkout works out of the box; ask INVO to enable the `game`/`steam` rails if you need them.
@@ -351,7 +373,10 @@ try {
351
373
 
352
374
  **"You have X to collect"**
353
375
 
354
- - **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).
355
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).
356
381
 
357
382
  ---
@@ -524,7 +549,7 @@ try {
524
549
 
525
550
  | Method | Returns |
526
551
  |---|---|
527
- | `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)) |
528
553
  | `initiateSend(input)` | `{ transactionId, verificationMethod, guardianApproval?, raw }` |
529
554
  | `initiateTransfer(input)` | `{ transactionId, verificationMethod, guardianApproval?, raw }` |
530
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";
@@ -308,5 +320,5 @@ function toDestinationsResult(raw, direction) {
308
320
  }
309
321
 
310
322
  export { Http, InvoError, assertSecureBaseUrl, toDestinationsResult };
311
- //# sourceMappingURL=chunk-U3EDJUQI.js.map
312
- //# sourceMappingURL=chunk-U3EDJUQI.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";
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-U3EDJUQI.js';
2
- export { InvoError } from './chunk-U3EDJUQI.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";
@@ -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.1 (+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-U3EDJUQI.js';
2
- export { InvoError } from './chunk-U3EDJUQI.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.1 (+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.1",
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,