@invonetwork/web-sdk 2.5.1 → 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 +110 -0
- package/README.md +125 -39
- package/dist/{chunk-5X3ESHJR.js → chunk-BPZJ63RM.js} +68 -2
- package/dist/index.cjs +133 -189
- package/dist/index.d.cts +18 -39
- package/dist/index.d.ts +18 -39
- package/dist/index.js +69 -191
- package/dist/server.cjs +134 -69
- package/dist/server.d.cts +39 -19
- package/dist/server.d.ts +39 -19
- package/dist/server.js +70 -71
- package/dist/{types-BHvVjdMV.d.cts → types-DjY-50jn.d.cts} +115 -118
- package/dist/{types-BHvVjdMV.d.ts → types-DjY-50jn.d.ts} +115 -118
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -4,6 +4,116 @@ 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
|
+
|
|
82
|
+
## [3.0.0] — 2026-07-20
|
|
83
|
+
|
|
84
|
+
**BREAKING — the Platform Commerce card leg moved to INVO's hosted checkout.** The backend now
|
|
85
|
+
hosts the entire card flow (card fields, Apple Pay / Google Pay, billing-address collection,
|
|
86
|
+
3-D Secure) on its own checkout page, so the browser card-element surface shipped in 2.5.x is
|
|
87
|
+
gone. Card sales are simpler AND safer: server creates → buyer pays on `checkoutUrl` → fulfill
|
|
88
|
+
on the `platform_commerce.purchased` webhook. Note: the card leg is pending final enablement on
|
|
89
|
+
the backend (sandbox payment test) — the balance leg is fully live.
|
|
90
|
+
|
|
91
|
+
### Migration from 2.5.x (card leg only — balance/status/refund/webhooks unchanged)
|
|
92
|
+
- `platformCommerce.purchase({ fundingSource: "card" })`: **remove `billingAddress`** (the type
|
|
93
|
+
is gone; the hosted page collects it) and optionally pass `successUrl` / `cancelUrl` /
|
|
94
|
+
`metadata`. The result now carries `checkoutUrl` / `sessionId` / `expiresAt` (unix seconds) /
|
|
95
|
+
`idempotentReplay` — **`clientSecret` no longer exists.**
|
|
96
|
+
- Browser: **`confirmCardPayment` and `mountCardPayment` are removed** (with all card-element
|
|
97
|
+
types and the `commercePublishableKey` config). Replace with a redirect
|
|
98
|
+
(`location.href = checkoutUrl`) or the new optional embed:
|
|
99
|
+
`invo.platformCommerce.mountCheckout(el, checkoutUrl, { onComplete })` — an iframe plus an
|
|
100
|
+
origin-checked listener for the page's `INVO_CHECKOUT_COMPLETE` message.
|
|
101
|
+
- Card duplicates no longer 409: retrying `purchase` with the same `clientRequestId` **replays
|
|
102
|
+
the same checkout session** (`idempotentReplay: true`), so a lost response is recoverable.
|
|
103
|
+
|
|
104
|
+
### Added
|
|
105
|
+
- `PlatformPurchaseInput.successUrl/cancelUrl/metadata`; result fields
|
|
106
|
+
`sessionId/checkoutUrl/expiresAt/idempotentReplay`.
|
|
107
|
+
- `InvoClient.platformCommerce.mountCheckout(el, checkoutUrl, opts)` → `{ iframe, destroy() }`.
|
|
108
|
+
- `err.isAboveCardMaximum` (`ABOVE_CARD_MAXIMUM`, card > $999.99) + client-side card USD
|
|
109
|
+
bounds fail-fast ($0.50–$999.99).
|
|
110
|
+
- Card `requires_payment` responses without a `checkout_url` fail closed (`INVALID_RESPONSE`).
|
|
111
|
+
|
|
112
|
+
### Removed
|
|
113
|
+
- `confirmCardPayment`, `mountCardPayment`, `commercePublishableKey`, `BillingAddress`, and the
|
|
114
|
+
card-element/processor types + the runtime CDN script loader (no more processor touchpoints
|
|
115
|
+
in this SDK at all).
|
|
116
|
+
|
|
7
117
|
## [2.5.1] — 2026-07-20
|
|
8
118
|
|
|
9
119
|
Hardening patch from a second, independent post-release audit (correctness vs the backend
|
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:** `
|
|
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
|
|
@@ -13,7 +13,7 @@ Five money flows plus passkey (WebAuthn) authentication, split across a trusted
|
|
|
13
13
|
|---|---|---|---|---|
|
|
14
14
|
| **Currency purchase** | real money **→** game currency | yes (card/rails) | no | server initiates, browser opens hosted checkout |
|
|
15
15
|
| **Item purchase** | game currency **→** in-game item | no (balance debit) | no | server only |
|
|
16
|
-
| **Platform Commerce** (ecommerce) | balance **or** card **→** a storefront item | card leg only | no | server creates
|
|
16
|
+
| **Platform Commerce** (ecommerce) | balance **or** card **→** a storefront item | card leg only | no | server creates; buyer pays on INVO's **hosted checkout** |
|
|
17
17
|
| **Send** | currency **→** another player (cross-game) | no | yes (sender approves) | server initiates, browser approves/claims |
|
|
18
18
|
| **Transfer** | currency **→** another player (transfer rail) | no | yes (sender approves) | server initiates, browser approves/claims |
|
|
19
19
|
|
|
@@ -21,10 +21,57 @@ Five money flows plus passkey (WebAuthn) authentication, split across a trusted
|
|
|
21
21
|
> - **[Item purchase](#item-purchase-spend-game-currency)** — a **game** tenant. A player spends **game currency they already hold** on an **in-game** item (a sword, a skin). Always a balance debit — **never a card, never new money, no refunds**. `server.purchaseItem(...)` → `/api/item-purchases`.
|
|
22
22
|
> - **[Platform Commerce](#platform-commerce-ecommerce)** — a **platform** tenant (a non-game app: vertical video, creator merch, marketplace). A **storefront** sale funded by **INVO balance or a real card** (new money), with **INVO as merchant of record** and **refunds**. `server.platformCommerce.purchase(...)` → `/api/platform-commerce`. A game tenant calling it gets `403 NOT_A_PLATFORM_TENANT`.
|
|
23
23
|
|
|
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 `
|
|
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
|
+
|
|
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.
|
|
25
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
|
|
|
@@ -313,7 +360,7 @@ const item = await server.purchaseItem({
|
|
|
313
360
|
|
|
314
361
|
> **This is not [item purchase](#item-purchase-spend-game-currency).** Item purchase is a *game* tenant spending a player's *existing game currency* on an *in-game* item — always a balance debit, never a card, no refunds. **Platform Commerce is a _platform_ tenant (a non-game app: vertical video, creator merch, marketplace) running a storefront.** The buyer pays with **INVO balance** *or* a **real card** (new money), INVO is **merchant of record**, and **refunds** exist. Only platform tenants may call it — a game tenant gets `403` (`err.isNotPlatformTenant`).
|
|
315
362
|
|
|
316
|
-
The funding source is resolved **server-side under lock** — the client can *request* `balance` or `card`, but the backend verifies the real balance before any value moves.
|
|
363
|
+
The funding source is resolved **server-side under lock** — the client can *request* `balance` or `card`, but the backend verifies the real balance before any value moves. Everything money-shaped is a server call (holds the secret, creates the purchase/refund); the browser's only job on the card leg is to **send the buyer to INVO's hosted checkout page**. Reached via the `platformCommerce` namespace on each entry point.
|
|
317
364
|
|
|
318
365
|
### Balance leg — one server call, settles now
|
|
319
366
|
|
|
@@ -335,12 +382,12 @@ const r = await server.platformCommerce.purchase({
|
|
|
335
382
|
// r.financialBreakdown { total_paid, developer_revenue, platform_fee } // INVO fee: 3.5% flat
|
|
336
383
|
```
|
|
337
384
|
|
|
338
|
-
### Card leg — server creates,
|
|
385
|
+
### Card leg — server creates, INVO hosts the checkout
|
|
339
386
|
|
|
340
|
-
|
|
387
|
+
**INVO hosts the entire card checkout** — card fields, Apple Pay / Google Pay, the international billing-address collector, and 3-D Secure all live on INVO's page. There is **no billing address in the request, no card element, no processor dependency, and no client payment code to write**: the server call returns a `checkoutUrl` and you send the buyer there. `totalPrice` is **USD** ($0.50–$999.99).
|
|
341
388
|
|
|
342
389
|
```ts
|
|
343
|
-
// 1) server — returns a
|
|
390
|
+
// 1) server — returns a hosted-checkout session, NOT yet paid
|
|
344
391
|
const r = await server.platformCommerce.purchase({
|
|
345
392
|
clientRequestId: crypto.randomUUID(),
|
|
346
393
|
fundingSource: "card",
|
|
@@ -351,29 +398,28 @@ const r = await server.platformCommerce.purchase({
|
|
|
351
398
|
itemQuantity: 1,
|
|
352
399
|
unitPrice: "5.00", // CARD leg: USD
|
|
353
400
|
totalPrice: "5.00",
|
|
354
|
-
|
|
355
|
-
|
|
356
|
-
|
|
357
|
-
},
|
|
401
|
+
successUrl: "https://app.example/thanks", // optional: where the buyer lands after paying
|
|
402
|
+
cancelUrl: "https://app.example/cart", // optional: where the buyer lands on cancel
|
|
403
|
+
metadata: { cartId: "c_9" }, // optional: echoed back on the webhook
|
|
358
404
|
});
|
|
359
|
-
// r.status === "requires_payment"
|
|
405
|
+
// r.status === "requires_payment"
|
|
406
|
+
// r.checkoutUrl → send the buyer here r.sessionId / r.expiresAt (unix seconds)
|
|
360
407
|
```
|
|
361
408
|
|
|
362
409
|
```ts
|
|
363
|
-
// 2) browser —
|
|
364
|
-
|
|
365
|
-
|
|
366
|
-
|
|
367
|
-
|
|
368
|
-
|
|
369
|
-
// optional: submit (your own Pay button, selector or element), submitLabel, appearance
|
|
410
|
+
// 2) browser — EITHER just redirect…
|
|
411
|
+
location.href = r.checkoutUrl;
|
|
412
|
+
|
|
413
|
+
// …OR embed the hosted page with the optional helper (iframe + completion listener):
|
|
414
|
+
const handle = invo.platformCommerce.mountCheckout("#checkout", checkoutUrl, {
|
|
415
|
+
onComplete: () => showProcessing(), // fires on the page's INVO_CHECKOUT_COMPLETE message
|
|
370
416
|
});
|
|
371
|
-
//
|
|
417
|
+
// later: handle.destroy();
|
|
372
418
|
```
|
|
373
419
|
|
|
374
|
-
|
|
420
|
+
`mountCheckout` accepts completion messages **only from the checkout page's own origin**, and `onComplete` is a UX signal — show "processing", then reconcile server-side.
|
|
375
421
|
|
|
376
|
-
> ⚠️ **The card sale is real only on the `platform_commerce.purchased` webhook — never on the
|
|
422
|
+
> ⚠️ **The card sale is real only on the `platform_commerce.purchased` webhook — never on the client return or the in-frame completion event** (a client can be tampered with). Fulfill on the webhook.
|
|
377
423
|
|
|
378
424
|
### Status & refunds
|
|
379
425
|
|
|
@@ -387,10 +433,9 @@ const ref = await server.platformCommerce.refund({ orderId: r.orderId, reason: "
|
|
|
387
433
|
// A second refund of the same order throws 409 (err.isAlreadyRefunded) — treat as already done.
|
|
388
434
|
```
|
|
389
435
|
|
|
390
|
-
- **
|
|
391
|
-
- **
|
|
392
|
-
-
|
|
393
|
-
- Client-side validation (missing fields, bad funding source, quantity outside `1..1000`, total ≠ unit×qty, missing/short billing address on the card leg) throws `INVALID_INPUT` **before** any network call.
|
|
436
|
+
- **Idempotency on `clientRequestId`:** a duplicate BALANCE purchase throws `409` (`err.isDuplicateRequest`); a duplicate CARD purchase **replays the same checkout session** (`r.idempotentReplay === true`, same URL — never a second charge), so a lost card-leg response is safely recovered by retrying with the *same* `clientRequestId`.
|
|
437
|
+
- INVO fee: **3.5% flat** (balance) · **3.5% + $0.30** (card). Too-small amounts throw `err.isAmountBelowMinimum` / `err.isBelowCardMinimum` (card < $0.50); a card total over $999.99 throws `err.isAboveCardMaximum`.
|
|
438
|
+
- Client-side validation (missing fields, bad funding source, quantity outside `1..1000`, total ≠ unit×qty, card USD bounds, non-E.164 `playerPhone`) throws **before** any network call.
|
|
394
439
|
- Fulfill on the **`platform_commerce.purchased`** webhook; handle **`platform_commerce.refunded`** for reversals.
|
|
395
440
|
|
|
396
441
|
---
|
|
@@ -412,7 +457,7 @@ comes from the token, no PII).
|
|
|
412
457
|
|
|
413
458
|
## Sends & transfers (move currency between players)
|
|
414
459
|
|
|
415
|
-
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:
|
|
416
461
|
|
|
417
462
|
| | Send | Transfer |
|
|
418
463
|
|---|---|---|
|
|
@@ -448,8 +493,9 @@ const t = await server.initiateTransfer({
|
|
|
448
493
|
// Check guardianApproval FIRST — the guardian path takes precedence.
|
|
449
494
|
switch (true) {
|
|
450
495
|
case !!t.guardianApproval: // minor/guardian path (HTTP 202) → pending approval, no PIN UI
|
|
451
|
-
case t.verificationMethod === "in_app": // sender
|
|
452
|
-
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.
|
|
453
499
|
}
|
|
454
500
|
|
|
455
501
|
// 2. BROWSER — the sender approves with their passkey (give them t.transactionId + the player token)
|
|
@@ -470,10 +516,11 @@ try {
|
|
|
470
516
|
}
|
|
471
517
|
```
|
|
472
518
|
|
|
473
|
-
- **`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.
|
|
474
520
|
- **Claim codes** are returned only by `approveTransfer`; they're the out-of-band fallback when the recipient isn't enrolled.
|
|
475
521
|
- **`err.isReceiverNotEnrolled`** on `confirmReceipt*` is the explicit signal to switch to claim-code entry.
|
|
476
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.
|
|
477
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.
|
|
478
525
|
- Transfer self-claim may be disabled for your tenant; if it is, surface the claim-code path instead.
|
|
479
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`).
|
|
@@ -490,7 +537,9 @@ try {
|
|
|
490
537
|
|
|
491
538
|
## Passkeys (enroll, approve, link, recover)
|
|
492
539
|
|
|
493
|
-
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.
|
|
494
543
|
|
|
495
544
|
```ts
|
|
496
545
|
// Enroll once per user (no-op to call again — the backend excludes already-enrolled credentials)
|
|
@@ -656,6 +705,41 @@ Every failure throws **`InvoError`** with:
|
|
|
656
705
|
- `.message` — human-readable
|
|
657
706
|
- `.body` — the raw parsed response
|
|
658
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
|
+
|
|
659
743
|
Helpers:
|
|
660
744
|
|
|
661
745
|
| Helper | Meaning |
|
|
@@ -665,7 +749,7 @@ Helpers:
|
|
|
665
749
|
| `.isInsufficientBalance` | item purchase failed (400); `required_amount` + `current_balance` on `.body` |
|
|
666
750
|
| `.isDuplicateRequest` | idempotency-keyed request was a duplicate (409) |
|
|
667
751
|
| `.isNotPlatformTenant` | Platform Commerce called by a non-platform tenant (403) — use `purchaseItem`/`createCheckout` instead |
|
|
668
|
-
| `.isAmountBelowMinimum` / `.isBelowCardMinimum` | Platform Commerce amount too small for the fee to round up / card charge under $0.50 (400) |
|
|
752
|
+
| `.isAmountBelowMinimum` / `.isBelowCardMinimum` / `.isAboveCardMaximum` | Platform Commerce amount too small for the fee to round up / card charge under $0.50 / card charge over $999.99 (400) |
|
|
669
753
|
| `.isAlreadyRefunded` | Platform Commerce refund of an already-refunded order (409) — treat as already done |
|
|
670
754
|
| `.retryAfter` | seconds to back off on a 429 throttle |
|
|
671
755
|
| `.isEnrollmentAuthorizationRequired` | first-enrollment needs the OTP grant → `enrollmentBegin`/`enrollmentVerify` |
|
|
@@ -674,6 +758,9 @@ Helpers:
|
|
|
674
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) |
|
|
675
759
|
| `.isNonSteamValueIntoSteamBlocked` | initiate blocked (409): non-Steam value can't move into a Steam title → show `.message`, pick a non-Steam destination |
|
|
676
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) |
|
|
677
764
|
|
|
678
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`.
|
|
679
766
|
|
|
@@ -706,13 +793,13 @@ try {
|
|
|
706
793
|
| `purchaseItem(input)` | `{ status, transactionId, orderId, newBalance, previousBalance, currencyName, financialBreakdown?, raw }` — **game** tenant spending game currency on an in-game item |
|
|
707
794
|
| `getItemPurchaseHistory({ playerEmail, limit?, offset? })` | `{ history, pagination, raw }` |
|
|
708
795
|
| `getItemOrderDetails({ orderId? \| transactionId? \| clientRequestId? })` | `{ order, financialSummary, statusTimeline, raw }` |
|
|
709
|
-
| `platformCommerce.purchase(input)` | `{ status, fundingSource, orderId
|
|
796
|
+
| `platformCommerce.purchase(input)` | `{ status, fundingSource, orderId?, transactionId?, newBalance?, financialBreakdown?, sessionId?, checkoutUrl?, expiresAt?, amountUsd?, idempotentReplay?, raw }` — **ecommerce** (platform tenant); `balance` settles now, `card` returns a hosted-checkout `checkoutUrl` |
|
|
710
797
|
| `platformCommerce.getStatus(orderId)` | `{ orderId, status, gameCurrencyAmount?, usdAmount?, paymentMethod?, createdAt?, raw }` |
|
|
711
798
|
| `platformCommerce.refund({ orderId? \| clientRequestId?, reason? })` | `{ status, orderId?, fundingSource?, refundedAmount?, amountUnit?, feeRetained?, raw }` — pass **exactly one** id; INVO keeps its fee |
|
|
712
799
|
| `getPlayerBalance({ playerEmail })` | `{ player, balances, summary, raw }` — **by email only** (no by-id route; use `InvoClient.getBalance()` client-side) |
|
|
713
800
|
| `getInboundPending({ playerEmail? \| playerPhone? })` | `{ inboundPending, raw }` — live unclaimed inbound sends/transfers |
|
|
714
801
|
| `getLinkedIdentities({ playerEmail? \| playerPhone? })` | `{ walletUserId, primaryEmail, primaryPhone, isMinor, emails, notFound, raw }` — **server-only** (returns PII) |
|
|
715
|
-
|
|
|
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. |
|
|
716
803
|
| `claimTransfer(input)` / `claimCurrency(input)` | `ClaimResult` — redeem a claim code (`needsAccountSelection` + `candidates` on a multi-account phone) |
|
|
717
804
|
| `getTransferStatus(txnId)` / `getSendStatus(txnId)` | `TransactionStatusResult` — poll outbound state (`verificationState`) |
|
|
718
805
|
| `getGuardianApprovalStatus(txnId)` | `GuardianApprovalStatusResult` — poll a guardian hold to resolution (`state`) |
|
|
@@ -738,10 +825,9 @@ Every method also accepts an optional final `{ signal }` (`AbortSignal`) for can
|
|
|
738
825
|
| `getPendingCollect()` | `{ pending, raw }` — the player's own pending-to-collect list (player-token) |
|
|
739
826
|
| `getDestinations({ direction? })` | `{ availableGames, sourceGameName, transferMode, … }` — where the player can send/transfer, metadata inline |
|
|
740
827
|
| `getBalance()` | `{ gameId, gameName, balances, totalValue, currencyCount, hasFunds, raw }` — the player's balances for this game |
|
|
741
|
-
| `platformCommerce.
|
|
742
|
-
| `platformCommerce.mountCardPayment(clientSecret, { mount, publishableKey? })` | `{ element, confirm({ returnUrl? }), destroy() }` — the primitive: confirm from your own Pay button |
|
|
828
|
+
| `platformCommerce.mountCheckout(el, checkoutUrl, { onComplete? })` | `{ iframe, destroy() }` — optional embed of INVO's hosted checkout (or just `location.href = checkoutUrl`); `onComplete` fires on the page's origin-checked `INVO_CHECKOUT_COMPLETE` message |
|
|
743
829
|
|
|
744
|
-
Every method throws `InvoError` on failure and takes an optional final `{ signal }`. Full inline types ship with the package.
|
|
830
|
+
Every method throws `InvoError` on failure and takes an optional final `{ signal }`. Full inline types ship with the package. The Platform Commerce card leg needs **no keys and no payment code in the browser** — INVO's hosted page owns the card form.
|
|
745
831
|
|
|
746
832
|
---
|
|
747
833
|
|
|
@@ -755,7 +841,7 @@ npm test # vitest
|
|
|
755
841
|
|
|
756
842
|
### Stability
|
|
757
843
|
|
|
758
|
-
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.
|
|
759
845
|
|
|
760
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`).
|
|
761
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";
|
|
@@ -155,6 +216,11 @@ var InvoError = class _InvoError extends Error {
|
|
|
155
216
|
get isBelowCardMinimum() {
|
|
156
217
|
return this.code === "BELOW_STRIPE_MINIMUM";
|
|
157
218
|
}
|
|
219
|
+
/** True if a Platform Commerce CARD purchase exceeded the hosted checkout's single-charge
|
|
220
|
+
* cap of $999.99 (`ABOVE_CARD_MAXIMUM`, 400) — split the sale or lower the amount. */
|
|
221
|
+
get isAboveCardMaximum() {
|
|
222
|
+
return this.code === "ABOVE_CARD_MAXIMUM";
|
|
223
|
+
}
|
|
158
224
|
/**
|
|
159
225
|
* True if a Platform Commerce refund targeted an order that was already refunded
|
|
160
226
|
* (409). Idempotent outcome — the original refund did happen, so treat this as
|
|
@@ -441,5 +507,5 @@ function toDestinationsResult(raw, direction) {
|
|
|
441
507
|
}
|
|
442
508
|
|
|
443
509
|
export { Http, InvoError, assertSecureBaseUrl, toDestinationsResult };
|
|
444
|
-
//# sourceMappingURL=chunk-
|
|
445
|
-
//# sourceMappingURL=chunk-
|
|
510
|
+
//# sourceMappingURL=chunk-BPZJ63RM.js.map
|
|
511
|
+
//# sourceMappingURL=chunk-BPZJ63RM.js.map
|