@invonetwork/web-sdk 3.2.0 → 3.2.1

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