@invonetwork/web-sdk 3.3.0 → 3.6.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 CHANGED
@@ -1,9 +1,166 @@
1
1
  # Changelog
2
2
 
3
+ ## 3.6.0
4
+
5
+ ### Minor Changes
6
+
7
+ - New: `InvoClient.approveHosted({ transactionId, flow })` — web games approve on INVO's
8
+ hosted identity page. The browser is the RFC 8628 client: with the player token it already
9
+ holds, the SDK calls `POST /api/sdk/approvals/device/begin` with `channel: "popup"` (INVO
10
+ records the page's `Origin` as the popup's opener), opens the hosted page in a popup
11
+ (synchronously, inside your click handler), polls `poll` honouring `interval` and
12
+ `slow_down` (+5 s), drives the INVO-branded match-code prompt from the poll's `enrollment`
13
+ object ("Set up INVO on iPhone? Code 48-27. Say Yes only if the phone you just
14
+ scanned/opened shows this code." → `confirm-enrollment`; `confirmed` shows "Finishing on
15
+ iPhone… / Stop it, wrong code"; a 409 already-decided takes it down quietly), and when the
16
+ poll says `approved` calls the flow's approve endpoint with the `device_code` —
17
+ `transfers/{id}/approve`, `send/{id}/approve`, `send/{id}/confirm-receipt`,
18
+ `transfers/{id}/confirm-receipt`. Resolves `{ status: "approved", approval }` (the same
19
+ `ApproveResult` / `ConfirmReceiptResult` the in-app calls return) or `denied` / `expired` /
20
+ `closed` / `blocked` / `redirected`; rejects with `InvoError` when the backend refuses.
21
+ `device_code` lives in the call's closure only — never on the result, never logged. The
22
+ page's `postMessage` is a wake-up that triggers an immediate poll (accepted only from the
23
+ hosted page's https origin and only from the popup the SDK opened), never a result. A
24
+ popup blocked by the browser resolves `blocked` before anything is started (default);
25
+ `popupBlocked: "redirect"` opts in to a full-tab redirect. A page sending
26
+ `Cross-Origin-Opener-Policy: same-origin` is detected and reported as `blocked` with a
27
+ hint. Your server does nothing new; its `device_approval.approved` webhook still fires.
28
+ In-app partner-domain passkeys are unchanged and remain supported. `onEnrollment(e,
29
+ respond)` + `renderPrompt:false` let a game draw its own prompt.
30
+
31
+ Docs: new "Web games — approving on INVO's hosted page" section; the console-flow poll
32
+ example now shows `match_code`. Test-only devDependency added: `happy-dom`.
33
+
34
+ Docs (hosted identity pages, Phase 7): the console section documents `channel` on
35
+ `begin` (`qr` default | `popup` — the browser must call `begin` itself, its https `Origin`
36
+ becomes the popup's opener, server-to-server callers are refused | `app_browser` — the
37
+ mobile plugins; the return scheme `invo-sdk-<game_id>` is derived server-side), the echoed
38
+ `channel` on the begin body, `recovery` on the poll's `enrollment` object, the hosted
39
+ passkey-recovery flow (screen confirm + emailed single-use link → old INVO passkeys
40
+ deactivated, `identity.passkey_reset` webhook, 24-hour `PASSKEY_RECOVERY_COOLDOWN` on
41
+ money out; receiving unaffected), the mobile auto-confirm note (`app_browser` enrolment is
42
+ confirmed by INVO, no prompt), and `ENROLLMENT_REQUIRES_PROOF` on the page. Sends &
43
+ transfers: guardian approval now goes by email first (`consent_channel` and
44
+ `resend_endpoint` on the raw 202 `guardian_approval` block; `decision_source: "email_link"`),
45
+ the once-per-approval `POST /api/sdk/approvals/guardian/{approvalId}/resend` `{channel:"sms"}`
46
+ contract (initiator's token; 403/409/410/503 codes), and phone-share / recipient-identity
47
+ consents on the same hosted page (unchanged 409 / 202 codes, `consent_channel` on the
48
+ phone-share body). Passkeys: the partner-domain freeze — new titles have nothing to verify
49
+ (`409 PARTNER_RP_FROZEN`; `WEBAUTHN_NOT_ENABLED_FOR_TENANT` is the expected state, use
50
+ `approveHosted`), tenants with a domain verified before the freeze keep it, removal is
51
+ irreversible. The "SMS first, then email" fallback sentence corrected to "email first, SMS
52
+ on request". Documentation only.
53
+
54
+ ### Patch Changes
55
+
56
+ - Docs: the device-approval page (RFC 8628, consoles / TVs / native Steam and desktop
57
+ clients) now enrols the player's INVO passkey on the **first** scan, and the proof is the
58
+ game screen: the phone says "confirm on your game screen", the game shows "Set up INVO on
59
+ this phone: iPhone?", the player presses Yes on the console, and the phone's biometric
60
+ creates the passkey and approves — no code to type, no SMS; every later scan is scan,
61
+ biometric, done. The "the player needs an INVO passkey" bullet is replaced accordingly.
62
+ Documents the two integrator-facing additions: the `enrollment` object
63
+ (`state` / `device_label` / `requested_at`) on the `authorization_pending` poll body while
64
+ a phone is waiting, and `POST /api/sdk/approvals/device/confirm-enrollment`
65
+ (`{device_code, decision: "approve" | "deny"}`, same auth as begin/poll; deny ends the
66
+ grant with `access_denied`), plus the backup email. Also documents two backend
67
+ behaviours: `begin` extends the transaction's own approval window past the code's expiry
68
+ (`transfer` / `send`), and `begin` may be called again for the same transaction once an
69
+ approved code's window has passed. Documentation only — no code or type changes; the
70
+ `begin`/`poll` endpoints, the `device_approval.approved` webhook and its `method` value
71
+ are unchanged.
72
+
73
+ Also on the send side: the claim SMS now carries a link to a hosted INVO claim page where
74
+ a recipient without the game collects with one email + an emailed code + their phone's
75
+ passkey (in-game claim unchanged; `transfer.received` fires the same); documents the
76
+ sender-token REST call `POST /api/sdk/send/{transactionId}/resend-claim` (30-second
77
+ cooldown, 10 per transaction per hour — no SDK method); and that an uncollected send is
78
+ still refunded at 24 hours but the sender is now emailed and the recipient texted, with
79
+ `transfer.claim_expired` / `transfer.refunded` as the source of truth. The `transfer.*`
80
+ rows were added to the event-types table.
81
+
82
+ - df2efe9: Docs: add an explicit per-platform verification/approval recommendation. The
83
+ "gold standard" section now spells out which method fits which client — a passkey
84
+ directly on mobile app/web and desktop web, and the QR device-approval flow
85
+ (RFC 8628) on consoles **and** on native Steam / desktop game clients (Mac &
86
+ Windows), where it is the embedded game client, not the OS, that can't invoke the
87
+ platform authenticator. Also documents the SMS-first-then-email fallback for
88
+ remote approvals with no passkey path. Documentation only — no code or type
89
+ changes; the `VerificationMethod` union and the device-approval REST flow are
90
+ unchanged.
91
+
3
92
  All notable changes to `@invonetwork/web-sdk` are documented here. This project follows
4
93
  [Semantic Versioning](https://semver.org/). Releases are managed with
5
94
  [changesets](https://github.com/changesets/changesets).
6
95
 
96
+ ## [3.5.0] - 2026-09-01
97
+
98
+ **The Steam purchase flow is now first-class SDK surface: `steamPacks()`, `steamInitPurchase()`, `steamFinalizePurchase()`** — plus browser-based checkout for platforms where the Steam overlay does not render, a finalize-poller error taxonomy, and webhook `channel` typing. No breaking changes.
99
+
100
+ Until now the SDK only _steered away_ from Steam (`purchaseCurrency` fails fast on `rail: "steam"`); the dedicated endpoints had to be called by hand. All three are typed methods now, and the fail-fast message names them.
101
+
102
+ ### Added
103
+
104
+ - **`InvoServer.steamPacks(query?)`** — the pack catalogue. `currencyAmount` is per-player (VAT and the storefront's revenue share come out of the sticker before currency is derived — a $4.99 pack yields 34, not 50, units at $1 = 10). Render it verbatim; never compute currency from price and never cache one answer for all players.
105
+ - **`InvoServer.steamInitPurchase(input)`** — start the purchase. Idempotent on `purchaseReference` (retries, including manual retries after a 409, MUST reuse it). New authorization modes:
106
+ - `usersession: "client"` (default, unchanged): Steam overlay in-game. The SDK sends **no** `usersession` key at all in this mode, pinned by test, so existing behaviour cannot shift.
107
+ - `usersession: "web"`: for platforms where the overlay does not render (observed: Electron on macOS). Requires `playerIp` — the PLAYER's address, never your server's; refused client-side before the network without it. Returns `steamCheckoutUrl`: Steam's own hosted approval page, which must open as a **top-level tab** (it cannot be iframed). _Note: Steam's sandbox issues checkout URLs its production host will not serve, so web-session approval is provable only against production; the rest of the flow is identical to client-session._
108
+ - `metadata` — echoed on the `purchase.completed` webhook (`data.metadata`) — the way to correlate your own player/order ids. The Steam rail merges its own context keys (`steam_wallet_currency`, `steam_country`, `steam_account_status`, `vat_rate_pct`) into the echoed object; avoid those names in yours.
109
+ - **`InvoServer.steamFinalizePurchase({orderId})`** — capture + credit. Idempotent: a replay returns `alreadyProcessed: true` and never credits twice.
110
+ - **Finalize poller taxonomy on `InvoError`** — because _not every 409 means "not yet"_, and a poller that assumes so polls a dead order forever:
111
+ - `isSteamAuthorizationPending` — player has not approved yet (Steam reports `Init`). The normal wait state; poll again.
112
+ - `isSteamAuthorizationDead` — any settled status — `Cancelled`, `Failed`, `Refunded`, `Chargedback`, and every other non-Init outcome (pending is the CLOSED set: only `Init` means "not yet"). Stop; no later call can succeed.
113
+ - The two are mutually exclusive by construction, and a test pins that they can never both answer true.
114
+ - **`InvoError.isPartnerCreditUnavailable`** (`PARTNER_CREDIT_UNAVAILABLE`, 409) — the studio's settlement float cannot cover the purchase. Structure is fine; the money is not. Plain failure toast; do **not** hot-poll init (each attempt briefly re-reserves headroom), and reuse the same `purchaseReference` on manual retry.
115
+ - **`InvoError.isPartnerRailSuspended`** (`PARTNER_RAIL_SUSPENDED`, 409) — terminal from the game's seat. The umbrella `isPartnerSettlementUnavailable` still covers both.
116
+ - **`InvoError.isUnknownSteamPack`** (400) — re-fetch `steamPacks()`; the body's `valid_pack_ids` lists what exists.
117
+ - **`InvoError.isMissingPlayerIp`** (400) — always an integration bug on web sessions.
118
+ - **`PurchaseCompletedData.channel`** — which storefront the purchase came from (`"steam"` / `"ios"` / `"android"` / `"web"` / `"console"`), beside `rail`. `null` means a legacy game key: a real answer ("unattributed"), read it as one.
119
+
120
+ ### Changed
121
+
122
+ - `purchaseCurrency`'s `rail: "steam"` fail-fast message now names the real methods instead of vaguely citing "dedicated endpoints".
123
+
124
+ ## [3.4.0] - 2026-09-01
125
+
126
+ **A Steam title now bills through its OWN Steam application.** New error helpers;
127
+ no breaking changes to any existing method or type.
128
+
129
+ ### Why this is a real change and not a doc tidy
130
+
131
+ Steam pays whoever owns the Steam application. Until now, INVO documented a
132
+ single INVO-owned Steam app that billed every title on the network — so a studio
133
+ had nothing to register and the money reached them through INVO. That model is
134
+ gone. Each title sells through the studio's own Steam app, the money lands in
135
+ their own Steamworks account, and INVO issues the player's currency immediately
136
+ and settles with the studio afterwards against a payment method on file.
137
+
138
+ If you shipped against 3.3.0 or earlier and your Steam integration works today,
139
+ nothing in your code needs to change. What changes is the **studio's** one-time
140
+ setup, and the errors you may now see if they have not done it.
141
+
142
+ ### Added
143
+
144
+ - `InvoError.isSteamNotConfigured` — the title has no Steam application
145
+ registered with INVO yet (`STEAM_NOT_CONFIGURED`, 503).
146
+ - `InvoError.isPartnerBillingNotSetUp` — the studio has not finished INVO billing
147
+ setup (`PARTNER_BILLING_NOT_SET_UP`, 409).
148
+ - `InvoError.isPartnerSettlementUnavailable` — settlement suspended or over
149
+ limit (`PARTNER_RAIL_SUSPENDED` / `PARTNER_CREDIT_UNAVAILABLE`, 409). Show a
150
+ neutral "purchases are unavailable right now": it is not the player's problem.
151
+ - `InvoError.isSteamAppChanged` — the order was started against a different
152
+ Steam application than the title is configured for now (`STEAM_APP_CHANGED`,
153
+ 409). Only reachable if a studio swaps apps mid-flight.
154
+
155
+ All four are refused **before the player is charged**, which is the point.
156
+
157
+ ### Changed
158
+
159
+ - README: the Steam section now documents the studio's Steamworks setup
160
+ (microtransactions enabled, a publisher-GROUP Web API key that includes the
161
+ app, appid + key entered in the INVO dashboard, payment method on file).
162
+ - README: removed the claim that no Steam-side registration was required.
163
+
7
164
  ## [3.3.0] - 2026-08-31
8
165
 
9
166
  **Documentation only. No code changes, no API changes.**
@@ -17,14 +174,14 @@ client library understands the responses.
17
174
  player approves on their phone; your **server** polls
18
175
  `POST /api/sdk/approvals/device/poll` until it hears back.
19
176
  - **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
177
+ which authorises a _client_, an INVO device code is bound to the transaction
21
178
  you named and is consumed when used — it cannot approve anything else and
22
179
  cannot be reused.
23
180
  - `user_code` is meant to be seen; `device_code` is not. Poll from your backend.
24
181
  - Subscribe to `device_approval.approved` to learn the moment an approval lands
25
182
  instead of waiting for the next poll. Polling still works alone.
26
183
  - 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
184
+ property of the _device_, not the game, so a title with a website and a
28
185
  console build uses the normal ceremony in the browser and this one on console.
29
186
  - Currency purchases on a console go through that console's store, as the
30
187
  platform holder requires; this flow is for approving transfers and sends.
@@ -41,7 +198,7 @@ the 3.2.2 Steam snippets that made them fail if copied.
41
198
  - **Base path.** The snippets said `/api/enhanced-purchase/...`. The routes are
42
199
  mounted at **`/api/currency-purchases/...`** -- `enhanced_purchase_api` is the
43
200
  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
201
+ found`, which reads like the Steam rail is unavailable rather than like a
45
202
  wrong URL.
46
203
  - **Auth header.** The snippets sent `X-Game-Secret`. The header is
47
204
  **`X-Game-Secret-Key`**, as it is everywhere else in this document. An unknown
@@ -134,9 +291,8 @@ one exists (`STRIPE_ERROR` becomes `PROCESSOR_ERROR`), and the literal wire valu
134
291
  `err.rawCode` for anyone already matching it. Refund reads prefer
135
292
  `processor_refund_reference` over the vendor-named field, with a fallback.
136
293
 
137
-
138
294
  **Storefront keys are still server-side keys.** A storefront key names where the
139
- *purchase* came from, not where the key lives. It belongs in your backend exactly like
295
+ _purchase_ came from, not where the key lives. It belongs in your backend exactly like
140
296
  your original key -- never in a game client, an app bundle, or browser code.
141
297
 
142
298
  ## [3.1.0] — 2026-08-04
@@ -152,6 +308,7 @@ verification options; they are not, and the docs said so in a way that produced
152
308
  integrations.
153
309
 
154
310
  ### Added — error-contract classifiers
311
+
155
312
  Three 403s that previously arrived as a generic `InvoError` (correct `status`/`code`/`message`,
156
313
  but no typed branch) now have classifiers:
157
314
 
@@ -171,6 +328,7 @@ Note the backend splits field names across these: the `*_GAME_NOT_LIVE` pair use
171
328
  already read both, so `err.code` is populated either way — the new tests pin both shapes.
172
329
 
173
330
  ### Clarified — the SDK does not, and did not, collapse non-2xx into transport errors
331
+
174
332
  Following a report of a `403` being debugged as a network outage: verified end-to-end that a
175
333
  non-2xx always surfaces with its real `status`, `code`, and `message`, and that `status: 0` is
176
334
  reserved for a genuine absence of an HTTP response. **No fix was needed in the SDK** — the loss
@@ -180,36 +338,40 @@ anti-pattern and the correct handler, and a note that `409` is a retryable not-r
180
338
  rather than a failure.
181
339
 
182
340
  ### Deprecated
341
+
183
342
  - **`InvoServer.verifySmsTransfer` / `InvoServer.verifySmsSend`** — marked `@deprecated`. They
184
343
  still work exactly as before and still hit the same endpoints. A **future major version will
185
344
  remove them**; no date is committed yet. Keep them only as a genuine last resort for users who
186
345
  cannot enroll a passkey (unsupported device, no platform authenticator) or who decline.
187
346
  **Migration:** when `initiateSend`/`initiateTransfer` returns `verificationMethod: "sms"`, read
188
- it as *"this sender has no passkey"* — prompt `InvoClient.enrollPasskey()` and then
347
+ it as _"this sender has no passkey"_ — prompt `InvoClient.enrollPasskey()` and then
189
348
  `InvoClient.approveSend` / `approveTransfer`, instead of routing to a PIN pad.
190
349
 
191
350
  ### Changed (documentation only)
351
+
192
352
  - New README section — **"Passkeys are the gold standard — don't build on SMS"** — with the
193
353
  do/don't table, the deprecation notice, and an explicit list of the OTP surfaces that are
194
354
  **not** discouraged.
195
355
  - `VerificationMethod`, `InitiateResult.verificationMethod` and `SmsVerifyResult` doc comments
196
356
  reframed: `"in_app"` and `"sms"` are no longer presented as peer options.
197
- - "Before you go live" now stresses configuring RP ID / origins *before* launch, since an
357
+ - "Before you go live" now stresses configuring RP ID / origins _before_ launch, since an
198
358
  unconfigured tenant silently drops every sender onto the deprecated path.
199
359
  - **New "Prerequisite: passkeys are dark until your tenant verifies a domain" subsection.**
200
360
  Recommending passkeys without saying what unlocks them would send developers straight into a
201
361
  `403` on their first `enrollPasskey()` call — with 0/3 prod tenants configured, that is
202
- currently *everyone*. The deprecation carries no removal date for the same reason.
362
+ currently _everyone_. The deprecation carries no removal date for the same reason.
203
363
  - Stability section corrected — it still claimed `2.0.0` was the only major, which `3.0.0`
204
364
  made false.
205
365
  - Design doc: `docs/features/passkey-first-authentication.md`.
206
366
 
207
367
  ### Not affected — still recommended
368
+
208
369
  `enrollmentBegin`/`enrollmentVerify`, `recoveryBegin`/`recoveryComplete`, and
209
- `phoneShareInitiate`/`phoneShareApprove` all involve a one-time code but are the on-ramp *to* a
370
+ `phoneShareInitiate`/`phoneShareApprove` all involve a one-time code but are the on-ramp _to_ a
210
371
  passkey (or phone-ownership consent), not a substitute for one. They are **not** deprecated.
211
372
 
212
373
  ### Upgrade note
374
+
213
375
  The only way this release can surface in a pipeline is a lint rule that treats `@deprecated`
214
376
  usage as an error (e.g. `deprecation/deprecation` with `--max-warnings 0`). That is a lint-level
215
377
  signal, not a build or runtime break, and it is the intended notice.
@@ -224,6 +386,7 @@ on the `platform_commerce.purchased` webhook. Note: the card leg is pending fina
224
386
  the backend (sandbox payment test) — the balance leg is fully live.
225
387
 
226
388
  ### Migration from 2.5.x (card leg only — balance/status/refund/webhooks unchanged)
389
+
227
390
  - `platformCommerce.purchase({ fundingSource: "card" })`: **remove `billingAddress`** (the type
228
391
  is gone; the hosted page collects it) and optionally pass `successUrl` / `cancelUrl` /
229
392
  `metadata`. The result now carries `checkoutUrl` / `sessionId` / `expiresAt` (unix seconds) /
@@ -237,6 +400,7 @@ the backend (sandbox payment test) — the balance leg is fully live.
237
400
  the same checkout session** (`idempotentReplay: true`), so a lost response is recoverable.
238
401
 
239
402
  ### Added
403
+
240
404
  - `PlatformPurchaseInput.successUrl/cancelUrl/metadata`; result fields
241
405
  `sessionId/checkoutUrl/expiresAt/idempotentReplay`.
242
406
  - `InvoClient.platformCommerce.mountCheckout(el, checkoutUrl, opts)` → `{ iframe, destroy() }`.
@@ -245,6 +409,7 @@ the backend (sandbox payment test) — the balance leg is fully live.
245
409
  - Card `requires_payment` responses without a `checkout_url` fail closed (`INVALID_RESPONSE`).
246
410
 
247
411
  ### Removed
412
+
248
413
  - `confirmCardPayment`, `mountCardPayment`, `commercePublishableKey`, `BillingAddress`, and the
249
414
  card-element/processor types + the runtime CDN script loader (no more processor touchpoints
250
415
  in this SDK at all).
@@ -255,6 +420,7 @@ Hardening patch from a second, independent post-release audit (correctness vs th
255
420
  blueprint + security red-team) of the 2.5.0 Platform Commerce feature. No API breaks.
256
421
 
257
422
  ### Fixed
423
+
258
424
  - **Card-confirm script loader could hang forever on retry.** After a transient CDN failure
259
425
  (or a pre-existing processor `<script>` tag whose events already fired), the next
260
426
  `mountCardPayment`/`confirmCardPayment` attached listeners to a dead tag and never settled —
@@ -280,6 +446,7 @@ blueprint + security red-team) of the 2.5.0 Platform Commerce feature. No API br
280
446
  (`{status,error_code,message}` / bare `{message}`), not idealized shapes.
281
447
 
282
448
  ### Docs
449
+
283
450
  - Card-leg lost-response caveat on `purchase` (duplicate 409 can strand a `clientSecret`-less
284
451
  pending order — reconcile via webhook/`getStatus`, retry with a NEW `clientRequestId`).
285
452
  - `confirmCardPayment`: bank-redirect return-leg guidance + remount-after-decline note;
@@ -290,7 +457,7 @@ blueprint + security red-team) of the 2.5.0 Platform Commerce feature. No API br
290
457
  **Platform Commerce (ecommerce).** A new flow for **platform** tenants (non-game apps: vertical
291
458
  video, creator merch, marketplace) to sell items funded by **INVO balance or a real card**, with
292
459
  INVO as merchant of record and full refunds. This is **distinct from item purchase** — that is a
293
- *game* tenant spending a player's *existing game currency* on an *in-game* item (balance only, no
460
+ _game_ tenant spending a player's _existing game currency_ on an _in-game_ item (balance only, no
294
461
  card, no refund). Additive; only platform tenants can call it (a game tenant gets `403
295
462
  NOT_A_PLATFORM_TENANT`). (Backend handoff: BE-PIP-009 `PLATFORM_COMMERCE_SDK.md`.)
296
463
 
@@ -305,7 +472,7 @@ NOT_A_PLATFORM_TENANT`). (Backend handoff: BE-PIP-009 `PLATFORM_COMMERCE_SDK.md`
305
472
  - **Browser** (`InvoClient.platformCommerce`):
306
473
  - `confirmCardPayment(clientSecret, { mount, publishableKey?, returnUrl?, submit? })` — mounts
307
474
  the card element and confirms; returns `{ status: "succeeded" | "requires_action" |
308
- "processing" | "failed" }`. The processor JS is **lazy-loaded from its CDN — no bundled
475
+ "processing" | "failed" }`. The processor JS is **lazy-loaded from its CDN — no bundled
309
476
  dependency**; pass its publishable key (or set `commercePublishableKey` on the client config).
310
477
  - `mountCardPayment(clientSecret, opts)` — the primitive: `{ element, confirm(), destroy() }`
311
478
  to confirm from your own Pay button.