@invonetwork/web-sdk 3.1.0 → 3.2.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,570 +1,610 @@
1
- # Changelog
2
-
3
- All notable changes to `@invonetwork/web-sdk` are documented here. This project follows
4
- [Semantic Versioning](https://semver.org/). Releases are managed with
5
- [changesets](https://github.com/changesets/changesets).
6
-
7
- ## [3.1.0] — 2026-08-04
8
-
9
- **Passkeys are the gold standard; the SMS-PIN path is deprecated.** This release makes INVO's
10
- authentication guidance explicit in the two places developers actually look — the README and IDE
11
- autocomplete. **No behavior changes, no API removals, no runtime warnings.** Upgrading and
12
- changing nothing produces byte-identical runtime behavior.
13
-
14
- A passkey is a phishing-resistant, origin-bound WebAuthn assertion. An SMS PIN is a shared secret
15
- on a channel exposed to SIM swap and interception. They were documented as interchangeable
16
- verification options; they are not, and the docs said so in a way that produced PIN-first
17
- integrations.
18
-
19
- ### Added — error-contract classifiers
20
- Three 403s that previously arrived as a generic `InvoError` (correct `status`/`code`/`message`,
21
- but no typed branch) now have classifiers:
22
-
23
- - **`err.isSourceGameNotLive`** — the caller's OWN game is in testing. Self-serve: switch it to
24
- Live in the console (Game Settings → Status).
25
- - **`err.isTargetGameNotLive`** — the DESTINATION game is in testing. Usually another
26
- developer's game, so the caller **cannot** fix it. **Deliberately distinct** from the source
27
- case: collapsing them into one "not live" branch yields a "go fix it" CTA that dead-ends half
28
- the time.
29
- - **`err.gameStatus`** — the `game_status` field from either refusal (e.g. `"testing"`).
30
- - **`err.isWebauthnNotEnabledForTenant`** — tenant has no verified WebAuthn RP ID. **This is
31
- configuration state, not a failure**: fall back to the SMS/in-app path instead of surfacing an
32
- error. Currently the common case — 4/23 sandbox and **0/3 production** tenants are configured.
33
-
34
- Note the backend splits field names across these: the `*_GAME_NOT_LIVE` pair uses
35
- `error_code`/`message`, while `WEBAUTHN_NOT_ENABLED_FOR_TENANT` uses `code`/`error`. The SDK
36
- already read both, so `err.code` is populated either way — the new tests pin both shapes.
37
-
38
- ### Clarified — the SDK does not, and did not, collapse non-2xx into transport errors
39
- Following a report of a `403` being debugged as a network outage: verified end-to-end that a
40
- non-2xx always surfaces with its real `status`, `code`, and `message`, and that `status: 0` is
41
- reserved for a genuine absence of an HTTP response. **No fix was needed in the SDK** — the loss
42
- happened in an integration-layer catch-all. Added regression tests pinning the behavior, plus a
43
- README section (**"`.status === 0` means 'no HTTP response' — and nothing else"**) showing the
44
- anti-pattern and the correct handler, and a note that `409` is a retryable not-ready state
45
- rather than a failure.
46
-
47
- ### Deprecated
48
- - **`InvoServer.verifySmsTransfer` / `InvoServer.verifySmsSend`** — marked `@deprecated`. They
49
- still work exactly as before and still hit the same endpoints. A **future major version will
50
- remove them**; no date is committed yet. Keep them only as a genuine last resort for users who
51
- cannot enroll a passkey (unsupported device, no platform authenticator) or who decline.
52
- **Migration:** when `initiateSend`/`initiateTransfer` returns `verificationMethod: "sms"`, read
53
- it as *"this sender has no passkey"* — prompt `InvoClient.enrollPasskey()` and then
54
- `InvoClient.approveSend` / `approveTransfer`, instead of routing to a PIN pad.
55
-
56
- ### Changed (documentation only)
57
- - New README section — **"Passkeys are the gold standard — don't build on SMS"** — with the
58
- do/don't table, the deprecation notice, and an explicit list of the OTP surfaces that are
59
- **not** discouraged.
60
- - `VerificationMethod`, `InitiateResult.verificationMethod` and `SmsVerifyResult` doc comments
61
- reframed: `"in_app"` and `"sms"` are no longer presented as peer options.
62
- - "Before you go live" now stresses configuring RP ID / origins *before* launch, since an
63
- unconfigured tenant silently drops every sender onto the deprecated path.
64
- - **New "Prerequisite: passkeys are dark until your tenant verifies a domain" subsection.**
65
- Recommending passkeys without saying what unlocks them would send developers straight into a
66
- `403` on their first `enrollPasskey()` call — with 0/3 prod tenants configured, that is
67
- currently *everyone*. The deprecation carries no removal date for the same reason.
68
- - Stability section corrected — it still claimed `2.0.0` was the only major, which `3.0.0`
69
- made false.
70
- - Design doc: `docs/features/passkey-first-authentication.md`.
71
-
72
- ### Not affected — still recommended
73
- `enrollmentBegin`/`enrollmentVerify`, `recoveryBegin`/`recoveryComplete`, and
74
- `phoneShareInitiate`/`phoneShareApprove` all involve a one-time code but are the on-ramp *to* a
75
- passkey (or phone-ownership consent), not a substitute for one. They are **not** deprecated.
76
-
77
- ### Upgrade note
78
- The only way this release can surface in a pipeline is a lint rule that treats `@deprecated`
79
- usage as an error (e.g. `deprecation/deprecation` with `--max-warnings 0`). That is a lint-level
80
- signal, not a build or runtime break, and it is the intended notice.
81
-
82
- ## [3.0.0] — 2026-07-20
83
-
84
- **BREAKING — the Platform Commerce card leg moved to INVO's hosted checkout.** The backend now
85
- hosts the entire card flow (card fields, Apple Pay / Google Pay, billing-address collection,
86
- 3-D Secure) on its own checkout page, so the browser card-element surface shipped in 2.5.x is
87
- gone. Card sales are simpler AND safer: server creates → buyer pays on `checkoutUrl` → fulfill
88
- on the `platform_commerce.purchased` webhook. Note: the card leg is pending final enablement on
89
- the backend (sandbox payment test) — the balance leg is fully live.
90
-
91
- ### Migration from 2.5.x (card leg only — balance/status/refund/webhooks unchanged)
92
- - `platformCommerce.purchase({ fundingSource: "card" })`: **remove `billingAddress`** (the type
93
- is gone; the hosted page collects it) and optionally pass `successUrl` / `cancelUrl` /
94
- `metadata`. The result now carries `checkoutUrl` / `sessionId` / `expiresAt` (unix seconds) /
95
- `idempotentReplay` — **`clientSecret` no longer exists.**
96
- - Browser: **`confirmCardPayment` and `mountCardPayment` are removed** (with all card-element
97
- types and the `commercePublishableKey` config). Replace with a redirect
98
- (`location.href = checkoutUrl`) or the new optional embed:
99
- `invo.platformCommerce.mountCheckout(el, checkoutUrl, { onComplete })` — an iframe plus an
100
- origin-checked listener for the page's `INVO_CHECKOUT_COMPLETE` message.
101
- - Card duplicates no longer 409: retrying `purchase` with the same `clientRequestId` **replays
102
- the same checkout session** (`idempotentReplay: true`), so a lost response is recoverable.
103
-
104
- ### Added
105
- - `PlatformPurchaseInput.successUrl/cancelUrl/metadata`; result fields
106
- `sessionId/checkoutUrl/expiresAt/idempotentReplay`.
107
- - `InvoClient.platformCommerce.mountCheckout(el, checkoutUrl, opts)` → `{ iframe, destroy() }`.
108
- - `err.isAboveCardMaximum` (`ABOVE_CARD_MAXIMUM`, card > $999.99) + client-side card USD
109
- bounds fail-fast ($0.50–$999.99).
110
- - Card `requires_payment` responses without a `checkout_url` fail closed (`INVALID_RESPONSE`).
111
-
112
- ### Removed
113
- - `confirmCardPayment`, `mountCardPayment`, `commercePublishableKey`, `BillingAddress`, and the
114
- card-element/processor types + the runtime CDN script loader (no more processor touchpoints
115
- in this SDK at all).
116
-
117
- ## [2.5.1] — 2026-07-20
118
-
119
- Hardening patch from a second, independent post-release audit (correctness vs the backend
120
- blueprint + security red-team) of the 2.5.0 Platform Commerce feature. No API breaks.
121
-
122
- ### Fixed
123
- - **Card-confirm script loader could hang forever on retry.** After a transient CDN failure
124
- (or a pre-existing processor `<script>` tag whose events already fired), the next
125
- `mountCardPayment`/`confirmCardPayment` attached listeners to a dead tag and never settled —
126
- checkout silently dead until page reload. The loader now removes failed tags and polls
127
- (bounded, 10s) when a tag pre-exists.
128
- - **Orphaned card element on submit-lookup failure.** `confirmCardPayment` now destroys the
129
- mounted Payment Element before rethrowing when the `submit` selector can't be resolved
130
- (previously a retry stacked a second live card iframe).
131
- - **Billing-address validation errors no longer echo the submitted values** (cardholder PII
132
- could otherwise land in logs/Sentry); optional billing fields (`name`/`line2`/`state`) are
133
- now type-checked.
134
- - **`playerPhone` on `platformCommerce.purchase` is now E.164-validated** — this endpoint can
135
- create the player identity, so a national-format phone must never reach the wire.
136
- - **`err.isInsufficientBalance` now also classifies the zero-balance 400** ("Player has no
137
- balance in this tenant", which carries only `current_balance`).
138
- - **Breaker-open 503 keeps its human message** (`err.code === "service_unavailable"`, message
139
- no longer collapses to the bare token).
140
- - **Webhook types:** `platform_commerce.refunded` `player_email` is nullable + `identity_id`
141
- added; (2.5.0 already made card-leg `total_price` optional on `purchased`).
142
- - **Refund result surfaces `newBalance`** (balance leg) **and `processorRefundId`** (card leg)
143
- instead of leaving them `raw`-only.
144
- - Platform-commerce error tests now assert the REAL backend envelopes
145
- (`{status,error_code,message}` / bare `{message}`), not idealized shapes.
146
-
147
- ### Docs
148
- - Card-leg lost-response caveat on `purchase` (duplicate 409 can strand a `clientSecret`-less
149
- pending order — reconcile via webhook/`getStatus`, retry with a NEW `clientRequestId`).
150
- - `confirmCardPayment`: bank-redirect return-leg guidance + remount-after-decline note;
151
- `CardPaymentResult.raw` log-redaction note.
152
-
153
- ## [2.5.0] — 2026-07-20
154
-
155
- **Platform Commerce (ecommerce).** A new flow for **platform** tenants (non-game apps: vertical
156
- video, creator merch, marketplace) to sell items funded by **INVO balance or a real card**, with
157
- INVO as merchant of record and full refunds. This is **distinct from item purchase** — that is a
158
- *game* tenant spending a player's *existing game currency* on an *in-game* item (balance only, no
159
- card, no refund). Additive; only platform tenants can call it (a game tenant gets `403
160
- NOT_A_PLATFORM_TENANT`). (Backend handoff: BE-PIP-009 `PLATFORM_COMMERCE_SDK.md`.)
161
-
162
- - **Server** (`InvoServer.platformCommerce`, mirrored in the Python SDK as
163
- `server.platform_commerce`):
164
- - `purchase(input)` — `fundingSource: "balance"` settles synchronously (`status:"success"`);
165
- `"card"` returns `status:"requires_payment"` + a `clientSecret` and **requires a
166
- `billingAddress`**. Idempotent on `clientRequestId`.
167
- - `getStatus(orderId)` — `completed` | `pending_payment` | `refunded`.
168
- - `refund({ orderId | clientRequestId, reason? })` — INVO retains its fee; a second refund
169
- throws `409` (`err.isAlreadyRefunded`).
170
- - **Browser** (`InvoClient.platformCommerce`):
171
- - `confirmCardPayment(clientSecret, { mount, publishableKey?, returnUrl?, submit? })` — mounts
172
- the card element and confirms; returns `{ status: "succeeded" | "requires_action" |
173
- "processing" | "failed" }`. The processor JS is **lazy-loaded from its CDN — no bundled
174
- dependency**; pass its publishable key (or set `commercePublishableKey` on the client config).
175
- - `mountCardPayment(clientSecret, opts)` — the primitive: `{ element, confirm(), destroy() }`
176
- to confirm from your own Pay button.
177
- - **Webhooks:** new typed `platform_commerce.purchased` / `platform_commerce.refunded` events.
178
- **Fulfill card orders on `platform_commerce.purchased`, never on the browser confirmation.**
179
- - **New `InvoError` classifiers:** `isNotPlatformTenant` (403), `isAmountBelowMinimum`,
180
- `isBelowCardMinimum` (card < $0.50), `isAlreadyRefunded` (409).
181
- - Docs: README now leads the flow list with an explicit **item purchase vs Platform Commerce**
182
- contrast; new "Platform Commerce (ecommerce)" section.
183
-
184
- ## [2.4.1] — 2026-07-10
185
-
186
- Docs only, no code change — corrects stale README prose that the 2.4.0 publish still carried:
187
- the status line led with an old version, and the Stability section still cited the `2.0.0`
188
- `playerPhone` requirement as the standing breaking change (2.2.0 relaxed it back to optional).
189
- Republished so the package-bundled README is accurate.
190
-
191
- ## [2.4.0] — 2026-07-10
192
-
193
- **Steam transfer policy.** Steam-purchased currency is locked to Steam titles; the backend now
194
- enforces this at transfer/send initiate and annotates destinations. Additive, and inert until a
195
- title is flagged Steam-distributed. (Design doc: `docs/features/steam-transfer-policy.md`.)
196
-
197
- - New `InvoError` classifiers on `initiateSend`/`initiateTransfer` 409s:
198
- `isSteamValueNonTransferable` (with `steamTransferableMax` / `steamOriginAmount` — decimal
199
- strings) and `isNonSteamValueIntoSteamBlocked`. Surface `err.message` verbatim.
200
- - New `DestinationGame.acceptsSteamOriginValue` (maps `accepts_steam_origin_value`; `false` when
201
- omitted) — disable non-Steam destinations for a player holding Steam value so they never hit
202
- the 409.
203
-
204
- No breaking changes.
205
-
206
- ## [2.3.0] — 2026-07-07
207
-
208
- **Claim-time phone-share approval.** The backend closed a security gap: claiming/collecting a
209
- phone-routed transfer now authorizes the collecting identity against the receiver phone before
210
- crediting. So `confirmReceiptSend`/`confirmReceiptTransfer` and `claimTransfer`/`claimCurrency`
211
- can now return the phone-share `409 PHONE_SHARE_APPROVAL_REQUIRED` (previously only
212
- registration/mint did). The existing `InvoError.isPhoneShareApprovalRequired` already classifies
213
- it — no consumer code must change — but:
214
-
215
- - New **`InvoError.phoneShareLast4`** surfaces the `phone_last4` from the 409 body for the UI
216
- ("we texted the phone ending 1234").
217
- - `isPhoneShareApprovalRequired` docs + the `confirmReceipt*`/claim method docs + README now
218
- spell out the claim-time path: it's **not a failure** — the funds are held and the phone owner
219
- is texted; show `err.message` verbatim, then **retry the same call** once approved (it succeeds
220
- idempotently); on denial/expiry the sender is refunded.
221
-
222
- Additive, no breaking changes; affects all rails' claim paths (transfer, currency send, amazon).
223
-
224
- ## [2.2.0] — 2026-07-07
225
-
226
- **Backend reconciliation** — a full audit of the SDK against the live backend surfaced three
227
- places the SDK didn't match reality. All changes are backward-compatible (relaxing required
228
- inputs / adding surface); no working call breaks.
229
-
230
- - **`mintPlayerToken` no longer requires `playerPhone`.** `/api/sdk/player-token` is a
231
- session-token mint for an **existing** player (looked up by email) — not a registration call.
232
- It reads only `player_email` and ignores `player_phone`. The 2.0.0 hard E.164 requirement was
233
- a bug: it could **block a valid token mint for an existing email-only player**. `playerPhone`
234
- is now optional and validated only if provided. Phone stays enforced where it matters — the
235
- sender's phone on `initiateSend`/`initiateTransfer`, and at player creation.
236
- - **Send by phone alone.** `receiverPlayerEmail` (send) and `targetPlayerEmail` (transfer) are
237
- now **optional** — you can send to a recipient's phone; they supply their email at claim
238
- (claim still requires it, since that's where the recipient establishes identity).
239
- - **`getPlayerBalance` is by email only.** There is no by-`playerId` balance route on the
240
- backend, so passing `playerId` threw a confusing 404. It now throws a clear `INVALID_INPUT`
241
- pointing you to `InvoClient.getBalance()` (client-side) or `playerEmail` (server-side).
242
- - **New `InvoError.isUserVerificationRequired`** for the `WEBAUTHN_UV_REQUIRED` (401) approve
243
- failure — re-run the passkey ceremony requiring UV.
244
- - Fixed `iterateItemPurchaseHistory` to read the backend's `total_count` pagination key (was
245
- `total`; the loop already terminated via the short-page guard, so behavior is unchanged).
246
-
247
- **Migration:** none required. If you were passing `playerPhone` to `mintPlayerToken` it still
248
- works; you can now also omit it. Replace any `getPlayerBalance({ playerId })` with an email
249
- lookup or `InvoClient.getBalance()`.
250
-
251
- ## [2.1.2] — 2026-07-07
252
-
253
- **Hosted-checkout reconciliation** (the create-session API contract is unchanged; the hosted
254
- page was rebuilt). Additive + docs only.
255
-
256
- - `createCheckout` now surfaces `expiresInSeconds` (the `checkout_url` token TTL, e.g. 900) as
257
- a first-class field on `CreateCheckoutResult` — previously only on `.raw`.
258
- - README: the `platform` rail is described as cards + Apple Pay / Google Pay / Link +
259
- international billing (no app-store commission), and the checkout note now says reloading the
260
- URL after a completed payment is idempotent (an already-complete success screen), not an
261
- error. No API/signature changes.
262
-
263
- ## [2.1.1] — 2026-07-06
264
-
265
- **Security & correctness hardening** from a full audit + red-team of both SDKs. No API changes;
266
- upgrade recommended.
267
-
268
- - **Fail closed on HTTP redirects (security).** The transport now sends `redirect:"manual"` and
269
- throws `UNEXPECTED_REDIRECT` on any 3xx instead of following it. Previously a redirect from
270
- the API host could cause the game-secret header to be re-sent to an unvalidated URL (matches
271
- the Python SDK fix, where the leak also covered the player token and an `http://` downgrade).
272
- - **`retryAfter` no longer treats a blank `retry_after` as `0`.** An empty/whitespace
273
- `retry_after` string used to become `0` (`Number("")===0`) — an immediate, no-backoff retry.
274
- It's now correctly `undefined`, in both `InvoError.retryAfter` and the retry layer.
275
- - **Whitespace OTP codes rejected client-side.** `recoveryComplete`/`enrollmentVerify` now
276
- reject a whitespace-only `code` before the network call, so it can't burn an attempt against
277
- the attempt-capped endpoints (parity with the Python SDK).
278
- - **Webhook verify uses `crypto.timingSafeEqual`** on the sync path (parity with Python's
279
- `hmac.compare_digest`); the runtime-agnostic async/edge path keeps its string compare.
280
- - **WebAuthn option mappers fail cleanly.** A malformed `register/begin` body now throws
281
- `WEBAUTHN_OPTIONS_MALFORMED` (an `InvoError`) instead of a raw `TypeError`.
282
-
283
- ## [2.1.0] — 2026-07-02
284
-
285
- **Passkey recovery ("lost or replaced my passkey").** Deleting a passkey on the device never
286
- tells the server the key is gone, so re-enrollment was dead-ended by the anti-takeover gate
287
- (`ENROLLMENT_REQUIRES_PROOF`) with nothing left to prove possession with. The backend shipped
288
- a self-serve, possession-proofed recovery flow; this release wires the client side.
289
-
290
- - `InvoClient.recoveryBegin()` — sends a one-time code to the phone/email on file
291
- (`{ status: "sent", channels }`); `InvoClient.recoveryComplete(code)` — deactivates the
292
- stale server-side passkey and authorizes a fresh enrollment
293
- (`{ status: "recovered", deactivatedCount, next }`). Then retry the same `enrollPasskey()`.
294
- - New `InvoError` classifiers: `isEnrollmentCodeInvalid`, `isPasskeyRecoveryCooldown`, and
295
- `retryAfterAt` (the ISO timestamp on the 403 cooldown — distinct from the numeric
296
- `retryAfter` throttle field). Bare `no_channel_on_file` / `rate_limited` error tokens are
297
- now promoted to `err.code`.
298
- - **24-hour money cooldown surfaced:** a recovery-enrolled passkey logs in and collects
299
- funds immediately, but `approveSend`/`approveTransfer` throw 403
300
- `PASSKEY_RECOVERY_COOLDOWN` for 24h (SIM-swap protection). Branch on
301
- `isPasskeyRecoveryCooldown`, show the pause message with `retryAfterAt`, don't retry-loop.
302
- - README: recovery subsection under Passkeys, incl. the password-manager cleanup tip for
303
- "there is a problem saving your passkey" (stale orphan entry).
304
-
305
- Additive, no breaking changes. Routes require SDK verification enabled for the tenant
306
- (dark 503 otherwise).
307
-
308
- ## [2.0.0] — 2026-07-02
309
-
310
- **BREAKING — `mintPlayerToken` now requires `playerPhone` (E.164).** Requested by the INVO
311
- backend after a live incident: a player registered email-only couldn't receive a cross-game
312
- transfer (incoming transfers are matched by phone) and never got the account-linking consent
313
- SMS (also phone-triggered). The network identity is derived from **email + phone together**,
314
- so the phone must be present on the FIRST registration call — attaching it later changes the
315
- identity and forces device re-enrollment.
316
-
317
- - `mintPlayerToken({ playerEmail, playerPhone })` — `playerPhone` is required and validated
318
- as E.164 (`+15555550100`: leading `+`, country code, digits only) before any network call;
319
- the body now posts `player_phone` alongside `player_email`.
320
- - **Pending approval is surfaced, not an error to swallow:** minting with a phone that
321
- already belongs to another INVO account (same person, new email) throws the existing
322
- `isPhoneShareApprovalRequired` 409 — the phone holder got a consent SMS. New
323
- `InvoError.phoneShareApprovalId` exposes the `approval_id` from the 409 body for the
324
- `phoneShareApprove` OTP fallback. Docs updated to cover the registration path (previously
325
- documented for claims only).
326
- - README: new "Player registration (email + phone, required)" section; examples updated
327
- (`proxy-server.ts` token route now rejects a phoneless actor with a clear 400).
328
-
329
- **Migration:** collect the player's phone in your enrollment UI before the first
330
- `mintPlayerToken` call and pass it as `playerPhone` in E.164. Handle the
331
- `isPhoneShareApprovalRequired` error as a "pending approval" UI state.
332
-
333
- ## [1.2.1] — 2026-07-01
334
-
335
- **Fix — browser "Illegal invocation".** The SDK invoked its fetch as `this.fetchImpl(...)`,
336
- so the browser's native `fetch` ran with the wrong `this` and threw
337
- `TypeError: Illegal invocation` — breaking every browser `InvoClient` read
338
- (balance/destinations/pending) and the passkey ceremonies when using the default global
339
- `fetch` (retries then made it slow on top). The fetch impl is now bound to `globalThis`
340
- (harmless for a custom `fetch`). No API change. Node/tests were unaffected, which is why it
341
- slipped through — added a `this`-sensitive regression test.
342
-
343
- ## [1.2.0] — 2026-07-01
344
-
345
- Two more server-side capabilities on `InvoServer`.
346
-
347
- - **Phone-share OTP handshake** — `phoneShareInitiate` / `phoneShareApprove` / `phoneShareStatus`
348
- resolve a `409 PHONE_SHARE_APPROVAL_REQUIRED`. Unauthenticated (phone-owner-driven — no game
349
- secret, no player token), relayed by a partner backend; after approve, re-issue the identical
350
- original request (the grant is server-side + auto-consumed). Adds
351
- `InvoError.isPhoneShareAlreadyApproved`.
352
- - **Server-side `getDestinations`** — game-secret variant of the browser
353
- `InvoClient.getDestinations`; pass `{ sourceGameId, direction }` (default `"transfer"`), rows
354
- share the same `DestinationGame` shape.
355
-
356
- ## [1.1.0] — 2026-07-01
357
-
358
- Four additive server-side flows on `InvoServer` (the SMS-PIN / claim-code / status /
359
- guardian paths partners still need alongside the passkey path).
360
-
361
- - **SMS-PIN completion** — `verifySmsTransfer` / `verifySmsSend` (for `verificationMethod: "sms"`).
362
- - **Claim-by-code** — `claimTransfer` / `claimCurrency`, incl. the `needsAccountSelection`
363
- multi-account disambiguation (a `200` with `candidates`, not an error).
364
- - **Status reads** — `getTransferStatus` / `getSendStatus` (surface `verificationState`).
365
- - **Guardian approval-status poll** — `getGuardianApprovalStatus` (poll a hold to `state`).
366
- - New typed results (`SmsVerifyResult`, `ClaimResult`, `TransactionStatusResult`,
367
- `GuardianApprovalStatusResult`) + `InvoError.isPhoneShareApprovalRequired`.
368
-
369
- ## [1.0.0] — 2026-07-01
370
-
371
- **1.0 — stable.** The public API is now covered by a stability commitment: it follows
372
- semver and no breaking change ships without a major bump + migration note. This is a
373
- milestone release, **not a breaking change** — code on `0.8.x` continues to work unchanged.
374
-
375
- Also in this release (docs + DX):
376
-
377
- - **Integration modes** documented — **browser-direct** (default) and **behind your proxy**
378
- (keep the INVO player token server-side via a custom `baseUrl`/`fetch`; no CORS or
379
- security-posture change). Plus a token-bootstrap example and a CORS + RP-ID/origins
380
- go-live checklist.
381
- - `linkDevice` called out as the lowest-risk first adoption (additive, no refactor).
382
-
383
- ## [0.8.0] — 2026-07-01
384
-
385
- Completes the **discovery layer** for send/transfer UIs.
386
-
387
- - **`InvoClient.getBalance()`** (browser, player-token, `GET /api/sdk/balance`) — the
388
- player's balances for the token's game: `balances[]` (`currencyId`, `currencyName`,
389
- `currencySymbol`/`currencySymbolUrl` (nullable), `availableBalance`/`reservedBalance`/
390
- `totalBalance` as decimal strings) plus `totalValue` / `currencyCount` / `hasFunds`. A
391
- player who hasn't transacted here yet returns an empty `balances` array (a `200`, not an
392
- error); `404 GAME_NOT_FOUND` throws.
393
- - **`InvoServer.getLinkedIdentities({ playerEmail | playerPhone })`** (server-only,
394
- game-secret) — a player's linked wallet identities (game-scoped). Provide one identifier
395
- (phone wins if both); no in-game match returns `notFound: true` with empty `emails`
396
- instead of throwing. **Returns first-party PII — never expose to the browser.**
397
-
398
- ## [0.7.0] — 2026-07-01
399
-
400
- Start of the **discovery layer** for send/transfer UIs.
401
-
402
- - **`InvoClient.getDestinations({ direction })`** — one player-token call
403
- (`GET /api/sdk/destinations`) returns every game the player can send/transfer to, with
404
- all display metadata **inline** (game name, icon, currency name/symbol, min/max transfer
405
- limits) — no per-game lookup. Includes source game/currency info and `transferMode`
406
- (`universal`/`linked` + `linkedGameIds`).
407
- - _(Coming in 0.7.x: `getBalance` single-game player-token read; `getLinkedIdentities`
408
- server-side.)_
409
-
410
- ## [0.6.0] — 2026-07-01
411
-
412
- Three additive browser flows for partner front-ends, built to the live backend contracts.
413
-
414
- - **`InvoClient.getPendingCollect()`** — the player's own pending-to-collect list
415
- (player-token `GET /api/sdk/transfers/pending`), PII-free. Each row's `kind`
416
- (`identity_gate` → `approve*`, `receiving_confirm` → `confirmReceipt*`) tells you the
417
- action; typed fields incl. `held` / `holdReason` / `stepUpRequired`.
418
- - **First-enrollment OTP grant** — `enrollmentBegin()` / `enrollmentVerify(code)` for
419
- `ENROLLMENT_REQUIRES_AUTHORIZATION` (send OTP to phone+email, verify, then retry the
420
- same `enrollPasskey()` — the server grant is auto-consumed). New `InvoError` helpers
421
- `isEnrollmentAuthorizationRequired` / `isEnrollmentProofRequired`.
422
- - **Typed approve/confirm holds** — `approve*`/`confirmReceipt*` now surface a typed
423
- `holdReason` (from `error_code ?? code`) on HTTP 202 holds, plus `risk` /
424
- `guardianApproval` / `pollEndpoint` on approve. `RECIPIENT_IDENTITY_PENDING` correctly
425
- surfaces on confirm-receipt. Success carries no `holdReason`.
426
-
427
- ## [0.5.0] — 2026-07-01
428
-
429
- Support partner `metadata` end-to-end on the purchase flow (additive, backward-compatible).
430
-
431
- - **`PurchaseCompletedData.metadata?`** — the `purchase.completed` webhook now echoes your
432
- metadata back (all rails); `event.data.metadata` is typed.
433
- - **`purchaseCurrency`** now accepts and forwards `metadata` (the direct `/purchase-currency`
434
- endpoint accepts it too, matching `createCheckout`).
435
-
436
- ## [0.4.2] — 2026-06-30
437
-
438
- Fixes from an independent line-by-line audit against the live backend.
439
-
440
- - **`linkDevice` now works.** `device/link/webauthn/begin` returns a wrapped
441
- `{ link_id, options }` body (challenge nested under `options`) and binds the
442
- challenge to a server-generated `link_id`. The client now unwraps `options` and
443
- echoes the server's `link_id` to `/complete` (it previously threw on an undefined
444
- challenge and sent the wrong id).
445
- - **`InvoError.code` is now populated for the direct purchase rail + guardian flows.**
446
- `errorFromResponse` reads `error_code` (SecureErrorHandler + `/purchase-currency`)
447
- in addition to `code`, and promotes known no-code tokens (`flow_paused`,
448
- `spending_limit_exceeded`, `receiver_not_enrolled_use_claim_code`) to `.code`. Fixes
449
- `isDuplicateRequest` on the direct rail.
450
- - **Guardian/minor routing.** The 202 guardian body also carries
451
- `verification_method:"sms"`; the SDK now suppresses it (reports
452
- `verificationMethod: undefined`) so a guardian-pending minor isn't routed into the
453
- SMS-PIN UI. README example reordered to branch on `guardianApproval` first.
454
-
455
- ## [0.4.1] — 2026-06-30
456
-
457
- Docs only — replaced the README's internal-leaking "Deployment prerequisites"
458
- (backend flag names, DB columns, gating mechanics) with a partner-facing
459
- "Before you go live"; republished so the npm page README is current.
460
-
461
- ## [0.4.0] — 2026-06-30
462
-
463
- Additive release — more server reads, edge-ready webhooks, cancellation, and tooling.
464
-
465
- - **`getInboundPending({ playerEmail | playerPhone })`** — live, unclaimed inbound
466
- sends/transfers for a player (the source of truth behind the "you have X to collect"
467
- badge; pairs with `transfer.claim_pending`).
468
- - **`verifyWebhookAsync`** — Web Crypto variant of `verifyWebhook` that runs on
469
- Cloudflare Workers / Deno / Vercel+Netlify Edge / Bun / browsers; and
470
- **`createWebhookHandler`** — a zero-dep Fetch-API `(Request) => Promise<Response>`
471
- webhook route handler (Next.js App Router, Workers, Deno, Hono, Bun).
472
- - **`iterateItemPurchaseHistory`** — async iterator that pages through a player's
473
- full item-purchase history.
474
- - **Per-call `AbortSignal`** — every method accepts an optional `{ signal }`; an
475
- aborted call throws `InvoError` code `ABORTED` and is never retried.
476
- - **Tooling**: ESLint (+ lint in CI), changesets release automation, `SECURITY.md`,
477
- and `CODEOWNERS`.
478
-
479
- ## [0.3.0] — 2026-06-30
480
-
481
- Additive release — new server capabilities plus transport resilience/observability.
482
-
483
- - **Webhook verification** (`/server`): `verifyWebhook(rawBody, signatureHeader, secret | secrets, opts?)`
484
- — constant-time HMAC-SHA256 over `${t}.${rawBody}`, 5-minute replay window,
485
- multi-secret rotation; returns a typed `InvoWebhookEvent` discriminated union
486
- (`purchase.*`, `item.purchased`, `transfer.*`, `payout.status_changed`, `webhook.test`).
487
- Throws `InvoError` (`WEBHOOK_SIGNATURE_INVALID` / `WEBHOOK_TIMESTAMP_EXPIRED` /
488
- `WEBHOOK_MALFORMED` / `WEBHOOK_SECRET_MISSING`). Server-only; the browser bundle
489
- stays crypto-free. Independently security-audited.
490
- - **`getPlayerBalance({ playerEmail | playerId })`** (`/server`): typed `player` / `balances` / `summary`.
491
- - **Automatic retries**: network errors/timeouts, `429` (honoring `retry_after`), and
492
- `5xx` are retried with exponential backoff + jitter. New config `maxRetries`
493
- (default 2, `0` disables) and `retryBaseDelayMs` (default 250).
494
- - **Observability hooks**: optional `onRequest` / `onResponse` / `onError` on both
495
- entries (best-effort/non-throwing); `InvoError.requestId` carries the backend
496
- request id for support/tracing.
497
- - **Typed reads**: `confirmPayment` → `ConfirmPaymentResult`; `getOrderDetails` /
498
- `getItemOrderDetails` → `OrderDetailsResult`; `getItemPurchaseHistory` →
499
- `ItemHistoryResult` (previously untyped `Record`). All keep `raw`.
500
- - **Light validation**: `mintPlayerToken` and `createCheckout` require a non-blank
501
- `playerEmail` (throws `INVALID_INPUT` before the network call).
502
- - **License**: `package.json` `license` is now `SEE LICENSE IN LICENSE` (was
503
- `UNLICENSED`); `LICENSE` rewritten as an explicit install-and-use grant for
504
- building INVO integrations.
505
-
506
- ## [0.2.1] — 2026-06-30
507
-
508
- Docs only — no code change (republished so the npm page README is current).
509
-
510
- - Rewrote the README into a complete integration/deployment guide: capability
511
- overview, architecture, deployment prerequisites, per-flow sections (currency
512
- purchase, item purchase, sends, transfers, passkeys), webhooks, errors, and a
513
- full API reference for both entries.
514
- - Added INVO console onboarding: `https://console.invo.network` (production) and
515
- `https://dev.console.invo.network` (testing/sandbox), mapped to their API base URLs.
516
-
517
- ## [0.2.0] — 2026-06-30
518
-
519
- Adds **item purchase** (spend existing game currency on an in-game item, §4.8) — an
520
- additive, server-only surface.
521
-
522
- - `InvoServer` (`/server`): `purchaseItem`, `getItemPurchaseHistory`, `getItemOrderDetails`.
523
- - Server-side, game-secret auth — no passkey, no real money, no payment rail (it's a
524
- balance debit). Grant the item off the `item.purchased` webhook.
525
- - Client-side guards: required fields (trim-checked), `itemQuantity` integer `1..1000`,
526
- prices `> 0` and `<= 999999.99` (magnitude-safe 2-decimal check), and
527
- `totalPrice == unitPrice × itemQuantity (±0.01)` compared in integer cents.
528
- - Load-bearing response fields (`transaction_id`, `order_id`) throw `INVALID_RESPONSE`
529
- if missing on a 200.
530
- - `InvoError` helpers: `isInsufficientBalance` (gated to 400; not the `429` throttle),
531
- `isDuplicateRequest` (409), `retryAfter` (numeric or string `retry_after`); all
532
- null-safe against non-JSON error bodies.
533
- - Independently audited (2 agents) against handoff doc §4.8/§6/§8; contract verified,
534
- error-classification edge cases fixed.
535
-
536
- ## [0.1.0] — 2026-06-30
537
-
538
- Initial scaffold.
539
-
540
- - `InvoServer` (`/server`): `mintPlayerToken`, `initiateSend`, `initiateTransfer`,
541
- `createCheckout`, `purchaseCurrency`, `confirmPayment`, `getOrderDetails`.
542
- - Client-side purchase guards (§4.7): USD amount `0 < x ≤ 999.99`, required
543
- `purchaseReference`, and `rail:"steam"` rejected before the network call
544
- (`INVALID_INPUT` / `MISSING_PURCHASE_REFERENCE` / `WRONG_RAIL_ENDPOINT`).
545
- - `InvoClient` (browser): `enrollPasskey`, `approveSend`/`approveTransfer`,
546
- `confirmReceiptSend`/`confirmReceiptTransfer`, and `linkDevice` for the
547
- interchangeable-methods flow (§4.6).
548
- - Optional `refreshToken` hook: transparently re-mints and retries once on
549
- `SDK_TOKEN_EXPIRED` (§11.2).
550
- - Shared: typed `InvoError`, isomorphic HTTP client, WebAuthn JSON⇄binary helpers.
551
- - Tests: HTTP layer, server request mapping + purchase guards, browser client
552
- flows (enroll/approve/link/token-refresh), and WebAuthn serialization.
553
- - Contracts extracted + auditor-verified against the INVO backend.
554
-
555
- ### Hardening (independent red-team pass)
556
-
557
- - **Guardian/minor `202` path no longer mismapped to `verificationMethod:"sms"`** —
558
- `initiateSend`/`initiateTransfer` now return `verificationMethod: undefined` and a
559
- `guardianApproval` block on the guardian path, so callers don't route into the
560
- PIN UI by mistake (§4.3).
561
- - `usdAmount` validation tightened: rejects non-plain-decimal strings
562
- (`"0x10"`, `"1e2"`, whitespace) and >2 decimal places before any network call.
563
- - Load-bearing response fields (`token`, `checkout_url`) now throw `INVALID_RESPONSE`
564
- instead of silently surfacing as empty strings.
565
- - `getOrderDetails` requires at least one of `orderId`/`transactionId`.
566
- - Token refresh now re-runs the **whole** passkey ceremony on `SDK_TOKEN_EXPIRED`
567
- (never replays a single-use assertion) and single-flights concurrent refreshes.
568
- - `baseUrl` must be `https://` (localhost exempt) so the token/secret can't travel
569
- in cleartext.
570
- - Published tarball excludes sourcemaps (no proprietary source shipped).
1
+ # Changelog
2
+
3
+ All notable changes to `@invonetwork/web-sdk` are documented here. This project follows
4
+ [Semantic Versioning](https://semver.org/). Releases are managed with
5
+ [changesets](https://github.com/changesets/changesets).
6
+
7
+ ## [3.2.0] — 2026-08-24
8
+
9
+ **Storefront keys.** A game that ships on more than one storefront now gets one SDK
10
+ key per storefront -- `steam`, `ios`, `android`, `web`, `console` -- all valid at the
11
+ same time, and the key determines the payment rail. Construct one client per key and
12
+ use whichever matches where the player is buying. **Additive: no behavior changes, no
13
+ API removals.** A single existing key keeps working exactly as it does today, `rail`
14
+ included, with no deadline and no migration.
15
+
16
+ Three new typed error predicates for refusals this SDK previously surfaced only as a
17
+ raw `code` string:
18
+
19
+ - `InvoError.isRailChannelMismatch` -- the `rail` you sent disagrees with the storefront key
20
+ you authenticated with (400). The fix is to stop sending `rail`; the key already
21
+ determines it. INVO refuses rather than silently overriding, because overriding
22
+ would bill a player through a route you did not ask for.
23
+ - `InvoError.isSteamRailNotEntitled` -- a Steam purchase was attempted for a title INVO has
24
+ not registered as distributed on Steam (403). Holding a `steam` storefront key does
25
+ not by itself register the title.
26
+ - `InvoError.isSteamPurchaseLayerRequired` -- a title distributed on Steam tried to sell currency
27
+ on a non-Steam rail (409). Use the dedicated Steam purchase flow.
28
+
29
+ Also in this release: the 3-D Secure completion method's documentation no longer names
30
+ a payment processor. INVO does not name processors in developer-facing surfaces, and
31
+ this line had been an exception to that for some time.
32
+
33
+ Also in 3.2.0: **provider-neutral error codes.** INVO stamps a neutral alias
34
+ (`error_code_public`) beside any machine code that carries a payment
35
+ processor's name. This SDK previously read only the raw code, so a partner
36
+ branching on `err.code` had to hard-code a vendor name INVO's own public
37
+ documentation is not allowed to print. `err.code` is now the neutral alias when
38
+ one exists (`STRIPE_ERROR` becomes `PROCESSOR_ERROR`), and the literal wire value stays reachable on
39
+ `err.rawCode` for anyone already matching it. Refund reads prefer
40
+ `processor_refund_reference` over the vendor-named field, with a fallback.
41
+
42
+
43
+ **Storefront keys are still server-side keys.** A storefront key names where the
44
+ *purchase* came from, not where the key lives. It belongs in your backend exactly like
45
+ your original key -- never in a game client, an app bundle, or browser code.
46
+
47
+ ## [3.1.0] — 2026-08-04
48
+
49
+ **Passkeys are the gold standard; the SMS-PIN path is deprecated.** This release makes INVO's
50
+ authentication guidance explicit in the two places developers actually look — the README and IDE
51
+ autocomplete. **No behavior changes, no API removals, no runtime warnings.** Upgrading and
52
+ changing nothing produces byte-identical runtime behavior.
53
+
54
+ A passkey is a phishing-resistant, origin-bound WebAuthn assertion. An SMS PIN is a shared secret
55
+ on a channel exposed to SIM swap and interception. They were documented as interchangeable
56
+ verification options; they are not, and the docs said so in a way that produced PIN-first
57
+ integrations.
58
+
59
+ ### Added — error-contract classifiers
60
+ Three 403s that previously arrived as a generic `InvoError` (correct `status`/`code`/`message`,
61
+ but no typed branch) now have classifiers:
62
+
63
+ - **`err.isSourceGameNotLive`** — the caller's OWN game is in testing. Self-serve: switch it to
64
+ Live in the console (Game Settings → Status).
65
+ - **`err.isTargetGameNotLive`** — the DESTINATION game is in testing. Usually another
66
+ developer's game, so the caller **cannot** fix it. **Deliberately distinct** from the source
67
+ case: collapsing them into one "not live" branch yields a "go fix it" CTA that dead-ends half
68
+ the time.
69
+ - **`err.gameStatus`** — the `game_status` field from either refusal (e.g. `"testing"`).
70
+ - **`err.isWebauthnNotEnabledForTenant`** — tenant has no verified WebAuthn RP ID. **This is
71
+ configuration state, not a failure**: fall back to the SMS/in-app path instead of surfacing an
72
+ error. Currently the common case — 4/23 sandbox and **0/3 production** tenants are configured.
73
+
74
+ Note the backend splits field names across these: the `*_GAME_NOT_LIVE` pair uses
75
+ `error_code`/`message`, while `WEBAUTHN_NOT_ENABLED_FOR_TENANT` uses `code`/`error`. The SDK
76
+ already read both, so `err.code` is populated either way — the new tests pin both shapes.
77
+
78
+ ### Clarified — the SDK does not, and did not, collapse non-2xx into transport errors
79
+ Following a report of a `403` being debugged as a network outage: verified end-to-end that a
80
+ non-2xx always surfaces with its real `status`, `code`, and `message`, and that `status: 0` is
81
+ reserved for a genuine absence of an HTTP response. **No fix was needed in the SDK** — the loss
82
+ happened in an integration-layer catch-all. Added regression tests pinning the behavior, plus a
83
+ README section (**"`.status === 0` means 'no HTTP response' — and nothing else"**) showing the
84
+ anti-pattern and the correct handler, and a note that `409` is a retryable not-ready state
85
+ rather than a failure.
86
+
87
+ ### Deprecated
88
+ - **`InvoServer.verifySmsTransfer` / `InvoServer.verifySmsSend`** — marked `@deprecated`. They
89
+ still work exactly as before and still hit the same endpoints. A **future major version will
90
+ remove them**; no date is committed yet. Keep them only as a genuine last resort for users who
91
+ cannot enroll a passkey (unsupported device, no platform authenticator) or who decline.
92
+ **Migration:** when `initiateSend`/`initiateTransfer` returns `verificationMethod: "sms"`, read
93
+ it as *"this sender has no passkey"* — prompt `InvoClient.enrollPasskey()` and then
94
+ `InvoClient.approveSend` / `approveTransfer`, instead of routing to a PIN pad.
95
+
96
+ ### Changed (documentation only)
97
+ - New README section — **"Passkeys are the gold standard — don't build on SMS"** — with the
98
+ do/don't table, the deprecation notice, and an explicit list of the OTP surfaces that are
99
+ **not** discouraged.
100
+ - `VerificationMethod`, `InitiateResult.verificationMethod` and `SmsVerifyResult` doc comments
101
+ reframed: `"in_app"` and `"sms"` are no longer presented as peer options.
102
+ - "Before you go live" now stresses configuring RP ID / origins *before* launch, since an
103
+ unconfigured tenant silently drops every sender onto the deprecated path.
104
+ - **New "Prerequisite: passkeys are dark until your tenant verifies a domain" subsection.**
105
+ Recommending passkeys without saying what unlocks them would send developers straight into a
106
+ `403` on their first `enrollPasskey()` call — with 0/3 prod tenants configured, that is
107
+ currently *everyone*. The deprecation carries no removal date for the same reason.
108
+ - Stability section corrected — it still claimed `2.0.0` was the only major, which `3.0.0`
109
+ made false.
110
+ - Design doc: `docs/features/passkey-first-authentication.md`.
111
+
112
+ ### Not affected — still recommended
113
+ `enrollmentBegin`/`enrollmentVerify`, `recoveryBegin`/`recoveryComplete`, and
114
+ `phoneShareInitiate`/`phoneShareApprove` all involve a one-time code but are the on-ramp *to* a
115
+ passkey (or phone-ownership consent), not a substitute for one. They are **not** deprecated.
116
+
117
+ ### Upgrade note
118
+ The only way this release can surface in a pipeline is a lint rule that treats `@deprecated`
119
+ usage as an error (e.g. `deprecation/deprecation` with `--max-warnings 0`). That is a lint-level
120
+ signal, not a build or runtime break, and it is the intended notice.
121
+
122
+ ## [3.0.0] — 2026-07-20
123
+
124
+ **BREAKING — the Platform Commerce card leg moved to INVO's hosted checkout.** The backend now
125
+ hosts the entire card flow (card fields, Apple Pay / Google Pay, billing-address collection,
126
+ 3-D Secure) on its own checkout page, so the browser card-element surface shipped in 2.5.x is
127
+ gone. Card sales are simpler AND safer: server creates → buyer pays on `checkoutUrl` → fulfill
128
+ on the `platform_commerce.purchased` webhook. Note: the card leg is pending final enablement on
129
+ the backend (sandbox payment test) — the balance leg is fully live.
130
+
131
+ ### Migration from 2.5.x (card leg only — balance/status/refund/webhooks unchanged)
132
+ - `platformCommerce.purchase({ fundingSource: "card" })`: **remove `billingAddress`** (the type
133
+ is gone; the hosted page collects it) and optionally pass `successUrl` / `cancelUrl` /
134
+ `metadata`. The result now carries `checkoutUrl` / `sessionId` / `expiresAt` (unix seconds) /
135
+ `idempotentReplay` — **`clientSecret` no longer exists.**
136
+ - Browser: **`confirmCardPayment` and `mountCardPayment` are removed** (with all card-element
137
+ types and the `commercePublishableKey` config). Replace with a redirect
138
+ (`location.href = checkoutUrl`) or the new optional embed:
139
+ `invo.platformCommerce.mountCheckout(el, checkoutUrl, { onComplete })` — an iframe plus an
140
+ origin-checked listener for the page's `INVO_CHECKOUT_COMPLETE` message.
141
+ - Card duplicates no longer 409: retrying `purchase` with the same `clientRequestId` **replays
142
+ the same checkout session** (`idempotentReplay: true`), so a lost response is recoverable.
143
+
144
+ ### Added
145
+ - `PlatformPurchaseInput.successUrl/cancelUrl/metadata`; result fields
146
+ `sessionId/checkoutUrl/expiresAt/idempotentReplay`.
147
+ - `InvoClient.platformCommerce.mountCheckout(el, checkoutUrl, opts)` → `{ iframe, destroy() }`.
148
+ - `err.isAboveCardMaximum` (`ABOVE_CARD_MAXIMUM`, card > $999.99) + client-side card USD
149
+ bounds fail-fast ($0.50–$999.99).
150
+ - Card `requires_payment` responses without a `checkout_url` fail closed (`INVALID_RESPONSE`).
151
+
152
+ ### Removed
153
+ - `confirmCardPayment`, `mountCardPayment`, `commercePublishableKey`, `BillingAddress`, and the
154
+ card-element/processor types + the runtime CDN script loader (no more processor touchpoints
155
+ in this SDK at all).
156
+
157
+ ## [2.5.1] — 2026-07-20
158
+
159
+ Hardening patch from a second, independent post-release audit (correctness vs the backend
160
+ blueprint + security red-team) of the 2.5.0 Platform Commerce feature. No API breaks.
161
+
162
+ ### Fixed
163
+ - **Card-confirm script loader could hang forever on retry.** After a transient CDN failure
164
+ (or a pre-existing processor `<script>` tag whose events already fired), the next
165
+ `mountCardPayment`/`confirmCardPayment` attached listeners to a dead tag and never settled —
166
+ checkout silently dead until page reload. The loader now removes failed tags and polls
167
+ (bounded, 10s) when a tag pre-exists.
168
+ - **Orphaned card element on submit-lookup failure.** `confirmCardPayment` now destroys the
169
+ mounted Payment Element before rethrowing when the `submit` selector can't be resolved
170
+ (previously a retry stacked a second live card iframe).
171
+ - **Billing-address validation errors no longer echo the submitted values** (cardholder PII
172
+ could otherwise land in logs/Sentry); optional billing fields (`name`/`line2`/`state`) are
173
+ now type-checked.
174
+ - **`playerPhone` on `platformCommerce.purchase` is now E.164-validated** — this endpoint can
175
+ create the player identity, so a national-format phone must never reach the wire.
176
+ - **`err.isInsufficientBalance` now also classifies the zero-balance 400** ("Player has no
177
+ balance in this tenant", which carries only `current_balance`).
178
+ - **Breaker-open 503 keeps its human message** (`err.code === "service_unavailable"`, message
179
+ no longer collapses to the bare token).
180
+ - **Webhook types:** `platform_commerce.refunded` `player_email` is nullable + `identity_id`
181
+ added; (2.5.0 already made card-leg `total_price` optional on `purchased`).
182
+ - **Refund result surfaces `newBalance`** (balance leg) **and `processorRefundId`** (card leg)
183
+ instead of leaving them `raw`-only.
184
+ - Platform-commerce error tests now assert the REAL backend envelopes
185
+ (`{status,error_code,message}` / bare `{message}`), not idealized shapes.
186
+
187
+ ### Docs
188
+ - Card-leg lost-response caveat on `purchase` (duplicate 409 can strand a `clientSecret`-less
189
+ pending order — reconcile via webhook/`getStatus`, retry with a NEW `clientRequestId`).
190
+ - `confirmCardPayment`: bank-redirect return-leg guidance + remount-after-decline note;
191
+ `CardPaymentResult.raw` log-redaction note.
192
+
193
+ ## [2.5.0] — 2026-07-20
194
+
195
+ **Platform Commerce (ecommerce).** A new flow for **platform** tenants (non-game apps: vertical
196
+ video, creator merch, marketplace) to sell items funded by **INVO balance or a real card**, with
197
+ INVO as merchant of record and full refunds. This is **distinct from item purchase** — that is a
198
+ *game* tenant spending a player's *existing game currency* on an *in-game* item (balance only, no
199
+ card, no refund). Additive; only platform tenants can call it (a game tenant gets `403
200
+ NOT_A_PLATFORM_TENANT`). (Backend handoff: BE-PIP-009 `PLATFORM_COMMERCE_SDK.md`.)
201
+
202
+ - **Server** (`InvoServer.platformCommerce`, mirrored in the Python SDK as
203
+ `server.platform_commerce`):
204
+ - `purchase(input)` — `fundingSource: "balance"` settles synchronously (`status:"success"`);
205
+ `"card"` returns `status:"requires_payment"` + a `clientSecret` and **requires a
206
+ `billingAddress`**. Idempotent on `clientRequestId`.
207
+ - `getStatus(orderId)` — `completed` | `pending_payment` | `refunded`.
208
+ - `refund({ orderId | clientRequestId, reason? })` — INVO retains its fee; a second refund
209
+ throws `409` (`err.isAlreadyRefunded`).
210
+ - **Browser** (`InvoClient.platformCommerce`):
211
+ - `confirmCardPayment(clientSecret, { mount, publishableKey?, returnUrl?, submit? })` — mounts
212
+ the card element and confirms; returns `{ status: "succeeded" | "requires_action" |
213
+ "processing" | "failed" }`. The processor JS is **lazy-loaded from its CDN — no bundled
214
+ dependency**; pass its publishable key (or set `commercePublishableKey` on the client config).
215
+ - `mountCardPayment(clientSecret, opts)` — the primitive: `{ element, confirm(), destroy() }`
216
+ to confirm from your own Pay button.
217
+ - **Webhooks:** new typed `platform_commerce.purchased` / `platform_commerce.refunded` events.
218
+ **Fulfill card orders on `platform_commerce.purchased`, never on the browser confirmation.**
219
+ - **New `InvoError` classifiers:** `isNotPlatformTenant` (403), `isAmountBelowMinimum`,
220
+ `isBelowCardMinimum` (card < $0.50), `isAlreadyRefunded` (409).
221
+ - Docs: README now leads the flow list with an explicit **item purchase vs Platform Commerce**
222
+ contrast; new "Platform Commerce (ecommerce)" section.
223
+
224
+ ## [2.4.1] — 2026-07-10
225
+
226
+ Docs only, no code change — corrects stale README prose that the 2.4.0 publish still carried:
227
+ the status line led with an old version, and the Stability section still cited the `2.0.0`
228
+ `playerPhone` requirement as the standing breaking change (2.2.0 relaxed it back to optional).
229
+ Republished so the package-bundled README is accurate.
230
+
231
+ ## [2.4.0] — 2026-07-10
232
+
233
+ **Steam transfer policy.** Steam-purchased currency is locked to Steam titles; the backend now
234
+ enforces this at transfer/send initiate and annotates destinations. Additive, and inert until a
235
+ title is flagged Steam-distributed. (Design doc: `docs/features/steam-transfer-policy.md`.)
236
+
237
+ - New `InvoError` classifiers on `initiateSend`/`initiateTransfer` 409s:
238
+ `isSteamValueNonTransferable` (with `steamTransferableMax` / `steamOriginAmount` — decimal
239
+ strings) and `isNonSteamValueIntoSteamBlocked`. Surface `err.message` verbatim.
240
+ - New `DestinationGame.acceptsSteamOriginValue` (maps `accepts_steam_origin_value`; `false` when
241
+ omitted) — disable non-Steam destinations for a player holding Steam value so they never hit
242
+ the 409.
243
+
244
+ No breaking changes.
245
+
246
+ ## [2.3.0] — 2026-07-07
247
+
248
+ **Claim-time phone-share approval.** The backend closed a security gap: claiming/collecting a
249
+ phone-routed transfer now authorizes the collecting identity against the receiver phone before
250
+ crediting. So `confirmReceiptSend`/`confirmReceiptTransfer` and `claimTransfer`/`claimCurrency`
251
+ can now return the phone-share `409 PHONE_SHARE_APPROVAL_REQUIRED` (previously only
252
+ registration/mint did). The existing `InvoError.isPhoneShareApprovalRequired` already classifies
253
+ it — no consumer code must change — but:
254
+
255
+ - New **`InvoError.phoneShareLast4`** surfaces the `phone_last4` from the 409 body for the UI
256
+ ("we texted the phone ending 1234").
257
+ - `isPhoneShareApprovalRequired` docs + the `confirmReceipt*`/claim method docs + README now
258
+ spell out the claim-time path: it's **not a failure** — the funds are held and the phone owner
259
+ is texted; show `err.message` verbatim, then **retry the same call** once approved (it succeeds
260
+ idempotently); on denial/expiry the sender is refunded.
261
+
262
+ Additive, no breaking changes; affects all rails' claim paths (transfer, currency send, amazon).
263
+
264
+ ## [2.2.0] — 2026-07-07
265
+
266
+ **Backend reconciliation** — a full audit of the SDK against the live backend surfaced three
267
+ places the SDK didn't match reality. All changes are backward-compatible (relaxing required
268
+ inputs / adding surface); no working call breaks.
269
+
270
+ - **`mintPlayerToken` no longer requires `playerPhone`.** `/api/sdk/player-token` is a
271
+ session-token mint for an **existing** player (looked up by email) — not a registration call.
272
+ It reads only `player_email` and ignores `player_phone`. The 2.0.0 hard E.164 requirement was
273
+ a bug: it could **block a valid token mint for an existing email-only player**. `playerPhone`
274
+ is now optional and validated only if provided. Phone stays enforced where it matters — the
275
+ sender's phone on `initiateSend`/`initiateTransfer`, and at player creation.
276
+ - **Send by phone alone.** `receiverPlayerEmail` (send) and `targetPlayerEmail` (transfer) are
277
+ now **optional** — you can send to a recipient's phone; they supply their email at claim
278
+ (claim still requires it, since that's where the recipient establishes identity).
279
+ - **`getPlayerBalance` is by email only.** There is no by-`playerId` balance route on the
280
+ backend, so passing `playerId` threw a confusing 404. It now throws a clear `INVALID_INPUT`
281
+ pointing you to `InvoClient.getBalance()` (client-side) or `playerEmail` (server-side).
282
+ - **New `InvoError.isUserVerificationRequired`** for the `WEBAUTHN_UV_REQUIRED` (401) approve
283
+ failure — re-run the passkey ceremony requiring UV.
284
+ - Fixed `iterateItemPurchaseHistory` to read the backend's `total_count` pagination key (was
285
+ `total`; the loop already terminated via the short-page guard, so behavior is unchanged).
286
+
287
+ **Migration:** none required. If you were passing `playerPhone` to `mintPlayerToken` it still
288
+ works; you can now also omit it. Replace any `getPlayerBalance({ playerId })` with an email
289
+ lookup or `InvoClient.getBalance()`.
290
+
291
+ ## [2.1.2] — 2026-07-07
292
+
293
+ **Hosted-checkout reconciliation** (the create-session API contract is unchanged; the hosted
294
+ page was rebuilt). Additive + docs only.
295
+
296
+ - `createCheckout` now surfaces `expiresInSeconds` (the `checkout_url` token TTL, e.g. 900) as
297
+ a first-class field on `CreateCheckoutResult` — previously only on `.raw`.
298
+ - README: the `platform` rail is described as cards + Apple Pay / Google Pay / Link +
299
+ international billing (no app-store commission), and the checkout note now says reloading the
300
+ URL after a completed payment is idempotent (an already-complete success screen), not an
301
+ error. No API/signature changes.
302
+
303
+ ## [2.1.1] — 2026-07-06
304
+
305
+ **Security & correctness hardening** from a full audit + red-team of both SDKs. No API changes;
306
+ upgrade recommended.
307
+
308
+ - **Fail closed on HTTP redirects (security).** The transport now sends `redirect:"manual"` and
309
+ throws `UNEXPECTED_REDIRECT` on any 3xx instead of following it. Previously a redirect from
310
+ the API host could cause the game-secret header to be re-sent to an unvalidated URL (matches
311
+ the Python SDK fix, where the leak also covered the player token and an `http://` downgrade).
312
+ - **`retryAfter` no longer treats a blank `retry_after` as `0`.** An empty/whitespace
313
+ `retry_after` string used to become `0` (`Number("")===0`) — an immediate, no-backoff retry.
314
+ It's now correctly `undefined`, in both `InvoError.retryAfter` and the retry layer.
315
+ - **Whitespace OTP codes rejected client-side.** `recoveryComplete`/`enrollmentVerify` now
316
+ reject a whitespace-only `code` before the network call, so it can't burn an attempt against
317
+ the attempt-capped endpoints (parity with the Python SDK).
318
+ - **Webhook verify uses `crypto.timingSafeEqual`** on the sync path (parity with Python's
319
+ `hmac.compare_digest`); the runtime-agnostic async/edge path keeps its string compare.
320
+ - **WebAuthn option mappers fail cleanly.** A malformed `register/begin` body now throws
321
+ `WEBAUTHN_OPTIONS_MALFORMED` (an `InvoError`) instead of a raw `TypeError`.
322
+
323
+ ## [2.1.0] — 2026-07-02
324
+
325
+ **Passkey recovery ("lost or replaced my passkey").** Deleting a passkey on the device never
326
+ tells the server the key is gone, so re-enrollment was dead-ended by the anti-takeover gate
327
+ (`ENROLLMENT_REQUIRES_PROOF`) with nothing left to prove possession with. The backend shipped
328
+ a self-serve, possession-proofed recovery flow; this release wires the client side.
329
+
330
+ - `InvoClient.recoveryBegin()` — sends a one-time code to the phone/email on file
331
+ (`{ status: "sent", channels }`); `InvoClient.recoveryComplete(code)` — deactivates the
332
+ stale server-side passkey and authorizes a fresh enrollment
333
+ (`{ status: "recovered", deactivatedCount, next }`). Then retry the same `enrollPasskey()`.
334
+ - New `InvoError` classifiers: `isEnrollmentCodeInvalid`, `isPasskeyRecoveryCooldown`, and
335
+ `retryAfterAt` (the ISO timestamp on the 403 cooldown — distinct from the numeric
336
+ `retryAfter` throttle field). Bare `no_channel_on_file` / `rate_limited` error tokens are
337
+ now promoted to `err.code`.
338
+ - **24-hour money cooldown surfaced:** a recovery-enrolled passkey logs in and collects
339
+ funds immediately, but `approveSend`/`approveTransfer` throw 403
340
+ `PASSKEY_RECOVERY_COOLDOWN` for 24h (SIM-swap protection). Branch on
341
+ `isPasskeyRecoveryCooldown`, show the pause message with `retryAfterAt`, don't retry-loop.
342
+ - README: recovery subsection under Passkeys, incl. the password-manager cleanup tip for
343
+ "there is a problem saving your passkey" (stale orphan entry).
344
+
345
+ Additive, no breaking changes. Routes require SDK verification enabled for the tenant
346
+ (dark 503 otherwise).
347
+
348
+ ## [2.0.0] — 2026-07-02
349
+
350
+ **BREAKING — `mintPlayerToken` now requires `playerPhone` (E.164).** Requested by the INVO
351
+ backend after a live incident: a player registered email-only couldn't receive a cross-game
352
+ transfer (incoming transfers are matched by phone) and never got the account-linking consent
353
+ SMS (also phone-triggered). The network identity is derived from **email + phone together**,
354
+ so the phone must be present on the FIRST registration call — attaching it later changes the
355
+ identity and forces device re-enrollment.
356
+
357
+ - `mintPlayerToken({ playerEmail, playerPhone })` — `playerPhone` is required and validated
358
+ as E.164 (`+15555550100`: leading `+`, country code, digits only) before any network call;
359
+ the body now posts `player_phone` alongside `player_email`.
360
+ - **Pending approval is surfaced, not an error to swallow:** minting with a phone that
361
+ already belongs to another INVO account (same person, new email) throws the existing
362
+ `isPhoneShareApprovalRequired` 409 — the phone holder got a consent SMS. New
363
+ `InvoError.phoneShareApprovalId` exposes the `approval_id` from the 409 body for the
364
+ `phoneShareApprove` OTP fallback. Docs updated to cover the registration path (previously
365
+ documented for claims only).
366
+ - README: new "Player registration (email + phone, required)" section; examples updated
367
+ (`proxy-server.ts` token route now rejects a phoneless actor with a clear 400).
368
+
369
+ **Migration:** collect the player's phone in your enrollment UI before the first
370
+ `mintPlayerToken` call and pass it as `playerPhone` in E.164. Handle the
371
+ `isPhoneShareApprovalRequired` error as a "pending approval" UI state.
372
+
373
+ ## [1.2.1] — 2026-07-01
374
+
375
+ **Fix — browser "Illegal invocation".** The SDK invoked its fetch as `this.fetchImpl(...)`,
376
+ so the browser's native `fetch` ran with the wrong `this` and threw
377
+ `TypeError: Illegal invocation` — breaking every browser `InvoClient` read
378
+ (balance/destinations/pending) and the passkey ceremonies when using the default global
379
+ `fetch` (retries then made it slow on top). The fetch impl is now bound to `globalThis`
380
+ (harmless for a custom `fetch`). No API change. Node/tests were unaffected, which is why it
381
+ slipped through — added a `this`-sensitive regression test.
382
+
383
+ ## [1.2.0] — 2026-07-01
384
+
385
+ Two more server-side capabilities on `InvoServer`.
386
+
387
+ - **Phone-share OTP handshake** — `phoneShareInitiate` / `phoneShareApprove` / `phoneShareStatus`
388
+ resolve a `409 PHONE_SHARE_APPROVAL_REQUIRED`. Unauthenticated (phone-owner-driven — no game
389
+ secret, no player token), relayed by a partner backend; after approve, re-issue the identical
390
+ original request (the grant is server-side + auto-consumed). Adds
391
+ `InvoError.isPhoneShareAlreadyApproved`.
392
+ - **Server-side `getDestinations`** — game-secret variant of the browser
393
+ `InvoClient.getDestinations`; pass `{ sourceGameId, direction }` (default `"transfer"`), rows
394
+ share the same `DestinationGame` shape.
395
+
396
+ ## [1.1.0] — 2026-07-01
397
+
398
+ Four additive server-side flows on `InvoServer` (the SMS-PIN / claim-code / status /
399
+ guardian paths partners still need alongside the passkey path).
400
+
401
+ - **SMS-PIN completion** — `verifySmsTransfer` / `verifySmsSend` (for `verificationMethod: "sms"`).
402
+ - **Claim-by-code** — `claimTransfer` / `claimCurrency`, incl. the `needsAccountSelection`
403
+ multi-account disambiguation (a `200` with `candidates`, not an error).
404
+ - **Status reads** — `getTransferStatus` / `getSendStatus` (surface `verificationState`).
405
+ - **Guardian approval-status poll** — `getGuardianApprovalStatus` (poll a hold to `state`).
406
+ - New typed results (`SmsVerifyResult`, `ClaimResult`, `TransactionStatusResult`,
407
+ `GuardianApprovalStatusResult`) + `InvoError.isPhoneShareApprovalRequired`.
408
+
409
+ ## [1.0.0] — 2026-07-01
410
+
411
+ **1.0 — stable.** The public API is now covered by a stability commitment: it follows
412
+ semver and no breaking change ships without a major bump + migration note. This is a
413
+ milestone release, **not a breaking change** — code on `0.8.x` continues to work unchanged.
414
+
415
+ Also in this release (docs + DX):
416
+
417
+ - **Integration modes** documented — **browser-direct** (default) and **behind your proxy**
418
+ (keep the INVO player token server-side via a custom `baseUrl`/`fetch`; no CORS or
419
+ security-posture change). Plus a token-bootstrap example and a CORS + RP-ID/origins
420
+ go-live checklist.
421
+ - `linkDevice` called out as the lowest-risk first adoption (additive, no refactor).
422
+
423
+ ## [0.8.0] — 2026-07-01
424
+
425
+ Completes the **discovery layer** for send/transfer UIs.
426
+
427
+ - **`InvoClient.getBalance()`** (browser, player-token, `GET /api/sdk/balance`) — the
428
+ player's balances for the token's game: `balances[]` (`currencyId`, `currencyName`,
429
+ `currencySymbol`/`currencySymbolUrl` (nullable), `availableBalance`/`reservedBalance`/
430
+ `totalBalance` as decimal strings) plus `totalValue` / `currencyCount` / `hasFunds`. A
431
+ player who hasn't transacted here yet returns an empty `balances` array (a `200`, not an
432
+ error); `404 GAME_NOT_FOUND` throws.
433
+ - **`InvoServer.getLinkedIdentities({ playerEmail | playerPhone })`** (server-only,
434
+ game-secret) — a player's linked wallet identities (game-scoped). Provide one identifier
435
+ (phone wins if both); no in-game match returns `notFound: true` with empty `emails`
436
+ instead of throwing. **Returns first-party PII — never expose to the browser.**
437
+
438
+ ## [0.7.0] — 2026-07-01
439
+
440
+ Start of the **discovery layer** for send/transfer UIs.
441
+
442
+ - **`InvoClient.getDestinations({ direction })`** — one player-token call
443
+ (`GET /api/sdk/destinations`) returns every game the player can send/transfer to, with
444
+ all display metadata **inline** (game name, icon, currency name/symbol, min/max transfer
445
+ limits) — no per-game lookup. Includes source game/currency info and `transferMode`
446
+ (`universal`/`linked` + `linkedGameIds`).
447
+ - _(Coming in 0.7.x: `getBalance` single-game player-token read; `getLinkedIdentities`
448
+ server-side.)_
449
+
450
+ ## [0.6.0] — 2026-07-01
451
+
452
+ Three additive browser flows for partner front-ends, built to the live backend contracts.
453
+
454
+ - **`InvoClient.getPendingCollect()`** — the player's own pending-to-collect list
455
+ (player-token `GET /api/sdk/transfers/pending`), PII-free. Each row's `kind`
456
+ (`identity_gate` → `approve*`, `receiving_confirm` → `confirmReceipt*`) tells you the
457
+ action; typed fields incl. `held` / `holdReason` / `stepUpRequired`.
458
+ - **First-enrollment OTP grant** — `enrollmentBegin()` / `enrollmentVerify(code)` for
459
+ `ENROLLMENT_REQUIRES_AUTHORIZATION` (send OTP to phone+email, verify, then retry the
460
+ same `enrollPasskey()` — the server grant is auto-consumed). New `InvoError` helpers
461
+ `isEnrollmentAuthorizationRequired` / `isEnrollmentProofRequired`.
462
+ - **Typed approve/confirm holds** — `approve*`/`confirmReceipt*` now surface a typed
463
+ `holdReason` (from `error_code ?? code`) on HTTP 202 holds, plus `risk` /
464
+ `guardianApproval` / `pollEndpoint` on approve. `RECIPIENT_IDENTITY_PENDING` correctly
465
+ surfaces on confirm-receipt. Success carries no `holdReason`.
466
+
467
+ ## [0.5.0] — 2026-07-01
468
+
469
+ Support partner `metadata` end-to-end on the purchase flow (additive, backward-compatible).
470
+
471
+ - **`PurchaseCompletedData.metadata?`** — the `purchase.completed` webhook now echoes your
472
+ metadata back (all rails); `event.data.metadata` is typed.
473
+ - **`purchaseCurrency`** now accepts and forwards `metadata` (the direct `/purchase-currency`
474
+ endpoint accepts it too, matching `createCheckout`).
475
+
476
+ ## [0.4.2] — 2026-06-30
477
+
478
+ Fixes from an independent line-by-line audit against the live backend.
479
+
480
+ - **`linkDevice` now works.** `device/link/webauthn/begin` returns a wrapped
481
+ `{ link_id, options }` body (challenge nested under `options`) and binds the
482
+ challenge to a server-generated `link_id`. The client now unwraps `options` and
483
+ echoes the server's `link_id` to `/complete` (it previously threw on an undefined
484
+ challenge and sent the wrong id).
485
+ - **`InvoError.code` is now populated for the direct purchase rail + guardian flows.**
486
+ `errorFromResponse` reads `error_code` (SecureErrorHandler + `/purchase-currency`)
487
+ in addition to `code`, and promotes known no-code tokens (`flow_paused`,
488
+ `spending_limit_exceeded`, `receiver_not_enrolled_use_claim_code`) to `.code`. Fixes
489
+ `isDuplicateRequest` on the direct rail.
490
+ - **Guardian/minor routing.** The 202 guardian body also carries
491
+ `verification_method:"sms"`; the SDK now suppresses it (reports
492
+ `verificationMethod: undefined`) so a guardian-pending minor isn't routed into the
493
+ SMS-PIN UI. README example reordered to branch on `guardianApproval` first.
494
+
495
+ ## [0.4.1] — 2026-06-30
496
+
497
+ Docs only — replaced the README's internal-leaking "Deployment prerequisites"
498
+ (backend flag names, DB columns, gating mechanics) with a partner-facing
499
+ "Before you go live"; republished so the npm page README is current.
500
+
501
+ ## [0.4.0] — 2026-06-30
502
+
503
+ Additive release — more server reads, edge-ready webhooks, cancellation, and tooling.
504
+
505
+ - **`getInboundPending({ playerEmail | playerPhone })`** — live, unclaimed inbound
506
+ sends/transfers for a player (the source of truth behind the "you have X to collect"
507
+ badge; pairs with `transfer.claim_pending`).
508
+ - **`verifyWebhookAsync`** — Web Crypto variant of `verifyWebhook` that runs on
509
+ Cloudflare Workers / Deno / Vercel+Netlify Edge / Bun / browsers; and
510
+ **`createWebhookHandler`** — a zero-dep Fetch-API `(Request) => Promise<Response>`
511
+ webhook route handler (Next.js App Router, Workers, Deno, Hono, Bun).
512
+ - **`iterateItemPurchaseHistory`** — async iterator that pages through a player's
513
+ full item-purchase history.
514
+ - **Per-call `AbortSignal`** — every method accepts an optional `{ signal }`; an
515
+ aborted call throws `InvoError` code `ABORTED` and is never retried.
516
+ - **Tooling**: ESLint (+ lint in CI), changesets release automation, `SECURITY.md`,
517
+ and `CODEOWNERS`.
518
+
519
+ ## [0.3.0] — 2026-06-30
520
+
521
+ Additive release — new server capabilities plus transport resilience/observability.
522
+
523
+ - **Webhook verification** (`/server`): `verifyWebhook(rawBody, signatureHeader, secret | secrets, opts?)`
524
+ — constant-time HMAC-SHA256 over `${t}.${rawBody}`, 5-minute replay window,
525
+ multi-secret rotation; returns a typed `InvoWebhookEvent` discriminated union
526
+ (`purchase.*`, `item.purchased`, `transfer.*`, `payout.status_changed`, `webhook.test`).
527
+ Throws `InvoError` (`WEBHOOK_SIGNATURE_INVALID` / `WEBHOOK_TIMESTAMP_EXPIRED` /
528
+ `WEBHOOK_MALFORMED` / `WEBHOOK_SECRET_MISSING`). Server-only; the browser bundle
529
+ stays crypto-free. Independently security-audited.
530
+ - **`getPlayerBalance({ playerEmail | playerId })`** (`/server`): typed `player` / `balances` / `summary`.
531
+ - **Automatic retries**: network errors/timeouts, `429` (honoring `retry_after`), and
532
+ `5xx` are retried with exponential backoff + jitter. New config `maxRetries`
533
+ (default 2, `0` disables) and `retryBaseDelayMs` (default 250).
534
+ - **Observability hooks**: optional `onRequest` / `onResponse` / `onError` on both
535
+ entries (best-effort/non-throwing); `InvoError.requestId` carries the backend
536
+ request id for support/tracing.
537
+ - **Typed reads**: `confirmPayment` → `ConfirmPaymentResult`; `getOrderDetails` /
538
+ `getItemOrderDetails` → `OrderDetailsResult`; `getItemPurchaseHistory` →
539
+ `ItemHistoryResult` (previously untyped `Record`). All keep `raw`.
540
+ - **Light validation**: `mintPlayerToken` and `createCheckout` require a non-blank
541
+ `playerEmail` (throws `INVALID_INPUT` before the network call).
542
+ - **License**: `package.json` `license` is now `SEE LICENSE IN LICENSE` (was
543
+ `UNLICENSED`); `LICENSE` rewritten as an explicit install-and-use grant for
544
+ building INVO integrations.
545
+
546
+ ## [0.2.1] — 2026-06-30
547
+
548
+ Docs only — no code change (republished so the npm page README is current).
549
+
550
+ - Rewrote the README into a complete integration/deployment guide: capability
551
+ overview, architecture, deployment prerequisites, per-flow sections (currency
552
+ purchase, item purchase, sends, transfers, passkeys), webhooks, errors, and a
553
+ full API reference for both entries.
554
+ - Added INVO console onboarding: `https://console.invo.network` (production) and
555
+ `https://dev.console.invo.network` (testing/sandbox), mapped to their API base URLs.
556
+
557
+ ## [0.2.0] — 2026-06-30
558
+
559
+ Adds **item purchase** (spend existing game currency on an in-game item, §4.8) — an
560
+ additive, server-only surface.
561
+
562
+ - `InvoServer` (`/server`): `purchaseItem`, `getItemPurchaseHistory`, `getItemOrderDetails`.
563
+ - Server-side, game-secret auth — no passkey, no real money, no payment rail (it's a
564
+ balance debit). Grant the item off the `item.purchased` webhook.
565
+ - Client-side guards: required fields (trim-checked), `itemQuantity` integer `1..1000`,
566
+ prices `> 0` and `<= 999999.99` (magnitude-safe 2-decimal check), and
567
+ `totalPrice == unitPrice × itemQuantity (±0.01)` compared in integer cents.
568
+ - Load-bearing response fields (`transaction_id`, `order_id`) throw `INVALID_RESPONSE`
569
+ if missing on a 200.
570
+ - `InvoError` helpers: `isInsufficientBalance` (gated to 400; not the `429` throttle),
571
+ `isDuplicateRequest` (409), `retryAfter` (numeric or string `retry_after`); all
572
+ null-safe against non-JSON error bodies.
573
+ - Independently audited (2 agents) against handoff doc §4.8/§6/§8; contract verified,
574
+ error-classification edge cases fixed.
575
+
576
+ ## [0.1.0] — 2026-06-30
577
+
578
+ Initial scaffold.
579
+
580
+ - `InvoServer` (`/server`): `mintPlayerToken`, `initiateSend`, `initiateTransfer`,
581
+ `createCheckout`, `purchaseCurrency`, `confirmPayment`, `getOrderDetails`.
582
+ - Client-side purchase guards (§4.7): USD amount `0 < x ≤ 999.99`, required
583
+ `purchaseReference`, and `rail:"steam"` rejected before the network call
584
+ (`INVALID_INPUT` / `MISSING_PURCHASE_REFERENCE` / `WRONG_RAIL_ENDPOINT`).
585
+ - `InvoClient` (browser): `enrollPasskey`, `approveSend`/`approveTransfer`,
586
+ `confirmReceiptSend`/`confirmReceiptTransfer`, and `linkDevice` for the
587
+ interchangeable-methods flow (§4.6).
588
+ - Optional `refreshToken` hook: transparently re-mints and retries once on
589
+ `SDK_TOKEN_EXPIRED` (§11.2).
590
+ - Shared: typed `InvoError`, isomorphic HTTP client, WebAuthn JSON⇄binary helpers.
591
+ - Tests: HTTP layer, server request mapping + purchase guards, browser client
592
+ flows (enroll/approve/link/token-refresh), and WebAuthn serialization.
593
+ - Contracts extracted + auditor-verified against the INVO backend.
594
+
595
+ ### Hardening (independent red-team pass)
596
+
597
+ - **Guardian/minor `202` path no longer mismapped to `verificationMethod:"sms"`** —
598
+ `initiateSend`/`initiateTransfer` now return `verificationMethod: undefined` and a
599
+ `guardianApproval` block on the guardian path, so callers don't route into the
600
+ PIN UI by mistake (§4.3).
601
+ - `usdAmount` validation tightened: rejects non-plain-decimal strings
602
+ (`"0x10"`, `"1e2"`, whitespace) and >2 decimal places before any network call.
603
+ - Load-bearing response fields (`token`, `checkout_url`) now throw `INVALID_RESPONSE`
604
+ instead of silently surfacing as empty strings.
605
+ - `getOrderDetails` requires at least one of `orderId`/`transactionId`.
606
+ - Token refresh now re-runs the **whole** passkey ceremony on `SDK_TOKEN_EXPIRED`
607
+ (never replays a single-use assertion) and single-flights concurrent refreshes.
608
+ - `baseUrl` must be `https://` (localhost exempt) so the token/secret can't travel
609
+ in cleartext.
610
+ - Published tarball excludes sourcemaps (no proprietary source shipped).