@invonetwork/web-sdk 2.0.0 → 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,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.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
+
7
32
  ## [2.0.0] — 2026-07-02
8
33
 
9
34
  **BREAKING — `mintPlayerToken` now requires `playerPhone` (E.164).** Requested by the INVO
package/README.md CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  First-party TypeScript SDK for integrating **INVO** into partner **web** platforms (storefronts, web games, dashboards). It wraps INVO's web money flows behind a typed, versioned API — the web analog of the Unity/Unreal plugins.
4
4
 
5
- > **Status:** `v2.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.
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)
@@ -143,7 +143,7 @@ The WebAuthn ceremony still runs in the browser (it must — it's `navigator.cre
143
143
  - **Real partner** (one login = one player) — derive the acting player from your **session**.
144
144
  - **Trusted first-party rig** (an internal tool that impersonates arbitrary test players) — the caller names `playerEmail`, guarded by a shared-secret header (`INVO_PROXY_TRUSTED_SECRET`), the same trusted pattern as a `player_email` token minter. Never expose this mode to end-user browsers.
145
145
 
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).
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).
147
147
 
148
148
  ## Before you go live
149
149
 
@@ -381,7 +381,7 @@ try {
381
381
 
382
382
  ---
383
383
 
384
- ## Passkeys (enroll, approve, link)
384
+ ## Passkeys (enroll, approve, link, recover)
385
385
 
386
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.
387
387
 
@@ -416,6 +416,39 @@ try {
416
416
  }
417
417
  ```
418
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
+
419
452
  - **User verification is required** on every approve/claim (a missing-UV assertion fails closed).
420
453
  - Challenges are single-use and bound to `{flow}:{transactionId}`.
421
454
  - The SDK passes the backend's WebAuthn options through unchanged (it does not hard-code `pubKeyCredParams`/`timeout`/`attestation`).
@@ -528,7 +561,7 @@ Helpers:
528
561
  | `.isPhoneShareApprovalRequired` | a new-account phone needs owner approval → run the `phoneShare*` handshake, then retry |
529
562
  | `.isPhoneShareAlreadyApproved` | phone-share was already approved (e.g. from a `/reject`) |
530
563
 
531
- 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`.
532
565
 
533
566
  ```ts
534
567
  import { InvoError } from "@invonetwork/web-sdk"; // or "@invonetwork/web-sdk/server"
@@ -581,6 +614,7 @@ Every method also accepts an optional final `{ signal }` (`AbortSignal`) for can
581
614
  |---|---|
582
615
  | `enrollPasskey()` | `{ status, device, raw }` |
583
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`) |
584
618
  | `approveSend(txnId)` / `approveTransfer(txnId)` | `{ status, next, transactionId, claimCode?, claimCodeExpiresAt?, holdReason?, risk?, guardianApproval?, pollEndpoint?, raw }` |
585
619
  | `confirmReceiptSend(txnId)` / `confirmReceiptTransfer(txnId)` | `{ status, holdReason?, raw }` |
586
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.
@@ -81,7 +106,9 @@ function errorFromResponse(status, body, requestId) {
81
106
  else if (typeof b["error_code"] === "string") code = b["error_code"];
82
107
  if (typeof b["error"] === "string") message = b["error"];
83
108
  else if (typeof b["message"] === "string") message = b["message"];
84
- 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
+ )) {
85
112
  code = b["error"];
86
113
  }
87
114
  } else if (typeof body === "string" && body.trim()) {
@@ -320,5 +347,5 @@ function toDestinationsResult(raw, direction) {
320
347
  }
321
348
 
322
349
  export { Http, InvoError, assertSecureBaseUrl, toDestinationsResult };
323
- //# sourceMappingURL=chunk-6XCI53XJ.js.map
324
- //# sourceMappingURL=chunk-6XCI53XJ.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.
@@ -83,7 +108,9 @@ function errorFromResponse(status, body, requestId) {
83
108
  else if (typeof b["error_code"] === "string") code = b["error_code"];
84
109
  if (typeof b["error"] === "string") message = b["error"];
85
110
  else if (typeof b["message"] === "string") message = b["message"];
86
- 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
+ )) {
87
114
  code = b["error"];
88
115
  }
89
116
  } else if (typeof body === "string" && body.trim()) {
@@ -452,7 +479,12 @@ var InvoClient = class {
452
479
  throw new Error("WebAuthn is not available in this environment (browser required).");
453
480
  }
454
481
  }
455
- /** 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
+ */
456
488
  async enrollPasskey(opts) {
457
489
  this.assertWebAuthn();
458
490
  const signal = opts?.signal;
@@ -581,7 +613,9 @@ var InvoClient = class {
581
613
  * this to send a 6-digit code to the player's phone + email on file, collect the code,
582
614
  * call `enrollmentVerify(code)`, then RETRY the SAME `enrollPasskey()` —
583
615
  * `register/complete` auto-consumes the server-side grant (30-min TTL). For
584
- * `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).
585
619
  */
586
620
  async enrollmentBegin(opts) {
587
621
  return this.withTokenRetry(async () => {
@@ -609,6 +643,65 @@ var InvoClient = class {
609
643
  return { status: String(raw["status"] ?? ""), raw };
610
644
  });
611
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
+ }
612
705
  // --- internals ---
613
706
  /** POST with the current player token. Token-expiry retry is handled one level
614
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-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';
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-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';
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-6XCI53XJ.js';
2
- export { InvoError } from './chunk-6XCI53XJ.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.
@@ -85,7 +110,9 @@ function errorFromResponse(status, body, requestId) {
85
110
  else if (typeof b["error_code"] === "string") code = b["error_code"];
86
111
  if (typeof b["error"] === "string") message = b["error"];
87
112
  else if (typeof b["message"] === "string") message = b["message"];
88
- 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
+ )) {
89
116
  code = b["error"];
90
117
  }
91
118
  } else if (typeof body === "string" && body.trim()) {
@@ -481,7 +508,7 @@ async function hmacHexSubtle(secret, message) {
481
508
  }
482
509
 
483
510
  // src/server.ts
484
- var DEFAULT_UA = "invonetwork-web-sdk/2.0.0 (+https://invo.network)";
511
+ var DEFAULT_UA = "invonetwork-web-sdk/2.1.0 (+https://invo.network)";
485
512
  var MAX_USD_AMOUNT = 999.99;
486
513
  var MAX_ITEM_PRICE = 999999.99;
487
514
  function invalidInput(label, value, why) {
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-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';
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). */
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-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';
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). */
package/dist/server.js CHANGED
@@ -1,5 +1,5 @@
1
- import { InvoError, assertSecureBaseUrl, Http, toDestinationsResult } from './chunk-6XCI53XJ.js';
2
- export { InvoError } from './chunk-6XCI53XJ.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/2.0.0 (+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) {
@@ -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.
@@ -475,6 +493,20 @@ interface EnrollmentVerifyResult {
475
493
  status: string;
476
494
  raw: Record<string, unknown>;
477
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
+ }
478
510
  interface LinkDeviceResult {
479
511
  /** "authorized" on success — a single-use grant that register/complete consumes. */
480
512
  status: string;
@@ -603,4 +635,4 @@ interface PhoneShareStatusResult {
603
635
  raw: Record<string, unknown>;
604
636
  }
605
637
 
606
- 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.
@@ -475,6 +493,20 @@ interface EnrollmentVerifyResult {
475
493
  status: string;
476
494
  raw: Record<string, unknown>;
477
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
+ }
478
510
  interface LinkDeviceResult {
479
511
  /** "authorized" on success — a single-use grant that register/complete consumes. */
480
512
  status: string;
@@ -603,4 +635,4 @@ interface PhoneShareStatusResult {
603
635
  raw: Record<string, unknown>;
604
636
  }
605
637
 
606
- 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": "2.0.0",
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,