@invonetwork/web-sdk 3.2.0 → 3.2.2

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