@invonetwork/web-sdk 3.3.0 → 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 +68 -0
- package/README.md +99 -34
- package/dist/{chunk-ZLPMCR5Q.js → chunk-MBKE6ULW.js} +117 -2
- package/dist/index.cjs +115 -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 +260 -1
- package/dist/server.d.cts +71 -4
- package/dist/server.d.ts +71 -4
- package/dist/server.js +147 -3
- package/dist/{types-DzmukUr9.d.cts → types-Dxo3IsYq.d.cts} +197 -1
- package/dist/{types-DzmukUr9.d.ts → types-Dxo3IsYq.d.ts} +197 -1
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -4,6 +4,74 @@ 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
|
+
|
|
7
75
|
## [3.3.0] - 2026-08-31
|
|
8
76
|
|
|
9
77
|
**Documentation only. No code changes, no API changes.**
|
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.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
|
|
327
|
-
|
|
328
|
-
`purchaseCurrency` rejects `rail: "steam"`
|
|
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 `
|
|
359
|
+
pass a `packId` back.
|
|
332
360
|
|
|
333
361
|
```ts
|
|
334
362
|
// 1. The catalogue, priced for THIS player. Always pass steamid.
|
|
335
|
-
const
|
|
336
|
-
|
|
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
|
|
344
|
-
|
|
345
|
-
|
|
346
|
-
|
|
347
|
-
|
|
348
|
-
|
|
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
|
-
// -> {
|
|
354
|
-
|
|
355
|
-
//
|
|
356
|
-
//
|
|
357
|
-
//
|
|
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,
|
|
362
|
-
|
|
363
|
-
**
|
|
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
|
|
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
|
-
- **
|
|
371
|
-
|
|
372
|
-
|
|
373
|
-
|
|
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
|
|
|
@@ -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-
|
|
548
|
-
//# sourceMappingURL=chunk-
|
|
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-
|
|
2
|
-
export { g as BalanceRow, h as DestinationGame, I as InvoError, i as InvoErrorInfo, j as InvoHooks, k as InvoRequestInfo, l as InvoResponseInfo, m as PendingCollectItem, n as Rail, V as VerificationMethod } from './types-
|
|
1
|
+
import { M as MountCheckoutOptions, C as CheckoutMountHandle, a as ClientConfig, b as CallOptions, A as ApproveResult, c as ConfirmReceiptResult, L as LinkDeviceResult, P as PendingCollectResult, D as DestinationsQuery, d as DestinationsResult, B as BalanceResult, E as EnrollmentBeginResult, e as EnrollmentVerifyResult, R as RecoveryBeginResult, f as RecoveryCompleteResult } from './types-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-
|
|
2
|
-
export { g as BalanceRow, h as DestinationGame, I as InvoError, i as InvoErrorInfo, j as InvoHooks, k as InvoRequestInfo, l as InvoResponseInfo, m as PendingCollectItem, n as Rail, V as VerificationMethod } from './types-
|
|
1
|
+
import { M as MountCheckoutOptions, C as CheckoutMountHandle, a as ClientConfig, b as CallOptions, A as ApproveResult, c as ConfirmReceiptResult, L as LinkDeviceResult, P as PendingCollectResult, D as DestinationsQuery, d as DestinationsResult, B as BalanceResult, E as EnrollmentBeginResult, e as EnrollmentVerifyResult, R as RecoveryBeginResult, f as RecoveryCompleteResult } from './types-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-
|
|
2
|
-
export { InvoError } from './chunk-
|
|
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) {
|