@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 +75 -0
- package/README.md +98 -9
- package/dist/{chunk-SPTYWJDN.js → chunk-BPZJ63RM.js} +63 -2
- package/dist/index.cjs +61 -0
- package/dist/index.d.cts +2 -2
- package/dist/index.d.ts +2 -2
- package/dist/index.js +2 -2
- package/dist/server.cjs +86 -5
- package/dist/server.d.cts +27 -7
- package/dist/server.d.ts +27 -7
- package/dist/server.js +27 -7
- package/dist/{types-DMNXAGiw.d.cts → types-DjY-50jn.d.cts} +70 -2
- package/dist/{types-DMNXAGiw.d.ts → types-DjY-50jn.d.ts} +70 -2
- package/package.json +1 -1
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.
|
|
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.
|
|
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** (
|
|
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
|
|
450
|
-
case t.verificationMethod === "sms": //
|
|
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"` →
|
|
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)
|
|
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
|
-
|
|
|
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`
|
|
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-
|
|
450
|
-
//# sourceMappingURL=chunk-
|
|
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-
|
|
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-
|
|
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-
|
|
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-
|
|
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-
|
|
2
|
-
export { InvoError } from './chunk-
|
|
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
|
|
1432
|
-
*
|
|
1433
|
-
*
|
|
1434
|
-
*
|
|
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
|
-
/**
|
|
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-
|
|
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-
|
|
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
|
|
369
|
-
*
|
|
370
|
-
*
|
|
371
|
-
*
|
|
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
|
-
/**
|
|
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-
|
|
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-
|
|
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
|
|
369
|
-
*
|
|
370
|
-
*
|
|
371
|
-
*
|
|
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
|
-
/**
|
|
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-
|
|
2
|
-
export { InvoError } from './chunk-
|
|
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
|
|
986
|
-
*
|
|
987
|
-
*
|
|
988
|
-
*
|
|
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
|
-
/**
|
|
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
|
-
/**
|
|
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
|
|
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
|
-
/**
|
|
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
|
|
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