@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.
- package/CHANGELOG.md +51 -0
- package/README.md +64 -5
- 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.
|
|
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/
|
|
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/
|
|
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