@invonetwork/web-sdk 3.2.3 → 3.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -4,6 +4,103 @@ 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.5.0] - 2026-09-01
8
+
9
+ **The Steam purchase flow is now first-class SDK surface: `steamPacks()`, `steamInitPurchase()`, `steamFinalizePurchase()`** — plus browser-based checkout for platforms where the Steam overlay does not render, a finalize-poller error taxonomy, and webhook `channel` typing. No breaking changes.
10
+
11
+ Until now the SDK only *steered away* from Steam (`purchaseCurrency` fails fast on `rail: "steam"`); the dedicated endpoints had to be called by hand. All three are typed methods now, and the fail-fast message names them.
12
+
13
+ ### Added
14
+
15
+ - **`InvoServer.steamPacks(query?)`** — the pack catalogue. `currencyAmount` is per-player (VAT and the storefront's revenue share come out of the sticker before currency is derived — a $4.99 pack yields 34, not 50, units at $1 = 10). Render it verbatim; never compute currency from price and never cache one answer for all players.
16
+ - **`InvoServer.steamInitPurchase(input)`** — start the purchase. Idempotent on `purchaseReference` (retries, including manual retries after a 409, MUST reuse it). New authorization modes:
17
+ - `usersession: "client"` (default, unchanged): Steam overlay in-game. The SDK sends **no** `usersession` key at all in this mode, pinned by test, so existing behaviour cannot shift.
18
+ - `usersession: "web"`: for platforms where the overlay does not render (observed: Electron on macOS). Requires `playerIp` — the PLAYER's address, never your server's; refused client-side before the network without it. Returns `steamCheckoutUrl`: Steam's own hosted approval page, which must open as a **top-level tab** (it cannot be iframed). *Note: Steam's sandbox issues checkout URLs its production host will not serve, so web-session approval is provable only against production; the rest of the flow is identical to client-session.*
19
+ - `metadata` — echoed on the `purchase.completed` webhook (`data.metadata`) — the way to correlate your own player/order ids. The Steam rail merges its own context keys (`steam_wallet_currency`, `steam_country`, `steam_account_status`, `vat_rate_pct`) into the echoed object; avoid those names in yours.
20
+ - **`InvoServer.steamFinalizePurchase({orderId})`** — capture + credit. Idempotent: a replay returns `alreadyProcessed: true` and never credits twice.
21
+ - **Finalize poller taxonomy on `InvoError`** — because *not every 409 means "not yet"*, and a poller that assumes so polls a dead order forever:
22
+ - `isSteamAuthorizationPending` — player has not approved yet (Steam reports `Init`). The normal wait state; poll again.
23
+ - `isSteamAuthorizationDead` — any settled status — `Cancelled`, `Failed`, `Refunded`, `Chargedback`, and every other non-Init outcome (pending is the CLOSED set: only `Init` means "not yet"). Stop; no later call can succeed.
24
+ - The two are mutually exclusive by construction, and a test pins that they can never both answer true.
25
+ - **`InvoError.isPartnerCreditUnavailable`** (`PARTNER_CREDIT_UNAVAILABLE`, 409) — the studio's settlement float cannot cover the purchase. Structure is fine; the money is not. Plain failure toast; do **not** hot-poll init (each attempt briefly re-reserves headroom), and reuse the same `purchaseReference` on manual retry.
26
+ - **`InvoError.isPartnerRailSuspended`** (`PARTNER_RAIL_SUSPENDED`, 409) — terminal from the game's seat. The umbrella `isPartnerSettlementUnavailable` still covers both.
27
+ - **`InvoError.isUnknownSteamPack`** (400) — re-fetch `steamPacks()`; the body's `valid_pack_ids` lists what exists.
28
+ - **`InvoError.isMissingPlayerIp`** (400) — always an integration bug on web sessions.
29
+ - **`PurchaseCompletedData.channel`** — which storefront the purchase came from (`"steam"` / `"ios"` / `"android"` / `"web"` / `"console"`), beside `rail`. `null` means a legacy game key: a real answer ("unattributed"), read it as one.
30
+
31
+ ### Changed
32
+
33
+ - `purchaseCurrency`'s `rail: "steam"` fail-fast message now names the real methods instead of vaguely citing "dedicated endpoints".
34
+
35
+ ## [3.4.0] - 2026-09-01
36
+
37
+ **A Steam title now bills through its OWN Steam application.** New error helpers;
38
+ no breaking changes to any existing method or type.
39
+
40
+ ### Why this is a real change and not a doc tidy
41
+
42
+ Steam pays whoever owns the Steam application. Until now, INVO documented a
43
+ single INVO-owned Steam app that billed every title on the network — so a studio
44
+ had nothing to register and the money reached them through INVO. That model is
45
+ gone. Each title sells through the studio's own Steam app, the money lands in
46
+ their own Steamworks account, and INVO issues the player's currency immediately
47
+ and settles with the studio afterwards against a payment method on file.
48
+
49
+ If you shipped against 3.3.0 or earlier and your Steam integration works today,
50
+ nothing in your code needs to change. What changes is the **studio's** one-time
51
+ setup, and the errors you may now see if they have not done it.
52
+
53
+ ### Added
54
+
55
+ - `InvoError.isSteamNotConfigured` — the title has no Steam application
56
+ registered with INVO yet (`STEAM_NOT_CONFIGURED`, 503).
57
+ - `InvoError.isPartnerBillingNotSetUp` — the studio has not finished INVO billing
58
+ setup (`PARTNER_BILLING_NOT_SET_UP`, 409).
59
+ - `InvoError.isPartnerSettlementUnavailable` — settlement suspended or over
60
+ limit (`PARTNER_RAIL_SUSPENDED` / `PARTNER_CREDIT_UNAVAILABLE`, 409). Show a
61
+ neutral "purchases are unavailable right now": it is not the player's problem.
62
+ - `InvoError.isSteamAppChanged` — the order was started against a different
63
+ Steam application than the title is configured for now (`STEAM_APP_CHANGED`,
64
+ 409). Only reachable if a studio swaps apps mid-flight.
65
+
66
+ All four are refused **before the player is charged**, which is the point.
67
+
68
+ ### Changed
69
+
70
+ - README: the Steam section now documents the studio's Steamworks setup
71
+ (microtransactions enabled, a publisher-GROUP Web API key that includes the
72
+ app, appid + key entered in the INVO dashboard, payment method on file).
73
+ - README: removed the claim that no Steam-side registration was required.
74
+
75
+ ## [3.3.0] - 2026-08-31
76
+
77
+ **Documentation only. No code changes, no API changes.**
78
+
79
+ Documents **Device Approval** — passkey step-up for consoles, TVs and any device
80
+ with no browser. It is the OAuth 2.0 Device Authorization Grant
81
+ ([RFC 8628](https://datatracker.ietf.org/doc/html/rfc8628)), so a standard
82
+ client library understands the responses.
83
+
84
+ - The device shows a short code and a QR (`verification_uri_complete`); the
85
+ player approves on their phone; your **server** polls
86
+ `POST /api/sdk/approvals/device/poll` until it hears back.
87
+ - **One approval authorises one transaction.** Unlike the plain RFC 8628 grant,
88
+ which authorises a *client*, an INVO device code is bound to the transaction
89
+ you named and is consumed when used — it cannot approve anything else and
90
+ cannot be reused.
91
+ - `user_code` is meant to be seen; `device_code` is not. Poll from your backend.
92
+ - Subscribe to `device_approval.approved` to learn the moment an approval lands
93
+ instead of waiting for the next poll. Polling still works alone.
94
+ - Available to every title with nothing to configure — the constraint is a
95
+ property of the *device*, not the game, so a title with a website and a
96
+ console build uses the normal ceremony in the browser and this one on console.
97
+ - Currency purchases on a console go through that console's store, as the
98
+ platform holder requires; this flow is for approving transfers and sends.
99
+
100
+ Minor rather than patch because it documents a new API surface. The snippets are
101
+ pinned by a test against this file, for the same reason the Steam ones are: a
102
+ REST flow with no SDK method behind it is the one thing no other test can see.
103
+
7
104
  ## [3.2.3] - 2026-08-28
8
105
 
9
106
  **Documentation only. No code changes, no API changes.** Corrects two errors in
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.2.3` — 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.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).
5
+ > **Status:** `v3.5.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.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
@@ -210,7 +210,7 @@ INVO enables each flow for your tenant in the [console](#get-your-account--game-
210
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)).
211
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.)
212
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)).
213
- - **For currency purchase:** card checkout works out of the box; ask INVO to enable the `game`/`steam` rails if you need them.
213
+ - **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).
214
214
  - **For item purchase:** nothing extra — it's a currency-balance debit.
215
215
 
216
216
  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.
@@ -300,6 +300,33 @@ The `rail` selects the in-page experience — all branded INVO, no visible redir
300
300
  - `"game"` — regional / game-store methods (may redirect to the regional hosted page).
301
301
  - `"steam"` — Steam titles hand off to the in-client Steam flow.
302
302
 
303
+ > ### Steam titles: before any of this works, the studio has setup to do
304
+ >
305
+ > **Steam pays whoever owns the Steam application.** Every INVO title therefore
306
+ > sells currency through **its own Steam app**, and the money lands in the
307
+ > studio's own Steamworks account. INVO issues the player's currency the moment
308
+ > Steam captures the charge, then settles with the studio separately against a
309
+ > payment method they keep on file.
310
+ >
311
+ > Once per title, in the INVO dashboard:
312
+ >
313
+ > 1. Enable **in-game purchases (microtransactions)** for the app in Steamworks.
314
+ > 2. Create a **publisher Web API key** — a *publisher group* key, not a personal
315
+ > user key, with the app in the group. A personal key fails verification.
316
+ > 3. Enter the **app id** and that **key** under the title's Steam settings. INVO
317
+ > calls Steam to prove the pair before saving it.
318
+ > 4. Add a **payment method** on the Billing screen and accept the authorisation.
319
+ >
320
+ > Until all four are done, purchases are refused **before the player is charged**:
321
+ > `STEAM_NOT_CONFIGURED` (503) or `PARTNER_BILLING_NOT_SET_UP` (409). That is
322
+ > deliberate — the alternative is taking a player's money for currency that
323
+ > cannot be issued.
324
+ >
325
+ > **This changed in September 2026.** Versions before 3.4.0 said Steam purchases
326
+ > ran through an INVO-owned Steam app and there was nothing to register. That was
327
+ > true while one INVO application billed every title; it is not true now, and
328
+ > following the old text leaves the rail closed.
329
+
303
330
  > **Steam titles: currency must be bought through Steam, and INVO sets the packs.**
304
331
  >
305
332
  > A title distributed on Steam may only sell currency on the `steam` rail — any other
@@ -323,54 +350,92 @@ Provider/processor names are an internal detail and never appear in the API.
323
350
 
324
351
  ### Steam purchases (packs, not prices)
325
352
 
326
- Steam is **not** an SDK method — it is a server-to-server REST flow, because the
327
- purchase is authorised inside the Steam client and your game has to relay that.
328
- `purchaseCurrency` rejects `rail: "steam"` with `WRONG_RAIL_ENDPOINT` for that reason.
353
+ Steam has first-class SDK methods as of 3.5.0: `steamPacks()`, `steamInitPurchase()`,
354
+ `steamFinalizePurchase()` — all on `InvoServer`, all server-side, because the game
355
+ secret must never reach a client. `purchaseCurrency` still rejects `rail: "steam"`
356
+ with `WRONG_RAIL_ENDPOINT` and points you here.
329
357
 
330
358
  **INVO owns the pack catalogue.** You never send a price. Fetch the packs, show them,
331
- pass a `pack_id` back.
359
+ pass a `packId` back.
332
360
 
333
361
  ```ts
334
362
  // 1. The catalogue, priced for THIS player. Always pass steamid.
335
- const res = await fetch(
336
- `${INVO_BASE}/api/currency-purchases/steam/packs?steamid=${steamId}`,
337
- { headers: { "X-Game-Secret-Key": GAME_SECRET } },
338
- );
339
- const { country, vat_rate_pct, packs } = await res.json();
340
- // packs: [{ pack_id, label, price_usd, currency_amount }, ...]
363
+ const { packs, country, vatRatePct } = await server.steamPacks({ steamid: steamId });
364
+ // packs: [{ packId, label, priceUsd, currencyAmount }, ...]
341
365
 
342
366
  // 2. Start the purchase with the pack the player chose.
343
- const init = await fetch(`${INVO_BASE}/api/currency-purchases/steam/init-purchase`, {
344
- method: "POST",
345
- headers: { "X-Game-Secret-Key": GAME_SECRET, "Content-Type": "application/json" },
346
- body: JSON.stringify({
347
- player_email: "player@example.com",
348
- steamid: steamId,
349
- pack_id: "steam_medium", // NOT a price
350
- purchase_reference: crypto.randomUUID(),
351
- }),
367
+ const init = await server.steamInitPurchase({
368
+ playerEmail: "player@example.com",
369
+ steamid: steamId,
370
+ packId: "steam_medium", // NOT a price
371
+ purchaseReference: myIdempotencyKey, // unique per INTENDED purchase; reuse on retry
372
+ metadata: { playerId: myPlayerId }, // echoed on the purchase.completed webhook
352
373
  });
353
- // -> { order_id, steam_transid, pack_id, charged_usd, currency_amount }
354
-
355
- // 3. Steam shows its overlay. Your game client receives
356
- // MicroTxnAuthorizationResponse_t and tells your backend to finalize.
357
- // 4. POST /steam/finalize-purchase { order_id } -> currency is credited.
374
+ // -> { orderId, steamTransid, packId, chargedUsd, currencyAmount }
375
+
376
+ // 3a. CLIENT SESSION (default): Steam shows its in-game overlay. Your game
377
+ // client receives MicroTxnAuthorizationResponse_t and tells your backend.
378
+ // 3b. WEB SESSION: for platforms where the overlay does not render (observed:
379
+ // Electron on macOS). Pass usersession: "web" + playerIp (the PLAYER's IP,
380
+ // never your server's) and open the returned steamCheckoutUrl as a
381
+ // TOP-LEVEL browser tab — it cannot be iframed.
382
+
383
+ // 4. Finalize: INVO re-checks the authorization with Steam, captures, credits.
384
+ const done = await server.steamFinalizePurchase({ orderId: init.orderId });
385
+ // -> { status: "success", newBalance, alreadyProcessed }
358
386
  ```
359
387
 
360
388
  **The price is identical everywhere; the currency inside is not.** Steam prices are
361
- VAT-inclusive wherever VAT is collected, so more of a fixed price goes to tax in a
362
- high-VAT country and less is left to buy currency with — the same `$9.99` pack yields
363
- **69** units in the US and **58** in France.
389
+ VAT-inclusive wherever VAT is collected, and the storefront's revenue share comes out
390
+ before currency is derived — so the same `$9.99` pack yields **69** units in the US
391
+ and **58** in France, and a `$4.99` pack yields **34**, not 50. Render
392
+ `currencyAmount` verbatim; never compute currency from the sticker price.
393
+
394
+ **Finalize is idempotent, and not every 409 means "try later".** A replay returns
395
+ `alreadyProcessed: true` and never credits twice. For a poller, branch on the error:
396
+
397
+ | Signal | Meaning | Do |
398
+ |---|---|---|
399
+ | `err.isSteamAuthorizationPending` | player has not approved yet (`Init`) | keep polling / wait for the callback |
400
+ | `err.isSteamAuthorizationDead` | any settled status: `Cancelled` / `Failed` / `Refunded` / `PartialRefund` / `Chargedback` / anything else non-Init | **stop** — no later call can succeed |
401
+ | `err.isSteamAppChanged` | the title's registration changed under the order | stop; terminal for this order |
402
+ | HTTP 502 / 503 | transient | retry |
403
+ | `"Order is not finalizable"` (4xx, no `not_authorized`) | the reconciler already settled the order's fate | **stop** |
404
+
405
+ A poller that treats every 409 as "not yet" polls a dead order forever. And a missed
406
+ finalize is not a lost credit — INVO's reconciler independently detects the authorized
407
+ transaction and credits, on a delay.
408
+
409
+ **Refusals before any charge**, so a player is never charged for currency that cannot
410
+ be issued:
411
+
412
+ - `err.isPartnerCreditUnavailable` — the studio's settlement float cannot cover it.
413
+ Plain failure toast; do **not** hot-poll init (each attempt briefly re-reserves
414
+ headroom), and reuse the same `purchaseReference` on a manual retry.
415
+ - `err.isPartnerRailSuspended` — terminal from the game's seat until the studio
416
+ resolves it in the INVO console.
417
+ - `err.isUnknownSteamPack` — re-fetch `steamPacks()`; the body's `valid_pack_ids`
418
+ lists what exists. The catalogue is INVO's and changes without an SDK release.
419
+ - `err.isSteamNotConfigured` (503) / `err.isSteamRailNotEntitled` (403) — the studio's
420
+ one-time Steam setup is incomplete.
421
+ - A locked Steam account is refused up front with `409 STEAM_ACCOUNT_LOCKED`.
364
422
 
365
- - **Always pass `steamid`** to `/steam/packs`. Without it the amounts are quoted with
423
+ - **Always pass `steamid`** to `steamPacks()`. Without it the amounts are quoted with
366
424
  no VAT deducted — the most any pack yields — so your store promises more than the
367
425
  purchase delivers.
368
426
  - **Do not cache one catalogue for all players**, and do not hard-code amounts. Pack
369
427
  prices and VAT rates are both configuration and change without an SDK release.
370
- - **A Steam-distributed title may only sell on this rail.** Any other is refused with
371
- `409 STEAM_PURCHASE_LAYER_REQUIRED`, across every storefront the title ships on,
372
- because a player's balance is shared between them.
373
- - A locked Steam account is refused up front with `409 STEAM_ACCOUNT_LOCKED`.
428
+ - **On a Steam-distributed title, a channel key may only sell on its own channel's
429
+ rail.** A mismatched caller is refused with `409 STEAM_PURCHASE_LAYER_REQUIRED`.
430
+ (The old absolute form — "only the Steam rail, across every storefront" — was
431
+ the rule before 2026-08-31 and no longer holds for channel-keyed callers.)
432
+ - **Correlation is `metadata`, not `purchase_reference`.** The webhook payload
433
+ deliberately omits your idempotency key; put your own player/order ids in
434
+ `metadata` and read them back at `data.metadata` on `purchase.completed` — note the
435
+ Steam rail ADDS its own context keys (`steam_wallet_currency`, `steam_country`,
436
+ `steam_account_status`, `vat_rate_pct`) into the echoed object, so avoid those
437
+ names in yours
438
+ (`data.channel` is the channel of the KEY you presented — `"steam"` when you call with your Steam channel key; `null` on a legacy game key).
374
439
 
375
440
  ### Direct rail (advanced — you tokenize the card yourself)
376
441
 
@@ -679,6 +744,65 @@ try {
679
744
  - Challenges are single-use and bound to `{flow}:{transactionId}`.
680
745
  - The SDK passes the backend's WebAuthn options through unchanged (it does not hard-code `pubKeyCredParams`/`timeout`/`attestation`).
681
746
 
747
+ ### Consoles and TVs — approving without a browser (RFC 8628)
748
+
749
+ A console has no browser, so it cannot run a passkey ceremony at all. **Device
750
+ Approval** moves the ceremony to a device that can: your game shows a short code, the
751
+ player approves on their phone, your server polls until it hears back. It is the
752
+ [OAuth 2.0 Device Authorization Grant, RFC 8628](https://datatracker.ietf.org/doc/html/rfc8628)
753
+ — the same flow every console and TV app uses — so a standard client library understands
754
+ the responses.
755
+
756
+ **Not an SDK method** — it is a server-to-server REST flow, because the polling has to
757
+ happen on your backend, not in the game client.
758
+
759
+ **Available to every title, with nothing to configure.** The constraint is a property of
760
+ the *device*, not your game: a title with a website *and* a console build uses the normal
761
+ ceremony in the browser and this one on the console.
762
+
763
+ ```ts
764
+ // 1. Your server starts an approval for ONE transaction.
765
+ // flow: "transfer" | "send" | "send_receipt" | "transfer_receipt"
766
+ const start = await fetch(`${INVO_BASE}/api/sdk/approvals/device/begin`, {
767
+ method: "POST",
768
+ headers: { Authorization: `Bearer ${sdkSessionToken}`, "Content-Type": "application/json" },
769
+ body: JSON.stringify({ transaction_id: transferId, flow: "transfer" }),
770
+ }).then((r) => r.json());
771
+ // -> { device_code, user_code, verification_uri, verification_uri_complete,
772
+ // expires_in, interval }
773
+
774
+ // 2. The game renders `verification_uri_complete` as a QR and prints `user_code`
775
+ // under it. The QR already contains the code, so most players never type.
776
+
777
+ // 3. Poll from your SERVER, never faster than `interval` seconds.
778
+ const poll = await fetch(`${INVO_BASE}/api/sdk/approvals/device/poll`, {
779
+ method: "POST",
780
+ headers: { Authorization: `Bearer ${sdkSessionToken}`, "Content-Type": "application/json" },
781
+ body: JSON.stringify({ device_code: start.device_code }),
782
+ }).then((r) => r.json());
783
+ // approved -> { status: "approved", transaction_id, flow }
784
+ // authorization_pending -> keep polling
785
+ // slow_down -> back off, then resume
786
+ // expired_token -> start a new approval
787
+ // access_denied -> the player declined; do not retry silently
788
+ // invalid_grant -> unknown or not yours
789
+ ```
790
+
791
+ - **One approval authorises one transaction.** Unlike the plain RFC 8628 grant, which
792
+ authorises a *client*, an INVO device code is bound to the transaction you named and is
793
+ consumed when used. It cannot approve anything else and cannot be reused.
794
+ - **`user_code` is meant to be seen; `device_code` is not.** Poll from your backend.
795
+ - **One live code per transaction.** Starting a second returns
796
+ `409 DEVICE_APPROVAL_ALREADY_PENDING` — reuse the one you have or let it expire.
797
+ - **Subscribe to `device_approval.approved`** to learn the moment an approval lands
798
+ instead of waiting for the next poll. Polling still works alone; the webhook is a
799
+ latency improvement, not a replacement.
800
+ - **The player needs an INVO passkey.** A passkey they set up on *your* domain is a
801
+ different credential and cannot be used here — that is how passkeys work. The approval
802
+ page says so plainly when they need to set one up.
803
+ - **Currency purchases on a console go through that console's store**, as the platform
804
+ holder requires. This flow is for approving transfers and sends.
805
+
682
806
  ---
683
807
 
684
808
  ## Webhooks
@@ -246,6 +246,121 @@ var InvoError = class _InvoError extends Error {
246
246
  get isSteamPurchaseLayerRequired() {
247
247
  return this.code === "STEAM_PURCHASE_LAYER_REQUIRED";
248
248
  }
249
+ /**
250
+ * True if the title has no Steam application registered with INVO yet
251
+ * (`STEAM_NOT_CONFIGURED`, 503).
252
+ *
253
+ * Steam pays whoever owns the Steam app, so every INVO title bills through
254
+ * ITS OWN Steam application. The studio adds their Steam app id and publisher
255
+ * Web API key in the INVO dashboard; until then the rail is closed. Earlier
256
+ * SDK versions said purchases ran through an INVO-owned Steam app and there
257
+ * was nothing to register — that is no longer true.
258
+ *
259
+ * Not retryable; the fix is a setup step in the dashboard.
260
+ */
261
+ get isSteamNotConfigured() {
262
+ return this.code === "STEAM_NOT_CONFIGURED";
263
+ }
264
+ /**
265
+ * True if the order was started against a DIFFERENT Steam application than the
266
+ * title is configured for now (`STEAM_APP_CHANGED`, 409).
267
+ *
268
+ * Happens when a studio swaps their Steam app while orders are in flight. The
269
+ * in-flight order cannot be captured under the new app — contact INVO to
270
+ * settle it. New purchases work normally.
271
+ */
272
+ get isSteamAppChanged() {
273
+ return this.code === "STEAM_APP_CHANGED";
274
+ }
275
+ /**
276
+ * True if the studio has not finished INVO billing setup
277
+ * (`PARTNER_BILLING_NOT_SET_UP`, 409).
278
+ *
279
+ * On Steam, Valve pays the STUDIO and INVO issues the player's currency, so
280
+ * INVO settles with the studio afterwards against a payment method they keep
281
+ * on file. No payment method, no sale. Not retryable; it is a dashboard step.
282
+ */
283
+ get isPartnerBillingNotSetUp() {
284
+ return this.code === "PARTNER_BILLING_NOT_SET_UP";
285
+ }
286
+ /**
287
+ * True if the studio's settlement has been suspended (`PARTNER_RAIL_SUSPENDED`,
288
+ * 409) or they are temporarily over their settlement limit
289
+ * (`PARTNER_CREDIT_UNAVAILABLE`, 409).
290
+ *
291
+ * Refused BEFORE the player is charged, which is deliberate — the alternative
292
+ * is taking their money for currency that cannot be issued. Show a neutral
293
+ * "purchases are unavailable right now"; do not surface it as the player's
294
+ * problem, because it is not.
295
+ */
296
+ get isPartnerSettlementUnavailable() {
297
+ return this.code === "PARTNER_RAIL_SUSPENDED" || this.code === "PARTNER_CREDIT_UNAVAILABLE";
298
+ }
299
+ /** True when the studio's settlement float cannot cover this purchase right
300
+ * now (`PARTNER_CREDIT_UNAVAILABLE`, 409) — the structure (billing profile,
301
+ * mandate, payment method) is in place; the MONEY is not. Fixed by the
302
+ * studio topping up (or a settlement sweep clearing), not by the player.
303
+ * Show a plain failure ("try again later"); do NOT hot-poll init — headroom
304
+ * changes on a human action, and each retry briefly re-reserves headroom.
305
+ * A manual retry MUST reuse the same purchaseReference. */
306
+ get isPartnerCreditUnavailable() {
307
+ return this.code === "PARTNER_CREDIT_UNAVAILABLE";
308
+ }
309
+ /** True when the studio's settlement rail is suspended
310
+ * (`PARTNER_RAIL_SUSPENDED`, 409) — collections failed repeatedly or an
311
+ * admin intervened. Terminal from the game's seat: no retry can succeed
312
+ * until the studio resolves it in the INVO console. */
313
+ get isPartnerRailSuspended() {
314
+ return this.code === "PARTNER_RAIL_SUSPENDED";
315
+ }
316
+ /** True when init-purchase was given a `packId` that is not in INVO's Steam
317
+ * catalogue (`UNKNOWN_STEAM_PACK`, 400). The error body's
318
+ * `valid_pack_ids` lists what exists; re-fetch `steamPacks()` — the
319
+ * catalogue is INVO's and can change without a deploy on your side. */
320
+ get isUnknownSteamPack() {
321
+ return this.code === "UNKNOWN_STEAM_PACK";
322
+ }
323
+ /** True when a web-session init was sent without the player's IP
324
+ * (`MISSING_PLAYER_IP`, 400). Always an integration bug: `playerIp` is
325
+ * required for `usersession: "web"` and must be the PLAYER's address as
326
+ * your server sees it — never your server's own. */
327
+ get isMissingPlayerIp() {
328
+ return this.code === "MISSING_PLAYER_IP";
329
+ }
330
+ /** True when finalize was called before the player approved the charge
331
+ * (409, `status: "not_authorized"` with Steam still reporting `Init`, or
332
+ * no status yet). THE NORMAL WAIT STATE — keep polling / wait for the
333
+ * client callback and call finalize again. Contrast
334
+ * {@link isSteamAuthorizationDead}.
335
+ *
336
+ * PENDING IS THE CLOSED SET, deliberately. The first version of this pair
337
+ * enumerated the DEAD statuses and made pending the complement — so a
338
+ * player pressing Cancel in the overlay (the most common non-approval
339
+ * outcome, which Steam reports as a status the list did not name)
340
+ * classified as "keep polling forever": the exact failure these getters
341
+ * exist to prevent, reintroduced by enumerating the author's hazards
342
+ * instead of the backend's vocabulary. Only `Init` (and an absent status)
343
+ * can mean "not yet"; every named status that is not Init is an outcome. */
344
+ get isSteamAuthorizationPending() {
345
+ const b = this.body;
346
+ if (!b || b["status"] !== "not_authorized") return false;
347
+ const st = String(b["steam_status"] ?? "").toLowerCase();
348
+ return st === "init" || st === "";
349
+ }
350
+ /** True when finalize reports the Steam transaction TERMINALLY not-approved:
351
+ * `not_authorized` with any settled status — Failed, Cancelled, Refunded,
352
+ * Chargedback, and every other non-Init outcome. STOP polling: no later
353
+ * call can succeed. (Dead is the open set on purpose: an unrecognised new
354
+ * status stops a poller rather than trapping it, and stopping wrongly costs
355
+ * one support question while polling wrongly runs forever.) A finalize
356
+ * answering `"Order is not finalizable"` with no `not_authorized` status is
357
+ * equally terminal — the reconciler has already settled the order's fate. */
358
+ get isSteamAuthorizationDead() {
359
+ const b = this.body;
360
+ if (!b || b["status"] !== "not_authorized") return false;
361
+ const st = String(b["steam_status"] ?? "").toLowerCase();
362
+ return st !== "init" && st !== "";
363
+ }
249
364
  /** True if a Platform Commerce CARD purchase was below the processor's floor of $0.50
250
365
  * (backend code `BELOW_STRIPE_MINIMUM`, 400). Neutral name; matches the wire code. */
251
366
  get isBelowCardMinimum() {
@@ -544,5 +659,5 @@ function toDestinationsResult(raw, direction) {
544
659
  }
545
660
 
546
661
  export { Http, InvoError, assertSecureBaseUrl, toDestinationsResult };
547
- //# sourceMappingURL=chunk-ZLPMCR5Q.js.map
548
- //# sourceMappingURL=chunk-ZLPMCR5Q.js.map
662
+ //# sourceMappingURL=chunk-MBKE6ULW.js.map
663
+ //# sourceMappingURL=chunk-MBKE6ULW.js.map
package/dist/index.cjs CHANGED
@@ -248,6 +248,121 @@ var InvoError = class _InvoError extends Error {
248
248
  get isSteamPurchaseLayerRequired() {
249
249
  return this.code === "STEAM_PURCHASE_LAYER_REQUIRED";
250
250
  }
251
+ /**
252
+ * True if the title has no Steam application registered with INVO yet
253
+ * (`STEAM_NOT_CONFIGURED`, 503).
254
+ *
255
+ * Steam pays whoever owns the Steam app, so every INVO title bills through
256
+ * ITS OWN Steam application. The studio adds their Steam app id and publisher
257
+ * Web API key in the INVO dashboard; until then the rail is closed. Earlier
258
+ * SDK versions said purchases ran through an INVO-owned Steam app and there
259
+ * was nothing to register — that is no longer true.
260
+ *
261
+ * Not retryable; the fix is a setup step in the dashboard.
262
+ */
263
+ get isSteamNotConfigured() {
264
+ return this.code === "STEAM_NOT_CONFIGURED";
265
+ }
266
+ /**
267
+ * True if the order was started against a DIFFERENT Steam application than the
268
+ * title is configured for now (`STEAM_APP_CHANGED`, 409).
269
+ *
270
+ * Happens when a studio swaps their Steam app while orders are in flight. The
271
+ * in-flight order cannot be captured under the new app — contact INVO to
272
+ * settle it. New purchases work normally.
273
+ */
274
+ get isSteamAppChanged() {
275
+ return this.code === "STEAM_APP_CHANGED";
276
+ }
277
+ /**
278
+ * True if the studio has not finished INVO billing setup
279
+ * (`PARTNER_BILLING_NOT_SET_UP`, 409).
280
+ *
281
+ * On Steam, Valve pays the STUDIO and INVO issues the player's currency, so
282
+ * INVO settles with the studio afterwards against a payment method they keep
283
+ * on file. No payment method, no sale. Not retryable; it is a dashboard step.
284
+ */
285
+ get isPartnerBillingNotSetUp() {
286
+ return this.code === "PARTNER_BILLING_NOT_SET_UP";
287
+ }
288
+ /**
289
+ * True if the studio's settlement has been suspended (`PARTNER_RAIL_SUSPENDED`,
290
+ * 409) or they are temporarily over their settlement limit
291
+ * (`PARTNER_CREDIT_UNAVAILABLE`, 409).
292
+ *
293
+ * Refused BEFORE the player is charged, which is deliberate — the alternative
294
+ * is taking their money for currency that cannot be issued. Show a neutral
295
+ * "purchases are unavailable right now"; do not surface it as the player's
296
+ * problem, because it is not.
297
+ */
298
+ get isPartnerSettlementUnavailable() {
299
+ return this.code === "PARTNER_RAIL_SUSPENDED" || this.code === "PARTNER_CREDIT_UNAVAILABLE";
300
+ }
301
+ /** True when the studio's settlement float cannot cover this purchase right
302
+ * now (`PARTNER_CREDIT_UNAVAILABLE`, 409) — the structure (billing profile,
303
+ * mandate, payment method) is in place; the MONEY is not. Fixed by the
304
+ * studio topping up (or a settlement sweep clearing), not by the player.
305
+ * Show a plain failure ("try again later"); do NOT hot-poll init — headroom
306
+ * changes on a human action, and each retry briefly re-reserves headroom.
307
+ * A manual retry MUST reuse the same purchaseReference. */
308
+ get isPartnerCreditUnavailable() {
309
+ return this.code === "PARTNER_CREDIT_UNAVAILABLE";
310
+ }
311
+ /** True when the studio's settlement rail is suspended
312
+ * (`PARTNER_RAIL_SUSPENDED`, 409) — collections failed repeatedly or an
313
+ * admin intervened. Terminal from the game's seat: no retry can succeed
314
+ * until the studio resolves it in the INVO console. */
315
+ get isPartnerRailSuspended() {
316
+ return this.code === "PARTNER_RAIL_SUSPENDED";
317
+ }
318
+ /** True when init-purchase was given a `packId` that is not in INVO's Steam
319
+ * catalogue (`UNKNOWN_STEAM_PACK`, 400). The error body's
320
+ * `valid_pack_ids` lists what exists; re-fetch `steamPacks()` — the
321
+ * catalogue is INVO's and can change without a deploy on your side. */
322
+ get isUnknownSteamPack() {
323
+ return this.code === "UNKNOWN_STEAM_PACK";
324
+ }
325
+ /** True when a web-session init was sent without the player's IP
326
+ * (`MISSING_PLAYER_IP`, 400). Always an integration bug: `playerIp` is
327
+ * required for `usersession: "web"` and must be the PLAYER's address as
328
+ * your server sees it — never your server's own. */
329
+ get isMissingPlayerIp() {
330
+ return this.code === "MISSING_PLAYER_IP";
331
+ }
332
+ /** True when finalize was called before the player approved the charge
333
+ * (409, `status: "not_authorized"` with Steam still reporting `Init`, or
334
+ * no status yet). THE NORMAL WAIT STATE — keep polling / wait for the
335
+ * client callback and call finalize again. Contrast
336
+ * {@link isSteamAuthorizationDead}.
337
+ *
338
+ * PENDING IS THE CLOSED SET, deliberately. The first version of this pair
339
+ * enumerated the DEAD statuses and made pending the complement — so a
340
+ * player pressing Cancel in the overlay (the most common non-approval
341
+ * outcome, which Steam reports as a status the list did not name)
342
+ * classified as "keep polling forever": the exact failure these getters
343
+ * exist to prevent, reintroduced by enumerating the author's hazards
344
+ * instead of the backend's vocabulary. Only `Init` (and an absent status)
345
+ * can mean "not yet"; every named status that is not Init is an outcome. */
346
+ get isSteamAuthorizationPending() {
347
+ const b = this.body;
348
+ if (!b || b["status"] !== "not_authorized") return false;
349
+ const st = String(b["steam_status"] ?? "").toLowerCase();
350
+ return st === "init" || st === "";
351
+ }
352
+ /** True when finalize reports the Steam transaction TERMINALLY not-approved:
353
+ * `not_authorized` with any settled status — Failed, Cancelled, Refunded,
354
+ * Chargedback, and every other non-Init outcome. STOP polling: no later
355
+ * call can succeed. (Dead is the open set on purpose: an unrecognised new
356
+ * status stops a poller rather than trapping it, and stopping wrongly costs
357
+ * one support question while polling wrongly runs forever.) A finalize
358
+ * answering `"Order is not finalizable"` with no `not_authorized` status is
359
+ * equally terminal — the reconciler has already settled the order's fate. */
360
+ get isSteamAuthorizationDead() {
361
+ const b = this.body;
362
+ if (!b || b["status"] !== "not_authorized") return false;
363
+ const st = String(b["steam_status"] ?? "").toLowerCase();
364
+ return st !== "init" && st !== "";
365
+ }
251
366
  /** True if a Platform Commerce CARD purchase was below the processor's floor of $0.50
252
367
  * (backend code `BELOW_STRIPE_MINIMUM`, 400). Neutral name; matches the wire code. */
253
368
  get isBelowCardMinimum() {
package/dist/index.d.cts CHANGED
@@ -1,5 +1,5 @@
1
- import { M as MountCheckoutOptions, C as CheckoutMountHandle, a as ClientConfig, b as CallOptions, A as ApproveResult, c as ConfirmReceiptResult, L as LinkDeviceResult, P as PendingCollectResult, D as DestinationsQuery, d as DestinationsResult, B as BalanceResult, E as EnrollmentBeginResult, e as EnrollmentVerifyResult, R as RecoveryBeginResult, f as RecoveryCompleteResult } from './types-DzmukUr9.cjs';
2
- export { g as BalanceRow, h as DestinationGame, I as InvoError, i as InvoErrorInfo, j as InvoHooks, k as InvoRequestInfo, l as InvoResponseInfo, m as PendingCollectItem, n as Rail, V as VerificationMethod } from './types-DzmukUr9.cjs';
1
+ import { M as MountCheckoutOptions, C as CheckoutMountHandle, a as ClientConfig, b as CallOptions, A as ApproveResult, c as ConfirmReceiptResult, L as LinkDeviceResult, P as PendingCollectResult, D as DestinationsQuery, d as DestinationsResult, B as BalanceResult, E as EnrollmentBeginResult, e as EnrollmentVerifyResult, R as RecoveryBeginResult, f as RecoveryCompleteResult } from './types-Dxo3IsYq.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-Dxo3IsYq.cjs';
3
3
 
4
4
  declare class PlatformCommerceClient {
5
5
  /**
package/dist/index.d.ts CHANGED
@@ -1,5 +1,5 @@
1
- import { M as MountCheckoutOptions, C as CheckoutMountHandle, a as ClientConfig, b as CallOptions, A as ApproveResult, c as ConfirmReceiptResult, L as LinkDeviceResult, P as PendingCollectResult, D as DestinationsQuery, d as DestinationsResult, B as BalanceResult, E as EnrollmentBeginResult, e as EnrollmentVerifyResult, R as RecoveryBeginResult, f as RecoveryCompleteResult } from './types-DzmukUr9.js';
2
- export { g as BalanceRow, h as DestinationGame, I as InvoError, i as InvoErrorInfo, j as InvoHooks, k as InvoRequestInfo, l as InvoResponseInfo, m as PendingCollectItem, n as Rail, V as VerificationMethod } from './types-DzmukUr9.js';
1
+ import { M as MountCheckoutOptions, C as CheckoutMountHandle, a as ClientConfig, b as CallOptions, A as ApproveResult, c as ConfirmReceiptResult, L as LinkDeviceResult, P as PendingCollectResult, D as DestinationsQuery, d as DestinationsResult, B as BalanceResult, E as EnrollmentBeginResult, e as EnrollmentVerifyResult, R as RecoveryBeginResult, f as RecoveryCompleteResult } from './types-Dxo3IsYq.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-Dxo3IsYq.js';
3
3
 
4
4
  declare class PlatformCommerceClient {
5
5
  /**
package/dist/index.js CHANGED
@@ -1,5 +1,5 @@
1
- import { InvoError, assertSecureBaseUrl, Http, toDestinationsResult } from './chunk-ZLPMCR5Q.js';
2
- export { InvoError } from './chunk-ZLPMCR5Q.js';
1
+ import { InvoError, assertSecureBaseUrl, Http, toDestinationsResult } from './chunk-MBKE6ULW.js';
2
+ export { InvoError } from './chunk-MBKE6ULW.js';
3
3
 
4
4
  // src/shared/webauthn.ts
5
5
  function malformedOptions(field) {