@invonetwork/web-sdk 3.0.0 → 3.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,81 @@ 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
+ ## [3.1.0] — 2026-08-04
8
+
9
+ **Passkeys are the gold standard; the SMS-PIN path is deprecated.** This release makes INVO's
10
+ authentication guidance explicit in the two places developers actually look — the README and IDE
11
+ autocomplete. **No behavior changes, no API removals, no runtime warnings.** Upgrading and
12
+ changing nothing produces byte-identical runtime behavior.
13
+
14
+ A passkey is a phishing-resistant, origin-bound WebAuthn assertion. An SMS PIN is a shared secret
15
+ on a channel exposed to SIM swap and interception. They were documented as interchangeable
16
+ verification options; they are not, and the docs said so in a way that produced PIN-first
17
+ integrations.
18
+
19
+ ### Added — error-contract classifiers
20
+ Three 403s that previously arrived as a generic `InvoError` (correct `status`/`code`/`message`,
21
+ but no typed branch) now have classifiers:
22
+
23
+ - **`err.isSourceGameNotLive`** — the caller's OWN game is in testing. Self-serve: switch it to
24
+ Live in the console (Game Settings → Status).
25
+ - **`err.isTargetGameNotLive`** — the DESTINATION game is in testing. Usually another
26
+ developer's game, so the caller **cannot** fix it. **Deliberately distinct** from the source
27
+ case: collapsing them into one "not live" branch yields a "go fix it" CTA that dead-ends half
28
+ the time.
29
+ - **`err.gameStatus`** — the `game_status` field from either refusal (e.g. `"testing"`).
30
+ - **`err.isWebauthnNotEnabledForTenant`** — tenant has no verified WebAuthn RP ID. **This is
31
+ configuration state, not a failure**: fall back to the SMS/in-app path instead of surfacing an
32
+ error. Currently the common case — 4/23 sandbox and **0/3 production** tenants are configured.
33
+
34
+ Note the backend splits field names across these: the `*_GAME_NOT_LIVE` pair uses
35
+ `error_code`/`message`, while `WEBAUTHN_NOT_ENABLED_FOR_TENANT` uses `code`/`error`. The SDK
36
+ already read both, so `err.code` is populated either way — the new tests pin both shapes.
37
+
38
+ ### Clarified — the SDK does not, and did not, collapse non-2xx into transport errors
39
+ Following a report of a `403` being debugged as a network outage: verified end-to-end that a
40
+ non-2xx always surfaces with its real `status`, `code`, and `message`, and that `status: 0` is
41
+ reserved for a genuine absence of an HTTP response. **No fix was needed in the SDK** — the loss
42
+ happened in an integration-layer catch-all. Added regression tests pinning the behavior, plus a
43
+ README section (**"`.status === 0` means 'no HTTP response' — and nothing else"**) showing the
44
+ anti-pattern and the correct handler, and a note that `409` is a retryable not-ready state
45
+ rather than a failure.
46
+
47
+ ### Deprecated
48
+ - **`InvoServer.verifySmsTransfer` / `InvoServer.verifySmsSend`** — marked `@deprecated`. They
49
+ still work exactly as before and still hit the same endpoints. A **future major version will
50
+ remove them**; no date is committed yet. Keep them only as a genuine last resort for users who
51
+ cannot enroll a passkey (unsupported device, no platform authenticator) or who decline.
52
+ **Migration:** when `initiateSend`/`initiateTransfer` returns `verificationMethod: "sms"`, read
53
+ it as *"this sender has no passkey"* — prompt `InvoClient.enrollPasskey()` and then
54
+ `InvoClient.approveSend` / `approveTransfer`, instead of routing to a PIN pad.
55
+
56
+ ### Changed (documentation only)
57
+ - New README section — **"Passkeys are the gold standard — don't build on SMS"** — with the
58
+ do/don't table, the deprecation notice, and an explicit list of the OTP surfaces that are
59
+ **not** discouraged.
60
+ - `VerificationMethod`, `InitiateResult.verificationMethod` and `SmsVerifyResult` doc comments
61
+ reframed: `"in_app"` and `"sms"` are no longer presented as peer options.
62
+ - "Before you go live" now stresses configuring RP ID / origins *before* launch, since an
63
+ unconfigured tenant silently drops every sender onto the deprecated path.
64
+ - **New "Prerequisite: passkeys are dark until your tenant verifies a domain" subsection.**
65
+ Recommending passkeys without saying what unlocks them would send developers straight into a
66
+ `403` on their first `enrollPasskey()` call — with 0/3 prod tenants configured, that is
67
+ currently *everyone*. The deprecation carries no removal date for the same reason.
68
+ - Stability section corrected — it still claimed `2.0.0` was the only major, which `3.0.0`
69
+ made false.
70
+ - Design doc: `docs/features/passkey-first-authentication.md`.
71
+
72
+ ### Not affected — still recommended
73
+ `enrollmentBegin`/`enrollmentVerify`, `recoveryBegin`/`recoveryComplete`, and
74
+ `phoneShareInitiate`/`phoneShareApprove` all involve a one-time code but are the on-ramp *to* a
75
+ passkey (or phone-ownership consent), not a substitute for one. They are **not** deprecated.
76
+
77
+ ### Upgrade note
78
+ The only way this release can surface in a pipeline is a lint rule that treats `@deprecated`
79
+ usage as an error (e.g. `deprecation/deprecation` with `--max-warnings 0`). That is a lint-level
80
+ signal, not a build or runtime break, and it is the intended notice.
81
+
7
82
  ## [3.0.0] — 2026-07-20
8
83
 
9
84
  **BREAKING — the Platform Commerce card leg moved to INVO's hosted checkout.** The backend now
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:** `v3.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. Recent highlights: **3.0.0** moves the Platform Commerce card leg to **INVO's hosted checkout** — the server `purchase()` now returns a `checkoutUrl` and the browser just sends the buyer there (redirect or `mountCheckout` iframe); the 2.5.x card-element surface (`confirmCardPayment`/`mountCardPayment`, `billingAddress`, `commercePublishableKey`) is **removed** — see the [CHANGELOG](CHANGELOG.md) migration note; **2.5.0** added **Platform Commerce** (ecommerce) — a platform tenant selling items funded by balance **or** card, with `invo.platformCommerce.purchase/getStatus/refund` (server) and the `platform_commerce.*` webhooks; **2.4.0** adds Steam transfer-policy handling (`isSteamValueNonTransferable`/`isNonSteamValueIntoSteamBlocked` + `DestinationGame.acceptsSteamOriginValue`); **2.3.0** surfaces the claim-time phone-share `409` on `confirmReceipt*`/`claim*` (+ `err.phoneShareLast4`). Full history in the [CHANGELOG](CHANGELOG.md).
5
+ > **Status:** `v3.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. Recent highlights: **3.1.0** makes the authentication guidance explicit — **[passkeys are the gold standard](#passkeys-are-the-gold-standard-dont-build-on-sms)** and the SMS-PIN completion (`verifySmsTransfer`/`verifySmsSend`) is **deprecated and being phased out** (documentation only — no behavior change, no runtime warnings); **3.0.0** moves the Platform Commerce card leg to **INVO's hosted checkout** — the server `purchase()` now returns a `checkoutUrl` and the browser just sends the buyer there (redirect or `mountCheckout` iframe); the 2.5.x card-element surface (`confirmCardPayment`/`mountCardPayment`, `billingAddress`, `commercePublishableKey`) is **removed** — see the [CHANGELOG](CHANGELOG.md) migration note; **2.5.0** added **Platform Commerce** (ecommerce) — a platform tenant selling items funded by balance **or** card, with `invo.platformCommerce.purchase/getStatus/refund` (server) and the `platform_commerce.*` webhooks; **2.4.0** adds Steam transfer-policy handling (`isSteamValueNonTransferable`/`isNonSteamValueIntoSteamBlocked` + `DestinationGame.acceptsSteamOriginValue`); **2.3.0** surfaces the claim-time phone-share `409` on `confirmReceipt*`/`claim*` (+ `err.phoneShareLast4`). Full history in the [CHANGELOG](CHANGELOG.md).
6
6
  > Canonical partner reference: **https://docs.invo.network/docs/currency-purchase** and **https://docs.invo.network/docs/game-developer-integration**.
7
7
 
8
8
  ## What it does
@@ -23,8 +23,55 @@ Five money flows plus passkey (WebAuthn) authentication, split across a trusted
23
23
 
24
24
  The **game secret stays on your server**; the browser only ever holds a short-lived, game-scoped **player token** (and, for the card leg, a per-purchase `checkoutUrl`).
25
25
 
26
+ ## Passkeys are the gold standard — don't build on SMS
27
+
28
+ **If you take one thing from this README: authorize money movement with a passkey. Do not design your verification UX around the SMS PIN.**
29
+
30
+ A passkey is a WebAuthn assertion — phishing-resistant, bound to your origin, and backed by the device's secure hardware. An SMS PIN is a shared secret delivered over a channel exposed to **SIM swap**, SS7 interception, and social engineering. They are not two equivalent ways to approve a transfer; one is materially weaker, and INVO treats it that way (see the 24-hour money-out cooldown after a passkey recovery — that gate exists precisely because phone-based possession can be stolen).
31
+
32
+ So:
33
+
34
+ | | Do this | Not this |
35
+ |---|---|---|
36
+ | Sender approves a send/transfer | `client.enrollPasskey()` once, then `client.approveSend` / `approveTransfer` | a PIN pad as the default flow |
37
+ | `initiate*` returns `verificationMethod: "sms"` | read it as *"this user has no passkey"* → offer enrollment | route straight to PIN entry |
38
+ | Recipient collects | `client.confirmReceiptSend` / `confirmReceiptTransfer` (passkey) | claim code as the primary path |
39
+
40
+ ### Prerequisite: passkeys are dark until your tenant verifies a domain
41
+
42
+ **Read this before you wire up `enrollPasskey()`.** Passkey step-up is enabled **per tenant** and stays off until you verify ownership of a domain (your RP ID) in the developer console. Until then every passkey endpoint returns `403 WEBAUTHN_NOT_ENABLED_FOR_TENANT`.
43
+
44
+ **This is the common case today, not an edge case.** As of 2026-08-05 only **4 of 23 sandbox tenants** and **0 of 3 production tenants** have a verified RP ID. If you skip this, your integration will 403 on its first `enrollPasskey()` call and you'll be debugging a configuration state as if it were a bug.
45
+
46
+ `WEBAUTHN_NOT_ENABLED_FOR_TENANT` is **configuration state, not an error** — the ceremony was never available to fail. Don't show the player a failure; fall back to the existing path:
47
+
48
+ ```ts
49
+ try {
50
+ await client.enrollPasskey();
51
+ } catch (e) {
52
+ if (e instanceof InvoError && e.isWebauthnNotEnabledForTenant) {
53
+ // Not a failure — this tenant simply hasn't verified a domain yet.
54
+ // Fall back to the SMS/in-app path and (if this is YOUR tenant) go verify a domain.
55
+ usePinFallback();
56
+ } else throw e;
57
+ }
58
+ ```
59
+
60
+ So the honest sequence is: **verify your domain → enroll passkeys → you're on the gold-standard path.** Until step one is done, the SMS path is carrying you whether you like it or not — which is exactly why the deprecation below has no removal date attached.
61
+
62
+ > ⚠️ **`verifySmsTransfer` / `verifySmsSend` are deprecated as of `3.1.0` and a future major version will remove them.** They still work exactly as before — this release changes documentation only, emits no runtime warning, and breaks nothing. Keep the PIN path as a genuine last resort for: users who **cannot** enroll (unsupported device, no platform authenticator), users who decline, and **tenants that haven't verified a domain yet** (see above). Just don't make it the road everyone walks down once passkeys are available to you.
63
+
64
+ **What is *not* discouraged.** These use a one-time code, but they are the on-ramp *to* a passkey — not a substitute for one. Use them freely:
65
+
66
+ - `enrollmentBegin` / `enrollmentVerify` — the first-enrollment grant. This is how a user **gets** a passkey.
67
+ - `recoveryBegin` / `recoveryComplete` — restores a passkey after the user loses or deletes it.
68
+ - `phoneShareInitiate` / `phoneShareApprove` — phone-**ownership consent**, not transaction authorization.
69
+
70
+ Beyond security, this is also an economics story: SMS costs real money per message at every scale, and INVO's architecture targets passkey/in-app verification as the primary path so the platform never depends on carrier delivery. A passkey-first integration is faster for your users, cheaper to run, and won't need migrating later.
71
+
26
72
  ## Contents
27
73
 
74
+ - [Passkeys are the gold standard — don't build on SMS](#passkeys-are-the-gold-standard--dont-build-on-sms)
28
75
  - [Install](#install)
29
76
  - [Architecture & the two entry points](#architecture--the-two-entry-points)
30
77
  - [Before you go live](#before-you-go-live)
@@ -162,7 +209,7 @@ INVO enables each flow for your tenant in the [console](#get-your-account--game-
162
209
  - **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.
163
210
  - **Make sure players have a phone (E.164) at creation/enrollment** — it's required on the money calls (`initiateSend`/`initiateTransfer`) and for cross-game receive, though not on the token mint itself (see [Player token](#player-token-session-mint-for-an-existing-player)).
164
211
  - **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.)
165
- - **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.)
212
+ - **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. **Get this configured before launch:** until a sender is enrolled the backend falls back to the deprecated SMS-PIN path, which is the flow you don't want your users on (see [Passkeys are the gold standard](#passkeys-are-the-gold-standard--dont-build-on-sms)).
166
213
  - **For currency purchase:** card checkout works out of the box; ask INVO to enable the `game`/`steam` rails if you need them.
167
214
  - **For item purchase:** nothing extra — it's a currency-balance debit.
168
215
 
@@ -410,7 +457,7 @@ comes from the token, no PII).
410
457
 
411
458
  ## Sends & transfers (move currency between players)
412
459
 
413
- Move already-owned game currency from one player to another, authorized by the **sender's passkey** (or an SMS PIN if they aren't enrolled). **Send** and **transfer** are parallel flows:
460
+ Move already-owned game currency from one player to another, authorized by the **sender's passkey** — the [gold standard](#passkeys-are-the-gold-standard--dont-build-on-sms). (A deprecated SMS-PIN fallback exists for senders who aren't enrolled; treat it as a last resort, not a design.) **Send** and **transfer** are parallel flows:
414
461
 
415
462
  | | Send | Transfer |
416
463
  |---|---|---|
@@ -446,8 +493,9 @@ const t = await server.initiateTransfer({
446
493
  // Check guardianApproval FIRST — the guardian path takes precedence.
447
494
  switch (true) {
448
495
  case !!t.guardianApproval: // minor/guardian path (HTTP 202) → pending approval, no PIN UI
449
- case t.verificationMethod === "in_app": // sender is passkey-enrolled → approve in the browser
450
- case t.verificationMethod === "sms": // not enrolled, a PIN was sent → show a PIN-entry fallback
496
+ case t.verificationMethod === "in_app": // sender HAS a passkey → approve in the browser. The good path.
497
+ case t.verificationMethod === "sms": // sender has NO passkey → offer enrollPasskey() and approve;
498
+ // show the PIN pad only if they can't or won't enroll.
451
499
  }
452
500
 
453
501
  // 2. BROWSER — the sender approves with their passkey (give them t.transactionId + the player token)
@@ -468,10 +516,11 @@ try {
468
516
  }
469
517
  ```
470
518
 
471
- - **`verificationMethod`** (from initiate): `"in_app"` → passkey approve; `"sms"` → un-enrolled, PIN sent; `undefined` + `guardianApproval` → minor/guardian (HTTP 202), do **not** show the PIN UI. On the guardian path the SDK reports `verificationMethod: undefined` (even though the raw 202 body also carries `"sms"`) so `guardianApproval` wins — but branch on it first to be safe.
519
+ - **`verificationMethod`** (from initiate): `"in_app"` → the sender has a passkey, go approve (the recommended path); `"sms"` → **the sender has no passkey** and a PIN was sent as a deprecated fallback — the best response is to offer `enrollPasskey()` and then `approveSend`/`approveTransfer`, showing the PIN pad only if they can't or won't enroll; `undefined` + `guardianApproval` → minor/guardian (HTTP 202), do **not** show the PIN UI. On the guardian path the SDK reports `verificationMethod: undefined` (even though the raw 202 body also carries `"sms"`) so `guardianApproval` wins — but branch on it first to be safe.
472
520
  - **Claim codes** are returned only by `approveTransfer`; they're the out-of-band fallback when the recipient isn't enrolled.
473
521
  - **`err.isReceiverNotEnrolled`** on `confirmReceipt*` is the explicit signal to switch to claim-code entry.
474
522
  - **`err.isPhoneShareApprovalRequired` on `confirmReceipt*` / `claimTransfer` / `claimCurrency`** (409): the receiver phone is contested, so INVO **holds the money** and texts the phone owner to approve. Not a failure — show `err.message` verbatim (`err.phoneShareLast4` names the phone), then **retry the same call** once approved (it succeeds idempotently); on denial/expiry the sender is refunded. Same handling as the initiate-time phone-share 409.
523
+ - **Both games must be Live.** `initiateSend`/`initiateTransfer` throw `403` if either side is still in testing, and the two cases are **deliberately separate** because the fix differs: `err.isSourceGameNotLive` is **your** game (self-serve — switch it to Live in the console under Game Settings → Status), `err.isTargetGameNotLive` is the **destination** game, usually owned by another developer, so you can't flip it — show `err.message` and steer the player elsewhere via `getDestinations`. `err.gameStatus` carries the current state. Don't merge these into one "not live" branch; it produces a "go fix it" button that leads nowhere half the time.
475
524
  - **Steam titles** (dark until a title is Steam-distributed): `initiateSend`/`initiateTransfer` can throw `err.isSteamValueNonTransferable` (moving more than the non-Steam balance to a non-Steam destination — show `err.message`, cap the amount at `err.steamTransferableMax`; `err.steamOriginAmount` is the Steam-locked portion) or `err.isNonSteamValueIntoSteamBlocked` (non-Steam value into a Steam title). Prevent both up front: `getDestinations` rows carry **`acceptsSteamOriginValue`** — disable non-Steam destinations for a player holding Steam-purchased currency.
476
525
  - Transfer self-claim may be disabled for your tenant; if it is, surface the claim-code path instead.
477
526
  - **Holds:** an approve/claim can return an HTTP 202 hold instead of success — inspect `result.holdReason` (`"RISK_HOLD"`, `"GUARDIAN_APPROVAL_PENDING"`, and on confirm-receipt `"RECIPIENT_IDENTITY_PENDING"`); success has no `holdReason` (and `next: "pending_claim"`). Terminal guardian outcomes throw (`GUARDIAN_APPROVAL_REJECTED`/`_EXPIRED`).
@@ -488,7 +537,9 @@ try {
488
537
 
489
538
  ## Passkeys (enroll, approve, link, recover)
490
539
 
491
- 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.
540
+ Passkeys (WebAuthn) are **the** way to approve sends/transfers — see [Passkeys are the gold standard](#passkeys-are-the-gold-standard--dont-build-on-sms) for why the SMS PIN they replace is deprecated. The browser SDK wraps `navigator.credentials.create/get`, base64url encoding, challenge round-trips, and error mapping.
541
+
542
+ **Enroll early.** The best moment is right after a player first signs in — not at the moment they're trying to move money, when a WebAuthn prompt reads as friction. A player enrolled up front never touches the PIN path at all.
492
543
 
493
544
  ```ts
494
545
  // Enroll once per user (no-op to call again — the backend excludes already-enrolled credentials)
@@ -654,6 +705,41 @@ Every failure throws **`InvoError`** with:
654
705
  - `.message` — human-readable
655
706
  - `.body` — the raw parsed response
656
707
 
708
+ ### `.status === 0` means "no HTTP response" — and nothing else
709
+
710
+ This is the single most important thing to get right when handling INVO errors, so it's worth stating precisely:
711
+
712
+ | `err.status` | What actually happened | What to tell the developer |
713
+ |---|---|---|
714
+ | `0` | **No HTTP response** — DNS failure, connection refused, TLS failure, timeout, or a client-side guard that ran before any network call | "couldn't reach INVO" |
715
+ | `4xx` | The API **answered**, with a precise refusal. `.code` and `.message` are populated | show `.message` — it says what to do |
716
+ | `5xx` | The API answered with a server fault | retry; escalate if it persists |
717
+
718
+ **The SDK never collapses a non-2xx into a transport error.** A `403` arrives as `status: 403` with `.code` and `.message` intact; only a genuine absence of a response produces `status: 0`. Both entry points and both SDKs behave this way, and it's covered by regression tests.
719
+
720
+ The failure mode to avoid is in **your** catch block:
721
+
722
+ ```ts
723
+ // ✗ Loses everything the API told you. A 403 with a precise, actionable refusal
724
+ // renders as a network outage, and the developer debugs a 500 that never happened.
725
+ try { await server.initiateTransfer(input); }
726
+ catch (e) { showToast("Could not reach the server"); }
727
+
728
+ // ✓ Distinguish "no response" from "answered with a refusal".
729
+ try { await server.initiateTransfer(input); }
730
+ catch (e) {
731
+ if (!(e instanceof InvoError)) throw e;
732
+ if (e.status === 0) showToast("Couldn't reach INVO — check your connection.");
733
+ else showToast(e.message); // the API already wrote the actionable text
734
+ }
735
+ ```
736
+
737
+ > This is not hypothetical. A developer once spent a debugging session hunting a 500 that didn't exist — the logs showed two clean `403`s carrying exact remediation steps, and a catch-all in the integration layer had rendered them as "could not reach the server."
738
+
739
+ ### 409 is usually "not ready" or "already done", not a failure
740
+
741
+ INVO uses `409` for **retryable not-ready states**, not errors: a duplicate `clientRequestId`, an already-refunded order, an unverified domain. Branch on them (`.isDuplicateRequest`, `.isAlreadyRefunded`, `.isPhoneShareApprovalRequired`, `.isPhoneShareAlreadyApproved`) and treat them as "retry" or "already done" — surfacing them as red error states misrepresents what happened.
742
+
657
743
  Helpers:
658
744
 
659
745
  | Helper | Meaning |
@@ -672,6 +758,9 @@ Helpers:
672
758
  | `.isSteamValueNonTransferable` | initiate blocked (409): would move more than the non-Steam balance to a non-Steam destination → show `.message`, cap input at `.steamTransferableMax` (`.steamOriginAmount` = Steam-locked portion) |
673
759
  | `.isNonSteamValueIntoSteamBlocked` | initiate blocked (409): non-Steam value can't move into a Steam title → show `.message`, pick a non-Steam destination |
674
760
  | `.isPhoneShareAlreadyApproved` | phone-share was already approved (e.g. from a `/reject`) |
761
+ | `.isSourceGameNotLive` | **(403)** the caller's OWN game is in testing → **self-serve**: switch it to Live in the console (Game Settings → Status). Show `.message`; `.gameStatus` has the current state |
762
+ | `.isTargetGameNotLive` | **(403)** the DESTINATION game is in testing → the caller usually **can't fix this** (someone else's game). Show `.message`; steer to another destination via `getDestinations`. Deliberately **distinct** from `.isSourceGameNotLive` — don't collapse them, the remediation differs |
763
+ | `.isWebauthnNotEnabledForTenant` | **(403)** tenant has no verified RP ID → **configuration state, not a failure**. Fall back to the SMS/in-app path; see [passkey prerequisites](#prerequisite-passkeys-are-dark-until-your-tenant-verifies-a-domain) |
675
764
 
676
765
  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`.
677
766
 
@@ -710,7 +799,7 @@ try {
710
799
  | `getPlayerBalance({ playerEmail })` | `{ player, balances, summary, raw }` — **by email only** (no by-id route; use `InvoClient.getBalance()` client-side) |
711
800
  | `getInboundPending({ playerEmail? \| playerPhone? })` | `{ inboundPending, raw }` — live unclaimed inbound sends/transfers |
712
801
  | `getLinkedIdentities({ playerEmail? \| playerPhone? })` | `{ walletUserId, primaryEmail, primaryPhone, isMinor, emails, notFound, raw }` — **server-only** (returns PII) |
713
- | `verifySmsTransfer(txnId, smsPin)` / `verifySmsSend(txnId, smsPin)` | `SmsVerifyResult` — complete the SMS-PIN path when `verificationMethod: "sms"` |
802
+ | ~~`verifySmsTransfer(txnId, smsPin)`~~ / ~~`verifySmsSend(txnId, smsPin)`~~ | **Deprecated (3.1.0), removal at a future major.** `SmsVerifyResult` — completes the SMS-PIN path when `verificationMethod: "sms"`. Prefer passkey enrollment + `approveTransfer`/`approveSend`; keep this only for users who can't enroll. Still fully functional. |
714
803
  | `claimTransfer(input)` / `claimCurrency(input)` | `ClaimResult` — redeem a claim code (`needsAccountSelection` + `candidates` on a multi-account phone) |
715
804
  | `getTransferStatus(txnId)` / `getSendStatus(txnId)` | `TransactionStatusResult` — poll outbound state (`verificationState`) |
716
805
  | `getGuardianApprovalStatus(txnId)` | `GuardianApprovalStatusResult` — poll a guardian hold to resolution (`state`) |
@@ -752,7 +841,7 @@ npm test # vitest
752
841
 
753
842
  ### Stability
754
843
 
755
- Since **`1.0.0`** the public API is **stable**: it follows [semver](https://semver.org/), and **no breaking change ships without a major version bump + a migration note**. Patch = fixes, minor = additive surface (new methods/fields, backward-compatible — e.g. `2.1.0`'s passkey recovery, `2.4.0`'s Steam-policy classifiers), major = breaking changes (rare — `2.0.0` is the only major to date, which required `playerPhone` at the token mint; `2.2.0` later relaxed that back to optional). The wire contract is the same live INVO API you'd call directly, and it's backward-compatible within a major — so a pinned SDK keeps working. Safe to depend on in production; pin a version and watch [releases](https://github.com/Invo-Technologies/invo-web-sdk/releases) for security updates.
844
+ Since **`1.0.0`** the public API is **stable**: it follows [semver](https://semver.org/), and **no breaking change ships without a major version bump + a migration note**. Patch = fixes, minor = additive surface (new methods/fields, backward-compatible — e.g. `2.1.0`'s passkey recovery, `2.4.0`'s Steam-policy classifiers), major = breaking changes (rare — two to date: `2.0.0` required `playerPhone` at the token mint, which `2.2.0` later relaxed back to optional, and `3.0.0` replaced the Platform Commerce card-element surface with INVO's hosted checkout). Deprecations get a documentation-only notice in a minor release first — `verifySmsTransfer`/`verifySmsSend` are deprecated as of `3.1.0` and keep working until a future major removes them. The wire contract is the same live INVO API you'd call directly, and it's backward-compatible within a major — so a pinned SDK keeps working. Safe to depend on in production; pin a version and watch [releases](https://github.com/Invo-Technologies/invo-web-sdk/releases) for security updates.
756
845
 
757
846
  Full history: [CHANGELOG](https://github.com/Invo-Technologies/invo-web-sdk/blob/main/CHANGELOG.md) · [release notes](https://github.com/Invo-Technologies/invo-web-sdk/blob/main/docs/RELEASES.md) (absolute links to `main`).
758
847
 
@@ -128,6 +128,67 @@ var InvoError = class _InvoError extends Error {
128
128
  get isNonSteamValueIntoSteamBlocked() {
129
129
  return this.code === "NON_STEAM_VALUE_INTO_STEAM_BLOCKED";
130
130
  }
131
+ /**
132
+ * True if the initiate was refused because **the caller's OWN game is in testing**
133
+ * (`SOURCE_GAME_NOT_LIVE`, 403). Reaches this SDK via `initiateSend` / `initiateTransfer`;
134
+ * the backend uses the same code on its Amazon rewards-send path too (not wrapped here),
135
+ * so one branch keeps working if that flow is ever added.
136
+ *
137
+ * **The caller can self-serve this**: switch the game to Live in the developer console
138
+ * (Game Settings → Status). Show `err.message` — it names the game and the exact control.
139
+ * `err.gameStatus` carries the current state if you want to render it.
140
+ *
141
+ * Deliberately distinct from {@link isTargetGameNotLive} — do NOT collapse the two into
142
+ * one "not live" case. The remediation differs: this one the developer can fix, the
143
+ * other one they cannot.
144
+ */
145
+ get isSourceGameNotLive() {
146
+ return this.code === "SOURCE_GAME_NOT_LIVE";
147
+ }
148
+ /**
149
+ * True if the initiate was refused because **the DESTINATION game is in testing**
150
+ * (`TARGET_GAME_NOT_LIVE`, 403). Reaches this SDK via `initiateSend` / `initiateTransfer`;
151
+ * same backend vocabulary on the Amazon rewards-send path (not wrapped here).
152
+ *
153
+ * **The caller usually CANNOT fix this** — the destination is another developer's game
154
+ * and only its owner can switch it to Live. Don't offer a "go fix it" action; show
155
+ * `err.message` and, ideally, steer the player to a different destination
156
+ * (`getDestinations`). `err.gameStatus` carries the current state.
157
+ *
158
+ * Deliberately distinct from {@link isSourceGameNotLive} — see the note there.
159
+ */
160
+ get isTargetGameNotLive() {
161
+ return this.code === "TARGET_GAME_NOT_LIVE";
162
+ }
163
+ /**
164
+ * The game's current status from a `*_GAME_NOT_LIVE` refusal (`game_status`, e.g.
165
+ * `"testing"`) — for rendering the actual state. Present on both the source and target
166
+ * refusals.
167
+ */
168
+ get gameStatus() {
169
+ const v = this.bodyObject()["game_status"];
170
+ return typeof v === "string" && v ? v : void 0;
171
+ }
172
+ /**
173
+ * True if the tenant has **no verified WebAuthn RP ID**, so passkey endpoints are dark
174
+ * (`WEBAUTHN_NOT_ENABLED_FOR_TENANT`, 403).
175
+ *
176
+ * **This is a configuration state, not a failure.** Passkey step-up is per-tenant and
177
+ * stays dark until the developer verifies a domain in the console. Treat it as
178
+ * "this tenant hasn't enabled passkeys yet" and fall back to the SMS/in-app path rather
179
+ * than surfacing an error to the player — the ceremony was never available to fail.
180
+ *
181
+ * This is currently the COMMON case, not an edge case: as of 2026-08-05 only 4 of 23
182
+ * sandbox tenants and **0 of 3 production tenants** have a verified RP ID. Every
183
+ * integration needs this branch until domain verification is widespread.
184
+ *
185
+ * The fix (for the developer's own tenant) is to verify a domain — see the passkey
186
+ * prerequisites in the README. Note this refusal carries the code on `code`, not
187
+ * `error_code`; the SDK reads both, so `err.code` is populated either way.
188
+ */
189
+ get isWebauthnNotEnabledForTenant() {
190
+ return this.code === "WEBAUTHN_NOT_ENABLED_FOR_TENANT";
191
+ }
131
192
  /** True if the phone-share (phone, requesting_email) pair was already approved. */
132
193
  get isPhoneShareAlreadyApproved() {
133
194
  return this.code === "PHONE_SHARE_ALREADY_APPROVED";
@@ -446,5 +507,5 @@ function toDestinationsResult(raw, direction) {
446
507
  }
447
508
 
448
509
  export { Http, InvoError, assertSecureBaseUrl, toDestinationsResult };
449
- //# sourceMappingURL=chunk-SPTYWJDN.js.map
450
- //# sourceMappingURL=chunk-SPTYWJDN.js.map
510
+ //# sourceMappingURL=chunk-BPZJ63RM.js.map
511
+ //# sourceMappingURL=chunk-BPZJ63RM.js.map
package/dist/index.cjs CHANGED
@@ -130,6 +130,67 @@ var InvoError = class _InvoError extends Error {
130
130
  get isNonSteamValueIntoSteamBlocked() {
131
131
  return this.code === "NON_STEAM_VALUE_INTO_STEAM_BLOCKED";
132
132
  }
133
+ /**
134
+ * True if the initiate was refused because **the caller's OWN game is in testing**
135
+ * (`SOURCE_GAME_NOT_LIVE`, 403). Reaches this SDK via `initiateSend` / `initiateTransfer`;
136
+ * the backend uses the same code on its Amazon rewards-send path too (not wrapped here),
137
+ * so one branch keeps working if that flow is ever added.
138
+ *
139
+ * **The caller can self-serve this**: switch the game to Live in the developer console
140
+ * (Game Settings → Status). Show `err.message` — it names the game and the exact control.
141
+ * `err.gameStatus` carries the current state if you want to render it.
142
+ *
143
+ * Deliberately distinct from {@link isTargetGameNotLive} — do NOT collapse the two into
144
+ * one "not live" case. The remediation differs: this one the developer can fix, the
145
+ * other one they cannot.
146
+ */
147
+ get isSourceGameNotLive() {
148
+ return this.code === "SOURCE_GAME_NOT_LIVE";
149
+ }
150
+ /**
151
+ * True if the initiate was refused because **the DESTINATION game is in testing**
152
+ * (`TARGET_GAME_NOT_LIVE`, 403). Reaches this SDK via `initiateSend` / `initiateTransfer`;
153
+ * same backend vocabulary on the Amazon rewards-send path (not wrapped here).
154
+ *
155
+ * **The caller usually CANNOT fix this** — the destination is another developer's game
156
+ * and only its owner can switch it to Live. Don't offer a "go fix it" action; show
157
+ * `err.message` and, ideally, steer the player to a different destination
158
+ * (`getDestinations`). `err.gameStatus` carries the current state.
159
+ *
160
+ * Deliberately distinct from {@link isSourceGameNotLive} — see the note there.
161
+ */
162
+ get isTargetGameNotLive() {
163
+ return this.code === "TARGET_GAME_NOT_LIVE";
164
+ }
165
+ /**
166
+ * The game's current status from a `*_GAME_NOT_LIVE` refusal (`game_status`, e.g.
167
+ * `"testing"`) — for rendering the actual state. Present on both the source and target
168
+ * refusals.
169
+ */
170
+ get gameStatus() {
171
+ const v = this.bodyObject()["game_status"];
172
+ return typeof v === "string" && v ? v : void 0;
173
+ }
174
+ /**
175
+ * True if the tenant has **no verified WebAuthn RP ID**, so passkey endpoints are dark
176
+ * (`WEBAUTHN_NOT_ENABLED_FOR_TENANT`, 403).
177
+ *
178
+ * **This is a configuration state, not a failure.** Passkey step-up is per-tenant and
179
+ * stays dark until the developer verifies a domain in the console. Treat it as
180
+ * "this tenant hasn't enabled passkeys yet" and fall back to the SMS/in-app path rather
181
+ * than surfacing an error to the player — the ceremony was never available to fail.
182
+ *
183
+ * This is currently the COMMON case, not an edge case: as of 2026-08-05 only 4 of 23
184
+ * sandbox tenants and **0 of 3 production tenants** have a verified RP ID. Every
185
+ * integration needs this branch until domain verification is widespread.
186
+ *
187
+ * The fix (for the developer's own tenant) is to verify a domain — see the passkey
188
+ * prerequisites in the README. Note this refusal carries the code on `code`, not
189
+ * `error_code`; the SDK reads both, so `err.code` is populated either way.
190
+ */
191
+ get isWebauthnNotEnabledForTenant() {
192
+ return this.code === "WEBAUTHN_NOT_ENABLED_FOR_TENANT";
193
+ }
133
194
  /** True if the phone-share (phone, requesting_email) pair was already approved. */
134
195
  get isPhoneShareAlreadyApproved() {
135
196
  return this.code === "PHONE_SHARE_ALREADY_APPROVED";
package/dist/index.d.cts CHANGED
@@ -1,5 +1,5 @@
1
- import { M as MountCheckoutOptions, C as CheckoutMountHandle, a as ClientConfig, b as CallOptions, A as ApproveResult, c as ConfirmReceiptResult, L as LinkDeviceResult, P as PendingCollectResult, D as DestinationsQuery, d as DestinationsResult, B as BalanceResult, E as EnrollmentBeginResult, e as EnrollmentVerifyResult, R as RecoveryBeginResult, f as RecoveryCompleteResult } from './types-DMNXAGiw.cjs';
2
- export { g as BalanceRow, h as DestinationGame, I as InvoError, i as InvoErrorInfo, j as InvoHooks, k as InvoRequestInfo, l as InvoResponseInfo, m as PendingCollectItem, n as Rail, V as VerificationMethod } from './types-DMNXAGiw.cjs';
1
+ import { M as MountCheckoutOptions, C as CheckoutMountHandle, a as ClientConfig, b as CallOptions, A as ApproveResult, c as ConfirmReceiptResult, L as LinkDeviceResult, P as PendingCollectResult, D as DestinationsQuery, d as DestinationsResult, B as BalanceResult, E as EnrollmentBeginResult, e as EnrollmentVerifyResult, R as RecoveryBeginResult, f as RecoveryCompleteResult } from './types-DjY-50jn.cjs';
2
+ export { g as BalanceRow, h as DestinationGame, I as InvoError, i as InvoErrorInfo, j as InvoHooks, k as InvoRequestInfo, l as InvoResponseInfo, m as PendingCollectItem, n as Rail, V as VerificationMethod } from './types-DjY-50jn.cjs';
3
3
 
4
4
  declare class PlatformCommerceClient {
5
5
  /**
package/dist/index.d.ts CHANGED
@@ -1,5 +1,5 @@
1
- import { M as MountCheckoutOptions, C as CheckoutMountHandle, a as ClientConfig, b as CallOptions, A as ApproveResult, c as ConfirmReceiptResult, L as LinkDeviceResult, P as PendingCollectResult, D as DestinationsQuery, d as DestinationsResult, B as BalanceResult, E as EnrollmentBeginResult, e as EnrollmentVerifyResult, R as RecoveryBeginResult, f as RecoveryCompleteResult } from './types-DMNXAGiw.js';
2
- export { g as BalanceRow, h as DestinationGame, I as InvoError, i as InvoErrorInfo, j as InvoHooks, k as InvoRequestInfo, l as InvoResponseInfo, m as PendingCollectItem, n as Rail, V as VerificationMethod } from './types-DMNXAGiw.js';
1
+ import { M as MountCheckoutOptions, C as CheckoutMountHandle, a as ClientConfig, b as CallOptions, A as ApproveResult, c as ConfirmReceiptResult, L as LinkDeviceResult, P as PendingCollectResult, D as DestinationsQuery, d as DestinationsResult, B as BalanceResult, E as EnrollmentBeginResult, e as EnrollmentVerifyResult, R as RecoveryBeginResult, f as RecoveryCompleteResult } from './types-DjY-50jn.js';
2
+ export { g as BalanceRow, h as DestinationGame, I as InvoError, i as InvoErrorInfo, j as InvoHooks, k as InvoRequestInfo, l as InvoResponseInfo, m as PendingCollectItem, n as Rail, V as VerificationMethod } from './types-DjY-50jn.js';
3
3
 
4
4
  declare class PlatformCommerceClient {
5
5
  /**
package/dist/index.js CHANGED
@@ -1,5 +1,5 @@
1
- import { InvoError, assertSecureBaseUrl, Http, toDestinationsResult } from './chunk-SPTYWJDN.js';
2
- export { InvoError } from './chunk-SPTYWJDN.js';
1
+ import { InvoError, assertSecureBaseUrl, Http, toDestinationsResult } from './chunk-BPZJ63RM.js';
2
+ export { InvoError } from './chunk-BPZJ63RM.js';
3
3
 
4
4
  // src/shared/webauthn.ts
5
5
  function malformedOptions(field) {
package/dist/server.cjs CHANGED
@@ -132,6 +132,67 @@ var InvoError = class _InvoError extends Error {
132
132
  get isNonSteamValueIntoSteamBlocked() {
133
133
  return this.code === "NON_STEAM_VALUE_INTO_STEAM_BLOCKED";
134
134
  }
135
+ /**
136
+ * True if the initiate was refused because **the caller's OWN game is in testing**
137
+ * (`SOURCE_GAME_NOT_LIVE`, 403). Reaches this SDK via `initiateSend` / `initiateTransfer`;
138
+ * the backend uses the same code on its Amazon rewards-send path too (not wrapped here),
139
+ * so one branch keeps working if that flow is ever added.
140
+ *
141
+ * **The caller can self-serve this**: switch the game to Live in the developer console
142
+ * (Game Settings → Status). Show `err.message` — it names the game and the exact control.
143
+ * `err.gameStatus` carries the current state if you want to render it.
144
+ *
145
+ * Deliberately distinct from {@link isTargetGameNotLive} — do NOT collapse the two into
146
+ * one "not live" case. The remediation differs: this one the developer can fix, the
147
+ * other one they cannot.
148
+ */
149
+ get isSourceGameNotLive() {
150
+ return this.code === "SOURCE_GAME_NOT_LIVE";
151
+ }
152
+ /**
153
+ * True if the initiate was refused because **the DESTINATION game is in testing**
154
+ * (`TARGET_GAME_NOT_LIVE`, 403). Reaches this SDK via `initiateSend` / `initiateTransfer`;
155
+ * same backend vocabulary on the Amazon rewards-send path (not wrapped here).
156
+ *
157
+ * **The caller usually CANNOT fix this** — the destination is another developer's game
158
+ * and only its owner can switch it to Live. Don't offer a "go fix it" action; show
159
+ * `err.message` and, ideally, steer the player to a different destination
160
+ * (`getDestinations`). `err.gameStatus` carries the current state.
161
+ *
162
+ * Deliberately distinct from {@link isSourceGameNotLive} — see the note there.
163
+ */
164
+ get isTargetGameNotLive() {
165
+ return this.code === "TARGET_GAME_NOT_LIVE";
166
+ }
167
+ /**
168
+ * The game's current status from a `*_GAME_NOT_LIVE` refusal (`game_status`, e.g.
169
+ * `"testing"`) — for rendering the actual state. Present on both the source and target
170
+ * refusals.
171
+ */
172
+ get gameStatus() {
173
+ const v = this.bodyObject()["game_status"];
174
+ return typeof v === "string" && v ? v : void 0;
175
+ }
176
+ /**
177
+ * True if the tenant has **no verified WebAuthn RP ID**, so passkey endpoints are dark
178
+ * (`WEBAUTHN_NOT_ENABLED_FOR_TENANT`, 403).
179
+ *
180
+ * **This is a configuration state, not a failure.** Passkey step-up is per-tenant and
181
+ * stays dark until the developer verifies a domain in the console. Treat it as
182
+ * "this tenant hasn't enabled passkeys yet" and fall back to the SMS/in-app path rather
183
+ * than surfacing an error to the player — the ceremony was never available to fail.
184
+ *
185
+ * This is currently the COMMON case, not an edge case: as of 2026-08-05 only 4 of 23
186
+ * sandbox tenants and **0 of 3 production tenants** have a verified RP ID. Every
187
+ * integration needs this branch until domain verification is widespread.
188
+ *
189
+ * The fix (for the developer's own tenant) is to verify a domain — see the passkey
190
+ * prerequisites in the README. Note this refusal carries the code on `code`, not
191
+ * `error_code`; the SDK reads both, so `err.code` is populated either way.
192
+ */
193
+ get isWebauthnNotEnabledForTenant() {
194
+ return this.code === "WEBAUTHN_NOT_ENABLED_FOR_TENANT";
195
+ }
135
196
  /** True if the phone-share (phone, requesting_email) pair was already approved. */
136
197
  get isPhoneShareAlreadyApproved() {
137
198
  return this.code === "PHONE_SHARE_ALREADY_APPROVED";
@@ -1428,10 +1489,22 @@ var InvoServer = class {
1428
1489
  };
1429
1490
  }
1430
1491
  /**
1431
- * Complete a TRANSFER's SMS-PIN step (un-enrolled fallback). NOT idempotent —
1432
- * each attempt is counted server-side, so this is never auto-retried. A bad PIN
1433
- * throws a 400 InvoError carrying `attempts_remaining` on `err.body`; a blocked
1434
- * recipient throws 429 (`sms_verification_blocked`).
1492
+ * Complete a TRANSFER's SMS-PIN step — the LAST-RESORT fallback for a sender who has
1493
+ * no passkey.
1494
+ *
1495
+ * @deprecated The SMS-PIN path is being phased out and a future major version will
1496
+ * remove this method. **Passkeys are the gold standard for authorizing money movement**
1497
+ * — an SMS PIN is a shared secret on a channel exposed to SIM swap and interception,
1498
+ * and it is not a peer of a WebAuthn assertion. When `initiate*` returns
1499
+ * `verificationMethod: "sms"` it is telling you the sender has no passkey: prompt
1500
+ * `InvoClient.enrollPasskey()` and then approve with
1501
+ * `InvoClient.approveTransfer(transactionId)`. Reach for this method only when the user
1502
+ * cannot enroll (unsupported device) or declines. Still fully functional — this
1503
+ * annotation changes documentation only, not behavior.
1504
+ *
1505
+ * NOT idempotent — each attempt is counted server-side, so this is never auto-retried.
1506
+ * A bad PIN throws a 400 InvoError carrying `attempts_remaining` on `err.body`; a
1507
+ * blocked recipient throws 429 (`sms_verification_blocked`).
1435
1508
  */
1436
1509
  async verifySmsTransfer(transactionId, smsPin, opts) {
1437
1510
  if (typeof transactionId !== "string" || !transactionId.trim()) {
@@ -1449,7 +1522,15 @@ var InvoServer = class {
1449
1522
  );
1450
1523
  return toSmsVerifyResult(raw);
1451
1524
  }
1452
- /** Complete a SEND's SMS-PIN step (un-enrolled fallback). See verifySmsTransfer. */
1525
+ /**
1526
+ * Complete a SEND's SMS-PIN step — the LAST-RESORT fallback for a sender who has no
1527
+ * passkey. See {@link verifySmsTransfer}.
1528
+ *
1529
+ * @deprecated The SMS-PIN path is being phased out and a future major version will
1530
+ * remove this method. Prompt `InvoClient.enrollPasskey()` and approve with
1531
+ * `InvoClient.approveSend(transactionId)` instead; use this only when the user cannot
1532
+ * enroll or declines. Documentation only — behavior is unchanged.
1533
+ */
1453
1534
  async verifySmsSend(transactionId, smsPin, opts) {
1454
1535
  if (typeof transactionId !== "string" || !transactionId.trim()) {
1455
1536
  throw invalidInput("transactionId", transactionId, "is required");
package/dist/server.d.cts CHANGED
@@ -1,5 +1,5 @@
1
- import { I as InvoError, H as Http, o as AuthHeader, p as PlatformPurchaseInput, b as CallOptions, q as PlatformPurchaseResult, r as PlatformOrderStatusResult, s as PlatformRefundInput, t as PlatformRefundResult, S as ServerConfig, u as PlayerToken, v as InitiateSendInput, w as InitiateResult, x as InitiateTransferInput, y as CreateCheckoutInput, z as CreateCheckoutResult, F as PurchaseInput, G as PurchaseResult, J as ConfirmPaymentResult, O as OrderDetailsResult, K as PurchaseItemInput, N as PurchaseItemResult, Q as ItemHistoryQuery, T as ItemHistoryResult, U as ItemOrderQuery, W as PlayerBalanceQuery, X as PlayerBalanceResult, Y as InboundPendingQuery, Z as InboundPendingResult, _ as LinkedIdentitiesQuery, $ as LinkedIdentitiesResult, a0 as SmsVerifyResult, a1 as ClaimTransferInput, a2 as ClaimResult, a3 as ClaimCurrencyInput, a4 as TransactionStatusResult, a5 as GuardianApprovalStatusResult, a6 as ServerDestinationsQuery, d as DestinationsResult, a7 as PhoneShareContact, a8 as PhoneShareInitiateResult, a9 as PhoneShareApproveInput, aa as PhoneShareApproveResult, ab as PhoneShareStatusResult } from './types-DMNXAGiw.cjs';
2
- export { ac as CurrencyBalance, h as DestinationGame, ad as FundingSource, ae as InboundPendingItem, i as InvoErrorInfo, j as InvoHooks, k as InvoRequestInfo, l as InvoResponseInfo, af as LinkedIdentityEmail, ag as PlatformPurchaseStatus, n as Rail, V as VerificationMethod } from './types-DMNXAGiw.cjs';
1
+ import { I as InvoError, H as Http, o as AuthHeader, p as PlatformPurchaseInput, b as CallOptions, q as PlatformPurchaseResult, r as PlatformOrderStatusResult, s as PlatformRefundInput, t as PlatformRefundResult, S as ServerConfig, u as PlayerToken, v as InitiateSendInput, w as InitiateResult, x as InitiateTransferInput, y as CreateCheckoutInput, z as CreateCheckoutResult, F as PurchaseInput, G as PurchaseResult, J as ConfirmPaymentResult, O as OrderDetailsResult, K as PurchaseItemInput, N as PurchaseItemResult, Q as ItemHistoryQuery, T as ItemHistoryResult, U as ItemOrderQuery, W as PlayerBalanceQuery, X as PlayerBalanceResult, Y as InboundPendingQuery, Z as InboundPendingResult, _ as LinkedIdentitiesQuery, $ as LinkedIdentitiesResult, a0 as SmsVerifyResult, a1 as ClaimTransferInput, a2 as ClaimResult, a3 as ClaimCurrencyInput, a4 as TransactionStatusResult, a5 as GuardianApprovalStatusResult, a6 as ServerDestinationsQuery, d as DestinationsResult, a7 as PhoneShareContact, a8 as PhoneShareInitiateResult, a9 as PhoneShareApproveInput, aa as PhoneShareApproveResult, ab as PhoneShareStatusResult } from './types-DjY-50jn.cjs';
2
+ export { ac as CurrencyBalance, h as DestinationGame, ad as FundingSource, ae as InboundPendingItem, i as InvoErrorInfo, j as InvoHooks, k as InvoRequestInfo, l as InvoResponseInfo, af as LinkedIdentityEmail, ag as PlatformPurchaseStatus, n as Rail, V as VerificationMethod } from './types-DjY-50jn.cjs';
3
3
 
4
4
  interface VerifyWebhookOptions {
5
5
  /** Max age of the signed timestamp, in seconds. Default 300 (5 min). */
@@ -365,13 +365,33 @@ declare class InvoServer {
365
365
  */
366
366
  getLinkedIdentities(query: LinkedIdentitiesQuery, opts?: CallOptions): Promise<LinkedIdentitiesResult>;
367
367
  /**
368
- * Complete a TRANSFER's SMS-PIN step (un-enrolled fallback). NOT idempotent —
369
- * each attempt is counted server-side, so this is never auto-retried. A bad PIN
370
- * throws a 400 InvoError carrying `attempts_remaining` on `err.body`; a blocked
371
- * recipient throws 429 (`sms_verification_blocked`).
368
+ * Complete a TRANSFER's SMS-PIN step — the LAST-RESORT fallback for a sender who has
369
+ * no passkey.
370
+ *
371
+ * @deprecated The SMS-PIN path is being phased out and a future major version will
372
+ * remove this method. **Passkeys are the gold standard for authorizing money movement**
373
+ * — an SMS PIN is a shared secret on a channel exposed to SIM swap and interception,
374
+ * and it is not a peer of a WebAuthn assertion. When `initiate*` returns
375
+ * `verificationMethod: "sms"` it is telling you the sender has no passkey: prompt
376
+ * `InvoClient.enrollPasskey()` and then approve with
377
+ * `InvoClient.approveTransfer(transactionId)`. Reach for this method only when the user
378
+ * cannot enroll (unsupported device) or declines. Still fully functional — this
379
+ * annotation changes documentation only, not behavior.
380
+ *
381
+ * NOT idempotent — each attempt is counted server-side, so this is never auto-retried.
382
+ * A bad PIN throws a 400 InvoError carrying `attempts_remaining` on `err.body`; a
383
+ * blocked recipient throws 429 (`sms_verification_blocked`).
372
384
  */
373
385
  verifySmsTransfer(transactionId: string, smsPin: string, opts?: CallOptions): Promise<SmsVerifyResult>;
374
- /** Complete a SEND's SMS-PIN step (un-enrolled fallback). See verifySmsTransfer. */
386
+ /**
387
+ * Complete a SEND's SMS-PIN step — the LAST-RESORT fallback for a sender who has no
388
+ * passkey. See {@link verifySmsTransfer}.
389
+ *
390
+ * @deprecated The SMS-PIN path is being phased out and a future major version will
391
+ * remove this method. Prompt `InvoClient.enrollPasskey()` and approve with
392
+ * `InvoClient.approveSend(transactionId)` instead; use this only when the user cannot
393
+ * enroll or declines. Documentation only — behavior is unchanged.
394
+ */
375
395
  verifySmsSend(transactionId: string, smsPin: string, opts?: CallOptions): Promise<SmsVerifyResult>;
376
396
  /**
377
397
  * Claim an inbound TRANSFER by its claim code, crediting one of this game's currencies.
package/dist/server.d.ts CHANGED
@@ -1,5 +1,5 @@
1
- import { I as InvoError, H as Http, o as AuthHeader, p as PlatformPurchaseInput, b as CallOptions, q as PlatformPurchaseResult, r as PlatformOrderStatusResult, s as PlatformRefundInput, t as PlatformRefundResult, S as ServerConfig, u as PlayerToken, v as InitiateSendInput, w as InitiateResult, x as InitiateTransferInput, y as CreateCheckoutInput, z as CreateCheckoutResult, F as PurchaseInput, G as PurchaseResult, J as ConfirmPaymentResult, O as OrderDetailsResult, K as PurchaseItemInput, N as PurchaseItemResult, Q as ItemHistoryQuery, T as ItemHistoryResult, U as ItemOrderQuery, W as PlayerBalanceQuery, X as PlayerBalanceResult, Y as InboundPendingQuery, Z as InboundPendingResult, _ as LinkedIdentitiesQuery, $ as LinkedIdentitiesResult, a0 as SmsVerifyResult, a1 as ClaimTransferInput, a2 as ClaimResult, a3 as ClaimCurrencyInput, a4 as TransactionStatusResult, a5 as GuardianApprovalStatusResult, a6 as ServerDestinationsQuery, d as DestinationsResult, a7 as PhoneShareContact, a8 as PhoneShareInitiateResult, a9 as PhoneShareApproveInput, aa as PhoneShareApproveResult, ab as PhoneShareStatusResult } from './types-DMNXAGiw.js';
2
- export { ac as CurrencyBalance, h as DestinationGame, ad as FundingSource, ae as InboundPendingItem, i as InvoErrorInfo, j as InvoHooks, k as InvoRequestInfo, l as InvoResponseInfo, af as LinkedIdentityEmail, ag as PlatformPurchaseStatus, n as Rail, V as VerificationMethod } from './types-DMNXAGiw.js';
1
+ import { I as InvoError, H as Http, o as AuthHeader, p as PlatformPurchaseInput, b as CallOptions, q as PlatformPurchaseResult, r as PlatformOrderStatusResult, s as PlatformRefundInput, t as PlatformRefundResult, S as ServerConfig, u as PlayerToken, v as InitiateSendInput, w as InitiateResult, x as InitiateTransferInput, y as CreateCheckoutInput, z as CreateCheckoutResult, F as PurchaseInput, G as PurchaseResult, J as ConfirmPaymentResult, O as OrderDetailsResult, K as PurchaseItemInput, N as PurchaseItemResult, Q as ItemHistoryQuery, T as ItemHistoryResult, U as ItemOrderQuery, W as PlayerBalanceQuery, X as PlayerBalanceResult, Y as InboundPendingQuery, Z as InboundPendingResult, _ as LinkedIdentitiesQuery, $ as LinkedIdentitiesResult, a0 as SmsVerifyResult, a1 as ClaimTransferInput, a2 as ClaimResult, a3 as ClaimCurrencyInput, a4 as TransactionStatusResult, a5 as GuardianApprovalStatusResult, a6 as ServerDestinationsQuery, d as DestinationsResult, a7 as PhoneShareContact, a8 as PhoneShareInitiateResult, a9 as PhoneShareApproveInput, aa as PhoneShareApproveResult, ab as PhoneShareStatusResult } from './types-DjY-50jn.js';
2
+ export { ac as CurrencyBalance, h as DestinationGame, ad as FundingSource, ae as InboundPendingItem, i as InvoErrorInfo, j as InvoHooks, k as InvoRequestInfo, l as InvoResponseInfo, af as LinkedIdentityEmail, ag as PlatformPurchaseStatus, n as Rail, V as VerificationMethod } from './types-DjY-50jn.js';
3
3
 
4
4
  interface VerifyWebhookOptions {
5
5
  /** Max age of the signed timestamp, in seconds. Default 300 (5 min). */
@@ -365,13 +365,33 @@ declare class InvoServer {
365
365
  */
366
366
  getLinkedIdentities(query: LinkedIdentitiesQuery, opts?: CallOptions): Promise<LinkedIdentitiesResult>;
367
367
  /**
368
- * Complete a TRANSFER's SMS-PIN step (un-enrolled fallback). NOT idempotent —
369
- * each attempt is counted server-side, so this is never auto-retried. A bad PIN
370
- * throws a 400 InvoError carrying `attempts_remaining` on `err.body`; a blocked
371
- * recipient throws 429 (`sms_verification_blocked`).
368
+ * Complete a TRANSFER's SMS-PIN step — the LAST-RESORT fallback for a sender who has
369
+ * no passkey.
370
+ *
371
+ * @deprecated The SMS-PIN path is being phased out and a future major version will
372
+ * remove this method. **Passkeys are the gold standard for authorizing money movement**
373
+ * — an SMS PIN is a shared secret on a channel exposed to SIM swap and interception,
374
+ * and it is not a peer of a WebAuthn assertion. When `initiate*` returns
375
+ * `verificationMethod: "sms"` it is telling you the sender has no passkey: prompt
376
+ * `InvoClient.enrollPasskey()` and then approve with
377
+ * `InvoClient.approveTransfer(transactionId)`. Reach for this method only when the user
378
+ * cannot enroll (unsupported device) or declines. Still fully functional — this
379
+ * annotation changes documentation only, not behavior.
380
+ *
381
+ * NOT idempotent — each attempt is counted server-side, so this is never auto-retried.
382
+ * A bad PIN throws a 400 InvoError carrying `attempts_remaining` on `err.body`; a
383
+ * blocked recipient throws 429 (`sms_verification_blocked`).
372
384
  */
373
385
  verifySmsTransfer(transactionId: string, smsPin: string, opts?: CallOptions): Promise<SmsVerifyResult>;
374
- /** Complete a SEND's SMS-PIN step (un-enrolled fallback). See verifySmsTransfer. */
386
+ /**
387
+ * Complete a SEND's SMS-PIN step — the LAST-RESORT fallback for a sender who has no
388
+ * passkey. See {@link verifySmsTransfer}.
389
+ *
390
+ * @deprecated The SMS-PIN path is being phased out and a future major version will
391
+ * remove this method. Prompt `InvoClient.enrollPasskey()` and approve with
392
+ * `InvoClient.approveSend(transactionId)` instead; use this only when the user cannot
393
+ * enroll or declines. Documentation only — behavior is unchanged.
394
+ */
375
395
  verifySmsSend(transactionId: string, smsPin: string, opts?: CallOptions): Promise<SmsVerifyResult>;
376
396
  /**
377
397
  * Claim an inbound TRANSFER by its claim code, crediting one of this game's currencies.
package/dist/server.js CHANGED
@@ -1,5 +1,5 @@
1
- import { InvoError, assertSecureBaseUrl, Http, toDestinationsResult } from './chunk-SPTYWJDN.js';
2
- export { InvoError } from './chunk-SPTYWJDN.js';
1
+ import { InvoError, assertSecureBaseUrl, Http, toDestinationsResult } from './chunk-BPZJ63RM.js';
2
+ export { InvoError } from './chunk-BPZJ63RM.js';
3
3
  import { createHmac, timingSafeEqual } from 'crypto';
4
4
 
5
5
  var DEFAULT_TOLERANCE_SEC = 300;
@@ -982,10 +982,22 @@ var InvoServer = class {
982
982
  };
983
983
  }
984
984
  /**
985
- * Complete a TRANSFER's SMS-PIN step (un-enrolled fallback). NOT idempotent —
986
- * each attempt is counted server-side, so this is never auto-retried. A bad PIN
987
- * throws a 400 InvoError carrying `attempts_remaining` on `err.body`; a blocked
988
- * recipient throws 429 (`sms_verification_blocked`).
985
+ * Complete a TRANSFER's SMS-PIN step — the LAST-RESORT fallback for a sender who has
986
+ * no passkey.
987
+ *
988
+ * @deprecated The SMS-PIN path is being phased out and a future major version will
989
+ * remove this method. **Passkeys are the gold standard for authorizing money movement**
990
+ * — an SMS PIN is a shared secret on a channel exposed to SIM swap and interception,
991
+ * and it is not a peer of a WebAuthn assertion. When `initiate*` returns
992
+ * `verificationMethod: "sms"` it is telling you the sender has no passkey: prompt
993
+ * `InvoClient.enrollPasskey()` and then approve with
994
+ * `InvoClient.approveTransfer(transactionId)`. Reach for this method only when the user
995
+ * cannot enroll (unsupported device) or declines. Still fully functional — this
996
+ * annotation changes documentation only, not behavior.
997
+ *
998
+ * NOT idempotent — each attempt is counted server-side, so this is never auto-retried.
999
+ * A bad PIN throws a 400 InvoError carrying `attempts_remaining` on `err.body`; a
1000
+ * blocked recipient throws 429 (`sms_verification_blocked`).
989
1001
  */
990
1002
  async verifySmsTransfer(transactionId, smsPin, opts) {
991
1003
  if (typeof transactionId !== "string" || !transactionId.trim()) {
@@ -1003,7 +1015,15 @@ var InvoServer = class {
1003
1015
  );
1004
1016
  return toSmsVerifyResult(raw);
1005
1017
  }
1006
- /** Complete a SEND's SMS-PIN step (un-enrolled fallback). See verifySmsTransfer. */
1018
+ /**
1019
+ * Complete a SEND's SMS-PIN step — the LAST-RESORT fallback for a sender who has no
1020
+ * passkey. See {@link verifySmsTransfer}.
1021
+ *
1022
+ * @deprecated The SMS-PIN path is being phased out and a future major version will
1023
+ * remove this method. Prompt `InvoClient.enrollPasskey()` and approve with
1024
+ * `InvoClient.approveSend(transactionId)` instead; use this only when the user cannot
1025
+ * enroll or declines. Documentation only — behavior is unchanged.
1026
+ */
1007
1027
  async verifySmsSend(transactionId, smsPin, opts) {
1008
1028
  if (typeof transactionId !== "string" || !transactionId.trim()) {
1009
1029
  throw invalidInput("transactionId", transactionId, "is required");
@@ -100,6 +100,58 @@ declare class InvoError extends Error {
100
100
  * pick a non-Steam destination (surfaced via `DestinationGame.acceptsSteamOriginValue`).
101
101
  */
102
102
  get isNonSteamValueIntoSteamBlocked(): boolean;
103
+ /**
104
+ * True if the initiate was refused because **the caller's OWN game is in testing**
105
+ * (`SOURCE_GAME_NOT_LIVE`, 403). Reaches this SDK via `initiateSend` / `initiateTransfer`;
106
+ * the backend uses the same code on its Amazon rewards-send path too (not wrapped here),
107
+ * so one branch keeps working if that flow is ever added.
108
+ *
109
+ * **The caller can self-serve this**: switch the game to Live in the developer console
110
+ * (Game Settings → Status). Show `err.message` — it names the game and the exact control.
111
+ * `err.gameStatus` carries the current state if you want to render it.
112
+ *
113
+ * Deliberately distinct from {@link isTargetGameNotLive} — do NOT collapse the two into
114
+ * one "not live" case. The remediation differs: this one the developer can fix, the
115
+ * other one they cannot.
116
+ */
117
+ get isSourceGameNotLive(): boolean;
118
+ /**
119
+ * True if the initiate was refused because **the DESTINATION game is in testing**
120
+ * (`TARGET_GAME_NOT_LIVE`, 403). Reaches this SDK via `initiateSend` / `initiateTransfer`;
121
+ * same backend vocabulary on the Amazon rewards-send path (not wrapped here).
122
+ *
123
+ * **The caller usually CANNOT fix this** — the destination is another developer's game
124
+ * and only its owner can switch it to Live. Don't offer a "go fix it" action; show
125
+ * `err.message` and, ideally, steer the player to a different destination
126
+ * (`getDestinations`). `err.gameStatus` carries the current state.
127
+ *
128
+ * Deliberately distinct from {@link isSourceGameNotLive} — see the note there.
129
+ */
130
+ get isTargetGameNotLive(): boolean;
131
+ /**
132
+ * The game's current status from a `*_GAME_NOT_LIVE` refusal (`game_status`, e.g.
133
+ * `"testing"`) — for rendering the actual state. Present on both the source and target
134
+ * refusals.
135
+ */
136
+ get gameStatus(): string | undefined;
137
+ /**
138
+ * True if the tenant has **no verified WebAuthn RP ID**, so passkey endpoints are dark
139
+ * (`WEBAUTHN_NOT_ENABLED_FOR_TENANT`, 403).
140
+ *
141
+ * **This is a configuration state, not a failure.** Passkey step-up is per-tenant and
142
+ * stays dark until the developer verifies a domain in the console. Treat it as
143
+ * "this tenant hasn't enabled passkeys yet" and fall back to the SMS/in-app path rather
144
+ * than surfacing an error to the player — the ceremony was never available to fail.
145
+ *
146
+ * This is currently the COMMON case, not an edge case: as of 2026-08-05 only 4 of 23
147
+ * sandbox tenants and **0 of 3 production tenants** have a verified RP ID. Every
148
+ * integration needs this branch until domain verification is widespread.
149
+ *
150
+ * The fix (for the developer's own tenant) is to verify a domain — see the passkey
151
+ * prerequisites in the README. Note this refusal carries the code on `code`, not
152
+ * `error_code`; the SDK reads both, so `err.code` is populated either way.
153
+ */
154
+ get isWebauthnNotEnabledForTenant(): boolean;
103
155
  /** True if the phone-share (phone, requesting_email) pair was already approved. */
104
156
  get isPhoneShareAlreadyApproved(): boolean;
105
157
  /** True if an idempotency-keyed request was a duplicate (item / platform purchase → 409). */
@@ -223,7 +275,14 @@ interface CallOptions {
223
275
  /** Public, neutral payment-rail names. Provider/processor names are an internal
224
276
  * backend routing detail and are deliberately NOT exposed here. */
225
277
  type Rail = "platform" | "game" | "steam";
226
- /** Verification method returned by initiate-send / initiate-transfer. */
278
+ /**
279
+ * Verification method returned by initiate-send / initiate-transfer.
280
+ *
281
+ * These are NOT two equivalent options. `"in_app"` is the passkey (WebAuthn) approve —
282
+ * the gold standard and the path to build for. `"sms"` means the sender has **no passkey
283
+ * enrolled** and the backend fell back to a PIN; treat it as a prompt to enroll, not as a
284
+ * destination. The SMS-PIN path is being phased out.
285
+ */
227
286
  type VerificationMethod = "in_app" | "sms";
228
287
  interface InvoConfig {
229
288
  /** API base URL. Prod: "https://invo.network". Sandbox: "https://sandbox.invo.network/sandbox". */
@@ -288,7 +347,11 @@ interface InitiateTransferInput {
288
347
  interface InitiateResult {
289
348
  transactionId: string;
290
349
  /**
291
- * "in_app" → proceed to the passkey approve flow; "sms" → un-enrolled fallback.
350
+ * `"in_app"` → the sender has a passkey; proceed to the approve flow (the recommended
351
+ * and only non-deprecated path). `"sms"` → the sender has **no passkey**, so a PIN was
352
+ * sent as a last-resort fallback — the best response is to offer `enrollPasskey()` and
353
+ * then `approveSend`/`approveTransfer`, falling back to the PIN pad only if they can't
354
+ * or won't enroll. The SMS-PIN completion is being phased out.
292
355
  * `undefined` when the backend returned the minor/guardian path (HTTP 202) and
293
356
  * no verification method applies yet — check `guardianApproval` and do NOT route
294
357
  * the user into the SMS-PIN UI in that case (§4.3 / §8).
@@ -752,6 +815,11 @@ interface LinkDeviceResult {
752
815
  status: string;
753
816
  raw: Record<string, unknown>;
754
817
  }
818
+ /**
819
+ * Result of `verifySmsTransfer` / `verifySmsSend` — the last-resort path for senders with
820
+ * no passkey. The SMS-PIN completion is being phased out; passkey approve
821
+ * (`InvoClient.approveSend` / `approveTransfer`) is the gold standard.
822
+ */
755
823
  interface SmsVerifyResult {
756
824
  /** "success" on a completed verification. */
757
825
  status: string;
@@ -100,6 +100,58 @@ declare class InvoError extends Error {
100
100
  * pick a non-Steam destination (surfaced via `DestinationGame.acceptsSteamOriginValue`).
101
101
  */
102
102
  get isNonSteamValueIntoSteamBlocked(): boolean;
103
+ /**
104
+ * True if the initiate was refused because **the caller's OWN game is in testing**
105
+ * (`SOURCE_GAME_NOT_LIVE`, 403). Reaches this SDK via `initiateSend` / `initiateTransfer`;
106
+ * the backend uses the same code on its Amazon rewards-send path too (not wrapped here),
107
+ * so one branch keeps working if that flow is ever added.
108
+ *
109
+ * **The caller can self-serve this**: switch the game to Live in the developer console
110
+ * (Game Settings → Status). Show `err.message` — it names the game and the exact control.
111
+ * `err.gameStatus` carries the current state if you want to render it.
112
+ *
113
+ * Deliberately distinct from {@link isTargetGameNotLive} — do NOT collapse the two into
114
+ * one "not live" case. The remediation differs: this one the developer can fix, the
115
+ * other one they cannot.
116
+ */
117
+ get isSourceGameNotLive(): boolean;
118
+ /**
119
+ * True if the initiate was refused because **the DESTINATION game is in testing**
120
+ * (`TARGET_GAME_NOT_LIVE`, 403). Reaches this SDK via `initiateSend` / `initiateTransfer`;
121
+ * same backend vocabulary on the Amazon rewards-send path (not wrapped here).
122
+ *
123
+ * **The caller usually CANNOT fix this** — the destination is another developer's game
124
+ * and only its owner can switch it to Live. Don't offer a "go fix it" action; show
125
+ * `err.message` and, ideally, steer the player to a different destination
126
+ * (`getDestinations`). `err.gameStatus` carries the current state.
127
+ *
128
+ * Deliberately distinct from {@link isSourceGameNotLive} — see the note there.
129
+ */
130
+ get isTargetGameNotLive(): boolean;
131
+ /**
132
+ * The game's current status from a `*_GAME_NOT_LIVE` refusal (`game_status`, e.g.
133
+ * `"testing"`) — for rendering the actual state. Present on both the source and target
134
+ * refusals.
135
+ */
136
+ get gameStatus(): string | undefined;
137
+ /**
138
+ * True if the tenant has **no verified WebAuthn RP ID**, so passkey endpoints are dark
139
+ * (`WEBAUTHN_NOT_ENABLED_FOR_TENANT`, 403).
140
+ *
141
+ * **This is a configuration state, not a failure.** Passkey step-up is per-tenant and
142
+ * stays dark until the developer verifies a domain in the console. Treat it as
143
+ * "this tenant hasn't enabled passkeys yet" and fall back to the SMS/in-app path rather
144
+ * than surfacing an error to the player — the ceremony was never available to fail.
145
+ *
146
+ * This is currently the COMMON case, not an edge case: as of 2026-08-05 only 4 of 23
147
+ * sandbox tenants and **0 of 3 production tenants** have a verified RP ID. Every
148
+ * integration needs this branch until domain verification is widespread.
149
+ *
150
+ * The fix (for the developer's own tenant) is to verify a domain — see the passkey
151
+ * prerequisites in the README. Note this refusal carries the code on `code`, not
152
+ * `error_code`; the SDK reads both, so `err.code` is populated either way.
153
+ */
154
+ get isWebauthnNotEnabledForTenant(): boolean;
103
155
  /** True if the phone-share (phone, requesting_email) pair was already approved. */
104
156
  get isPhoneShareAlreadyApproved(): boolean;
105
157
  /** True if an idempotency-keyed request was a duplicate (item / platform purchase → 409). */
@@ -223,7 +275,14 @@ interface CallOptions {
223
275
  /** Public, neutral payment-rail names. Provider/processor names are an internal
224
276
  * backend routing detail and are deliberately NOT exposed here. */
225
277
  type Rail = "platform" | "game" | "steam";
226
- /** Verification method returned by initiate-send / initiate-transfer. */
278
+ /**
279
+ * Verification method returned by initiate-send / initiate-transfer.
280
+ *
281
+ * These are NOT two equivalent options. `"in_app"` is the passkey (WebAuthn) approve —
282
+ * the gold standard and the path to build for. `"sms"` means the sender has **no passkey
283
+ * enrolled** and the backend fell back to a PIN; treat it as a prompt to enroll, not as a
284
+ * destination. The SMS-PIN path is being phased out.
285
+ */
227
286
  type VerificationMethod = "in_app" | "sms";
228
287
  interface InvoConfig {
229
288
  /** API base URL. Prod: "https://invo.network". Sandbox: "https://sandbox.invo.network/sandbox". */
@@ -288,7 +347,11 @@ interface InitiateTransferInput {
288
347
  interface InitiateResult {
289
348
  transactionId: string;
290
349
  /**
291
- * "in_app" → proceed to the passkey approve flow; "sms" → un-enrolled fallback.
350
+ * `"in_app"` → the sender has a passkey; proceed to the approve flow (the recommended
351
+ * and only non-deprecated path). `"sms"` → the sender has **no passkey**, so a PIN was
352
+ * sent as a last-resort fallback — the best response is to offer `enrollPasskey()` and
353
+ * then `approveSend`/`approveTransfer`, falling back to the PIN pad only if they can't
354
+ * or won't enroll. The SMS-PIN completion is being phased out.
292
355
  * `undefined` when the backend returned the minor/guardian path (HTTP 202) and
293
356
  * no verification method applies yet — check `guardianApproval` and do NOT route
294
357
  * the user into the SMS-PIN UI in that case (§4.3 / §8).
@@ -752,6 +815,11 @@ interface LinkDeviceResult {
752
815
  status: string;
753
816
  raw: Record<string, unknown>;
754
817
  }
818
+ /**
819
+ * Result of `verifySmsTransfer` / `verifySmsSend` — the last-resort path for senders with
820
+ * no passkey. The SMS-PIN completion is being phased out; passkey approve
821
+ * (`InvoClient.approveSend` / `approveTransfer`) is the gold standard.
822
+ */
755
823
  interface SmsVerifyResult {
756
824
  /** "success" on a completed verification. */
757
825
  status: string;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@invonetwork/web-sdk",
3
- "version": "3.0.0",
3
+ "version": "3.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,