@invonetwork/web-sdk 3.2.2 → 3.3.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.
Files changed (3) hide show
  1. package/CHANGELOG.md +51 -0
  2. package/README.md +64 -5
  3. package/package.json +1 -1
package/CHANGELOG.md CHANGED
@@ -4,6 +4,57 @@ 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.3.0] - 2026-08-31
8
+
9
+ **Documentation only. No code changes, no API changes.**
10
+
11
+ Documents **Device Approval** — passkey step-up for consoles, TVs and any device
12
+ with no browser. It is the OAuth 2.0 Device Authorization Grant
13
+ ([RFC 8628](https://datatracker.ietf.org/doc/html/rfc8628)), so a standard
14
+ client library understands the responses.
15
+
16
+ - The device shows a short code and a QR (`verification_uri_complete`); the
17
+ player approves on their phone; your **server** polls
18
+ `POST /api/sdk/approvals/device/poll` until it hears back.
19
+ - **One approval authorises one transaction.** Unlike the plain RFC 8628 grant,
20
+ which authorises a *client*, an INVO device code is bound to the transaction
21
+ you named and is consumed when used — it cannot approve anything else and
22
+ cannot be reused.
23
+ - `user_code` is meant to be seen; `device_code` is not. Poll from your backend.
24
+ - Subscribe to `device_approval.approved` to learn the moment an approval lands
25
+ instead of waiting for the next poll. Polling still works alone.
26
+ - Available to every title with nothing to configure — the constraint is a
27
+ property of the *device*, not the game, so a title with a website and a
28
+ console build uses the normal ceremony in the browser and this one on console.
29
+ - Currency purchases on a console go through that console's store, as the
30
+ platform holder requires; this flow is for approving transfers and sends.
31
+
32
+ Minor rather than patch because it documents a new API surface. The snippets are
33
+ pinned by a test against this file, for the same reason the Steam ones are: a
34
+ REST flow with no SDK method behind it is the one thing no other test can see.
35
+
36
+ ## [3.2.3] - 2026-08-28
37
+
38
+ **Documentation only. No code changes, no API changes.** Corrects two errors in
39
+ the 3.2.2 Steam snippets that made them fail if copied.
40
+
41
+ - **Base path.** The snippets said `/api/enhanced-purchase/...`. The routes are
42
+ mounted at **`/api/currency-purchases/...`** -- `enhanced_purchase_api` is the
43
+ module name, not the mount point. Copying 3.2.2 returned `404 Resource not
44
+ found`, which reads like the Steam rail is unavailable rather than like a
45
+ wrong URL.
46
+ - **Auth header.** The snippets sent `X-Game-Secret`. The header is
47
+ **`X-Game-Secret-Key`**, as it is everywhere else in this document. An unknown
48
+ header is ignored, so the request arrived unauthenticated.
49
+
50
+ Both were confined to the Steam section added in 3.2.2; every other snippet was
51
+ correct. The Steam flow itself is unchanged -- pack catalogue, `pack_id`,
52
+ VAT-aware amounts, all exactly as 3.2.2 describes.
53
+
54
+ The paths and header are now pinned by a test against this file, because the
55
+ Steam section is the one snippet with no SDK method behind it and so was the one
56
+ thing no test could see.
57
+
7
58
  ## [3.2.2] - 2026-08-28
8
59
 
9
60
  **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
@@ -333,16 +333,16 @@ pass a `pack_id` back.
333
333
  ```ts
334
334
  // 1. The catalogue, priced for THIS player. Always pass steamid.
335
335
  const res = await fetch(
336
- `${INVO_BASE}/api/enhanced-purchase/steam/packs?steamid=${steamId}`,
337
- { headers: { "X-Game-Secret": GAME_SECRET } },
336
+ `${INVO_BASE}/api/currency-purchases/steam/packs?steamid=${steamId}`,
337
+ { headers: { "X-Game-Secret-Key": GAME_SECRET } },
338
338
  );
339
339
  const { country, vat_rate_pct, packs } = await res.json();
340
340
  // packs: [{ pack_id, label, price_usd, currency_amount }, ...]
341
341
 
342
342
  // 2. Start the purchase with the pack the player chose.
343
- const init = await fetch(`${INVO_BASE}/api/enhanced-purchase/steam/init-purchase`, {
343
+ const init = await fetch(`${INVO_BASE}/api/currency-purchases/steam/init-purchase`, {
344
344
  method: "POST",
345
- headers: { "X-Game-Secret": GAME_SECRET, "Content-Type": "application/json" },
345
+ headers: { "X-Game-Secret-Key": GAME_SECRET, "Content-Type": "application/json" },
346
346
  body: JSON.stringify({
347
347
  player_email: "player@example.com",
348
348
  steamid: steamId,
@@ -679,6 +679,65 @@ try {
679
679
  - Challenges are single-use and bound to `{flow}:{transactionId}`.
680
680
  - The SDK passes the backend's WebAuthn options through unchanged (it does not hard-code `pubKeyCredParams`/`timeout`/`attestation`).
681
681
 
682
+ ### Consoles and TVs — approving without a browser (RFC 8628)
683
+
684
+ A console has no browser, so it cannot run a passkey ceremony at all. **Device
685
+ Approval** moves the ceremony to a device that can: your game shows a short code, the
686
+ player approves on their phone, your server polls until it hears back. It is the
687
+ [OAuth 2.0 Device Authorization Grant, RFC 8628](https://datatracker.ietf.org/doc/html/rfc8628)
688
+ — the same flow every console and TV app uses — so a standard client library understands
689
+ the responses.
690
+
691
+ **Not an SDK method** — it is a server-to-server REST flow, because the polling has to
692
+ happen on your backend, not in the game client.
693
+
694
+ **Available to every title, with nothing to configure.** The constraint is a property of
695
+ the *device*, not your game: a title with a website *and* a console build uses the normal
696
+ ceremony in the browser and this one on the console.
697
+
698
+ ```ts
699
+ // 1. Your server starts an approval for ONE transaction.
700
+ // flow: "transfer" | "send" | "send_receipt" | "transfer_receipt"
701
+ const start = await fetch(`${INVO_BASE}/api/sdk/approvals/device/begin`, {
702
+ method: "POST",
703
+ headers: { Authorization: `Bearer ${sdkSessionToken}`, "Content-Type": "application/json" },
704
+ body: JSON.stringify({ transaction_id: transferId, flow: "transfer" }),
705
+ }).then((r) => r.json());
706
+ // -> { device_code, user_code, verification_uri, verification_uri_complete,
707
+ // expires_in, interval }
708
+
709
+ // 2. The game renders `verification_uri_complete` as a QR and prints `user_code`
710
+ // under it. The QR already contains the code, so most players never type.
711
+
712
+ // 3. Poll from your SERVER, never faster than `interval` seconds.
713
+ const poll = await fetch(`${INVO_BASE}/api/sdk/approvals/device/poll`, {
714
+ method: "POST",
715
+ headers: { Authorization: `Bearer ${sdkSessionToken}`, "Content-Type": "application/json" },
716
+ body: JSON.stringify({ device_code: start.device_code }),
717
+ }).then((r) => r.json());
718
+ // approved -> { status: "approved", transaction_id, flow }
719
+ // authorization_pending -> keep polling
720
+ // slow_down -> back off, then resume
721
+ // expired_token -> start a new approval
722
+ // access_denied -> the player declined; do not retry silently
723
+ // invalid_grant -> unknown or not yours
724
+ ```
725
+
726
+ - **One approval authorises one transaction.** Unlike the plain RFC 8628 grant, which
727
+ authorises a *client*, an INVO device code is bound to the transaction you named and is
728
+ consumed when used. It cannot approve anything else and cannot be reused.
729
+ - **`user_code` is meant to be seen; `device_code` is not.** Poll from your backend.
730
+ - **One live code per transaction.** Starting a second returns
731
+ `409 DEVICE_APPROVAL_ALREADY_PENDING` — reuse the one you have or let it expire.
732
+ - **Subscribe to `device_approval.approved`** to learn the moment an approval lands
733
+ instead of waiting for the next poll. Polling still works alone; the webhook is a
734
+ latency improvement, not a replacement.
735
+ - **The player needs an INVO passkey.** A passkey they set up on *your* domain is a
736
+ different credential and cannot be used here — that is how passkeys work. The approval
737
+ page says so plainly when they need to set one up.
738
+ - **Currency purchases on a console go through that console's store**, as the platform
739
+ holder requires. This flow is for approving transfers and sends.
740
+
682
741
  ---
683
742
 
684
743
  ## Webhooks
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@invonetwork/web-sdk",
3
- "version": "3.2.2",
3
+ "version": "3.3.0",
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,