@invonetwork/web-sdk 3.8.1 → 3.9.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 +42 -0
- package/LICENSE +18 -18
- package/README.md +86 -23
- package/dist/{chunk-HYGBTUEJ.js → chunk-NB6UF657.js} +30 -2
- package/dist/index.cjs +28 -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 +110 -7
- package/dist/server.d.cts +55 -9
- package/dist/server.d.ts +55 -9
- package/dist/server.js +84 -9
- package/dist/{types-DqRuqbqI.d.cts → types-CUzSzV8-.d.cts} +71 -2
- package/dist/{types-DqRuqbqI.d.ts → types-CUzSzV8-.d.ts} +71 -2
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,47 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 3.9.0
|
|
4
|
+
|
|
5
|
+
### Minor Changes
|
|
6
|
+
|
|
7
|
+
- The INVO-hosted card page is the recommended way to save a card for a subscription.
|
|
8
|
+
|
|
9
|
+
New on `invo.cards`:
|
|
10
|
+
|
|
11
|
+
- **`createSetupSession({ playerEmail, successUrl?, cancelUrl?, metadata? })`** ->
|
|
12
|
+
`{ sessionId, cardSetupUrl, expiresAt, raw }` (`POST /api/checkout/card-setup-sessions`,
|
|
13
|
+
game secret header). Mint a 10-minute link server-side, send the member to `cardSetupUrl`
|
|
14
|
+
(top-level, never framed), and read the saved card's `id` back from `cards.list`; it appears
|
|
15
|
+
there immediately, carries the off-session consent a subscription needs, and no event fires
|
|
16
|
+
for it. No browser code, no client secret, no card processor named anywhere, so INVO can change
|
|
17
|
+
processor without partners changing anything. Never auto-retried: each call mints a fresh link.
|
|
18
|
+
Script-scheme `successUrl` / `cancelUrl` values are refused before the network (`INVALID_INPUT`,
|
|
19
|
+
status 0), matching INVO's own rule.
|
|
20
|
+
- `beginSetup` / `confirmSetup` are now documented as the **processor-bound alternative**: they
|
|
21
|
+
hand back a `clientSecret` only the current processor's client library can consume, so a card
|
|
22
|
+
form built on them needs rework when INVO changes processor.
|
|
23
|
+
|
|
24
|
+
New error classifiers: `isPlayerNotFound` (404 `PLAYER_NOT_FOUND`: the card page never creates
|
|
25
|
+
players), `isInvalidPlayerEmail` (400 `INVALID_PLAYER_EMAIL`), `isInvalidInput` (`INVALID_INPUT`,
|
|
26
|
+
at status 0 from the SDK's own guards or 400 from INVO for a script-scheme URL).
|
|
27
|
+
|
|
28
|
+
Fixed: `subscriptions.get(id, { includePlayer: true })` never populated `player`. INVO puts
|
|
29
|
+
`player_email` / `player_name` on the subscription object itself, not in a separate block; they
|
|
30
|
+
are now surfaced as `subscription.playerEmail` / `subscription.playerName`, and `player` is
|
|
31
|
+
derived from them.
|
|
32
|
+
|
|
33
|
+
README: a "Cards for subscriptions" section a partner can follow start to finish (mint, send,
|
|
34
|
+
read the card back, subscribe, what each error means, the 10-minute session, no browser code).
|
|
35
|
+
|
|
36
|
+
README corrections that ride along in this release: `subscription.expired` no longer carries
|
|
37
|
+
`failure_code: "steam_containment"` (a balance is spendable in any title whatever rail bought
|
|
38
|
+
it, so the "wallet value that cannot be spent in this game" deferral is gone from the deferrals
|
|
39
|
+
paragraph and the event table); the Steam transfer-policy note now says it is a rule about
|
|
40
|
+
currency moving between titles, not about spending (an item purchase never fails on origin);
|
|
41
|
+
and "game" reads "title" in a few places so a platform tenant is not misled by the word.
|
|
42
|
+
Line endings: a `.gitattributes` (`* text=auto eol=lf`) keeps the packed README, CHANGELOG and
|
|
43
|
+
package.json LF on every checkout (3.9.0's first build packed CRLF from a Windows checkout).
|
|
44
|
+
|
|
3
45
|
## 3.8.1
|
|
4
46
|
|
|
5
47
|
### Patch Changes
|
package/LICENSE
CHANGED
|
@@ -1,18 +1,18 @@
|
|
|
1
|
-
Copyright (c) 2026 Invo Tech Inc. All rights reserved.
|
|
2
|
-
|
|
3
|
-
This software and associated documentation files (the "Software") are the
|
|
4
|
-
proprietary property of Invo Tech Inc. ("INVO"). The Software is licensed, not
|
|
5
|
-
sold.
|
|
6
|
-
|
|
7
|
-
GRANT. INVO grants you a non-exclusive, non-transferable, royalty-free license to
|
|
8
|
-
install and use the Software, in unmodified form, solely to build and operate
|
|
9
|
-
integrations with the INVO platform, subject to INVO's developer terms at
|
|
10
|
-
https://invo.network.
|
|
11
|
-
|
|
12
|
-
RESTRICTIONS. Except as expressly permitted above, you may not copy, modify,
|
|
13
|
-
distribute, sublicense, sell, or create derivative works of the Software, or
|
|
14
|
-
remove any proprietary notices, without INVO's prior written consent.
|
|
15
|
-
|
|
16
|
-
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
17
|
-
IMPLIED. IN NO EVENT SHALL INVO BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER
|
|
18
|
-
LIABILITY ARISING FROM, OUT OF, OR IN CONNECTION WITH THE SOFTWARE.
|
|
1
|
+
Copyright (c) 2026 Invo Tech Inc. All rights reserved.
|
|
2
|
+
|
|
3
|
+
This software and associated documentation files (the "Software") are the
|
|
4
|
+
proprietary property of Invo Tech Inc. ("INVO"). The Software is licensed, not
|
|
5
|
+
sold.
|
|
6
|
+
|
|
7
|
+
GRANT. INVO grants you a non-exclusive, non-transferable, royalty-free license to
|
|
8
|
+
install and use the Software, in unmodified form, solely to build and operate
|
|
9
|
+
integrations with the INVO platform, subject to INVO's developer terms at
|
|
10
|
+
https://invo.network.
|
|
11
|
+
|
|
12
|
+
RESTRICTIONS. Except as expressly permitted above, you may not copy, modify,
|
|
13
|
+
distribute, sublicense, sell, or create derivative works of the Software, or
|
|
14
|
+
remove any proprietary notices, without INVO's prior written consent.
|
|
15
|
+
|
|
16
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
17
|
+
IMPLIED. IN NO EVENT SHALL INVO BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER
|
|
18
|
+
LIABILITY ARISING FROM, OUT OF, OR IN CONNECTION WITH THE SOFTWARE.
|
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.9.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.9.0** adds the **[INVO-hosted card page for subscriptions](#cards-for-subscriptions)**, `invo.cards.createSetupSession`: mint a 10-minute link server-side, send the member to it, read the card back from `cards.list`, with no browser code and no card processor named anywhere (`beginSetup`/`confirmSetup` remain as the processor-bound alternative), plus the `isPlayerNotFound`, `isInvalidPlayerEmail` and `isInvalidInput` classifiers and a fix that makes `includePlayer` reads actually surface `playerEmail`/`playerName`; **3.8.0** adds **[Subscriptions](#subscriptions-recurring-billing)** as a first-class server surface on both rails — `invo.subscriptions.create/get/listForPlayer/cancel/changeAmount/setPaymentMethod/refund/steamInit/steamFinalize`, the off-session card capture (`invo.cards.beginSetup/confirmSetup/list`), the sandbox clock tools (`invo.sandbox.subscriptions.*`, which post to `/subscriptions/<id>/...` **relative to the sandbox base, not under `/api`**, with the new `sandboxClockKey`), typed `data` for all seven `subscription.*` webhook events, and eleven new error classifiers; **3.7.0** makes the **device approval grant a first-class SDK surface** — `beginDeviceApproval`, `pollDeviceApproval`, `confirmDeviceEnrollment` and, the step that actually moves the money, **`approveWithDeviceCode`** (plus the optional `completeDeviceApproval` loop); a grant that is polled to `approved` and left there settles **nothing**, which is the failure this release exists to make impossible, and `TRANSACTION_NOT_PENDING` now comes back as a typed `status: "not_pending"` result with `alreadySettled` rather than a thrown error you would have to string-match; **3.4.0** documents that a Steam title now bills through **its own Steam application** — the studio registers their appid + publisher Web API key and keeps a payment method on file, because Valve pays the studio and INVO settles afterwards (new `isSteamNotConfigured`, `isPartnerBillingNotSetUp`, `isPartnerSettlementUnavailable`, `isSteamAppChanged` error helpers); **3.2.3** corrects the base path and auth header in the Steam snippets (`/api/currency-purchases`, `X-Game-Secret-Key`) — 3.2.2 published both wrong, and copying them returned a 404; **3.2.x** documents **Steam currency purchases on a pack model** — INVO owns the catalogue, you pass a `pack_id` and never a price, and the currency inside a pack varies by country because Steam prices are VAT-inclusive; **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
|
|
@@ -24,6 +24,8 @@ Six money flows plus passkey (WebAuthn) authentication, split across a trusted s
|
|
|
24
24
|
|
|
25
25
|
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`).
|
|
26
26
|
|
|
27
|
+
> **This applies to a game or a platform alike:** the SDK calls the tenant a game and names the option `gameSecret`, but a platform tenant uses the same option and the same flow.
|
|
28
|
+
|
|
27
29
|
## Passkeys are the gold standard — don't build on SMS
|
|
28
30
|
|
|
29
31
|
**If you take one thing from this README: authorize money movement with a passkey. Do not design your verification UX around the SMS PIN.**
|
|
@@ -44,7 +46,7 @@ So:
|
|
|
44
46
|
**Read this before you wire up `enrollPasskey()`.** There are two places a passkey ceremony can run, and which one serves your title is decided by whether you hold a partner passkey domain:
|
|
45
47
|
|
|
46
48
|
- **No partner domain (every new title):** INVO runs the ceremony **on its own domain** — the hosted approval page — for every platform. There is **no domain to verify and nothing to configure**; submitting one is refused (`409 PARTNER_RP_FROZEN`). On the web the path is [`approveHosted()`](#web-games--approving-on-invos-hosted-page); on consoles it is the QR flow; on iOS/Android the mobile plugins open the same page. The in-app `enrollPasskey()` / `approveSend` / `approveTransfer` calls return `403 WEBAUTHN_NOT_ENABLED_FOR_TENANT` for you — that is the **expected state, not a setup gap** (the body's `hosted_flow` says so and points at `device_code`).
|
|
47
|
-
- **A domain verified before the freeze (existing tenants):** your passkeys are bound to that RP ID for life, so `enrollPasskey()` and the in-app approves keep working exactly as documented below. You may still change or re-verify the domain. Removing it is **irreversible
|
|
49
|
+
- **A domain verified before the freeze (existing tenants):** your passkeys are bound to that RP ID for life, so `enrollPasskey()` and the in-app approves keep working exactly as documented below. You may still change or re-verify the domain. Removing it is **irreversible**: it can never be re-added, and the hosted flow serves the title from then on.
|
|
48
50
|
|
|
49
51
|
`WEBAUTHN_NOT_ENABLED_FOR_TENANT` is **configuration state, not an error** — the in-app ceremony was never available to fail. Don't show the player a failure; use the hosted page:
|
|
50
52
|
|
|
@@ -97,6 +99,7 @@ The right approval method is a property of the **client the player is sitting in
|
|
|
97
99
|
- [Item purchase (spend game currency)](#item-purchase-spend-game-currency)
|
|
98
100
|
- [Platform Commerce (ecommerce)](#platform-commerce-ecommerce)
|
|
99
101
|
- [Subscriptions (recurring billing)](#subscriptions-recurring-billing)
|
|
102
|
+
- [Cards for subscriptions](#cards-for-subscriptions)
|
|
100
103
|
- [Player balance](#player-balance)
|
|
101
104
|
- [Sends & transfers (move currency between players)](#sends--transfers-move-currency-between-players)
|
|
102
105
|
- [Legacy fallback: the SMS PIN (being retired)](#legacy-fallback-the-sms-pin-being-retired)
|
|
@@ -123,9 +126,9 @@ Node ≥ 18 on the server (uses the global `fetch`). The browser build ships ESM
|
|
|
123
126
|
|
|
124
127
|
## Get your account & game secret (INVO console)
|
|
125
128
|
|
|
126
|
-
Sign up, create your
|
|
129
|
+
Sign up, create your title, and copy its credentials (the **game secret**, plus your WebAuthn **RP ID / origins**) in the INVO console. Use the console that matches the environment you're building against:
|
|
127
130
|
|
|
128
|
-
| Environment | Console
|
|
131
|
+
| Environment | Console: sign up, manage titles, copy your game secret | API `baseUrl` |
|
|
129
132
|
|---|---|---|
|
|
130
133
|
| **Testing / sandbox** | **https://dev.console.invo.network** | `https://sandbox.invo.network/sandbox` |
|
|
131
134
|
| **Production** | **https://console.invo.network** | `https://invo.network` |
|
|
@@ -163,7 +166,7 @@ Build and test against the **dev console + sandbox** first, then switch to the *
|
|
|
163
166
|
### Player token (session mint for an existing player)
|
|
164
167
|
|
|
165
168
|
`mintPlayerToken` mints a short-lived, game-scoped **session token** for a player who
|
|
166
|
-
**already exists** on your
|
|
169
|
+
**already exists** on your title. It is *not* a registration call: the backend looks the
|
|
167
170
|
player up by `playerEmail` and returns a token for their existing identity (or `404` if no
|
|
168
171
|
such player exists). It only needs `playerEmail`:
|
|
169
172
|
|
|
@@ -237,7 +240,7 @@ INVO enables each flow for your tenant in the [console](#get-your-account--game-
|
|
|
237
240
|
- **For passkeys (sends/transfers):** nothing to configure — new titles approve on INVO's hosted page ([`approveHosted()`](#web-games--approving-on-invos-hosted-page)); there is no partner domain to verify. Only a tenant that verified an **RP ID + web origin(s)** before the freeze uses the in-app `enrollPasskey()` / `approveSend` path, and those passkeys only validate on the approved origins. **Wire the approve step 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)).
|
|
238
241
|
- **For currency purchase:** card checkout works out of the box; ask INVO to enable the `game`/`steam` rails if you need them. **The `steam` rail additionally requires the studio to register their own Steam app id + publisher Web API key and put a payment method on file** — see [Steam purchases](#steam-purchases-packs-not-prices).
|
|
239
242
|
- **For item purchase:** nothing extra — it's a currency-balance debit.
|
|
240
|
-
- **For subscriptions:** the game must be **`live`** (a `testing` game cannot create one), a **webhook target must be registered first** (several `subscription.*` events carry data you cannot fetch any other way), and a card subscription needs a card captured **off-session** via `cards.beginSetup`
|
|
243
|
+
- **For subscriptions:** the game must be **`live`** (a `testing` game cannot create one), a **webhook target must be registered first** (several `subscription.*` events carry data you cannot fetch any other way), and a card subscription needs a card captured **off-session** via `cards.createSetupSession` (the INVO-hosted card page; `cards.beginSetup` is the processor-bound alternative); the hosted checkout does not save one. See [Cards for subscriptions](#cards-for-subscriptions).
|
|
241
244
|
|
|
242
245
|
If a flow isn't enabled for your tenant yet, calls return a clear `InvoError` (e.g. `TENANT_NOT_MIGRATED`, `WEBAUTHN_NOT_ENABLED_FOR_TENANT`, or `flow_paused`) — coordinate with your INVO contact to turn it on.
|
|
243
246
|
|
|
@@ -604,7 +607,7 @@ const ref = await server.platformCommerce.refund({ orderId: r.orderId, reason: "
|
|
|
604
607
|
|
|
605
608
|
## Subscriptions (recurring billing)
|
|
606
609
|
|
|
607
|
-
A subscription is a standing agreement, created by **your server**, under which INVO bills one of your players a fixed USD price on a fixed interval and grants them your
|
|
610
|
+
A subscription is a standing agreement, created by **your server**, under which INVO bills one of your players a fixed USD price on a fixed interval and grants them your title's currency each period. **You keep the entitlement** (what the member gets in your title). INVO keeps the clock, the charges, the retries, the notifications and the revenue split. Two rails, fixed at creation:
|
|
608
611
|
|
|
609
612
|
| `fundingRail` | How the shortfall is funded | Created by |
|
|
610
613
|
|---|---|---|
|
|
@@ -621,12 +624,65 @@ Each period INVO works out what the period is worth in coins (card: price × the
|
|
|
621
624
|
|
|
622
625
|
**Before you start:** the game must be `live` in the environment you're calling (a `testing` game is refused `403 GAME_NOT_LIVE`, `err.isGameNotLive`, though it may still read/cancel/reprice existing subscriptions); register a webhook target first (several events carry data you cannot fetch any other way); use the primary game key (`ivsdk_...`) or a channel key in `X-Game-Secret-Key` (on the Steam rail only the primary key or the `steam` channel key may start a subscription: `err.isSteamChannelRequired`). Money and coin figures are **decimal strings** on the wire and in every typed result, so nothing rounds silently.
|
|
623
626
|
|
|
624
|
-
###
|
|
627
|
+
### Cards for subscriptions
|
|
628
|
+
|
|
629
|
+
A card subscription needs a card saved for later, off-session use. **The recommended way to save one is the INVO-hosted card page:** two server-to-server calls and one redirect, **no browser code**, and nothing in your integration references a card processor or loads its script, so INVO can change processor without you changing anything. Your PCI scope does not change: the subscription endpoints never receive card data and neither does this SDK.
|
|
630
|
+
|
|
631
|
+
**1. Mint a card-setup session on your server.** The member must already exist in your title; this call never creates players.
|
|
632
|
+
|
|
633
|
+
```ts
|
|
634
|
+
const session = await server.cards.createSetupSession({
|
|
635
|
+
playerEmail: "member@example.com",
|
|
636
|
+
successUrl: "https://your.game/billing/card-saved?member=7", // optional: where the page sends the member after the save; put your own correlation id here
|
|
637
|
+
});
|
|
638
|
+
// session.sessionId, session.cardSetupUrl, session.expiresAt (10 minutes from now)
|
|
639
|
+
```
|
|
640
|
+
|
|
641
|
+
**2. Send the member to `session.cardSetupUrl`.** Open it as a top-level page (a redirect or a new tab); **do not frame it**. The page says in words that no money moves. The member enters the card, authenticates with their issuer if the issuer asks, and INVO saves the card and then redirects to your `successUrl` (or shows "Card saved, you can close this window" when you gave none). You write no browser code for this step and you never see a client secret, a publishable key or a processor name.
|
|
625
642
|
|
|
626
|
-
**
|
|
643
|
+
**3. Read the card back and subscribe.** A card saved this way **appears in `cards.list` immediately**, carries the off-session consent a subscription needs, and is indistinguishable from one saved any other way. The `id` is the only handle INVO returns for a card.
|
|
627
644
|
|
|
628
645
|
```ts
|
|
629
|
-
|
|
646
|
+
const { cards } = await server.cards.list("member@example.com"); // unexpired, newest first
|
|
647
|
+
const r = await server.subscriptions.create({
|
|
648
|
+
clientRequestId: "guild-42-member-7",
|
|
649
|
+
playerEmail: "member@example.com",
|
|
650
|
+
playerName: "Member",
|
|
651
|
+
itemId: "guild-42-membership",
|
|
652
|
+
amountUsd: "9.99",
|
|
653
|
+
playerCardId: cards[0].id, // or omit it: INVO attaches the member's newest unexpired saved card
|
|
654
|
+
});
|
|
655
|
+
```
|
|
656
|
+
|
|
657
|
+
**A brand-new member (no player in your title yet).** The card page needs an existing player and there is no create-player call, so bring the member into your title first. Two ways that move no money: `subscriptions.create` with `trialDays` creates the player and a `trialing` subscription (`firstCharge.status: "skipped_trial"`); or a card-less `subscriptions.create` (no `playerCardId`, no saved card yet) creates the player and the subscription, and its first charge is recorded as failed with `failureCode: "no_payment_method"` (outcome `insufficient_funds`), so the subscription sits in dunning with access retained. Then mint the card session and send the member to the page. After the save either call `subscriptions.setPaymentMethod(id, { playerCardId })` or do nothing: INVO adopts the member's newest saved card at the next attempt and attaches it. A currency purchase also creates the player, and with `save_card: true` saves the card in the same step.
|
|
658
|
+
|
|
659
|
+
**What to expect.**
|
|
660
|
+
|
|
661
|
+
- **The session lives 10 minutes.** Entering a card is one sitting. Mint the link when the member is about to use it, not ahead of time. An expired link shows the member a message asking for a new one; a new `createSetupSession` call is all it takes.
|
|
662
|
+
- **The link may be reloaded freely before the card is saved.** A reload after the issuer has authorised the card opens directly on the final "finish saving" step rather than asking for the card again.
|
|
663
|
+
- **Once the card is saved the link is spent.** Reopening it returns the same saved card and redirects to `successUrl` again; nothing is saved twice.
|
|
664
|
+
- **If saving fails after the issuer authorised the card,** the page tells the member to try again and the same link keeps working; nothing is recorded until the save succeeds. If what the member entered is not a card (a bank account, for instance) the page stops with a terminal message and a new link is needed.
|
|
665
|
+
- **There is no webhook for a saved card.** `cards.list` is the signal: read it when the member lands on `successUrl`, or right before the next `subscriptions.create`.
|
|
666
|
+
- **`createSetupSession` is never auto-retried.** Each call mints a fresh link, so on a timeout or 5xx just call it again.
|
|
667
|
+
- **`successUrl` is redirected to verbatim**, with nothing appended, and `metadata` is stored on the session and not returned anywhere today (no read returns the session). Put your own correlation id in `successUrl`. `cancelUrl` is carried on the session but not used by the page today.
|
|
668
|
+
|
|
669
|
+
**Errors from `createSetupSession`.** Match on `err.code`, never on the message.
|
|
670
|
+
|
|
671
|
+
| Helper / code | HTTP | Meaning |
|
|
672
|
+
|---|---|---|
|
|
673
|
+
| `.isInvalidPlayerEmail` (`INVALID_PLAYER_EMAIL`) | 400 | `playerEmail` is not an email address (INVO checks for an `@`). A missing or blank `playerEmail` never reaches INVO: the SDK throws `INVALID_INPUT` with `.status === 0` first |
|
|
674
|
+
| `.isPlayerNotFound` (`PLAYER_NOT_FOUND`) | 404 | the member does not exist in this title yet. Create the player first (any call that creates players, for example a currency purchase); the card page never creates one |
|
|
675
|
+
| `.isInvalidInput` (`INVALID_INPUT`) | 400 | `successUrl` or `cancelUrl` uses a script scheme (`javascript:`, `data:`, `vbscript:`). http(s) and app deep-link schemes are fine. The SDK refuses the same values before the network with `.status === 0` |
|
|
676
|
+
| no code, `err.status === 401` | 401 | the game key is missing or wrong for this environment (body is `{ message }`) |
|
|
677
|
+
| no code, `err.status === 403` | 403 | the game is not `live` or `testing` |
|
|
678
|
+
| `err.status === 503` (the `error_code` names the cause) | 503 | card setup is not available right now; retry shortly |
|
|
679
|
+
|
|
680
|
+
Rate limit: 2000 per minute per game key with a per-IP floor; on a 429 honour `err.retryAfter`.
|
|
681
|
+
|
|
682
|
+
**The processor-bound alternative: `cards.beginSetup` / `cards.confirmSetup`.** Use these only if you already run a card form in your own client against INVO's current card processor. `beginSetup` hands back a `clientSecret` that only that processor's client library can consume, so the browser code you write for it is bound to the processor of the day and will need rework when INVO changes processor. `createSetupSession` does not have that problem, which is why it is the recommended path.
|
|
683
|
+
|
|
684
|
+
```ts
|
|
685
|
+
// The processor-bound alternative (charges nothing). The player must already exist in this game.
|
|
630
686
|
const setup = await server.cards.beginSetup({
|
|
631
687
|
playerEmail: "member@example.com",
|
|
632
688
|
setupReference: "setup-guild-42-member-7", // idempotency anchor: resend the same value on a retry
|
|
@@ -643,10 +699,15 @@ switch (setup.status) {
|
|
|
643
699
|
// saved.card.id (a 400 with body.status === "still_requires_action" means the client hasn't finished)
|
|
644
700
|
break;
|
|
645
701
|
}
|
|
702
|
+
```
|
|
646
703
|
|
|
647
|
-
|
|
648
|
-
// `save_card: true` in the body saves it with the off-session consent as a side effect.
|
|
704
|
+
**Saving the card during a purchase** also works: `purchaseCurrency(...)` with a new `paymentMethodId` and `save_card: true` in the body saves it with the off-session consent as a side effect; the purchase response carries `card_saved: true` and you read the `id` from `cards.list`.
|
|
649
705
|
|
|
706
|
+
### The card road
|
|
707
|
+
|
|
708
|
+
**1. Capture a card (off-session).** Three ways to save one, and **the hosted checkout is not one of them** (a member who paid through the hosted checkout page does *not* thereby have a card on file for recurring billing; neither does a card saved through a `savedCardId` purchase): the INVO-hosted card page through `cards.createSetupSession` (recommended; see [Cards for subscriptions](#cards-for-subscriptions) above), the processor-bound `cards.beginSetup` / `cards.confirmSetup` pair, or a purchase with `save_card: true`. Whichever you use, the card's `id` comes from `cards.list`:
|
|
709
|
+
|
|
710
|
+
```ts
|
|
650
711
|
const { cards } = await server.cards.list("member@example.com"); // unexpired, newest first; `id` is the only handle
|
|
651
712
|
```
|
|
652
713
|
|
|
@@ -778,7 +839,7 @@ export const POST = createWebhookHandler({
|
|
|
778
839
|
break;
|
|
779
840
|
case "subscription.expired": // the retry budget ran out (or a Steam row was never authorised)
|
|
780
841
|
await revokeAt(event.data.subscription_id, event.data.final_period_end); // NOT ended_at; null if nothing was ever paid
|
|
781
|
-
break; // failure_code "steam_containment"
|
|
842
|
+
break; // failure_code "steam_containment" is no longer sent (spending is not restricted by origin)
|
|
782
843
|
case "subscription.refunded": // your revenue for the refunded portion is reversed; INVO's fee is retained
|
|
783
844
|
await recordReversal(event.data.subscription_id, event.data.refund.partner_revenue_reversed_usd);
|
|
784
845
|
break;
|
|
@@ -793,7 +854,7 @@ export const POST = createWebhookHandler({
|
|
|
793
854
|
| Should I revoke access? | only on `subscription.expired` (at `final_period_end`) or `subscription.canceled` (at `access_until`); **never** on `payment_failed`, `past_due` or `authentication_required` |
|
|
794
855
|
| What did I earn? | `split.partner_revenue_usd` on `subscription.renewed`, minus `refund.partner_revenue_reversed_usd` on any `subscription.refunded` |
|
|
795
856
|
|
|
796
|
-
A few renewal outcomes are **deferrals**, not failures, with no event and no retry consumed (a price above the 25000.00 per-charge ceiling;
|
|
857
|
+
A few renewal outcomes are **deferrals**, not failures, with no event and no retry consumed (a price above the 25000.00 per-charge ceiling; on Steam, your billing setup or Steam configuration being unusable). You see them on `get` as an unchanged (or `past_due`) status with `nextChargeAt` about 24 hours out. There used to be a third: a wallet holding currency bought through Steam, in a title that was not on Steam. **That deferral is gone.** A balance is spendable in any title whatever rail bought it, so a renewal spends the whole wallet.
|
|
797
858
|
|
|
798
859
|
### Reading, cancelling, repricing, changing the card
|
|
799
860
|
|
|
@@ -857,7 +918,7 @@ await sb.forceAuthChallenge(id); // moves it to awaiting_authenticati
|
|
|
857
918
|
>
|
|
858
919
|
> **Second credential.** Every clock call sends `X-Game-Secret-Key` *and* `X-Sandbox-Clock-Key`, a separate per-game key (`ivclk_...`). Get it from the sandbox console: open the game, **Game Settings**, the **"Sandbox clock key"** card (generated the first time you reveal it; the same card rotates it, with a 7-day grace). Pass it as `sandboxClockKey`; a missing key throws `INVALID_INPUT` before the network, a wrong one is `401 SANDBOX_CLOCK_UNAUTHORIZED` (`err.isSandboxClockUnauthorized`). Keep it out of game clients and source control. None of these calls is auto-retried: each one moves the clock or runs the engine.
|
|
859
920
|
|
|
860
|
-
**Card recipe.** Make the sandbox game live and register a webhook. Save a card with `cards.beginSetup` using `paymentMethodId: "pm_card_visa"` (immediate) or `"pm_card_threeDSecure2Required"` (returns `requires_action`; finish on the client, then `confirmSetup`). `subscriptions.create` with that `playerCardId`: expect `firstCharge.status: "paid"`, `subscription.periodSeq: 2`, and a `subscription.renewed` delivery with `period_seq: 1`. Replay the same input: expect `idempotentReplay: true`. Then `advanceClock` + `forceRenewal` for as many periods as you like (`engineStats.renewed: 1`, `period_seq` advancing on each `subscription.renewed`); `forceFailure` four times (or swap in `"pm_card_chargeDeclined"` through `setPaymentMethod`, then advance + force four times) to walk `past_due` to `expired` with `final_period_end`; `changeAmount` then advance + force to see the old price on that renewal and the new one on the next; `cancel({ atPeriodEnd: true })` then advance + force to get `action: "retired-at-period-end"`; `refund` a paid period; and create one with `trialDays: 7` to see `skipped_trial` convert.
|
|
921
|
+
**Card recipe.** Make the sandbox game live and register a webhook. Save a card with `cards.createSetupSession` (open `cardSetupUrl` in a browser; the sandbox page runs against the test-mode card processor, so enter a test card there, never a real one; the sandbox recipe on the public docs site is at https://docs.invo.network/docs/subscriptions-sandbox), or, on the processor-bound path, with `cards.beginSetup` using `paymentMethodId: "pm_card_visa"` (immediate) or `"pm_card_threeDSecure2Required"` (returns `requires_action`; finish on the client, then `confirmSetup`). `subscriptions.create` with that `playerCardId`: expect `firstCharge.status: "paid"`, `subscription.periodSeq: 2`, and a `subscription.renewed` delivery with `period_seq: 1`. Replay the same input: expect `idempotentReplay: true`. Then `advanceClock` + `forceRenewal` for as many periods as you like (`engineStats.renewed: 1`, `period_seq` advancing on each `subscription.renewed`); `forceFailure` four times (or swap in `"pm_card_chargeDeclined"` through `setPaymentMethod`, then advance + force four times) to walk `past_due` to `expired` with `final_period_end`; `changeAmount` then advance + force to see the old price on that renewal and the new one on the next; `cancel({ atPeriodEnd: true })` then advance + force to get `action: "retired-at-period-end"`; `refund` a paid period; and create one with `trialDays: 7` to see `skipped_trial` convert.
|
|
861
922
|
|
|
862
923
|
**Steam recipe.** In sandbox `steamFinalize` **does not call Steam**: it auto-approves a stand-in agreement and runs the real settlement (`fin.sandboxAutoApproved === true`), and `forceRenewal` treats the Steam charge as captured (`engineStats.steam_charged: 1, sandbox_synthetic: 1`). So sandbox proves INVO's currency path (coins, split, events, dunning), not Valve's charge: do one real Steam sandbox authorisation before launch. Credit the wallet above the price (a sandbox purchase), advance + force, and expect `funding.steam_charged_usd: "0.00"`.
|
|
863
924
|
|
|
@@ -885,7 +946,8 @@ Match on `err.code` (and on `body.status` where the body carries one), never on
|
|
|
885
946
|
| `WALLET_ONLY_SUBSCRIPTION` / `WALLET_ONLY_CONFLICT` | `walletOnly: true` with a card; or a wallet-only subscription needs `walletOnly: false` beside the new card |
|
|
886
947
|
| `NO_PAID_PERIOD` / `PERIOD_NOT_REFUNDABLE` / `AMOUNT_EXCEEDS_REMAINING` | refund refusals (the last carries `remaining_refundable_usd`) |
|
|
887
948
|
| `AMOUNT_TOO_SMALL_FOR_STEAM` / `STEAM_CHARGE_UNPLANNABLE` / `STEAM_UNAVAILABLE` / `STEAM_ERROR` | Steam init refusals; the last three abandoned the row (its id on `.existingSubscriptionId`): retry with a **new** key |
|
|
888
|
-
| `
|
|
949
|
+
| `.isPlayerNotFound` / `.isInvalidPlayerEmail` / `.isInvalidInput` | (404 / 400 / 400) `cards.createSetupSession`: the member does not exist yet (the card page never creates players); `playerEmail` is not an email; `successUrl`/`cancelUrl` uses a script scheme (`isInvalidInput` is also the SDK's own pre-network guard code, at `.status === 0`) |
|
|
950
|
+
| `SETUP_REFERENCE_REUSED` / `PLAYER_NOT_FOUND` / `CARD_DECLINED` / `RAW_CARD_NOT_SUPPORTED` / `CARD_PERSIST_FAILED` | the processor-bound card capture (`beginSetup`/`confirmSetup`); on `CARD_PERSIST_FAILED` (500) retry `confirmSetup` with the same `setupIntentId` |
|
|
889
951
|
|
|
890
952
|
Client-side guards (missing key, a `sub_`-prefixed key, a bad amount, a non-E.164 `playerPhone`, a trial or card field on Steam, a web session without `playerIp`, a missing `sandboxClockKey`) throw `InvoError` with `.status === 0` **before** any network call.
|
|
891
953
|
|
|
@@ -900,7 +962,7 @@ Client-side guards (missing key, a `sub_`-prefixed key, a bad amount, a non-E.16
|
|
|
900
962
|
7. **Do not poll for renewals.** Handle `subscription.renewed`.
|
|
901
963
|
8. **One live subscription per item, across rails.** Cancel the old one before creating a new one for the same `itemId`, or reprice with `changeAmount`.
|
|
902
964
|
9. **Period numbers differ by road.** `subscription.periodSeq` after a paid charge is the *next* period; `firstCharge.paidPeriodSeq` and the webhook's `period_seq` are the period *just paid*. Key entitlement on the latter.
|
|
903
|
-
10. **A card saved without off-session consent cannot back a subscription.** Hosted checkout and `savedCardId` purchases do not save one; use `cards.
|
|
965
|
+
10. **A card saved without off-session consent cannot back a subscription.** Hosted checkout and `savedCardId` purchases do not save one; use `cards.createSetupSession` (the INVO-hosted card page), the processor-bound `cards.beginSetup`, or a `save_card: true` purchase.
|
|
904
966
|
11. **`walletOnly` is absolute.** A card attached later is ignored until you pass `walletOnly: false` on `setPaymentMethod`.
|
|
905
967
|
12. **Price changes apply next period, and big jumps never apply.** More than double, or above 25000.00, stays pending.
|
|
906
968
|
13. **`sub_` is reserved** as a prefix for every idempotency key on the platform.
|
|
@@ -1027,7 +1089,7 @@ try {
|
|
|
1027
1089
|
`transfer.refunded` remain the source of truth — reconcile off those, not the messages.
|
|
1028
1090
|
- **`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.
|
|
1029
1091
|
- **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.
|
|
1030
|
-
- **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.
|
|
1092
|
+
- **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. **This is a rule about currency moving between titles, not about spending.** A player can spend any balance on items in any title, Steam-distributed or not, including currency bought through Steam, so an item purchase never fails on origin and there is nothing to branch on there.
|
|
1031
1093
|
- Transfer self-claim may be disabled for your tenant; if it is, surface the claim-code path instead.
|
|
1032
1094
|
- **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`).
|
|
1033
1095
|
- **Guardian approval goes by email first.** When a minor's initiate returns the 202, the guardian gets a
|
|
@@ -1446,7 +1508,7 @@ Each settle call takes the body `{"device_code": "..."}` and the player's bearer
|
|
|
1446
1508
|
the same token that began the grant.
|
|
1447
1509
|
|
|
1448
1510
|
**Available to every title, with nothing to configure.** The constraint is a property of
|
|
1449
|
-
the *device*, not your
|
|
1511
|
+
the *device*, not your title: a title with a website *and* a console build uses the normal
|
|
1450
1512
|
ceremony in the browser and this one on the console.
|
|
1451
1513
|
|
|
1452
1514
|
**Native Steam and desktop game clients (Mac & Windows) belong here too.** Even though the
|
|
@@ -1731,7 +1793,7 @@ export const POST = createWebhookHandler({
|
|
|
1731
1793
|
| `subscription.payment_failed` / `subscription.past_due` | every failed attempt / entering `past_due` once | notify the member; **access is retained** — do not revoke (`failure_code, retry_at, retries_remaining, grace_period_end, access_retained`) |
|
|
1732
1794
|
| `subscription.authentication_required` | a card issuer wants the cardholder to authenticate (card rail) | **not a failure** — relay `confirmation_url` before `expires_at` |
|
|
1733
1795
|
| `subscription.canceled` | a cancel request (yours, or the member's from Steam: `canceled_by`) | revoke at `access_until` |
|
|
1734
|
-
| `subscription.expired` | the retry budget ran out, a Steam row was never authorised (`steam_authorization_abandoned`)
|
|
1796
|
+
| `subscription.expired` | the retry budget ran out, or a Steam row was never authorised (`steam_authorization_abandoned`). `steam_containment` is **no longer returned**: spending is not restricted by which rail bought the currency | **revoke at `final_period_end`** (not `ended_at`; `null` if nothing was ever paid) |
|
|
1735
1797
|
| `subscription.refunded` | a period refund | record the reversal (`refund.partner_revenue_reversed_usd`, `is_full_refund`, `revenue_share_attribution`) |
|
|
1736
1798
|
| `transfer.received` / `transfer.claim_expired` / `transfer.refunded` | sends & transfers | reconcile claim state — credited to the recipient (by any claim path, the hosted claim page included) / not collected within 24h / returned to the sender |
|
|
1737
1799
|
|
|
@@ -1863,7 +1925,7 @@ try {
|
|
|
1863
1925
|
| `platformCommerce.getStatus(orderId)` | `{ orderId, status, gameCurrencyAmount?, usdAmount?, paymentMethod?, createdAt?, raw }` |
|
|
1864
1926
|
| `platformCommerce.refund({ orderId? \| clientRequestId?, reason? })` | `{ status, orderId?, fundingSource?, refundedAmount?, amountUnit?, feeRetained?, raw }` — pass **exactly one** id; INVO keeps its fee |
|
|
1865
1927
|
| `subscriptions.create(input)` | `SubscriptionResult` — `{ status, idempotentReplay, subscription, card, firstCharge, warning?, raw }`; **card rail**, charges the first period before answering; branch on `firstCharge.status` (`paid` \| `requires_action` \| `skipped_trial` \| `failed` \| `pending`); idempotent on `clientRequestId` (a repeat is `idempotentReplay: true`, never thrown) |
|
|
1866
|
-
| `subscriptions.get(id, { includePlayer? })` | `{ subscription, player?, raw }
|
|
1928
|
+
| `subscriptions.get(id, { includePlayer? })` | `{ subscription, player?, raw }`: `subscription.paidThrough` is the entitlement boundary; `currentPeriodEnd` is only the billing window; `includePlayer: true` adds `subscription.playerEmail` / `subscription.playerName` (INVO puts them on the object; `player` is derived from them) |
|
|
1867
1929
|
| `subscriptions.listForPlayer(playerEmail, { status?, limit?, offset?, includePlayer? })` | `{ playerEmail, subscriptions, pagination: { totalCount, limit, offset, hasMore }, raw }` — newest first; `status: "live"` expands to the four live statuses |
|
|
1868
1930
|
| `subscriptions.cancel(id, { atPeriodEnd?, reason? })` | `CancelResult` — `{ alreadyCanceled, cancelAtPeriodEnd, terminatedImmediately, effectiveAt, accessUntil, paidThrough, subscription, raw }`; an already-terminal row is a 200 with `alreadyCanceled: true` |
|
|
1869
1931
|
| `subscriptions.changeAmount(id, amountUsd)` | `ChangeAmountResult` — `{ oldAmountUsd, newAmountUsd, pendingAmountUsd, changeQueued, appliesFrom, appliesFromPeriodSeq, prorated, subscription, raw }`; staged for the next renewal (Steam: increases throw `isSteamReauthorizationRequired`) |
|
|
@@ -1871,8 +1933,9 @@ try {
|
|
|
1871
1933
|
| `subscriptions.refund(id, { clientRequestId, periodSeq?, amountUsd?, reason? })` | `RefundResult` — the receipt (`isFullRefund, fundingShape, balanceDeltaCoins, cardRefundedUsd, partnerRevenueReversedUsd, revenueShareAttribution, idempotentReplay, raw`); idempotent on `clientRequestId`; Steam-charged periods throw `isSteamRefundNotSupported` |
|
|
1872
1934
|
| `subscriptions.steamInit(input)` | `SteamInitResult` — `{ status, subscriptionStatus, idempotentReplay, pendingReuse, subscription, subscriptionId, orderId, steamOrderId, steamTransid, steamCheckoutUrl, amountUsd, amountCoins, steamChargeUsd, recurringAmountUsd, firstCharge, message, raw }`; **Steam rail**, nothing charged until finalize; match the Steam client callback on `steamOrderId` |
|
|
1873
1935
|
| `subscriptions.steamFinalize(subscriptionId)` | `SteamFinalizeSubscriptionResult` — the `SubscriptionResult` plus `{ alreadyProcessed, steamAgreementStatus, sandboxAutoApproved }`; `isNotAuthorized` (409) is the normal wait state |
|
|
1874
|
-
| `cards.
|
|
1875
|
-
| `cards.
|
|
1936
|
+
| `cards.createSetupSession({ playerEmail, successUrl?, cancelUrl?, metadata? })` | `CardSetupSessionResult`: `{ sessionId, cardSetupUrl, expiresAt, raw }`. **The recommended card capture for subscriptions**: mint a 10-minute link to the INVO-hosted card page, send the member to `cardSetupUrl` (top-level), then read the card's `id` from `cards.list`; no browser code, no processor named; never auto-retried; `isPlayerNotFound` / `isInvalidPlayerEmail` / `isInvalidInput` |
|
|
1937
|
+
| `cards.beginSetup({ playerEmail, setupReference, paymentMethodId? })` | `CardSetupResult`: `{ status, setupIntentId, clientSecret?, publishableKey?, card, alreadySaved, raw }`; the **processor-bound** card capture (you run the card form; charges nothing; idempotent on `setupReference`) |
|
|
1938
|
+
| `cards.confirmSetup({ setupIntentId })` | `{ status, setupIntentId, card, alreadySaved, raw }`: finish a client-confirmed setup on the processor-bound path |
|
|
1876
1939
|
| `cards.list(playerEmail)` | `{ cards: SavedCard[], raw }` — unexpired cards, newest first; `card.id` is the `playerCardId` |
|
|
1877
1940
|
| `sandbox.subscriptions.advanceClock(id, intervals?)` / `forceRenewal(id)` / `forceFailure(id, outcome?, { failureCode?, failureMessage? })` / `forceAuthChallenge(id, { failureMessage? })` | `SandboxClockResult` — `{ status, action, subscription, before?, after?, engineStats?, retryScheduleDays?, retriesRemaining?, authChallengesUsed?, …, raw }`; **sandbox only**, posts to `/subscriptions/<id>/...` relative to the sandbox base (not `/api`), needs `sandboxClockKey`; never auto-retried |
|
|
1878
1941
|
| `getPlayerBalance({ playerEmail })` | `{ player, balances, summary, raw }` — **by email only** (no by-id route; use `InvoClient.getBalance()` client-side) |
|
|
@@ -563,6 +563,34 @@ var InvoError = class _InvoError extends Error {
|
|
|
563
563
|
get isGameNotLive() {
|
|
564
564
|
return this.code === "GAME_NOT_LIVE";
|
|
565
565
|
}
|
|
566
|
+
// ---- Card setup session (the INVO-hosted card page) ----
|
|
567
|
+
/**
|
|
568
|
+
* True when `cards.createSetupSession` was refused because the member does not exist
|
|
569
|
+
* in this game yet (`PLAYER_NOT_FOUND`, 404). The card page never creates players;
|
|
570
|
+
* create the member first (any endpoint that creates players, for example a currency
|
|
571
|
+
* purchase), then mint the session again. The same code comes back from
|
|
572
|
+
* `cards.beginSetup` and from `mintPlayerToken` for the same reason.
|
|
573
|
+
*/
|
|
574
|
+
get isPlayerNotFound() {
|
|
575
|
+
return this.code === "PLAYER_NOT_FOUND";
|
|
576
|
+
}
|
|
577
|
+
/**
|
|
578
|
+
* True when `cards.createSetupSession` was refused because `playerEmail` was missing or
|
|
579
|
+
* is not an email address (`INVALID_PLAYER_EMAIL`, 400).
|
|
580
|
+
*/
|
|
581
|
+
get isInvalidPlayerEmail() {
|
|
582
|
+
return this.code === "INVALID_PLAYER_EMAIL";
|
|
583
|
+
}
|
|
584
|
+
/**
|
|
585
|
+
* True on an `INVALID_INPUT` refusal. Two sources, told apart by `status`:
|
|
586
|
+
* `status === 0` is this SDK refusing a value before the network (every client-side
|
|
587
|
+
* guard uses this code); `status === 400` is INVO refusing one, on
|
|
588
|
+
* `cards.createSetupSession` a `successUrl` / `cancelUrl` that uses a script scheme
|
|
589
|
+
* (`javascript:`, `data:`, `vbscript:`). http(s) and app deep-link schemes are fine.
|
|
590
|
+
*/
|
|
591
|
+
get isInvalidInput() {
|
|
592
|
+
return this.code === "INVALID_INPUT";
|
|
593
|
+
}
|
|
566
594
|
/** Seconds to wait before retrying, when the backend throttled the call (429 `retry_after`). */
|
|
567
595
|
get retryAfter() {
|
|
568
596
|
const v = this.bodyObject()["retry_after"];
|
|
@@ -846,5 +874,5 @@ function toDestinationsResult(raw, direction) {
|
|
|
846
874
|
}
|
|
847
875
|
|
|
848
876
|
export { Http, InvoError, assertSecureBaseUrl, toDestinationsResult };
|
|
849
|
-
//# sourceMappingURL=chunk-
|
|
850
|
-
//# sourceMappingURL=chunk-
|
|
877
|
+
//# sourceMappingURL=chunk-NB6UF657.js.map
|
|
878
|
+
//# sourceMappingURL=chunk-NB6UF657.js.map
|
package/dist/index.cjs
CHANGED
|
@@ -565,6 +565,34 @@ var InvoError = class _InvoError extends Error {
|
|
|
565
565
|
get isGameNotLive() {
|
|
566
566
|
return this.code === "GAME_NOT_LIVE";
|
|
567
567
|
}
|
|
568
|
+
// ---- Card setup session (the INVO-hosted card page) ----
|
|
569
|
+
/**
|
|
570
|
+
* True when `cards.createSetupSession` was refused because the member does not exist
|
|
571
|
+
* in this game yet (`PLAYER_NOT_FOUND`, 404). The card page never creates players;
|
|
572
|
+
* create the member first (any endpoint that creates players, for example a currency
|
|
573
|
+
* purchase), then mint the session again. The same code comes back from
|
|
574
|
+
* `cards.beginSetup` and from `mintPlayerToken` for the same reason.
|
|
575
|
+
*/
|
|
576
|
+
get isPlayerNotFound() {
|
|
577
|
+
return this.code === "PLAYER_NOT_FOUND";
|
|
578
|
+
}
|
|
579
|
+
/**
|
|
580
|
+
* True when `cards.createSetupSession` was refused because `playerEmail` was missing or
|
|
581
|
+
* is not an email address (`INVALID_PLAYER_EMAIL`, 400).
|
|
582
|
+
*/
|
|
583
|
+
get isInvalidPlayerEmail() {
|
|
584
|
+
return this.code === "INVALID_PLAYER_EMAIL";
|
|
585
|
+
}
|
|
586
|
+
/**
|
|
587
|
+
* True on an `INVALID_INPUT` refusal. Two sources, told apart by `status`:
|
|
588
|
+
* `status === 0` is this SDK refusing a value before the network (every client-side
|
|
589
|
+
* guard uses this code); `status === 400` is INVO refusing one, on
|
|
590
|
+
* `cards.createSetupSession` a `successUrl` / `cancelUrl` that uses a script scheme
|
|
591
|
+
* (`javascript:`, `data:`, `vbscript:`). http(s) and app deep-link schemes are fine.
|
|
592
|
+
*/
|
|
593
|
+
get isInvalidInput() {
|
|
594
|
+
return this.code === "INVALID_INPUT";
|
|
595
|
+
}
|
|
568
596
|
/** Seconds to wait before retrying, when the backend throttled the call (429 `retry_after`). */
|
|
569
597
|
get retryAfter() {
|
|
570
598
|
const v = this.bodyObject()["retry_after"];
|
package/dist/index.d.cts
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
|
-
import { A as ApproveResult, C as ConfirmReceiptResult, M as MountCheckoutOptions, a as CheckoutMountHandle, b as ClientConfig, c as CallOptions, 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 { A as ApproveResult, C as ConfirmReceiptResult, M as MountCheckoutOptions, a as CheckoutMountHandle, b as ClientConfig, c as CallOptions, 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-CUzSzV8-.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-CUzSzV8-.cjs';
|
|
3
3
|
|
|
4
4
|
/** The four device-approval flows (`begin.flow`). */
|
|
5
5
|
type HostedFlow = "transfer" | "send" | "send_receipt" | "transfer_receipt";
|
package/dist/index.d.ts
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
|
-
import { A as ApproveResult, C as ConfirmReceiptResult, M as MountCheckoutOptions, a as CheckoutMountHandle, b as ClientConfig, c as CallOptions, 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 { A as ApproveResult, C as ConfirmReceiptResult, M as MountCheckoutOptions, a as CheckoutMountHandle, b as ClientConfig, c as CallOptions, 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-CUzSzV8-.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-CUzSzV8-.js';
|
|
3
3
|
|
|
4
4
|
/** The four device-approval flows (`begin.flow`). */
|
|
5
5
|
type HostedFlow = "transfer" | "send" | "send_receipt" | "transfer_receipt";
|
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-NB6UF657.js';
|
|
2
|
+
export { InvoError } from './chunk-NB6UF657.js';
|
|
3
3
|
|
|
4
4
|
// src/shared/webauthn.ts
|
|
5
5
|
function malformedOptions(field) {
|