@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.
Files changed (3) hide show
  1. package/CHANGELOG.md +48 -0
  2. package/README.md +64 -8
  3. 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.1.0` — stable, published on npm. The backend it wraps is **live** on sandbox + production. The API is covered by a [stability commitment](#stability): no breaking changes without a major bump. Recent highlights: **3.1.0** makes the authentication guidance explicit — **[passkeys are the gold standard](#passkeys-are-the-gold-standard-dont-build-on-sms)** and the SMS-PIN completion (`verifySmsTransfer`/`verifySmsSend`) is **deprecated and being phased out** (documentation only — no behavior change, no runtime warnings); **3.0.0** moves the Platform Commerce card leg to **INVO's hosted checkout** — the server `purchase()` now returns a `checkoutUrl` and the browser just sends the buyer there (redirect or `mountCheckout` iframe); the 2.5.x card-element surface (`confirmCardPayment`/`mountCardPayment`, `billingAddress`, `commercePublishableKey`) is **removed** — see the [CHANGELOG](CHANGELOG.md) migration note; **2.5.0** added **Platform Commerce** (ecommerce) — a platform tenant selling items funded by balance **or** card, with `invo.platformCommerce.purchase/getStatus/refund` (server) and the `platform_commerce.*` webhooks; **2.4.0** adds Steam transfer-policy handling (`isSteamValueNonTransferable`/`isNonSteamValueIntoSteamBlocked` + `DestinationGame.acceptsSteamOriginValue`); **2.3.0** surfaces the claim-time phone-share `409` on `confirmReceipt*`/`claim*` (+ `err.phoneShareLast4`). Full history in the [CHANGELOG](CHANGELOG.md).
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 the player pays more.**
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
- > Steam's platform commission is **priced into the charge, not absorbed**. You send the
311
- > **value** the player should receive; the response tells you what Steam will actually
312
- > bill. Show `charged_usd` in your store, never the value you sent. The amount of
313
- > currency the player receives is unchanged, so a pack is worth the same in-game on
314
- > every rail. The rate is configuration — read `charged_usd` from the response rather
315
- > than hard-coding a multiplier.
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
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@invonetwork/web-sdk",
3
- "version": "3.2.1",
3
+ "version": "3.2.3",
4
4
  "description": "INVO Web SDK — currency purchase + passkey (WebAuthn) verification for partner web platforms.",
5
5
  "license": "SEE LICENSE IN LICENSE",
6
6
  "private": false,