@invonetwork/web-sdk 3.33.0 → 3.34.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.
package/CHANGELOG.md CHANGED
@@ -1,1490 +1,1506 @@
1
- # Changelog
2
-
3
- ## 3.33.0
4
-
5
- ### Minor Changes
6
-
7
- - Platform Commerce: buyer-approved balance purchases. `purchase({ requirePlayerApproval: true, returnUrl })` returns `status: "pending_approval"` with `approvalId` and `approvalUrl`; nothing is debited until the buyer approves on INVO's page. New `getApproval({ approvalId | clientRequestId })` and `cancelApproval(approvalId)` (`PlatformApprovalResult`), and error helpers `isBalanceUnavailable`, `isApprovalNotAvailable`, `isApprovalNotFound`, `isApprovalAlreadyEnded`. Webhooks: `platform_commerce.declined` (opt-in, never delivered through `*`); `metadata` on `platform_commerce.purchased` and `platform_commerce.refunded` (both legs). All additive.
8
-
9
- ## 3.32.0
10
-
11
- ### Minor Changes
12
-
13
- - Add `InvoError.isPaymentsPaused` for `PAYMENTS_PAUSED` (403): INVO has paused new payments on the developer account. Every call that starts a payment returns it; refunds, reads, balances, transfers and existing subscription renewals keep working.
14
-
15
- ### Patch Changes
16
-
17
- - 34f0767: Doc comment: `guarantee_covered` on `purchase.disputed` no longer says a lost coin chargeback costs you nothing; a coin purchase dispute reports what it charged you in `spent_coins_charged_usd`. No code or API change.
18
-
19
- ## 3.31.0
20
-
21
- ### Minor Changes
22
-
23
- - Types the backend fields that shipped 2026-10-20. All additive; nothing renamed or removed.
24
-
25
- - `platformCommerce.getStatus()` and every `getPurchaseHistory()` entry: `invoFeeUsd` (everything INVO kept on the sale) and `partnerShareUsd` (what you earned), USD decimal strings. `null` until the sale settles or when the split cannot be read; absent from an INVO release that does not send them. A later refund or lost dispute does not change them.
26
- - `purchase.disputed` (coin purchase, on close): `spent_coins_charged_usd`. On a lost dispute INVO takes back the coins the player still holds and charges you for coins already spent, at the price paid per coin before tax; `"0.00"` when nothing was charged.
27
- - Errors: `err.isRateLimited` (true on any 429; every rate-limit refusal now carries `error_code` `RATE_LIMITED`, `retry_after` and a `Retry-After` header). `err.retryAfter` falls back to the `Retry-After` header when the body has no `retry_after`; the raw header is on `err.retryAfterHeader`. `errorFromResponse` takes an optional fourth argument for it.
28
- - README: dispute holds on both tiers (the disputed amount is held from your earnings while a dispute you are responsible for is open), the spent-coin charge on a lost coin purchase dispute, and the payout minimum is now $10 (scheduled and on demand; it was $100).
29
-
30
- ## 3.30.4
31
-
32
- ### Patch Changes
33
-
34
- - cbf46e7: Docs and doc comments: INVO's hosted pages (hosted checkout on every rail, the hosted card page and the subscription payment confirmation page) show the INVO logo by default, or the game's own logo when one is set in the INVO console (Game settings, Checkout branding), with a "Secured by INVO" line at the bottom. The `CreateCheckoutInput.rail` comment and the README no longer say the pages are always INVO-branded. The logo is set in the console only; there is no new SDK call. No code or API change.
35
-
36
- ## 3.30.3
37
-
38
- ### Patch Changes
39
-
40
- - Docs and docstrings: `partnerFeeUsd` examples now read $0.50 on a $10.00 Open purchase ($0.65 on Merchant of Record), matching 3.5% + $0.15 / 5.0% + $0.15; the last "$0.65 on Open" examples are corrected.
41
- - Payouts: scheduled payouts (the 1st and 16th of each month, UTC, $100 minimum) are free; payouts requested on demand are 1% capped at $500 with a $100 minimum. Creator payouts keep the fee.
42
- - Release history in the README states the prices each earlier release shipped with again (3.18.0, 3.22.0), which 3.30.2 had overwritten with today's rates.
43
- - No code or API change.
44
-
45
- ## 3.30.2
46
-
47
- ### Patch Changes
48
-
49
- - Docs and docstrings follow the 2026-10-15 pricing: INVO card fee 3.5% + $0.15 on Open and 5.0% + $0.15 on Merchant of Record (was 3.5% + $0.30 and 5.5% + $0.50), plus 1.5% on cards issued outside the US; item purchases 5% (you keep 95%). Worked examples recomputed ($10.00 coin pack: $0.50 Open, $0.65 MoR). No code or API change.
50
-
51
- ## 3.30.1
52
-
53
- ### Patch Changes
54
-
55
- - Demo key: `POST /transfers/{id}/approve` no longer returns the claim code to the sender's browser (`claimCode` is always `null`). The game server keeps it and collects for the recipient, so the browser never needed it.
56
- - UI kit: moves to INVO Demo Arcade on the demo key are described as delivered automatically once approved, matching the backend, instead of refunded after 24 hours.
57
- - Game server: a purchase is confirmed even when the signed webhook can't reach the server (for example a private `*.replit.dev` development preview, which refuses requests that don't come from a signed-in browser). While a purchase is pending, `GET /purchases/{ref}` reads the checkout's status from INVO server-side, with the session token kept on the server, and credits from INVO's answer. The webhook and the status read credit under the same ledger ref, so whichever lands first wins and the other is a no-op. The browser's word is never used.
58
- - `InvoServer.getCheckoutStatus({ sessionId, sessionToken })`: the server-side read of a hosted checkout's status.
59
- - Nothing removed or renamed.
60
-
61
- ## 3.30.0
62
-
63
- ### Minor Changes
64
-
65
- - Game layer: player-to-player **transfers and sends**. Both rails are approved with the sender's passkey on INVO's hosted page; the game server only starts them.
66
- - **Server routes:**
67
- - `GET /transfers/status`: whether transfers are on, who can receive and which recipient details to ask for.
68
- - `POST /transfers/token`: a short-lived player token for approving and collecting.
69
- - `POST /transfers`: `{ kind: "transfer" | "send", targetGameId, amount, recipientEmail?, recipientPhone?, senderPhone?, clientRequestId? }`.
70
- - **When they're on:** the public demo key and production keys. Other sandbox keys are off unless `INVO_TRANSFERS=on`, and `INVO_TRANSFERS=off` turns them off anywhere. The server option is `transfers: boolean | "auto"`.
71
- - **On the demo key:**
72
- - transfers are scoped to the project
73
- - the friend's email is mapped with `toDemoEmail`
74
- - both sides get fictional phones (`demoPhoneFor`), so a real address or number never reaches INVO
75
- - **On a real key:** the recipient's phone is required, and the sender's stored phone is used. `SENDER_PHONE_REQUIRED` when the game never stored one.
76
- - **Demo-key approval.** INVO's passkey page can't be completed by demo players, so the game server does both steps itself:
77
- - It approves in INVO's demo sandbox with `POST /transfers/{id}/approve`, using the new `invo.sandbox.approveDemoMove`.
78
- - It keeps the claim code in the store (`demoMoves`).
79
- - The recipient lists what's waiting with `GET /transfers/pending` and collects with `POST /transfers/{id}/collect`, which calls `claimCurrency` with the kept claim code.
80
- - These three routes answer `409 PASSKEY_REQUIRED` on real keys.
81
- - `InvoGameEconomy`:
82
- - Methods: `transferStatus()`, `prepareTransfers()`, `transferDestinations()`, `startTransfer(input)`, `approveTransfer(start)`, `pendingTransfers()` and `collectTransfer(item, approval)`.
83
- - `transferDestinations()` lists this game first (`thisGame`, send rail only; a transfer to your own game is refused), then INVO's destination list.
84
- - Status and start answers carry `approval: "passkey" | "sandbox"`.
85
- - Call the approve and collect methods directly from a click: they open INVO's hosted page.
86
- - New event: `transfer` (`TransferUpdate`).
87
- - New option: `invoFetch`.
88
- - UI kit:
89
- - `ui.openTransfers(tab?)` and a Transfer button in the HUD. The button shows a lock while transfers are off; `hideTransferButton` hides it.
90
- - A Send / Collect dialog with destinations and limits, a review step, the passkey step and claim codes.
91
- - The demo copy says transfers work between players of the project.
92
- - UI kit: `[hidden]` now always hides (the phone field on the demo key showed through `.invo-field`'s `display:flex`).
93
- - New types: `GameTransferKind`, `GameTransferStatus`, `GameTransferInput`, `GameTransferStart`, `GameTransferDestination`, `TransferUpdate` and `StoredDemoMove`. `ApproveHostedResult`, `DestinationGame` and `PendingCollectItem` are re-exported from the game entry.
94
- - Nothing removed or renamed.
95
-
96
- ## 3.29.1
97
-
98
- ### Patch Changes
99
-
100
- - Remix detection on Replit now uses `REPL_ID`: the same Repl keeps its project id when it moves from `*.replit.dev` (building) to `*.replit.app` (deployed), and `registerProject` re-registers the new webhook URL with the saved registration token. A different `REPL_ID` is a remix and gets a fresh project id. Outside Replit a changed public host still counts as a remix. The project file now records `replId`.
101
- - `GET /catalog` adds `demo` (true on the public demo key) and `playerFields.phone` (`"hidden"` on the demo key, `"first_sign_in"` otherwise); `/health` and `invoGameServerFromEnv` also report `demo`. The UI kit hides the phone field when the catalog says so.
102
- - Nothing removed or renamed.
103
-
104
- ## 3.29.0
105
-
106
- ### Minor Changes
107
-
108
- - Public demo sandbox (INVO game templates): on the demo key, `invoGameServerFromEnv` maps every sign-in to the demo sandbox's player email format for the fork's project (`toDemoEmail`) and gives the player a fictional 555-01XX phone (`demoPhoneFor`), so no real address or number reaches INVO. The project id comes from `INVO_PROJECT_ID`, else `.invo/project.json` (option `projectFile`), else a new one written there; a copied file on a different public host (a remix) gets a fresh id.
109
- - New `registerProject({ gameSecret, webhookUrl, file? })` (game-server entry): registers the fork on every start, stores the webhook signing secret and the registration token in the project file the first time, and handles a remix's `409 PROJECT_REGISTERED` by taking a fresh project id. `invoGameServerFromEnv` reads the webhook secret from that file when `INVO_WEBHOOK_SECRET` is not set, or from the new `webhookSecret` option.
110
- - `verifyInvoSignature(rawBody, header, secrets)`: the INVO webhook signature check under the name the template guide uses (same as `verifyWebhook`).
111
- - The key-environment lookup is retried on each call until it succeeds (a failure at boot no longer wedges the server), and a production error falls through to the sandbox lookup.
112
- - `InvoGameServerSetup.environment` is `"sandbox"`, `"production"` or `"resolving"`; `sandbox` is no longer `true` for a live key whose environment is still being looked up.
113
- - Nothing removed or renamed.
114
-
115
- ## 3.28.0
116
-
117
- ### Minor Changes
118
-
119
- - Going live is swapping the key. `invoGameServerFromEnv` now picks the environment from `INVO_GAME_SECRET`: the public demo key (`ivsdk_demo_...`, baked into INVO's game templates) is the sandbox; any other key is looked up once with `GET /api/sdk/key-environment` (production first, then the sandbox) and cached. `INVO_ENV` and `INVO_BASE_URL` still override it.
120
- - `X-Invo-Project-Id` is now sent on every call in both environments, so the first live call after go-live links the template project to your INVO account. `INVO_PROJECT_ID` is read when `projectId` is not passed. The id format is `proj_` + a 26-character uppercase Crockford ULID; `newProjectId()` (game-server entry) makes one.
121
- - New exports (server and game-server entries): `resolveEnvironment`, `baseUrlForKey`, `isDemoKey`, `EnvironmentUnknownError`, `PRODUCTION_BASE_URL`, `SANDBOX_BASE_URL`, `DEMO_KEY_PREFIX`.
122
- - Nothing removed or renamed.
123
-
124
- ## 3.27.0
125
-
126
- ### Minor Changes
127
-
128
- - Loyalty: `InvoServer.reportGameEvent({ playerEmail, eventType, eventId?, occurredAt?, payload? })` (`POST /api/sdk/loyalty/server-events`, game secret, trusted for rewards) and `InvoClient.reportGameEvent(...)` (`POST /api/sdk/loyalty/events`, player token). `eventId` is generated when omitted and returned; the server call retries with it. Types `GameEventType`, `ReportGameEventInput`, `ReportServerGameEventInput`, `ReportGameEventResult`.
129
- - New entry `@invonetwork/web-sdk/game-server`: the server half of a browser game's economy. `invoGameServerFromEnv` / `createInvoGameServer` serve sessions, the premium wallet (read from INVO), a soft-currency ledger, hosted checkout, signed-webhook crediting processed exactly once, idempotent item purchases (premium through `purchaseItem`, soft through the ledger), rate-limited earnings, loyalty events and rewards, under `/api/invo`. `createFileGameStore` (atomic JSON file) and `createMemoryGameStore`; `toNodeListener` adapts it to `node:http`. With secrets missing it answers `503 INVO_SETUP_REQUIRED` and keeps `/health` and `/catalog` up.
130
- - New entry `@invonetwork/web-sdk/game`: `InvoGameEconomy` (the browser client for that server: sign-in, wallet events, `buyItem`, `buyPremium` with popup or redirect checkout, batched `earn`, `reportEvent`) and `mountInvoUI`, a framework-free DOM kit (balance HUD, buy-currency modal, shop grid, sign-in, toasts) in the INVO palette, themeable by CSS variables. Holds no secret. Used by `@invonetwork/phaser` and `@invonetwork/three`.
131
- - `invoGameServerFromEnv` accepts `projectId` (sent to the sandbox as `X-Invo-Project-Id` on every call, never in production) and `fetch`. `InvoGameEconomy.checkSetup()` re-asks the server whether its INVO secrets are set; the UI kit's developer setup guide uses it to notice when the keys arrive.
132
- - The UI kit ships the INVO design: a glass wallet HUD with animated balance changes, a tabbed shop with lit item cards, ownership chips and stack pips, premium packs with a best-value ribbon, sign-in with field icons, a step-by-step developer setup guide, toasts, and bottom sheets on phones. It respects `prefers-reduced-motion`.
133
- - Nothing removed or renamed; the `.` and `./server` entries are unchanged apart from the two new methods.
134
-
135
- ## 3.26.1
136
-
137
- ### Patch Changes
138
-
139
- - Types: `Payee` gains `payable` and `payable_blockers` (`PayableBlocker`, exported from the server entry). Check `payable` before offering a payout to a creator.
140
- - Docs: refusals add `PAYEE_TERMS_NOT_ACCEPTED` (the creator hasn't accepted INVO's current Payee Terms yet), and removing a creator with a payout still being processed reports `payouts_in_flight_by_status`.
141
- - Nothing removed or renamed.
142
-
143
- ## 3.26.0
144
-
145
- ### Minor Changes
146
-
147
- - Server: `invo.payouts.removePayee(payeeId)` (`POST /api/partner-payees/{payeeId}/remove`): remove a creator from your program; the status becomes `closed`.
148
- - Types: `PayeeStatus` gains `closed`; `Payee` gains `erased`; `Payout` and `PayoutStatusChangedData` gain `return_reason_code` (typed `ReturnReasonCode`), `partner_message` and `owner_confirmation_required` (`Payout` also `owner_confirmed_at`). `PayoutStatusChangedData.status` and `previous_status` are typed `PayoutStatus`. `PayoutStatus` and `ReturnReasonCode` are exported from the server entry and from webhooks.
149
- - Docs: `requestPayout` takes exactly one of `payeeId` or `bankAccountId`; the comment no longer says a request without either defaults to your own bank. Refusal codes listed in full.
150
- - Behaviour on the API, not the SDK: partner payout reads and `payout.status_changed` no longer carry INVO's internal notes (`admin_note`), admin ids (`reviewed_by_admin_id`, `initiated_by_admin_id`) or the accounting provider's fields (`qb_vendor_id`, `qb_bill_id`, `qb_payment_reference`). They were never part of the documented contract; read `partner_message` for a note INVO writes for you.
151
- - Nothing in the SDK removed or renamed.
152
-
153
- ## 3.25.0
154
-
155
- ### Minor Changes
156
-
157
- - Server: `InvoServer.payouts`, partner payouts and creator payouts. `registerPayee` (`POST /api/partner-payees`), `listPayees`, `getPayee`, `resendPayeeInvite`, `requestPayout` (`POST /api/partner-payouts/request`, with `payeeId` to have INVO pay a verified creator from the earnings INVO owes you, or `bankAccountId` for your own verified bank), `getPayout`, `listPayouts` (optional `payeeId`) and `cancelPayout` (a creator payout still `requested`). Results keep the API's snake_case fields. Creators are INVO's customers: you see their status only, never their documents, tax id or bank details.
158
- - Webhook types: `payee.status_changed` is typed as `PayeeStatusChangedData`. `PayoutStatusChangedData` gains `payee_id`, `payout_method` and `returned_at`. Payout statuses now include `cancelled` and `returned`.
159
- - Nothing removed or renamed.
160
-
161
- ## 3.24.1
162
-
163
- ### Patch Changes
164
-
165
- - Player activity: on the recipient's entry for a send or transfer from another game, `grossAmount` and `feeAmount` are now filled in the recipient's currency (`grossAmount - feeAmount === amount`). They were `null` on every cross-game entry. Doc comment updated; no type change.
166
-
167
- ## 3.24.0
168
-
169
- ### Minor Changes
170
-
171
- - Player activity: send and transfer entries from `getPlayerActivity` / `iteratePlayerActivity` carry the fee. On the sender's entry `feeAmount` and `netAmount` (what the recipient gets) sit beside the gross `amount`; on the recipient's entry `grossAmount` and `feeAmount` sit beside `amount` (what arrived). While a send waits to be collected they show the fee that will apply; `null` when it ended without being collected, and on the recipient side of a currency-converting transfer. Purchases do not carry them.
172
- - Errors: initiate-send and initiate-transfer amount-limit refusals now carry `error_code` `AMOUNT_BELOW_MINIMUM` / `AMOUNT_ABOVE_MAXIMUM` with the limit. `err.isAmountBelowMinimum` (now also true for these, and on the wallet transfer route where `err.code` stays `INVALID_AMOUNT`), new `err.isAmountAboveMaximum`, `err.minimumAmount`, `err.maximumAmount` and `err.limitCurrencyName`. A sender phone that does not match the one on file now carries `PHONE_MISMATCH` (400); `err.isPhoneMismatch` covers it as well as `registerPlayer`'s 409.
173
- - Webhook types: `identity.passkey_reset` is typed as `IdentityPasskeyResetData` (`identity_id`, `reset_via`, `cooldown_until`, `deactivated_count`). It now also fires for an in-app recovery (`reset_via: "sdk"`) and can be subscribed to by name.
174
- - Nothing removed or renamed.
175
-
176
- ## 3.23.0
177
-
178
- ### Minor Changes
179
-
180
- - Webhook types: `PurchaseEventData` gains `dispute_fee_usd` (`string | null`, USD decimal such as `"15.00"`, `"0.00"` when INVO bears the fee) and `dispute_fee_charged_to_partner` (`boolean | null`), carried on a card `purchase.disputed` when the dispute closes. From November 8, 2026 the card dispute fee on Open-tier card sales (coin purchases, Platform Commerce card sales and subscription charges) is passed through to you at cost. A lost dispute is `purchase.disputed` with `dispute_status: "lost"`, not a separate event. README updated. Both fields optional; nothing removed or renamed.
181
-
182
- ## 3.22.0
183
-
184
- ### Minor Changes
185
-
186
- - e3895ab: 2026-10 pricing and new reads. Server: `getPlayerActivity({ playerEmail, limit?, cursor?, types? })`
187
- (`GET /api/sdk/players/activity`), one merged, newest-first page of a player's currency purchases,
188
- item purchases, Platform Commerce purchases, sends and transfers, and `iteratePlayerActivity`, which
189
- follows `nextCursor`. `platformCommerce.getPurchaseHistory({ playerEmail, limit?, cursor? })`
190
- (`GET /api/platform-commerce/purchase-history`, entries shaped like `getStatus`) and
191
- `platformCommerce.iteratePurchaseHistory`. `getTransferStatus` / `getSendStatus` results carry
192
- `expiryReason` once expired. Webhook types: `TransferEventData` gains `order_id`,
193
- `net_transfer_amount`, `claim_code_expires_at`, `from_game_id`, `to_game_id`, `from_player_id`,
194
- `expired_at`, `reason`, `expiry_reason` and `refunded_amount`; `payout.status_changed` is typed as
195
- `PayoutStatusChangedData`, with the payout fee fields `offboarding_fee_pct`, `offboarding_fee_usd`,
196
- `offboarding_fee_cap_usd` and `net_payout_usd`. New additive `err.publicCode`: the
197
- provider-neutral twin of a code (INVO's `error_code_public` on errors from the API). The SDK's own
198
- pre-network refusal of a Platform Commerce card total under $0.50 keeps `err.code` exactly as
199
- before and now also carries `err.publicCode === "BELOW_CARD_MINIMUM"` and `err.minUsd === "0.50"`;
200
- `err.isBelowCardMinimum` is true as before and accepts both spellings. Nothing removed or renamed. README: the
201
- Open card fee is 3.5% + $0.30 (was 4.5%); the chargeback guarantee is a Merchant of Record term
202
- (Open-tier card payments made before November 8, 2026 keep it); transfers are 10% (3.5% / 3.5% /
203
- 3%); payouts carry a 1% fee capped at $500 per payout; the hosted checkout reports a finished
204
- purchase as status `"completed"`; on `phoneMismatch`, call `updatePlayerPhone`. Additive only.
205
- - Player-confirmed phone change. Server: `requestPhoneChange({ playerEmail, newPhone })`
206
- (`POST /api/sdk/players/phone/change-requests`, 202, never auto-retried) returns
207
- `changeRequestId`, `status`, `expiresAt`, `delivery`, `confirmation` and `message`; INVO emails
208
- the player, who confirms on INVO's page (plus their passkey or enrolled device when they have
209
- one). `getPhoneChange(changeRequestId)` reads the request. Browser, with the player token, on
210
- the player's enrolled device: `listPhoneChangeApprovals()` and
211
- `approvePhoneChange(changeRequestId, { deviceFingerprint, decision?, sign | deviceSignal })`,
212
- which sends a `device_signal` over `phone-change|<id>|<nonce>|<timestamp>` (or
213
- `phone-change-deny|...`); new `phoneChangeSignalMessage()` builds that message. No method sends
214
- a confirmation code: games never collect it. `err.changeRequestEndpoint` on
215
- `PHONE_CHANGE_REQUIRES_VERIFICATION`; new error predicates `isConfirmOnInvoPage`,
216
- `isChangeRequestNotFound`, `isChangeRequestNotReady`, `isChangeRequestNotPending` (with
217
- `changeRequestStatus`), `isChangeRequestInProgress`, `isPhoneChangeLocked`,
218
- `isTooManyChangeRequests`, `isPhoneChangeUnavailable`, `isDeviceSignalRejected`,
219
- `isPhoneChangeRecoveryCooldown` (`PHONE_CHANGE_RECOVERY_COOLDOWN`, 409 on create and approve:
220
- a recent sign-in recovery; retry later, declining still works) and
221
- `isDeviceEnrolledAfterRequest` (`DEVICE_ENROLLED_AFTER_REQUEST`, 409 on approve). New
222
- `isPendingTransfersToOldPhone` / `isPendingTransfersToNewPhone`, which `updatePlayerPhone`
223
- now also answers (409, no counts) as well as the change request routes. Webhook
224
- type: `player.phone_changed` as `PlayerPhoneChangedData` (`new_phone` only for the requesting
225
- game). README section "Player-confirmed phone change": on `phoneMismatch` or
226
- `player.phone_changed`, never push a stored number back; ask the player. Additive only.
227
-
228
- ## 3.21.0
229
-
230
- ### Minor Changes
231
-
232
- - 0238b53: Player registration, phone changes and identity re-key. Server: `mintPlayerToken` takes optional
233
- `playerPhone` and `playerName`; with a phone, a player new to your title is created, and the
234
- result now carries `created` and `phoneMismatch` (previously dropped). New
235
- `registerPlayer({ playerEmail, playerPhone, playerName? })` (`POST /api/sdk/players`) and
236
- `updatePlayerPhone({ playerEmail, newPhone })` (`POST /api/sdk/players/phone`, never
237
- auto-retried). `initiateSend` / `initiateTransfer` results expose `identityRekeyed`,
238
- `playerToken`, `playerTokenExpiresAt`, `identityId` and `claimDeliveryPlanned`; approve results
239
- expose `claimDelivery`. New error predicates `isPlayerTokenStale`,
240
- `isPhoneChangeRequiresVerification`, `isPhoneMismatch`, `isPhoneShareRefused`;
241
- `isPlayerNotFound` also recognises the codeless `player_not_found` 404. A 403
242
- `PLAYER_TOKEN_STALE` on approve is surfaced, never auto-retried: re-mint and retry once.
243
- Additive only. README section "Registering players and changing their phone".
244
-
245
- ## 3.20.0
246
-
247
- ### Minor Changes
248
-
249
- - 1dc07df: Loyalty and rewards. Server: `InvoServer.getPlayerRewards(playerEmail)` reads one player's
250
- loyalty cards with the game secret (`GET /api/sdk/loyalty/players/rewards`). Browser, with the
251
- player token: `InvoClient.getMyRewards()` (the player's cards), `getMyVault()`,
252
- `redeemReward(vaultEntryId)` (the only response with a code; never auto-retried) and
253
- `getRewardsPageLink()` (INVO's hosted "My rewards" page). Every card step carries `progress`,
254
- `{ current, target }`, or `null` when unavailable; `state` decides completion. New error
255
- predicates `isRewardAlreadyRedeemed`, `isRewardNotFound`, `isRewardExpired`,
256
- `isRewardUnavailable` (`inventory_exhausted` / `conflict`); the server read's
257
- `PLAYER_NOT_FOUND` and `INVALID_PLAYER_EMAIL` use the existing `isPlayerNotFound` and
258
- `isInvalidPlayerEmail`. Additive only. README section "Loyalty and rewards".
259
-
260
- ## 3.19.0
261
-
262
- ### Minor Changes
263
-
264
- - 6940139: D-PRICE-012: a subscription card refund, and a lost chargeback not covered by the chargeback guarantee, now cost the partner the whole refunded amount, INVO's card fee included, exactly as a Platform Commerce card refund does. There is no separate payment processor fee on a refund any more: `processingFeeUsd` reads `"0.00"` and `processingFeeBasis` `"none"`.
265
-
266
- Additive, optional fields:
267
-
268
- - `RefundResult.cardFeeChargedToPartnerUsd` and `RefundResult.partnerDebitedUsd` on `subscriptions.refund` (the 200 receipt and the 202 `pending_approval` body). `undefined` on a receipt stored before this release.
269
- - `card_fee_charged_to_partner_usd` and `partner_debited_usd` on the `refund` block of `subscription.refunded` (`SubscriptionRefundDetail`) and on `purchase.disputed` (`PurchaseEventData`, subscription and Platform Commerce losses; `null` where not applicable).
270
-
271
- README: subscription refund costs, lost chargebacks and the "What did I earn?" answer updated.
272
-
273
- ## 3.18.0
274
-
275
- ### Minor Changes
276
-
277
- - 432fb75: INVO's 2026-09 card pricing. On card purchases the partner now pays INVO's card fee (4.5% + $0.30 on Open, 5.5% + $0.50 on Merchant of Record, plus 1.5% of the listed price (before tax) on a card issued outside the US); the player pays the listed price (plus tax where owed) and receives the listed coins. Fraud screening and a chargeback guarantee (a fraud chargeback on a card sale is covered by INVO) are included. Minimum card purchase $2.99 on coin purchases and Platform Commerce card sales, enforced from 2026-10-27. Card purchases only; purchases through a third-party storefront or payment rail are unaffected. All additive:
278
-
279
- - `PurchaseResult` and `CurrencyPurchaseQuote` gain `partnerFeeUsd`, `internationalCardFeeUsd` and `minPurchaseWarning` (`MinPurchaseWarning`: `{ code, minUsd, enforcedFrom, message?, enforced?, raw }`), each set only when INVO sends it. `processingFeeUsd` stays and reads `"0.00"`.
280
- - `FeeTakenFrom` gains `"partner"`. `UnacknowledgedPurchaseOutcome.feeTakenFrom` stays required; INVO always sends it, and should it ever be missing the SDK reads `"partner"` when the quote carries `partner_fee_usd`, otherwise `"coins"` as before.
281
- - `err.minUsd` and `err.enforcedFrom` on `BELOW_CARD_MINIMUM` (`err.isBelowCardMinimum`, which now also covers INVO's minimum card purchase). `err.isAmountBelowFee` is deprecated: `AMOUNT_BELOW_FEE` is no longer returned.
282
- - `acknowledgedTotalUsd` is still honored: INVO never charges more than it, and an older, higher fee-inclusive total is accepted with the true, lower total charged. Only a total below the true total is refused (`QUOTE_STALE`).
283
- - `partnerFeeUsd` and `internationalCardFeeUsd` are `string | null`: `null` only when the fee could not be booked when the purchase completed (the purchase succeeded; INVO books the fee shortly after). `internationalCardFeeUsd` is `"0.00"` on a US card or one whose country is unknown, and always `null` on a quote (no card yet). The quote also carries `feeTakenFrom`, and `ifUnacknowledged.partnerFeeUsd`.
284
- - `createCheckout()` and the Platform Commerce card leg of `platformCommerce.purchase()` return `minPurchaseWarning` while an amount under the minimum card purchase is still accepted. `BELOW_CARD_MINIMUM` also answers a card charge under the $0.50 card floor at any date, on coin purchases, hosted checkout and Platform Commerce: `err.minUsd` reads `"0.50"` there, with no `err.enforcedFrom`.
285
- - `purchaseCurrency()` accepts `country` and `subdivision`, the place you quoted with. On Merchant of Record INVO uses it only when it cannot read the buyer's tax location from the card; without it such a purchase is refused with `409 TAX_PLACE_UNAVAILABLE` (new `err.isTaxPlaceUnavailable`, `err.untaxedTotalUsd`), nothing charged.
286
- - Platform Commerce card refunds: `cardFeeChargedToPartnerUsd` and `partnerDebitedUsd` on the refund result and `card_fee_charged_to_partner_usd` / `partner_debited_usd` on `platform_commerce.refunded` (the card fee is not returned on a refund; it stays charged to you).
287
- - Webhook types: `purchase.completed` gains `partner_fee_usd` and `international_card_fee_usd` (nullable); `purchase.disputed` gains `guarantee_covered` (lost Platform Commerce card sale and subscription disputes only; never on a coin purchase dispute), `order_type`, `developer_revenue_reversed_usd`, `subscription_id`, `period_seq` and `processing_fee_usd` (the processor fee a non-fraud lost subscription chargeback charges you, as a refund does); `platform_commerce.purchased` gains `international_card_fee_usd` (already included in `fee_breakdown.platform_fee`); `subscription.renewed`'s split gains `international_card_fee_usd` (the same figure as `pass_through_fees_usd`, never add them; `partner_revenue_usd` stays gross).
288
- - Behaviour to notice: an unacknowledged $10.00 coin purchase now credits the full 100.00 coins (93.70 under the earlier pricing); an older fee-inclusive acknowledged total is accepted and the lower true total charged; `AMOUNT_BELOW_FEE` is no longer returned.
289
- - README and doc comments: every card fee figure, the Tiers table (card rates, international fee, who pays, fraud screening, chargeback guarantee, minimum card purchase) and the quote example ($10.00 charges the player $10.00; your fee is $0.75 on Open).
290
-
291
- ## 3.17.0
292
-
293
- ### Minor Changes
294
-
295
- - 28a96bf: Webhook payload types: `PurchaseEventData` gains `payment_intent_id` / `charge_id` / `dispute_id` (`string | null`: `null` on a Steam chargeback), `rail`, `steam_transid`, `fully_refunded`, `currency_debited` and `new_balance`. Steam chargebacks now arrive as `purchase.disputed` with the same keys as a lost card dispute, and a Steam partial refund arrives as `purchase.refunded` with `fully_refunded: false`. README: if you revoke on `purchase.refunded`, handle `purchase.disputed` the same way. All additive and optional.
296
-
297
- ## 3.16.1
298
-
299
- ### Patch Changes
300
-
301
- - 9dd2bf5: README: the `isDuplicateClientRequestId` note describes only what the caller sees. Documentation only.
302
-
303
- ## 3.16.0
304
-
305
- ### Minor Changes
306
-
307
- - 58143c2: `warnings` on `createCheckout()` results (typed `CheckoutWarning[]`, mapped from the additive `warnings` field): a checkout session sells game currency, and `metadata` carrying `item_id` / `item_name` now returns `ITEM_METADATA_ON_CURRENCY_SESSION`, pointing to `platformCommerce.purchase` for item sales. New error helpers: `err.isDuplicateClientRequestId` (409 `DUPLICATE_CLIENT_REQUEST_ID` on a Platform Commerce card purchase, with `order_id` / `order_status`; `err.isDuplicateRequest` is also true), `err.isTrialAmountBelowFeeFloor` (400 `TRIAL_AMOUNT_BELOW_FEE_FLOOR`; the message names the smallest accepted trial price) and `err.isIdentityCheckUnavailable` (503 `IDENTITY_CHECK_UNAVAILABLE` on claims and confirm-receipt, retryable). `err.isAmountBelowMinimum` now also covers `purchaseItem`, whose `totalPrice` is rounded to cents. README: refunds take back only the coins still held from that purchase, chargebacks up to the purchase's coins from the available balance, never below zero. All additive and optional.
308
-
309
- ## 3.15.0
310
-
311
- ### Minor Changes
312
-
313
- - 5adf010: `cards.createSetupSession()` takes optional `playerName` and `playerPhone` (mapped to `player_name` / `player_phone`). When the member is new to the game and `playerName` is sent, INVO creates the member exactly as `subscriptions.create` does and then mints the card link, so a brand-new signup can save a card before a paid trial (`subscriptions.create` with `trialAmountUsd` and `playerCardId`). Without `playerName` an unknown member is still `err.isPlayerNotFound` (404). A known member is never re-created or renamed by this call. New `err.isPlayerCreateFailed` (503 `PLAYER_CREATE_FAILED`); a phone already on another member answers `err.isPhoneShareApprovalRequired` (409). The SDK refuses a blank or over-255-character `playerName` and a non-E.164 `playerPhone` before the network (`INVALID_INPUT`, status 0). README: the card page and paid-trial sections show the new-signup order. All additive and optional.
314
-
315
- ## 3.14.2
316
-
317
- ### Patch Changes
318
-
319
- - README: the Merchant of Record chargeback threshold is measured on the previous complete calendar month. Documentation only.
320
-
321
- ## 3.14.1
322
-
323
- ### Patch Changes
324
-
325
- - README: Merchant of Record is applied for from the Selling & Tax page in the INVO console (the page name was wrong in 3.14.0). Documentation only.
326
-
327
- ## 3.14.0
328
-
329
- ### Minor Changes
330
-
331
- - 8f2298b: `credited` and `reasonCode` on `confirmPayment()` and `steamFinalizePurchase()` results (mapped from the additive `credited` / `reason_code` response fields; `status` is unchanged and still means the payment succeeded, so report a completed purchase only when `credited` is `true`). Merchant of Record receipt fields `receiptNumber` / `receiptUrl` on `purchaseCurrency()`, `getOrderDetails()`, `CheckoutClient.getPurchaseStatus()`, `platformCommerce.getStatus()` and `firstCharge`, and `receipt_number` / `receipt_url` (plus `tax_treatment` on `purchase.completed`) on the purchase, Platform Commerce and subscription webhook payload types. README: the tier's effect on responses (`tax_treatment: "partner_responsible"` on Open, receipts and the chargeback reserve on Merchant of Record). Platform Commerce card refunds in parts: optional `refundRemaining` / `confirmAdditionalRefund` on `platformCommerce.refund()`, optional `partialRefund` / `adopted` / `refundedTotalUsd` / `chargeTotalUsd` / `remainingUsd` on its result, and `err.isRefundRemainingRequiresConfirmation` / `err.isRefundRecentlyIssued` / `err.isRefundNotCompleted` (`err.isAlreadyRefunded` is now false for the two refund-in-parts refusals). All additive and optional. README: subscription card charges are 4% + $0.30 on Open and 5% + $0.50 on Merchant of Record (were 7% + $0.30 and 8.5% + $0.30); international card and currency conversion costs on subscriptions pass through at cost; chargebacks by tier; Merchant of Record is applied for from the console.
332
-
333
- ## 3.13.0
334
-
335
- ### Minor Changes
336
-
337
- - INVO's card fee on coin purchases, paid trials, and the two tiers.
338
-
339
- **Coin purchases carry INVO's card fee: 3.5% + $0.30** of the price (on the Open tier), never less than the card cost. `purchaseCurrency` charges in the same request, so there are now two shapes and you pick one by what you send:
340
-
341
- - **Quote, show, acknowledge.** New `server.quoteCurrencyPurchase({ playerEmail, usdAmount, country?, subdivision? })` calls `POST /api/currency-purchases/quote`. It moves no money and creates nothing, and returns `totalUsd`, `amountCents`, `subtotalUsd`, `processingFeeUsd`, `coins`, `currencyName`, a camelCase `breakdown` and `ifUnacknowledged`. Show the player `totalUsd`, then pass it as the new optional `acknowledgedTotalUsd` on `purchaseCurrency`: the card is charged that total, to the cent, and the coins are priced off `usdAmount`. $10.00 quotes $10.65.
342
- - **Send only `usdAmount`.** The card is charged exactly `usdAmount`, never more, and the fee comes out of the coins: $10.00 credits 93.70 coins at the default 10 per USD.
343
-
344
- A `success` result now also carries `processingFeeUsd`, `feeTakenFrom` (`"charge"` or `"coins"`), `coinsCredited` and `chargeTotalUsd`. New error helpers: `err.isQuoteStale` (409 `QUOTE_STALE`, with `err.expectedTotalUsd` and `err.acknowledgedTotalUsd`) and `err.isAmountBelowFee` (400 `AMOUNT_BELOW_FEE`). Nothing is charged on either. `acknowledgedTotalUsd` is shape-checked locally (a positive two-decimal amount) with a ceiling above the largest price, because the fee rides above INVO's card maximum.
345
-
346
- **Refunds of coin purchases:** only unspent coins are refundable; spent coins are never refunded. Documented; no SDK call refunds a coin purchase.
347
-
348
- **Paid trials on card subscriptions.** `subscriptions.create` accepts `trialAmountUsd` (with `trialDays` or `trialEnd`, card only, at least 0.50 and less than `amountUsd`): period 1 is charged the trial price inside the call and `amountUsd` from period 2. The consent object accepts `disclosedTrialAmountUsd`, `disclosedTrialDays` and `disclosedTrialEnd`, and returns `disclosed_trial_amount_usd`, `disclosed_trial_days` and `disclosed_trial_end`. The subscription gains `trialAmountUsd` and, on create and finalize bodies, `trialAmountCoinsEstimate`. Webhook types: `is_trial` on `subscription.renewed`; `is_trial` and `trial_amount_usd` on the trial period's `payment_failed`, `past_due`, `authentication_required` and `expired` (new `SubscriptionTrialEventFields`); `expire_cause` (`"trial_payment_failed"`) on `subscription.expired`. New error helpers: `isPaymentMethodRequired`, `isTrialAmountInvalid`, `isTrialAmountRequiresTrial`, `isTrialAmountNotSupportedForFunding`, `isConsentDisclosedTrialInvalid`. The SDK refuses, before the network and with INVO's own codes, a `trialAmountUsd` without a trial, with `walletOnly: true`, or on `steamInit`; the $0.50 floor and the "less than `amountUsd`" rule are left to INVO.
349
-
350
- **README:** a new Tiers section (Open by default: you are the seller and handle tax; Merchant of Record by application: INVO is the seller and handles tax; fees per tier), the coin fee flow, the refund rule and paid trials. Every statement that INVO is the merchant of record on the card rail for everyone is removed.
351
-
352
- All additive: no export was removed, renamed or retyped, and every new field on an existing type is optional.
353
-
354
- ## 3.12.1
355
-
356
- ### Patch Changes
357
-
358
- - Docs: subscription packages.
359
-
360
- The README's Subscriptions section gains a **Subscription packages** part. A package (the API calls it a plan) is what a developer sells: a name, a price, a billing interval and the `item_id` the game checks. Packages are created, edited, closed and reopened in the INVO dashboard with the developer's own sign-in, never with the game secret or a player token, so this SDK does not wrap them and has no `packages` or `plans` namespace. That is deliberate.
361
-
362
- Nothing about an integration changes. `server.subscriptions.create(...)` and `steamInit(...)` still subscribe a member to an `itemId`, webhooks carry the same payloads, and entitlement still comes from `subscription.renewed`. A package's subscriber counts and monthly revenue are measured per title and `item_id`, so a new package immediately shows the members already subscribed to its item. The section also covers the two counts (`subscriber_count` on basis `active`, `live_subscriber_count` on basis `live`), who a price change applies to, and that closing a package cancels nobody. Full guide: https://docs.invo.network/docs/subscriptions-packages/
363
-
364
- Doc correction: the subscription refund daily limit. The README and the `subscriptions.refund` JSDoc said a game's daily self-serve refund limit is $500 by default. It no longer is: by default the limit is never lower than the largest single subscription charge (`25000.00` USD today), so any single period can always be refunded on its own, and if INVO raises the per-charge maximum the limit rises with it. INVO can still set a specific limit for one game, which applies as set, even if lower. Everything else about refunds is unchanged: reaching the limit exactly still runs, going over it answers HTTP 202 `pending_approval`, and approved requests do not count toward the day. The sandbox recipe now says how to see a 202 (ask INVO for a low limit on the sandbox game).
365
-
366
- Documentation only. No export was added, removed, renamed or retyped.
367
-
368
- ## 3.12.0
369
-
370
- ### Minor Changes
371
-
372
- - The card maximum is INVO's, not the SDK's.
373
-
374
- **INVO raised the maximum single card charge from $999.99 to $100,000.00 on 2026-09-18, and this package was refusing it.** The old limit was enforced client-side and threw before any network call, so a partner charging $50,000 failed inside the SDK and INVO never saw the request. The backend raise was invisible to every SDK user until this release. Per-customer velocity limits rose with it, to 100,000 per hour, 200,000 per day and 1,000,000 per month, all enforced by INVO.
375
-
376
- **The design decision: the floor is a fact, the ceiling is a policy, and only facts belong in a client.**
377
-
378
- $0.50 is the card rail's own minimum charge. Below it nothing settles in any environment, INVO holds it as a plain constant rather than a setting, and no configuration makes a smaller amount chargeable. That check stays exactly where it was and still throws before any request (`BELOW_STRIPE_MINIMUM`, `err.isBelowCardMinimum`).
379
-
380
- The maximum is the opposite. It is a runtime setting an INVO admin edits without a deploy, and it differs between sandbox and production. Any number pinned in a published package is stale the moment somebody changes it, and the only remedy is a release, which is precisely the failure this release is repairing. So the local ceiling is **removed** rather than re-pinned at $100,000.00. It was not replaced by a fetch of the live limits either: that would turn one purchase call into two network calls, add a failure mode and a cache to a money path, and still be a snapshot rather than the truth at the moment of charge, because only the request itself is evaluated against the setting in force.
381
-
382
- What remains is a structural bound. `usdAmount` and a card `totalPrice` must still be a positive amount with at most two decimals, and must still be at most `999999.99`, the same house ceiling every other money field in this SDK uses. That figure is deliberately **above** the largest value INVO's setting is permitted to take, so it can never refuse an amount INVO would have accepted. The invariant for anyone editing this later: the local bound must never be tighter than the server's maximum possible limit. This SDK may cost you a wasted round trip. It must never cost you a sale that a package upgrade would have allowed.
383
-
384
- **What changed for you**
385
-
386
- - Amounts between `999.99` and `999999.99` are now sent instead of being rejected locally. Nothing that worked before stops working; the validation only loosened.
387
- - `err.isAboveCardMaximum` is unchanged and still means what it always meant, but it now arrives only from INVO (a `400`), never from the SDK. Nothing was charged.
388
- - An amount above `999999.99` now throws `INVALID_INPUT` where it previously threw `ABOVE_CARD_MAXIMUM`. That range is malformed input, not a policy refusal, and INVO classifies it the same way.
389
-
390
- **When INVO refuses an amount the SDK allowed**, catch `err.isAboveCardMaximum`. `err.message` carries the figure that was in force for that request, for example "Card purchases must be $100,000.00 or less." Do not retry it unchanged: lower the amount, split the sale, or ask INVO to raise the setting. The live figure for a tenant is also the `max_amount` of the hosted checkout's `validate-game` read, next to `min_amount`; read that if you want to show a limit in your own UI, and re-read it, because it can change under you. A velocity limit is a `429` with `err.retryAfter`, not this error.
391
-
392
- **README: the minimum is $0.50.** The docs said only `0 < x <= 999.99` and left the floor unstated. They now state $0.50, which is what INVO advertises and what the card rail actually enforces. A $1.00 minimum was advertised by INVO's own checkout read until 2026-09-18 and was enforced nowhere; it is gone rather than enforced, because enforcing it would newly refuse charges between $0.50 and $0.99 that settle today.
393
-
394
- No export was added, removed, renamed or retyped.
395
-
396
- ## 3.11.0
397
-
398
- ### Minor Changes
399
-
400
- - The purchase status read, and the subscription fee is 7%.
401
-
402
- **A buyer can always be told what happened to the money they paid.** `invo.checkout` (and the standalone `CheckoutClient`, for a page with no player token) reads `GET /api/checkout/sessions/<id>`, authenticated by the SESSION token; the id in the path is a label, not a credential. `getPurchaseStatus({ sessionId, sessionToken })` reads once; `waitForPurchase({ ..., intervalMs, timeoutMs, maxAttempts, signal, onUpdate })` polls until INVO says it is finished and returns that result. Six statuses, four of them terminal, plus `orderId`, `coinsCredited` / `transactionId` / `newBalance` on a credit, `reasonCode` + a player-safe `message` on a refusal, and both money figures (`amountChargedUsd`, `listedUsd`) so a buyer billed 206.29 for a 200 pack can be shown where the 6.29 went.
403
-
404
- `terminal` is read off the response and is NEVER recomputed from `status`, so a status a later backend introduces cannot make this build decide a purchase finished, or finished well. A status it does not recognise is not terminal and is never a success. `paid_pending_credit` is deliberately not terminal at any age: INVO's reconciler recovers a stalled credit. A failed poll is not a failed purchase: network, timeout, 429 and 5xx are polled through; 401, 403 and 410 are raised at once (`isWrongSessionPurpose`, `isCheckoutSessionMismatch`, `isCheckoutSessionExpired`). On the cap `waitForPurchase` returns the last result it read rather than throwing, so the page keeps showing something true.
405
-
406
- `CheckoutPurchaseStatus` is a widened union (`… | (string & {})`), not a literal one, and a tsc test pins that partner code storing or comparing an unknown status still compiles, which is the fix 3.10.0 had to make to `RefundResult` after the fact. It is named `Checkout…` because `PurchaseStatus` is already the direct `purchaseCurrency` result and is unchanged. New: `CheckoutClient`, `InvoClient.checkout`, `isPurchaseCredited` / `isPurchaseRefused` / `isPurchaseRefunded` / `isPurchaseExpired`, `nothingWasCharged` (true only where INVO said no money was taken; everything else, an unknown code included, happened after the card was charged, so never put a Try again on it), and the types `PurchaseStatusResult`, `PurchaseStatusInput`, `WaitForPurchaseInput`, `PurchaseRefusalReason`, `PurchaseCredited` / `PurchaseRefused` / `PurchaseRefunded` / `PurchaseExpired`, `CheckoutClientConfig`.
407
-
408
- `createCheckout()` now also returns `sessionToken`, read from INVO's `session_token` field (backend commit `856fa266`) and falling back to the `checkout_url` query string only for a server that predates it, so nothing has to parse a URL to use the read. The two cannot disagree, and if a response ever carried both and they differed the field wins, because a query-key spelling is not a contract.
409
-
410
- **Doc fix: INVO's subscription fee is 7% plus $0.30, not 10%** ($9.99 pays INVO $1.00 and you $8.99). Subscriptions became their own rate on 2026-09-17; item purchases stay at 10/90. No code change.
411
-
412
- **Not included: withdrawals.** INVO's withdrawal request and history reads gained additive `kyc_hold`, `kyc_hold_reason` and `next_steps` fields on 2026-09-17. This package exposes no withdrawal surface at all, so there is nowhere for them to go, and adding one is a separate decision rather than part of a documentation pass.
413
-
414
- **Fixed: the User-Agent version had drifted.** `SDK_VERSION` was left at `3.10.0` when 3.10.1 published, so every server call from 3.10.1 reported a version that was not the one running, and the test pinning it to `package.json` was failing on `main`. Back in step, and the pin is green.
415
-
416
- ## 3.10.1
417
-
418
- ### Patch Changes
419
-
420
- - `linkDevice()` takes no arguments. The server mints the link id, so requiring one was wrong: callers had to invent a placeholder. The parameter stays optional and any value passed is still sent and ignored by the server, so code written against 3.10 keeps working unchanged. The README now also states that a tenant whose players enrol a passkey on the tenant's own domain MUST offer `linkDevice()`, because that credential can only be asserted on that tenant's origin, and that recovery is never the answer to `ENROLLMENT_REQUIRES_PROOF`.
421
-
422
- ## 3.10.0
423
-
424
- ### Minor Changes
425
-
426
- - f66103c: Card-only subscriptions and subscription refund guardrails (INVO backend, 2026-09-17). Everything here is additive: no field, type or behaviour of an existing call was removed or renamed.
427
-
428
- **Card-only subscriptions (behaviour change on INVO's side, no type changes).** A card subscription's card is now charged the full price every period; the member's coin wallet never pays for it and never moves. Steam subscriptions are unchanged (wallet first, Steam tops up the shortfall).
429
-
430
- - `subscription.renewed` on the card rail: `funding.balance_applied_coins` is always `"0.00"`, `funding.card_charged_usd` is the price, `mint_order_id` is never `null`.
431
- - Every paid card renewal also emits `purchase.completed` with `data.metadata.source === "subscription_renewal"`. Do not grant currency from it; `subscription.renewed` is the entitlement signal.
432
- - A member with no saved card fails with `failure_code: "no_payment_method"` whatever their balance. New additive `failure_code`: `wallet_negative`.
433
- - `walletOnly` is marked `@deprecated` (still accepted and returned): a wallet-only card subscription can never be paid (`failure_code: "wallet_only"`).
434
- - `subscription.authentication_required`: `card_amount_usd` now equals `amount_due_usd` on card challenges.
435
- - Doc fix: the `amountUsd` JSDoc now states the per-charge ceiling of `25000.00` (it still said `500.00`), and `SubscriptionExpiredData` no longer says `steam_containment` is sent.
436
-
437
- **Subscription refund guardrails.**
438
-
439
- - `subscriptions.refund` can now return a refund request. `RefundResult` stays a single interface (its `status` is typed `"refunded" | "pending_approval" | (string & {})`, so any string still assigns and compares); branch with the new `isRefundPendingApproval(r)` type guard, which narrows to `RefundPendingApproval`. `"pending_approval"` is the new HTTP 202: the refund would exceed the game's daily self-serve limit ($500 by default), nothing moved, and INVO reviews it as a refund request (`requestId`, `requestStatus`, `requestedAmountUsd`, `requestedAt`, `dailyCapUsd`, `executedTodayUsd`, `message`). Both carry every receipt field; the `request*` fields are optional on `RefundResult` and required on `RefundPendingApproval`. The status string is passed through from INVO unchanged.
440
- - New optional result fields: `warnings` (`REASON_RECOMMENDED`, `REASON_TRUNCATED`), `subscriptionCanceled`, `subscriptionStatus`, `processingFeeUsd`, `processingFeeBasis`, `processingFeeBorneBy`, `processingFeeTransactionId`, `partnerTotalReversedUsd`, `initiation`, `refundRequestId`. `undefined` on receipts stored before the change.
441
- - `reason` is documented as recommended now and required after a notice period. Refunds run within 30 days of the charge. A full refund cancels the subscription. Card-only periods are refunded in cash, partial included. The partner bears the card processor fee. INVO emails the member.
442
- - New `InvoError` classifiers: `isRefundsNotEnabled` (403), `isRefundWindowClosed` (409), `isRefundRequestPending` (409), `isRefundRequestRejected` (409), `isConcurrentRequest` (409), `isRefundMismatch` (502), with body accessors `refundRequestId`, `decisionReason`, `periodChargedAt`, `refundWindowDays`, `refundWindowClosedAt`.
443
- - New webhook types: `subscription.refund_requested`, `subscription.refund_approved`, `subscription.refund_rejected` (`SubscriptionRefundRequestData`, `SubscriptionRefundApprovedData`, `SubscriptionRefundRejectedData`). Additive fields on `subscription.refunded` (`refund.processing_fee_*`, `refund.partner_total_reversed_usd`, `initiation`, `refund_request_id`, `subscription_canceled`) and `subscription.canceled` (`cancel_cause: "full_refund"`).
444
- - New exports: `isRefundPendingApproval`; types `RefundReceipt`, `RefundPendingApproval` (both extend `RefundResult`), `RefundWarning`, `RefundInitiation`, `RefundProcessingFeeBasis`.
445
-
446
- **Compatibility.** Additive only. Code that compares `status` to any string, builds `RefundResult` mocks with a `string` status, or `extends`/`implements` `RefundResult` keeps compiling (pinned by a tsc test). `subscription.refunded`, `subscription.refund_approved` and, on a full refund, `subscription.canceled` are sent together and may arrive in any order.
447
-
448
- README: the Subscriptions section states card-only funding, the renewal `purchase.completed` trap, the refund limits and the 202, the new events and classifiers, and "what did I earn" now subtracts `partner_total_reversed_usd`.
449
-
450
- ## 3.9.0
451
-
452
- ### Minor Changes
453
-
454
- - The INVO-hosted card page is the recommended way to save a card for a subscription.
455
-
456
- New on `invo.cards`:
457
-
458
- - **`createSetupSession({ playerEmail, successUrl?, cancelUrl?, metadata? })`** ->
459
- `{ sessionId, cardSetupUrl, expiresAt, raw }` (`POST /api/checkout/card-setup-sessions`,
460
- game secret header). Mint a 10-minute link server-side, send the member to `cardSetupUrl`
461
- (top-level, never framed), and read the saved card's `id` back from `cards.list`; it appears
462
- there immediately, carries the off-session consent a subscription needs, and no event fires
463
- for it. No browser code, no client secret, no card processor named anywhere, so INVO can change
464
- processor without partners changing anything. Never auto-retried: each call mints a fresh link.
465
- Script-scheme `successUrl` / `cancelUrl` values are refused before the network (`INVALID_INPUT`,
466
- status 0), matching INVO's own rule.
467
- - `beginSetup` / `confirmSetup` are now documented as the **processor-bound alternative**: they
468
- hand back a `clientSecret` only the current processor's client library can consume, so a card
469
- form built on them needs rework when INVO changes processor.
470
-
471
- New error classifiers: `isPlayerNotFound` (404 `PLAYER_NOT_FOUND`: the card page never creates
472
- players), `isInvalidPlayerEmail` (400 `INVALID_PLAYER_EMAIL`), `isInvalidInput` (`INVALID_INPUT`,
473
- at status 0 from the SDK's own guards or 400 from INVO for a script-scheme URL).
474
-
475
- Fixed: `subscriptions.get(id, { includePlayer: true })` never populated `player`. INVO puts
476
- `player_email` / `player_name` on the subscription object itself, not in a separate block; they
477
- are now surfaced as `subscription.playerEmail` / `subscription.playerName`, and `player` is
478
- derived from them.
479
-
480
- README: a "Cards for subscriptions" section a partner can follow start to finish (mint, send,
481
- read the card back, subscribe, what each error means, the 10-minute session, no browser code).
482
-
483
- README corrections that ride along in this release: `subscription.expired` no longer carries
484
- `failure_code: "steam_containment"` (a balance is spendable in any title whatever rail bought
485
- it, so the "wallet value that cannot be spent in this game" deferral is gone from the deferrals
486
- paragraph and the event table); the Steam transfer-policy note now says it is a rule about
487
- currency moving between titles, not about spending (an item purchase never fails on origin);
488
- and "game" reads "title" in a few places so a platform tenant is not misled by the word.
489
- Line endings: a `.gitattributes` (`* text=auto eol=lf`) keeps the packed README, CHANGELOG and
490
- package.json LF on every checkout (3.9.0's first build packed CRLF from a Windows checkout).
491
-
492
- ## 3.8.1
493
-
494
- ### Patch Changes
495
-
496
- - Subscription docs: the per-charge ceiling is 25000.00, not 500.00, and it is
497
- per CHARGE rather than per month. An annual plan bills the whole year in one
498
- go, so a $500 a month plan sold as a 12-month plan is a single $6,000 charge
499
- and is chargeable. The old number quietly refused every annual plan above
500
- $41.66 a month.
501
-
502
- ## 3.8.0
503
-
504
- ### Minor Changes
505
-
506
- - Subscriptions are a first-class server surface, on both rails, with the card capture and the
507
- sandbox clock tools beside them.
508
-
509
- New on `InvoServer`:
510
-
511
- - **`invo.subscriptions`**: `create` (card rail; charges the first period before answering,
512
- idempotent on `clientRequestId`, a repeat is a typed `idempotentReplay: true` result),
513
- `get`, `listForPlayer`, `cancel` (an already-terminal row is a 200 `alreadyCanceled`, never
514
- thrown), `changeAmount` (staged for the next renewal), `setPaymentMethod`, `refund`
515
- (idempotent; the receipt replays), `steamInit` and `steamFinalize` (Steam rail;
516
- `alreadyProcessed` is a result, not an error).
517
- - **`invo.cards`**: `beginSetup` / `confirmSetup` / `list`: the off-session card capture a
518
- card subscription needs. The hosted checkout does not save a card for subscriptions.
519
- - **`invo.sandbox.subscriptions`**: `advanceClock` / `forceRenewal` / `forceFailure` /
520
- `forceAuthChallenge`. These post to `/subscriptions/<id>/...` **relative to the sandbox
521
- base URL, not under `/api`**, and send `X-Sandbox-Clock-Key` from the new
522
- `sandboxClockKey` config; a missing key throws before the network.
523
-
524
- Typed results: `SubscriptionResult` (the subscription object with its TWO clocks,
525
- `firstCharge` with `paidPeriodSeq`, `card`, `idempotentReplay`), `FirstCharge` (`paid` |
526
- `requires_action` | `skipped_trial` | `failed` | `pending` | `pending_authorization`),
527
- `SteamInitResult` (`steamOrderId` for the client callback, `amountCoins`, `pendingReuse`),
528
- `CancelResult`, `ChangeAmountResult`, `RefundResult`, `CardSetupResult`, `SandboxClockResult`
529
- (`engineStats`), and typed `data` for all seven `subscription.*` webhook events.
530
-
531
- Error classifiers: `isActiveSubscriptionExists` (+ `existingSubscriptionId`),
532
- `isIdempotentReplayMismatch` (+ `mismatchedFields`), `isSteamReauthorizationRequired`,
533
- `isNotACardSubscription`, `isSteamChannelRequired`, `isSubscriptionTerminal`,
534
- `isNotAuthorized`, `isSandboxClockUnauthorized`, `isSteamRefundNotSupported`, `isFlowPaused`,
535
- `isGameNotLive`; `isSteamAuthorizationPending` now also covers the subscription 409.
536
-
537
- Also: the server `User-Agent` version now derives from the package version (it had read
538
- `3.0.0` since 3.0.0), pinned by a test.
539
-
540
- ## 3.7.0
541
-
542
- ### Minor Changes
543
-
544
- - Device approval grant (RFC 8628) is now a first-class server surface — including **the
545
- step that moves the money**.
546
-
547
- An integrator followed the README, polled a grant to `approved`, and stopped. Nothing
548
- moved: an approved grant is a _factor_, and the transaction sat at
549
- `pending_pin_verification` until it expired and was refunded. The README's section ended
550
- at the poll and neither package had a method for the step after it. Both halves of that
551
- are fixed here.
552
-
553
- New on `InvoServer` (all authenticate with the **player token** — on a console the game
554
- server holds the token it minted, and the game secret is never sent):
555
-
556
- - `beginDeviceApproval({ playerToken, transactionId, flow, channel? })` → the RFC 8628
557
- §3.2 grant (`deviceCode`, `userCode`, `verificationUriComplete`, `expiresIn`,
558
- `interval`, `channel`). `channel: "popup"` is refused before the network — it is
559
- browser-only (`InvoClient.approveHosted`).
560
- - `pollDeviceApproval({ playerToken, deviceCode })` → a typed outcome
561
- (`authorization_pending` / `slow_down` / `approved` / `access_denied` /
562
- `expired_token`), plus the `enrollment` object while a first-time phone waits on the
563
- game screen. `invalid_grant` throws.
564
- - `confirmDeviceEnrollment({ playerToken, deviceCode, decision })` → answers the
565
- on-screen match-code prompt (`"approve"` | `"deny"`).
566
- - **`approveWithDeviceCode({ playerToken, transactionId, flow, deviceCode })` — the money
567
- step.** Routes by flow: `send` → `/api/sdk/send/{id}/approve`, `transfer` →
568
- `/api/sdk/transfers/{id}/approve`, `send_receipt` →
569
- `/api/sdk/send/{id}/confirm-receipt`, `transfer_receipt` →
570
- `/api/sdk/transfers/{id}/confirm-receipt`. Never auto-retried.
571
- - `completeDeviceApproval(...)` — convenience loop: polls honouring `interval` and
572
- `slow_down`, surfaces the enrollment prompt, then calls `approveWithDeviceCode`.
573
-
574
- **`TRANSACTION_NOT_PENDING` is a result, not a throw.** `approveWithDeviceCode` returns
575
- `{ status: "not_pending", alreadySettled, currentStatus }` so "your earlier attempt
576
- already landed" is distinguishable from a real refusal **without string-matching** — the
577
- difference between "the guard worked" and "her currency is stuck". Every other refusal
578
- stays a typed thrown `InvoError`.
579
-
580
- `alreadySettled` is **flow-aware and fails closed**. The four endpoints gate on different
581
- status sets — the sender approves accept `pending_pin_verification` /
582
- `pending_verification`, the two receipt endpoints accept `pending_claim` / `verified` — so
583
- a receipt settle landing on `pending_pin_verification` means the SENDER has not approved
584
- yet (possibly held at a guardian 202). That is _before_ the step, not past it, and calling
585
- it settled would tell a game to hand over goods for value never credited. It is an
586
- allow-list per flow rather than a "not expired/failed" deny-list, so a status INVO adds
587
- later answers `alreadySettled: false` with `currentStatus` set — go read the transaction —
588
- instead of defaulting to "the money moved" in already-deployed copies of this SDK.
589
-
590
- Older backend bodies that carried only the message ("Transaction not pending…", "…cannot
591
- be confirmed…") with no machine code are matched too, but narrowly: HTTP 400, one of those
592
- two phrases, **and** a readable `(current status: …)` / `(status: …)` clause. "cannot be
593
- confirmed" is ordinary English, so a phrase match alone can never assert that money moved.
594
-
595
- New `InvoError` predicates: `isTransactionNotPending`, `currentTransactionStatus`,
596
- `isDeviceApprovalNotApproved`, `isDeviceApprovalAlreadyPending`,
597
- `deviceApprovalExpiresAt`, `isSettleFault`, `errorRef`. The RFC 8628 §3.5 tokens are
598
- promoted onto `err.code`.
599
-
600
- Two safety fixes in `completeDeviceApproval`: `transactionId` is validated **before** the
601
- loop (an empty id used to poll for minutes, let the player approve, and only then throw —
602
- an approved grant with nothing settled), and the `respond` callable handed to
603
- `onEnrollment` now resolves quietly for every "the prompt is moot" refusal
604
- (`expired_token`, `invalid_grant`, and the two enrollment 409s) instead of rejecting. A
605
- prompt on a TV routinely outlives its ten-minute grant, callers fire `respond` without
606
- awaiting it, and an unhandled rejection exits a Node process.
607
-
608
- README: the console section is rewritten around begin → show the QR → poll → **call
609
- `approveWithDeviceCode`** → webhooks, with the supersede-vs-409 begin semantics corrected
610
- and "consumed when used" replaced by _when_ the code is spent. A new top-level **Sends and
611
- transfers, stage by stage** section covers both flows and both sides with a
612
- call-order table, an error table, and a common-mistakes box led by "polling to `approved`
613
- and stopping". The error tables now also carry the receipt-flow-only refusals a console
614
- recipient meets (`receiver_not_enrolled_use_claim_code`, `not_intended_receiver`, the
615
- phone-share 409, `RECIPIENT_IDENTITY_PENDING` / `_DECLINED`) and a warning that a settle
616
- FAILURE is ambiguous about the money — INVO commits and then reads the transaction back to
617
- build its 200, so a `*_FAILED` or a timeout can both describe money that already moved:
618
- read the transaction status before telling the player it failed, and never auto-start a
619
- replacement. SMS is now confined to a clearly-labelled legacy-fallback subsection.
620
-
621
- ## 3.6.0
622
-
623
- ### Minor Changes
624
-
625
- - New: `InvoClient.approveHosted({ transactionId, flow })` — web games approve on INVO's
626
- hosted identity page. The browser is the RFC 8628 client: with the player token it already
627
- holds, the SDK calls `POST /api/sdk/approvals/device/begin` with `channel: "popup"` (INVO
628
- records the page's `Origin` as the popup's opener), opens the hosted page in a popup
629
- (synchronously, inside your click handler), polls `poll` honouring `interval` and
630
- `slow_down` (+5 s), drives the INVO-branded match-code prompt from the poll's `enrollment`
631
- object ("Set up INVO on iPhone? Code 48-27. Say Yes only if the phone you just
632
- scanned/opened shows this code." → `confirm-enrollment`; `confirmed` shows "Finishing on
633
- iPhone… / Stop it, wrong code"; a 409 already-decided takes it down quietly), and when the
634
- poll says `approved` calls the flow's approve endpoint with the `device_code` —
635
- `transfers/{id}/approve`, `send/{id}/approve`, `send/{id}/confirm-receipt`,
636
- `transfers/{id}/confirm-receipt`. Resolves `{ status: "approved", approval }` (the same
637
- `ApproveResult` / `ConfirmReceiptResult` the in-app calls return) or `denied` / `expired` /
638
- `closed` / `blocked` / `redirected`; rejects with `InvoError` when the backend refuses.
639
- `device_code` lives in the call's closure only — never on the result, never logged. The
640
- page's `postMessage` is a wake-up that triggers an immediate poll (accepted only from the
641
- hosted page's https origin and only from the popup the SDK opened), never a result. A
642
- popup blocked by the browser resolves `blocked` before anything is started (default);
643
- `popupBlocked: "redirect"` opts in to a full-tab redirect. A page sending
644
- `Cross-Origin-Opener-Policy: same-origin` is detected and reported as `blocked` with a
645
- hint. Your server does nothing new; its `device_approval.approved` webhook still fires.
646
- In-app partner-domain passkeys are unchanged and remain supported. `onEnrollment(e,
647
- respond)` + `renderPrompt:false` let a game draw its own prompt.
648
-
649
- Docs: new "Web games — approving on INVO's hosted page" section; the console-flow poll
650
- example now shows `match_code`. Test-only devDependency added: `happy-dom`.
651
-
652
- Docs (hosted identity pages, Phase 7): the console section documents `channel` on
653
- `begin` (`qr` default | `popup` — the browser must call `begin` itself, its https `Origin`
654
- becomes the popup's opener, server-to-server callers are refused | `app_browser` — the
655
- mobile plugins; the return scheme `invo-sdk-<game_id>` is derived server-side), the echoed
656
- `channel` on the begin body, `recovery` on the poll's `enrollment` object, the hosted
657
- passkey-recovery flow (screen confirm + emailed single-use link → old INVO passkeys
658
- deactivated, `identity.passkey_reset` webhook, 24-hour `PASSKEY_RECOVERY_COOLDOWN` on
659
- money out; receiving unaffected), the mobile auto-confirm note (`app_browser` enrolment is
660
- confirmed by INVO, no prompt), and `ENROLLMENT_REQUIRES_PROOF` on the page. Sends &
661
- transfers: guardian approval now goes by email first (`consent_channel` and
662
- `resend_endpoint` on the raw 202 `guardian_approval` block; `decision_source: "email_link"`),
663
- the once-per-approval `POST /api/sdk/approvals/guardian/{approvalId}/resend` `{channel:"sms"}`
664
- contract (initiator's token; 403/409/410/503 codes), and phone-share / recipient-identity
665
- consents on the same hosted page (unchanged 409 / 202 codes, `consent_channel` on the
666
- phone-share body). Passkeys: the partner-domain freeze — new titles have nothing to verify
667
- (`409 PARTNER_RP_FROZEN`; `WEBAUTHN_NOT_ENABLED_FOR_TENANT` is the expected state, use
668
- `approveHosted`), tenants with a domain verified before the freeze keep it, removal is
669
- irreversible. The "SMS first, then email" fallback sentence corrected to "email first, SMS
670
- on request". Documentation only.
671
-
672
- ### Patch Changes
673
-
674
- - Docs: the device-approval page (RFC 8628, consoles / TVs / native Steam and desktop
675
- clients) now enrols the player's INVO passkey on the **first** scan, and the proof is the
676
- game screen: the phone says "confirm on your game screen", the game shows "Set up INVO on
677
- this phone: iPhone?", the player presses Yes on the console, and the phone's biometric
678
- creates the passkey and approves — no code to type, no SMS; every later scan is scan,
679
- biometric, done. The "the player needs an INVO passkey" bullet is replaced accordingly.
680
- Documents the two integrator-facing additions: the `enrollment` object
681
- (`state` / `device_label` / `requested_at`) on the `authorization_pending` poll body while
682
- a phone is waiting, and `POST /api/sdk/approvals/device/confirm-enrollment`
683
- (`{device_code, decision: "approve" | "deny"}`, same auth as begin/poll; deny ends the
684
- grant with `access_denied`), plus the backup email. Also documents two backend
685
- behaviours: `begin` extends the transaction's own approval window past the code's expiry
686
- (`transfer` / `send`), and `begin` may be called again for the same transaction once an
687
- approved code's window has passed. Documentation only — no code or type changes; the
688
- `begin`/`poll` endpoints, the `device_approval.approved` webhook and its `method` value
689
- are unchanged.
690
-
691
- Also on the send side: the claim SMS now carries a link to a hosted INVO claim page where
692
- a recipient without the game collects with one email + an emailed code + their phone's
693
- passkey (in-game claim unchanged; `transfer.received` fires the same); documents the
694
- sender-token REST call `POST /api/sdk/send/{transactionId}/resend-claim` (30-second
695
- cooldown, 10 per transaction per hour — no SDK method); and that an uncollected send is
696
- still refunded at 24 hours but the sender is now emailed and the recipient texted, with
697
- `transfer.claim_expired` / `transfer.refunded` as the source of truth. The `transfer.*`
698
- rows were added to the event-types table.
699
-
700
- - df2efe9: Docs: add an explicit per-platform verification/approval recommendation. The
701
- "gold standard" section now spells out which method fits which client — a passkey
702
- directly on mobile app/web and desktop web, and the QR device-approval flow
703
- (RFC 8628) on consoles **and** on native Steam / desktop game clients (Mac &
704
- Windows), where it is the embedded game client, not the OS, that can't invoke the
705
- platform authenticator. Also documents the SMS-first-then-email fallback for
706
- remote approvals with no passkey path. Documentation only — no code or type
707
- changes; the `VerificationMethod` union and the device-approval REST flow are
708
- unchanged.
709
-
710
- All notable changes to `@invonetwork/web-sdk` are documented here. This project follows
711
- [Semantic Versioning](https://semver.org/). Releases are managed with
712
- [changesets](https://github.com/changesets/changesets).
713
-
714
- ## [3.5.0] - 2026-09-01
715
-
716
- **The Steam purchase flow is now first-class SDK surface: `steamPacks()`, `steamInitPurchase()`, `steamFinalizePurchase()`** — plus browser-based checkout for platforms where the Steam overlay does not render, a finalize-poller error taxonomy, and webhook `channel` typing. No breaking changes.
717
-
718
- Until now the SDK only _steered away_ from Steam (`purchaseCurrency` fails fast on `rail: "steam"`); the dedicated endpoints had to be called by hand. All three are typed methods now, and the fail-fast message names them.
719
-
720
- ### Added
721
-
722
- - **`InvoServer.steamPacks(query?)`** — the pack catalogue. `currencyAmount` is per-player (VAT and the storefront's revenue share come out of the sticker before currency is derived — a $4.99 pack yields 34, not 50, units at $1 = 10). Render it verbatim; never compute currency from price and never cache one answer for all players.
723
- - **`InvoServer.steamInitPurchase(input)`** — start the purchase. Idempotent on `purchaseReference` (retries, including manual retries after a 409, MUST reuse it). New authorization modes:
724
- - `usersession: "client"` (default, unchanged): Steam overlay in-game. The SDK sends **no** `usersession` key at all in this mode, pinned by test, so existing behaviour cannot shift.
725
- - `usersession: "web"`: for platforms where the overlay does not render (observed: Electron on macOS). Requires `playerIp` — the PLAYER's address, never your server's; refused client-side before the network without it. Returns `steamCheckoutUrl`: Steam's own hosted approval page, which must open as a **top-level tab** (it cannot be iframed). _Note: Steam's sandbox issues checkout URLs its production host will not serve, so web-session approval is provable only against production; the rest of the flow is identical to client-session._
726
- - `metadata` — echoed on the `purchase.completed` webhook (`data.metadata`) — the way to correlate your own player/order ids. The Steam rail merges its own context keys (`steam_wallet_currency`, `steam_country`, `steam_account_status`, `vat_rate_pct`) into the echoed object; avoid those names in yours.
727
- - **`InvoServer.steamFinalizePurchase({orderId})`** — capture + credit. Idempotent: a replay returns `alreadyProcessed: true` and never credits twice.
728
- - **Finalize poller taxonomy on `InvoError`** — because _not every 409 means "not yet"_, and a poller that assumes so polls a dead order forever:
729
- - `isSteamAuthorizationPending` — player has not approved yet (Steam reports `Init`). The normal wait state; poll again.
730
- - `isSteamAuthorizationDead` — any settled status — `Cancelled`, `Failed`, `Refunded`, `Chargedback`, and every other non-Init outcome (pending is the CLOSED set: only `Init` means "not yet"). Stop; no later call can succeed.
731
- - The two are mutually exclusive by construction, and a test pins that they can never both answer true.
732
- - **`InvoError.isPartnerCreditUnavailable`** (`PARTNER_CREDIT_UNAVAILABLE`, 409) — the studio's settlement float cannot cover the purchase. Structure is fine; the money is not. Plain failure toast; do **not** hot-poll init (each attempt briefly re-reserves headroom), and reuse the same `purchaseReference` on manual retry.
733
- - **`InvoError.isPartnerRailSuspended`** (`PARTNER_RAIL_SUSPENDED`, 409) — terminal from the game's seat. The umbrella `isPartnerSettlementUnavailable` still covers both.
734
- - **`InvoError.isUnknownSteamPack`** (400) — re-fetch `steamPacks()`; the body's `valid_pack_ids` lists what exists.
735
- - **`InvoError.isMissingPlayerIp`** (400) — always an integration bug on web sessions.
736
- - **`PurchaseCompletedData.channel`** — which storefront the purchase came from (`"steam"` / `"ios"` / `"android"` / `"web"` / `"console"`), beside `rail`. `null` means a legacy game key: a real answer ("unattributed"), read it as one.
737
-
738
- ### Changed
739
-
740
- - `purchaseCurrency`'s `rail: "steam"` fail-fast message now names the real methods instead of vaguely citing "dedicated endpoints".
741
-
742
- ## [3.4.0] - 2026-09-01
743
-
744
- **A Steam title now bills through its OWN Steam application.** New error helpers;
745
- no breaking changes to any existing method or type.
746
-
747
- ### Why this is a real change and not a doc tidy
748
-
749
- Steam pays whoever owns the Steam application. Until now, INVO documented a
750
- single INVO-owned Steam app that billed every title on the network — so a studio
751
- had nothing to register and the money reached them through INVO. That model is
752
- gone. Each title sells through the studio's own Steam app, the money lands in
753
- their own Steamworks account, and INVO issues the player's currency immediately
754
- and settles with the studio afterwards against a payment method on file.
755
-
756
- If you shipped against 3.3.0 or earlier and your Steam integration works today,
757
- nothing in your code needs to change. What changes is the **studio's** one-time
758
- setup, and the errors you may now see if they have not done it.
759
-
760
- ### Added
761
-
762
- - `InvoError.isSteamNotConfigured` — the title has no Steam application
763
- registered with INVO yet (`STEAM_NOT_CONFIGURED`, 503).
764
- - `InvoError.isPartnerBillingNotSetUp` — the studio has not finished INVO billing
765
- setup (`PARTNER_BILLING_NOT_SET_UP`, 409).
766
- - `InvoError.isPartnerSettlementUnavailable` — settlement suspended or over
767
- limit (`PARTNER_RAIL_SUSPENDED` / `PARTNER_CREDIT_UNAVAILABLE`, 409). Show a
768
- neutral "purchases are unavailable right now": it is not the player's problem.
769
- - `InvoError.isSteamAppChanged` — the order was started against a different
770
- Steam application than the title is configured for now (`STEAM_APP_CHANGED`,
771
- 409). Only reachable if a studio swaps apps mid-flight.
772
-
773
- All four are refused **before the player is charged**, which is the point.
774
-
775
- ### Changed
776
-
777
- - README: the Steam section now documents the studio's Steamworks setup
778
- (microtransactions enabled, a publisher-GROUP Web API key that includes the
779
- app, appid + key entered in the INVO dashboard, payment method on file).
780
- - README: removed the claim that no Steam-side registration was required.
781
-
782
- ## [3.3.0] - 2026-08-31
783
-
784
- **Documentation only. No code changes, no API changes.**
785
-
786
- Documents **Device Approval** — passkey step-up for consoles, TVs and any device
787
- with no browser. It is the OAuth 2.0 Device Authorization Grant
788
- ([RFC 8628](https://datatracker.ietf.org/doc/html/rfc8628)), so a standard
789
- client library understands the responses.
790
-
791
- - The device shows a short code and a QR (`verification_uri_complete`); the
792
- player approves on their phone; your **server** polls
793
- `POST /api/sdk/approvals/device/poll` until it hears back.
794
- - **One approval authorises one transaction.** Unlike the plain RFC 8628 grant,
795
- which authorises a _client_, an INVO device code is bound to the transaction
796
- you named and is consumed when used — it cannot approve anything else and
797
- cannot be reused.
798
- - `user_code` is meant to be seen; `device_code` is not. Poll from your backend.
799
- - Subscribe to `device_approval.approved` to learn the moment an approval lands
800
- instead of waiting for the next poll. Polling still works alone.
801
- - Available to every title with nothing to configure — the constraint is a
802
- property of the _device_, not the game, so a title with a website and a
803
- console build uses the normal ceremony in the browser and this one on console.
804
- - Currency purchases on a console go through that console's store, as the
805
- platform holder requires; this flow is for approving transfers and sends.
806
-
807
- Minor rather than patch because it documents a new API surface. The snippets are
808
- pinned by a test against this file, for the same reason the Steam ones are: a
809
- REST flow with no SDK method behind it is the one thing no other test can see.
810
-
811
- ## [3.2.3] - 2026-08-28
812
-
813
- **Documentation only. No code changes, no API changes.** Corrects two errors in
814
- the 3.2.2 Steam snippets that made them fail if copied.
815
-
816
- - **Base path.** The snippets said `/api/enhanced-purchase/...`. The routes are
817
- mounted at **`/api/currency-purchases/...`** -- `enhanced_purchase_api` is the
818
- module name, not the mount point. Copying 3.2.2 returned `404 Resource not
819
- found`, which reads like the Steam rail is unavailable rather than like a
820
- wrong URL.
821
- - **Auth header.** The snippets sent `X-Game-Secret`. The header is
822
- **`X-Game-Secret-Key`**, as it is everywhere else in this document. An unknown
823
- header is ignored, so the request arrived unauthenticated.
824
-
825
- Both were confined to the Steam section added in 3.2.2; every other snippet was
826
- correct. The Steam flow itself is unchanged -- pack catalogue, `pack_id`,
827
- VAT-aware amounts, all exactly as 3.2.2 describes.
828
-
829
- The paths and header are now pinned by a test against this file, because the
830
- Steam section is the one snippet with no SDK method behind it and so was the one
831
- thing no test could see.
832
-
833
- ## [3.2.2] - 2026-08-28
834
-
835
- **Documentation only. No code changes, no API changes.**
836
-
837
- Steam currency purchases now work on a **pack model**, and this documents it. The
838
- 3.2.1 notes described an earlier design that has been replaced -- read this
839
- instead.
840
-
841
- - **INVO owns the Steam pack catalogue.** You do not set prices and you never
842
- send an amount. Fetch `GET /steam/packs?steamid=...`, render it, and pass a
843
- `pack_id` to `/steam/init-purchase`. An amount is refused with
844
- `400 UNKNOWN_STEAM_PACK`.
845
- - **The price is identical everywhere; the currency inside is not.** Steam prices
846
- are VAT-inclusive wherever VAT is collected, so more of a fixed price goes to
847
- tax in a high-VAT country -- the same $9.99 pack yields 69 units in the US and
848
- 58 in France.
849
- - **Always pass `steamid`** when fetching the catalogue. Without it amounts are
850
- quoted with no VAT deducted, so a store promises more than the purchase
851
- delivers. Do not cache one catalogue for all players.
852
- - A Steam-distributed title may only sell currency on the `steam` rail
853
- (`409 STEAM_PURCHASE_LAYER_REQUIRED`), and a locked Steam account is refused up
854
- front (`409 STEAM_ACCOUNT_LOCKED`).
855
-
856
- Steam remains a server-to-server REST flow rather than an SDK method, because the
857
- purchase is authorised inside the Steam client and your game relays that.
858
-
859
- ## [3.2.1] - 2026-08-28
860
-
861
- **Documentation only. No code changes, no API changes.**
862
-
863
- Documents two things about the Steam rail that the SDK does not change but every
864
- Steam integration has to handle:
865
-
866
- - **Currency for a Steam-distributed title must be bought on the `steam` rail.**
867
- Any other rail is refused with `409 STEAM_PURCHASE_LAYER_REQUIRED`. This is a
868
- platform requirement and it applies across every storefront the title ships on,
869
- because a player's balance is shared between them.
870
- - **The player is charged more than the value you request.** Steam's platform
871
- commission is priced into the charge rather than absorbed, so the Steam
872
- init-purchase response now carries `charged_usd` alongside `value_usd`. Show
873
- `charged_usd` in your store. The currency the player receives is unchanged, so a
874
- pack is worth the same in-game on every rail, and the rate is configuration --
875
- read the response rather than hard-coding a multiplier.
876
-
877
- ## [3.2.0] — 2026-08-24
878
-
879
- **Storefront keys.** A game that ships on more than one storefront now gets one SDK
880
- key per storefront -- `steam`, `ios`, `android`, `web`, `console` -- all valid at the
881
- same time, and the key determines the payment rail. Construct one client per key and
882
- use whichever matches where the player is buying. **Additive: no behavior changes, no
883
- API removals.** A single existing key keeps working exactly as it does today, `rail`
884
- included, with no deadline and no migration.
885
-
886
- Three new typed error predicates for refusals this SDK previously surfaced only as a
887
- raw `code` string:
888
-
889
- - `InvoError.isRailChannelMismatch` -- the `rail` you sent disagrees with the storefront key
890
- you authenticated with (400). The fix is to stop sending `rail`; the key already
891
- determines it. INVO refuses rather than silently overriding, because overriding
892
- would bill a player through a route you did not ask for.
893
- - `InvoError.isSteamRailNotEntitled` -- a Steam purchase was attempted for a title INVO has
894
- not registered as distributed on Steam (403). Holding a `steam` storefront key does
895
- not by itself register the title.
896
- - `InvoError.isSteamPurchaseLayerRequired` -- a title distributed on Steam tried to sell currency
897
- on a non-Steam rail (409). Use the dedicated Steam purchase flow.
898
-
899
- Also in this release: the 3-D Secure completion method's documentation no longer names
900
- a payment processor. INVO does not name processors in developer-facing surfaces, and
901
- this line had been an exception to that for some time.
902
-
903
- Also in 3.2.0: **provider-neutral error codes.** INVO stamps a neutral alias
904
- (`error_code_public`) beside any machine code that carries a payment
905
- processor's name. This SDK previously read only the raw code, so a partner
906
- branching on `err.code` had to hard-code a vendor name INVO's own public
907
- documentation is not allowed to print. `err.code` is now the neutral alias when
908
- one exists (`STRIPE_ERROR` becomes `PROCESSOR_ERROR`), and the literal wire value stays reachable on
909
- `err.rawCode` for anyone already matching it. Refund reads prefer
910
- `processor_refund_reference` over the vendor-named field, with a fallback.
911
-
912
- **Storefront keys are still server-side keys.** A storefront key names where the
913
- _purchase_ came from, not where the key lives. It belongs in your backend exactly like
914
- your original key -- never in a game client, an app bundle, or browser code.
915
-
916
- ## [3.1.0] — 2026-08-04
917
-
918
- **Passkeys are the gold standard; the SMS-PIN path is deprecated.** This release makes INVO's
919
- authentication guidance explicit in the two places developers actually look — the README and IDE
920
- autocomplete. **No behavior changes, no API removals, no runtime warnings.** Upgrading and
921
- changing nothing produces byte-identical runtime behavior.
922
-
923
- A passkey is a phishing-resistant, origin-bound WebAuthn assertion. An SMS PIN is a shared secret
924
- on a channel exposed to SIM swap and interception. They were documented as interchangeable
925
- verification options; they are not, and the docs said so in a way that produced PIN-first
926
- integrations.
927
-
928
- ### Added — error-contract classifiers
929
-
930
- Three 403s that previously arrived as a generic `InvoError` (correct `status`/`code`/`message`,
931
- but no typed branch) now have classifiers:
932
-
933
- - **`err.isSourceGameNotLive`** — the caller's OWN game is in testing. Self-serve: switch it to
934
- Live in the console (Game Settings → Status).
935
- - **`err.isTargetGameNotLive`** — the DESTINATION game is in testing. Usually another
936
- developer's game, so the caller **cannot** fix it. **Deliberately distinct** from the source
937
- case: collapsing them into one "not live" branch yields a "go fix it" CTA that dead-ends half
938
- the time.
939
- - **`err.gameStatus`** — the `game_status` field from either refusal (e.g. `"testing"`).
940
- - **`err.isWebauthnNotEnabledForTenant`** — tenant has no verified WebAuthn RP ID. **This is
941
- configuration state, not a failure**: fall back to the SMS/in-app path instead of surfacing an
942
- error. Currently the common case — 4/23 sandbox and **0/3 production** tenants are configured.
943
-
944
- Note the backend splits field names across these: the `*_GAME_NOT_LIVE` pair uses
945
- `error_code`/`message`, while `WEBAUTHN_NOT_ENABLED_FOR_TENANT` uses `code`/`error`. The SDK
946
- already read both, so `err.code` is populated either way — the new tests pin both shapes.
947
-
948
- ### Clarified — the SDK does not, and did not, collapse non-2xx into transport errors
949
-
950
- Following a report of a `403` being debugged as a network outage: verified end-to-end that a
951
- non-2xx always surfaces with its real `status`, `code`, and `message`, and that `status: 0` is
952
- reserved for a genuine absence of an HTTP response. **No fix was needed in the SDK** — the loss
953
- happened in an integration-layer catch-all. Added regression tests pinning the behavior, plus a
954
- README section (**"`.status === 0` means 'no HTTP response' — and nothing else"**) showing the
955
- anti-pattern and the correct handler, and a note that `409` is a retryable not-ready state
956
- rather than a failure.
957
-
958
- ### Deprecated
959
-
960
- - **`InvoServer.verifySmsTransfer` / `InvoServer.verifySmsSend`** — marked `@deprecated`. They
961
- still work exactly as before and still hit the same endpoints. A **future major version will
962
- remove them**; no date is committed yet. Keep them only as a genuine last resort for users who
963
- cannot enroll a passkey (unsupported device, no platform authenticator) or who decline.
964
- **Migration:** when `initiateSend`/`initiateTransfer` returns `verificationMethod: "sms"`, read
965
- it as _"this sender has no passkey"_ — prompt `InvoClient.enrollPasskey()` and then
966
- `InvoClient.approveSend` / `approveTransfer`, instead of routing to a PIN pad.
967
-
968
- ### Changed (documentation only)
969
-
970
- - New README section — **"Passkeys are the gold standard — don't build on SMS"** — with the
971
- do/don't table, the deprecation notice, and an explicit list of the OTP surfaces that are
972
- **not** discouraged.
973
- - `VerificationMethod`, `InitiateResult.verificationMethod` and `SmsVerifyResult` doc comments
974
- reframed: `"in_app"` and `"sms"` are no longer presented as peer options.
975
- - "Before you go live" now stresses configuring RP ID / origins _before_ launch, since an
976
- unconfigured tenant silently drops every sender onto the deprecated path.
977
- - **New "Prerequisite: passkeys are dark until your tenant verifies a domain" subsection.**
978
- Recommending passkeys without saying what unlocks them would send developers straight into a
979
- `403` on their first `enrollPasskey()` call — with 0/3 prod tenants configured, that is
980
- currently _everyone_. The deprecation carries no removal date for the same reason.
981
- - Stability section corrected — it still claimed `2.0.0` was the only major, which `3.0.0`
982
- made false.
983
- - Design doc: `docs/features/passkey-first-authentication.md`.
984
-
985
- ### Not affected — still recommended
986
-
987
- `enrollmentBegin`/`enrollmentVerify`, `recoveryBegin`/`recoveryComplete`, and
988
- `phoneShareInitiate`/`phoneShareApprove` all involve a one-time code but are the on-ramp _to_ a
989
- passkey (or phone-ownership consent), not a substitute for one. They are **not** deprecated.
990
-
991
- ### Upgrade note
992
-
993
- The only way this release can surface in a pipeline is a lint rule that treats `@deprecated`
994
- usage as an error (e.g. `deprecation/deprecation` with `--max-warnings 0`). That is a lint-level
995
- signal, not a build or runtime break, and it is the intended notice.
996
-
997
- ## [3.0.0] — 2026-07-20
998
-
999
- **BREAKING — the Platform Commerce card leg moved to INVO's hosted checkout.** The backend now
1000
- hosts the entire card flow (card fields, Apple Pay / Google Pay, billing-address collection,
1001
- 3-D Secure) on its own checkout page, so the browser card-element surface shipped in 2.5.x is
1002
- gone. Card sales are simpler AND safer: server creates → buyer pays on `checkoutUrl` → fulfill
1003
- on the `platform_commerce.purchased` webhook. Note: the card leg is pending final enablement on
1004
- the backend (sandbox payment test) — the balance leg is fully live.
1005
-
1006
- ### Migration from 2.5.x (card leg only — balance/status/refund/webhooks unchanged)
1007
-
1008
- - `platformCommerce.purchase({ fundingSource: "card" })`: **remove `billingAddress`** (the type
1009
- is gone; the hosted page collects it) and optionally pass `successUrl` / `cancelUrl` /
1010
- `metadata`. The result now carries `checkoutUrl` / `sessionId` / `expiresAt` (unix seconds) /
1011
- `idempotentReplay` — **`clientSecret` no longer exists.**
1012
- - Browser: **`confirmCardPayment` and `mountCardPayment` are removed** (with all card-element
1013
- types and the `commercePublishableKey` config). Replace with a redirect
1014
- (`location.href = checkoutUrl`) or the new optional embed:
1015
- `invo.platformCommerce.mountCheckout(el, checkoutUrl, { onComplete })` — an iframe plus an
1016
- origin-checked listener for the page's `INVO_CHECKOUT_COMPLETE` message.
1017
- - Card duplicates no longer 409: retrying `purchase` with the same `clientRequestId` **replays
1018
- the same checkout session** (`idempotentReplay: true`), so a lost response is recoverable.
1019
-
1020
- ### Added
1021
-
1022
- - `PlatformPurchaseInput.successUrl/cancelUrl/metadata`; result fields
1023
- `sessionId/checkoutUrl/expiresAt/idempotentReplay`.
1024
- - `InvoClient.platformCommerce.mountCheckout(el, checkoutUrl, opts)` → `{ iframe, destroy() }`.
1025
- - `err.isAboveCardMaximum` (`ABOVE_CARD_MAXIMUM`, card > $999.99) + client-side card USD
1026
- bounds fail-fast ($0.50–$999.99).
1027
- - Card `requires_payment` responses without a `checkout_url` fail closed (`INVALID_RESPONSE`).
1028
-
1029
- ### Removed
1030
-
1031
- - `confirmCardPayment`, `mountCardPayment`, `commercePublishableKey`, `BillingAddress`, and the
1032
- card-element/processor types + the runtime CDN script loader (no more processor touchpoints
1033
- in this SDK at all).
1034
-
1035
- ## [2.5.1] — 2026-07-20
1036
-
1037
- Hardening patch from a second, independent post-release audit (correctness vs the backend
1038
- blueprint + security red-team) of the 2.5.0 Platform Commerce feature. No API breaks.
1039
-
1040
- ### Fixed
1041
-
1042
- - **Card-confirm script loader could hang forever on retry.** After a transient CDN failure
1043
- (or a pre-existing processor `<script>` tag whose events already fired), the next
1044
- `mountCardPayment`/`confirmCardPayment` attached listeners to a dead tag and never settled —
1045
- checkout silently dead until page reload. The loader now removes failed tags and polls
1046
- (bounded, 10s) when a tag pre-exists.
1047
- - **Orphaned card element on submit-lookup failure.** `confirmCardPayment` now destroys the
1048
- mounted Payment Element before rethrowing when the `submit` selector can't be resolved
1049
- (previously a retry stacked a second live card iframe).
1050
- - **Billing-address validation errors no longer echo the submitted values** (cardholder PII
1051
- could otherwise land in logs/Sentry); optional billing fields (`name`/`line2`/`state`) are
1052
- now type-checked.
1053
- - **`playerPhone` on `platformCommerce.purchase` is now E.164-validated** — this endpoint can
1054
- create the player identity, so a national-format phone must never reach the wire.
1055
- - **`err.isInsufficientBalance` now also classifies the zero-balance 400** ("Player has no
1056
- balance in this tenant", which carries only `current_balance`).
1057
- - **Breaker-open 503 keeps its human message** (`err.code === "service_unavailable"`, message
1058
- no longer collapses to the bare token).
1059
- - **Webhook types:** `platform_commerce.refunded` `player_email` is nullable + `identity_id`
1060
- added; (2.5.0 already made card-leg `total_price` optional on `purchased`).
1061
- - **Refund result surfaces `newBalance`** (balance leg) **and `processorRefundId`** (card leg)
1062
- instead of leaving them `raw`-only.
1063
- - Platform-commerce error tests now assert the REAL backend envelopes
1064
- (`{status,error_code,message}` / bare `{message}`), not idealized shapes.
1065
-
1066
- ### Docs
1067
-
1068
- - Card-leg lost-response caveat on `purchase` (duplicate 409 can strand a `clientSecret`-less
1069
- pending order — reconcile via webhook/`getStatus`, retry with a NEW `clientRequestId`).
1070
- - `confirmCardPayment`: bank-redirect return-leg guidance + remount-after-decline note;
1071
- `CardPaymentResult.raw` log-redaction note.
1072
-
1073
- ## [2.5.0] — 2026-07-20
1074
-
1075
- **Platform Commerce (ecommerce).** A new flow for **platform** tenants (non-game apps: vertical
1076
- video, creator merch, marketplace) to sell items funded by **INVO balance or a real card**, with
1077
- INVO as merchant of record and full refunds. This is **distinct from item purchase** — that is a
1078
- _game_ tenant spending a player's _existing game currency_ on an _in-game_ item (balance only, no
1079
- card, no refund). Additive; only platform tenants can call it (a game tenant gets `403
1080
- NOT_A_PLATFORM_TENANT`). (Backend handoff: BE-PIP-009 `PLATFORM_COMMERCE_SDK.md`.)
1081
-
1082
- - **Server** (`InvoServer.platformCommerce`, mirrored in the Python SDK as
1083
- `server.platform_commerce`):
1084
- - `purchase(input)` — `fundingSource: "balance"` settles synchronously (`status:"success"`);
1085
- `"card"` returns `status:"requires_payment"` + a `clientSecret` and **requires a
1086
- `billingAddress`**. Idempotent on `clientRequestId`.
1087
- - `getStatus(orderId)` — `completed` | `pending_payment` | `refunded`.
1088
- - `refund({ orderId | clientRequestId, reason? })` — INVO retains its fee; a second refund
1089
- throws `409` (`err.isAlreadyRefunded`).
1090
- - **Browser** (`InvoClient.platformCommerce`):
1091
- - `confirmCardPayment(clientSecret, { mount, publishableKey?, returnUrl?, submit? })` — mounts
1092
- the card element and confirms; returns `{ status: "succeeded" | "requires_action" |
1093
- "processing" | "failed" }`. The processor JS is **lazy-loaded from its CDN — no bundled
1094
- dependency**; pass its publishable key (or set `commercePublishableKey` on the client config).
1095
- - `mountCardPayment(clientSecret, opts)` — the primitive: `{ element, confirm(), destroy() }`
1096
- to confirm from your own Pay button.
1097
- - **Webhooks:** new typed `platform_commerce.purchased` / `platform_commerce.refunded` events.
1098
- **Fulfill card orders on `platform_commerce.purchased`, never on the browser confirmation.**
1099
- - **New `InvoError` classifiers:** `isNotPlatformTenant` (403), `isAmountBelowMinimum`,
1100
- `isBelowCardMinimum` (card < $0.50), `isAlreadyRefunded` (409).
1101
- - Docs: README now leads the flow list with an explicit **item purchase vs Platform Commerce**
1102
- contrast; new "Platform Commerce (ecommerce)" section.
1103
-
1104
- ## [2.4.1] — 2026-07-10
1105
-
1106
- Docs only, no code change — corrects stale README prose that the 2.4.0 publish still carried:
1107
- the status line led with an old version, and the Stability section still cited the `2.0.0`
1108
- `playerPhone` requirement as the standing breaking change (2.2.0 relaxed it back to optional).
1109
- Republished so the package-bundled README is accurate.
1110
-
1111
- ## [2.4.0] — 2026-07-10
1112
-
1113
- **Steam transfer policy.** Steam-purchased currency is locked to Steam titles; the backend now
1114
- enforces this at transfer/send initiate and annotates destinations. Additive, and inert until a
1115
- title is flagged Steam-distributed. (Design doc: `docs/features/steam-transfer-policy.md`.)
1116
-
1117
- - New `InvoError` classifiers on `initiateSend`/`initiateTransfer` 409s:
1118
- `isSteamValueNonTransferable` (with `steamTransferableMax` / `steamOriginAmount` — decimal
1119
- strings) and `isNonSteamValueIntoSteamBlocked`. Surface `err.message` verbatim.
1120
- - New `DestinationGame.acceptsSteamOriginValue` (maps `accepts_steam_origin_value`; `false` when
1121
- omitted) — disable non-Steam destinations for a player holding Steam value so they never hit
1122
- the 409.
1123
-
1124
- No breaking changes.
1125
-
1126
- ## [2.3.0] — 2026-07-07
1127
-
1128
- **Claim-time phone-share approval.** The backend closed a security gap: claiming/collecting a
1129
- phone-routed transfer now authorizes the collecting identity against the receiver phone before
1130
- crediting. So `confirmReceiptSend`/`confirmReceiptTransfer` and `claimTransfer`/`claimCurrency`
1131
- can now return the phone-share `409 PHONE_SHARE_APPROVAL_REQUIRED` (previously only
1132
- registration/mint did). The existing `InvoError.isPhoneShareApprovalRequired` already classifies
1133
- it — no consumer code must change — but:
1134
-
1135
- - New **`InvoError.phoneShareLast4`** surfaces the `phone_last4` from the 409 body for the UI
1136
- ("we texted the phone ending 1234").
1137
- - `isPhoneShareApprovalRequired` docs + the `confirmReceipt*`/claim method docs + README now
1138
- spell out the claim-time path: it's **not a failure** — the funds are held and the phone owner
1139
- is texted; show `err.message` verbatim, then **retry the same call** once approved (it succeeds
1140
- idempotently); on denial/expiry the sender is refunded.
1141
-
1142
- Additive, no breaking changes; affects all rails' claim paths (transfer, currency send, amazon).
1143
-
1144
- ## [2.2.0] — 2026-07-07
1145
-
1146
- **Backend reconciliation** — a full audit of the SDK against the live backend surfaced three
1147
- places the SDK didn't match reality. All changes are backward-compatible (relaxing required
1148
- inputs / adding surface); no working call breaks.
1149
-
1150
- - **`mintPlayerToken` no longer requires `playerPhone`.** `/api/sdk/player-token` is a
1151
- session-token mint for an **existing** player (looked up by email) — not a registration call.
1152
- It reads only `player_email` and ignores `player_phone`. The 2.0.0 hard E.164 requirement was
1153
- a bug: it could **block a valid token mint for an existing email-only player**. `playerPhone`
1154
- is now optional and validated only if provided. Phone stays enforced where it matters — the
1155
- sender's phone on `initiateSend`/`initiateTransfer`, and at player creation.
1156
- - **Send by phone alone.** `receiverPlayerEmail` (send) and `targetPlayerEmail` (transfer) are
1157
- now **optional** — you can send to a recipient's phone; they supply their email at claim
1158
- (claim still requires it, since that's where the recipient establishes identity).
1159
- - **`getPlayerBalance` is by email only.** There is no by-`playerId` balance route on the
1160
- backend, so passing `playerId` threw a confusing 404. It now throws a clear `INVALID_INPUT`
1161
- pointing you to `InvoClient.getBalance()` (client-side) or `playerEmail` (server-side).
1162
- - **New `InvoError.isUserVerificationRequired`** for the `WEBAUTHN_UV_REQUIRED` (401) approve
1163
- failure — re-run the passkey ceremony requiring UV.
1164
- - Fixed `iterateItemPurchaseHistory` to read the backend's `total_count` pagination key (was
1165
- `total`; the loop already terminated via the short-page guard, so behavior is unchanged).
1166
-
1167
- **Migration:** none required. If you were passing `playerPhone` to `mintPlayerToken` it still
1168
- works; you can now also omit it. Replace any `getPlayerBalance({ playerId })` with an email
1169
- lookup or `InvoClient.getBalance()`.
1170
-
1171
- ## [2.1.2] — 2026-07-07
1172
-
1173
- **Hosted-checkout reconciliation** (the create-session API contract is unchanged; the hosted
1174
- page was rebuilt). Additive + docs only.
1175
-
1176
- - `createCheckout` now surfaces `expiresInSeconds` (the `checkout_url` token TTL, e.g. 900) as
1177
- a first-class field on `CreateCheckoutResult` — previously only on `.raw`.
1178
- - README: the `platform` rail is described as cards + Apple Pay / Google Pay / Link +
1179
- international billing (no app-store commission), and the checkout note now says reloading the
1180
- URL after a completed payment is idempotent (an already-complete success screen), not an
1181
- error. No API/signature changes.
1182
-
1183
- ## [2.1.1] — 2026-07-06
1184
-
1185
- **Security & correctness hardening** from a full audit + red-team of both SDKs. No API changes;
1186
- upgrade recommended.
1187
-
1188
- - **Fail closed on HTTP redirects (security).** The transport now sends `redirect:"manual"` and
1189
- throws `UNEXPECTED_REDIRECT` on any 3xx instead of following it. Previously a redirect from
1190
- the API host could cause the game-secret header to be re-sent to an unvalidated URL (matches
1191
- the Python SDK fix, where the leak also covered the player token and an `http://` downgrade).
1192
- - **`retryAfter` no longer treats a blank `retry_after` as `0`.** An empty/whitespace
1193
- `retry_after` string used to become `0` (`Number("")===0`) — an immediate, no-backoff retry.
1194
- It's now correctly `undefined`, in both `InvoError.retryAfter` and the retry layer.
1195
- - **Whitespace OTP codes rejected client-side.** `recoveryComplete`/`enrollmentVerify` now
1196
- reject a whitespace-only `code` before the network call, so it can't burn an attempt against
1197
- the attempt-capped endpoints (parity with the Python SDK).
1198
- - **Webhook verify uses `crypto.timingSafeEqual`** on the sync path (parity with Python's
1199
- `hmac.compare_digest`); the runtime-agnostic async/edge path keeps its string compare.
1200
- - **WebAuthn option mappers fail cleanly.** A malformed `register/begin` body now throws
1201
- `WEBAUTHN_OPTIONS_MALFORMED` (an `InvoError`) instead of a raw `TypeError`.
1202
-
1203
- ## [2.1.0] — 2026-07-02
1204
-
1205
- **Passkey recovery ("lost or replaced my passkey").** Deleting a passkey on the device never
1206
- tells the server the key is gone, so re-enrollment was dead-ended by the anti-takeover gate
1207
- (`ENROLLMENT_REQUIRES_PROOF`) with nothing left to prove possession with. The backend shipped
1208
- a self-serve, possession-proofed recovery flow; this release wires the client side.
1209
-
1210
- - `InvoClient.recoveryBegin()` — sends a one-time code to the phone/email on file
1211
- (`{ status: "sent", channels }`); `InvoClient.recoveryComplete(code)` — deactivates the
1212
- stale server-side passkey and authorizes a fresh enrollment
1213
- (`{ status: "recovered", deactivatedCount, next }`). Then retry the same `enrollPasskey()`.
1214
- - New `InvoError` classifiers: `isEnrollmentCodeInvalid`, `isPasskeyRecoveryCooldown`, and
1215
- `retryAfterAt` (the ISO timestamp on the 403 cooldown — distinct from the numeric
1216
- `retryAfter` throttle field). Bare `no_channel_on_file` / `rate_limited` error tokens are
1217
- now promoted to `err.code`.
1218
- - **24-hour money cooldown surfaced:** a recovery-enrolled passkey logs in and collects
1219
- funds immediately, but `approveSend`/`approveTransfer` throw 403
1220
- `PASSKEY_RECOVERY_COOLDOWN` for 24h (SIM-swap protection). Branch on
1221
- `isPasskeyRecoveryCooldown`, show the pause message with `retryAfterAt`, don't retry-loop.
1222
- - README: recovery subsection under Passkeys, incl. the password-manager cleanup tip for
1223
- "there is a problem saving your passkey" (stale orphan entry).
1224
-
1225
- Additive, no breaking changes. Routes require SDK verification enabled for the tenant
1226
- (dark 503 otherwise).
1227
-
1228
- ## [2.0.0] — 2026-07-02
1229
-
1230
- **BREAKING — `mintPlayerToken` now requires `playerPhone` (E.164).** Requested by the INVO
1231
- backend after a live incident: a player registered email-only couldn't receive a cross-game
1232
- transfer (incoming transfers are matched by phone) and never got the account-linking consent
1233
- SMS (also phone-triggered). The network identity is derived from **email + phone together**,
1234
- so the phone must be present on the FIRST registration call — attaching it later changes the
1235
- identity and forces device re-enrollment.
1236
-
1237
- - `mintPlayerToken({ playerEmail, playerPhone })` — `playerPhone` is required and validated
1238
- as E.164 (`+15555550100`: leading `+`, country code, digits only) before any network call;
1239
- the body now posts `player_phone` alongside `player_email`.
1240
- - **Pending approval is surfaced, not an error to swallow:** minting with a phone that
1241
- already belongs to another INVO account (same person, new email) throws the existing
1242
- `isPhoneShareApprovalRequired` 409 — the phone holder got a consent SMS. New
1243
- `InvoError.phoneShareApprovalId` exposes the `approval_id` from the 409 body for the
1244
- `phoneShareApprove` OTP fallback. Docs updated to cover the registration path (previously
1245
- documented for claims only).
1246
- - README: new "Player registration (email + phone, required)" section; examples updated
1247
- (`proxy-server.ts` token route now rejects a phoneless actor with a clear 400).
1248
-
1249
- **Migration:** collect the player's phone in your enrollment UI before the first
1250
- `mintPlayerToken` call and pass it as `playerPhone` in E.164. Handle the
1251
- `isPhoneShareApprovalRequired` error as a "pending approval" UI state.
1252
-
1253
- ## [1.2.1] — 2026-07-01
1254
-
1255
- **Fix — browser "Illegal invocation".** The SDK invoked its fetch as `this.fetchImpl(...)`,
1256
- so the browser's native `fetch` ran with the wrong `this` and threw
1257
- `TypeError: Illegal invocation` — breaking every browser `InvoClient` read
1258
- (balance/destinations/pending) and the passkey ceremonies when using the default global
1259
- `fetch` (retries then made it slow on top). The fetch impl is now bound to `globalThis`
1260
- (harmless for a custom `fetch`). No API change. Node/tests were unaffected, which is why it
1261
- slipped through — added a `this`-sensitive regression test.
1262
-
1263
- ## [1.2.0] — 2026-07-01
1264
-
1265
- Two more server-side capabilities on `InvoServer`.
1266
-
1267
- - **Phone-share OTP handshake** — `phoneShareInitiate` / `phoneShareApprove` / `phoneShareStatus`
1268
- resolve a `409 PHONE_SHARE_APPROVAL_REQUIRED`. Unauthenticated (phone-owner-driven — no game
1269
- secret, no player token), relayed by a partner backend; after approve, re-issue the identical
1270
- original request (the grant is server-side + auto-consumed). Adds
1271
- `InvoError.isPhoneShareAlreadyApproved`.
1272
- - **Server-side `getDestinations`** — game-secret variant of the browser
1273
- `InvoClient.getDestinations`; pass `{ sourceGameId, direction }` (default `"transfer"`), rows
1274
- share the same `DestinationGame` shape.
1275
-
1276
- ## [1.1.0] — 2026-07-01
1277
-
1278
- Four additive server-side flows on `InvoServer` (the SMS-PIN / claim-code / status /
1279
- guardian paths partners still need alongside the passkey path).
1280
-
1281
- - **SMS-PIN completion** — `verifySmsTransfer` / `verifySmsSend` (for `verificationMethod: "sms"`).
1282
- - **Claim-by-code** — `claimTransfer` / `claimCurrency`, incl. the `needsAccountSelection`
1283
- multi-account disambiguation (a `200` with `candidates`, not an error).
1284
- - **Status reads** — `getTransferStatus` / `getSendStatus` (surface `verificationState`).
1285
- - **Guardian approval-status poll** — `getGuardianApprovalStatus` (poll a hold to `state`).
1286
- - New typed results (`SmsVerifyResult`, `ClaimResult`, `TransactionStatusResult`,
1287
- `GuardianApprovalStatusResult`) + `InvoError.isPhoneShareApprovalRequired`.
1288
-
1289
- ## [1.0.0] — 2026-07-01
1290
-
1291
- **1.0 — stable.** The public API is now covered by a stability commitment: it follows
1292
- semver and no breaking change ships without a major bump + migration note. This is a
1293
- milestone release, **not a breaking change** — code on `0.8.x` continues to work unchanged.
1294
-
1295
- Also in this release (docs + DX):
1296
-
1297
- - **Integration modes** documented — **browser-direct** (default) and **behind your proxy**
1298
- (keep the INVO player token server-side via a custom `baseUrl`/`fetch`; no CORS or
1299
- security-posture change). Plus a token-bootstrap example and a CORS + RP-ID/origins
1300
- go-live checklist.
1301
- - `linkDevice` called out as the lowest-risk first adoption (additive, no refactor).
1302
-
1303
- ## [0.8.0] — 2026-07-01
1304
-
1305
- Completes the **discovery layer** for send/transfer UIs.
1306
-
1307
- - **`InvoClient.getBalance()`** (browser, player-token, `GET /api/sdk/balance`) — the
1308
- player's balances for the token's game: `balances[]` (`currencyId`, `currencyName`,
1309
- `currencySymbol`/`currencySymbolUrl` (nullable), `availableBalance`/`reservedBalance`/
1310
- `totalBalance` as decimal strings) plus `totalValue` / `currencyCount` / `hasFunds`. A
1311
- player who hasn't transacted here yet returns an empty `balances` array (a `200`, not an
1312
- error); `404 GAME_NOT_FOUND` throws.
1313
- - **`InvoServer.getLinkedIdentities({ playerEmail | playerPhone })`** (server-only,
1314
- game-secret) — a player's linked wallet identities (game-scoped). Provide one identifier
1315
- (phone wins if both); no in-game match returns `notFound: true` with empty `emails`
1316
- instead of throwing. **Returns first-party PII — never expose to the browser.**
1317
-
1318
- ## [0.7.0] — 2026-07-01
1319
-
1320
- Start of the **discovery layer** for send/transfer UIs.
1321
-
1322
- - **`InvoClient.getDestinations({ direction })`** — one player-token call
1323
- (`GET /api/sdk/destinations`) returns every game the player can send/transfer to, with
1324
- all display metadata **inline** (game name, icon, currency name/symbol, min/max transfer
1325
- limits) — no per-game lookup. Includes source game/currency info and `transferMode`
1326
- (`universal`/`linked` + `linkedGameIds`).
1327
- - _(Coming in 0.7.x: `getBalance` single-game player-token read; `getLinkedIdentities`
1328
- server-side.)_
1329
-
1330
- ## [0.6.0] — 2026-07-01
1331
-
1332
- Three additive browser flows for partner front-ends, built to the live backend contracts.
1333
-
1334
- - **`InvoClient.getPendingCollect()`** — the player's own pending-to-collect list
1335
- (player-token `GET /api/sdk/transfers/pending`), PII-free. Each row's `kind`
1336
- (`identity_gate` → `approve*`, `receiving_confirm` → `confirmReceipt*`) tells you the
1337
- action; typed fields incl. `held` / `holdReason` / `stepUpRequired`.
1338
- - **First-enrollment OTP grant** — `enrollmentBegin()` / `enrollmentVerify(code)` for
1339
- `ENROLLMENT_REQUIRES_AUTHORIZATION` (send OTP to phone+email, verify, then retry the
1340
- same `enrollPasskey()` — the server grant is auto-consumed). New `InvoError` helpers
1341
- `isEnrollmentAuthorizationRequired` / `isEnrollmentProofRequired`.
1342
- - **Typed approve/confirm holds** — `approve*`/`confirmReceipt*` now surface a typed
1343
- `holdReason` (from `error_code ?? code`) on HTTP 202 holds, plus `risk` /
1344
- `guardianApproval` / `pollEndpoint` on approve. `RECIPIENT_IDENTITY_PENDING` correctly
1345
- surfaces on confirm-receipt. Success carries no `holdReason`.
1346
-
1347
- ## [0.5.0] — 2026-07-01
1348
-
1349
- Support partner `metadata` end-to-end on the purchase flow (additive, backward-compatible).
1350
-
1351
- - **`PurchaseCompletedData.metadata?`** — the `purchase.completed` webhook now echoes your
1352
- metadata back (all rails); `event.data.metadata` is typed.
1353
- - **`purchaseCurrency`** now accepts and forwards `metadata` (the direct `/purchase-currency`
1354
- endpoint accepts it too, matching `createCheckout`).
1355
-
1356
- ## [0.4.2] — 2026-06-30
1357
-
1358
- Fixes from an independent line-by-line audit against the live backend.
1359
-
1360
- - **`linkDevice` now works.** `device/link/webauthn/begin` returns a wrapped
1361
- `{ link_id, options }` body (challenge nested under `options`) and binds the
1362
- challenge to a server-generated `link_id`. The client now unwraps `options` and
1363
- echoes the server's `link_id` to `/complete` (it previously threw on an undefined
1364
- challenge and sent the wrong id).
1365
- - **`InvoError.code` is now populated for the direct purchase rail + guardian flows.**
1366
- `errorFromResponse` reads `error_code` (SecureErrorHandler + `/purchase-currency`)
1367
- in addition to `code`, and promotes known no-code tokens (`flow_paused`,
1368
- `spending_limit_exceeded`, `receiver_not_enrolled_use_claim_code`) to `.code`. Fixes
1369
- `isDuplicateRequest` on the direct rail.
1370
- - **Guardian/minor routing.** The 202 guardian body also carries
1371
- `verification_method:"sms"`; the SDK now suppresses it (reports
1372
- `verificationMethod: undefined`) so a guardian-pending minor isn't routed into the
1373
- SMS-PIN UI. README example reordered to branch on `guardianApproval` first.
1374
-
1375
- ## [0.4.1] — 2026-06-30
1376
-
1377
- Docs only — replaced the README's internal-leaking "Deployment prerequisites"
1378
- (backend flag names, DB columns, gating mechanics) with a partner-facing
1379
- "Before you go live"; republished so the npm page README is current.
1380
-
1381
- ## [0.4.0] — 2026-06-30
1382
-
1383
- Additive release — more server reads, edge-ready webhooks, cancellation, and tooling.
1384
-
1385
- - **`getInboundPending({ playerEmail | playerPhone })`** — live, unclaimed inbound
1386
- sends/transfers for a player (the source of truth behind the "you have X to collect"
1387
- badge; pairs with `transfer.claim_pending`).
1388
- - **`verifyWebhookAsync`** — Web Crypto variant of `verifyWebhook` that runs on
1389
- Cloudflare Workers / Deno / Vercel+Netlify Edge / Bun / browsers; and
1390
- **`createWebhookHandler`** — a zero-dep Fetch-API `(Request) => Promise<Response>`
1391
- webhook route handler (Next.js App Router, Workers, Deno, Hono, Bun).
1392
- - **`iterateItemPurchaseHistory`** — async iterator that pages through a player's
1393
- full item-purchase history.
1394
- - **Per-call `AbortSignal`** — every method accepts an optional `{ signal }`; an
1395
- aborted call throws `InvoError` code `ABORTED` and is never retried.
1396
- - **Tooling**: ESLint (+ lint in CI), changesets release automation, `SECURITY.md`,
1397
- and `CODEOWNERS`.
1398
-
1399
- ## [0.3.0] — 2026-06-30
1400
-
1401
- Additive release — new server capabilities plus transport resilience/observability.
1402
-
1403
- - **Webhook verification** (`/server`): `verifyWebhook(rawBody, signatureHeader, secret | secrets, opts?)`
1404
- — constant-time HMAC-SHA256 over `${t}.${rawBody}`, 5-minute replay window,
1405
- multi-secret rotation; returns a typed `InvoWebhookEvent` discriminated union
1406
- (`purchase.*`, `item.purchased`, `transfer.*`, `payout.status_changed`, `webhook.test`).
1407
- Throws `InvoError` (`WEBHOOK_SIGNATURE_INVALID` / `WEBHOOK_TIMESTAMP_EXPIRED` /
1408
- `WEBHOOK_MALFORMED` / `WEBHOOK_SECRET_MISSING`). Server-only; the browser bundle
1409
- stays crypto-free. Independently security-audited.
1410
- - **`getPlayerBalance({ playerEmail | playerId })`** (`/server`): typed `player` / `balances` / `summary`.
1411
- - **Automatic retries**: network errors/timeouts, `429` (honoring `retry_after`), and
1412
- `5xx` are retried with exponential backoff + jitter. New config `maxRetries`
1413
- (default 2, `0` disables) and `retryBaseDelayMs` (default 250).
1414
- - **Observability hooks**: optional `onRequest` / `onResponse` / `onError` on both
1415
- entries (best-effort/non-throwing); `InvoError.requestId` carries the backend
1416
- request id for support/tracing.
1417
- - **Typed reads**: `confirmPayment` → `ConfirmPaymentResult`; `getOrderDetails` /
1418
- `getItemOrderDetails` → `OrderDetailsResult`; `getItemPurchaseHistory` →
1419
- `ItemHistoryResult` (previously untyped `Record`). All keep `raw`.
1420
- - **Light validation**: `mintPlayerToken` and `createCheckout` require a non-blank
1421
- `playerEmail` (throws `INVALID_INPUT` before the network call).
1422
- - **License**: `package.json` `license` is now `SEE LICENSE IN LICENSE` (was
1423
- `UNLICENSED`); `LICENSE` rewritten as an explicit install-and-use grant for
1424
- building INVO integrations.
1425
-
1426
- ## [0.2.1] — 2026-06-30
1427
-
1428
- Docs only — no code change (republished so the npm page README is current).
1429
-
1430
- - Rewrote the README into a complete integration/deployment guide: capability
1431
- overview, architecture, deployment prerequisites, per-flow sections (currency
1432
- purchase, item purchase, sends, transfers, passkeys), webhooks, errors, and a
1433
- full API reference for both entries.
1434
- - Added INVO console onboarding: `https://console.invo.network` (production) and
1435
- `https://dev.console.invo.network` (testing/sandbox), mapped to their API base URLs.
1436
-
1437
- ## [0.2.0] — 2026-06-30
1438
-
1439
- Adds **item purchase** (spend existing game currency on an in-game item, §4.8) — an
1440
- additive, server-only surface.
1441
-
1442
- - `InvoServer` (`/server`): `purchaseItem`, `getItemPurchaseHistory`, `getItemOrderDetails`.
1443
- - Server-side, game-secret auth — no passkey, no real money, no payment rail (it's a
1444
- balance debit). Grant the item off the `item.purchased` webhook.
1445
- - Client-side guards: required fields (trim-checked), `itemQuantity` integer `1..1000`,
1446
- prices `> 0` and `<= 999999.99` (magnitude-safe 2-decimal check), and
1447
- `totalPrice == unitPrice × itemQuantity (±0.01)` compared in integer cents.
1448
- - Load-bearing response fields (`transaction_id`, `order_id`) throw `INVALID_RESPONSE`
1449
- if missing on a 200.
1450
- - `InvoError` helpers: `isInsufficientBalance` (gated to 400; not the `429` throttle),
1451
- `isDuplicateRequest` (409), `retryAfter` (numeric or string `retry_after`); all
1452
- null-safe against non-JSON error bodies.
1453
- - Independently audited (2 agents) against handoff doc §4.8/§6/§8; contract verified,
1454
- error-classification edge cases fixed.
1455
-
1456
- ## [0.1.0] — 2026-06-30
1457
-
1458
- Initial scaffold.
1459
-
1460
- - `InvoServer` (`/server`): `mintPlayerToken`, `initiateSend`, `initiateTransfer`,
1461
- `createCheckout`, `purchaseCurrency`, `confirmPayment`, `getOrderDetails`.
1462
- - Client-side purchase guards (§4.7): USD amount `0 < x ≤ 999.99`, required
1463
- `purchaseReference`, and `rail:"steam"` rejected before the network call
1464
- (`INVALID_INPUT` / `MISSING_PURCHASE_REFERENCE` / `WRONG_RAIL_ENDPOINT`).
1465
- - `InvoClient` (browser): `enrollPasskey`, `approveSend`/`approveTransfer`,
1466
- `confirmReceiptSend`/`confirmReceiptTransfer`, and `linkDevice` for the
1467
- interchangeable-methods flow (§4.6).
1468
- - Optional `refreshToken` hook: transparently re-mints and retries once on
1469
- `SDK_TOKEN_EXPIRED` (§11.2).
1470
- - Shared: typed `InvoError`, isomorphic HTTP client, WebAuthn JSON⇄binary helpers.
1471
- - Tests: HTTP layer, server request mapping + purchase guards, browser client
1472
- flows (enroll/approve/link/token-refresh), and WebAuthn serialization.
1473
- - Contracts extracted + auditor-verified against the INVO backend.
1474
-
1475
- ### Hardening (independent red-team pass)
1476
-
1477
- - **Guardian/minor `202` path no longer mismapped to `verificationMethod:"sms"`** —
1478
- `initiateSend`/`initiateTransfer` now return `verificationMethod: undefined` and a
1479
- `guardianApproval` block on the guardian path, so callers don't route into the
1480
- PIN UI by mistake (§4.3).
1481
- - `usdAmount` validation tightened: rejects non-plain-decimal strings
1482
- (`"0x10"`, `"1e2"`, whitespace) and >2 decimal places before any network call.
1483
- - Load-bearing response fields (`token`, `checkout_url`) now throw `INVALID_RESPONSE`
1484
- instead of silently surfacing as empty strings.
1485
- - `getOrderDetails` requires at least one of `orderId`/`transactionId`.
1486
- - Token refresh now re-runs the **whole** passkey ceremony on `SDK_TOKEN_EXPIRED`
1487
- (never replays a single-use assertion) and single-flights concurrent refreshes.
1488
- - `baseUrl` must be `https://` (localhost exempt) so the token/secret can't travel
1489
- in cleartext.
1490
- - Published tarball excludes sourcemaps (no proprietary source shipped).
1
+ # Changelog
2
+
3
+ ## 3.34.1
4
+
5
+ ### Patch Changes
6
+
7
+ - Console links now point at the one INVO console: live mode at `https://console.invo.network`, test mode at `https://console.invo.network/test`. The game UI's "Open the INVO console" link for a sandbox game, the README console table, and the sandbox clock key guidance (README, `sandboxClockKey` and `isSandboxClockUnauthorized` docs, and the `INVALID_INPUT` message) now name the console in test mode. The old `https://dev.console.invo.network` address still redirects there. API hosts are unchanged. No code or type changes beyond the link and the message text.
8
+
9
+ ## 3.34.0
10
+
11
+ ### Minor Changes
12
+
13
+ - Key prefixes name the environment. New keys are `ivsdk_live_...` (production) and `ivsdk_test_...` (sandbox). `resolveEnvironment`, `baseUrlForKey` and `invoGameServerFromEnv` pick the environment from the prefix with no network call, as they already did for the demo key. Older `ivsdk_...` keys keep working and are still looked up with `GET /api/sdk/key-environment`, exactly as before.
14
+ - New `environmentFromKeyPrefix(key)`: `"production"`, `"sandbox"` or `null` (an unprefixed key). Also exported: `environmentForBaseUrl(url)`, `LIVE_KEY_PREFIX`, `TEST_KEY_PREFIX` and `KeyEnvironmentMismatchError`.
15
+ - A live or test key paired with the other INVO host now throws `KeyEnvironmentMismatchError` at construction, before any request: `new InvoServer({ gameSecret, baseUrl })`, and `invoGameServerFromEnv` with `INVO_BASE_URL` or an `INVO_ENV` that disagrees with the key. A base URL that is not an INVO host (your own proxy) is never checked, and unprefixed and demo keys are never checked.
16
+ - `InvoError.isKeyForOtherEnvironment` for `KEY_FOR_OTHER_ENVIRONMENT` (401): the key belongs to the other environment. Not retried.
17
+ - Webhook signing secrets made from now on start with `whsec_live_` or `whsec_test_`. Nothing changes: the whole secret is the signing key, as before.
18
+
19
+ ## 3.33.0
20
+
21
+ ### Minor Changes
22
+
23
+ - Platform Commerce: buyer-approved balance purchases. `purchase({ requirePlayerApproval: true, returnUrl })` returns `status: "pending_approval"` with `approvalId` and `approvalUrl`; nothing is debited until the buyer approves on INVO's page. New `getApproval({ approvalId | clientRequestId })` and `cancelApproval(approvalId)` (`PlatformApprovalResult`), and error helpers `isBalanceUnavailable`, `isApprovalNotAvailable`, `isApprovalNotFound`, `isApprovalAlreadyEnded`. Webhooks: `platform_commerce.declined` (opt-in, never delivered through `*`); `metadata` on `platform_commerce.purchased` and `platform_commerce.refunded` (both legs). All additive.
24
+
25
+ ## 3.32.0
26
+
27
+ ### Minor Changes
28
+
29
+ - Add `InvoError.isPaymentsPaused` for `PAYMENTS_PAUSED` (403): INVO has paused new payments on the developer account. Every call that starts a payment returns it; refunds, reads, balances, transfers and existing subscription renewals keep working.
30
+
31
+ ### Patch Changes
32
+
33
+ - 34f0767: Doc comment: `guarantee_covered` on `purchase.disputed` no longer says a lost coin chargeback costs you nothing; a coin purchase dispute reports what it charged you in `spent_coins_charged_usd`. No code or API change.
34
+
35
+ ## 3.31.0
36
+
37
+ ### Minor Changes
38
+
39
+ - Types the backend fields that shipped 2026-10-20. All additive; nothing renamed or removed.
40
+
41
+ - `platformCommerce.getStatus()` and every `getPurchaseHistory()` entry: `invoFeeUsd` (everything INVO kept on the sale) and `partnerShareUsd` (what you earned), USD decimal strings. `null` until the sale settles or when the split cannot be read; absent from an INVO release that does not send them. A later refund or lost dispute does not change them.
42
+ - `purchase.disputed` (coin purchase, on close): `spent_coins_charged_usd`. On a lost dispute INVO takes back the coins the player still holds and charges you for coins already spent, at the price paid per coin before tax; `"0.00"` when nothing was charged.
43
+ - Errors: `err.isRateLimited` (true on any 429; every rate-limit refusal now carries `error_code` `RATE_LIMITED`, `retry_after` and a `Retry-After` header). `err.retryAfter` falls back to the `Retry-After` header when the body has no `retry_after`; the raw header is on `err.retryAfterHeader`. `errorFromResponse` takes an optional fourth argument for it.
44
+ - README: dispute holds on both tiers (the disputed amount is held from your earnings while a dispute you are responsible for is open), the spent-coin charge on a lost coin purchase dispute, and the payout minimum is now $10 (scheduled and on demand; it was $100).
45
+
46
+ ## 3.30.4
47
+
48
+ ### Patch Changes
49
+
50
+ - cbf46e7: Docs and doc comments: INVO's hosted pages (hosted checkout on every rail, the hosted card page and the subscription payment confirmation page) show the INVO logo by default, or the game's own logo when one is set in the INVO console (Game settings, Checkout branding), with a "Secured by INVO" line at the bottom. The `CreateCheckoutInput.rail` comment and the README no longer say the pages are always INVO-branded. The logo is set in the console only; there is no new SDK call. No code or API change.
51
+
52
+ ## 3.30.3
53
+
54
+ ### Patch Changes
55
+
56
+ - Docs and docstrings: `partnerFeeUsd` examples now read $0.50 on a $10.00 Open purchase ($0.65 on Merchant of Record), matching 3.5% + $0.15 / 5.0% + $0.15; the last "$0.65 on Open" examples are corrected.
57
+ - Payouts: scheduled payouts (the 1st and 16th of each month, UTC, $100 minimum) are free; payouts requested on demand are 1% capped at $500 with a $100 minimum. Creator payouts keep the fee.
58
+ - Release history in the README states the prices each earlier release shipped with again (3.18.0, 3.22.0), which 3.30.2 had overwritten with today's rates.
59
+ - No code or API change.
60
+
61
+ ## 3.30.2
62
+
63
+ ### Patch Changes
64
+
65
+ - Docs and docstrings follow the 2026-10-15 pricing: INVO card fee 3.5% + $0.15 on Open and 5.0% + $0.15 on Merchant of Record (was 3.5% + $0.30 and 5.5% + $0.50), plus 1.5% on cards issued outside the US; item purchases 5% (you keep 95%). Worked examples recomputed ($10.00 coin pack: $0.50 Open, $0.65 MoR). No code or API change.
66
+
67
+ ## 3.30.1
68
+
69
+ ### Patch Changes
70
+
71
+ - Demo key: `POST /transfers/{id}/approve` no longer returns the claim code to the sender's browser (`claimCode` is always `null`). The game server keeps it and collects for the recipient, so the browser never needed it.
72
+ - UI kit: moves to INVO Demo Arcade on the demo key are described as delivered automatically once approved, matching the backend, instead of refunded after 24 hours.
73
+ - Game server: a purchase is confirmed even when the signed webhook can't reach the server (for example a private `*.replit.dev` development preview, which refuses requests that don't come from a signed-in browser). While a purchase is pending, `GET /purchases/{ref}` reads the checkout's status from INVO server-side, with the session token kept on the server, and credits from INVO's answer. The webhook and the status read credit under the same ledger ref, so whichever lands first wins and the other is a no-op. The browser's word is never used.
74
+ - `InvoServer.getCheckoutStatus({ sessionId, sessionToken })`: the server-side read of a hosted checkout's status.
75
+ - Nothing removed or renamed.
76
+
77
+ ## 3.30.0
78
+
79
+ ### Minor Changes
80
+
81
+ - Game layer: player-to-player **transfers and sends**. Both rails are approved with the sender's passkey on INVO's hosted page; the game server only starts them.
82
+ - **Server routes:**
83
+ - `GET /transfers/status`: whether transfers are on, who can receive and which recipient details to ask for.
84
+ - `POST /transfers/token`: a short-lived player token for approving and collecting.
85
+ - `POST /transfers`: `{ kind: "transfer" | "send", targetGameId, amount, recipientEmail?, recipientPhone?, senderPhone?, clientRequestId? }`.
86
+ - **When they're on:** the public demo key and production keys. Other sandbox keys are off unless `INVO_TRANSFERS=on`, and `INVO_TRANSFERS=off` turns them off anywhere. The server option is `transfers: boolean | "auto"`.
87
+ - **On the demo key:**
88
+ - transfers are scoped to the project
89
+ - the friend's email is mapped with `toDemoEmail`
90
+ - both sides get fictional phones (`demoPhoneFor`), so a real address or number never reaches INVO
91
+ - **On a real key:** the recipient's phone is required, and the sender's stored phone is used. `SENDER_PHONE_REQUIRED` when the game never stored one.
92
+ - **Demo-key approval.** INVO's passkey page can't be completed by demo players, so the game server does both steps itself:
93
+ - It approves in INVO's demo sandbox with `POST /transfers/{id}/approve`, using the new `invo.sandbox.approveDemoMove`.
94
+ - It keeps the claim code in the store (`demoMoves`).
95
+ - The recipient lists what's waiting with `GET /transfers/pending` and collects with `POST /transfers/{id}/collect`, which calls `claimCurrency` with the kept claim code.
96
+ - These three routes answer `409 PASSKEY_REQUIRED` on real keys.
97
+ - `InvoGameEconomy`:
98
+ - Methods: `transferStatus()`, `prepareTransfers()`, `transferDestinations()`, `startTransfer(input)`, `approveTransfer(start)`, `pendingTransfers()` and `collectTransfer(item, approval)`.
99
+ - `transferDestinations()` lists this game first (`thisGame`, send rail only; a transfer to your own game is refused), then INVO's destination list.
100
+ - Status and start answers carry `approval: "passkey" | "sandbox"`.
101
+ - Call the approve and collect methods directly from a click: they open INVO's hosted page.
102
+ - New event: `transfer` (`TransferUpdate`).
103
+ - New option: `invoFetch`.
104
+ - UI kit:
105
+ - `ui.openTransfers(tab?)` and a Transfer button in the HUD. The button shows a lock while transfers are off; `hideTransferButton` hides it.
106
+ - A Send / Collect dialog with destinations and limits, a review step, the passkey step and claim codes.
107
+ - The demo copy says transfers work between players of the project.
108
+ - UI kit: `[hidden]` now always hides (the phone field on the demo key showed through `.invo-field`'s `display:flex`).
109
+ - New types: `GameTransferKind`, `GameTransferStatus`, `GameTransferInput`, `GameTransferStart`, `GameTransferDestination`, `TransferUpdate` and `StoredDemoMove`. `ApproveHostedResult`, `DestinationGame` and `PendingCollectItem` are re-exported from the game entry.
110
+ - Nothing removed or renamed.
111
+
112
+ ## 3.29.1
113
+
114
+ ### Patch Changes
115
+
116
+ - Remix detection on Replit now uses `REPL_ID`: the same Repl keeps its project id when it moves from `*.replit.dev` (building) to `*.replit.app` (deployed), and `registerProject` re-registers the new webhook URL with the saved registration token. A different `REPL_ID` is a remix and gets a fresh project id. Outside Replit a changed public host still counts as a remix. The project file now records `replId`.
117
+ - `GET /catalog` adds `demo` (true on the public demo key) and `playerFields.phone` (`"hidden"` on the demo key, `"first_sign_in"` otherwise); `/health` and `invoGameServerFromEnv` also report `demo`. The UI kit hides the phone field when the catalog says so.
118
+ - Nothing removed or renamed.
119
+
120
+ ## 3.29.0
121
+
122
+ ### Minor Changes
123
+
124
+ - Public demo sandbox (INVO game templates): on the demo key, `invoGameServerFromEnv` maps every sign-in to the demo sandbox's player email format for the fork's project (`toDemoEmail`) and gives the player a fictional 555-01XX phone (`demoPhoneFor`), so no real address or number reaches INVO. The project id comes from `INVO_PROJECT_ID`, else `.invo/project.json` (option `projectFile`), else a new one written there; a copied file on a different public host (a remix) gets a fresh id.
125
+ - New `registerProject({ gameSecret, webhookUrl, file? })` (game-server entry): registers the fork on every start, stores the webhook signing secret and the registration token in the project file the first time, and handles a remix's `409 PROJECT_REGISTERED` by taking a fresh project id. `invoGameServerFromEnv` reads the webhook secret from that file when `INVO_WEBHOOK_SECRET` is not set, or from the new `webhookSecret` option.
126
+ - `verifyInvoSignature(rawBody, header, secrets)`: the INVO webhook signature check under the name the template guide uses (same as `verifyWebhook`).
127
+ - The key-environment lookup is retried on each call until it succeeds (a failure at boot no longer wedges the server), and a production error falls through to the sandbox lookup.
128
+ - `InvoGameServerSetup.environment` is `"sandbox"`, `"production"` or `"resolving"`; `sandbox` is no longer `true` for a live key whose environment is still being looked up.
129
+ - Nothing removed or renamed.
130
+
131
+ ## 3.28.0
132
+
133
+ ### Minor Changes
134
+
135
+ - Going live is swapping the key. `invoGameServerFromEnv` now picks the environment from `INVO_GAME_SECRET`: the public demo key (`ivsdk_demo_...`, baked into INVO's game templates) is the sandbox; any other key is looked up once with `GET /api/sdk/key-environment` (production first, then the sandbox) and cached. `INVO_ENV` and `INVO_BASE_URL` still override it.
136
+ - `X-Invo-Project-Id` is now sent on every call in both environments, so the first live call after go-live links the template project to your INVO account. `INVO_PROJECT_ID` is read when `projectId` is not passed. The id format is `proj_` + a 26-character uppercase Crockford ULID; `newProjectId()` (game-server entry) makes one.
137
+ - New exports (server and game-server entries): `resolveEnvironment`, `baseUrlForKey`, `isDemoKey`, `EnvironmentUnknownError`, `PRODUCTION_BASE_URL`, `SANDBOX_BASE_URL`, `DEMO_KEY_PREFIX`.
138
+ - Nothing removed or renamed.
139
+
140
+ ## 3.27.0
141
+
142
+ ### Minor Changes
143
+
144
+ - Loyalty: `InvoServer.reportGameEvent({ playerEmail, eventType, eventId?, occurredAt?, payload? })` (`POST /api/sdk/loyalty/server-events`, game secret, trusted for rewards) and `InvoClient.reportGameEvent(...)` (`POST /api/sdk/loyalty/events`, player token). `eventId` is generated when omitted and returned; the server call retries with it. Types `GameEventType`, `ReportGameEventInput`, `ReportServerGameEventInput`, `ReportGameEventResult`.
145
+ - New entry `@invonetwork/web-sdk/game-server`: the server half of a browser game's economy. `invoGameServerFromEnv` / `createInvoGameServer` serve sessions, the premium wallet (read from INVO), a soft-currency ledger, hosted checkout, signed-webhook crediting processed exactly once, idempotent item purchases (premium through `purchaseItem`, soft through the ledger), rate-limited earnings, loyalty events and rewards, under `/api/invo`. `createFileGameStore` (atomic JSON file) and `createMemoryGameStore`; `toNodeListener` adapts it to `node:http`. With secrets missing it answers `503 INVO_SETUP_REQUIRED` and keeps `/health` and `/catalog` up.
146
+ - New entry `@invonetwork/web-sdk/game`: `InvoGameEconomy` (the browser client for that server: sign-in, wallet events, `buyItem`, `buyPremium` with popup or redirect checkout, batched `earn`, `reportEvent`) and `mountInvoUI`, a framework-free DOM kit (balance HUD, buy-currency modal, shop grid, sign-in, toasts) in the INVO palette, themeable by CSS variables. Holds no secret. Used by `@invonetwork/phaser` and `@invonetwork/three`.
147
+ - `invoGameServerFromEnv` accepts `projectId` (sent to the sandbox as `X-Invo-Project-Id` on every call, never in production) and `fetch`. `InvoGameEconomy.checkSetup()` re-asks the server whether its INVO secrets are set; the UI kit's developer setup guide uses it to notice when the keys arrive.
148
+ - The UI kit ships the INVO design: a glass wallet HUD with animated balance changes, a tabbed shop with lit item cards, ownership chips and stack pips, premium packs with a best-value ribbon, sign-in with field icons, a step-by-step developer setup guide, toasts, and bottom sheets on phones. It respects `prefers-reduced-motion`.
149
+ - Nothing removed or renamed; the `.` and `./server` entries are unchanged apart from the two new methods.
150
+
151
+ ## 3.26.1
152
+
153
+ ### Patch Changes
154
+
155
+ - Types: `Payee` gains `payable` and `payable_blockers` (`PayableBlocker`, exported from the server entry). Check `payable` before offering a payout to a creator.
156
+ - Docs: refusals add `PAYEE_TERMS_NOT_ACCEPTED` (the creator hasn't accepted INVO's current Payee Terms yet), and removing a creator with a payout still being processed reports `payouts_in_flight_by_status`.
157
+ - Nothing removed or renamed.
158
+
159
+ ## 3.26.0
160
+
161
+ ### Minor Changes
162
+
163
+ - Server: `invo.payouts.removePayee(payeeId)` (`POST /api/partner-payees/{payeeId}/remove`): remove a creator from your program; the status becomes `closed`.
164
+ - Types: `PayeeStatus` gains `closed`; `Payee` gains `erased`; `Payout` and `PayoutStatusChangedData` gain `return_reason_code` (typed `ReturnReasonCode`), `partner_message` and `owner_confirmation_required` (`Payout` also `owner_confirmed_at`). `PayoutStatusChangedData.status` and `previous_status` are typed `PayoutStatus`. `PayoutStatus` and `ReturnReasonCode` are exported from the server entry and from webhooks.
165
+ - Docs: `requestPayout` takes exactly one of `payeeId` or `bankAccountId`; the comment no longer says a request without either defaults to your own bank. Refusal codes listed in full.
166
+ - Behaviour on the API, not the SDK: partner payout reads and `payout.status_changed` no longer carry INVO's internal notes (`admin_note`), admin ids (`reviewed_by_admin_id`, `initiated_by_admin_id`) or the accounting provider's fields (`qb_vendor_id`, `qb_bill_id`, `qb_payment_reference`). They were never part of the documented contract; read `partner_message` for a note INVO writes for you.
167
+ - Nothing in the SDK removed or renamed.
168
+
169
+ ## 3.25.0
170
+
171
+ ### Minor Changes
172
+
173
+ - Server: `InvoServer.payouts`, partner payouts and creator payouts. `registerPayee` (`POST /api/partner-payees`), `listPayees`, `getPayee`, `resendPayeeInvite`, `requestPayout` (`POST /api/partner-payouts/request`, with `payeeId` to have INVO pay a verified creator from the earnings INVO owes you, or `bankAccountId` for your own verified bank), `getPayout`, `listPayouts` (optional `payeeId`) and `cancelPayout` (a creator payout still `requested`). Results keep the API's snake_case fields. Creators are INVO's customers: you see their status only, never their documents, tax id or bank details.
174
+ - Webhook types: `payee.status_changed` is typed as `PayeeStatusChangedData`. `PayoutStatusChangedData` gains `payee_id`, `payout_method` and `returned_at`. Payout statuses now include `cancelled` and `returned`.
175
+ - Nothing removed or renamed.
176
+
177
+ ## 3.24.1
178
+
179
+ ### Patch Changes
180
+
181
+ - Player activity: on the recipient's entry for a send or transfer from another game, `grossAmount` and `feeAmount` are now filled in the recipient's currency (`grossAmount - feeAmount === amount`). They were `null` on every cross-game entry. Doc comment updated; no type change.
182
+
183
+ ## 3.24.0
184
+
185
+ ### Minor Changes
186
+
187
+ - Player activity: send and transfer entries from `getPlayerActivity` / `iteratePlayerActivity` carry the fee. On the sender's entry `feeAmount` and `netAmount` (what the recipient gets) sit beside the gross `amount`; on the recipient's entry `grossAmount` and `feeAmount` sit beside `amount` (what arrived). While a send waits to be collected they show the fee that will apply; `null` when it ended without being collected, and on the recipient side of a currency-converting transfer. Purchases do not carry them.
188
+ - Errors: initiate-send and initiate-transfer amount-limit refusals now carry `error_code` `AMOUNT_BELOW_MINIMUM` / `AMOUNT_ABOVE_MAXIMUM` with the limit. `err.isAmountBelowMinimum` (now also true for these, and on the wallet transfer route where `err.code` stays `INVALID_AMOUNT`), new `err.isAmountAboveMaximum`, `err.minimumAmount`, `err.maximumAmount` and `err.limitCurrencyName`. A sender phone that does not match the one on file now carries `PHONE_MISMATCH` (400); `err.isPhoneMismatch` covers it as well as `registerPlayer`'s 409.
189
+ - Webhook types: `identity.passkey_reset` is typed as `IdentityPasskeyResetData` (`identity_id`, `reset_via`, `cooldown_until`, `deactivated_count`). It now also fires for an in-app recovery (`reset_via: "sdk"`) and can be subscribed to by name.
190
+ - Nothing removed or renamed.
191
+
192
+ ## 3.23.0
193
+
194
+ ### Minor Changes
195
+
196
+ - Webhook types: `PurchaseEventData` gains `dispute_fee_usd` (`string | null`, USD decimal such as `"15.00"`, `"0.00"` when INVO bears the fee) and `dispute_fee_charged_to_partner` (`boolean | null`), carried on a card `purchase.disputed` when the dispute closes. From November 8, 2026 the card dispute fee on Open-tier card sales (coin purchases, Platform Commerce card sales and subscription charges) is passed through to you at cost. A lost dispute is `purchase.disputed` with `dispute_status: "lost"`, not a separate event. README updated. Both fields optional; nothing removed or renamed.
197
+
198
+ ## 3.22.0
199
+
200
+ ### Minor Changes
201
+
202
+ - e3895ab: 2026-10 pricing and new reads. Server: `getPlayerActivity({ playerEmail, limit?, cursor?, types? })`
203
+ (`GET /api/sdk/players/activity`), one merged, newest-first page of a player's currency purchases,
204
+ item purchases, Platform Commerce purchases, sends and transfers, and `iteratePlayerActivity`, which
205
+ follows `nextCursor`. `platformCommerce.getPurchaseHistory({ playerEmail, limit?, cursor? })`
206
+ (`GET /api/platform-commerce/purchase-history`, entries shaped like `getStatus`) and
207
+ `platformCommerce.iteratePurchaseHistory`. `getTransferStatus` / `getSendStatus` results carry
208
+ `expiryReason` once expired. Webhook types: `TransferEventData` gains `order_id`,
209
+ `net_transfer_amount`, `claim_code_expires_at`, `from_game_id`, `to_game_id`, `from_player_id`,
210
+ `expired_at`, `reason`, `expiry_reason` and `refunded_amount`; `payout.status_changed` is typed as
211
+ `PayoutStatusChangedData`, with the payout fee fields `offboarding_fee_pct`, `offboarding_fee_usd`,
212
+ `offboarding_fee_cap_usd` and `net_payout_usd`. New additive `err.publicCode`: the
213
+ provider-neutral twin of a code (INVO's `error_code_public` on errors from the API). The SDK's own
214
+ pre-network refusal of a Platform Commerce card total under $0.50 keeps `err.code` exactly as
215
+ before and now also carries `err.publicCode === "BELOW_CARD_MINIMUM"` and `err.minUsd === "0.50"`;
216
+ `err.isBelowCardMinimum` is true as before and accepts both spellings. Nothing removed or renamed. README: the
217
+ Open card fee is 3.5% + $0.30 (was 4.5%); the chargeback guarantee is a Merchant of Record term
218
+ (Open-tier card payments made before November 8, 2026 keep it); transfers are 10% (3.5% / 3.5% /
219
+ 3%); payouts carry a 1% fee capped at $500 per payout; the hosted checkout reports a finished
220
+ purchase as status `"completed"`; on `phoneMismatch`, call `updatePlayerPhone`. Additive only.
221
+ - Player-confirmed phone change. Server: `requestPhoneChange({ playerEmail, newPhone })`
222
+ (`POST /api/sdk/players/phone/change-requests`, 202, never auto-retried) returns
223
+ `changeRequestId`, `status`, `expiresAt`, `delivery`, `confirmation` and `message`; INVO emails
224
+ the player, who confirms on INVO's page (plus their passkey or enrolled device when they have
225
+ one). `getPhoneChange(changeRequestId)` reads the request. Browser, with the player token, on
226
+ the player's enrolled device: `listPhoneChangeApprovals()` and
227
+ `approvePhoneChange(changeRequestId, { deviceFingerprint, decision?, sign | deviceSignal })`,
228
+ which sends a `device_signal` over `phone-change|<id>|<nonce>|<timestamp>` (or
229
+ `phone-change-deny|...`); new `phoneChangeSignalMessage()` builds that message. No method sends
230
+ a confirmation code: games never collect it. `err.changeRequestEndpoint` on
231
+ `PHONE_CHANGE_REQUIRES_VERIFICATION`; new error predicates `isConfirmOnInvoPage`,
232
+ `isChangeRequestNotFound`, `isChangeRequestNotReady`, `isChangeRequestNotPending` (with
233
+ `changeRequestStatus`), `isChangeRequestInProgress`, `isPhoneChangeLocked`,
234
+ `isTooManyChangeRequests`, `isPhoneChangeUnavailable`, `isDeviceSignalRejected`,
235
+ `isPhoneChangeRecoveryCooldown` (`PHONE_CHANGE_RECOVERY_COOLDOWN`, 409 on create and approve:
236
+ a recent sign-in recovery; retry later, declining still works) and
237
+ `isDeviceEnrolledAfterRequest` (`DEVICE_ENROLLED_AFTER_REQUEST`, 409 on approve). New
238
+ `isPendingTransfersToOldPhone` / `isPendingTransfersToNewPhone`, which `updatePlayerPhone`
239
+ now also answers (409, no counts) as well as the change request routes. Webhook
240
+ type: `player.phone_changed` as `PlayerPhoneChangedData` (`new_phone` only for the requesting
241
+ game). README section "Player-confirmed phone change": on `phoneMismatch` or
242
+ `player.phone_changed`, never push a stored number back; ask the player. Additive only.
243
+
244
+ ## 3.21.0
245
+
246
+ ### Minor Changes
247
+
248
+ - 0238b53: Player registration, phone changes and identity re-key. Server: `mintPlayerToken` takes optional
249
+ `playerPhone` and `playerName`; with a phone, a player new to your title is created, and the
250
+ result now carries `created` and `phoneMismatch` (previously dropped). New
251
+ `registerPlayer({ playerEmail, playerPhone, playerName? })` (`POST /api/sdk/players`) and
252
+ `updatePlayerPhone({ playerEmail, newPhone })` (`POST /api/sdk/players/phone`, never
253
+ auto-retried). `initiateSend` / `initiateTransfer` results expose `identityRekeyed`,
254
+ `playerToken`, `playerTokenExpiresAt`, `identityId` and `claimDeliveryPlanned`; approve results
255
+ expose `claimDelivery`. New error predicates `isPlayerTokenStale`,
256
+ `isPhoneChangeRequiresVerification`, `isPhoneMismatch`, `isPhoneShareRefused`;
257
+ `isPlayerNotFound` also recognises the codeless `player_not_found` 404. A 403
258
+ `PLAYER_TOKEN_STALE` on approve is surfaced, never auto-retried: re-mint and retry once.
259
+ Additive only. README section "Registering players and changing their phone".
260
+
261
+ ## 3.20.0
262
+
263
+ ### Minor Changes
264
+
265
+ - 1dc07df: Loyalty and rewards. Server: `InvoServer.getPlayerRewards(playerEmail)` reads one player's
266
+ loyalty cards with the game secret (`GET /api/sdk/loyalty/players/rewards`). Browser, with the
267
+ player token: `InvoClient.getMyRewards()` (the player's cards), `getMyVault()`,
268
+ `redeemReward(vaultEntryId)` (the only response with a code; never auto-retried) and
269
+ `getRewardsPageLink()` (INVO's hosted "My rewards" page). Every card step carries `progress`,
270
+ `{ current, target }`, or `null` when unavailable; `state` decides completion. New error
271
+ predicates `isRewardAlreadyRedeemed`, `isRewardNotFound`, `isRewardExpired`,
272
+ `isRewardUnavailable` (`inventory_exhausted` / `conflict`); the server read's
273
+ `PLAYER_NOT_FOUND` and `INVALID_PLAYER_EMAIL` use the existing `isPlayerNotFound` and
274
+ `isInvalidPlayerEmail`. Additive only. README section "Loyalty and rewards".
275
+
276
+ ## 3.19.0
277
+
278
+ ### Minor Changes
279
+
280
+ - 6940139: D-PRICE-012: a subscription card refund, and a lost chargeback not covered by the chargeback guarantee, now cost the partner the whole refunded amount, INVO's card fee included, exactly as a Platform Commerce card refund does. There is no separate payment processor fee on a refund any more: `processingFeeUsd` reads `"0.00"` and `processingFeeBasis` `"none"`.
281
+
282
+ Additive, optional fields:
283
+
284
+ - `RefundResult.cardFeeChargedToPartnerUsd` and `RefundResult.partnerDebitedUsd` on `subscriptions.refund` (the 200 receipt and the 202 `pending_approval` body). `undefined` on a receipt stored before this release.
285
+ - `card_fee_charged_to_partner_usd` and `partner_debited_usd` on the `refund` block of `subscription.refunded` (`SubscriptionRefundDetail`) and on `purchase.disputed` (`PurchaseEventData`, subscription and Platform Commerce losses; `null` where not applicable).
286
+
287
+ README: subscription refund costs, lost chargebacks and the "What did I earn?" answer updated.
288
+
289
+ ## 3.18.0
290
+
291
+ ### Minor Changes
292
+
293
+ - 432fb75: INVO's 2026-09 card pricing. On card purchases the partner now pays INVO's card fee (4.5% + $0.30 on Open, 5.5% + $0.50 on Merchant of Record, plus 1.5% of the listed price (before tax) on a card issued outside the US); the player pays the listed price (plus tax where owed) and receives the listed coins. Fraud screening and a chargeback guarantee (a fraud chargeback on a card sale is covered by INVO) are included. Minimum card purchase $2.99 on coin purchases and Platform Commerce card sales, enforced from 2026-10-27. Card purchases only; purchases through a third-party storefront or payment rail are unaffected. All additive:
294
+
295
+ - `PurchaseResult` and `CurrencyPurchaseQuote` gain `partnerFeeUsd`, `internationalCardFeeUsd` and `minPurchaseWarning` (`MinPurchaseWarning`: `{ code, minUsd, enforcedFrom, message?, enforced?, raw }`), each set only when INVO sends it. `processingFeeUsd` stays and reads `"0.00"`.
296
+ - `FeeTakenFrom` gains `"partner"`. `UnacknowledgedPurchaseOutcome.feeTakenFrom` stays required; INVO always sends it, and should it ever be missing the SDK reads `"partner"` when the quote carries `partner_fee_usd`, otherwise `"coins"` as before.
297
+ - `err.minUsd` and `err.enforcedFrom` on `BELOW_CARD_MINIMUM` (`err.isBelowCardMinimum`, which now also covers INVO's minimum card purchase). `err.isAmountBelowFee` is deprecated: `AMOUNT_BELOW_FEE` is no longer returned.
298
+ - `acknowledgedTotalUsd` is still honored: INVO never charges more than it, and an older, higher fee-inclusive total is accepted with the true, lower total charged. Only a total below the true total is refused (`QUOTE_STALE`).
299
+ - `partnerFeeUsd` and `internationalCardFeeUsd` are `string | null`: `null` only when the fee could not be booked when the purchase completed (the purchase succeeded; INVO books the fee shortly after). `internationalCardFeeUsd` is `"0.00"` on a US card or one whose country is unknown, and always `null` on a quote (no card yet). The quote also carries `feeTakenFrom`, and `ifUnacknowledged.partnerFeeUsd`.
300
+ - `createCheckout()` and the Platform Commerce card leg of `platformCommerce.purchase()` return `minPurchaseWarning` while an amount under the minimum card purchase is still accepted. `BELOW_CARD_MINIMUM` also answers a card charge under the $0.50 card floor at any date, on coin purchases, hosted checkout and Platform Commerce: `err.minUsd` reads `"0.50"` there, with no `err.enforcedFrom`.
301
+ - `purchaseCurrency()` accepts `country` and `subdivision`, the place you quoted with. On Merchant of Record INVO uses it only when it cannot read the buyer's tax location from the card; without it such a purchase is refused with `409 TAX_PLACE_UNAVAILABLE` (new `err.isTaxPlaceUnavailable`, `err.untaxedTotalUsd`), nothing charged.
302
+ - Platform Commerce card refunds: `cardFeeChargedToPartnerUsd` and `partnerDebitedUsd` on the refund result and `card_fee_charged_to_partner_usd` / `partner_debited_usd` on `platform_commerce.refunded` (the card fee is not returned on a refund; it stays charged to you).
303
+ - Webhook types: `purchase.completed` gains `partner_fee_usd` and `international_card_fee_usd` (nullable); `purchase.disputed` gains `guarantee_covered` (lost Platform Commerce card sale and subscription disputes only; never on a coin purchase dispute), `order_type`, `developer_revenue_reversed_usd`, `subscription_id`, `period_seq` and `processing_fee_usd` (the processor fee a non-fraud lost subscription chargeback charges you, as a refund does); `platform_commerce.purchased` gains `international_card_fee_usd` (already included in `fee_breakdown.platform_fee`); `subscription.renewed`'s split gains `international_card_fee_usd` (the same figure as `pass_through_fees_usd`, never add them; `partner_revenue_usd` stays gross).
304
+ - Behaviour to notice: an unacknowledged $10.00 coin purchase now credits the full 100.00 coins (93.70 under the earlier pricing); an older fee-inclusive acknowledged total is accepted and the lower true total charged; `AMOUNT_BELOW_FEE` is no longer returned.
305
+ - README and doc comments: every card fee figure, the Tiers table (card rates, international fee, who pays, fraud screening, chargeback guarantee, minimum card purchase) and the quote example ($10.00 charges the player $10.00; your fee is $0.75 on Open).
306
+
307
+ ## 3.17.0
308
+
309
+ ### Minor Changes
310
+
311
+ - 28a96bf: Webhook payload types: `PurchaseEventData` gains `payment_intent_id` / `charge_id` / `dispute_id` (`string | null`: `null` on a Steam chargeback), `rail`, `steam_transid`, `fully_refunded`, `currency_debited` and `new_balance`. Steam chargebacks now arrive as `purchase.disputed` with the same keys as a lost card dispute, and a Steam partial refund arrives as `purchase.refunded` with `fully_refunded: false`. README: if you revoke on `purchase.refunded`, handle `purchase.disputed` the same way. All additive and optional.
312
+
313
+ ## 3.16.1
314
+
315
+ ### Patch Changes
316
+
317
+ - 9dd2bf5: README: the `isDuplicateClientRequestId` note describes only what the caller sees. Documentation only.
318
+
319
+ ## 3.16.0
320
+
321
+ ### Minor Changes
322
+
323
+ - 58143c2: `warnings` on `createCheckout()` results (typed `CheckoutWarning[]`, mapped from the additive `warnings` field): a checkout session sells game currency, and `metadata` carrying `item_id` / `item_name` now returns `ITEM_METADATA_ON_CURRENCY_SESSION`, pointing to `platformCommerce.purchase` for item sales. New error helpers: `err.isDuplicateClientRequestId` (409 `DUPLICATE_CLIENT_REQUEST_ID` on a Platform Commerce card purchase, with `order_id` / `order_status`; `err.isDuplicateRequest` is also true), `err.isTrialAmountBelowFeeFloor` (400 `TRIAL_AMOUNT_BELOW_FEE_FLOOR`; the message names the smallest accepted trial price) and `err.isIdentityCheckUnavailable` (503 `IDENTITY_CHECK_UNAVAILABLE` on claims and confirm-receipt, retryable). `err.isAmountBelowMinimum` now also covers `purchaseItem`, whose `totalPrice` is rounded to cents. README: refunds take back only the coins still held from that purchase, chargebacks up to the purchase's coins from the available balance, never below zero. All additive and optional.
324
+
325
+ ## 3.15.0
326
+
327
+ ### Minor Changes
328
+
329
+ - 5adf010: `cards.createSetupSession()` takes optional `playerName` and `playerPhone` (mapped to `player_name` / `player_phone`). When the member is new to the game and `playerName` is sent, INVO creates the member exactly as `subscriptions.create` does and then mints the card link, so a brand-new signup can save a card before a paid trial (`subscriptions.create` with `trialAmountUsd` and `playerCardId`). Without `playerName` an unknown member is still `err.isPlayerNotFound` (404). A known member is never re-created or renamed by this call. New `err.isPlayerCreateFailed` (503 `PLAYER_CREATE_FAILED`); a phone already on another member answers `err.isPhoneShareApprovalRequired` (409). The SDK refuses a blank or over-255-character `playerName` and a non-E.164 `playerPhone` before the network (`INVALID_INPUT`, status 0). README: the card page and paid-trial sections show the new-signup order. All additive and optional.
330
+
331
+ ## 3.14.2
332
+
333
+ ### Patch Changes
334
+
335
+ - README: the Merchant of Record chargeback threshold is measured on the previous complete calendar month. Documentation only.
336
+
337
+ ## 3.14.1
338
+
339
+ ### Patch Changes
340
+
341
+ - README: Merchant of Record is applied for from the Selling & Tax page in the INVO console (the page name was wrong in 3.14.0). Documentation only.
342
+
343
+ ## 3.14.0
344
+
345
+ ### Minor Changes
346
+
347
+ - 8f2298b: `credited` and `reasonCode` on `confirmPayment()` and `steamFinalizePurchase()` results (mapped from the additive `credited` / `reason_code` response fields; `status` is unchanged and still means the payment succeeded, so report a completed purchase only when `credited` is `true`). Merchant of Record receipt fields `receiptNumber` / `receiptUrl` on `purchaseCurrency()`, `getOrderDetails()`, `CheckoutClient.getPurchaseStatus()`, `platformCommerce.getStatus()` and `firstCharge`, and `receipt_number` / `receipt_url` (plus `tax_treatment` on `purchase.completed`) on the purchase, Platform Commerce and subscription webhook payload types. README: the tier's effect on responses (`tax_treatment: "partner_responsible"` on Open, receipts and the chargeback reserve on Merchant of Record). Platform Commerce card refunds in parts: optional `refundRemaining` / `confirmAdditionalRefund` on `platformCommerce.refund()`, optional `partialRefund` / `adopted` / `refundedTotalUsd` / `chargeTotalUsd` / `remainingUsd` on its result, and `err.isRefundRemainingRequiresConfirmation` / `err.isRefundRecentlyIssued` / `err.isRefundNotCompleted` (`err.isAlreadyRefunded` is now false for the two refund-in-parts refusals). All additive and optional. README: subscription card charges are 4% + $0.30 on Open and 5% + $0.50 on Merchant of Record (were 7% + $0.30 and 8.5% + $0.30); international card and currency conversion costs on subscriptions pass through at cost; chargebacks by tier; Merchant of Record is applied for from the console.
348
+
349
+ ## 3.13.0
350
+
351
+ ### Minor Changes
352
+
353
+ - INVO's card fee on coin purchases, paid trials, and the two tiers.
354
+
355
+ **Coin purchases carry INVO's card fee: 3.5% + $0.30** of the price (on the Open tier), never less than the card cost. `purchaseCurrency` charges in the same request, so there are now two shapes and you pick one by what you send:
356
+
357
+ - **Quote, show, acknowledge.** New `server.quoteCurrencyPurchase({ playerEmail, usdAmount, country?, subdivision? })` calls `POST /api/currency-purchases/quote`. It moves no money and creates nothing, and returns `totalUsd`, `amountCents`, `subtotalUsd`, `processingFeeUsd`, `coins`, `currencyName`, a camelCase `breakdown` and `ifUnacknowledged`. Show the player `totalUsd`, then pass it as the new optional `acknowledgedTotalUsd` on `purchaseCurrency`: the card is charged that total, to the cent, and the coins are priced off `usdAmount`. $10.00 quotes $10.65.
358
+ - **Send only `usdAmount`.** The card is charged exactly `usdAmount`, never more, and the fee comes out of the coins: $10.00 credits 93.70 coins at the default 10 per USD.
359
+
360
+ A `success` result now also carries `processingFeeUsd`, `feeTakenFrom` (`"charge"` or `"coins"`), `coinsCredited` and `chargeTotalUsd`. New error helpers: `err.isQuoteStale` (409 `QUOTE_STALE`, with `err.expectedTotalUsd` and `err.acknowledgedTotalUsd`) and `err.isAmountBelowFee` (400 `AMOUNT_BELOW_FEE`). Nothing is charged on either. `acknowledgedTotalUsd` is shape-checked locally (a positive two-decimal amount) with a ceiling above the largest price, because the fee rides above INVO's card maximum.
361
+
362
+ **Refunds of coin purchases:** only unspent coins are refundable; spent coins are never refunded. Documented; no SDK call refunds a coin purchase.
363
+
364
+ **Paid trials on card subscriptions.** `subscriptions.create` accepts `trialAmountUsd` (with `trialDays` or `trialEnd`, card only, at least 0.50 and less than `amountUsd`): period 1 is charged the trial price inside the call and `amountUsd` from period 2. The consent object accepts `disclosedTrialAmountUsd`, `disclosedTrialDays` and `disclosedTrialEnd`, and returns `disclosed_trial_amount_usd`, `disclosed_trial_days` and `disclosed_trial_end`. The subscription gains `trialAmountUsd` and, on create and finalize bodies, `trialAmountCoinsEstimate`. Webhook types: `is_trial` on `subscription.renewed`; `is_trial` and `trial_amount_usd` on the trial period's `payment_failed`, `past_due`, `authentication_required` and `expired` (new `SubscriptionTrialEventFields`); `expire_cause` (`"trial_payment_failed"`) on `subscription.expired`. New error helpers: `isPaymentMethodRequired`, `isTrialAmountInvalid`, `isTrialAmountRequiresTrial`, `isTrialAmountNotSupportedForFunding`, `isConsentDisclosedTrialInvalid`. The SDK refuses, before the network and with INVO's own codes, a `trialAmountUsd` without a trial, with `walletOnly: true`, or on `steamInit`; the $0.50 floor and the "less than `amountUsd`" rule are left to INVO.
365
+
366
+ **README:** a new Tiers section (Open by default: you are the seller and handle tax; Merchant of Record by application: INVO is the seller and handles tax; fees per tier), the coin fee flow, the refund rule and paid trials. Every statement that INVO is the merchant of record on the card rail for everyone is removed.
367
+
368
+ All additive: no export was removed, renamed or retyped, and every new field on an existing type is optional.
369
+
370
+ ## 3.12.1
371
+
372
+ ### Patch Changes
373
+
374
+ - Docs: subscription packages.
375
+
376
+ The README's Subscriptions section gains a **Subscription packages** part. A package (the API calls it a plan) is what a developer sells: a name, a price, a billing interval and the `item_id` the game checks. Packages are created, edited, closed and reopened in the INVO dashboard with the developer's own sign-in, never with the game secret or a player token, so this SDK does not wrap them and has no `packages` or `plans` namespace. That is deliberate.
377
+
378
+ Nothing about an integration changes. `server.subscriptions.create(...)` and `steamInit(...)` still subscribe a member to an `itemId`, webhooks carry the same payloads, and entitlement still comes from `subscription.renewed`. A package's subscriber counts and monthly revenue are measured per title and `item_id`, so a new package immediately shows the members already subscribed to its item. The section also covers the two counts (`subscriber_count` on basis `active`, `live_subscriber_count` on basis `live`), who a price change applies to, and that closing a package cancels nobody. Full guide: https://docs.invo.network/docs/subscriptions-packages/
379
+
380
+ Doc correction: the subscription refund daily limit. The README and the `subscriptions.refund` JSDoc said a game's daily self-serve refund limit is $500 by default. It no longer is: by default the limit is never lower than the largest single subscription charge (`25000.00` USD today), so any single period can always be refunded on its own, and if INVO raises the per-charge maximum the limit rises with it. INVO can still set a specific limit for one game, which applies as set, even if lower. Everything else about refunds is unchanged: reaching the limit exactly still runs, going over it answers HTTP 202 `pending_approval`, and approved requests do not count toward the day. The sandbox recipe now says how to see a 202 (ask INVO for a low limit on the sandbox game).
381
+
382
+ Documentation only. No export was added, removed, renamed or retyped.
383
+
384
+ ## 3.12.0
385
+
386
+ ### Minor Changes
387
+
388
+ - The card maximum is INVO's, not the SDK's.
389
+
390
+ **INVO raised the maximum single card charge from $999.99 to $100,000.00 on 2026-09-18, and this package was refusing it.** The old limit was enforced client-side and threw before any network call, so a partner charging $50,000 failed inside the SDK and INVO never saw the request. The backend raise was invisible to every SDK user until this release. Per-customer velocity limits rose with it, to 100,000 per hour, 200,000 per day and 1,000,000 per month, all enforced by INVO.
391
+
392
+ **The design decision: the floor is a fact, the ceiling is a policy, and only facts belong in a client.**
393
+
394
+ $0.50 is the card rail's own minimum charge. Below it nothing settles in any environment, INVO holds it as a plain constant rather than a setting, and no configuration makes a smaller amount chargeable. That check stays exactly where it was and still throws before any request (`BELOW_STRIPE_MINIMUM`, `err.isBelowCardMinimum`).
395
+
396
+ The maximum is the opposite. It is a runtime setting an INVO admin edits without a deploy, and it differs between sandbox and production. Any number pinned in a published package is stale the moment somebody changes it, and the only remedy is a release, which is precisely the failure this release is repairing. So the local ceiling is **removed** rather than re-pinned at $100,000.00. It was not replaced by a fetch of the live limits either: that would turn one purchase call into two network calls, add a failure mode and a cache to a money path, and still be a snapshot rather than the truth at the moment of charge, because only the request itself is evaluated against the setting in force.
397
+
398
+ What remains is a structural bound. `usdAmount` and a card `totalPrice` must still be a positive amount with at most two decimals, and must still be at most `999999.99`, the same house ceiling every other money field in this SDK uses. That figure is deliberately **above** the largest value INVO's setting is permitted to take, so it can never refuse an amount INVO would have accepted. The invariant for anyone editing this later: the local bound must never be tighter than the server's maximum possible limit. This SDK may cost you a wasted round trip. It must never cost you a sale that a package upgrade would have allowed.
399
+
400
+ **What changed for you**
401
+
402
+ - Amounts between `999.99` and `999999.99` are now sent instead of being rejected locally. Nothing that worked before stops working; the validation only loosened.
403
+ - `err.isAboveCardMaximum` is unchanged and still means what it always meant, but it now arrives only from INVO (a `400`), never from the SDK. Nothing was charged.
404
+ - An amount above `999999.99` now throws `INVALID_INPUT` where it previously threw `ABOVE_CARD_MAXIMUM`. That range is malformed input, not a policy refusal, and INVO classifies it the same way.
405
+
406
+ **When INVO refuses an amount the SDK allowed**, catch `err.isAboveCardMaximum`. `err.message` carries the figure that was in force for that request, for example "Card purchases must be $100,000.00 or less." Do not retry it unchanged: lower the amount, split the sale, or ask INVO to raise the setting. The live figure for a tenant is also the `max_amount` of the hosted checkout's `validate-game` read, next to `min_amount`; read that if you want to show a limit in your own UI, and re-read it, because it can change under you. A velocity limit is a `429` with `err.retryAfter`, not this error.
407
+
408
+ **README: the minimum is $0.50.** The docs said only `0 < x <= 999.99` and left the floor unstated. They now state $0.50, which is what INVO advertises and what the card rail actually enforces. A $1.00 minimum was advertised by INVO's own checkout read until 2026-09-18 and was enforced nowhere; it is gone rather than enforced, because enforcing it would newly refuse charges between $0.50 and $0.99 that settle today.
409
+
410
+ No export was added, removed, renamed or retyped.
411
+
412
+ ## 3.11.0
413
+
414
+ ### Minor Changes
415
+
416
+ - The purchase status read, and the subscription fee is 7%.
417
+
418
+ **A buyer can always be told what happened to the money they paid.** `invo.checkout` (and the standalone `CheckoutClient`, for a page with no player token) reads `GET /api/checkout/sessions/<id>`, authenticated by the SESSION token; the id in the path is a label, not a credential. `getPurchaseStatus({ sessionId, sessionToken })` reads once; `waitForPurchase({ ..., intervalMs, timeoutMs, maxAttempts, signal, onUpdate })` polls until INVO says it is finished and returns that result. Six statuses, four of them terminal, plus `orderId`, `coinsCredited` / `transactionId` / `newBalance` on a credit, `reasonCode` + a player-safe `message` on a refusal, and both money figures (`amountChargedUsd`, `listedUsd`) so a buyer billed 206.29 for a 200 pack can be shown where the 6.29 went.
419
+
420
+ `terminal` is read off the response and is NEVER recomputed from `status`, so a status a later backend introduces cannot make this build decide a purchase finished, or finished well. A status it does not recognise is not terminal and is never a success. `paid_pending_credit` is deliberately not terminal at any age: INVO's reconciler recovers a stalled credit. A failed poll is not a failed purchase: network, timeout, 429 and 5xx are polled through; 401, 403 and 410 are raised at once (`isWrongSessionPurpose`, `isCheckoutSessionMismatch`, `isCheckoutSessionExpired`). On the cap `waitForPurchase` returns the last result it read rather than throwing, so the page keeps showing something true.
421
+
422
+ `CheckoutPurchaseStatus` is a widened union (`… | (string & {})`), not a literal one, and a tsc test pins that partner code storing or comparing an unknown status still compiles, which is the fix 3.10.0 had to make to `RefundResult` after the fact. It is named `Checkout…` because `PurchaseStatus` is already the direct `purchaseCurrency` result and is unchanged. New: `CheckoutClient`, `InvoClient.checkout`, `isPurchaseCredited` / `isPurchaseRefused` / `isPurchaseRefunded` / `isPurchaseExpired`, `nothingWasCharged` (true only where INVO said no money was taken; everything else, an unknown code included, happened after the card was charged, so never put a Try again on it), and the types `PurchaseStatusResult`, `PurchaseStatusInput`, `WaitForPurchaseInput`, `PurchaseRefusalReason`, `PurchaseCredited` / `PurchaseRefused` / `PurchaseRefunded` / `PurchaseExpired`, `CheckoutClientConfig`.
423
+
424
+ `createCheckout()` now also returns `sessionToken`, read from INVO's `session_token` field (backend commit `856fa266`) and falling back to the `checkout_url` query string only for a server that predates it, so nothing has to parse a URL to use the read. The two cannot disagree, and if a response ever carried both and they differed the field wins, because a query-key spelling is not a contract.
425
+
426
+ **Doc fix: INVO's subscription fee is 7% plus $0.30, not 10%** ($9.99 pays INVO $1.00 and you $8.99). Subscriptions became their own rate on 2026-09-17; item purchases stay at 10/90. No code change.
427
+
428
+ **Not included: withdrawals.** INVO's withdrawal request and history reads gained additive `kyc_hold`, `kyc_hold_reason` and `next_steps` fields on 2026-09-17. This package exposes no withdrawal surface at all, so there is nowhere for them to go, and adding one is a separate decision rather than part of a documentation pass.
429
+
430
+ **Fixed: the User-Agent version had drifted.** `SDK_VERSION` was left at `3.10.0` when 3.10.1 published, so every server call from 3.10.1 reported a version that was not the one running, and the test pinning it to `package.json` was failing on `main`. Back in step, and the pin is green.
431
+
432
+ ## 3.10.1
433
+
434
+ ### Patch Changes
435
+
436
+ - `linkDevice()` takes no arguments. The server mints the link id, so requiring one was wrong: callers had to invent a placeholder. The parameter stays optional and any value passed is still sent and ignored by the server, so code written against 3.10 keeps working unchanged. The README now also states that a tenant whose players enrol a passkey on the tenant's own domain MUST offer `linkDevice()`, because that credential can only be asserted on that tenant's origin, and that recovery is never the answer to `ENROLLMENT_REQUIRES_PROOF`.
437
+
438
+ ## 3.10.0
439
+
440
+ ### Minor Changes
441
+
442
+ - f66103c: Card-only subscriptions and subscription refund guardrails (INVO backend, 2026-09-17). Everything here is additive: no field, type or behaviour of an existing call was removed or renamed.
443
+
444
+ **Card-only subscriptions (behaviour change on INVO's side, no type changes).** A card subscription's card is now charged the full price every period; the member's coin wallet never pays for it and never moves. Steam subscriptions are unchanged (wallet first, Steam tops up the shortfall).
445
+
446
+ - `subscription.renewed` on the card rail: `funding.balance_applied_coins` is always `"0.00"`, `funding.card_charged_usd` is the price, `mint_order_id` is never `null`.
447
+ - Every paid card renewal also emits `purchase.completed` with `data.metadata.source === "subscription_renewal"`. Do not grant currency from it; `subscription.renewed` is the entitlement signal.
448
+ - A member with no saved card fails with `failure_code: "no_payment_method"` whatever their balance. New additive `failure_code`: `wallet_negative`.
449
+ - `walletOnly` is marked `@deprecated` (still accepted and returned): a wallet-only card subscription can never be paid (`failure_code: "wallet_only"`).
450
+ - `subscription.authentication_required`: `card_amount_usd` now equals `amount_due_usd` on card challenges.
451
+ - Doc fix: the `amountUsd` JSDoc now states the per-charge ceiling of `25000.00` (it still said `500.00`), and `SubscriptionExpiredData` no longer says `steam_containment` is sent.
452
+
453
+ **Subscription refund guardrails.**
454
+
455
+ - `subscriptions.refund` can now return a refund request. `RefundResult` stays a single interface (its `status` is typed `"refunded" | "pending_approval" | (string & {})`, so any string still assigns and compares); branch with the new `isRefundPendingApproval(r)` type guard, which narrows to `RefundPendingApproval`. `"pending_approval"` is the new HTTP 202: the refund would exceed the game's daily self-serve limit ($500 by default), nothing moved, and INVO reviews it as a refund request (`requestId`, `requestStatus`, `requestedAmountUsd`, `requestedAt`, `dailyCapUsd`, `executedTodayUsd`, `message`). Both carry every receipt field; the `request*` fields are optional on `RefundResult` and required on `RefundPendingApproval`. The status string is passed through from INVO unchanged.
456
+ - New optional result fields: `warnings` (`REASON_RECOMMENDED`, `REASON_TRUNCATED`), `subscriptionCanceled`, `subscriptionStatus`, `processingFeeUsd`, `processingFeeBasis`, `processingFeeBorneBy`, `processingFeeTransactionId`, `partnerTotalReversedUsd`, `initiation`, `refundRequestId`. `undefined` on receipts stored before the change.
457
+ - `reason` is documented as recommended now and required after a notice period. Refunds run within 30 days of the charge. A full refund cancels the subscription. Card-only periods are refunded in cash, partial included. The partner bears the card processor fee. INVO emails the member.
458
+ - New `InvoError` classifiers: `isRefundsNotEnabled` (403), `isRefundWindowClosed` (409), `isRefundRequestPending` (409), `isRefundRequestRejected` (409), `isConcurrentRequest` (409), `isRefundMismatch` (502), with body accessors `refundRequestId`, `decisionReason`, `periodChargedAt`, `refundWindowDays`, `refundWindowClosedAt`.
459
+ - New webhook types: `subscription.refund_requested`, `subscription.refund_approved`, `subscription.refund_rejected` (`SubscriptionRefundRequestData`, `SubscriptionRefundApprovedData`, `SubscriptionRefundRejectedData`). Additive fields on `subscription.refunded` (`refund.processing_fee_*`, `refund.partner_total_reversed_usd`, `initiation`, `refund_request_id`, `subscription_canceled`) and `subscription.canceled` (`cancel_cause: "full_refund"`).
460
+ - New exports: `isRefundPendingApproval`; types `RefundReceipt`, `RefundPendingApproval` (both extend `RefundResult`), `RefundWarning`, `RefundInitiation`, `RefundProcessingFeeBasis`.
461
+
462
+ **Compatibility.** Additive only. Code that compares `status` to any string, builds `RefundResult` mocks with a `string` status, or `extends`/`implements` `RefundResult` keeps compiling (pinned by a tsc test). `subscription.refunded`, `subscription.refund_approved` and, on a full refund, `subscription.canceled` are sent together and may arrive in any order.
463
+
464
+ README: the Subscriptions section states card-only funding, the renewal `purchase.completed` trap, the refund limits and the 202, the new events and classifiers, and "what did I earn" now subtracts `partner_total_reversed_usd`.
465
+
466
+ ## 3.9.0
467
+
468
+ ### Minor Changes
469
+
470
+ - The INVO-hosted card page is the recommended way to save a card for a subscription.
471
+
472
+ New on `invo.cards`:
473
+
474
+ - **`createSetupSession({ playerEmail, successUrl?, cancelUrl?, metadata? })`** ->
475
+ `{ sessionId, cardSetupUrl, expiresAt, raw }` (`POST /api/checkout/card-setup-sessions`,
476
+ game secret header). Mint a 10-minute link server-side, send the member to `cardSetupUrl`
477
+ (top-level, never framed), and read the saved card's `id` back from `cards.list`; it appears
478
+ there immediately, carries the off-session consent a subscription needs, and no event fires
479
+ for it. No browser code, no client secret, no card processor named anywhere, so INVO can change
480
+ processor without partners changing anything. Never auto-retried: each call mints a fresh link.
481
+ Script-scheme `successUrl` / `cancelUrl` values are refused before the network (`INVALID_INPUT`,
482
+ status 0), matching INVO's own rule.
483
+ - `beginSetup` / `confirmSetup` are now documented as the **processor-bound alternative**: they
484
+ hand back a `clientSecret` only the current processor's client library can consume, so a card
485
+ form built on them needs rework when INVO changes processor.
486
+
487
+ New error classifiers: `isPlayerNotFound` (404 `PLAYER_NOT_FOUND`: the card page never creates
488
+ players), `isInvalidPlayerEmail` (400 `INVALID_PLAYER_EMAIL`), `isInvalidInput` (`INVALID_INPUT`,
489
+ at status 0 from the SDK's own guards or 400 from INVO for a script-scheme URL).
490
+
491
+ Fixed: `subscriptions.get(id, { includePlayer: true })` never populated `player`. INVO puts
492
+ `player_email` / `player_name` on the subscription object itself, not in a separate block; they
493
+ are now surfaced as `subscription.playerEmail` / `subscription.playerName`, and `player` is
494
+ derived from them.
495
+
496
+ README: a "Cards for subscriptions" section a partner can follow start to finish (mint, send,
497
+ read the card back, subscribe, what each error means, the 10-minute session, no browser code).
498
+
499
+ README corrections that ride along in this release: `subscription.expired` no longer carries
500
+ `failure_code: "steam_containment"` (a balance is spendable in any title whatever rail bought
501
+ it, so the "wallet value that cannot be spent in this game" deferral is gone from the deferrals
502
+ paragraph and the event table); the Steam transfer-policy note now says it is a rule about
503
+ currency moving between titles, not about spending (an item purchase never fails on origin);
504
+ and "game" reads "title" in a few places so a platform tenant is not misled by the word.
505
+ Line endings: a `.gitattributes` (`* text=auto eol=lf`) keeps the packed README, CHANGELOG and
506
+ package.json LF on every checkout (3.9.0's first build packed CRLF from a Windows checkout).
507
+
508
+ ## 3.8.1
509
+
510
+ ### Patch Changes
511
+
512
+ - Subscription docs: the per-charge ceiling is 25000.00, not 500.00, and it is
513
+ per CHARGE rather than per month. An annual plan bills the whole year in one
514
+ go, so a $500 a month plan sold as a 12-month plan is a single $6,000 charge
515
+ and is chargeable. The old number quietly refused every annual plan above
516
+ $41.66 a month.
517
+
518
+ ## 3.8.0
519
+
520
+ ### Minor Changes
521
+
522
+ - Subscriptions are a first-class server surface, on both rails, with the card capture and the
523
+ sandbox clock tools beside them.
524
+
525
+ New on `InvoServer`:
526
+
527
+ - **`invo.subscriptions`**: `create` (card rail; charges the first period before answering,
528
+ idempotent on `clientRequestId`, a repeat is a typed `idempotentReplay: true` result),
529
+ `get`, `listForPlayer`, `cancel` (an already-terminal row is a 200 `alreadyCanceled`, never
530
+ thrown), `changeAmount` (staged for the next renewal), `setPaymentMethod`, `refund`
531
+ (idempotent; the receipt replays), `steamInit` and `steamFinalize` (Steam rail;
532
+ `alreadyProcessed` is a result, not an error).
533
+ - **`invo.cards`**: `beginSetup` / `confirmSetup` / `list`: the off-session card capture a
534
+ card subscription needs. The hosted checkout does not save a card for subscriptions.
535
+ - **`invo.sandbox.subscriptions`**: `advanceClock` / `forceRenewal` / `forceFailure` /
536
+ `forceAuthChallenge`. These post to `/subscriptions/<id>/...` **relative to the sandbox
537
+ base URL, not under `/api`**, and send `X-Sandbox-Clock-Key` from the new
538
+ `sandboxClockKey` config; a missing key throws before the network.
539
+
540
+ Typed results: `SubscriptionResult` (the subscription object with its TWO clocks,
541
+ `firstCharge` with `paidPeriodSeq`, `card`, `idempotentReplay`), `FirstCharge` (`paid` |
542
+ `requires_action` | `skipped_trial` | `failed` | `pending` | `pending_authorization`),
543
+ `SteamInitResult` (`steamOrderId` for the client callback, `amountCoins`, `pendingReuse`),
544
+ `CancelResult`, `ChangeAmountResult`, `RefundResult`, `CardSetupResult`, `SandboxClockResult`
545
+ (`engineStats`), and typed `data` for all seven `subscription.*` webhook events.
546
+
547
+ Error classifiers: `isActiveSubscriptionExists` (+ `existingSubscriptionId`),
548
+ `isIdempotentReplayMismatch` (+ `mismatchedFields`), `isSteamReauthorizationRequired`,
549
+ `isNotACardSubscription`, `isSteamChannelRequired`, `isSubscriptionTerminal`,
550
+ `isNotAuthorized`, `isSandboxClockUnauthorized`, `isSteamRefundNotSupported`, `isFlowPaused`,
551
+ `isGameNotLive`; `isSteamAuthorizationPending` now also covers the subscription 409.
552
+
553
+ Also: the server `User-Agent` version now derives from the package version (it had read
554
+ `3.0.0` since 3.0.0), pinned by a test.
555
+
556
+ ## 3.7.0
557
+
558
+ ### Minor Changes
559
+
560
+ - Device approval grant (RFC 8628) is now a first-class server surface — including **the
561
+ step that moves the money**.
562
+
563
+ An integrator followed the README, polled a grant to `approved`, and stopped. Nothing
564
+ moved: an approved grant is a _factor_, and the transaction sat at
565
+ `pending_pin_verification` until it expired and was refunded. The README's section ended
566
+ at the poll and neither package had a method for the step after it. Both halves of that
567
+ are fixed here.
568
+
569
+ New on `InvoServer` (all authenticate with the **player token** — on a console the game
570
+ server holds the token it minted, and the game secret is never sent):
571
+
572
+ - `beginDeviceApproval({ playerToken, transactionId, flow, channel? })` → the RFC 8628
573
+ §3.2 grant (`deviceCode`, `userCode`, `verificationUriComplete`, `expiresIn`,
574
+ `interval`, `channel`). `channel: "popup"` is refused before the network — it is
575
+ browser-only (`InvoClient.approveHosted`).
576
+ - `pollDeviceApproval({ playerToken, deviceCode })` → a typed outcome
577
+ (`authorization_pending` / `slow_down` / `approved` / `access_denied` /
578
+ `expired_token`), plus the `enrollment` object while a first-time phone waits on the
579
+ game screen. `invalid_grant` throws.
580
+ - `confirmDeviceEnrollment({ playerToken, deviceCode, decision })` → answers the
581
+ on-screen match-code prompt (`"approve"` | `"deny"`).
582
+ - **`approveWithDeviceCode({ playerToken, transactionId, flow, deviceCode })` — the money
583
+ step.** Routes by flow: `send` → `/api/sdk/send/{id}/approve`, `transfer` →
584
+ `/api/sdk/transfers/{id}/approve`, `send_receipt` →
585
+ `/api/sdk/send/{id}/confirm-receipt`, `transfer_receipt` →
586
+ `/api/sdk/transfers/{id}/confirm-receipt`. Never auto-retried.
587
+ - `completeDeviceApproval(...)` — convenience loop: polls honouring `interval` and
588
+ `slow_down`, surfaces the enrollment prompt, then calls `approveWithDeviceCode`.
589
+
590
+ **`TRANSACTION_NOT_PENDING` is a result, not a throw.** `approveWithDeviceCode` returns
591
+ `{ status: "not_pending", alreadySettled, currentStatus }` so "your earlier attempt
592
+ already landed" is distinguishable from a real refusal **without string-matching** — the
593
+ difference between "the guard worked" and "her currency is stuck". Every other refusal
594
+ stays a typed thrown `InvoError`.
595
+
596
+ `alreadySettled` is **flow-aware and fails closed**. The four endpoints gate on different
597
+ status sets — the sender approves accept `pending_pin_verification` /
598
+ `pending_verification`, the two receipt endpoints accept `pending_claim` / `verified` — so
599
+ a receipt settle landing on `pending_pin_verification` means the SENDER has not approved
600
+ yet (possibly held at a guardian 202). That is _before_ the step, not past it, and calling
601
+ it settled would tell a game to hand over goods for value never credited. It is an
602
+ allow-list per flow rather than a "not expired/failed" deny-list, so a status INVO adds
603
+ later answers `alreadySettled: false` with `currentStatus` set — go read the transaction —
604
+ instead of defaulting to "the money moved" in already-deployed copies of this SDK.
605
+
606
+ Older backend bodies that carried only the message ("Transaction not pending…", "…cannot
607
+ be confirmed…") with no machine code are matched too, but narrowly: HTTP 400, one of those
608
+ two phrases, **and** a readable `(current status: …)` / `(status: …)` clause. "cannot be
609
+ confirmed" is ordinary English, so a phrase match alone can never assert that money moved.
610
+
611
+ New `InvoError` predicates: `isTransactionNotPending`, `currentTransactionStatus`,
612
+ `isDeviceApprovalNotApproved`, `isDeviceApprovalAlreadyPending`,
613
+ `deviceApprovalExpiresAt`, `isSettleFault`, `errorRef`. The RFC 8628 §3.5 tokens are
614
+ promoted onto `err.code`.
615
+
616
+ Two safety fixes in `completeDeviceApproval`: `transactionId` is validated **before** the
617
+ loop (an empty id used to poll for minutes, let the player approve, and only then throw —
618
+ an approved grant with nothing settled), and the `respond` callable handed to
619
+ `onEnrollment` now resolves quietly for every "the prompt is moot" refusal
620
+ (`expired_token`, `invalid_grant`, and the two enrollment 409s) instead of rejecting. A
621
+ prompt on a TV routinely outlives its ten-minute grant, callers fire `respond` without
622
+ awaiting it, and an unhandled rejection exits a Node process.
623
+
624
+ README: the console section is rewritten around begin → show the QR → poll → **call
625
+ `approveWithDeviceCode`** → webhooks, with the supersede-vs-409 begin semantics corrected
626
+ and "consumed when used" replaced by _when_ the code is spent. A new top-level **Sends and
627
+ transfers, stage by stage** section covers both flows and both sides with a
628
+ call-order table, an error table, and a common-mistakes box led by "polling to `approved`
629
+ and stopping". The error tables now also carry the receipt-flow-only refusals a console
630
+ recipient meets (`receiver_not_enrolled_use_claim_code`, `not_intended_receiver`, the
631
+ phone-share 409, `RECIPIENT_IDENTITY_PENDING` / `_DECLINED`) and a warning that a settle
632
+ FAILURE is ambiguous about the money — INVO commits and then reads the transaction back to
633
+ build its 200, so a `*_FAILED` or a timeout can both describe money that already moved:
634
+ read the transaction status before telling the player it failed, and never auto-start a
635
+ replacement. SMS is now confined to a clearly-labelled legacy-fallback subsection.
636
+
637
+ ## 3.6.0
638
+
639
+ ### Minor Changes
640
+
641
+ - New: `InvoClient.approveHosted({ transactionId, flow })` — web games approve on INVO's
642
+ hosted identity page. The browser is the RFC 8628 client: with the player token it already
643
+ holds, the SDK calls `POST /api/sdk/approvals/device/begin` with `channel: "popup"` (INVO
644
+ records the page's `Origin` as the popup's opener), opens the hosted page in a popup
645
+ (synchronously, inside your click handler), polls `poll` honouring `interval` and
646
+ `slow_down` (+5 s), drives the INVO-branded match-code prompt from the poll's `enrollment`
647
+ object ("Set up INVO on iPhone? Code 48-27. Say Yes only if the phone you just
648
+ scanned/opened shows this code." → `confirm-enrollment`; `confirmed` shows "Finishing on
649
+ iPhone… / Stop it, wrong code"; a 409 already-decided takes it down quietly), and when the
650
+ poll says `approved` calls the flow's approve endpoint with the `device_code` —
651
+ `transfers/{id}/approve`, `send/{id}/approve`, `send/{id}/confirm-receipt`,
652
+ `transfers/{id}/confirm-receipt`. Resolves `{ status: "approved", approval }` (the same
653
+ `ApproveResult` / `ConfirmReceiptResult` the in-app calls return) or `denied` / `expired` /
654
+ `closed` / `blocked` / `redirected`; rejects with `InvoError` when the backend refuses.
655
+ `device_code` lives in the call's closure only — never on the result, never logged. The
656
+ page's `postMessage` is a wake-up that triggers an immediate poll (accepted only from the
657
+ hosted page's https origin and only from the popup the SDK opened), never a result. A
658
+ popup blocked by the browser resolves `blocked` before anything is started (default);
659
+ `popupBlocked: "redirect"` opts in to a full-tab redirect. A page sending
660
+ `Cross-Origin-Opener-Policy: same-origin` is detected and reported as `blocked` with a
661
+ hint. Your server does nothing new; its `device_approval.approved` webhook still fires.
662
+ In-app partner-domain passkeys are unchanged and remain supported. `onEnrollment(e,
663
+ respond)` + `renderPrompt:false` let a game draw its own prompt.
664
+
665
+ Docs: new "Web games — approving on INVO's hosted page" section; the console-flow poll
666
+ example now shows `match_code`. Test-only devDependency added: `happy-dom`.
667
+
668
+ Docs (hosted identity pages, Phase 7): the console section documents `channel` on
669
+ `begin` (`qr` default | `popup` — the browser must call `begin` itself, its https `Origin`
670
+ becomes the popup's opener, server-to-server callers are refused | `app_browser` — the
671
+ mobile plugins; the return scheme `invo-sdk-<game_id>` is derived server-side), the echoed
672
+ `channel` on the begin body, `recovery` on the poll's `enrollment` object, the hosted
673
+ passkey-recovery flow (screen confirm + emailed single-use link → old INVO passkeys
674
+ deactivated, `identity.passkey_reset` webhook, 24-hour `PASSKEY_RECOVERY_COOLDOWN` on
675
+ money out; receiving unaffected), the mobile auto-confirm note (`app_browser` enrolment is
676
+ confirmed by INVO, no prompt), and `ENROLLMENT_REQUIRES_PROOF` on the page. Sends &
677
+ transfers: guardian approval now goes by email first (`consent_channel` and
678
+ `resend_endpoint` on the raw 202 `guardian_approval` block; `decision_source: "email_link"`),
679
+ the once-per-approval `POST /api/sdk/approvals/guardian/{approvalId}/resend` `{channel:"sms"}`
680
+ contract (initiator's token; 403/409/410/503 codes), and phone-share / recipient-identity
681
+ consents on the same hosted page (unchanged 409 / 202 codes, `consent_channel` on the
682
+ phone-share body). Passkeys: the partner-domain freeze — new titles have nothing to verify
683
+ (`409 PARTNER_RP_FROZEN`; `WEBAUTHN_NOT_ENABLED_FOR_TENANT` is the expected state, use
684
+ `approveHosted`), tenants with a domain verified before the freeze keep it, removal is
685
+ irreversible. The "SMS first, then email" fallback sentence corrected to "email first, SMS
686
+ on request". Documentation only.
687
+
688
+ ### Patch Changes
689
+
690
+ - Docs: the device-approval page (RFC 8628, consoles / TVs / native Steam and desktop
691
+ clients) now enrols the player's INVO passkey on the **first** scan, and the proof is the
692
+ game screen: the phone says "confirm on your game screen", the game shows "Set up INVO on
693
+ this phone: iPhone?", the player presses Yes on the console, and the phone's biometric
694
+ creates the passkey and approves — no code to type, no SMS; every later scan is scan,
695
+ biometric, done. The "the player needs an INVO passkey" bullet is replaced accordingly.
696
+ Documents the two integrator-facing additions: the `enrollment` object
697
+ (`state` / `device_label` / `requested_at`) on the `authorization_pending` poll body while
698
+ a phone is waiting, and `POST /api/sdk/approvals/device/confirm-enrollment`
699
+ (`{device_code, decision: "approve" | "deny"}`, same auth as begin/poll; deny ends the
700
+ grant with `access_denied`), plus the backup email. Also documents two backend
701
+ behaviours: `begin` extends the transaction's own approval window past the code's expiry
702
+ (`transfer` / `send`), and `begin` may be called again for the same transaction once an
703
+ approved code's window has passed. Documentation only — no code or type changes; the
704
+ `begin`/`poll` endpoints, the `device_approval.approved` webhook and its `method` value
705
+ are unchanged.
706
+
707
+ Also on the send side: the claim SMS now carries a link to a hosted INVO claim page where
708
+ a recipient without the game collects with one email + an emailed code + their phone's
709
+ passkey (in-game claim unchanged; `transfer.received` fires the same); documents the
710
+ sender-token REST call `POST /api/sdk/send/{transactionId}/resend-claim` (30-second
711
+ cooldown, 10 per transaction per hour — no SDK method); and that an uncollected send is
712
+ still refunded at 24 hours but the sender is now emailed and the recipient texted, with
713
+ `transfer.claim_expired` / `transfer.refunded` as the source of truth. The `transfer.*`
714
+ rows were added to the event-types table.
715
+
716
+ - df2efe9: Docs: add an explicit per-platform verification/approval recommendation. The
717
+ "gold standard" section now spells out which method fits which client — a passkey
718
+ directly on mobile app/web and desktop web, and the QR device-approval flow
719
+ (RFC 8628) on consoles **and** on native Steam / desktop game clients (Mac &
720
+ Windows), where it is the embedded game client, not the OS, that can't invoke the
721
+ platform authenticator. Also documents the SMS-first-then-email fallback for
722
+ remote approvals with no passkey path. Documentation only — no code or type
723
+ changes; the `VerificationMethod` union and the device-approval REST flow are
724
+ unchanged.
725
+
726
+ All notable changes to `@invonetwork/web-sdk` are documented here. This project follows
727
+ [Semantic Versioning](https://semver.org/). Releases are managed with
728
+ [changesets](https://github.com/changesets/changesets).
729
+
730
+ ## [3.5.0] - 2026-09-01
731
+
732
+ **The Steam purchase flow is now first-class SDK surface: `steamPacks()`, `steamInitPurchase()`, `steamFinalizePurchase()`** — plus browser-based checkout for platforms where the Steam overlay does not render, a finalize-poller error taxonomy, and webhook `channel` typing. No breaking changes.
733
+
734
+ Until now the SDK only _steered away_ from Steam (`purchaseCurrency` fails fast on `rail: "steam"`); the dedicated endpoints had to be called by hand. All three are typed methods now, and the fail-fast message names them.
735
+
736
+ ### Added
737
+
738
+ - **`InvoServer.steamPacks(query?)`** — the pack catalogue. `currencyAmount` is per-player (VAT and the storefront's revenue share come out of the sticker before currency is derived — a $4.99 pack yields 34, not 50, units at $1 = 10). Render it verbatim; never compute currency from price and never cache one answer for all players.
739
+ - **`InvoServer.steamInitPurchase(input)`** — start the purchase. Idempotent on `purchaseReference` (retries, including manual retries after a 409, MUST reuse it). New authorization modes:
740
+ - `usersession: "client"` (default, unchanged): Steam overlay in-game. The SDK sends **no** `usersession` key at all in this mode, pinned by test, so existing behaviour cannot shift.
741
+ - `usersession: "web"`: for platforms where the overlay does not render (observed: Electron on macOS). Requires `playerIp` — the PLAYER's address, never your server's; refused client-side before the network without it. Returns `steamCheckoutUrl`: Steam's own hosted approval page, which must open as a **top-level tab** (it cannot be iframed). _Note: Steam's sandbox issues checkout URLs its production host will not serve, so web-session approval is provable only against production; the rest of the flow is identical to client-session._
742
+ - `metadata` — echoed on the `purchase.completed` webhook (`data.metadata`) — the way to correlate your own player/order ids. The Steam rail merges its own context keys (`steam_wallet_currency`, `steam_country`, `steam_account_status`, `vat_rate_pct`) into the echoed object; avoid those names in yours.
743
+ - **`InvoServer.steamFinalizePurchase({orderId})`** — capture + credit. Idempotent: a replay returns `alreadyProcessed: true` and never credits twice.
744
+ - **Finalize poller taxonomy on `InvoError`** — because _not every 409 means "not yet"_, and a poller that assumes so polls a dead order forever:
745
+ - `isSteamAuthorizationPending` — player has not approved yet (Steam reports `Init`). The normal wait state; poll again.
746
+ - `isSteamAuthorizationDead` — any settled status — `Cancelled`, `Failed`, `Refunded`, `Chargedback`, and every other non-Init outcome (pending is the CLOSED set: only `Init` means "not yet"). Stop; no later call can succeed.
747
+ - The two are mutually exclusive by construction, and a test pins that they can never both answer true.
748
+ - **`InvoError.isPartnerCreditUnavailable`** (`PARTNER_CREDIT_UNAVAILABLE`, 409) — the studio's settlement float cannot cover the purchase. Structure is fine; the money is not. Plain failure toast; do **not** hot-poll init (each attempt briefly re-reserves headroom), and reuse the same `purchaseReference` on manual retry.
749
+ - **`InvoError.isPartnerRailSuspended`** (`PARTNER_RAIL_SUSPENDED`, 409) — terminal from the game's seat. The umbrella `isPartnerSettlementUnavailable` still covers both.
750
+ - **`InvoError.isUnknownSteamPack`** (400) — re-fetch `steamPacks()`; the body's `valid_pack_ids` lists what exists.
751
+ - **`InvoError.isMissingPlayerIp`** (400) — always an integration bug on web sessions.
752
+ - **`PurchaseCompletedData.channel`** — which storefront the purchase came from (`"steam"` / `"ios"` / `"android"` / `"web"` / `"console"`), beside `rail`. `null` means a legacy game key: a real answer ("unattributed"), read it as one.
753
+
754
+ ### Changed
755
+
756
+ - `purchaseCurrency`'s `rail: "steam"` fail-fast message now names the real methods instead of vaguely citing "dedicated endpoints".
757
+
758
+ ## [3.4.0] - 2026-09-01
759
+
760
+ **A Steam title now bills through its OWN Steam application.** New error helpers;
761
+ no breaking changes to any existing method or type.
762
+
763
+ ### Why this is a real change and not a doc tidy
764
+
765
+ Steam pays whoever owns the Steam application. Until now, INVO documented a
766
+ single INVO-owned Steam app that billed every title on the network — so a studio
767
+ had nothing to register and the money reached them through INVO. That model is
768
+ gone. Each title sells through the studio's own Steam app, the money lands in
769
+ their own Steamworks account, and INVO issues the player's currency immediately
770
+ and settles with the studio afterwards against a payment method on file.
771
+
772
+ If you shipped against 3.3.0 or earlier and your Steam integration works today,
773
+ nothing in your code needs to change. What changes is the **studio's** one-time
774
+ setup, and the errors you may now see if they have not done it.
775
+
776
+ ### Added
777
+
778
+ - `InvoError.isSteamNotConfigured` — the title has no Steam application
779
+ registered with INVO yet (`STEAM_NOT_CONFIGURED`, 503).
780
+ - `InvoError.isPartnerBillingNotSetUp` — the studio has not finished INVO billing
781
+ setup (`PARTNER_BILLING_NOT_SET_UP`, 409).
782
+ - `InvoError.isPartnerSettlementUnavailable` — settlement suspended or over
783
+ limit (`PARTNER_RAIL_SUSPENDED` / `PARTNER_CREDIT_UNAVAILABLE`, 409). Show a
784
+ neutral "purchases are unavailable right now": it is not the player's problem.
785
+ - `InvoError.isSteamAppChanged` — the order was started against a different
786
+ Steam application than the title is configured for now (`STEAM_APP_CHANGED`,
787
+ 409). Only reachable if a studio swaps apps mid-flight.
788
+
789
+ All four are refused **before the player is charged**, which is the point.
790
+
791
+ ### Changed
792
+
793
+ - README: the Steam section now documents the studio's Steamworks setup
794
+ (microtransactions enabled, a publisher-GROUP Web API key that includes the
795
+ app, appid + key entered in the INVO dashboard, payment method on file).
796
+ - README: removed the claim that no Steam-side registration was required.
797
+
798
+ ## [3.3.0] - 2026-08-31
799
+
800
+ **Documentation only. No code changes, no API changes.**
801
+
802
+ Documents **Device Approval** — passkey step-up for consoles, TVs and any device
803
+ with no browser. It is the OAuth 2.0 Device Authorization Grant
804
+ ([RFC 8628](https://datatracker.ietf.org/doc/html/rfc8628)), so a standard
805
+ client library understands the responses.
806
+
807
+ - The device shows a short code and a QR (`verification_uri_complete`); the
808
+ player approves on their phone; your **server** polls
809
+ `POST /api/sdk/approvals/device/poll` until it hears back.
810
+ - **One approval authorises one transaction.** Unlike the plain RFC 8628 grant,
811
+ which authorises a _client_, an INVO device code is bound to the transaction
812
+ you named and is consumed when used — it cannot approve anything else and
813
+ cannot be reused.
814
+ - `user_code` is meant to be seen; `device_code` is not. Poll from your backend.
815
+ - Subscribe to `device_approval.approved` to learn the moment an approval lands
816
+ instead of waiting for the next poll. Polling still works alone.
817
+ - Available to every title with nothing to configure — the constraint is a
818
+ property of the _device_, not the game, so a title with a website and a
819
+ console build uses the normal ceremony in the browser and this one on console.
820
+ - Currency purchases on a console go through that console's store, as the
821
+ platform holder requires; this flow is for approving transfers and sends.
822
+
823
+ Minor rather than patch because it documents a new API surface. The snippets are
824
+ pinned by a test against this file, for the same reason the Steam ones are: a
825
+ REST flow with no SDK method behind it is the one thing no other test can see.
826
+
827
+ ## [3.2.3] - 2026-08-28
828
+
829
+ **Documentation only. No code changes, no API changes.** Corrects two errors in
830
+ the 3.2.2 Steam snippets that made them fail if copied.
831
+
832
+ - **Base path.** The snippets said `/api/enhanced-purchase/...`. The routes are
833
+ mounted at **`/api/currency-purchases/...`** -- `enhanced_purchase_api` is the
834
+ module name, not the mount point. Copying 3.2.2 returned `404 Resource not
835
+ found`, which reads like the Steam rail is unavailable rather than like a
836
+ wrong URL.
837
+ - **Auth header.** The snippets sent `X-Game-Secret`. The header is
838
+ **`X-Game-Secret-Key`**, as it is everywhere else in this document. An unknown
839
+ header is ignored, so the request arrived unauthenticated.
840
+
841
+ Both were confined to the Steam section added in 3.2.2; every other snippet was
842
+ correct. The Steam flow itself is unchanged -- pack catalogue, `pack_id`,
843
+ VAT-aware amounts, all exactly as 3.2.2 describes.
844
+
845
+ The paths and header are now pinned by a test against this file, because the
846
+ Steam section is the one snippet with no SDK method behind it and so was the one
847
+ thing no test could see.
848
+
849
+ ## [3.2.2] - 2026-08-28
850
+
851
+ **Documentation only. No code changes, no API changes.**
852
+
853
+ Steam currency purchases now work on a **pack model**, and this documents it. The
854
+ 3.2.1 notes described an earlier design that has been replaced -- read this
855
+ instead.
856
+
857
+ - **INVO owns the Steam pack catalogue.** You do not set prices and you never
858
+ send an amount. Fetch `GET /steam/packs?steamid=...`, render it, and pass a
859
+ `pack_id` to `/steam/init-purchase`. An amount is refused with
860
+ `400 UNKNOWN_STEAM_PACK`.
861
+ - **The price is identical everywhere; the currency inside is not.** Steam prices
862
+ are VAT-inclusive wherever VAT is collected, so more of a fixed price goes to
863
+ tax in a high-VAT country -- the same $9.99 pack yields 69 units in the US and
864
+ 58 in France.
865
+ - **Always pass `steamid`** when fetching the catalogue. Without it amounts are
866
+ quoted with no VAT deducted, so a store promises more than the purchase
867
+ delivers. Do not cache one catalogue for all players.
868
+ - A Steam-distributed title may only sell currency on the `steam` rail
869
+ (`409 STEAM_PURCHASE_LAYER_REQUIRED`), and a locked Steam account is refused up
870
+ front (`409 STEAM_ACCOUNT_LOCKED`).
871
+
872
+ Steam remains a server-to-server REST flow rather than an SDK method, because the
873
+ purchase is authorised inside the Steam client and your game relays that.
874
+
875
+ ## [3.2.1] - 2026-08-28
876
+
877
+ **Documentation only. No code changes, no API changes.**
878
+
879
+ Documents two things about the Steam rail that the SDK does not change but every
880
+ Steam integration has to handle:
881
+
882
+ - **Currency for a Steam-distributed title must be bought on the `steam` rail.**
883
+ Any other rail is refused with `409 STEAM_PURCHASE_LAYER_REQUIRED`. This is a
884
+ platform requirement and it applies across every storefront the title ships on,
885
+ because a player's balance is shared between them.
886
+ - **The player is charged more than the value you request.** Steam's platform
887
+ commission is priced into the charge rather than absorbed, so the Steam
888
+ init-purchase response now carries `charged_usd` alongside `value_usd`. Show
889
+ `charged_usd` in your store. The currency the player receives is unchanged, so a
890
+ pack is worth the same in-game on every rail, and the rate is configuration --
891
+ read the response rather than hard-coding a multiplier.
892
+
893
+ ## [3.2.0] — 2026-08-24
894
+
895
+ **Storefront keys.** A game that ships on more than one storefront now gets one SDK
896
+ key per storefront -- `steam`, `ios`, `android`, `web`, `console` -- all valid at the
897
+ same time, and the key determines the payment rail. Construct one client per key and
898
+ use whichever matches where the player is buying. **Additive: no behavior changes, no
899
+ API removals.** A single existing key keeps working exactly as it does today, `rail`
900
+ included, with no deadline and no migration.
901
+
902
+ Three new typed error predicates for refusals this SDK previously surfaced only as a
903
+ raw `code` string:
904
+
905
+ - `InvoError.isRailChannelMismatch` -- the `rail` you sent disagrees with the storefront key
906
+ you authenticated with (400). The fix is to stop sending `rail`; the key already
907
+ determines it. INVO refuses rather than silently overriding, because overriding
908
+ would bill a player through a route you did not ask for.
909
+ - `InvoError.isSteamRailNotEntitled` -- a Steam purchase was attempted for a title INVO has
910
+ not registered as distributed on Steam (403). Holding a `steam` storefront key does
911
+ not by itself register the title.
912
+ - `InvoError.isSteamPurchaseLayerRequired` -- a title distributed on Steam tried to sell currency
913
+ on a non-Steam rail (409). Use the dedicated Steam purchase flow.
914
+
915
+ Also in this release: the 3-D Secure completion method's documentation no longer names
916
+ a payment processor. INVO does not name processors in developer-facing surfaces, and
917
+ this line had been an exception to that for some time.
918
+
919
+ Also in 3.2.0: **provider-neutral error codes.** INVO stamps a neutral alias
920
+ (`error_code_public`) beside any machine code that carries a payment
921
+ processor's name. This SDK previously read only the raw code, so a partner
922
+ branching on `err.code` had to hard-code a vendor name INVO's own public
923
+ documentation is not allowed to print. `err.code` is now the neutral alias when
924
+ one exists (`STRIPE_ERROR` becomes `PROCESSOR_ERROR`), and the literal wire value stays reachable on
925
+ `err.rawCode` for anyone already matching it. Refund reads prefer
926
+ `processor_refund_reference` over the vendor-named field, with a fallback.
927
+
928
+ **Storefront keys are still server-side keys.** A storefront key names where the
929
+ _purchase_ came from, not where the key lives. It belongs in your backend exactly like
930
+ your original key -- never in a game client, an app bundle, or browser code.
931
+
932
+ ## [3.1.0] — 2026-08-04
933
+
934
+ **Passkeys are the gold standard; the SMS-PIN path is deprecated.** This release makes INVO's
935
+ authentication guidance explicit in the two places developers actually look — the README and IDE
936
+ autocomplete. **No behavior changes, no API removals, no runtime warnings.** Upgrading and
937
+ changing nothing produces byte-identical runtime behavior.
938
+
939
+ A passkey is a phishing-resistant, origin-bound WebAuthn assertion. An SMS PIN is a shared secret
940
+ on a channel exposed to SIM swap and interception. They were documented as interchangeable
941
+ verification options; they are not, and the docs said so in a way that produced PIN-first
942
+ integrations.
943
+
944
+ ### Added — error-contract classifiers
945
+
946
+ Three 403s that previously arrived as a generic `InvoError` (correct `status`/`code`/`message`,
947
+ but no typed branch) now have classifiers:
948
+
949
+ - **`err.isSourceGameNotLive`** — the caller's OWN game is in testing. Self-serve: switch it to
950
+ Live in the console (Game Settings → Status).
951
+ - **`err.isTargetGameNotLive`** — the DESTINATION game is in testing. Usually another
952
+ developer's game, so the caller **cannot** fix it. **Deliberately distinct** from the source
953
+ case: collapsing them into one "not live" branch yields a "go fix it" CTA that dead-ends half
954
+ the time.
955
+ - **`err.gameStatus`** — the `game_status` field from either refusal (e.g. `"testing"`).
956
+ - **`err.isWebauthnNotEnabledForTenant`** — tenant has no verified WebAuthn RP ID. **This is
957
+ configuration state, not a failure**: fall back to the SMS/in-app path instead of surfacing an
958
+ error. Currently the common case — 4/23 sandbox and **0/3 production** tenants are configured.
959
+
960
+ Note the backend splits field names across these: the `*_GAME_NOT_LIVE` pair uses
961
+ `error_code`/`message`, while `WEBAUTHN_NOT_ENABLED_FOR_TENANT` uses `code`/`error`. The SDK
962
+ already read both, so `err.code` is populated either way — the new tests pin both shapes.
963
+
964
+ ### Clarified — the SDK does not, and did not, collapse non-2xx into transport errors
965
+
966
+ Following a report of a `403` being debugged as a network outage: verified end-to-end that a
967
+ non-2xx always surfaces with its real `status`, `code`, and `message`, and that `status: 0` is
968
+ reserved for a genuine absence of an HTTP response. **No fix was needed in the SDK** — the loss
969
+ happened in an integration-layer catch-all. Added regression tests pinning the behavior, plus a
970
+ README section (**"`.status === 0` means 'no HTTP response' — and nothing else"**) showing the
971
+ anti-pattern and the correct handler, and a note that `409` is a retryable not-ready state
972
+ rather than a failure.
973
+
974
+ ### Deprecated
975
+
976
+ - **`InvoServer.verifySmsTransfer` / `InvoServer.verifySmsSend`** — marked `@deprecated`. They
977
+ still work exactly as before and still hit the same endpoints. A **future major version will
978
+ remove them**; no date is committed yet. Keep them only as a genuine last resort for users who
979
+ cannot enroll a passkey (unsupported device, no platform authenticator) or who decline.
980
+ **Migration:** when `initiateSend`/`initiateTransfer` returns `verificationMethod: "sms"`, read
981
+ it as _"this sender has no passkey"_ — prompt `InvoClient.enrollPasskey()` and then
982
+ `InvoClient.approveSend` / `approveTransfer`, instead of routing to a PIN pad.
983
+
984
+ ### Changed (documentation only)
985
+
986
+ - New README section — **"Passkeys are the gold standard — don't build on SMS"** — with the
987
+ do/don't table, the deprecation notice, and an explicit list of the OTP surfaces that are
988
+ **not** discouraged.
989
+ - `VerificationMethod`, `InitiateResult.verificationMethod` and `SmsVerifyResult` doc comments
990
+ reframed: `"in_app"` and `"sms"` are no longer presented as peer options.
991
+ - "Before you go live" now stresses configuring RP ID / origins _before_ launch, since an
992
+ unconfigured tenant silently drops every sender onto the deprecated path.
993
+ - **New "Prerequisite: passkeys are dark until your tenant verifies a domain" subsection.**
994
+ Recommending passkeys without saying what unlocks them would send developers straight into a
995
+ `403` on their first `enrollPasskey()` call — with 0/3 prod tenants configured, that is
996
+ currently _everyone_. The deprecation carries no removal date for the same reason.
997
+ - Stability section corrected — it still claimed `2.0.0` was the only major, which `3.0.0`
998
+ made false.
999
+ - Design doc: `docs/features/passkey-first-authentication.md`.
1000
+
1001
+ ### Not affected — still recommended
1002
+
1003
+ `enrollmentBegin`/`enrollmentVerify`, `recoveryBegin`/`recoveryComplete`, and
1004
+ `phoneShareInitiate`/`phoneShareApprove` all involve a one-time code but are the on-ramp _to_ a
1005
+ passkey (or phone-ownership consent), not a substitute for one. They are **not** deprecated.
1006
+
1007
+ ### Upgrade note
1008
+
1009
+ The only way this release can surface in a pipeline is a lint rule that treats `@deprecated`
1010
+ usage as an error (e.g. `deprecation/deprecation` with `--max-warnings 0`). That is a lint-level
1011
+ signal, not a build or runtime break, and it is the intended notice.
1012
+
1013
+ ## [3.0.0] — 2026-07-20
1014
+
1015
+ **BREAKING — the Platform Commerce card leg moved to INVO's hosted checkout.** The backend now
1016
+ hosts the entire card flow (card fields, Apple Pay / Google Pay, billing-address collection,
1017
+ 3-D Secure) on its own checkout page, so the browser card-element surface shipped in 2.5.x is
1018
+ gone. Card sales are simpler AND safer: server creates → buyer pays on `checkoutUrl` → fulfill
1019
+ on the `platform_commerce.purchased` webhook. Note: the card leg is pending final enablement on
1020
+ the backend (sandbox payment test) — the balance leg is fully live.
1021
+
1022
+ ### Migration from 2.5.x (card leg only — balance/status/refund/webhooks unchanged)
1023
+
1024
+ - `platformCommerce.purchase({ fundingSource: "card" })`: **remove `billingAddress`** (the type
1025
+ is gone; the hosted page collects it) and optionally pass `successUrl` / `cancelUrl` /
1026
+ `metadata`. The result now carries `checkoutUrl` / `sessionId` / `expiresAt` (unix seconds) /
1027
+ `idempotentReplay` — **`clientSecret` no longer exists.**
1028
+ - Browser: **`confirmCardPayment` and `mountCardPayment` are removed** (with all card-element
1029
+ types and the `commercePublishableKey` config). Replace with a redirect
1030
+ (`location.href = checkoutUrl`) or the new optional embed:
1031
+ `invo.platformCommerce.mountCheckout(el, checkoutUrl, { onComplete })` — an iframe plus an
1032
+ origin-checked listener for the page's `INVO_CHECKOUT_COMPLETE` message.
1033
+ - Card duplicates no longer 409: retrying `purchase` with the same `clientRequestId` **replays
1034
+ the same checkout session** (`idempotentReplay: true`), so a lost response is recoverable.
1035
+
1036
+ ### Added
1037
+
1038
+ - `PlatformPurchaseInput.successUrl/cancelUrl/metadata`; result fields
1039
+ `sessionId/checkoutUrl/expiresAt/idempotentReplay`.
1040
+ - `InvoClient.platformCommerce.mountCheckout(el, checkoutUrl, opts)` → `{ iframe, destroy() }`.
1041
+ - `err.isAboveCardMaximum` (`ABOVE_CARD_MAXIMUM`, card > $999.99) + client-side card USD
1042
+ bounds fail-fast ($0.50–$999.99).
1043
+ - Card `requires_payment` responses without a `checkout_url` fail closed (`INVALID_RESPONSE`).
1044
+
1045
+ ### Removed
1046
+
1047
+ - `confirmCardPayment`, `mountCardPayment`, `commercePublishableKey`, `BillingAddress`, and the
1048
+ card-element/processor types + the runtime CDN script loader (no more processor touchpoints
1049
+ in this SDK at all).
1050
+
1051
+ ## [2.5.1] — 2026-07-20
1052
+
1053
+ Hardening patch from a second, independent post-release audit (correctness vs the backend
1054
+ blueprint + security red-team) of the 2.5.0 Platform Commerce feature. No API breaks.
1055
+
1056
+ ### Fixed
1057
+
1058
+ - **Card-confirm script loader could hang forever on retry.** After a transient CDN failure
1059
+ (or a pre-existing processor `<script>` tag whose events already fired), the next
1060
+ `mountCardPayment`/`confirmCardPayment` attached listeners to a dead tag and never settled —
1061
+ checkout silently dead until page reload. The loader now removes failed tags and polls
1062
+ (bounded, 10s) when a tag pre-exists.
1063
+ - **Orphaned card element on submit-lookup failure.** `confirmCardPayment` now destroys the
1064
+ mounted Payment Element before rethrowing when the `submit` selector can't be resolved
1065
+ (previously a retry stacked a second live card iframe).
1066
+ - **Billing-address validation errors no longer echo the submitted values** (cardholder PII
1067
+ could otherwise land in logs/Sentry); optional billing fields (`name`/`line2`/`state`) are
1068
+ now type-checked.
1069
+ - **`playerPhone` on `platformCommerce.purchase` is now E.164-validated** — this endpoint can
1070
+ create the player identity, so a national-format phone must never reach the wire.
1071
+ - **`err.isInsufficientBalance` now also classifies the zero-balance 400** ("Player has no
1072
+ balance in this tenant", which carries only `current_balance`).
1073
+ - **Breaker-open 503 keeps its human message** (`err.code === "service_unavailable"`, message
1074
+ no longer collapses to the bare token).
1075
+ - **Webhook types:** `platform_commerce.refunded` `player_email` is nullable + `identity_id`
1076
+ added; (2.5.0 already made card-leg `total_price` optional on `purchased`).
1077
+ - **Refund result surfaces `newBalance`** (balance leg) **and `processorRefundId`** (card leg)
1078
+ instead of leaving them `raw`-only.
1079
+ - Platform-commerce error tests now assert the REAL backend envelopes
1080
+ (`{status,error_code,message}` / bare `{message}`), not idealized shapes.
1081
+
1082
+ ### Docs
1083
+
1084
+ - Card-leg lost-response caveat on `purchase` (duplicate 409 can strand a `clientSecret`-less
1085
+ pending order — reconcile via webhook/`getStatus`, retry with a NEW `clientRequestId`).
1086
+ - `confirmCardPayment`: bank-redirect return-leg guidance + remount-after-decline note;
1087
+ `CardPaymentResult.raw` log-redaction note.
1088
+
1089
+ ## [2.5.0] — 2026-07-20
1090
+
1091
+ **Platform Commerce (ecommerce).** A new flow for **platform** tenants (non-game apps: vertical
1092
+ video, creator merch, marketplace) to sell items funded by **INVO balance or a real card**, with
1093
+ INVO as merchant of record and full refunds. This is **distinct from item purchase** — that is a
1094
+ _game_ tenant spending a player's _existing game currency_ on an _in-game_ item (balance only, no
1095
+ card, no refund). Additive; only platform tenants can call it (a game tenant gets `403
1096
+ NOT_A_PLATFORM_TENANT`). (Backend handoff: BE-PIP-009 `PLATFORM_COMMERCE_SDK.md`.)
1097
+
1098
+ - **Server** (`InvoServer.platformCommerce`, mirrored in the Python SDK as
1099
+ `server.platform_commerce`):
1100
+ - `purchase(input)` — `fundingSource: "balance"` settles synchronously (`status:"success"`);
1101
+ `"card"` returns `status:"requires_payment"` + a `clientSecret` and **requires a
1102
+ `billingAddress`**. Idempotent on `clientRequestId`.
1103
+ - `getStatus(orderId)` — `completed` | `pending_payment` | `refunded`.
1104
+ - `refund({ orderId | clientRequestId, reason? })` — INVO retains its fee; a second refund
1105
+ throws `409` (`err.isAlreadyRefunded`).
1106
+ - **Browser** (`InvoClient.platformCommerce`):
1107
+ - `confirmCardPayment(clientSecret, { mount, publishableKey?, returnUrl?, submit? })` — mounts
1108
+ the card element and confirms; returns `{ status: "succeeded" | "requires_action" |
1109
+ "processing" | "failed" }`. The processor JS is **lazy-loaded from its CDN — no bundled
1110
+ dependency**; pass its publishable key (or set `commercePublishableKey` on the client config).
1111
+ - `mountCardPayment(clientSecret, opts)` — the primitive: `{ element, confirm(), destroy() }`
1112
+ to confirm from your own Pay button.
1113
+ - **Webhooks:** new typed `platform_commerce.purchased` / `platform_commerce.refunded` events.
1114
+ **Fulfill card orders on `platform_commerce.purchased`, never on the browser confirmation.**
1115
+ - **New `InvoError` classifiers:** `isNotPlatformTenant` (403), `isAmountBelowMinimum`,
1116
+ `isBelowCardMinimum` (card < $0.50), `isAlreadyRefunded` (409).
1117
+ - Docs: README now leads the flow list with an explicit **item purchase vs Platform Commerce**
1118
+ contrast; new "Platform Commerce (ecommerce)" section.
1119
+
1120
+ ## [2.4.1] — 2026-07-10
1121
+
1122
+ Docs only, no code change — corrects stale README prose that the 2.4.0 publish still carried:
1123
+ the status line led with an old version, and the Stability section still cited the `2.0.0`
1124
+ `playerPhone` requirement as the standing breaking change (2.2.0 relaxed it back to optional).
1125
+ Republished so the package-bundled README is accurate.
1126
+
1127
+ ## [2.4.0] — 2026-07-10
1128
+
1129
+ **Steam transfer policy.** Steam-purchased currency is locked to Steam titles; the backend now
1130
+ enforces this at transfer/send initiate and annotates destinations. Additive, and inert until a
1131
+ title is flagged Steam-distributed. (Design doc: `docs/features/steam-transfer-policy.md`.)
1132
+
1133
+ - New `InvoError` classifiers on `initiateSend`/`initiateTransfer` 409s:
1134
+ `isSteamValueNonTransferable` (with `steamTransferableMax` / `steamOriginAmount` — decimal
1135
+ strings) and `isNonSteamValueIntoSteamBlocked`. Surface `err.message` verbatim.
1136
+ - New `DestinationGame.acceptsSteamOriginValue` (maps `accepts_steam_origin_value`; `false` when
1137
+ omitted) — disable non-Steam destinations for a player holding Steam value so they never hit
1138
+ the 409.
1139
+
1140
+ No breaking changes.
1141
+
1142
+ ## [2.3.0] — 2026-07-07
1143
+
1144
+ **Claim-time phone-share approval.** The backend closed a security gap: claiming/collecting a
1145
+ phone-routed transfer now authorizes the collecting identity against the receiver phone before
1146
+ crediting. So `confirmReceiptSend`/`confirmReceiptTransfer` and `claimTransfer`/`claimCurrency`
1147
+ can now return the phone-share `409 PHONE_SHARE_APPROVAL_REQUIRED` (previously only
1148
+ registration/mint did). The existing `InvoError.isPhoneShareApprovalRequired` already classifies
1149
+ it — no consumer code must change — but:
1150
+
1151
+ - New **`InvoError.phoneShareLast4`** surfaces the `phone_last4` from the 409 body for the UI
1152
+ ("we texted the phone ending 1234").
1153
+ - `isPhoneShareApprovalRequired` docs + the `confirmReceipt*`/claim method docs + README now
1154
+ spell out the claim-time path: it's **not a failure** — the funds are held and the phone owner
1155
+ is texted; show `err.message` verbatim, then **retry the same call** once approved (it succeeds
1156
+ idempotently); on denial/expiry the sender is refunded.
1157
+
1158
+ Additive, no breaking changes; affects all rails' claim paths (transfer, currency send, amazon).
1159
+
1160
+ ## [2.2.0] — 2026-07-07
1161
+
1162
+ **Backend reconciliation** — a full audit of the SDK against the live backend surfaced three
1163
+ places the SDK didn't match reality. All changes are backward-compatible (relaxing required
1164
+ inputs / adding surface); no working call breaks.
1165
+
1166
+ - **`mintPlayerToken` no longer requires `playerPhone`.** `/api/sdk/player-token` is a
1167
+ session-token mint for an **existing** player (looked up by email) — not a registration call.
1168
+ It reads only `player_email` and ignores `player_phone`. The 2.0.0 hard E.164 requirement was
1169
+ a bug: it could **block a valid token mint for an existing email-only player**. `playerPhone`
1170
+ is now optional and validated only if provided. Phone stays enforced where it matters — the
1171
+ sender's phone on `initiateSend`/`initiateTransfer`, and at player creation.
1172
+ - **Send by phone alone.** `receiverPlayerEmail` (send) and `targetPlayerEmail` (transfer) are
1173
+ now **optional** — you can send to a recipient's phone; they supply their email at claim
1174
+ (claim still requires it, since that's where the recipient establishes identity).
1175
+ - **`getPlayerBalance` is by email only.** There is no by-`playerId` balance route on the
1176
+ backend, so passing `playerId` threw a confusing 404. It now throws a clear `INVALID_INPUT`
1177
+ pointing you to `InvoClient.getBalance()` (client-side) or `playerEmail` (server-side).
1178
+ - **New `InvoError.isUserVerificationRequired`** for the `WEBAUTHN_UV_REQUIRED` (401) approve
1179
+ failure — re-run the passkey ceremony requiring UV.
1180
+ - Fixed `iterateItemPurchaseHistory` to read the backend's `total_count` pagination key (was
1181
+ `total`; the loop already terminated via the short-page guard, so behavior is unchanged).
1182
+
1183
+ **Migration:** none required. If you were passing `playerPhone` to `mintPlayerToken` it still
1184
+ works; you can now also omit it. Replace any `getPlayerBalance({ playerId })` with an email
1185
+ lookup or `InvoClient.getBalance()`.
1186
+
1187
+ ## [2.1.2] — 2026-07-07
1188
+
1189
+ **Hosted-checkout reconciliation** (the create-session API contract is unchanged; the hosted
1190
+ page was rebuilt). Additive + docs only.
1191
+
1192
+ - `createCheckout` now surfaces `expiresInSeconds` (the `checkout_url` token TTL, e.g. 900) as
1193
+ a first-class field on `CreateCheckoutResult` — previously only on `.raw`.
1194
+ - README: the `platform` rail is described as cards + Apple Pay / Google Pay / Link +
1195
+ international billing (no app-store commission), and the checkout note now says reloading the
1196
+ URL after a completed payment is idempotent (an already-complete success screen), not an
1197
+ error. No API/signature changes.
1198
+
1199
+ ## [2.1.1] — 2026-07-06
1200
+
1201
+ **Security & correctness hardening** from a full audit + red-team of both SDKs. No API changes;
1202
+ upgrade recommended.
1203
+
1204
+ - **Fail closed on HTTP redirects (security).** The transport now sends `redirect:"manual"` and
1205
+ throws `UNEXPECTED_REDIRECT` on any 3xx instead of following it. Previously a redirect from
1206
+ the API host could cause the game-secret header to be re-sent to an unvalidated URL (matches
1207
+ the Python SDK fix, where the leak also covered the player token and an `http://` downgrade).
1208
+ - **`retryAfter` no longer treats a blank `retry_after` as `0`.** An empty/whitespace
1209
+ `retry_after` string used to become `0` (`Number("")===0`) — an immediate, no-backoff retry.
1210
+ It's now correctly `undefined`, in both `InvoError.retryAfter` and the retry layer.
1211
+ - **Whitespace OTP codes rejected client-side.** `recoveryComplete`/`enrollmentVerify` now
1212
+ reject a whitespace-only `code` before the network call, so it can't burn an attempt against
1213
+ the attempt-capped endpoints (parity with the Python SDK).
1214
+ - **Webhook verify uses `crypto.timingSafeEqual`** on the sync path (parity with Python's
1215
+ `hmac.compare_digest`); the runtime-agnostic async/edge path keeps its string compare.
1216
+ - **WebAuthn option mappers fail cleanly.** A malformed `register/begin` body now throws
1217
+ `WEBAUTHN_OPTIONS_MALFORMED` (an `InvoError`) instead of a raw `TypeError`.
1218
+
1219
+ ## [2.1.0] — 2026-07-02
1220
+
1221
+ **Passkey recovery ("lost or replaced my passkey").** Deleting a passkey on the device never
1222
+ tells the server the key is gone, so re-enrollment was dead-ended by the anti-takeover gate
1223
+ (`ENROLLMENT_REQUIRES_PROOF`) with nothing left to prove possession with. The backend shipped
1224
+ a self-serve, possession-proofed recovery flow; this release wires the client side.
1225
+
1226
+ - `InvoClient.recoveryBegin()` — sends a one-time code to the phone/email on file
1227
+ (`{ status: "sent", channels }`); `InvoClient.recoveryComplete(code)` — deactivates the
1228
+ stale server-side passkey and authorizes a fresh enrollment
1229
+ (`{ status: "recovered", deactivatedCount, next }`). Then retry the same `enrollPasskey()`.
1230
+ - New `InvoError` classifiers: `isEnrollmentCodeInvalid`, `isPasskeyRecoveryCooldown`, and
1231
+ `retryAfterAt` (the ISO timestamp on the 403 cooldown — distinct from the numeric
1232
+ `retryAfter` throttle field). Bare `no_channel_on_file` / `rate_limited` error tokens are
1233
+ now promoted to `err.code`.
1234
+ - **24-hour money cooldown surfaced:** a recovery-enrolled passkey logs in and collects
1235
+ funds immediately, but `approveSend`/`approveTransfer` throw 403
1236
+ `PASSKEY_RECOVERY_COOLDOWN` for 24h (SIM-swap protection). Branch on
1237
+ `isPasskeyRecoveryCooldown`, show the pause message with `retryAfterAt`, don't retry-loop.
1238
+ - README: recovery subsection under Passkeys, incl. the password-manager cleanup tip for
1239
+ "there is a problem saving your passkey" (stale orphan entry).
1240
+
1241
+ Additive, no breaking changes. Routes require SDK verification enabled for the tenant
1242
+ (dark 503 otherwise).
1243
+
1244
+ ## [2.0.0] — 2026-07-02
1245
+
1246
+ **BREAKING — `mintPlayerToken` now requires `playerPhone` (E.164).** Requested by the INVO
1247
+ backend after a live incident: a player registered email-only couldn't receive a cross-game
1248
+ transfer (incoming transfers are matched by phone) and never got the account-linking consent
1249
+ SMS (also phone-triggered). The network identity is derived from **email + phone together**,
1250
+ so the phone must be present on the FIRST registration call — attaching it later changes the
1251
+ identity and forces device re-enrollment.
1252
+
1253
+ - `mintPlayerToken({ playerEmail, playerPhone })` — `playerPhone` is required and validated
1254
+ as E.164 (`+15555550100`: leading `+`, country code, digits only) before any network call;
1255
+ the body now posts `player_phone` alongside `player_email`.
1256
+ - **Pending approval is surfaced, not an error to swallow:** minting with a phone that
1257
+ already belongs to another INVO account (same person, new email) throws the existing
1258
+ `isPhoneShareApprovalRequired` 409 — the phone holder got a consent SMS. New
1259
+ `InvoError.phoneShareApprovalId` exposes the `approval_id` from the 409 body for the
1260
+ `phoneShareApprove` OTP fallback. Docs updated to cover the registration path (previously
1261
+ documented for claims only).
1262
+ - README: new "Player registration (email + phone, required)" section; examples updated
1263
+ (`proxy-server.ts` token route now rejects a phoneless actor with a clear 400).
1264
+
1265
+ **Migration:** collect the player's phone in your enrollment UI before the first
1266
+ `mintPlayerToken` call and pass it as `playerPhone` in E.164. Handle the
1267
+ `isPhoneShareApprovalRequired` error as a "pending approval" UI state.
1268
+
1269
+ ## [1.2.1] — 2026-07-01
1270
+
1271
+ **Fix — browser "Illegal invocation".** The SDK invoked its fetch as `this.fetchImpl(...)`,
1272
+ so the browser's native `fetch` ran with the wrong `this` and threw
1273
+ `TypeError: Illegal invocation` — breaking every browser `InvoClient` read
1274
+ (balance/destinations/pending) and the passkey ceremonies when using the default global
1275
+ `fetch` (retries then made it slow on top). The fetch impl is now bound to `globalThis`
1276
+ (harmless for a custom `fetch`). No API change. Node/tests were unaffected, which is why it
1277
+ slipped through — added a `this`-sensitive regression test.
1278
+
1279
+ ## [1.2.0] — 2026-07-01
1280
+
1281
+ Two more server-side capabilities on `InvoServer`.
1282
+
1283
+ - **Phone-share OTP handshake** — `phoneShareInitiate` / `phoneShareApprove` / `phoneShareStatus`
1284
+ resolve a `409 PHONE_SHARE_APPROVAL_REQUIRED`. Unauthenticated (phone-owner-driven — no game
1285
+ secret, no player token), relayed by a partner backend; after approve, re-issue the identical
1286
+ original request (the grant is server-side + auto-consumed). Adds
1287
+ `InvoError.isPhoneShareAlreadyApproved`.
1288
+ - **Server-side `getDestinations`** — game-secret variant of the browser
1289
+ `InvoClient.getDestinations`; pass `{ sourceGameId, direction }` (default `"transfer"`), rows
1290
+ share the same `DestinationGame` shape.
1291
+
1292
+ ## [1.1.0] — 2026-07-01
1293
+
1294
+ Four additive server-side flows on `InvoServer` (the SMS-PIN / claim-code / status /
1295
+ guardian paths partners still need alongside the passkey path).
1296
+
1297
+ - **SMS-PIN completion** — `verifySmsTransfer` / `verifySmsSend` (for `verificationMethod: "sms"`).
1298
+ - **Claim-by-code** — `claimTransfer` / `claimCurrency`, incl. the `needsAccountSelection`
1299
+ multi-account disambiguation (a `200` with `candidates`, not an error).
1300
+ - **Status reads** — `getTransferStatus` / `getSendStatus` (surface `verificationState`).
1301
+ - **Guardian approval-status poll** — `getGuardianApprovalStatus` (poll a hold to `state`).
1302
+ - New typed results (`SmsVerifyResult`, `ClaimResult`, `TransactionStatusResult`,
1303
+ `GuardianApprovalStatusResult`) + `InvoError.isPhoneShareApprovalRequired`.
1304
+
1305
+ ## [1.0.0] — 2026-07-01
1306
+
1307
+ **1.0 — stable.** The public API is now covered by a stability commitment: it follows
1308
+ semver and no breaking change ships without a major bump + migration note. This is a
1309
+ milestone release, **not a breaking change** — code on `0.8.x` continues to work unchanged.
1310
+
1311
+ Also in this release (docs + DX):
1312
+
1313
+ - **Integration modes** documented — **browser-direct** (default) and **behind your proxy**
1314
+ (keep the INVO player token server-side via a custom `baseUrl`/`fetch`; no CORS or
1315
+ security-posture change). Plus a token-bootstrap example and a CORS + RP-ID/origins
1316
+ go-live checklist.
1317
+ - `linkDevice` called out as the lowest-risk first adoption (additive, no refactor).
1318
+
1319
+ ## [0.8.0] — 2026-07-01
1320
+
1321
+ Completes the **discovery layer** for send/transfer UIs.
1322
+
1323
+ - **`InvoClient.getBalance()`** (browser, player-token, `GET /api/sdk/balance`) — the
1324
+ player's balances for the token's game: `balances[]` (`currencyId`, `currencyName`,
1325
+ `currencySymbol`/`currencySymbolUrl` (nullable), `availableBalance`/`reservedBalance`/
1326
+ `totalBalance` as decimal strings) plus `totalValue` / `currencyCount` / `hasFunds`. A
1327
+ player who hasn't transacted here yet returns an empty `balances` array (a `200`, not an
1328
+ error); `404 GAME_NOT_FOUND` throws.
1329
+ - **`InvoServer.getLinkedIdentities({ playerEmail | playerPhone })`** (server-only,
1330
+ game-secret) — a player's linked wallet identities (game-scoped). Provide one identifier
1331
+ (phone wins if both); no in-game match returns `notFound: true` with empty `emails`
1332
+ instead of throwing. **Returns first-party PII — never expose to the browser.**
1333
+
1334
+ ## [0.7.0] — 2026-07-01
1335
+
1336
+ Start of the **discovery layer** for send/transfer UIs.
1337
+
1338
+ - **`InvoClient.getDestinations({ direction })`** — one player-token call
1339
+ (`GET /api/sdk/destinations`) returns every game the player can send/transfer to, with
1340
+ all display metadata **inline** (game name, icon, currency name/symbol, min/max transfer
1341
+ limits) — no per-game lookup. Includes source game/currency info and `transferMode`
1342
+ (`universal`/`linked` + `linkedGameIds`).
1343
+ - _(Coming in 0.7.x: `getBalance` single-game player-token read; `getLinkedIdentities`
1344
+ server-side.)_
1345
+
1346
+ ## [0.6.0] — 2026-07-01
1347
+
1348
+ Three additive browser flows for partner front-ends, built to the live backend contracts.
1349
+
1350
+ - **`InvoClient.getPendingCollect()`** — the player's own pending-to-collect list
1351
+ (player-token `GET /api/sdk/transfers/pending`), PII-free. Each row's `kind`
1352
+ (`identity_gate` → `approve*`, `receiving_confirm` → `confirmReceipt*`) tells you the
1353
+ action; typed fields incl. `held` / `holdReason` / `stepUpRequired`.
1354
+ - **First-enrollment OTP grant** — `enrollmentBegin()` / `enrollmentVerify(code)` for
1355
+ `ENROLLMENT_REQUIRES_AUTHORIZATION` (send OTP to phone+email, verify, then retry the
1356
+ same `enrollPasskey()` — the server grant is auto-consumed). New `InvoError` helpers
1357
+ `isEnrollmentAuthorizationRequired` / `isEnrollmentProofRequired`.
1358
+ - **Typed approve/confirm holds** — `approve*`/`confirmReceipt*` now surface a typed
1359
+ `holdReason` (from `error_code ?? code`) on HTTP 202 holds, plus `risk` /
1360
+ `guardianApproval` / `pollEndpoint` on approve. `RECIPIENT_IDENTITY_PENDING` correctly
1361
+ surfaces on confirm-receipt. Success carries no `holdReason`.
1362
+
1363
+ ## [0.5.0] — 2026-07-01
1364
+
1365
+ Support partner `metadata` end-to-end on the purchase flow (additive, backward-compatible).
1366
+
1367
+ - **`PurchaseCompletedData.metadata?`** — the `purchase.completed` webhook now echoes your
1368
+ metadata back (all rails); `event.data.metadata` is typed.
1369
+ - **`purchaseCurrency`** now accepts and forwards `metadata` (the direct `/purchase-currency`
1370
+ endpoint accepts it too, matching `createCheckout`).
1371
+
1372
+ ## [0.4.2] — 2026-06-30
1373
+
1374
+ Fixes from an independent line-by-line audit against the live backend.
1375
+
1376
+ - **`linkDevice` now works.** `device/link/webauthn/begin` returns a wrapped
1377
+ `{ link_id, options }` body (challenge nested under `options`) and binds the
1378
+ challenge to a server-generated `link_id`. The client now unwraps `options` and
1379
+ echoes the server's `link_id` to `/complete` (it previously threw on an undefined
1380
+ challenge and sent the wrong id).
1381
+ - **`InvoError.code` is now populated for the direct purchase rail + guardian flows.**
1382
+ `errorFromResponse` reads `error_code` (SecureErrorHandler + `/purchase-currency`)
1383
+ in addition to `code`, and promotes known no-code tokens (`flow_paused`,
1384
+ `spending_limit_exceeded`, `receiver_not_enrolled_use_claim_code`) to `.code`. Fixes
1385
+ `isDuplicateRequest` on the direct rail.
1386
+ - **Guardian/minor routing.** The 202 guardian body also carries
1387
+ `verification_method:"sms"`; the SDK now suppresses it (reports
1388
+ `verificationMethod: undefined`) so a guardian-pending minor isn't routed into the
1389
+ SMS-PIN UI. README example reordered to branch on `guardianApproval` first.
1390
+
1391
+ ## [0.4.1] — 2026-06-30
1392
+
1393
+ Docs only — replaced the README's internal-leaking "Deployment prerequisites"
1394
+ (backend flag names, DB columns, gating mechanics) with a partner-facing
1395
+ "Before you go live"; republished so the npm page README is current.
1396
+
1397
+ ## [0.4.0] — 2026-06-30
1398
+
1399
+ Additive release — more server reads, edge-ready webhooks, cancellation, and tooling.
1400
+
1401
+ - **`getInboundPending({ playerEmail | playerPhone })`** — live, unclaimed inbound
1402
+ sends/transfers for a player (the source of truth behind the "you have X to collect"
1403
+ badge; pairs with `transfer.claim_pending`).
1404
+ - **`verifyWebhookAsync`** — Web Crypto variant of `verifyWebhook` that runs on
1405
+ Cloudflare Workers / Deno / Vercel+Netlify Edge / Bun / browsers; and
1406
+ **`createWebhookHandler`** — a zero-dep Fetch-API `(Request) => Promise<Response>`
1407
+ webhook route handler (Next.js App Router, Workers, Deno, Hono, Bun).
1408
+ - **`iterateItemPurchaseHistory`** — async iterator that pages through a player's
1409
+ full item-purchase history.
1410
+ - **Per-call `AbortSignal`** — every method accepts an optional `{ signal }`; an
1411
+ aborted call throws `InvoError` code `ABORTED` and is never retried.
1412
+ - **Tooling**: ESLint (+ lint in CI), changesets release automation, `SECURITY.md`,
1413
+ and `CODEOWNERS`.
1414
+
1415
+ ## [0.3.0] — 2026-06-30
1416
+
1417
+ Additive release — new server capabilities plus transport resilience/observability.
1418
+
1419
+ - **Webhook verification** (`/server`): `verifyWebhook(rawBody, signatureHeader, secret | secrets, opts?)`
1420
+ — constant-time HMAC-SHA256 over `${t}.${rawBody}`, 5-minute replay window,
1421
+ multi-secret rotation; returns a typed `InvoWebhookEvent` discriminated union
1422
+ (`purchase.*`, `item.purchased`, `transfer.*`, `payout.status_changed`, `webhook.test`).
1423
+ Throws `InvoError` (`WEBHOOK_SIGNATURE_INVALID` / `WEBHOOK_TIMESTAMP_EXPIRED` /
1424
+ `WEBHOOK_MALFORMED` / `WEBHOOK_SECRET_MISSING`). Server-only; the browser bundle
1425
+ stays crypto-free. Independently security-audited.
1426
+ - **`getPlayerBalance({ playerEmail | playerId })`** (`/server`): typed `player` / `balances` / `summary`.
1427
+ - **Automatic retries**: network errors/timeouts, `429` (honoring `retry_after`), and
1428
+ `5xx` are retried with exponential backoff + jitter. New config `maxRetries`
1429
+ (default 2, `0` disables) and `retryBaseDelayMs` (default 250).
1430
+ - **Observability hooks**: optional `onRequest` / `onResponse` / `onError` on both
1431
+ entries (best-effort/non-throwing); `InvoError.requestId` carries the backend
1432
+ request id for support/tracing.
1433
+ - **Typed reads**: `confirmPayment` → `ConfirmPaymentResult`; `getOrderDetails` /
1434
+ `getItemOrderDetails` → `OrderDetailsResult`; `getItemPurchaseHistory` →
1435
+ `ItemHistoryResult` (previously untyped `Record`). All keep `raw`.
1436
+ - **Light validation**: `mintPlayerToken` and `createCheckout` require a non-blank
1437
+ `playerEmail` (throws `INVALID_INPUT` before the network call).
1438
+ - **License**: `package.json` `license` is now `SEE LICENSE IN LICENSE` (was
1439
+ `UNLICENSED`); `LICENSE` rewritten as an explicit install-and-use grant for
1440
+ building INVO integrations.
1441
+
1442
+ ## [0.2.1] — 2026-06-30
1443
+
1444
+ Docs only — no code change (republished so the npm page README is current).
1445
+
1446
+ - Rewrote the README into a complete integration/deployment guide: capability
1447
+ overview, architecture, deployment prerequisites, per-flow sections (currency
1448
+ purchase, item purchase, sends, transfers, passkeys), webhooks, errors, and a
1449
+ full API reference for both entries.
1450
+ - Added INVO console onboarding: `https://console.invo.network` (production) and
1451
+ `https://dev.console.invo.network` (testing/sandbox), mapped to their API base URLs.
1452
+
1453
+ ## [0.2.0] — 2026-06-30
1454
+
1455
+ Adds **item purchase** (spend existing game currency on an in-game item, §4.8) — an
1456
+ additive, server-only surface.
1457
+
1458
+ - `InvoServer` (`/server`): `purchaseItem`, `getItemPurchaseHistory`, `getItemOrderDetails`.
1459
+ - Server-side, game-secret auth — no passkey, no real money, no payment rail (it's a
1460
+ balance debit). Grant the item off the `item.purchased` webhook.
1461
+ - Client-side guards: required fields (trim-checked), `itemQuantity` integer `1..1000`,
1462
+ prices `> 0` and `<= 999999.99` (magnitude-safe 2-decimal check), and
1463
+ `totalPrice == unitPrice × itemQuantity (±0.01)` compared in integer cents.
1464
+ - Load-bearing response fields (`transaction_id`, `order_id`) throw `INVALID_RESPONSE`
1465
+ if missing on a 200.
1466
+ - `InvoError` helpers: `isInsufficientBalance` (gated to 400; not the `429` throttle),
1467
+ `isDuplicateRequest` (409), `retryAfter` (numeric or string `retry_after`); all
1468
+ null-safe against non-JSON error bodies.
1469
+ - Independently audited (2 agents) against handoff doc §4.8/§6/§8; contract verified,
1470
+ error-classification edge cases fixed.
1471
+
1472
+ ## [0.1.0] — 2026-06-30
1473
+
1474
+ Initial scaffold.
1475
+
1476
+ - `InvoServer` (`/server`): `mintPlayerToken`, `initiateSend`, `initiateTransfer`,
1477
+ `createCheckout`, `purchaseCurrency`, `confirmPayment`, `getOrderDetails`.
1478
+ - Client-side purchase guards (§4.7): USD amount `0 < x ≤ 999.99`, required
1479
+ `purchaseReference`, and `rail:"steam"` rejected before the network call
1480
+ (`INVALID_INPUT` / `MISSING_PURCHASE_REFERENCE` / `WRONG_RAIL_ENDPOINT`).
1481
+ - `InvoClient` (browser): `enrollPasskey`, `approveSend`/`approveTransfer`,
1482
+ `confirmReceiptSend`/`confirmReceiptTransfer`, and `linkDevice` for the
1483
+ interchangeable-methods flow (§4.6).
1484
+ - Optional `refreshToken` hook: transparently re-mints and retries once on
1485
+ `SDK_TOKEN_EXPIRED` (§11.2).
1486
+ - Shared: typed `InvoError`, isomorphic HTTP client, WebAuthn JSON⇄binary helpers.
1487
+ - Tests: HTTP layer, server request mapping + purchase guards, browser client
1488
+ flows (enroll/approve/link/token-refresh), and WebAuthn serialization.
1489
+ - Contracts extracted + auditor-verified against the INVO backend.
1490
+
1491
+ ### Hardening (independent red-team pass)
1492
+
1493
+ - **Guardian/minor `202` path no longer mismapped to `verificationMethod:"sms"`** —
1494
+ `initiateSend`/`initiateTransfer` now return `verificationMethod: undefined` and a
1495
+ `guardianApproval` block on the guardian path, so callers don't route into the
1496
+ PIN UI by mistake (§4.3).
1497
+ - `usdAmount` validation tightened: rejects non-plain-decimal strings
1498
+ (`"0x10"`, `"1e2"`, whitespace) and >2 decimal places before any network call.
1499
+ - Load-bearing response fields (`token`, `checkout_url`) now throw `INVALID_RESPONSE`
1500
+ instead of silently surfacing as empty strings.
1501
+ - `getOrderDetails` requires at least one of `orderId`/`transactionId`.
1502
+ - Token refresh now re-runs the **whole** passkey ceremony on `SDK_TOKEN_EXPIRED`
1503
+ (never replays a single-use assertion) and single-flights concurrent refreshes.
1504
+ - `baseUrl` must be `https://` (localhost exempt) so the token/secret can't travel
1505
+ in cleartext.
1506
+ - Published tarball excludes sourcemaps (no proprietary source shipped).