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