@invonetwork/web-sdk 1.2.1 → 2.1.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,56 @@ 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.1.0] — 2026-07-02
8
+
9
+ **Passkey recovery ("lost or replaced my passkey").** Deleting a passkey on the device never
10
+ tells the server the key is gone, so re-enrollment was dead-ended by the anti-takeover gate
11
+ (`ENROLLMENT_REQUIRES_PROOF`) with nothing left to prove possession with. The backend shipped
12
+ a self-serve, possession-proofed recovery flow; this release wires the client side.
13
+
14
+ - `InvoClient.recoveryBegin()` — sends a one-time code to the phone/email on file
15
+ (`{ status: "sent", channels }`); `InvoClient.recoveryComplete(code)` — deactivates the
16
+ stale server-side passkey and authorizes a fresh enrollment
17
+ (`{ status: "recovered", deactivatedCount, next }`). Then retry the same `enrollPasskey()`.
18
+ - New `InvoError` classifiers: `isEnrollmentCodeInvalid`, `isPasskeyRecoveryCooldown`, and
19
+ `retryAfterAt` (the ISO timestamp on the 403 cooldown — distinct from the numeric
20
+ `retryAfter` throttle field). Bare `no_channel_on_file` / `rate_limited` error tokens are
21
+ now promoted to `err.code`.
22
+ - **24-hour money cooldown surfaced:** a recovery-enrolled passkey logs in and collects
23
+ funds immediately, but `approveSend`/`approveTransfer` throw 403
24
+ `PASSKEY_RECOVERY_COOLDOWN` for 24h (SIM-swap protection). Branch on
25
+ `isPasskeyRecoveryCooldown`, show the pause message with `retryAfterAt`, don't retry-loop.
26
+ - README: recovery subsection under Passkeys, incl. the password-manager cleanup tip for
27
+ "there is a problem saving your passkey" (stale orphan entry).
28
+
29
+ Additive, no breaking changes. Routes require SDK verification enabled for the tenant
30
+ (dark 503 otherwise).
31
+
32
+ ## [2.0.0] — 2026-07-02
33
+
34
+ **BREAKING — `mintPlayerToken` now requires `playerPhone` (E.164).** Requested by the INVO
35
+ backend after a live incident: a player registered email-only couldn't receive a cross-game
36
+ transfer (incoming transfers are matched by phone) and never got the account-linking consent
37
+ SMS (also phone-triggered). The network identity is derived from **email + phone together**,
38
+ so the phone must be present on the FIRST registration call — attaching it later changes the
39
+ identity and forces device re-enrollment.
40
+
41
+ - `mintPlayerToken({ playerEmail, playerPhone })` — `playerPhone` is required and validated
42
+ as E.164 (`+15555550100`: leading `+`, country code, digits only) before any network call;
43
+ the body now posts `player_phone` alongside `player_email`.
44
+ - **Pending approval is surfaced, not an error to swallow:** minting with a phone that
45
+ already belongs to another INVO account (same person, new email) throws the existing
46
+ `isPhoneShareApprovalRequired` 409 — the phone holder got a consent SMS. New
47
+ `InvoError.phoneShareApprovalId` exposes the `approval_id` from the 409 body for the
48
+ `phoneShareApprove` OTP fallback. Docs updated to cover the registration path (previously
49
+ documented for claims only).
50
+ - README: new "Player registration (email + phone, required)" section; examples updated
51
+ (`proxy-server.ts` token route now rejects a phoneless actor with a clear 400).
52
+
53
+ **Migration:** collect the player's phone in your enrollment UI before the first
54
+ `mintPlayerToken` call and pass it as `playerPhone` in E.164. Handle the
55
+ `isPhoneShareApprovalRequired` error as a "pending approval" UI state.
56
+
7
57
  ## [1.2.1] — 2026-07-01
8
58
 
9
59
  **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.1.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. **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`).
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
@@ -28,7 +28,7 @@ The **game secret stays on your server**; the browser only ever holds a short-li
28
28
  - [Item purchase (spend game currency)](#item-purchase-spend-game-currency)
29
29
  - [Player balance](#player-balance)
30
30
  - [Sends & transfers (move currency between players)](#sends--transfers-move-currency-between-players)
31
- - [Passkeys (enroll, approve, link)](#passkeys-enroll-approve-link)
31
+ - [Passkeys (enroll, approve, link, recover)](#passkeys-enroll-approve-link-recover)
32
32
  - [Webhooks](#webhooks)
33
33
  - [Resilience & observability](#resilience--observability)
34
34
  - [Errors](#errors)
@@ -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:
@@ -122,13 +143,14 @@ The WebAuthn ceremony still runs in the browser (it must — it's `navigator.cre
122
143
  - **Real partner** (one login = one player) — derive the acting player from your **session**.
123
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.
124
145
 
125
- > **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).
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-recover).
126
147
 
127
148
  ## Before you go live
128
149
 
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,12 +373,15 @@ 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
  ---
358
383
 
359
- ## Passkeys (enroll, approve, link)
384
+ ## Passkeys (enroll, approve, link, recover)
360
385
 
361
386
  Passkeys (WebAuthn) replace the SMS PIN for approving sends/transfers. The browser SDK wraps `navigator.credentials.create/get`, base64url encoding, challenge round-trips, and error mapping.
362
387
 
@@ -391,6 +416,39 @@ try {
391
416
  }
392
417
  ```
393
418
 
419
+ ### Lost or replaced passkey (recovery)
420
+
421
+ Deleting a passkey on the device **never tells the server the key is gone**, so the next
422
+ `enrollPasskey()` is blocked by the anti-takeover gate with `ENROLLMENT_REQUIRES_PROOF` —
423
+ and the player has nothing left to prove possession with. Offer a **"Lost or replaced your
424
+ passkey?"** action that runs the possession-proofed recovery flow:
425
+
426
+ ```ts
427
+ try {
428
+ await client.enrollPasskey();
429
+ } catch (e) {
430
+ if (e instanceof InvoError && e.isEnrollmentProofRequired) {
431
+ // Player still HAS the other method → linkDevice (above). Lost/deleted it → recover:
432
+ await client.recoveryBegin(); // → { status:"sent", channels:["sms","email"] }
433
+ await client.recoveryComplete(codeFromUser); // → { status:"recovered", deactivatedCount }
434
+ await client.enrollPasskey(); // same call — now succeeds
435
+ } else throw e;
436
+ }
437
+ ```
438
+
439
+ - `recoveryBegin()` errors: `no_channel_on_file` (422), `rate_limited` (429 — max 5 codes / 10 min).
440
+ - `recoveryComplete(code)` errors: `ENROLLMENT_CODE_INVALID` (wrong/expired, attempt-capped — let the user retry or resend), `RECOVERY_FAILED` (500, transient).
441
+ - A recovery also sends the owner an out-of-band "your passkey was reset" SMS/email — that's the intended tamper alert; surface nothing special.
442
+ - If the **OS fails to save** a new passkey ("there is a problem saving your passkey"), have the user delete the stale entry in their password manager first (iPhone: Settings → Passwords; Android: Google Password Manager; Windows: Settings → Accounts → Passkeys).
443
+
444
+ > ⚠️ **24-hour money cooldown after recovery.** A recovery-enrolled passkey logs in and
445
+ > **collects funds immediately**, but `approveSend`/`approveTransfer` return **403
446
+ > `PASSKEY_RECOVERY_COOLDOWN`** for 24 hours (SIM-swap protection). Branch on
447
+ > `err.isPasskeyRecoveryCooldown` and show — *"For your security, transfers are paused for
448
+ > 24 hours after a passkey reset. You can still receive funds. Try again after
449
+ > `err.retryAfterAt`."* — do **not** treat it as a generic failure or retry-loop it.
450
+ > Unaffected: login, `getPendingCollect`, inbound `confirmReceipt*`.
451
+
394
452
  - **User verification is required** on every approve/claim (a missing-UV assertion fails closed).
395
453
  - Challenges are single-use and bound to `{flow}:{transactionId}`.
396
454
  - The SDK passes the backend's WebAuthn options through unchanged (it does not hard-code `pubKeyCredParams`/`timeout`/`attestation`).
@@ -503,7 +561,7 @@ Helpers:
503
561
  | `.isPhoneShareApprovalRequired` | a new-account phone needs owner approval → run the `phoneShare*` handshake, then retry |
504
562
  | `.isPhoneShareAlreadyApproved` | phone-share was already approved (e.g. from a `/reject`) |
505
563
 
506
- Client-side guards (bad amount, missing idempotency key, `rail:"steam"` on `purchaseCurrency`, item validation) throw `InvoError` with `.status === 0` **before** any network call. Notable backend codes: `SDK_TOKEN_EXPIRED`, `TENANT_NOT_MIGRATED`, `WEBAUTHN_NOT_ENABLED_FOR_TENANT`, `WEBAUTHN_UV_REQUIRED`, `ENROLLMENT_REQUIRES_PROOF`, `WRONG_RAIL_ENDPOINT`, `flow_paused`.
564
+ 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`.
507
565
 
508
566
  ```ts
509
567
  import { InvoError } from "@invonetwork/web-sdk"; // or "@invonetwork/web-sdk/server"
@@ -524,7 +582,7 @@ try {
524
582
 
525
583
  | Method | Returns |
526
584
  |---|---|
527
- | `mintPlayerToken({ playerEmail })` | `{ token, expiresAt, identityId }` |
585
+ | `mintPlayerToken({ playerEmail, playerPhone })` | `{ token, expiresAt, identityId }` — **both required**; `playerPhone` must be E.164 (see [Player registration](#player-registration-email--phone-required)) |
528
586
  | `initiateSend(input)` | `{ transactionId, verificationMethod, guardianApproval?, raw }` |
529
587
  | `initiateTransfer(input)` | `{ transactionId, verificationMethod, guardianApproval?, raw }` |
530
588
  | `createCheckout(input)` | `{ sessionId, checkoutUrl, expiresAt, raw }` |
@@ -556,6 +614,7 @@ Every method also accepts an optional final `{ signal }` (`AbortSignal`) for can
556
614
  |---|---|
557
615
  | `enrollPasskey()` | `{ status, device, raw }` |
558
616
  | `enrollmentBegin()` / `enrollmentVerify(code)` | OTP grant for `ENROLLMENT_REQUIRES_AUTHORIZATION` (then retry `enrollPasskey`) |
617
+ | `recoveryBegin()` / `recoveryComplete(code)` | passkey recovery for `ENROLLMENT_REQUIRES_PROOF` when the passkey was lost/deleted (then retry `enrollPasskey`) — recovered keys can't move money OUT for 24h (`PASSKEY_RECOVERY_COOLDOWN`) |
559
618
  | `approveSend(txnId)` / `approveTransfer(txnId)` | `{ status, next, transactionId, claimCode?, claimCodeExpiresAt?, holdReason?, risk?, guardianApproval?, pollEndpoint?, raw }` |
560
619
  | `confirmReceiptSend(txnId)` / `confirmReceiptTransfer(txnId)` | `{ status, holdReason?, raw }` |
561
620
  | `linkDevice(linkId)` | `{ status, raw }` |
@@ -21,10 +21,35 @@ var InvoError = class _InvoError extends Error {
21
21
  get isEnrollmentAuthorizationRequired() {
22
22
  return this.code === "ENROLLMENT_REQUIRES_AUTHORIZATION";
23
23
  }
24
- /** True if enrolling is blocked because another method exists — use `linkDevice`. */
24
+ /**
25
+ * True if enrolling is blocked because the identity already has an enrolled method
26
+ * (anti-takeover gate, register/complete → 409). Two ways forward: `linkDevice` when
27
+ * the player still HAS the other method, or the passkey-recovery flow
28
+ * (`recoveryBegin`/`recoveryComplete` — "Lost or replaced your passkey?") when they
29
+ * deleted/lost it — the server can't know a device-side passkey is gone.
30
+ */
25
31
  get isEnrollmentProofRequired() {
26
32
  return this.code === "ENROLLMENT_REQUIRES_PROOF";
27
33
  }
34
+ /** True if the recovery OTP was wrong or expired (attempt-capped) — let the user retry or resend. */
35
+ get isEnrollmentCodeInvalid() {
36
+ return this.code === "ENROLLMENT_CODE_INVALID";
37
+ }
38
+ /**
39
+ * True if a money-OUT approve was refused because the passkey was enrolled via
40
+ * recovery less than 24h ago (SIM-swap protection, approve → 403). NOT a generic
41
+ * failure — do not retry-loop. Login and inbound confirm-receipt (collecting money)
42
+ * still work. Show: "For your security, transfers are paused for 24 hours after a
43
+ * passkey reset. You can still receive funds. Try again after {retryAfterAt}."
44
+ */
45
+ get isPasskeyRecoveryCooldown() {
46
+ return this.code === "PASSKEY_RECOVERY_COOLDOWN";
47
+ }
48
+ /** The ISO timestamp when a `PASSKEY_RECOVERY_COOLDOWN` lifts (`retry_after`), when present. */
49
+ get retryAfterAt() {
50
+ const v = this.bodyObject()["retry_after"];
51
+ return typeof v === "string" && v && Number.isNaN(Number(v)) ? v : void 0;
52
+ }
28
53
  /**
29
54
  * True if an item purchase failed because the player's balance was too low (§4.8 → 400).
30
55
  * The backend carries `required_amount` + `current_balance` on the body for the UI.
@@ -36,10 +61,22 @@ var InvoError = class _InvoError extends Error {
36
61
  const b = this.bodyObject();
37
62
  return this.code === "INSUFFICIENT_BALANCE" || "required_amount" in b || /insufficient[_ ]balance/i.test(this.message);
38
63
  }
39
- /** True if a claim needs phone-share approval before it can complete (claim → 409). */
64
+ /**
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.
71
+ */
40
72
  get isPhoneShareApprovalRequired() {
41
73
  return this.code === "PHONE_SHARE_APPROVAL_REQUIRED";
42
74
  }
75
+ /** The `approval_id` from a phone-share 409 body, for `phoneShareApprove`. */
76
+ get phoneShareApprovalId() {
77
+ const v = this.bodyObject()["approval_id"];
78
+ return typeof v === "string" && v ? v : void 0;
79
+ }
43
80
  /** True if the phone-share (phone, requesting_email) pair was already approved. */
44
81
  get isPhoneShareAlreadyApproved() {
45
82
  return this.code === "PHONE_SHARE_ALREADY_APPROVED";
@@ -69,7 +106,9 @@ function errorFromResponse(status, body, requestId) {
69
106
  else if (typeof b["error_code"] === "string") code = b["error_code"];
70
107
  if (typeof b["error"] === "string") message = b["error"];
71
108
  else if (typeof b["message"] === "string") message = b["message"];
72
- if (!code && typeof b["error"] === "string" && /^(flow_paused|spending_limit_exceeded|receiver_not_enrolled_use_claim_code)$/.test(b["error"])) {
109
+ if (!code && typeof b["error"] === "string" && /^(flow_paused|spending_limit_exceeded|receiver_not_enrolled_use_claim_code|no_channel_on_file|rate_limited)$/.test(
110
+ b["error"]
111
+ )) {
73
112
  code = b["error"];
74
113
  }
75
114
  } else if (typeof body === "string" && body.trim()) {
@@ -308,5 +347,5 @@ function toDestinationsResult(raw, direction) {
308
347
  }
309
348
 
310
349
  export { Http, InvoError, assertSecureBaseUrl, toDestinationsResult };
311
- //# sourceMappingURL=chunk-U3EDJUQI.js.map
312
- //# sourceMappingURL=chunk-U3EDJUQI.js.map
350
+ //# sourceMappingURL=chunk-YCEW7NC3.js.map
351
+ //# sourceMappingURL=chunk-YCEW7NC3.js.map
package/dist/index.cjs CHANGED
@@ -23,10 +23,35 @@ var InvoError = class _InvoError extends Error {
23
23
  get isEnrollmentAuthorizationRequired() {
24
24
  return this.code === "ENROLLMENT_REQUIRES_AUTHORIZATION";
25
25
  }
26
- /** True if enrolling is blocked because another method exists — use `linkDevice`. */
26
+ /**
27
+ * True if enrolling is blocked because the identity already has an enrolled method
28
+ * (anti-takeover gate, register/complete → 409). Two ways forward: `linkDevice` when
29
+ * the player still HAS the other method, or the passkey-recovery flow
30
+ * (`recoveryBegin`/`recoveryComplete` — "Lost or replaced your passkey?") when they
31
+ * deleted/lost it — the server can't know a device-side passkey is gone.
32
+ */
27
33
  get isEnrollmentProofRequired() {
28
34
  return this.code === "ENROLLMENT_REQUIRES_PROOF";
29
35
  }
36
+ /** True if the recovery OTP was wrong or expired (attempt-capped) — let the user retry or resend. */
37
+ get isEnrollmentCodeInvalid() {
38
+ return this.code === "ENROLLMENT_CODE_INVALID";
39
+ }
40
+ /**
41
+ * True if a money-OUT approve was refused because the passkey was enrolled via
42
+ * recovery less than 24h ago (SIM-swap protection, approve → 403). NOT a generic
43
+ * failure — do not retry-loop. Login and inbound confirm-receipt (collecting money)
44
+ * still work. Show: "For your security, transfers are paused for 24 hours after a
45
+ * passkey reset. You can still receive funds. Try again after {retryAfterAt}."
46
+ */
47
+ get isPasskeyRecoveryCooldown() {
48
+ return this.code === "PASSKEY_RECOVERY_COOLDOWN";
49
+ }
50
+ /** The ISO timestamp when a `PASSKEY_RECOVERY_COOLDOWN` lifts (`retry_after`), when present. */
51
+ get retryAfterAt() {
52
+ const v = this.bodyObject()["retry_after"];
53
+ return typeof v === "string" && v && Number.isNaN(Number(v)) ? v : void 0;
54
+ }
30
55
  /**
31
56
  * True if an item purchase failed because the player's balance was too low (§4.8 → 400).
32
57
  * The backend carries `required_amount` + `current_balance` on the body for the UI.
@@ -38,10 +63,22 @@ var InvoError = class _InvoError extends Error {
38
63
  const b = this.bodyObject();
39
64
  return this.code === "INSUFFICIENT_BALANCE" || "required_amount" in b || /insufficient[_ ]balance/i.test(this.message);
40
65
  }
41
- /** True if a claim needs phone-share approval before it can complete (claim → 409). */
66
+ /**
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.
73
+ */
42
74
  get isPhoneShareApprovalRequired() {
43
75
  return this.code === "PHONE_SHARE_APPROVAL_REQUIRED";
44
76
  }
77
+ /** The `approval_id` from a phone-share 409 body, for `phoneShareApprove`. */
78
+ get phoneShareApprovalId() {
79
+ const v = this.bodyObject()["approval_id"];
80
+ return typeof v === "string" && v ? v : void 0;
81
+ }
45
82
  /** True if the phone-share (phone, requesting_email) pair was already approved. */
46
83
  get isPhoneShareAlreadyApproved() {
47
84
  return this.code === "PHONE_SHARE_ALREADY_APPROVED";
@@ -71,7 +108,9 @@ function errorFromResponse(status, body, requestId) {
71
108
  else if (typeof b["error_code"] === "string") code = b["error_code"];
72
109
  if (typeof b["error"] === "string") message = b["error"];
73
110
  else if (typeof b["message"] === "string") message = b["message"];
74
- if (!code && typeof b["error"] === "string" && /^(flow_paused|spending_limit_exceeded|receiver_not_enrolled_use_claim_code)$/.test(b["error"])) {
111
+ if (!code && typeof b["error"] === "string" && /^(flow_paused|spending_limit_exceeded|receiver_not_enrolled_use_claim_code|no_channel_on_file|rate_limited)$/.test(
112
+ b["error"]
113
+ )) {
75
114
  code = b["error"];
76
115
  }
77
116
  } else if (typeof body === "string" && body.trim()) {
@@ -440,7 +479,12 @@ var InvoClient = class {
440
479
  throw new Error("WebAuthn is not available in this environment (browser required).");
441
480
  }
442
481
  }
443
- /** Enroll a passkey for the token's identity (register/begin -> create() -> register/complete). */
482
+ /**
483
+ * Enroll a passkey for the token's identity (register/begin -> create() -> register/complete).
484
+ * Gates: `ENROLLMENT_REQUIRES_AUTHORIZATION` → {@link enrollmentBegin} OTP grant;
485
+ * `ENROLLMENT_REQUIRES_PROOF` → {@link linkDevice}, or {@link recoveryBegin} when the
486
+ * player lost/deleted the old passkey ("Lost or replaced your passkey?").
487
+ */
444
488
  async enrollPasskey(opts) {
445
489
  this.assertWebAuthn();
446
490
  const signal = opts?.signal;
@@ -569,7 +613,9 @@ var InvoClient = class {
569
613
  * this to send a 6-digit code to the player's phone + email on file, collect the code,
570
614
  * call `enrollmentVerify(code)`, then RETRY the SAME `enrollPasskey()` —
571
615
  * `register/complete` auto-consumes the server-side grant (30-min TTL). For
572
- * `ENROLLMENT_REQUIRES_PROOF` (`err.isEnrollmentProofRequired`) use `linkDevice` instead.
616
+ * `ENROLLMENT_REQUIRES_PROOF` (`err.isEnrollmentProofRequired`) use `linkDevice`
617
+ * (player still has the other method) or `recoveryBegin`/`recoveryComplete`
618
+ * (player lost/deleted their passkey).
573
619
  */
574
620
  async enrollmentBegin(opts) {
575
621
  return this.withTokenRetry(async () => {
@@ -597,6 +643,65 @@ var InvoClient = class {
597
643
  return { status: String(raw["status"] ?? ""), raw };
598
644
  });
599
645
  }
646
+ /**
647
+ * Passkey recovery — "Lost or replaced your passkey?". Deleting a passkey on the
648
+ * device never tells the server the key is gone, so the next `enrollPasskey()` is
649
+ * blocked by the anti-takeover gate with `ENROLLMENT_REQUIRES_PROOF`
650
+ * (`err.isEnrollmentProofRequired`). When the player can't prove the old method
651
+ * (they deleted/lost it — otherwise prefer `linkDevice`), run:
652
+ *
653
+ * 1. `recoveryBegin()` — sends a one-time code to the phone/email on file
654
+ * (422 `no_channel_on_file`, 429 `rate_limited` at 5/10min).
655
+ * 2. `recoveryComplete(code)` — deactivates the stale server-side passkey and
656
+ * authorizes a fresh enrollment (400 `ENROLLMENT_CODE_INVALID` on a wrong/
657
+ * expired code — attempt-capped; let the user retry or resend).
658
+ * 3. Immediately retry the SAME `enrollPasskey()` — it now succeeds.
659
+ *
660
+ * The owner also gets an out-of-band "your passkey was reset" SMS/email — that's
661
+ * the intended tamper alert; surface nothing special for it.
662
+ *
663
+ * ⚠ 24-HOUR MONEY COOLDOWN: a recovery-enrolled passkey logs in and COLLECTS
664
+ * funds immediately, but `approveSend`/`approveTransfer` throw
665
+ * `PASSKEY_RECOVERY_COOLDOWN` (403; `err.isPasskeyRecoveryCooldown`,
666
+ * `err.retryAfterAt`) for 24h — SIM-swap protection. Show the pause message with
667
+ * the timestamp; do not retry-loop it.
668
+ *
669
+ * If the OS itself fails to SAVE a new passkey ("there is a problem saving your
670
+ * passkey"), have the user delete the stale entry in their password manager first
671
+ * (iPhone: Settings → Passwords; Android: Google Password Manager; Windows:
672
+ * Settings → Accounts → Passkeys).
673
+ */
674
+ async recoveryBegin(opts) {
675
+ return this.withTokenRetry(async () => {
676
+ const raw = await this.post(
677
+ "/api/sdk/device/recover/begin",
678
+ void 0,
679
+ opts?.signal
680
+ );
681
+ return {
682
+ status: String(raw["status"] ?? ""),
683
+ channels: Array.isArray(raw["channels"]) ? raw["channels"] : [],
684
+ raw
685
+ };
686
+ });
687
+ }
688
+ /** Verify the recovery code (see {@link recoveryBegin}); on success, call `enrollPasskey()`. */
689
+ async recoveryComplete(code, opts) {
690
+ if (!code) throw new Error("recoveryComplete requires the one-time `code`.");
691
+ return this.withTokenRetry(async () => {
692
+ const raw = await this.post(
693
+ "/api/sdk/device/recover/complete",
694
+ { code },
695
+ opts?.signal
696
+ );
697
+ return {
698
+ status: String(raw["status"] ?? ""),
699
+ deactivatedCount: Number(raw["deactivated_count"] ?? 0),
700
+ next: typeof raw["next"] === "string" ? raw["next"] : void 0,
701
+ raw
702
+ };
703
+ });
704
+ }
600
705
  // --- internals ---
601
706
  /** POST with the current player token. Token-expiry retry is handled one level
602
707
  * up by withTokenRetry (which re-runs the whole ceremony, not a single call). */
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, R as RecoveryBeginResult, e as RecoveryCompleteResult } from './types-DtihCpOj.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-DtihCpOj.cjs';
3
3
 
4
4
  declare class InvoClient {
5
5
  private readonly http;
@@ -9,7 +9,12 @@ declare class InvoClient {
9
9
  private refreshInFlight;
10
10
  constructor(config: ClientConfig);
11
11
  private assertWebAuthn;
12
- /** Enroll a passkey for the token's identity (register/begin -> create() -> register/complete). */
12
+ /**
13
+ * Enroll a passkey for the token's identity (register/begin -> create() -> register/complete).
14
+ * Gates: `ENROLLMENT_REQUIRES_AUTHORIZATION` → {@link enrollmentBegin} OTP grant;
15
+ * `ENROLLMENT_REQUIRES_PROOF` → {@link linkDevice}, or {@link recoveryBegin} when the
16
+ * player lost/deleted the old passkey ("Lost or replaced your passkey?").
17
+ */
13
18
  enrollPasskey(opts?: CallOptions): Promise<{
14
19
  status: string;
15
20
  device: unknown;
@@ -58,11 +63,44 @@ declare class InvoClient {
58
63
  * this to send a 6-digit code to the player's phone + email on file, collect the code,
59
64
  * call `enrollmentVerify(code)`, then RETRY the SAME `enrollPasskey()` —
60
65
  * `register/complete` auto-consumes the server-side grant (30-min TTL). For
61
- * `ENROLLMENT_REQUIRES_PROOF` (`err.isEnrollmentProofRequired`) use `linkDevice` instead.
66
+ * `ENROLLMENT_REQUIRES_PROOF` (`err.isEnrollmentProofRequired`) use `linkDevice`
67
+ * (player still has the other method) or `recoveryBegin`/`recoveryComplete`
68
+ * (player lost/deleted their passkey).
62
69
  */
63
70
  enrollmentBegin(opts?: CallOptions): Promise<EnrollmentBeginResult>;
64
71
  /** Verify the enrollment OTP (see {@link enrollmentBegin}); on success, retry `enrollPasskey()`. */
65
72
  enrollmentVerify(code: string, opts?: CallOptions): Promise<EnrollmentVerifyResult>;
73
+ /**
74
+ * Passkey recovery — "Lost or replaced your passkey?". Deleting a passkey on the
75
+ * device never tells the server the key is gone, so the next `enrollPasskey()` is
76
+ * blocked by the anti-takeover gate with `ENROLLMENT_REQUIRES_PROOF`
77
+ * (`err.isEnrollmentProofRequired`). When the player can't prove the old method
78
+ * (they deleted/lost it — otherwise prefer `linkDevice`), run:
79
+ *
80
+ * 1. `recoveryBegin()` — sends a one-time code to the phone/email on file
81
+ * (422 `no_channel_on_file`, 429 `rate_limited` at 5/10min).
82
+ * 2. `recoveryComplete(code)` — deactivates the stale server-side passkey and
83
+ * authorizes a fresh enrollment (400 `ENROLLMENT_CODE_INVALID` on a wrong/
84
+ * expired code — attempt-capped; let the user retry or resend).
85
+ * 3. Immediately retry the SAME `enrollPasskey()` — it now succeeds.
86
+ *
87
+ * The owner also gets an out-of-band "your passkey was reset" SMS/email — that's
88
+ * the intended tamper alert; surface nothing special for it.
89
+ *
90
+ * ⚠ 24-HOUR MONEY COOLDOWN: a recovery-enrolled passkey logs in and COLLECTS
91
+ * funds immediately, but `approveSend`/`approveTransfer` throw
92
+ * `PASSKEY_RECOVERY_COOLDOWN` (403; `err.isPasskeyRecoveryCooldown`,
93
+ * `err.retryAfterAt`) for 24h — SIM-swap protection. Show the pause message with
94
+ * the timestamp; do not retry-loop it.
95
+ *
96
+ * If the OS itself fails to SAVE a new passkey ("there is a problem saving your
97
+ * passkey"), have the user delete the stale entry in their password manager first
98
+ * (iPhone: Settings → Passwords; Android: Google Password Manager; Windows:
99
+ * Settings → Accounts → Passkeys).
100
+ */
101
+ recoveryBegin(opts?: CallOptions): Promise<RecoveryBeginResult>;
102
+ /** Verify the recovery code (see {@link recoveryBegin}); on success, call `enrollPasskey()`. */
103
+ recoveryComplete(code: string, opts?: CallOptions): Promise<RecoveryCompleteResult>;
66
104
  /** POST with the current player token. Token-expiry retry is handled one level
67
105
  * up by withTokenRetry (which re-runs the whole ceremony, not a single call). */
68
106
  private post;
@@ -81,4 +119,4 @@ declare class InvoClient {
81
119
  private confirmReceipt;
82
120
  }
83
121
 
84
- export { ApproveResult, BalanceResult, CallOptions, ClientConfig, ConfirmReceiptResult, DestinationsQuery, DestinationsResult, EnrollmentBeginResult, EnrollmentVerifyResult, InvoClient, LinkDeviceResult, PendingCollectResult };
122
+ export { ApproveResult, BalanceResult, CallOptions, ClientConfig, ConfirmReceiptResult, DestinationsQuery, DestinationsResult, EnrollmentBeginResult, EnrollmentVerifyResult, InvoClient, LinkDeviceResult, PendingCollectResult, RecoveryBeginResult, RecoveryCompleteResult };
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, R as RecoveryBeginResult, e as RecoveryCompleteResult } from './types-DtihCpOj.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-DtihCpOj.js';
3
3
 
4
4
  declare class InvoClient {
5
5
  private readonly http;
@@ -9,7 +9,12 @@ declare class InvoClient {
9
9
  private refreshInFlight;
10
10
  constructor(config: ClientConfig);
11
11
  private assertWebAuthn;
12
- /** Enroll a passkey for the token's identity (register/begin -> create() -> register/complete). */
12
+ /**
13
+ * Enroll a passkey for the token's identity (register/begin -> create() -> register/complete).
14
+ * Gates: `ENROLLMENT_REQUIRES_AUTHORIZATION` → {@link enrollmentBegin} OTP grant;
15
+ * `ENROLLMENT_REQUIRES_PROOF` → {@link linkDevice}, or {@link recoveryBegin} when the
16
+ * player lost/deleted the old passkey ("Lost or replaced your passkey?").
17
+ */
13
18
  enrollPasskey(opts?: CallOptions): Promise<{
14
19
  status: string;
15
20
  device: unknown;
@@ -58,11 +63,44 @@ declare class InvoClient {
58
63
  * this to send a 6-digit code to the player's phone + email on file, collect the code,
59
64
  * call `enrollmentVerify(code)`, then RETRY the SAME `enrollPasskey()` —
60
65
  * `register/complete` auto-consumes the server-side grant (30-min TTL). For
61
- * `ENROLLMENT_REQUIRES_PROOF` (`err.isEnrollmentProofRequired`) use `linkDevice` instead.
66
+ * `ENROLLMENT_REQUIRES_PROOF` (`err.isEnrollmentProofRequired`) use `linkDevice`
67
+ * (player still has the other method) or `recoveryBegin`/`recoveryComplete`
68
+ * (player lost/deleted their passkey).
62
69
  */
63
70
  enrollmentBegin(opts?: CallOptions): Promise<EnrollmentBeginResult>;
64
71
  /** Verify the enrollment OTP (see {@link enrollmentBegin}); on success, retry `enrollPasskey()`. */
65
72
  enrollmentVerify(code: string, opts?: CallOptions): Promise<EnrollmentVerifyResult>;
73
+ /**
74
+ * Passkey recovery — "Lost or replaced your passkey?". Deleting a passkey on the
75
+ * device never tells the server the key is gone, so the next `enrollPasskey()` is
76
+ * blocked by the anti-takeover gate with `ENROLLMENT_REQUIRES_PROOF`
77
+ * (`err.isEnrollmentProofRequired`). When the player can't prove the old method
78
+ * (they deleted/lost it — otherwise prefer `linkDevice`), run:
79
+ *
80
+ * 1. `recoveryBegin()` — sends a one-time code to the phone/email on file
81
+ * (422 `no_channel_on_file`, 429 `rate_limited` at 5/10min).
82
+ * 2. `recoveryComplete(code)` — deactivates the stale server-side passkey and
83
+ * authorizes a fresh enrollment (400 `ENROLLMENT_CODE_INVALID` on a wrong/
84
+ * expired code — attempt-capped; let the user retry or resend).
85
+ * 3. Immediately retry the SAME `enrollPasskey()` — it now succeeds.
86
+ *
87
+ * The owner also gets an out-of-band "your passkey was reset" SMS/email — that's
88
+ * the intended tamper alert; surface nothing special for it.
89
+ *
90
+ * ⚠ 24-HOUR MONEY COOLDOWN: a recovery-enrolled passkey logs in and COLLECTS
91
+ * funds immediately, but `approveSend`/`approveTransfer` throw
92
+ * `PASSKEY_RECOVERY_COOLDOWN` (403; `err.isPasskeyRecoveryCooldown`,
93
+ * `err.retryAfterAt`) for 24h — SIM-swap protection. Show the pause message with
94
+ * the timestamp; do not retry-loop it.
95
+ *
96
+ * If the OS itself fails to SAVE a new passkey ("there is a problem saving your
97
+ * passkey"), have the user delete the stale entry in their password manager first
98
+ * (iPhone: Settings → Passwords; Android: Google Password Manager; Windows:
99
+ * Settings → Accounts → Passkeys).
100
+ */
101
+ recoveryBegin(opts?: CallOptions): Promise<RecoveryBeginResult>;
102
+ /** Verify the recovery code (see {@link recoveryBegin}); on success, call `enrollPasskey()`. */
103
+ recoveryComplete(code: string, opts?: CallOptions): Promise<RecoveryCompleteResult>;
66
104
  /** POST with the current player token. Token-expiry retry is handled one level
67
105
  * up by withTokenRetry (which re-runs the whole ceremony, not a single call). */
68
106
  private post;
@@ -81,4 +119,4 @@ declare class InvoClient {
81
119
  private confirmReceipt;
82
120
  }
83
121
 
84
- export { ApproveResult, BalanceResult, CallOptions, ClientConfig, ConfirmReceiptResult, DestinationsQuery, DestinationsResult, EnrollmentBeginResult, EnrollmentVerifyResult, InvoClient, LinkDeviceResult, PendingCollectResult };
122
+ export { ApproveResult, BalanceResult, CallOptions, ClientConfig, ConfirmReceiptResult, DestinationsQuery, DestinationsResult, EnrollmentBeginResult, EnrollmentVerifyResult, InvoClient, LinkDeviceResult, PendingCollectResult, RecoveryBeginResult, RecoveryCompleteResult };
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-YCEW7NC3.js';
2
+ export { InvoError } from './chunk-YCEW7NC3.js';
3
3
 
4
4
  // src/shared/webauthn.ts
5
5
  function b64urlToBuffer(value) {
@@ -132,7 +132,12 @@ var InvoClient = class {
132
132
  throw new Error("WebAuthn is not available in this environment (browser required).");
133
133
  }
134
134
  }
135
- /** Enroll a passkey for the token's identity (register/begin -> create() -> register/complete). */
135
+ /**
136
+ * Enroll a passkey for the token's identity (register/begin -> create() -> register/complete).
137
+ * Gates: `ENROLLMENT_REQUIRES_AUTHORIZATION` → {@link enrollmentBegin} OTP grant;
138
+ * `ENROLLMENT_REQUIRES_PROOF` → {@link linkDevice}, or {@link recoveryBegin} when the
139
+ * player lost/deleted the old passkey ("Lost or replaced your passkey?").
140
+ */
136
141
  async enrollPasskey(opts) {
137
142
  this.assertWebAuthn();
138
143
  const signal = opts?.signal;
@@ -261,7 +266,9 @@ var InvoClient = class {
261
266
  * this to send a 6-digit code to the player's phone + email on file, collect the code,
262
267
  * call `enrollmentVerify(code)`, then RETRY the SAME `enrollPasskey()` —
263
268
  * `register/complete` auto-consumes the server-side grant (30-min TTL). For
264
- * `ENROLLMENT_REQUIRES_PROOF` (`err.isEnrollmentProofRequired`) use `linkDevice` instead.
269
+ * `ENROLLMENT_REQUIRES_PROOF` (`err.isEnrollmentProofRequired`) use `linkDevice`
270
+ * (player still has the other method) or `recoveryBegin`/`recoveryComplete`
271
+ * (player lost/deleted their passkey).
265
272
  */
266
273
  async enrollmentBegin(opts) {
267
274
  return this.withTokenRetry(async () => {
@@ -289,6 +296,65 @@ var InvoClient = class {
289
296
  return { status: String(raw["status"] ?? ""), raw };
290
297
  });
291
298
  }
299
+ /**
300
+ * Passkey recovery — "Lost or replaced your passkey?". Deleting a passkey on the
301
+ * device never tells the server the key is gone, so the next `enrollPasskey()` is
302
+ * blocked by the anti-takeover gate with `ENROLLMENT_REQUIRES_PROOF`
303
+ * (`err.isEnrollmentProofRequired`). When the player can't prove the old method
304
+ * (they deleted/lost it — otherwise prefer `linkDevice`), run:
305
+ *
306
+ * 1. `recoveryBegin()` — sends a one-time code to the phone/email on file
307
+ * (422 `no_channel_on_file`, 429 `rate_limited` at 5/10min).
308
+ * 2. `recoveryComplete(code)` — deactivates the stale server-side passkey and
309
+ * authorizes a fresh enrollment (400 `ENROLLMENT_CODE_INVALID` on a wrong/
310
+ * expired code — attempt-capped; let the user retry or resend).
311
+ * 3. Immediately retry the SAME `enrollPasskey()` — it now succeeds.
312
+ *
313
+ * The owner also gets an out-of-band "your passkey was reset" SMS/email — that's
314
+ * the intended tamper alert; surface nothing special for it.
315
+ *
316
+ * ⚠ 24-HOUR MONEY COOLDOWN: a recovery-enrolled passkey logs in and COLLECTS
317
+ * funds immediately, but `approveSend`/`approveTransfer` throw
318
+ * `PASSKEY_RECOVERY_COOLDOWN` (403; `err.isPasskeyRecoveryCooldown`,
319
+ * `err.retryAfterAt`) for 24h — SIM-swap protection. Show the pause message with
320
+ * the timestamp; do not retry-loop it.
321
+ *
322
+ * If the OS itself fails to SAVE a new passkey ("there is a problem saving your
323
+ * passkey"), have the user delete the stale entry in their password manager first
324
+ * (iPhone: Settings → Passwords; Android: Google Password Manager; Windows:
325
+ * Settings → Accounts → Passkeys).
326
+ */
327
+ async recoveryBegin(opts) {
328
+ return this.withTokenRetry(async () => {
329
+ const raw = await this.post(
330
+ "/api/sdk/device/recover/begin",
331
+ void 0,
332
+ opts?.signal
333
+ );
334
+ return {
335
+ status: String(raw["status"] ?? ""),
336
+ channels: Array.isArray(raw["channels"]) ? raw["channels"] : [],
337
+ raw
338
+ };
339
+ });
340
+ }
341
+ /** Verify the recovery code (see {@link recoveryBegin}); on success, call `enrollPasskey()`. */
342
+ async recoveryComplete(code, opts) {
343
+ if (!code) throw new Error("recoveryComplete requires the one-time `code`.");
344
+ return this.withTokenRetry(async () => {
345
+ const raw = await this.post(
346
+ "/api/sdk/device/recover/complete",
347
+ { code },
348
+ opts?.signal
349
+ );
350
+ return {
351
+ status: String(raw["status"] ?? ""),
352
+ deactivatedCount: Number(raw["deactivated_count"] ?? 0),
353
+ next: typeof raw["next"] === "string" ? raw["next"] : void 0,
354
+ raw
355
+ };
356
+ });
357
+ }
292
358
  // --- internals ---
293
359
  /** POST with the current player token. Token-expiry retry is handled one level
294
360
  * up by withTokenRetry (which re-runs the whole ceremony, not a single call). */
package/dist/server.cjs CHANGED
@@ -25,10 +25,35 @@ var InvoError = class _InvoError extends Error {
25
25
  get isEnrollmentAuthorizationRequired() {
26
26
  return this.code === "ENROLLMENT_REQUIRES_AUTHORIZATION";
27
27
  }
28
- /** True if enrolling is blocked because another method exists — use `linkDevice`. */
28
+ /**
29
+ * True if enrolling is blocked because the identity already has an enrolled method
30
+ * (anti-takeover gate, register/complete → 409). Two ways forward: `linkDevice` when
31
+ * the player still HAS the other method, or the passkey-recovery flow
32
+ * (`recoveryBegin`/`recoveryComplete` — "Lost or replaced your passkey?") when they
33
+ * deleted/lost it — the server can't know a device-side passkey is gone.
34
+ */
29
35
  get isEnrollmentProofRequired() {
30
36
  return this.code === "ENROLLMENT_REQUIRES_PROOF";
31
37
  }
38
+ /** True if the recovery OTP was wrong or expired (attempt-capped) — let the user retry or resend. */
39
+ get isEnrollmentCodeInvalid() {
40
+ return this.code === "ENROLLMENT_CODE_INVALID";
41
+ }
42
+ /**
43
+ * True if a money-OUT approve was refused because the passkey was enrolled via
44
+ * recovery less than 24h ago (SIM-swap protection, approve → 403). NOT a generic
45
+ * failure — do not retry-loop. Login and inbound confirm-receipt (collecting money)
46
+ * still work. Show: "For your security, transfers are paused for 24 hours after a
47
+ * passkey reset. You can still receive funds. Try again after {retryAfterAt}."
48
+ */
49
+ get isPasskeyRecoveryCooldown() {
50
+ return this.code === "PASSKEY_RECOVERY_COOLDOWN";
51
+ }
52
+ /** The ISO timestamp when a `PASSKEY_RECOVERY_COOLDOWN` lifts (`retry_after`), when present. */
53
+ get retryAfterAt() {
54
+ const v = this.bodyObject()["retry_after"];
55
+ return typeof v === "string" && v && Number.isNaN(Number(v)) ? v : void 0;
56
+ }
32
57
  /**
33
58
  * True if an item purchase failed because the player's balance was too low (§4.8 → 400).
34
59
  * The backend carries `required_amount` + `current_balance` on the body for the UI.
@@ -40,10 +65,22 @@ var InvoError = class _InvoError extends Error {
40
65
  const b = this.bodyObject();
41
66
  return this.code === "INSUFFICIENT_BALANCE" || "required_amount" in b || /insufficient[_ ]balance/i.test(this.message);
42
67
  }
43
- /** True if a claim needs phone-share approval before it can complete (claim → 409). */
68
+ /**
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.
75
+ */
44
76
  get isPhoneShareApprovalRequired() {
45
77
  return this.code === "PHONE_SHARE_APPROVAL_REQUIRED";
46
78
  }
79
+ /** The `approval_id` from a phone-share 409 body, for `phoneShareApprove`. */
80
+ get phoneShareApprovalId() {
81
+ const v = this.bodyObject()["approval_id"];
82
+ return typeof v === "string" && v ? v : void 0;
83
+ }
47
84
  /** True if the phone-share (phone, requesting_email) pair was already approved. */
48
85
  get isPhoneShareAlreadyApproved() {
49
86
  return this.code === "PHONE_SHARE_ALREADY_APPROVED";
@@ -73,7 +110,9 @@ function errorFromResponse(status, body, requestId) {
73
110
  else if (typeof b["error_code"] === "string") code = b["error_code"];
74
111
  if (typeof b["error"] === "string") message = b["error"];
75
112
  else if (typeof b["message"] === "string") message = b["message"];
76
- if (!code && typeof b["error"] === "string" && /^(flow_paused|spending_limit_exceeded|receiver_not_enrolled_use_claim_code)$/.test(b["error"])) {
113
+ if (!code && typeof b["error"] === "string" && /^(flow_paused|spending_limit_exceeded|receiver_not_enrolled_use_claim_code|no_channel_on_file|rate_limited)$/.test(
114
+ b["error"]
115
+ )) {
77
116
  code = b["error"];
78
117
  }
79
118
  } else if (typeof body === "string" && body.trim()) {
@@ -469,7 +508,7 @@ async function hmacHexSubtle(secret, message) {
469
508
  }
470
509
 
471
510
  // src/server.ts
472
- var DEFAULT_UA = "invonetwork-web-sdk/1.2.1 (+https://invo.network)";
511
+ var DEFAULT_UA = "invonetwork-web-sdk/2.1.0 (+https://invo.network)";
473
512
  var MAX_USD_AMOUNT = 999.99;
474
513
  var MAX_ITEM_PRICE = 999999.99;
475
514
  function invalidInput(label, value, why) {
@@ -501,6 +540,12 @@ function parseMoney(value, max, label) {
501
540
  function assertUsdAmount(usdAmount) {
502
541
  parseMoney(usdAmount, MAX_USD_AMOUNT, "usdAmount");
503
542
  }
543
+ var E164 = /^\+[1-9]\d{1,14}$/;
544
+ function assertE164(value, label) {
545
+ if (typeof value !== "string" || !E164.test(value)) {
546
+ throw invalidInput(label, value, 'must be an E.164 phone number, e.g. "+15555550100"');
547
+ }
548
+ }
504
549
  function toOrderDetails(raw) {
505
550
  return {
506
551
  order: raw["order"] ?? {},
@@ -641,14 +686,31 @@ var InvoServer = class {
641
686
  });
642
687
  this.auth = { kind: "game-secret", secret: config.gameSecret };
643
688
  }
644
- /** Mint a short-lived, game-scoped player token to hand to the browser InvoClient. */
689
+ /**
690
+ * Mint a short-lived, game-scoped player token to hand to the browser InvoClient.
691
+ *
692
+ * This is the player REGISTRATION call: the network identity is derived from
693
+ * `email + phone` TOGETHER, so both are required. Registering email-only and
694
+ * attaching the phone later changes the identity and forces device re-enrollment —
695
+ * collect the phone before the first mint. `playerPhone` must be E.164
696
+ * (e.g. "+15555550100"); incoming cross-game transfers and the account-linking
697
+ * consent SMS are both matched by phone, so an account without one can't receive
698
+ * either.
699
+ *
700
+ * If the phone already belongs to another INVO account (same person, new email),
701
+ * this throws an InvoError with `isPhoneShareApprovalRequired` — NOT a failure:
702
+ * the phone holder was sent a consent SMS. Surface "pending approval" to the user,
703
+ * then re-issue the same call once approved (poll `phoneShareStatus`, or use
704
+ * `phoneShareInitiate`/`phoneShareApprove` for the in-app OTP fallback).
705
+ */
645
706
  async mintPlayerToken(input, opts) {
646
707
  if (typeof input.playerEmail !== "string" || !input.playerEmail.trim()) {
647
708
  throw invalidInput("playerEmail", input.playerEmail, "is required");
648
709
  }
710
+ assertE164(input.playerPhone, "playerPhone");
649
711
  const raw = await this.http.post(
650
712
  "/api/sdk/player-token",
651
- { player_email: input.playerEmail },
713
+ { player_email: input.playerEmail, player_phone: input.playerPhone },
652
714
  this.auth,
653
715
  { idempotent: true, signal: opts?.signal }
654
716
  // 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, 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-DtihCpOj.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-DtihCpOj.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, 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-DtihCpOj.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-DtihCpOj.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-YCEW7NC3.js';
2
+ export { InvoError } from './chunk-YCEW7NC3.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.1.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
@@ -28,8 +28,26 @@ 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
- /** True if enrolling is blocked because another method exists — use `linkDevice`. */
31
+ /**
32
+ * True if enrolling is blocked because the identity already has an enrolled method
33
+ * (anti-takeover gate, register/complete → 409). Two ways forward: `linkDevice` when
34
+ * the player still HAS the other method, or the passkey-recovery flow
35
+ * (`recoveryBegin`/`recoveryComplete` — "Lost or replaced your passkey?") when they
36
+ * deleted/lost it — the server can't know a device-side passkey is gone.
37
+ */
32
38
  get isEnrollmentProofRequired(): boolean;
39
+ /** True if the recovery OTP was wrong or expired (attempt-capped) — let the user retry or resend. */
40
+ get isEnrollmentCodeInvalid(): boolean;
41
+ /**
42
+ * True if a money-OUT approve was refused because the passkey was enrolled via
43
+ * recovery less than 24h ago (SIM-swap protection, approve → 403). NOT a generic
44
+ * failure — do not retry-loop. Login and inbound confirm-receipt (collecting money)
45
+ * still work. Show: "For your security, transfers are paused for 24 hours after a
46
+ * passkey reset. You can still receive funds. Try again after {retryAfterAt}."
47
+ */
48
+ get isPasskeyRecoveryCooldown(): boolean;
49
+ /** The ISO timestamp when a `PASSKEY_RECOVERY_COOLDOWN` lifts (`retry_after`), when present. */
50
+ get retryAfterAt(): string | undefined;
33
51
  /**
34
52
  * True if an item purchase failed because the player's balance was too low (§4.8 → 400).
35
53
  * The backend carries `required_amount` + `current_balance` on the body for the UI.
@@ -37,8 +55,17 @@ declare class InvoError extends Error {
37
55
  * is a rate-limit, not a top-up condition) is NOT misclassified as this.
38
56
  */
39
57
  get isInsufficientBalance(): boolean;
40
- /** True if a claim needs phone-share approval before it can complete (claim → 409). */
58
+ /**
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
+ */
41
66
  get isPhoneShareApprovalRequired(): boolean;
67
+ /** The `approval_id` from a phone-share 409 body, for `phoneShareApprove`. */
68
+ get phoneShareApprovalId(): string | undefined;
42
69
  /** True if the phone-share (phone, requesting_email) pair was already approved. */
43
70
  get isPhoneShareAlreadyApproved(): boolean;
44
71
  /** True if an idempotency-keyed request was a duplicate (item purchase → 409). */
@@ -466,6 +493,20 @@ interface EnrollmentVerifyResult {
466
493
  status: string;
467
494
  raw: Record<string, unknown>;
468
495
  }
496
+ interface RecoveryBeginResult {
497
+ status: string;
498
+ /** Channels the one-time code was sent to, e.g. ["sms","email"]. */
499
+ channels: string[];
500
+ raw: Record<string, unknown>;
501
+ }
502
+ interface RecoveryCompleteResult {
503
+ status: string;
504
+ /** How many stale server-side passkeys were deactivated. */
505
+ deactivatedCount: number;
506
+ /** Human hint from the backend (what to do next). */
507
+ next?: string;
508
+ raw: Record<string, unknown>;
509
+ }
469
510
  interface LinkDeviceResult {
470
511
  /** "authorized" on success — a single-use grant that register/complete consumes. */
471
512
  status: string;
@@ -594,4 +635,4 @@ interface PhoneShareStatusResult {
594
635
  raw: Record<string, unknown>;
595
636
  }
596
637
 
597
- export { type PhoneShareApproveResult as $, type ApproveResult as A, type BalanceResult as B, type ClientConfig as C, type DestinationsQuery as D, type EnrollmentBeginResult as E, type PlayerBalanceResult as F, type InboundPendingQuery as G, type InboundPendingResult as H, InvoError as I, type LinkedIdentitiesQuery as J, type LinkedIdentitiesResult as K, type LinkDeviceResult as L, type SmsVerifyResult as M, type ClaimTransferInput as N, type OrderDetailsResult as O, type PendingCollectResult as P, type ClaimResult as Q, type Rail as R, type ServerConfig as S, type ClaimCurrencyInput as T, type TransactionStatusResult as U, type VerificationMethod as V, type GuardianApprovalStatusResult as W, type ServerDestinationsQuery as X, type PhoneShareContact as Y, type PhoneShareInitiateResult as Z, type PhoneShareApproveInput as _, type CallOptions as a, type PhoneShareStatusResult as a0, type CurrencyBalance as a1, type InboundPendingItem as a2, type LinkedIdentityEmail as a3, type ConfirmReceiptResult as b, type DestinationsResult as c, type EnrollmentVerifyResult as d, type BalanceRow as e, type DestinationGame as f, type InvoErrorInfo as g, type InvoHooks as h, type InvoRequestInfo as i, type InvoResponseInfo as j, type PendingCollectItem as k, type PlayerToken as l, type InitiateSendInput as m, type InitiateResult as n, type InitiateTransferInput as o, type CreateCheckoutInput as p, type CreateCheckoutResult as q, type PurchaseInput as r, type PurchaseResult as s, type ConfirmPaymentResult as t, type PurchaseItemInput as u, type PurchaseItemResult as v, type ItemHistoryQuery as w, type ItemHistoryResult as x, type ItemOrderQuery as y, type PlayerBalanceQuery as z };
638
+ export { type PhoneShareInitiateResult as $, type ApproveResult as A, type BalanceResult as B, type ClientConfig as C, type DestinationsQuery as D, type EnrollmentBeginResult as E, type ItemOrderQuery as F, type PlayerBalanceQuery as G, type PlayerBalanceResult as H, InvoError as I, type InboundPendingQuery as J, type InboundPendingResult as K, type LinkDeviceResult as L, type LinkedIdentitiesQuery as M, type LinkedIdentitiesResult as N, type OrderDetailsResult as O, type PendingCollectResult as P, type SmsVerifyResult as Q, type RecoveryBeginResult as R, type ServerConfig as S, type ClaimTransferInput as T, type ClaimResult as U, type VerificationMethod as V, type ClaimCurrencyInput as W, type TransactionStatusResult as X, type GuardianApprovalStatusResult as Y, type ServerDestinationsQuery as Z, type PhoneShareContact as _, type CallOptions as a, type PhoneShareApproveInput as a0, type PhoneShareApproveResult as a1, type PhoneShareStatusResult as a2, type CurrencyBalance as a3, type InboundPendingItem as a4, type LinkedIdentityEmail as a5, type ConfirmReceiptResult as b, type DestinationsResult as c, type EnrollmentVerifyResult as d, type RecoveryCompleteResult as e, type BalanceRow as f, type DestinationGame as g, type InvoErrorInfo as h, type InvoHooks as i, type InvoRequestInfo as j, type InvoResponseInfo as k, type PendingCollectItem as l, type Rail as m, type PlayerToken as n, type InitiateSendInput as o, type InitiateResult as p, type InitiateTransferInput as q, type CreateCheckoutInput as r, type CreateCheckoutResult as s, type PurchaseInput as t, type PurchaseResult as u, type ConfirmPaymentResult as v, type PurchaseItemInput as w, type PurchaseItemResult as x, type ItemHistoryQuery as y, type ItemHistoryResult as z };
@@ -28,8 +28,26 @@ 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
- /** True if enrolling is blocked because another method exists — use `linkDevice`. */
31
+ /**
32
+ * True if enrolling is blocked because the identity already has an enrolled method
33
+ * (anti-takeover gate, register/complete → 409). Two ways forward: `linkDevice` when
34
+ * the player still HAS the other method, or the passkey-recovery flow
35
+ * (`recoveryBegin`/`recoveryComplete` — "Lost or replaced your passkey?") when they
36
+ * deleted/lost it — the server can't know a device-side passkey is gone.
37
+ */
32
38
  get isEnrollmentProofRequired(): boolean;
39
+ /** True if the recovery OTP was wrong or expired (attempt-capped) — let the user retry or resend. */
40
+ get isEnrollmentCodeInvalid(): boolean;
41
+ /**
42
+ * True if a money-OUT approve was refused because the passkey was enrolled via
43
+ * recovery less than 24h ago (SIM-swap protection, approve → 403). NOT a generic
44
+ * failure — do not retry-loop. Login and inbound confirm-receipt (collecting money)
45
+ * still work. Show: "For your security, transfers are paused for 24 hours after a
46
+ * passkey reset. You can still receive funds. Try again after {retryAfterAt}."
47
+ */
48
+ get isPasskeyRecoveryCooldown(): boolean;
49
+ /** The ISO timestamp when a `PASSKEY_RECOVERY_COOLDOWN` lifts (`retry_after`), when present. */
50
+ get retryAfterAt(): string | undefined;
33
51
  /**
34
52
  * True if an item purchase failed because the player's balance was too low (§4.8 → 400).
35
53
  * The backend carries `required_amount` + `current_balance` on the body for the UI.
@@ -37,8 +55,17 @@ declare class InvoError extends Error {
37
55
  * is a rate-limit, not a top-up condition) is NOT misclassified as this.
38
56
  */
39
57
  get isInsufficientBalance(): boolean;
40
- /** True if a claim needs phone-share approval before it can complete (claim → 409). */
58
+ /**
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
+ */
41
66
  get isPhoneShareApprovalRequired(): boolean;
67
+ /** The `approval_id` from a phone-share 409 body, for `phoneShareApprove`. */
68
+ get phoneShareApprovalId(): string | undefined;
42
69
  /** True if the phone-share (phone, requesting_email) pair was already approved. */
43
70
  get isPhoneShareAlreadyApproved(): boolean;
44
71
  /** True if an idempotency-keyed request was a duplicate (item purchase → 409). */
@@ -466,6 +493,20 @@ interface EnrollmentVerifyResult {
466
493
  status: string;
467
494
  raw: Record<string, unknown>;
468
495
  }
496
+ interface RecoveryBeginResult {
497
+ status: string;
498
+ /** Channels the one-time code was sent to, e.g. ["sms","email"]. */
499
+ channels: string[];
500
+ raw: Record<string, unknown>;
501
+ }
502
+ interface RecoveryCompleteResult {
503
+ status: string;
504
+ /** How many stale server-side passkeys were deactivated. */
505
+ deactivatedCount: number;
506
+ /** Human hint from the backend (what to do next). */
507
+ next?: string;
508
+ raw: Record<string, unknown>;
509
+ }
469
510
  interface LinkDeviceResult {
470
511
  /** "authorized" on success — a single-use grant that register/complete consumes. */
471
512
  status: string;
@@ -594,4 +635,4 @@ interface PhoneShareStatusResult {
594
635
  raw: Record<string, unknown>;
595
636
  }
596
637
 
597
- export { type PhoneShareApproveResult as $, type ApproveResult as A, type BalanceResult as B, type ClientConfig as C, type DestinationsQuery as D, type EnrollmentBeginResult as E, type PlayerBalanceResult as F, type InboundPendingQuery as G, type InboundPendingResult as H, InvoError as I, type LinkedIdentitiesQuery as J, type LinkedIdentitiesResult as K, type LinkDeviceResult as L, type SmsVerifyResult as M, type ClaimTransferInput as N, type OrderDetailsResult as O, type PendingCollectResult as P, type ClaimResult as Q, type Rail as R, type ServerConfig as S, type ClaimCurrencyInput as T, type TransactionStatusResult as U, type VerificationMethod as V, type GuardianApprovalStatusResult as W, type ServerDestinationsQuery as X, type PhoneShareContact as Y, type PhoneShareInitiateResult as Z, type PhoneShareApproveInput as _, type CallOptions as a, type PhoneShareStatusResult as a0, type CurrencyBalance as a1, type InboundPendingItem as a2, type LinkedIdentityEmail as a3, type ConfirmReceiptResult as b, type DestinationsResult as c, type EnrollmentVerifyResult as d, type BalanceRow as e, type DestinationGame as f, type InvoErrorInfo as g, type InvoHooks as h, type InvoRequestInfo as i, type InvoResponseInfo as j, type PendingCollectItem as k, type PlayerToken as l, type InitiateSendInput as m, type InitiateResult as n, type InitiateTransferInput as o, type CreateCheckoutInput as p, type CreateCheckoutResult as q, type PurchaseInput as r, type PurchaseResult as s, type ConfirmPaymentResult as t, type PurchaseItemInput as u, type PurchaseItemResult as v, type ItemHistoryQuery as w, type ItemHistoryResult as x, type ItemOrderQuery as y, type PlayerBalanceQuery as z };
638
+ export { type PhoneShareInitiateResult as $, type ApproveResult as A, type BalanceResult as B, type ClientConfig as C, type DestinationsQuery as D, type EnrollmentBeginResult as E, type ItemOrderQuery as F, type PlayerBalanceQuery as G, type PlayerBalanceResult as H, InvoError as I, type InboundPendingQuery as J, type InboundPendingResult as K, type LinkDeviceResult as L, type LinkedIdentitiesQuery as M, type LinkedIdentitiesResult as N, type OrderDetailsResult as O, type PendingCollectResult as P, type SmsVerifyResult as Q, type RecoveryBeginResult as R, type ServerConfig as S, type ClaimTransferInput as T, type ClaimResult as U, type VerificationMethod as V, type ClaimCurrencyInput as W, type TransactionStatusResult as X, type GuardianApprovalStatusResult as Y, type ServerDestinationsQuery as Z, type PhoneShareContact as _, type CallOptions as a, type PhoneShareApproveInput as a0, type PhoneShareApproveResult as a1, type PhoneShareStatusResult as a2, type CurrencyBalance as a3, type InboundPendingItem as a4, type LinkedIdentityEmail as a5, type ConfirmReceiptResult as b, type DestinationsResult as c, type EnrollmentVerifyResult as d, type RecoveryCompleteResult as e, type BalanceRow as f, type DestinationGame as g, type InvoErrorInfo as h, type InvoHooks as i, type InvoRequestInfo as j, type InvoResponseInfo as k, type PendingCollectItem as l, type Rail as m, type PlayerToken as n, type InitiateSendInput as o, type InitiateResult as p, type InitiateTransferInput as q, type CreateCheckoutInput as r, type CreateCheckoutResult as s, type PurchaseInput as t, type PurchaseResult as u, type ConfirmPaymentResult as v, type PurchaseItemInput as w, type PurchaseItemResult as x, type ItemHistoryQuery as y, type ItemHistoryResult as z };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@invonetwork/web-sdk",
3
- "version": "1.2.1",
3
+ "version": "2.1.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,