@invonetwork/web-sdk 3.0.0 → 3.2.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/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
 
@@ -4,6 +4,7 @@ var InvoError = class _InvoError extends Error {
4
4
  super(args.message);
5
5
  this.name = "InvoError";
6
6
  this.code = args.code;
7
+ this.rawCode = args.rawCode ?? args.code;
7
8
  this.status = args.status;
8
9
  this.body = args.body ?? null;
9
10
  this.requestId = args.requestId;
@@ -128,6 +129,67 @@ var InvoError = class _InvoError extends Error {
128
129
  get isNonSteamValueIntoSteamBlocked() {
129
130
  return this.code === "NON_STEAM_VALUE_INTO_STEAM_BLOCKED";
130
131
  }
132
+ /**
133
+ * True if the initiate was refused because **the caller's OWN game is in testing**
134
+ * (`SOURCE_GAME_NOT_LIVE`, 403). Reaches this SDK via `initiateSend` / `initiateTransfer`;
135
+ * the backend uses the same code on its Amazon rewards-send path too (not wrapped here),
136
+ * so one branch keeps working if that flow is ever added.
137
+ *
138
+ * **The caller can self-serve this**: switch the game to Live in the developer console
139
+ * (Game Settings → Status). Show `err.message` — it names the game and the exact control.
140
+ * `err.gameStatus` carries the current state if you want to render it.
141
+ *
142
+ * Deliberately distinct from {@link isTargetGameNotLive} — do NOT collapse the two into
143
+ * one "not live" case. The remediation differs: this one the developer can fix, the
144
+ * other one they cannot.
145
+ */
146
+ get isSourceGameNotLive() {
147
+ return this.code === "SOURCE_GAME_NOT_LIVE";
148
+ }
149
+ /**
150
+ * True if the initiate was refused because **the DESTINATION game is in testing**
151
+ * (`TARGET_GAME_NOT_LIVE`, 403). Reaches this SDK via `initiateSend` / `initiateTransfer`;
152
+ * same backend vocabulary on the Amazon rewards-send path (not wrapped here).
153
+ *
154
+ * **The caller usually CANNOT fix this** — the destination is another developer's game
155
+ * and only its owner can switch it to Live. Don't offer a "go fix it" action; show
156
+ * `err.message` and, ideally, steer the player to a different destination
157
+ * (`getDestinations`). `err.gameStatus` carries the current state.
158
+ *
159
+ * Deliberately distinct from {@link isSourceGameNotLive} — see the note there.
160
+ */
161
+ get isTargetGameNotLive() {
162
+ return this.code === "TARGET_GAME_NOT_LIVE";
163
+ }
164
+ /**
165
+ * The game's current status from a `*_GAME_NOT_LIVE` refusal (`game_status`, e.g.
166
+ * `"testing"`) — for rendering the actual state. Present on both the source and target
167
+ * refusals.
168
+ */
169
+ get gameStatus() {
170
+ const v = this.bodyObject()["game_status"];
171
+ return typeof v === "string" && v ? v : void 0;
172
+ }
173
+ /**
174
+ * True if the tenant has **no verified WebAuthn RP ID**, so passkey endpoints are dark
175
+ * (`WEBAUTHN_NOT_ENABLED_FOR_TENANT`, 403).
176
+ *
177
+ * **This is a configuration state, not a failure.** Passkey step-up is per-tenant and
178
+ * stays dark until the developer verifies a domain in the console. Treat it as
179
+ * "this tenant hasn't enabled passkeys yet" and fall back to the SMS/in-app path rather
180
+ * than surfacing an error to the player — the ceremony was never available to fail.
181
+ *
182
+ * This is currently the COMMON case, not an edge case: as of 2026-08-05 only 4 of 23
183
+ * sandbox tenants and **0 of 3 production tenants** have a verified RP ID. Every
184
+ * integration needs this branch until domain verification is widespread.
185
+ *
186
+ * The fix (for the developer's own tenant) is to verify a domain — see the passkey
187
+ * prerequisites in the README. Note this refusal carries the code on `code`, not
188
+ * `error_code`; the SDK reads both, so `err.code` is populated either way.
189
+ */
190
+ get isWebauthnNotEnabledForTenant() {
191
+ return this.code === "WEBAUTHN_NOT_ENABLED_FOR_TENANT";
192
+ }
131
193
  /** True if the phone-share (phone, requesting_email) pair was already approved. */
132
194
  get isPhoneShareAlreadyApproved() {
133
195
  return this.code === "PHONE_SHARE_ALREADY_APPROVED";
@@ -150,10 +212,44 @@ var InvoError = class _InvoError extends Error {
150
212
  get isAmountBelowMinimum() {
151
213
  return this.code === "AMOUNT_BELOW_MINIMUM";
152
214
  }
215
+ /**
216
+ * True if the `rail` you sent disagrees with the storefront key you
217
+ * authenticated with (`RAIL_CHANNEL_MISMATCH`, 400).
218
+ *
219
+ * A storefront key already determines the rail, so the fix is to stop sending
220
+ * `rail` — not to send a different one. The error body carries `channel` and
221
+ * `rail` so you can see which storefront the key belongs to.
222
+ *
223
+ * INVO refuses rather than silently overriding, because silently overriding
224
+ * would bill a player through a route you did not ask for.
225
+ */
226
+ get isRailChannelMismatch() {
227
+ return this.code === "RAIL_CHANNEL_MISMATCH";
228
+ }
229
+ /**
230
+ * True if a Steam purchase was attempted for a title INVO has not registered
231
+ * as distributed on Steam (`STEAM_RAIL_NOT_ENTITLED`, 403).
232
+ *
233
+ * Holding a `steam` storefront key does not by itself register the title —
234
+ * only INVO can do that. This is not retryable; contact INVO.
235
+ */
236
+ get isSteamRailNotEntitled() {
237
+ return this.code === "STEAM_RAIL_NOT_ENTITLED";
238
+ }
239
+ /**
240
+ * True if a title distributed on Steam tried to sell currency on a non-Steam
241
+ * rail (`STEAM_PURCHASE_LAYER_REQUIRED`, 409).
242
+ *
243
+ * Currency for a Steam title must be bought through Steam. Use the dedicated
244
+ * Steam purchase flow. Not retryable on the same rail.
245
+ */
246
+ get isSteamPurchaseLayerRequired() {
247
+ return this.code === "STEAM_PURCHASE_LAYER_REQUIRED";
248
+ }
153
249
  /** True if a Platform Commerce CARD purchase was below the processor's floor of $0.50
154
250
  * (backend code `BELOW_STRIPE_MINIMUM`, 400). Neutral name; matches the wire code. */
155
251
  get isBelowCardMinimum() {
156
- return this.code === "BELOW_STRIPE_MINIMUM";
252
+ return this.code === "BELOW_CARD_MINIMUM" || this.rawCode === "BELOW_STRIPE_MINIMUM";
157
253
  }
158
254
  /** True if a Platform Commerce CARD purchase exceeded the hosted checkout's single-charge
159
255
  * cap of $999.99 (`ABOVE_CARD_MAXIMUM`, 400) — split the sale or lower the amount. */
@@ -183,10 +279,12 @@ var InvoError = class _InvoError extends Error {
183
279
  function errorFromResponse(status, body, requestId) {
184
280
  let message = `INVO request failed (HTTP ${status})`;
185
281
  let code;
282
+ let rawCode;
186
283
  if (body && typeof body === "object") {
187
284
  const b = body;
188
- if (typeof b["code"] === "string") code = b["code"];
189
- else if (typeof b["error_code"] === "string") code = b["error_code"];
285
+ if (typeof b["code"] === "string") rawCode = b["code"];
286
+ else if (typeof b["error_code"] === "string") rawCode = b["error_code"];
287
+ code = typeof b["error_code_public"] === "string" ? b["error_code_public"] : rawCode;
190
288
  if (typeof b["error"] === "string") message = b["error"];
191
289
  else if (typeof b["message"] === "string") message = b["message"];
192
290
  if (!code && typeof b["error"] === "string" && /^(flow_paused|spending_limit_exceeded|receiver_not_enrolled_use_claim_code|no_channel_on_file|rate_limited|service_unavailable)$/.test(
@@ -198,7 +296,7 @@ function errorFromResponse(status, body, requestId) {
198
296
  } else if (typeof body === "string" && body.trim()) {
199
297
  message = body;
200
298
  }
201
- return new InvoError({ message, code, status, body, requestId });
299
+ return new InvoError({ message, code, rawCode, status, body, requestId });
202
300
  }
203
301
 
204
302
  // src/shared/http.ts
@@ -446,5 +544,5 @@ function toDestinationsResult(raw, direction) {
446
544
  }
447
545
 
448
546
  export { Http, InvoError, assertSecureBaseUrl, toDestinationsResult };
449
- //# sourceMappingURL=chunk-SPTYWJDN.js.map
450
- //# sourceMappingURL=chunk-SPTYWJDN.js.map
547
+ //# sourceMappingURL=chunk-ZLPMCR5Q.js.map
548
+ //# sourceMappingURL=chunk-ZLPMCR5Q.js.map
package/dist/index.cjs CHANGED
@@ -6,6 +6,7 @@ var InvoError = class _InvoError extends Error {
6
6
  super(args.message);
7
7
  this.name = "InvoError";
8
8
  this.code = args.code;
9
+ this.rawCode = args.rawCode ?? args.code;
9
10
  this.status = args.status;
10
11
  this.body = args.body ?? null;
11
12
  this.requestId = args.requestId;
@@ -130,6 +131,67 @@ var InvoError = class _InvoError extends Error {
130
131
  get isNonSteamValueIntoSteamBlocked() {
131
132
  return this.code === "NON_STEAM_VALUE_INTO_STEAM_BLOCKED";
132
133
  }
134
+ /**
135
+ * True if the initiate was refused because **the caller's OWN game is in testing**
136
+ * (`SOURCE_GAME_NOT_LIVE`, 403). Reaches this SDK via `initiateSend` / `initiateTransfer`;
137
+ * the backend uses the same code on its Amazon rewards-send path too (not wrapped here),
138
+ * so one branch keeps working if that flow is ever added.
139
+ *
140
+ * **The caller can self-serve this**: switch the game to Live in the developer console
141
+ * (Game Settings → Status). Show `err.message` — it names the game and the exact control.
142
+ * `err.gameStatus` carries the current state if you want to render it.
143
+ *
144
+ * Deliberately distinct from {@link isTargetGameNotLive} — do NOT collapse the two into
145
+ * one "not live" case. The remediation differs: this one the developer can fix, the
146
+ * other one they cannot.
147
+ */
148
+ get isSourceGameNotLive() {
149
+ return this.code === "SOURCE_GAME_NOT_LIVE";
150
+ }
151
+ /**
152
+ * True if the initiate was refused because **the DESTINATION game is in testing**
153
+ * (`TARGET_GAME_NOT_LIVE`, 403). Reaches this SDK via `initiateSend` / `initiateTransfer`;
154
+ * same backend vocabulary on the Amazon rewards-send path (not wrapped here).
155
+ *
156
+ * **The caller usually CANNOT fix this** — the destination is another developer's game
157
+ * and only its owner can switch it to Live. Don't offer a "go fix it" action; show
158
+ * `err.message` and, ideally, steer the player to a different destination
159
+ * (`getDestinations`). `err.gameStatus` carries the current state.
160
+ *
161
+ * Deliberately distinct from {@link isSourceGameNotLive} — see the note there.
162
+ */
163
+ get isTargetGameNotLive() {
164
+ return this.code === "TARGET_GAME_NOT_LIVE";
165
+ }
166
+ /**
167
+ * The game's current status from a `*_GAME_NOT_LIVE` refusal (`game_status`, e.g.
168
+ * `"testing"`) — for rendering the actual state. Present on both the source and target
169
+ * refusals.
170
+ */
171
+ get gameStatus() {
172
+ const v = this.bodyObject()["game_status"];
173
+ return typeof v === "string" && v ? v : void 0;
174
+ }
175
+ /**
176
+ * True if the tenant has **no verified WebAuthn RP ID**, so passkey endpoints are dark
177
+ * (`WEBAUTHN_NOT_ENABLED_FOR_TENANT`, 403).
178
+ *
179
+ * **This is a configuration state, not a failure.** Passkey step-up is per-tenant and
180
+ * stays dark until the developer verifies a domain in the console. Treat it as
181
+ * "this tenant hasn't enabled passkeys yet" and fall back to the SMS/in-app path rather
182
+ * than surfacing an error to the player — the ceremony was never available to fail.
183
+ *
184
+ * This is currently the COMMON case, not an edge case: as of 2026-08-05 only 4 of 23
185
+ * sandbox tenants and **0 of 3 production tenants** have a verified RP ID. Every
186
+ * integration needs this branch until domain verification is widespread.
187
+ *
188
+ * The fix (for the developer's own tenant) is to verify a domain — see the passkey
189
+ * prerequisites in the README. Note this refusal carries the code on `code`, not
190
+ * `error_code`; the SDK reads both, so `err.code` is populated either way.
191
+ */
192
+ get isWebauthnNotEnabledForTenant() {
193
+ return this.code === "WEBAUTHN_NOT_ENABLED_FOR_TENANT";
194
+ }
133
195
  /** True if the phone-share (phone, requesting_email) pair was already approved. */
134
196
  get isPhoneShareAlreadyApproved() {
135
197
  return this.code === "PHONE_SHARE_ALREADY_APPROVED";
@@ -152,10 +214,44 @@ var InvoError = class _InvoError extends Error {
152
214
  get isAmountBelowMinimum() {
153
215
  return this.code === "AMOUNT_BELOW_MINIMUM";
154
216
  }
217
+ /**
218
+ * True if the `rail` you sent disagrees with the storefront key you
219
+ * authenticated with (`RAIL_CHANNEL_MISMATCH`, 400).
220
+ *
221
+ * A storefront key already determines the rail, so the fix is to stop sending
222
+ * `rail` — not to send a different one. The error body carries `channel` and
223
+ * `rail` so you can see which storefront the key belongs to.
224
+ *
225
+ * INVO refuses rather than silently overriding, because silently overriding
226
+ * would bill a player through a route you did not ask for.
227
+ */
228
+ get isRailChannelMismatch() {
229
+ return this.code === "RAIL_CHANNEL_MISMATCH";
230
+ }
231
+ /**
232
+ * True if a Steam purchase was attempted for a title INVO has not registered
233
+ * as distributed on Steam (`STEAM_RAIL_NOT_ENTITLED`, 403).
234
+ *
235
+ * Holding a `steam` storefront key does not by itself register the title —
236
+ * only INVO can do that. This is not retryable; contact INVO.
237
+ */
238
+ get isSteamRailNotEntitled() {
239
+ return this.code === "STEAM_RAIL_NOT_ENTITLED";
240
+ }
241
+ /**
242
+ * True if a title distributed on Steam tried to sell currency on a non-Steam
243
+ * rail (`STEAM_PURCHASE_LAYER_REQUIRED`, 409).
244
+ *
245
+ * Currency for a Steam title must be bought through Steam. Use the dedicated
246
+ * Steam purchase flow. Not retryable on the same rail.
247
+ */
248
+ get isSteamPurchaseLayerRequired() {
249
+ return this.code === "STEAM_PURCHASE_LAYER_REQUIRED";
250
+ }
155
251
  /** True if a Platform Commerce CARD purchase was below the processor's floor of $0.50
156
252
  * (backend code `BELOW_STRIPE_MINIMUM`, 400). Neutral name; matches the wire code. */
157
253
  get isBelowCardMinimum() {
158
- return this.code === "BELOW_STRIPE_MINIMUM";
254
+ return this.code === "BELOW_CARD_MINIMUM" || this.rawCode === "BELOW_STRIPE_MINIMUM";
159
255
  }
160
256
  /** True if a Platform Commerce CARD purchase exceeded the hosted checkout's single-charge
161
257
  * cap of $999.99 (`ABOVE_CARD_MAXIMUM`, 400) — split the sale or lower the amount. */
@@ -185,10 +281,12 @@ var InvoError = class _InvoError extends Error {
185
281
  function errorFromResponse(status, body, requestId) {
186
282
  let message = `INVO request failed (HTTP ${status})`;
187
283
  let code;
284
+ let rawCode;
188
285
  if (body && typeof body === "object") {
189
286
  const b = body;
190
- if (typeof b["code"] === "string") code = b["code"];
191
- else if (typeof b["error_code"] === "string") code = b["error_code"];
287
+ if (typeof b["code"] === "string") rawCode = b["code"];
288
+ else if (typeof b["error_code"] === "string") rawCode = b["error_code"];
289
+ code = typeof b["error_code_public"] === "string" ? b["error_code_public"] : rawCode;
192
290
  if (typeof b["error"] === "string") message = b["error"];
193
291
  else if (typeof b["message"] === "string") message = b["message"];
194
292
  if (!code && typeof b["error"] === "string" && /^(flow_paused|spending_limit_exceeded|receiver_not_enrolled_use_claim_code|no_channel_on_file|rate_limited|service_unavailable)$/.test(
@@ -200,7 +298,7 @@ function errorFromResponse(status, body, requestId) {
200
298
  } else if (typeof body === "string" && body.trim()) {
201
299
  message = body;
202
300
  }
203
- return new InvoError({ message, code, status, body, requestId });
301
+ return new InvoError({ message, code, rawCode, status, body, requestId });
204
302
  }
205
303
 
206
304
  // src/shared/http.ts
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-DzmukUr9.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-DzmukUr9.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-DzmukUr9.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-DzmukUr9.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-ZLPMCR5Q.js';
2
+ export { InvoError } from './chunk-ZLPMCR5Q.js';
3
3
 
4
4
  // src/shared/webauthn.ts
5
5
  function malformedOptions(field) {