@invonetwork/web-sdk 3.2.1 → 3.2.3
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 +48 -0
- package/README.md +64 -8
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -4,6 +4,54 @@ 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.2.3] - 2026-08-28
|
|
8
|
+
|
|
9
|
+
**Documentation only. No code changes, no API changes.** Corrects two errors in
|
|
10
|
+
the 3.2.2 Steam snippets that made them fail if copied.
|
|
11
|
+
|
|
12
|
+
- **Base path.** The snippets said `/api/enhanced-purchase/...`. The routes are
|
|
13
|
+
mounted at **`/api/currency-purchases/...`** -- `enhanced_purchase_api` is the
|
|
14
|
+
module name, not the mount point. Copying 3.2.2 returned `404 Resource not
|
|
15
|
+
found`, which reads like the Steam rail is unavailable rather than like a
|
|
16
|
+
wrong URL.
|
|
17
|
+
- **Auth header.** The snippets sent `X-Game-Secret`. The header is
|
|
18
|
+
**`X-Game-Secret-Key`**, as it is everywhere else in this document. An unknown
|
|
19
|
+
header is ignored, so the request arrived unauthenticated.
|
|
20
|
+
|
|
21
|
+
Both were confined to the Steam section added in 3.2.2; every other snippet was
|
|
22
|
+
correct. The Steam flow itself is unchanged -- pack catalogue, `pack_id`,
|
|
23
|
+
VAT-aware amounts, all exactly as 3.2.2 describes.
|
|
24
|
+
|
|
25
|
+
The paths and header are now pinned by a test against this file, because the
|
|
26
|
+
Steam section is the one snippet with no SDK method behind it and so was the one
|
|
27
|
+
thing no test could see.
|
|
28
|
+
|
|
29
|
+
## [3.2.2] - 2026-08-28
|
|
30
|
+
|
|
31
|
+
**Documentation only. No code changes, no API changes.**
|
|
32
|
+
|
|
33
|
+
Steam currency purchases now work on a **pack model**, and this documents it. The
|
|
34
|
+
3.2.1 notes described an earlier design that has been replaced -- read this
|
|
35
|
+
instead.
|
|
36
|
+
|
|
37
|
+
- **INVO owns the Steam pack catalogue.** You do not set prices and you never
|
|
38
|
+
send an amount. Fetch `GET /steam/packs?steamid=...`, render it, and pass a
|
|
39
|
+
`pack_id` to `/steam/init-purchase`. An amount is refused with
|
|
40
|
+
`400 UNKNOWN_STEAM_PACK`.
|
|
41
|
+
- **The price is identical everywhere; the currency inside is not.** Steam prices
|
|
42
|
+
are VAT-inclusive wherever VAT is collected, so more of a fixed price goes to
|
|
43
|
+
tax in a high-VAT country -- the same $9.99 pack yields 69 units in the US and
|
|
44
|
+
58 in France.
|
|
45
|
+
- **Always pass `steamid`** when fetching the catalogue. Without it amounts are
|
|
46
|
+
quoted with no VAT deducted, so a store promises more than the purchase
|
|
47
|
+
delivers. Do not cache one catalogue for all players.
|
|
48
|
+
- A Steam-distributed title may only sell currency on the `steam` rail
|
|
49
|
+
(`409 STEAM_PURCHASE_LAYER_REQUIRED`), and a locked Steam account is refused up
|
|
50
|
+
front (`409 STEAM_ACCOUNT_LOCKED`).
|
|
51
|
+
|
|
52
|
+
Steam remains a server-to-server REST flow rather than an SDK method, because the
|
|
53
|
+
purchase is authorised inside the Steam client and your game relays that.
|
|
54
|
+
|
|
7
55
|
## [3.2.1] - 2026-08-28
|
|
8
56
|
|
|
9
57
|
**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.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).
|
|
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
|
|
@@ -300,22 +300,78 @@ 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: currency must be bought through Steam, and
|
|
303
|
+
> **Steam titles: currency must be bought through Steam, and INVO sets the packs.**
|
|
304
304
|
>
|
|
305
305
|
> A title distributed on Steam may only sell currency on the `steam` rail — any other
|
|
306
306
|
> rail is refused with `409 STEAM_PURCHASE_LAYER_REQUIRED`. This is a platform
|
|
307
307
|
> requirement, not an INVO preference, and it applies to every storefront the title
|
|
308
308
|
> ships on because a player's balance is shared across them.
|
|
309
309
|
>
|
|
310
|
-
>
|
|
311
|
-
>
|
|
312
|
-
>
|
|
313
|
-
>
|
|
314
|
-
>
|
|
315
|
-
>
|
|
310
|
+
> **You do not set Steam prices and you do not send an amount.** INVO defines the pack
|
|
311
|
+
> catalogue for every game on the network. Fetch it with `GET /steam/packs?steamid=...`,
|
|
312
|
+
> render it, and pass the `pack_id` back to the purchase call.
|
|
313
|
+
>
|
|
314
|
+
> **The price is the same everywhere; the currency inside is not.** Steam prices are
|
|
315
|
+
> VAT-inclusive wherever VAT is collected, so more of a fixed price goes to tax in a
|
|
316
|
+
> high-VAT country and less is left to buy currency with — the same $9.99 pack yields
|
|
317
|
+
> 69 units in the US and 58 in France. Always pass `steamid` when fetching the
|
|
318
|
+
> catalogue, or the amounts are quoted with no VAT deducted and your store promises
|
|
319
|
+
> more than the purchase delivers. Do not cache one catalogue for all players and do
|
|
320
|
+
> not hard-code amounts: pack prices and VAT rates are both configuration.
|
|
316
321
|
|
|
317
322
|
Provider/processor names are an internal detail and never appear in the API.
|
|
318
323
|
|
|
324
|
+
### Steam purchases (packs, not prices)
|
|
325
|
+
|
|
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.
|
|
329
|
+
|
|
330
|
+
**INVO owns the pack catalogue.** You never send a price. Fetch the packs, show them,
|
|
331
|
+
pass a `pack_id` back.
|
|
332
|
+
|
|
333
|
+
```ts
|
|
334
|
+
// 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 }, ...]
|
|
341
|
+
|
|
342
|
+
// 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
|
+
}),
|
|
352
|
+
});
|
|
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.
|
|
358
|
+
```
|
|
359
|
+
|
|
360
|
+
**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.
|
|
364
|
+
|
|
365
|
+
- **Always pass `steamid`** to `/steam/packs`. Without it the amounts are quoted with
|
|
366
|
+
no VAT deducted — the most any pack yields — so your store promises more than the
|
|
367
|
+
purchase delivers.
|
|
368
|
+
- **Do not cache one catalogue for all players**, and do not hard-code amounts. Pack
|
|
369
|
+
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`.
|
|
374
|
+
|
|
319
375
|
### Direct rail (advanced — you tokenize the card yourself)
|
|
320
376
|
|
|
321
377
|
```ts
|
package/package.json
CHANGED