@invonetwork/web-sdk 3.5.0 → 3.7.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/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.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.4.0** documents that a Steam title now bills through **its own Steam application** — the studio registers their appid + publisher Web API key and keeps a payment method on file, because Valve pays the studio and INVO settles afterwards (new `isSteamNotConfigured`, `isPartnerBillingNotSetUp`, `isPartnerSettlementUnavailable`, `isSteamAppChanged` error helpers); **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).
5
+ > **Status:** `v3.7.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.7.0** makes the **device approval grant a first-class SDK surface** — `beginDeviceApproval`, `pollDeviceApproval`, `confirmDeviceEnrollment` and, the step that actually moves the money, **`approveWithDeviceCode`** (plus the optional `completeDeviceApproval` loop); a grant that is polled to `approved` and left there settles **nothing**, which is the failure this release exists to make impossible, and `TRANSACTION_NOT_PENDING` now comes back as a typed `status: "not_pending"` result with `alreadySettled` rather than a thrown error you would have to string-match; **3.4.0** documents that a Steam title now bills through **its own Steam application** — the studio registers their appid + publisher Web API key and keeps a payment method on file, because Valve pays the studio and INVO settles afterwards (new `isSteamNotConfigured`, `isPartnerBillingNotSetUp`, `isPartnerSettlementUnavailable`, `isSteamAppChanged` error helpers); **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
@@ -35,31 +35,33 @@ So:
35
35
  |---|---|---|
36
36
  | Sender approves a send/transfer | `client.enrollPasskey()` once, then `client.approveSend` / `approveTransfer` | a PIN pad as the default flow |
37
37
  | `initiate*` returns `verificationMethod: "sms"` | read it as *"this user has no passkey"* → offer enrollment | route straight to PIN entry |
38
- | Recipient collects | `client.confirmReceiptSend` / `confirmReceiptTransfer` (passkey) | claim code as the primary path |
38
+ | Recipient collects | `client.confirmReceiptSend` / `confirmReceiptTransfer` (passkey), or the QR flow with `flow: "send_receipt"` / `"transfer_receipt"` | claim code as the primary path |
39
+ | Console / TV / native client | the QR device-approval grant, **then `server.approveWithDeviceCode`** | polling to `approved` and stopping — that settles nothing |
39
40
 
40
- ### Prerequisite: passkeys are dark until your tenant verifies a domain
41
+ ### Prerequisite: which passkey path serves your tenant
41
42
 
42
- **Read this before you wire up `enrollPasskey()`.** Passkey step-up is enabled **per tenant** and stays off until you verify ownership of a domain (your RP ID) in the developer console. Until then every passkey endpoint returns `403 WEBAUTHN_NOT_ENABLED_FOR_TENANT`.
43
+ **Read this before you wire up `enrollPasskey()`.** There are two places a passkey ceremony can run, and which one serves your title is decided by whether you hold a partner passkey domain:
43
44
 
44
- **This is the common case today, not an edge case.** As of 2026-08-05 only **4 of 23 sandbox tenants** and **0 of 3 production tenants** have a verified RP ID. If you skip this, your integration will 403 on its first `enrollPasskey()` call and you'll be debugging a configuration state as if it were a bug.
45
+ - **No partner domain (every new title):** INVO runs the ceremony **on its own domain** — the hosted approval page — for every platform. There is **no domain to verify and nothing to configure**; submitting one is refused (`409 PARTNER_RP_FROZEN`). On the web the path is [`approveHosted()`](#web-games--approving-on-invos-hosted-page); on consoles it is the QR flow; on iOS/Android the mobile plugins open the same page. The in-app `enrollPasskey()` / `approveSend` / `approveTransfer` calls return `403 WEBAUTHN_NOT_ENABLED_FOR_TENANT` for you — that is the **expected state, not a setup gap** (the body's `hosted_flow` says so and points at `device_code`).
46
+ - **A domain verified before the freeze (existing tenants):** your passkeys are bound to that RP ID for life, so `enrollPasskey()` and the in-app approves keep working exactly as documented below. You may still change or re-verify the domain. Removing it is **irreversible** — it can never be re-added, and the hosted flow serves the game from then on.
45
47
 
46
- `WEBAUTHN_NOT_ENABLED_FOR_TENANT` is **configuration state, not an error** — the ceremony was never available to fail. Don't show the player a failure; fall back to the existing path:
48
+ `WEBAUTHN_NOT_ENABLED_FOR_TENANT` is **configuration state, not an error** — the in-app ceremony was never available to fail. Don't show the player a failure; use the hosted page:
47
49
 
48
50
  ```ts
49
51
  try {
50
52
  await client.enrollPasskey();
51
53
  } catch (e) {
52
54
  if (e instanceof InvoError && e.isWebauthnNotEnabledForTenant) {
53
- // Not a failure — this tenant simply hasn't verified a domain yet.
54
- // Fall back to the SMS/in-app path and (if this is YOUR tenant) go verify a domain.
55
- usePinFallback();
55
+ // Not a failure — this tenant has no partner passkey domain, which is now the norm.
56
+ // Approve on INVO's hosted page instead (nothing to configure):
57
+ await client.approveHosted({ transactionId, flow: "transfer" });
56
58
  } else throw e;
57
59
  }
58
60
  ```
59
61
 
60
- So the honest sequence is: **verify your domain → enroll passkeys → you're on the gold-standard path.** Until step one is done, the SMS path is carrying you whether you like it or not — which is exactly why the deprecation below has no removal date attached.
62
+ So the honest sequence is: **start the transfer → `approveHosted()` (or the in-app approve if you hold a domain) → you're on the gold-standard path.** The SMS PIN is what carries a player who cannot or will not enrol — which is exactly why the deprecation below has no removal date attached.
61
63
 
62
- > ⚠️ **`verifySmsTransfer` / `verifySmsSend` are deprecated as of `3.1.0` and a future major version will remove them.** They still work exactly as before — this release changes documentation only, emits no runtime warning, and breaks nothing. Keep the PIN path as a genuine last resort for: users who **cannot** enroll (unsupported device, no platform authenticator), users who decline, and **tenants that haven't verified a domain yet** (see above). Just don't make it the road everyone walks down once passkeys are available to you.
64
+ > ⚠️ **`verifySmsTransfer` / `verifySmsSend` are deprecated as of `3.1.0` and a future major version will remove them.** They still work exactly as before — this release changes documentation only, emits no runtime warning, and breaks nothing. Keep the PIN path as a genuine last resort for: users who **cannot** enroll (unsupported device, no platform authenticator), users who decline, and **players who will not use the hosted page** (see above). Just don't make it the road everyone walks down once passkeys are available to you.
63
65
 
64
66
  **What is *not* discouraged.** These use a one-time code, but they are the on-ramp *to* a passkey — not a substitute for one. Use them freely:
65
67
 
@@ -69,6 +71,20 @@ So the honest sequence is: **verify your domain → enroll passkeys → you're o
69
71
 
70
72
  Beyond security, this is also an economics story: SMS costs real money per message at every scale, and INVO's architecture targets passkey/in-app verification as the primary path so the platform never depends on carrier delivery. A passkey-first integration is faster for your users, cheaper to run, and won't need migrating later.
71
73
 
74
+ ### Which method fits which platform
75
+
76
+ The right approval method is a property of the **client the player is sitting in front of**, not of your title. Pick it per platform:
77
+
78
+ | Where the player is | Approve with | Why |
79
+ |---|---|---|
80
+ | Mobile app & mobile web (iOS 16+ / Android 9+) | **a passkey, directly** | the platform authenticator (Face ID / Touch ID / fingerprint) is available in-client — strongest option, zero messaging cost |
81
+ | Desktop web (browser) | **a passkey, directly** | Touch ID / Windows Hello are available to the browser |
82
+ | Web, player has no in-app passkey yet | **INVO's hosted page in a popup** ([`approveHosted`](#web-games--approving-on-invos-hosted-page), below) | the same page a console scans, opened by the SDK from the browser; the player enrols an INVO passkey on INVO's own domain and the SDK polls and approves — one call, nothing new on your server |
83
+ | Consoles (PlayStation / Xbox / Switch) | **the QR device-approval flow** ([RFC 8628](#consoles-and-tvs--approving-without-a-browser-rfc-8628), below) | no browser and no WebAuthn in-client — show the QR, the player scans it and completes the passkey on their phone, your server polls, and **your server then calls `approveWithDeviceCode`** — the poll proves who, that call moves the money |
84
+ | Native Steam / desktop game clients (Mac & Windows) | **the QR device-approval flow** ([RFC 8628](#consoles-and-tvs--approving-without-a-browser-rfc-8628), below) | the OS supports passkeys, but the embedded game client can't invoke the platform authenticator from inside the engine — it is the **client**, not the OS, that forces QR here |
85
+
86
+ **When there is no passkey path at all** — a remote approval that can't run a ceremony (a guardian, a phone's existing owner) — INVO goes **email first, SMS on request**: a signed link to a hosted page to the oldest verified address, and a text only when there is no verified email, the email could not be delivered, or the player asks for one. SMS is the last resort, not the primary channel.
87
+
72
88
  ## Contents
73
89
 
74
90
  - [Passkeys are the gold standard — don't build on SMS](#passkeys-are-the-gold-standard--dont-build-on-sms)
@@ -81,7 +97,14 @@ Beyond security, this is also an economics story: SMS costs real money per messa
81
97
  - [Platform Commerce (ecommerce)](#platform-commerce-ecommerce)
82
98
  - [Player balance](#player-balance)
83
99
  - [Sends & transfers (move currency between players)](#sends--transfers-move-currency-between-players)
100
+ - [Legacy fallback: the SMS PIN (being retired)](#legacy-fallback-the-sms-pin-being-retired)
101
+ - [Sends and transfers, stage by stage](#sends-and-transfers-stage-by-stage)
102
+ - [What your server must call, in order](#what-your-server-must-call-in-order)
103
+ - [Errors on the money path](#errors-on-the-money-path)
104
+ - [Common mistakes](#common-mistakes)
84
105
  - [Passkeys (enroll, approve, link, recover)](#passkeys-enroll-approve-link-recover)
106
+ - [Web games — approving on INVO's hosted page](#web-games--approving-on-invos-hosted-page)
107
+ - [Consoles and TVs — approving without a browser (RFC 8628)](#consoles-and-tvs--approving-without-a-browser-rfc-8628)
85
108
  - [Webhooks](#webhooks)
86
109
  - [Resilience & observability](#resilience--observability)
87
110
  - [Errors](#errors)
@@ -209,7 +232,7 @@ INVO enables each flow for your tenant in the [console](#get-your-account--game-
209
232
  - **Store the game secret server-side** and expose a small endpoint that calls `mintPlayerToken` so the browser can fetch/refresh its token. Never ship the secret to the browser.
210
233
  - **Make sure players have a phone (E.164) at creation/enrollment** — it's required on the money calls (`initiateSend`/`initiateTransfer`) and for cross-game receive, though not on the token mint itself (see [Player token](#player-token-session-mint-for-an-existing-player)).
211
234
  - **If you use browser-direct ([Mode A](#mode-a--browser-direct-default)):** ask INVO to **CORS-allow your web origin(s)** so the browser can call the API directly. (Not needed for [Mode B / proxy](#mode-b--behind-your-proxy-keep-the-token-server-side) — those requests are same-origin to your backend.)
212
- - **For passkeys (sends/transfers):** give INVO the **RP ID + web origin(s)** you'll serve from. Passkeys only validate on approved origins — if a call returns `WEBAUTHN_NOT_ENABLED_FOR_TENANT`, your origins aren't set up yet; contact INVO. **Get this configured before launch:** until a sender is enrolled the backend falls back to the deprecated SMS-PIN path, which is the flow you don't want your users on (see [Passkeys are the gold standard](#passkeys-are-the-gold-standard--dont-build-on-sms)).
235
+ - **For passkeys (sends/transfers):** nothing to configure — new titles approve on INVO's hosted page ([`approveHosted()`](#web-games--approving-on-invos-hosted-page)); there is no partner domain to verify. Only a tenant that verified an **RP ID + web origin(s)** before the freeze uses the in-app `enrollPasskey()` / `approveSend` path, and those passkeys only validate on the approved origins. **Wire the approve step before launch:** until a sender is enrolled the backend falls back to the deprecated SMS-PIN path, which is the flow you don't want your users on (see [Passkeys are the gold standard](#passkeys-are-the-gold-standard--dont-build-on-sms)).
213
236
  - **For currency purchase:** card checkout works out of the box; ask INVO to enable the `game`/`steam` rails if you need them. **The `steam` rail additionally requires the studio to register their own Steam app id + publisher Web API key and put a payment method on file** — see [Steam purchases](#steam-purchases-packs-not-prices).
214
237
  - **For item purchase:** nothing extra — it's a currency-balance debit.
215
238
 
@@ -592,7 +615,16 @@ comes from the token, no PII).
592
615
 
593
616
  ## Sends & transfers (move currency between players)
594
617
 
595
- Move already-owned game currency from one player to another, authorized by the **sender's passkey** — the [gold standard](#passkeys-are-the-gold-standard--dont-build-on-sms). (A deprecated SMS-PIN fallback exists for senders who aren't enrolled; treat it as a last resort, not a design.) **Send** and **transfer** are parallel flows:
618
+ Move already-owned game currency from one player to another, authorized by the **sender's passkey** — the [gold standard](#passkeys-are-the-gold-standard--dont-build-on-sms).
619
+
620
+ **There are exactly two approval paths, and both are passkeys:**
621
+
622
+ - **In-app passkey** — wherever WebAuthn can run in the client: a browser, or a web game on INVO's [hosted approval page](#web-games--approving-on-invos-hosted-page). `approveSend` / `approveTransfer` / `approveHosted`.
623
+ - **Device approval (QR)** — wherever it cannot: consoles, TVs, native Steam and desktop clients. The player approves on their phone; **your server then makes the call that moves the money**. See [Consoles and TVs](#consoles-and-tvs--approving-without-a-browser-rfc-8628) and [Sends and transfers, stage by stage](#sends-and-transfers-stage-by-stage).
624
+
625
+ A legacy SMS-PIN fallback still exists for a sender who cannot use either — it is [being retired](#legacy-fallback-the-sms-pin-being-retired) and new integrations should not build on it.
626
+
627
+ **Send** and **transfer** are parallel flows:
596
628
 
597
629
  | | Send | Transfer |
598
630
  |---|---|---|
@@ -627,14 +659,17 @@ const t = await server.initiateTransfer({
627
659
 
628
660
  // Check guardianApproval FIRST — the guardian path takes precedence.
629
661
  switch (true) {
630
- case !!t.guardianApproval: // minor/guardian path (HTTP 202) → pending approval, no PIN UI
631
- case t.verificationMethod === "in_app": // sender HAS a passkey → approve in the browser. The good path.
632
- case t.verificationMethod === "sms": // sender has NO passkey → offer enrollPasskey() and approve;
633
- // show the PIN pad only if they can't or won't enroll.
662
+ case !!t.guardianApproval: // minor/guardian path (HTTP 202) → a guardian is emailed a
663
+ // signed approve/decline link; poll, show no approval UI.
664
+ case t.verificationMethod === "in_app": // sender HAS a passkey → approve in the client. The good path.
665
+ default: // sender has NO passkey yet → enrol one (enrollPasskey() or
666
+ // approveHosted()), or run the QR flow on a console.
634
667
  }
635
668
 
636
669
  // 2. BROWSER — the sender approves with their passkey (give them t.transactionId + the player token)
637
670
  const approved = await client.approveTransfer(t.transactionId); // or approveSend(...)
671
+ // On a console / TV / native client there is no browser: run the device approval grant
672
+ // instead — begin → show QR → poll → approveWithDeviceCode. See "stage by stage".
638
673
  // approved.claimCode + approved.claimCodeExpiresAt (transfer only) — deliver if the recipient can't self-claim
639
674
 
640
675
  // 3. BROWSER — the recipient claims with their passkey; fall back to the claim code if not enrolled
@@ -651,14 +686,57 @@ try {
651
686
  }
652
687
  ```
653
688
 
654
- - **`verificationMethod`** (from initiate): `"in_app"` → the sender has a passkey, go approve (the recommended path); `"sms"` → **the sender has no passkey** and a PIN was sent as a deprecated fallback — the best response is to offer `enrollPasskey()` and then `approveSend`/`approveTransfer`, showing the PIN pad only if they can't or won't enroll; `undefined` + `guardianApproval` → minor/guardian (HTTP 202), do **not** show the PIN UI. On the guardian path the SDK reports `verificationMethod: undefined` (even though the raw 202 body also carries `"sms"`) so `guardianApproval` wins — but branch on it first to be safe.
689
+ - **`verificationMethod`** (from initiate): `"in_app"` → the sender has a passkey, go approve — the path you want. `"sms"` → read it as **"this sender has no passkey yet"**: offer enrollment (`enrollPasskey()`, or `approveHosted()` where you hold no verified domain), or run the [device approval grant](#consoles-and-tvs--approving-without-a-browser-rfc-8628) on a console. `undefined` + `guardianApproval` → minor/guardian (HTTP 202), show no approval UI. On the guardian path the SDK reports `verificationMethod: undefined` (even though the raw 202 body also carries `"sms"`) so `guardianApproval` wins — but branch on it first to be safe.
655
690
  - **Claim codes** are returned only by `approveTransfer`; they're the out-of-band fallback when the recipient isn't enrolled.
656
691
  - **`err.isReceiverNotEnrolled`** on `confirmReceipt*` is the explicit signal to switch to claim-code entry.
692
+ - **The one message that is still a text: the claim link to a phone-only recipient.** A
693
+ send can be addressed to someone INVO has never met — the sender knows their phone number
694
+ and nothing else, so there is no email to write to and no session to notify. That is the
695
+ only remaining place INVO sends an SMS by default; everything else that needs a human
696
+ (guardian consent, enrolment backup, phone-share) goes by **email first**. The claim text a send's receiver gets
697
+ now ends with a link to a hosted INVO page ("Or collect here: …"). They see who sent what in
698
+ which game, enter **one email** (the same thing in-game claim already requires), confirm it
699
+ with an emailed 6-digit code, and their phone's fingerprint / face / screen lock creates an
700
+ INVO passkey — a recipient who already has one just confirms with it. The currency lands in
701
+ their balance for the receiving game; the page shows the new balance and tells them to sign
702
+ in to the game with that email + phone. In-game claim (`claimCurrency` / `confirmReceiptSend`)
703
+ is unchanged — point a player at the link when they don't have the game open, at in-game
704
+ claim when they do; both are the same claim with one lifetime. `transfer.received` fires
705
+ the same either way, and you change nothing.
706
+ - **Resend the claim SMS — a REST call, not an SDK method.**
707
+ `POST /api/sdk/send/{transactionId}/resend-claim` with the **sender's** player token, no
708
+ body. It re-sends the identical message (same code, same link); nothing new is minted.
709
+ 30-second cooldown (`429 RESEND_COOLDOWN` + `retry_after`), at most 10 per transaction per
710
+ hour; `400 CLAIM_EXPIRED` / `NOT_CLAIMABLE` once the send can no longer be claimed; `403`
711
+ for anyone but the sender. `200 { status: "resent", transaction_id, retry_after }`.
712
+ - **Uncollected after 24 hours → refunded, and both parties are told.** The refund to the
713
+ sender is as before; what's new is that the sender gets an email and the recipient a single
714
+ text saying the currency was returned, instead of silence. `transfer.claim_expired` +
715
+ `transfer.refunded` remain the source of truth — reconcile off those, not the messages.
657
716
  - **`err.isPhoneShareApprovalRequired` on `confirmReceipt*` / `claimTransfer` / `claimCurrency`** (409): the receiver phone is contested, so INVO **holds the money** and texts the phone owner to approve. Not a failure — show `err.message` verbatim (`err.phoneShareLast4` names the phone), then **retry the same call** once approved (it succeeds idempotently); on denial/expiry the sender is refunded. Same handling as the initiate-time phone-share 409.
658
717
  - **Both games must be Live.** `initiateSend`/`initiateTransfer` throw `403` if either side is still in testing, and the two cases are **deliberately separate** because the fix differs: `err.isSourceGameNotLive` is **your** game (self-serve — switch it to Live in the console under Game Settings → Status), `err.isTargetGameNotLive` is the **destination** game, usually owned by another developer, so you can't flip it — show `err.message` and steer the player elsewhere via `getDestinations`. `err.gameStatus` carries the current state. Don't merge these into one "not live" branch; it produces a "go fix it" button that leads nowhere half the time.
659
718
  - **Steam titles** (dark until a title is Steam-distributed): `initiateSend`/`initiateTransfer` can throw `err.isSteamValueNonTransferable` (moving more than the non-Steam balance to a non-Steam destination — show `err.message`, cap the amount at `err.steamTransferableMax`; `err.steamOriginAmount` is the Steam-locked portion) or `err.isNonSteamValueIntoSteamBlocked` (non-Steam value into a Steam title). Prevent both up front: `getDestinations` rows carry **`acceptsSteamOriginValue`** — disable non-Steam destinations for a player holding Steam-purchased currency.
660
719
  - Transfer self-claim may be disabled for your tenant; if it is, surface the claim-code path instead.
661
720
  - **Holds:** an approve/claim can return an HTTP 202 hold instead of success — inspect `result.holdReason` (`"RISK_HOLD"`, `"GUARDIAN_APPROVAL_PENDING"`, and on confirm-receipt `"RECIPIENT_IDENTITY_PENDING"`); success has no `holdReason` (and `next: "pending_claim"`). Terminal guardian outcomes throw (`GUARDIAN_APPROVAL_REJECTED`/`_EXPIRED`).
721
+ - **Guardian approval goes by email first.** When a minor's initiate returns the 202, the guardian gets a
722
+ signed, single-use link to a hosted INVO page with Approve / Decline — not a text. A reply-YES text goes
723
+ out only when the guardian has no verified email or the email could not be delivered. The raw 202
724
+ `guardian_approval` block (`t.raw`) now carries **`consent_channel`** (`"email"` | `"sms"`) — use it for
725
+ your waiting copy — and **`resend_endpoint`**. Poll `getGuardianApprovalStatus` exactly as before; the
726
+ approval object's `consent_channel` says how it went out and `decision_source` is `email_link` for a
727
+ page decision.
728
+ - **"Text my parent instead" — a REST call, not an SDK method.** `POST /api/sdk/approvals/guardian/{approvalId}/resend`
729
+ with the **minor's** player token (the session that started the transaction) and body `{ "channel": "sms" }`
730
+ — the only accepted value. Once per approval. `200 { status: "sent", channel: "sms" }`; `403 NOT_INITIATOR`;
731
+ `409 CHANNEL_WAS_SMS` (it already went by text — hide the button when `consent_channel` is `"sms"`);
732
+ `409 ALREADY_RESENT`; `410 APPROVAL_GONE` (decided or expired); `503 DELIVERY_FAILED` (retryable — does not
733
+ use up the one allowance). The emailed link keeps working alongside the text.
734
+ - **Phone-share and recipient-identity consents use the same hosted page.** On `err.isPhoneShareApprovalRequired`
735
+ the phone's existing owner gets an emailed link (Allow / Decline) when INVO has itself proven an address for
736
+ them — at most three holders, one email per request — and the 409 body carries `consent_channel: "email"`;
737
+ the OTP text goes out instead only when no proven holder exists (`consent_channel: "sms"`). The
738
+ `RECIPIENT_IDENTITY_PENDING` hold emails the phone owner's oldest verified address the same way. **Nothing
739
+ changes for you:** same 409 / 202 codes, same poll-and-retry, and the typed-code and in-app approves still work.
662
740
 
663
741
  **"You have X to collect"**
664
742
 
@@ -668,6 +746,186 @@ try {
668
746
  > **Seeing incoming transfers from other games?** They come back as **`kind: "receiving_confirm"`** — render **both** kinds (a UI that only shows `identity_gate` will miss all inbound). The list is scoped to the token's player, so mint the token for the **recipient**. PII-free (no claim code / phone).
669
747
  - **Server (game-secret):** `server.getInboundPending({ playerEmail | playerPhone })` — richer, includes `toPhone`/`toIdentityId` for routing a notification to the right account. Match `toPhone` to the player (`toIdentityId` is null when the phone maps to >1 of your players).
670
748
 
749
+ ### Legacy fallback: the SMS PIN (being retired)
750
+
751
+ **This is the legacy path. It is being retired, and new integrations should not build on
752
+ it.** It is kept working only for a sender who genuinely cannot approve with a passkey:
753
+ an unsupported device with no platform authenticator, or a player who declines both the
754
+ in-app ceremony and the QR flow.
755
+
756
+ When a sender has no enrolled approver, `initiateSend` / `initiateTransfer` return
757
+ `verificationMethod: "sms"` and a one-time PIN is texted. The completion calls are
758
+ `server.verifySmsTransfer(txnId, pin)` / `verifySmsSend(txnId, pin)` — **deprecated since
759
+ 3.1.0**, still fully functional, no runtime warning. They will be removed at some future
760
+ major; no date is being promised.
761
+
762
+ Why it is going away: a PIN in a text is a shared secret on a channel exposed to SIM swap,
763
+ SS7 interception and social engineering, it costs real money per message at every scale,
764
+ and it depends on carrier delivery INVO does not control. A passkey — in the client where
765
+ WebAuthn can run, on the player's phone by QR where it cannot — is stronger, faster and
766
+ free. Read `verificationMethod: "sms"` as *"this sender has no passkey yet"* and offer them
767
+ one; show a PIN pad only when there is no other way to serve that specific player.
768
+
769
+
770
+ ---
771
+
772
+ ## Sends and transfers, stage by stage
773
+
774
+ One reference for the whole money path — **both flows** (send and transfer) and **both
775
+ sides** (the sender who authorises, the recipient who collects). It exists because the
776
+ stages are easy to read as three when there are four, and the fourth one is the money.
777
+
778
+ > Companion page, same title, on the docs site:
779
+ > [**Sends and transfers, stage by stage**](https://docs.invo.network/docs/sends-and-transfers-stage-by-stage)
780
+ > — the same walkthrough with the raw REST calls, for stacks that don't use this package.
781
+
782
+ **The four stages.**
783
+
784
+ 1. **Initiate** (your server). Nothing has moved; a transaction now exists, pending the
785
+ sender's approval.
786
+ 2. **Prove who is approving.** A passkey ceremony in the browser, on INVO's hosted page,
787
+ or — where no browser exists — a device approval grant on the player's phone.
788
+ 3. **Settle** (your server, for the grant path). **A proof is not a payment.** The
789
+ approval says *who*; a separate call moves the value and runs every gate (guardian,
790
+ risk, recovery cooldown). In the browser `approveSend` / `approveTransfer` does both
791
+ at once, which is why the split only becomes visible on the grant path.
792
+ 4. **Collect.** The recipient confirms receipt (their own passkey, or the grant), or
793
+ redeems the claim code. Reconcile off webhooks, never off stage 3's response alone.
794
+
795
+ ### What your server must call, in order
796
+
797
+ | # | Stage | Send | Transfer | Auth |
798
+ |---|---|---|---|---|
799
+ | 1 | Initiate | `server.initiateSend(...)` | `server.initiateTransfer(...)` | game secret |
800
+ | 2 | Mint the player's session | `server.mintPlayerToken({ playerEmail })` | same | game secret |
801
+ | 3a | Sender approves — **browser** | `client.approveSend(txnId)` | `client.approveTransfer(txnId)` | player token |
802
+ | 3b | Sender approves — **web, hosted page** | `client.approveHosted({ transactionId, flow: "send" })` | `… flow: "transfer"` | player token |
803
+ | 3c | Sender approves — **console / TV / native** | `server.beginDeviceApproval({ flow: "send" })` → `pollDeviceApproval` | `… flow: "transfer"` | **player** token |
804
+ | 4 | **Settle the grant** (3c only) | **`server.approveWithDeviceCode({ flow: "send", deviceCode })`** | **`… flow: "transfer"`** | **player** token |
805
+ | 5a | Recipient collects — browser | `client.confirmReceiptSend(txnId)` | `client.confirmReceiptTransfer(txnId)` | player token |
806
+ | 5b | Recipient collects — console | `begin`/`poll` `flow: "send_receipt"` → **`approveWithDeviceCode`** | `… flow: "transfer_receipt"` → **`approveWithDeviceCode`** | **player** token |
807
+ | 5c | Recipient collects — claim code | `server.claimCurrency({ claimCode, … })` | `server.claimTransfer({ claimCode, … })` | game secret |
808
+ | 6 | Reconcile | `transfer.claim_pending` → `transfer.received` webhooks | same | webhook secret |
809
+
810
+ Steps 3c, 4 and 5b take the **player token explicitly** — on a console the game *server*
811
+ holds the token it minted, and the game secret is never sent on any of them.
812
+
813
+ ### The four device-approval flows
814
+
815
+ `flow` picks which endpoint stage 4 settles against. Begin with one flow and settle with
816
+ the same one: a grant approved for `transfer` settles nothing else.
817
+
818
+ | Side | `flow` | What `approveWithDeviceCode` calls | Success looks like |
819
+ |---|---|---|---|
820
+ | Sender, send | `send` | `POST /api/sdk/send/{id}/approve` | `status: "approved"`, `next: "pending_claim"` |
821
+ | Sender, transfer | `transfer` | `POST /api/sdk/transfers/{id}/approve` | `status: "approved"`, `next: "pending_claim"`, `claimCode` |
822
+ | Recipient, send | `send_receipt` | `POST /api/sdk/send/{id}/confirm-receipt` | `status: "completed"`, `amountReceived` |
823
+ | Recipient, transfer | `transfer_receipt` | `POST /api/sdk/transfers/{id}/confirm-receipt` | `status: "completed"`, `amountReceived` |
824
+
825
+ ### Errors on the money path
826
+
827
+ | Code | HTTP | Means | Do |
828
+ |---|---|---|---|
829
+ | `TRANSACTION_NOT_PENDING` | 400 | The transaction is not at this step. Three different situations: your earlier attempt **already landed**; the transaction is **dead** (expired / refunded); or — on a receipt flow — it has **not got here yet**, because the sender's own approval is still pending or held at a guardian. | **Not thrown by `approveWithDeviceCode`** — it comes back as `{ status: "not_pending", alreadySettled, currentStatus }`. `alreadySettled` separates the first case from the other two. When it is `false`, go read `getTransferStatus` / `getSendStatus` rather than assuming; never retry-loop. |
830
+ | `DEVICE_APPROVAL_NOT_APPROVED` | 400 | The `device_code` was unknown, another player's, bound to a different transaction, bound to a different **flow**, or the player has not approved yet. One answer for all five, deliberately — distinguishing them would leak which transactions have a live approval. | `err.isDeviceApprovalNotApproved`. Check the `flow` matches the `begin`, and that the poll actually said `approved`. |
831
+ | `DEVICE_APPROVAL_ALREADY_PENDING` | 409 | An **approved** grant for this transaction and flow is still inside its window. The player already approved. | `err.isDeviceApprovalAlreadyPending`, `err.deviceApprovalExpiresAt`. You are missing stage 4, not a new code — call `approveWithDeviceCode` with the code you have. (A merely *pending* earlier grant does **not** 409; `begin` supersedes it.) |
832
+ | `PASSKEY_RECOVERY_COOLDOWN` | 403 | Money **out** is paused for 24 h after a passkey recovery (SIM-swap protection). Receiving and collecting are unaffected. | `err.isPasskeyRecoveryCooldown`, `err.retryAfterAt` (ISO; the body also carries `retry_after_seconds`). Expect a fresh initiate later — do not retry-loop. |
833
+ | `SEND_APPROVE_FAILED`, `TRANSFER_APPROVE_FAILED`, `CONFIRM_RECEIPT_FAILED` | 400 | A **fault** on INVO's side, not a rule. `err.isSettleFault`; the body carries **`error_ref`** (`err.errorRef`). | Never retryable. See the ambiguity note below — do **not** tell the player it failed until you have read the transaction. Quote `errorRef` to INVO support; it names the exact server log line. |
834
+ | guardian hold | 202 | A minor's transaction is waiting on a guardian. **The money is held, not refused.** | Returned as a result with `holdReason`; poll `getGuardianApprovalStatus`. Terminal outcomes (`GUARDIAN_APPROVAL_REJECTED` / `_EXPIRED`) throw as 410. |
835
+
836
+ **Also reachable from a receipt settle** (`send_receipt` / `transfer_receipt`) — a console
837
+ recipient built only from the table above ships with no fallback for these:
838
+
839
+ | Code | HTTP | Means | Do |
840
+ |---|---|---|---|
841
+ | `receiver_not_enrolled_use_claim_code` | 409 | The recipient has no passkey in this game, so there is no in-app confirm to run. | `err.isReceiverNotEnrolled`. Fall back to the claim code — show it, or point them at the hosted claim link from their text. |
842
+ | `not_intended_receiver` | 403 | The token's identity is not the addressed recipient. | Not retryable. You minted the token for the wrong player, or the send was addressed to a different phone. |
843
+ | `PHONE_SHARE_APPROVAL_REQUIRED` | 409 | The receiver phone is contested, so INVO **holds the money** and asks its owner to approve. | `err.isPhoneShareApprovalRequired`. Not a failure: show `err.message` verbatim (`err.phoneShareLast4` names the phone), then **retry the same call** once approved — it then succeeds idempotently. On denial/expiry the sender is refunded. |
844
+ | `RECIPIENT_IDENTITY_PENDING` | 202 | Same shape, on the identity check: **money held**, the phone's owner emailed. | Comes back as a result with `holdReason`, not a throw. Keep the collect pending and retry later. |
845
+ | `RECIPIENT_IDENTITY_DECLINED` | 403 | The phone's owner said no. | Terminal. The sender is refunded; do not retry. |
846
+
847
+ > ⚠️ **A settle FAILURE is ambiguous about the money.** INVO commits the transfer and
848
+ > *then* builds its `200` by reading the transaction back — so a fault raised after that
849
+ > commit answers `400 *_FAILED` for money that **already moved**. A `err.status === 0`
850
+ > (timeout, dropped connection) is ambiguous for exactly the same reason, and this call is
851
+ > deliberately never auto-retried. On either: read `getTransferStatus` / `getSendStatus`,
852
+ > or wait for the `transfer.claim_pending` webhook, **before** you tell the player it
853
+ > failed — and never auto-start a replacement transaction.
854
+
855
+ ### "Already settled" is not a refusal
856
+
857
+ The integrator question this section was written for: *did the guard stop me, or is her
858
+ gold stuck?* You must be able to answer that without matching on message text.
859
+
860
+ `approveWithDeviceCode` **does not throw** for `TRANSACTION_NOT_PENDING`. It returns:
861
+
862
+ ```ts
863
+ const r = await server.approveWithDeviceCode({ playerToken, transactionId, flow: "transfer", deviceCode });
864
+ if (r.status === "not_pending") {
865
+ if (r.alreadySettled) {
866
+ // This step already happened — typically your first attempt landed and the response
867
+ // was lost. r.currentStatus says where it is now (pending_claim, completed…).
868
+ } else {
869
+ // NOT settled. Either dead (expired / failed / refunded), or — on a receipt flow —
870
+ // not there YET: the sender has not approved, or their approval is held at a
871
+ // guardian. It is also what an unrecognised status returns, deliberately.
872
+ // Go and read it; do not guess and do not start a replacement transaction:
873
+ const t = await server.getTransferStatus(transactionId);
874
+ }
875
+ } else {
876
+ // status "approved" (+ next: "pending_claim", claimCode on a transfer)
877
+ // or "completed" (+ amountReceived) on the receipt flows
878
+ // or a 202 hold — r.holdReason names it.
879
+ }
880
+ ```
881
+
882
+ Every other refusal is a normal thrown `InvoError` with a typed predicate, so a
883
+ `try`/`catch` around this call still means "something is wrong". Nothing in your code has
884
+ to read an English sentence to tell the two apart.
885
+
886
+ **`alreadySettled` fails closed.** It is `true` only for a status INVO knows to be past
887
+ this flow's step — and the two receipt flows have a *different* set from the two sender
888
+ flows, because the four endpoints gate on different statuses. Anything else, including a
889
+ status this SDK version has never seen, answers `false` with `currentStatus` set. Cautious
890
+ and wrong costs you a status lookup; confident and wrong credits goods for money that
891
+ never arrived.
892
+
893
+ *(Older INVO deployments answered this case with only a message — "Transaction not pending
894
+ PIN verification…", "…cannot be confirmed…" — and no machine code. The SDK matches those
895
+ shapes too, so `alreadySettled` is correct against an older backend without any
896
+ string-matching in your code. That fallback requires HTTP 400, one of those two phrases,
897
+ **and** a readable `(current status: …)` / `(status: …)` clause: "cannot be confirmed" is
898
+ ordinary English, so a phrase match alone is never allowed to assert that money moved.)*
899
+
900
+ ### Common mistakes
901
+
902
+ > **1. Polling to `approved` and stopping.** The one that costs real money. A device
903
+ > approval grant is a **factor**, not a payment: `approved` means the player proved who
904
+ > they are, and the transaction is still sitting at `pending_pin_verification`. **You must
905
+ > call `approveWithDeviceCode`.** Nothing else in this SDK settles it, and no webhook does
906
+ > it for you — `device_approval.approved` is the *cue* to call it. Left alone, the
907
+ > transaction expires on its own window and is refunded.
908
+ >
909
+ > **2. Treating "already settled" as a failure.** A repeat call after a crash or a lost
910
+ > response answers `TRANSACTION_NOT_PENDING`. That is your earlier attempt succeeding, not
911
+ > a refusal. Branch on `r.alreadySettled` — never on the message.
912
+ >
913
+ > **3. Sending the game secret on the grant calls.** Every device-approval call
914
+ > authenticates with the **player token**. A game secret in a console build is a game
915
+ > secret in a disassembler.
916
+ >
917
+ > **4. Beginning a second grant instead of settling the first.** If `begin` answers
918
+ > `409 DEVICE_APPROVAL_ALREADY_PENDING`, the player has already approved; you need stage
919
+ > 4, not another QR.
920
+ >
921
+ > **5. Polling faster than `interval`.** You get `slow_down`; add 5 seconds and resume.
922
+ >
923
+ > **6. Using the wrong `flow` at stage 4.** The sender's grant (`transfer`) cannot settle
924
+ > the recipient's step (`transfer_receipt`) — it answers `DEVICE_APPROVAL_NOT_APPROVED`,
925
+ > which reads like a broken code and is really a wrong flow.
926
+ >
927
+ > **7. Granting value off stage 3's HTTP response.** Reconcile off webhooks.
928
+
671
929
  ---
672
930
 
673
931
  ## Passkeys (enroll, approve, link, recover)
@@ -688,8 +946,8 @@ await client.enrollPasskey();
688
946
  ```
689
947
 
690
948
  **First-enrollment OTP grant.** For tenants that require it, the first `enrollPasskey()`
691
- throws `ENROLLMENT_REQUIRES_AUTHORIZATION`. Send a one-time code (to the player's phone +
692
- email on file), verify it, then **retry the same `enrollPasskey()`** — the server-side
949
+ throws `ENROLLMENT_REQUIRES_AUTHORIZATION`. Send a one-time code (to the player's email on
950
+ file first; by text only on request or when there is no email), verify it, then **retry the same `enrollPasskey()`** — the server-side
693
951
  grant is consumed automatically:
694
952
 
695
953
  ```ts
@@ -697,7 +955,7 @@ try {
697
955
  await client.enrollPasskey();
698
956
  } catch (e) {
699
957
  if (e instanceof InvoError && e.isEnrollmentAuthorizationRequired) {
700
- await client.enrollmentBegin(); // → { status: "sent", channels: ["sms","email"] }
958
+ await client.enrollmentBegin(); // → { status: "sent", channels: ["email"] } — email first; { channel: "sms" } to text instead
701
959
  await client.enrollmentVerify(codeFromUser); // 6-digit OTP
702
960
  await client.enrollPasskey(); // retry — grant auto-consumed
703
961
  } else if (e instanceof InvoError && e.isEnrollmentProofRequired) {
@@ -720,7 +978,7 @@ try {
720
978
  } catch (e) {
721
979
  if (e instanceof InvoError && e.isEnrollmentProofRequired) {
722
980
  // Player still HAS the other method → linkDevice (above). Lost/deleted it → recover:
723
- await client.recoveryBegin(); // → { status:"sent", channels:["sms","email"] }
981
+ await client.recoveryBegin(); // → { status:"sent", channels:["email"] } — email first; { channel: "sms" } to text instead
724
982
  await client.recoveryComplete(codeFromUser); // → { status:"recovered", deactivatedCount }
725
983
  await client.enrollPasskey(); // same call — now succeeds
726
984
  } else throw e;
@@ -744,62 +1002,356 @@ try {
744
1002
  - Challenges are single-use and bound to `{flow}:{transactionId}`.
745
1003
  - The SDK passes the backend's WebAuthn options through unchanged (it does not hard-code `pubKeyCredParams`/`timeout`/`attestation`).
746
1004
 
1005
+ ### Web games — approving on INVO's hosted page
1006
+
1007
+ A player on the **web** who has no INVO passkey yet — or whose passkey lives on your domain
1008
+ and so cannot approve on INVO's — uses the same hosted page a console player scans. On the
1009
+ web the **browser is the client**: one SDK call runs the whole device-approval grant with
1010
+ the player token it already holds, exactly as the in-app passkey calls do. Your **server does
1011
+ nothing new** — it initiates the transfer/send as today and its `device_approval.approved`
1012
+ webhook still fires.
1013
+
1014
+ **This is the path for every new title** — there is no partner passkey domain to verify any
1015
+ more (see [which passkey path serves your tenant](#prerequisite-which-passkey-path-serves-your-tenant)).
1016
+ In-app passkeys on your own domain (`enrollPasskey`, `approveSend`, `approveTransfer`) remain
1017
+ fully supported for tenants that verified a domain before the freeze.
1018
+
1019
+ ```ts
1020
+ import { InvoClient, InvoError } from "@invonetwork/web-sdk";
1021
+
1022
+ const client = new InvoClient({ token: playerToken, baseUrl: INVO_BASE });
1023
+
1024
+ // Call from a click handler: the popup is opened synchronously, before any network call.
1025
+ approveButton.onclick = async () => {
1026
+ try {
1027
+ const result = await client.approveHosted({
1028
+ transactionId: transferId, // the transfer/send your server initiated
1029
+ flow: "transfer", // "transfer" | "send" | "send_receipt" | "transfer_receipt"
1030
+ // onEnrollment: (e, respond) => …, // optional: observe / draw your own prompt (renderPrompt:false)
1031
+ });
1032
+ switch (result.status) {
1033
+ case "approved": // money moved (or is held: result.approval.holdReason) — same shape as approveTransfer()
1034
+ showClaimCode(result.approval?.claimCode); break;
1035
+ case "denied": // the player said no on INVO's page (or denied the enrolment)
1036
+ case "expired": // start a new approval
1037
+ case "closed": // the player closed the popup
1038
+ break;
1039
+ case "blocked": // popup blocked or severed — nothing started; show a button and call again
1040
+ showRetry(result.message); break;
1041
+ }
1042
+ } catch (e) {
1043
+ if (e instanceof InvoError) handleBackendRefusal(e); // begin 400, invalid_grant, approve gates (e.g. PASSKEY_RECOVERY_COOLDOWN)
1044
+ }
1045
+ };
1046
+ ```
1047
+
1048
+ What the one call does, in order — the same REST flow as the console section below, driven
1049
+ from the browser:
1050
+
1051
+ 1. `POST /api/sdk/approvals/device/begin` with `{ transaction_id, flow, channel: "popup" }`.
1052
+ INVO records this page's `Origin` as the popup's opener. **The SDK holds the returned
1053
+ `device_code` for the duration of the call** — it is never on the result and never
1054
+ logged; your code never sees it.
1055
+ 2. Opens `verification_uri_complete` in a popup (480×720). The player enrols or uses their
1056
+ INVO passkey there, on INVO's own domain.
1057
+ 3. Polls `POST /api/sdk/approvals/device/poll` at the server's `interval`, backing off by
1058
+ 5 s on `slow_down`.
1059
+ 4. First-time enrolment: while the page waits on your screen, the poll carries
1060
+ `enrollment { state: "awaiting_screen", device_label, match_code }` and the SDK shows
1061
+ the INVO match-code prompt — *"Set up INVO on iPhone? Code 48-27. Say Yes only if the
1062
+ phone you just scanned/opened shows this code."* — with **Yes, it shows this code** /
1063
+ **No, that is not my phone** (focus-trapped dialog; Escape = No). The answer goes to
1064
+ `POST /api/sdk/approvals/device/confirm-enrollment`; `confirmed` shows a quiet
1065
+ "Finishing on iPhone… / Stop it, wrong code" row; a 409 already-decided (the backup
1066
+ email answered first) takes the prompt down quietly.
1067
+ 5. When the poll says `approved`, the SDK calls the flow's approve endpoint with the
1068
+ `device_code` — `transfers/{id}/approve`, `send/{id}/approve`,
1069
+ `send/{id}/confirm-receipt` or `transfers/{id}/confirm-receipt` — through every gate your
1070
+ in-app approve already runs, and resolves `{ status: "approved", approval }`.
1071
+
1072
+ Security notes, in plain language:
1073
+
1074
+ - **The page's message is a wake-up, not a result.** When INVO's page finishes it posts a
1075
+ status-only message to the window that opened it; the SDK uses it to poll *right now*
1076
+ and nothing else. The outcome always comes from the poll and the approve call.
1077
+ - **Origin check.** The SDK accepts that message only from the hosted page's own https
1078
+ origin (parsed from `verification_uri_complete`; pass `platformOrigin` to pin it — the
1079
+ URL must then match it exactly) and only from the popup it opened. Anything else is
1080
+ ignored. The page posts only to its opener — the origin your `begin` request carried —
1081
+ never to `*`.
1082
+ - **No redirect parameter.** The hosted page never navigates to your site; there is no
1083
+ `return`/`redirect` URL to supply or to spoof. The popup is closed on `approved` and left
1084
+ readable on denied/expired. If the browser blocks the popup the default is to resolve
1085
+ `blocked` *before anything is started*, so you can show a button and call again from its
1086
+ click; `popupBlocked: "redirect"` opts in to sending this tab to the hosted page instead
1087
+ (your page unloads; the `device_approval.approved` webhook is then your server's signal).
1088
+ - **COOP.** Do not send `Cross-Origin-Opener-Policy: same-origin` on the page that calls
1089
+ `approveHosted` — it severs the popup from its opener and the wake-up can never arrive.
1090
+ Use `same-origin-allow-popups`. The SDK detects a severed popup and resolves `blocked`
1091
+ with a hint.
1092
+ - **Cancel with `signal`** (resolves `closed` and closes the popup). Nothing is called after
1093
+ the promise settles.
1094
+
747
1095
  ### Consoles and TVs — approving without a browser (RFC 8628)
748
1096
 
749
1097
  A console has no browser, so it cannot run a passkey ceremony at all. **Device
750
1098
  Approval** moves the ceremony to a device that can: your game shows a short code, the
751
- player approves on their phone, your server polls until it hears back. It is the
1099
+ player approves on their phone, your server polls until it hears back — **and then your
1100
+ server makes the call that actually moves the money.** It is the
752
1101
  [OAuth 2.0 Device Authorization Grant, RFC 8628](https://datatracker.ietf.org/doc/html/rfc8628)
753
1102
  — the same flow every console and TV app uses — so a standard client library understands
754
1103
  the responses.
755
1104
 
756
- **Not an SDK method** — it is a server-to-server REST flow, because the polling has to
757
- happen on your backend, not in the game client.
1105
+ > **The grant is a factor, not a payment.** Reaching `approved` proves *who* approved and
1106
+ > settles **nothing**. The transaction is still waiting. `approveWithDeviceCode` is the
1107
+ > money step, and without it the transaction expires and is refunded. This is the single
1108
+ > most common integration failure on this flow — see
1109
+ > [Sends and transfers, stage by stage](#sends-and-transfers-stage-by-stage).
1110
+
1111
+ **Four SDK methods, since 3.7.0** (`server.beginDeviceApproval`, `pollDeviceApproval`,
1112
+ `confirmDeviceEnrollment`, **`approveWithDeviceCode`**), plus the optional
1113
+ `completeDeviceApproval` loop. Earlier versions documented this as raw REST only, which is
1114
+ how a grant could be polled to `approved` and then dropped. The REST endpoints are
1115
+ unchanged and still usable directly.
1116
+
1117
+ Every one of these calls authenticates with the **player token**, never the game secret —
1118
+ on a console it is your *server* that holds the token it minted for the player.
1119
+
1120
+ **The endpoints underneath**, for a stack that is not using this package. All four take
1121
+ `Authorization: Bearer <player token>`; none takes the game secret:
1122
+
1123
+ | SDK method | Endpoint |
1124
+ |---|---|
1125
+ | `beginDeviceApproval` | `POST /api/sdk/approvals/device/begin` |
1126
+ | `pollDeviceApproval` | `POST /api/sdk/approvals/device/poll` |
1127
+ | `confirmDeviceEnrollment` | `POST /api/sdk/approvals/device/confirm-enrollment` |
1128
+ | **`approveWithDeviceCode`**, `flow: "send"` | **`POST /api/sdk/send/{transaction_id}/approve`** |
1129
+ | **`approveWithDeviceCode`**, `flow: "transfer"` | **`POST /api/sdk/transfers/{transaction_id}/approve`** |
1130
+ | **`approveWithDeviceCode`**, `flow: "send_receipt"` | **`POST /api/sdk/send/{transaction_id}/confirm-receipt`** |
1131
+ | **`approveWithDeviceCode`**, `flow: "transfer_receipt"` | **`POST /api/sdk/transfers/{transaction_id}/confirm-receipt`** |
1132
+
1133
+ Each settle call takes the body `{"device_code": "..."}` and the player's bearer token —
1134
+ the same token that began the grant.
758
1135
 
759
1136
  **Available to every title, with nothing to configure.** The constraint is a property of
760
1137
  the *device*, not your game: a title with a website *and* a console build uses the normal
761
1138
  ceremony in the browser and this one on the console.
762
1139
 
1140
+ **Native Steam and desktop game clients (Mac & Windows) belong here too.** Even though the
1141
+ operating system supports passkeys, an embedded game client can't invoke the platform
1142
+ authenticator from inside the engine — so a native desktop title uses this QR flow exactly as
1143
+ a console does. It is the **client** that forces QR here, not the OS.
1144
+
763
1145
  ```ts
764
- // 1. Your server starts an approval for ONE transaction.
1146
+ import { InvoServer } from "@invonetwork/web-sdk/server";
1147
+
1148
+ const server = new InvoServer({
1149
+ gameSecret: process.env.INVO_GAME_SECRET!,
1150
+ baseUrl: "https://sandbox.invo.network/sandbox",
1151
+ });
1152
+ const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
1153
+
1154
+ // The player token your server minted for this player (mintPlayerToken).
1155
+ const playerToken = session.invoPlayerToken;
1156
+
1157
+ // 1. BEGIN — start an approval for ONE transaction.
765
1158
  // flow: "transfer" | "send" | "send_receipt" | "transfer_receipt"
766
- const start = await fetch(`${INVO_BASE}/api/sdk/approvals/device/begin`, {
767
- method: "POST",
768
- headers: { Authorization: `Bearer ${sdkSessionToken}`, "Content-Type": "application/json" },
769
- body: JSON.stringify({ transaction_id: transferId, flow: "transfer" }),
770
- }).then((r) => r.json());
771
- // -> { device_code, user_code, verification_uri, verification_uri_complete,
772
- // expires_in, interval }
773
-
774
- // 2. The game renders `verification_uri_complete` as a QR and prints `user_code`
775
- // under it. The QR already contains the code, so most players never type.
776
-
777
- // 3. Poll from your SERVER, never faster than `interval` seconds.
778
- const poll = await fetch(`${INVO_BASE}/api/sdk/approvals/device/poll`, {
779
- method: "POST",
780
- headers: { Authorization: `Bearer ${sdkSessionToken}`, "Content-Type": "application/json" },
781
- body: JSON.stringify({ device_code: start.device_code }),
782
- }).then((r) => r.json());
783
- // approved -> { status: "approved", transaction_id, flow }
784
- // authorization_pending -> keep polling
785
- // slow_down -> back off, then resume
786
- // expired_token -> start a new approval
787
- // access_denied -> the player declined; do not retry silently
788
- // invalid_grant -> unknown or not yours
1159
+ // channel (optional, default "qr"): "qr" (console / TV / native desktop),
1160
+ // "app_browser" (the Unity / Unreal plugin opens the system browser).
1161
+ // "popup" is browser-only — that is client.approveHosted().
1162
+ const grant = await server.beginDeviceApproval({
1163
+ playerToken,
1164
+ transactionId,
1165
+ flow: "transfer",
1166
+ });
1167
+ // grant: { deviceCode, userCode, verificationUri, verificationUriComplete,
1168
+ // expiresIn, interval, channel, raw }
1169
+
1170
+ // 2. SHOW — render grant.verificationUriComplete as a QR and print grant.userCode
1171
+ // under it. The QR already carries the code, so most players never type.
1172
+ // Keep grant.deviceCode on your server: it is a bearer credential.
1173
+
1174
+ // 3. POLL — never faster than grant.interval seconds.
1175
+ let interval = grant.interval;
1176
+ for (;;) {
1177
+ await sleep(interval * 1000);
1178
+ const poll = await server.pollDeviceApproval({ playerToken, deviceCode: grant.deviceCode });
1179
+
1180
+ if (poll.status === "authorization_pending") {
1181
+ // A first-time phone may be waiting on YOUR screen — see `enrollment` below.
1182
+ if (poll.enrollment) showMatchPrompt(poll.enrollment);
1183
+ if (poll.interval) interval = poll.interval;
1184
+ continue;
1185
+ }
1186
+ if (poll.status === "slow_down") { interval += 5; continue; } // RFC 8628 §3.5
1187
+ if (poll.status === "access_denied") return playerDeclined();
1188
+ if (poll.status === "expired_token") return startOver(); // begin again
1189
+
1190
+ // 4. APPROVED → **CALL THE MONEY STEP.** Nothing has moved until this returns.
1191
+ const settle = await server.approveWithDeviceCode({
1192
+ playerToken,
1193
+ transactionId,
1194
+ flow: "transfer", // the SAME flow you began with
1195
+ deviceCode: grant.deviceCode,
1196
+ });
1197
+
1198
+ if (settle.status === "not_pending") {
1199
+ // Your earlier attempt already landed (settle.alreadySettled) or the transaction
1200
+ // is dead (expired / refunded). Read settle.currentStatus. Not a refusal.
1201
+ } else {
1202
+ // "approved" + next: "pending_claim" (+ settle.claimCode on a transfer), or
1203
+ // "completed" + settle.amountReceived on the receipt flows, or a 202 hold
1204
+ // (settle.holdReason).
1205
+ }
1206
+ break;
1207
+ }
1208
+ ```
1209
+
1210
+ **Or let the SDK run stages 3 and 4** — `completeDeviceApproval` polls on `interval`,
1211
+ adds 5 s on `slow_down`, surfaces the enrollment prompt, and on `approved` calls
1212
+ `approveWithDeviceCode` for you:
1213
+
1214
+ ```ts
1215
+ const done = await server.completeDeviceApproval({
1216
+ playerToken,
1217
+ transactionId,
1218
+ flow: "transfer",
1219
+ deviceCode: grant.deviceCode,
1220
+ interval: grant.interval,
1221
+ onEnrollment: (e, respond) => {
1222
+ if (!e) return hideMatchPrompt();
1223
+ showMatchPrompt(e); // "Set up INVO on <e.deviceLabel>? Code <e.matchCode>"
1224
+ // ALWAYS attach a .catch: this is called without await, and an unhandled rejection
1225
+ // exits a Node process. A prompt the grant has outlived resolves quietly, but any
1226
+ // other refusal rejects — log it and move on; the next poll reports the real state.
1227
+ onPlayerAnswer((yes) =>
1228
+ respond(yes ? "approve" : "deny").catch((err) => log.warn("enrolment answer lost", err)),
1229
+ );
1230
+ },
1231
+ });
1232
+ // done.status: "approved" (done.settlement carries the result) | "denied" | "expired" | "aborted"
789
1233
  ```
790
1234
 
1235
+ > **Convenience only.** It holds a request open for as long as the player takes, so it
1236
+ > suits a job or a per-player worker, not a request handler with a short timeout. And
1237
+ > because it moves money from inside a loop, **record the attempt in your own store before
1238
+ > the loop starts** — if your process dies between the approve call and its response, the
1239
+ > only way to know whether the money moved is a record you wrote first, plus
1240
+ > `getTransferStatus` / `getSendStatus`. Servers that can't hold a loop open should use
1241
+ > the three calls directly and keep `deviceCode` in their own store.
1242
+
791
1243
  - **One approval authorises one transaction.** Unlike the plain RFC 8628 grant, which
792
- authorises a *client*, an INVO device code is bound to the transaction you named and is
793
- consumed when used. It cannot approve anything else and cannot be reused.
794
- - **`user_code` is meant to be seen; `device_code` is not.** Poll from your backend.
795
- - **One live code per transaction.** Starting a second returns
796
- `409 DEVICE_APPROVAL_ALREADY_PENDING` — reuse the one you have or let it expire.
1244
+ authorises a *client*, an INVO device code is bound to the transaction **and the flow**
1245
+ you named. It cannot approve anything else.
1246
+ - **When the code is spent: at the money step, not at approval.** The `device_code` stops
1247
+ being usable when `approveWithDeviceCode` settles the transaction — because the
1248
+ transaction is then no longer pending, and that is what the settle call checks under a
1249
+ row lock. Polling to `approved` consumes nothing; a *second* `approveWithDeviceCode`
1250
+ with the same code answers `TRANSACTION_NOT_PENDING` (returned as
1251
+ `status: "not_pending"`, not thrown) — which, on a sender flow, is how you confirm that a
1252
+ settle whose response you lost did in fact land.
1253
+ - **`userCode` is meant to be seen; `deviceCode` is not.** Poll from your backend, never
1254
+ from the game client, and never log or render the device code.
1255
+ - **One live code per transaction and flow.** Calling `begin` again while an earlier grant
1256
+ is merely *pending* **supersedes** it — you get a fresh code and a page still open on the
1257
+ old one is told to scan again (that is the right answer when a player retries after a
1258
+ crash or an abandoned phone ceremony). If the earlier grant was already **approved**, the
1259
+ begin is refused with `409 DEVICE_APPROVAL_ALREADY_PENDING` + `expires_at`
1260
+ (`err.isDeviceApprovalAlreadyPending`, `err.deviceApprovalExpiresAt`): the player has
1261
+ approved and you are missing the money step, not a new code. Once that approved grant's
1262
+ own window passes, `begin` works again for the same transaction. The sender's grant and
1263
+ the recipient's are scoped separately, so `transfer` and `transfer_receipt` never block
1264
+ each other.
1265
+ - **Starting an approval extends the transaction's window.** For `transfer` and `send`,
1266
+ `begin` pushes the transaction's own approval window past the code's expiry, so an
1267
+ approval at minute nine can't land on a transfer that has already expired and been
1268
+ refunded.
797
1269
  - **Subscribe to `device_approval.approved`** to learn the moment an approval lands
798
- instead of waiting for the next poll. Polling still works alone; the webhook is a
799
- latency improvement, not a replacement.
800
- - **The player needs an INVO passkey.** A passkey they set up on *your* domain is a
801
- different credential and cannot be used here — that is how passkeys work. The approval
802
- page says so plainly when they need to set one up.
1270
+ instead of waiting for the next poll — then **call `approveWithDeviceCode`**. The
1271
+ webhook is a latency improvement, not the money step and not a replacement for it; the
1272
+ `transfer.*` lifecycle events that follow are what you reconcile against.
1273
+ - **First-time approvers enrol on the spot — your only job is one Yes/No prompt.** The
1274
+ approval page uses a passkey registered with INVO, on INVO's own domain; a passkey the
1275
+ player set up on *your* domain is a different credential and cannot be used there — that
1276
+ is how passkeys work. So the first scan enrols one, and the proof it's really them is
1277
+ **your game screen**: the phone says "Confirm on your game screen", your game shows "Set
1278
+ up INVO on this phone: iPhone?", the player presses Yes on the console, and their phone's
1279
+ fingerprint / face / screen lock creates the passkey and approves. No code to type, no
1280
+ SMS, ever. Every later scan is scan, biometric, done. Same `begin`/`poll`, same
1281
+ `device_approval.approved` webhook, same `method` value `device_grant_webauthn`, same
1282
+ approve call with the `device_code` afterwards.
1283
+ - **Poll: the `enrollment` object.** While a phone is waiting on your screen, the
1284
+ `authorization_pending` body gains it (absent when no phone asked — an already-enrolled
1285
+ phone never triggers it):
1286
+
1287
+ ```json
1288
+ { "error": "authorization_pending",
1289
+ "enrollment": { "state": "awaiting_screen", "device_label": "iPhone",
1290
+ "match_code": "48-27", "recovery": false,
1291
+ "requested_at": "2026-09-03T18:04:12+00:00" } }
1292
+ ```
1293
+
1294
+ Show the prompt while `state` is `awaiting_screen`; remove it the moment it changes
1295
+ (`confirmed` / `denied`) or the object disappears. `device_label` is from a fixed list
1296
+ (iPhone, iPad, Android phone, Android device, Mac, Windows PC, Chromebook, Linux device,
1297
+ phone), derived from the scanning phone's browser — a hint, not an identity. Lead the
1298
+ copy with "scanned just now". **`recovery: true`** means the phone declared it is
1299
+ *replacing* a lost INVO passkey — word the prompt "Replace your INVO passkey with this
1300
+ iPhone? Code 48-27" and answer through the same `confirm-enrollment` (see *Recovering a
1301
+ lost passkey* below).
1302
+ - **Answer it: `confirmDeviceEnrollment`** — same player token as begin/poll
1303
+ (`POST /api/sdk/approvals/device/confirm-enrollment` underneath).
1304
+
1305
+ ```ts
1306
+ const r = await server.confirmDeviceEnrollment({
1307
+ playerToken,
1308
+ deviceCode: grant.deviceCode,
1309
+ decision: "approve", // or "deny"
1310
+ });
1311
+ // r.status: "confirmed" | "denied"
1312
+ // throws 409 DEVICE_APPROVAL_ENROLLMENT_ALREADY_DECIDED { decided, via }
1313
+ // -> the backup email answered first; take the prompt down quietly
1314
+ // throws 409 DEVICE_APPROVAL_NO_ENROLLMENT_PENDING -> no phone has asked
1315
+ // throws 400 invalid_grant / expired_token
1316
+ ```
1317
+
1318
+ **Deny ends the grant**: poll returns `access_denied`, and the phone says it was declined
1319
+ on the game screen.
1320
+ - **Backup email.** At the scan, an email goes to the address on file — "confirm on your game
1321
+ screen; can't see the prompt? tap here; wasn't you? tap here; ignore this if you already
1322
+ confirmed". Opened after the screen answered, it says "you already confirmed this". A
1323
+ backup for a missed prompt, not the proof channel; nothing for you to do.
1324
+ - **Mobile (`channel: "app_browser"`): enrolment is auto-confirmed, no prompt.** The Unity /
1325
+ Unreal plugins open the same page in the system browser (`ASWebAuthenticationSession` /
1326
+ Custom Tabs) and return on `invo-sdk-<game_id>://done`, which carries nothing. Because the
1327
+ phone running the page *is* the device that opened it, the game's prompt is unreachable
1328
+ and a match code proves nothing — so INVO confirms the enrolment itself: the poll's
1329
+ `enrollment` object appears already `confirmed` and goes straight to `approved`; the
1330
+ backup email still goes out as the "if this wasn't you" alert. Start polling on
1331
+ `interval` the moment `begin` returns — the return is only a hint to poll sooner.
1332
+ - **Recovering a lost passkey — from the page, nothing new on your side.** A player whose
1333
+ only INVO passkey was on a phone they no longer have taps "Recover my passkey by email"
1334
+ on the page. Recovery needs **both** halves of the identity: your game screen confirms
1335
+ the phone (the `recovery: true` prompt above — auto-confirmed on mobile), and *only then*
1336
+ a single-use recovery link is emailed to the address on file (never an address the page
1337
+ supplies; one recovery per identity per 24 h). Opened on the same phone, that tab
1338
+ confirms and the page carries on: INVO deactivates the old INVO passkeys, notifies the
1339
+ owner on every channel, enqueues an **`identity.passkey_reset`** webhook to your game,
1340
+ and the phone enrols a fresh passkey and settles the approval — your poll reports
1341
+ `approved` and `device_approval.approved` fires as usual.
1342
+
1343
+ > ⚠️ **Money out is paused for 24 hours after a recovery.** The approval settles, but the
1344
+ > approve call for a `transfer` / `send` is refused with `403 PASSKEY_RECOVERY_COOLDOWN`
1345
+ > (+ `retry_after`). The page tells the player "recovered; start this transfer again after
1346
+ > the hold" — expect a fresh initiate later, not a retry. Receiving and collecting are
1347
+ > unaffected.
1348
+ - **An identity with a method elsewhere must vouch for the new one.** If the identity
1349
+ already has an active approver — a passkey on a partner domain, the INVO app's device key —
1350
+ the page refuses to enrol beside it with `409 ENROLLMENT_REQUIRES_PROOF` and tells the
1351
+ player to add this phone from where that method lives (`linkDevice`), then scan again. An
1352
+ identity with no method enrols freely.
1353
+ - **The code box on the page is the RFC 8628 `user_code`,** there for a TV with no camera.
1354
+ When the QR pre-fills it, the box isn't shown. It is not an SMS field.
803
1355
  - **Currency purchases on a console go through that console's store**, as the platform
804
1356
  holder requires. This flow is for approving transfers and sends.
805
1357
 
@@ -863,6 +1415,7 @@ export const POST = createWebhookHandler({
863
1415
  | `item.purchased` | every item purchase | **grant the in-game item** (payload includes `transaction_id, order_id, player_email, identity_id, item_id, item_name, item_quantity, unit_price, total_price, currency_name, new_balance, fee_breakdown`) |
864
1416
  | `platform_commerce.purchased` | every Platform Commerce purchase (balance immediately; **card after payment settles**) | **fulfill the ecommerce order** — never on the browser confirm (payload: `transaction_id, order_id, funding_source, player_email, identity_id, item_id, item_name, item_quantity, total_price`; + `unit_price, currency_name, new_balance` on balance; `total_price_usd` on card; `fee_breakdown`) |
865
1417
  | `platform_commerce.refunded` | a Platform Commerce refund | handle the reversal (payload: `order_id, funding_source, player_email, refunded_amount, amount_unit, fee_retained`) |
1418
+ | `transfer.received` / `transfer.claim_expired` / `transfer.refunded` | sends & transfers | reconcile claim state — credited to the recipient (by any claim path, the hosted claim page included) / not collected within 24h / returned to the sender |
866
1419
 
867
1420
  Don't block waiting on `purchase.failed` for the `game`/`steam` rails — they only emit `completed`/`refunded`. Reconcile off `*.completed` + the status endpoints. For Platform Commerce **card** orders, fulfill on `platform_commerce.purchased`, not the browser confirmation.
868
1421
 
@@ -954,7 +1507,7 @@ Helpers:
954
1507
  | `.isPhoneShareAlreadyApproved` | phone-share was already approved (e.g. from a `/reject`) |
955
1508
  | `.isSourceGameNotLive` | **(403)** the caller's OWN game is in testing → **self-serve**: switch it to Live in the console (Game Settings → Status). Show `.message`; `.gameStatus` has the current state |
956
1509
  | `.isTargetGameNotLive` | **(403)** the DESTINATION game is in testing → the caller usually **can't fix this** (someone else's game). Show `.message`; steer to another destination via `getDestinations`. Deliberately **distinct** from `.isSourceGameNotLive` — don't collapse them, the remediation differs |
957
- | `.isWebauthnNotEnabledForTenant` | **(403)** tenant has no verified RP ID → **configuration state, not a failure**. Fall back to the SMS/in-app path; see [passkey prerequisites](#prerequisite-passkeys-are-dark-until-your-tenant-verifies-a-domain) |
1510
+ | `.isWebauthnNotEnabledForTenant` | **(403)** tenant has no partner passkey domain — the normal state now that new domains are frozen → **configuration state, not a failure**. Approve on INVO's hosted page (`approveHosted`); see [which passkey path serves your tenant](#prerequisite-which-passkey-path-serves-your-tenant) |
958
1511
 
959
1512
  Client-side guards (bad amount, missing idempotency key, `rail:"steam"` on `purchaseCurrency`, item validation) throw `InvoError` with `.status === 0` **before** any network call. Notable backend codes: `SDK_TOKEN_EXPIRED`, `TENANT_NOT_MIGRATED`, `WEBAUTHN_NOT_ENABLED_FOR_TENANT`, `WEBAUTHN_UV_REQUIRED`, `ENROLLMENT_REQUIRES_PROOF`, `ENROLLMENT_CODE_INVALID`, `PASSKEY_RECOVERY_COOLDOWN` (403, `retryAfterAt`), `no_channel_on_file`, `rate_limited`, `WRONG_RAIL_ENDPOINT`, `flow_paused`.
960
1513
 
@@ -998,6 +1551,11 @@ try {
998
1551
  | `getTransferStatus(txnId)` / `getSendStatus(txnId)` | `TransactionStatusResult` — poll outbound state (`verificationState`) |
999
1552
  | `getGuardianApprovalStatus(txnId)` | `GuardianApprovalStatusResult` — poll a guardian hold to resolution (`state`) |
1000
1553
  | `getDestinations({ sourceGameId, direction? })` | `DestinationsResult` — server-side (game-secret) destinations; same rows as the browser variant |
1554
+ | `beginDeviceApproval({ playerToken, transactionId, flow, channel? })` | `DeviceApprovalGrant` — `{ deviceCode, userCode, verificationUri, verificationUriComplete, expiresIn, interval, channel, raw }`. **Player token**, never the game secret. Show `verificationUriComplete` as a QR |
1555
+ | `pollDeviceApproval({ playerToken, deviceCode })` | `DeviceApprovalPollResult` — `status: "approved" \| "authorization_pending" \| "slow_down" \| "expired_token" \| "access_denied"` (+ `enrollment` while a first-time phone waits on your screen). `invalid_grant` throws |
1556
+ | `confirmDeviceEnrollment({ playerToken, deviceCode, decision })` | `{ status, raw }` — answers the on-screen match-code prompt; `decision: "approve" \| "deny"` |
1557
+ | **`approveWithDeviceCode({ playerToken, transactionId, flow, deviceCode })`** | **The money step.** `DeviceApprovalSettleResult` — routes by `flow` to the transfer/send approve or confirm-receipt endpoint. `TRANSACTION_NOT_PENDING` comes back as `status: "not_pending"` + `alreadySettled` + `currentStatus`, **not** thrown |
1558
+ | `completeDeviceApproval({ playerToken, transactionId, flow, deviceCode, interval?, onEnrollment?, signal? })` | `{ status: "approved" \| "denied" \| "expired" \| "aborted", settlement?, lastPoll? }` — convenience loop: polls honouring `interval`/`slow_down`, then calls `approveWithDeviceCode` |
1001
1559
  | `phoneShareInitiate({ phone, email })` / `phoneShareApprove({ approvalId, otp })` / `phoneShareStatus({ phone, email })` | phone-share OTP handshake (unauthenticated) to resolve a `PHONE_SHARE_APPROVAL_REQUIRED` (409); then re-issue the original request |
1002
1560
  | `iterateItemPurchaseHistory({ playerEmail, pageSize? })` | async iterator over all history rows |
1003
1561
  | `verifyWebhook(rawBody, signatureHeader, secret \| secrets, opts?)` | typed `InvoWebhookEvent` (throws on bad signature) |
@@ -1019,6 +1577,7 @@ Every method also accepts an optional final `{ signal }` (`AbortSignal`) for can
1019
1577
  | `getPendingCollect()` | `{ pending, raw }` — the player's own pending-to-collect list (player-token) |
1020
1578
  | `getDestinations({ direction? })` | `{ availableGames, sourceGameName, transferMode, … }` — where the player can send/transfer, metadata inline |
1021
1579
  | `getBalance()` | `{ gameId, gameName, balances, totalValue, currencyCount, hasFunds, raw }` — the player's balances for this game |
1580
+ | `approveHosted({ transactionId, flow, platformOrigin?, onEnrollment?, renderPrompt?, popupBlocked?, popup?, signal? })` | `{ status: "approved" \| "denied" \| "expired" \| "closed" \| "blocked" \| "redirected", popupBlocked, message?, approval? }` — runs the whole RFC 8628 device-approval grant from the browser on INVO's hosted page (begin `channel:"popup"` → popup → poll → match-code prompt → confirm-enrollment → approve with the `device_code`, which the SDK holds and never exposes); `approval` is the `ApproveResult` / `ConfirmReceiptResult` of the flow's approve endpoint |
1022
1581
  | `platformCommerce.mountCheckout(el, checkoutUrl, { onComplete? })` | `{ iframe, destroy() }` — optional embed of INVO's hosted checkout (or just `location.href = checkoutUrl`); `onComplete` fires on the page's origin-checked `INVO_CHECKOUT_COMPLETE` message |
1023
1582
 
1024
1583
  Every method throws `InvoError` on failure and takes an optional final `{ signal }`. Full inline types ship with the package. The Platform Commerce card leg needs **no keys and no payment code in the browser** — INVO's hosted page owns the card form.