@invonetwork/web-sdk 3.2.1 → 3.2.2

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 +26 -0
  2. package/README.md +63 -7
  3. package/package.json +1 -1
package/CHANGELOG.md CHANGED
@@ -4,6 +4,32 @@ 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.2] - 2026-08-28
8
+
9
+ **Documentation only. No code changes, no API changes.**
10
+
11
+ Steam currency purchases now work on a **pack model**, and this documents it. The
12
+ 3.2.1 notes described an earlier design that has been replaced -- read this
13
+ instead.
14
+
15
+ - **INVO owns the Steam pack catalogue.** You do not set prices and you never
16
+ send an amount. Fetch `GET /steam/packs?steamid=...`, render it, and pass a
17
+ `pack_id` to `/steam/init-purchase`. An amount is refused with
18
+ `400 UNKNOWN_STEAM_PACK`.
19
+ - **The price is identical everywhere; the currency inside is not.** Steam prices
20
+ are VAT-inclusive wherever VAT is collected, so more of a fixed price goes to
21
+ tax in a high-VAT country -- the same $9.99 pack yields 69 units in the US and
22
+ 58 in France.
23
+ - **Always pass `steamid`** when fetching the catalogue. Without it amounts are
24
+ quoted with no VAT deducted, so a store promises more than the purchase
25
+ delivers. Do not cache one catalogue for all players.
26
+ - A Steam-distributed title may only sell currency on the `steam` rail
27
+ (`409 STEAM_PURCHASE_LAYER_REQUIRED`), and a locked Steam account is refused up
28
+ front (`409 STEAM_ACCOUNT_LOCKED`).
29
+
30
+ Steam remains a server-to-server REST flow rather than an SDK method, because the
31
+ purchase is authorised inside the Steam client and your game relays that.
32
+
7
33
  ## [3.2.1] - 2026-08-28
8
34
 
9
35
  **Documentation only. No code changes, no API changes.**
package/README.md CHANGED
@@ -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/enhanced-purchase/steam/packs?steamid=${steamId}`,
337
+ { headers: { "X-Game-Secret": 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/enhanced-purchase/steam/init-purchase`, {
344
+ method: "POST",
345
+ headers: { "X-Game-Secret": 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.2",
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,