@invonetwork/web-sdk 3.30.3 → 3.31.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,22 @@
1
1
  # Changelog
2
2
 
3
+ ## 3.31.0
4
+
5
+ ### Minor Changes
6
+
7
+ - Types the backend fields that shipped 2026-10-20. All additive; nothing renamed or removed.
8
+
9
+ - `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.
10
+ - `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.
11
+ - 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.
12
+ - 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).
13
+
14
+ ## 3.30.4
15
+
16
+ ### Patch Changes
17
+
18
+ - 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.
19
+
3
20
  ## 3.30.3
4
21
 
5
22
  ### Patch Changes
package/README.md CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  First-party TypeScript SDK for integrating **INVO** into partner **web** platforms (storefronts, web games, dashboards). It wraps INVO's web money flows behind a typed, versioned API — the web analog of the Unity/Unreal plugins.
4
4
 
5
- > **Status:** `v3.23.0`, stable, published on npm. The backend it wraps is **live** on sandbox + production. The API is covered by a [stability commitment](#stability): no breaking changes without a major bump. Recent highlights: **3.23.0** types two optional fields on the `purchase.disputed` close: `dispute_fee_usd` and `dispute_fee_charged_to_partner` (from November 8, 2026 the card dispute fee on Open-tier card sales is passed through to you at cost); **3.22.0** follows INVO's 2026-10 pricing: the Open card fee is **3.5% + $0.30** (was 4.5%), Merchant of Record stays **5.5% + $0.50**; the **chargeback guarantee** is a Merchant of Record term (Open-tier card payments made before November 8, 2026 keep it); payouts to your bank carry a **1% fee, capped at $500 per payout**. New reads: `getPlayerActivity()` / `iteratePlayerActivity()` (one merged list of a player's purchases, sends and transfers) and `platformCommerce.getPurchaseHistory()` / `iteratePurchaseHistory()`; `expiryReason` on `getTransferStatus()` / `getSendStatus()`; typed `transfer.*` and `payout.status_changed` webhook fields; new additive `err.publicCode` (the neutral twin of a code), set to `"BELOW_CARD_MINIMUM"` on the local card-floor refusal, whose `err.code` is unchanged (see [Tiers](#tiers) for the pricing); and the **[player-confirmed phone change](#player-confirmed-phone-change)**: `requestPhoneChange()` / `getPhoneChange()` on the server, `listPhoneChangeApprovals()` / `approvePhoneChange()` on the player's enrolled device, the typed `player.phone_changed` webhook, `err.changeRequestEndpoint` and new phone change error helpers; **3.18.0** follows INVO's 2026-09 card pricing: on card purchases **you pay INVO's card fee** (**4.5% + $0.30** on Open, **5.5% + $0.50** on Merchant of Record, plus **1.5%** on a card issued outside the US) and the player pays the listed price and gets the listed coins; fraud screening and a **chargeback guarantee** are included; minimum card purchase **$2.99** from 2026-10-27. New `partnerFeeUsd`, `internationalCardFeeUsd`, `minPurchaseWarning`, `feeTakenFrom: "partner"`, `err.minUsd` / `err.enforcedFrom` on `err.isBelowCardMinimum`, `minPurchaseWarning` on `createCheckout()`, `country` / `subdivision` on `purchaseCurrency()` with `err.isTaxPlaceUnavailable`, `cardFeeChargedToPartnerUsd` / `partnerDebitedUsd` on Platform Commerce card refunds, and the `partner_fee_usd` / `international_card_fee_usd` / `guarantee_covered` / `card_fee_charged_to_partner_usd` / `partner_debited_usd` webhook fields, all additive; an unacknowledged $10.00 coin purchase now credits 100.00 coins, not 93.70 (see **[Tiers](#tiers)**); **3.17.0** types the Steam fields on `purchase.refunded` / `purchase.disputed` (`rail`, `steam_transid`, nullable card-only ids): Steam chargebacks now arrive as `purchase.disputed`; **3.16.0** adds `warnings` on `createCheckout()` (item metadata on a coin session), `err.isDuplicateClientRequestId`, `err.isTrialAmountBelowFeeFloor` and `err.isIdentityCheckUnavailable`; **3.14.0** adds `credited` / `reasonCode` on `confirmPayment()` and `steamFinalizePurchase()`, Merchant of Record receipt fields, Platform Commerce card refunds in parts, and updates the **[tiers](#tiers)**: subscription card rates and chargeback handling by tier (the rates are superseded by 3.18.0), and Merchant of Record is applied for from the console; **3.13.0** documents the two **[tiers](#tiers)** (Open by default, Merchant of Record by application), adds **[INVO's card fee on coin purchases](#invos-card-fee-quote-show-acknowledge)** (rates superseded by 3.18.0): `quoteCurrencyPurchase()`, `acknowledgedTotalUsd` on `purchaseCurrency()`, the new `processingFeeUsd` / `feeTakenFrom` / `coinsCredited` / `chargeTotalUsd` fields and `err.isAmountBelowFee` / `err.isQuoteStale`, states the coin refund rule (only unspent coins), and adds **[paid trials](#paid-trials)** on card subscriptions (`trialAmountUsd`, the disclosed trial consent fields, `is_trial` / `expire_cause` on the events, `err.isPaymentMethodRequired` and the `isTrialAmount*` helpers); **3.12.0** removes the SDK's own card maximum (INVO's is a runtime setting, $100,000.00 by default); **3.11.0** adds the **[purchase status read](#did-the-purchase-go-through-the-status-read)**, where `invo.checkout.getPurchaseStatus()` / `waitForPurchase()` (and the standalone `CheckoutClient`) answer what happened to a hosted-checkout purchase in six words, four of them terminal, so a buyer is never shown a page that closes on nothing; stopping is decided by INVO's `terminal` and never re-derived from `status`, `nothingWasCharged()` says when a **Try again** is safe, `createCheckout()` now also returns `sessionToken`, and the subscription fee is corrected (it is its own rate; item purchases stay at 10/90; see [Tiers](#tiers) for the current rate); **3.10.0** documents **card-only subscriptions** (the card pays the full price every period, the coin wallet never pays; `walletOnly` deprecated; new `failure_code` `wallet_negative`; a renewal's `purchase.completed` is not a purchase) and the **[subscription refund limits](#refunds)**: `subscriptions.refund` can now return a 202 `pending_approval` refund request (`isRefundPendingApproval`), with `warnings`, the processor fee you bear, `subscriptionCanceled` (a full refund cancels), new classifiers (`isRefundsNotEnabled`, `isRefundWindowClosed`, `isRefundRequestPending`, `isRefundRequestRejected`, `isConcurrentRequest`, `isRefundMismatch`) and typed `subscription.refund_requested` / `refund_approved` / `refund_rejected` events, all additive; **3.9.0** adds the **[INVO-hosted card page for subscriptions](#cards-for-subscriptions)**, `invo.cards.createSetupSession`: mint a 10-minute link server-side, send the member to it, read the card back from `cards.list`, with no browser code and no card processor named anywhere (`beginSetup`/`confirmSetup` remain as the processor-bound alternative), plus the `isPlayerNotFound`, `isInvalidPlayerEmail` and `isInvalidInput` classifiers and a fix that makes `includePlayer` reads actually surface `playerEmail`/`playerName`; **3.8.0** adds **[Subscriptions](#subscriptions-recurring-billing)** as a first-class server surface on both rails: `invo.subscriptions.create/get/listForPlayer/cancel/changeAmount/setPaymentMethod/refund/steamInit/steamFinalize`, the off-session card capture (`invo.cards.beginSetup/confirmSetup/list`), the sandbox clock tools (`invo.sandbox.subscriptions.*`, which post to `/subscriptions/<id>/...` **relative to the sandbox base, not under `/api`**, with the new `sandboxClockKey`), typed `data` for all seven `subscription.*` webhook events, and eleven new error classifiers; **3.7.0** makes the **device approval grant a first-class SDK surface**: `beginDeviceApproval`, `pollDeviceApproval`, `confirmDeviceEnrollment` and, the step that actually moves the money, **`approveWithDeviceCode`** (plus the optional `completeDeviceApproval` loop); a grant that is polled to `approved` and left there settles **nothing**, which is the failure this release exists to make impossible, and `TRANSACTION_NOT_PENDING` now comes back as a typed `status: "not_pending"` result with `alreadySettled` rather than a thrown error you would have to string-match; **3.4.0** documents that a Steam title now bills through **its own Steam application**: the studio registers their appid + publisher Web API key and keeps a payment method on file, because Valve pays the studio and INVO settles afterwards (new `isSteamNotConfigured`, `isPartnerBillingNotSetUp`, `isPartnerSettlementUnavailable`, `isSteamAppChanged` error helpers); **3.2.3** corrects the base path and auth header in the Steam snippets (`/api/currency-purchases`, `X-Game-Secret-Key`); 3.2.2 published both wrong, and copying them returned a 404; **3.2.x** documents **Steam currency purchases on a pack model**: INVO owns the catalogue, you pass a `pack_id` and never a price, and the currency inside a pack varies by country because Steam prices are VAT-inclusive; **3.1.0** makes the authentication guidance explicit: **[passkeys are the gold standard](#passkeys-are-the-gold-standard-dont-build-on-sms)** and the SMS-PIN completion (`verifySmsTransfer`/`verifySmsSend`) is **deprecated and being phased out** (documentation only: no behavior change, no runtime warnings); **3.0.0** moves the Platform Commerce card leg to **INVO's hosted checkout**: the server `purchase()` now returns a `checkoutUrl` and the browser just sends the buyer there (redirect or `mountCheckout` iframe); the 2.5.x card-element surface (`confirmCardPayment`/`mountCardPayment`, `billingAddress`, `commercePublishableKey`) is **removed**; see the [CHANGELOG](CHANGELOG.md) migration note; **2.5.0** added **Platform Commerce** (ecommerce): a platform tenant selling items funded by balance **or** card, with `invo.platformCommerce.purchase/getStatus/refund` (server) and the `platform_commerce.*` webhooks; **2.4.0** adds Steam transfer-policy handling (`isSteamValueNonTransferable`/`isNonSteamValueIntoSteamBlocked` + `DestinationGame.acceptsSteamOriginValue`); **2.3.0** surfaces the claim-time phone-share `409` on `confirmReceipt*`/`claim*` (+ `err.phoneShareLast4`). Full history in the [CHANGELOG](CHANGELOG.md).
5
+ > **Status:** `v3.31.0`, stable, published on npm. The backend it wraps is **live** on sandbox + production. The API is covered by a [stability commitment](#stability): no breaking changes without a major bump. Recent highlights: **3.31.0** adds `invoFeeUsd` / `partnerShareUsd` on `platformCommerce.getStatus()` and `getPurchaseHistory()`, `spent_coins_charged_usd` on the coin `purchase.disputed` close (coins already spent are charged to you on a lost dispute), `err.isRateLimited` (every rate-limit 429 now carries `RATE_LIMITED`) and a `Retry-After` header fallback for `err.retryAfter`, and documents dispute holds on both tiers and the $10 payout minimum; **3.23.0** types two optional fields on the `purchase.disputed` close: `dispute_fee_usd` and `dispute_fee_charged_to_partner` (from November 8, 2026 the card dispute fee on Open-tier card sales is passed through to you at cost); **3.22.0** follows INVO's 2026-10 pricing: the Open card fee is **3.5% + $0.30** (was 4.5%), Merchant of Record stays **5.5% + $0.50**; the **chargeback guarantee** is a Merchant of Record term (Open-tier card payments made before November 8, 2026 keep it); payouts to your bank carry a **1% fee, capped at $500 per payout**. New reads: `getPlayerActivity()` / `iteratePlayerActivity()` (one merged list of a player's purchases, sends and transfers) and `platformCommerce.getPurchaseHistory()` / `iteratePurchaseHistory()`; `expiryReason` on `getTransferStatus()` / `getSendStatus()`; typed `transfer.*` and `payout.status_changed` webhook fields; new additive `err.publicCode` (the neutral twin of a code), set to `"BELOW_CARD_MINIMUM"` on the local card-floor refusal, whose `err.code` is unchanged (see [Tiers](#tiers) for the pricing); and the **[player-confirmed phone change](#player-confirmed-phone-change)**: `requestPhoneChange()` / `getPhoneChange()` on the server, `listPhoneChangeApprovals()` / `approvePhoneChange()` on the player's enrolled device, the typed `player.phone_changed` webhook, `err.changeRequestEndpoint` and new phone change error helpers; **3.18.0** follows INVO's 2026-09 card pricing: on card purchases **you pay INVO's card fee** (**4.5% + $0.30** on Open, **5.5% + $0.50** on Merchant of Record, plus **1.5%** on a card issued outside the US) and the player pays the listed price and gets the listed coins; fraud screening and a **chargeback guarantee** are included; minimum card purchase **$2.99** from 2026-10-27. New `partnerFeeUsd`, `internationalCardFeeUsd`, `minPurchaseWarning`, `feeTakenFrom: "partner"`, `err.minUsd` / `err.enforcedFrom` on `err.isBelowCardMinimum`, `minPurchaseWarning` on `createCheckout()`, `country` / `subdivision` on `purchaseCurrency()` with `err.isTaxPlaceUnavailable`, `cardFeeChargedToPartnerUsd` / `partnerDebitedUsd` on Platform Commerce card refunds, and the `partner_fee_usd` / `international_card_fee_usd` / `guarantee_covered` / `card_fee_charged_to_partner_usd` / `partner_debited_usd` webhook fields, all additive; an unacknowledged $10.00 coin purchase now credits 100.00 coins, not 93.70 (see **[Tiers](#tiers)**); **3.17.0** types the Steam fields on `purchase.refunded` / `purchase.disputed` (`rail`, `steam_transid`, nullable card-only ids): Steam chargebacks now arrive as `purchase.disputed`; **3.16.0** adds `warnings` on `createCheckout()` (item metadata on a coin session), `err.isDuplicateClientRequestId`, `err.isTrialAmountBelowFeeFloor` and `err.isIdentityCheckUnavailable`; **3.14.0** adds `credited` / `reasonCode` on `confirmPayment()` and `steamFinalizePurchase()`, Merchant of Record receipt fields, Platform Commerce card refunds in parts, and updates the **[tiers](#tiers)**: subscription card rates and chargeback handling by tier (the rates are superseded by 3.18.0), and Merchant of Record is applied for from the console; **3.13.0** documents the two **[tiers](#tiers)** (Open by default, Merchant of Record by application), adds **[INVO's card fee on coin purchases](#invos-card-fee-quote-show-acknowledge)** (rates superseded by 3.18.0): `quoteCurrencyPurchase()`, `acknowledgedTotalUsd` on `purchaseCurrency()`, the new `processingFeeUsd` / `feeTakenFrom` / `coinsCredited` / `chargeTotalUsd` fields and `err.isAmountBelowFee` / `err.isQuoteStale`, states the coin refund rule (only unspent coins), and adds **[paid trials](#paid-trials)** on card subscriptions (`trialAmountUsd`, the disclosed trial consent fields, `is_trial` / `expire_cause` on the events, `err.isPaymentMethodRequired` and the `isTrialAmount*` helpers); **3.12.0** removes the SDK's own card maximum (INVO's is a runtime setting, $100,000.00 by default); **3.11.0** adds the **[purchase status read](#did-the-purchase-go-through-the-status-read)**, where `invo.checkout.getPurchaseStatus()` / `waitForPurchase()` (and the standalone `CheckoutClient`) answer what happened to a hosted-checkout purchase in six words, four of them terminal, so a buyer is never shown a page that closes on nothing; stopping is decided by INVO's `terminal` and never re-derived from `status`, `nothingWasCharged()` says when a **Try again** is safe, `createCheckout()` now also returns `sessionToken`, and the subscription fee is corrected (it is its own rate; item purchases stay at 10/90; see [Tiers](#tiers) for the current rate); **3.10.0** documents **card-only subscriptions** (the card pays the full price every period, the coin wallet never pays; `walletOnly` deprecated; new `failure_code` `wallet_negative`; a renewal's `purchase.completed` is not a purchase) and the **[subscription refund limits](#refunds)**: `subscriptions.refund` can now return a 202 `pending_approval` refund request (`isRefundPendingApproval`), with `warnings`, the processor fee you bear, `subscriptionCanceled` (a full refund cancels), new classifiers (`isRefundsNotEnabled`, `isRefundWindowClosed`, `isRefundRequestPending`, `isRefundRequestRejected`, `isConcurrentRequest`, `isRefundMismatch`) and typed `subscription.refund_requested` / `refund_approved` / `refund_rejected` events, all additive; **3.9.0** adds the **[INVO-hosted card page for subscriptions](#cards-for-subscriptions)**, `invo.cards.createSetupSession`: mint a 10-minute link server-side, send the member to it, read the card back from `cards.list`, with no browser code and no card processor named anywhere (`beginSetup`/`confirmSetup` remain as the processor-bound alternative), plus the `isPlayerNotFound`, `isInvalidPlayerEmail` and `isInvalidInput` classifiers and a fix that makes `includePlayer` reads actually surface `playerEmail`/`playerName`; **3.8.0** adds **[Subscriptions](#subscriptions-recurring-billing)** as a first-class server surface on both rails: `invo.subscriptions.create/get/listForPlayer/cancel/changeAmount/setPaymentMethod/refund/steamInit/steamFinalize`, the off-session card capture (`invo.cards.beginSetup/confirmSetup/list`), the sandbox clock tools (`invo.sandbox.subscriptions.*`, which post to `/subscriptions/<id>/...` **relative to the sandbox base, not under `/api`**, with the new `sandboxClockKey`), typed `data` for all seven `subscription.*` webhook events, and eleven new error classifiers; **3.7.0** makes the **device approval grant a first-class SDK surface**: `beginDeviceApproval`, `pollDeviceApproval`, `confirmDeviceEnrollment` and, the step that actually moves the money, **`approveWithDeviceCode`** (plus the optional `completeDeviceApproval` loop); a grant that is polled to `approved` and left there settles **nothing**, which is the failure this release exists to make impossible, and `TRANSACTION_NOT_PENDING` now comes back as a typed `status: "not_pending"` result with `alreadySettled` rather than a thrown error you would have to string-match; **3.4.0** documents that a Steam title now bills through **its own Steam application**: the studio registers their appid + publisher Web API key and keeps a payment method on file, because Valve pays the studio and INVO settles afterwards (new `isSteamNotConfigured`, `isPartnerBillingNotSetUp`, `isPartnerSettlementUnavailable`, `isSteamAppChanged` error helpers); **3.2.3** corrects the base path and auth header in the Steam snippets (`/api/currency-purchases`, `X-Game-Secret-Key`); 3.2.2 published both wrong, and copying them returned a 404; **3.2.x** documents **Steam currency purchases on a pack model**: INVO owns the catalogue, you pass a `pack_id` and never a price, and the currency inside a pack varies by country because Steam prices are VAT-inclusive; **3.1.0** makes the authentication guidance explicit: **[passkeys are the gold standard](#passkeys-are-the-gold-standard-dont-build-on-sms)** and the SMS-PIN completion (`verifySmsTransfer`/`verifySmsSend`) is **deprecated and being phased out** (documentation only: no behavior change, no runtime warnings); **3.0.0** moves the Platform Commerce card leg to **INVO's hosted checkout**: the server `purchase()` now returns a `checkoutUrl` and the browser just sends the buyer there (redirect or `mountCheckout` iframe); the 2.5.x card-element surface (`confirmCardPayment`/`mountCardPayment`, `billingAddress`, `commercePublishableKey`) is **removed**; see the [CHANGELOG](CHANGELOG.md) migration note; **2.5.0** added **Platform Commerce** (ecommerce): a platform tenant selling items funded by balance **or** card, with `invo.platformCommerce.purchase/getStatus/refund` (server) and the `platform_commerce.*` webhooks; **2.4.0** adds Steam transfer-policy handling (`isSteamValueNonTransferable`/`isNonSteamValueIntoSteamBlocked` + `DestinationGame.acceptsSteamOriginValue`); **2.3.0** surfaces the claim-time phone-share `409` on `confirmReceipt*`/`claim*` (+ `err.phoneShareLast4`). Full history in the [CHANGELOG](CHANGELOG.md).
6
6
  > Canonical partner reference: **https://docs.invo.network/docs/currency-purchase** and **https://docs.invo.network/docs/game-developer-integration**.
7
7
 
8
8
  ## What it does
@@ -494,15 +494,17 @@ Every INVO developer account is on one of two tiers. The SDK calls are the same
494
494
  | Item purchases (coins spent on an item) | 5% (you keep 95%) | 5% (you keep 95%) |
495
495
  | Platform Commerce balance purchases | 3.5% | 3.5% |
496
496
  | Sends and transfers between players | 10% of the amount: 3.5% to the sending title, 3.5% to the receiving title, 3% to INVO | same |
497
- | Payouts to your bank | scheduled payouts (the 1st and 16th of each month, UTC, $100 minimum) are free; on demand, 1% per payout, capped at $500, $100 minimum | same |
497
+ | Payouts to your bank | scheduled payouts (the 1st and 16th of each month, UTC, $10 minimum) are free; on demand, 1% per payout, capped at $500, $10 minimum | same |
498
498
 
499
499
  The card terms above (card fee, international fee, minimum and chargeback guarantee) apply to card purchases only; purchases through a third-party storefront or payment rail are unaffected and keep their current terms. On both tiers every card charge runs on INVO's card rail and INVO pays you out, as today. The card fee is charged to you, never to the buyer: the buyer pays the listed price (plus tax on Merchant of Record) and receives the listed coins or item. It nets against your earnings at purchase time and is not returned on a refund. The 1.5% on a card issued outside the United States applies on both tiers to every card charge and is reported as `international_card_fee_usd` (on a Platform Commerce sale it is already included in `fee_breakdown.platform_fee`); it replaces the earlier pass-through of international and currency conversion costs on subscriptions. Worked example, a $100.00 card sale: the buyer pays $100.00 (plus tax on Merchant of Record) and your fee is $3.65 on Open or $5.15 on Merchant of Record; on a card issued outside the US, $5.15 or $6.65. On a $10.00 sale: $0.50 or $0.65. The Open card fee was 4.5% + $0.30 until 2026-10-09 and 3.5% + $0.30 until 2026-10-15; Merchant of Record was 5.5% + $0.50 until 2026-10-15. On Merchant of Record, if your chargeback rate for the previous calendar month (disputes opened, excluding inquiries, divided by card charges completed, in UTC months) was above 0.75%, the dispute fee on subscription charges disputed this month for a reason the chargeback guarantee does not cover is charged to you as on Open, and INVO reviews your approval. Merchant of Record is applied for per developer account, not per game, from the Selling & Tax page in your INVO console, and INVO reviews each application. Full details: https://docs.invo.network/docs/tiers/
500
500
 
501
501
  **Chargeback guarantee by tier.** The guarantee (INVO absorbs a lost fraud chargeback on a card sale) is a Merchant of Record term. On Open, card payments made before November 8, 2026 keep it; for card payments from that date, a lost fraud chargeback is your responsibility and is passed through at cost, like any other lost chargeback. Fraud screening stays included on every card payment on both tiers. On a lost dispute, `guarantee_covered` on `purchase.disputed` says which case applies. When a card dispute closes, `purchase.disputed` also carries `dispute_fee_usd` (the dispute fee charged to you for that dispute, `"0.00"` when INVO bears it) and `dispute_fee_charged_to_partner`. A lost dispute is `purchase.disputed` with `dispute_status: "lost"`; there is no separate lost-dispute event.
502
502
 
503
+ **Held while a dispute is open, both tiers (since 2026-10-20).** While a dispute you are responsible for is open, the disputed amount is held from your earnings so it cannot be paid out: your share of a Platform Commerce card sale or subscription charge, or on a coin purchase the price paid before tax, less anything already refunded and never more than the disputed amount. Your withdrawable balance already excludes it (`dispute_holds_usd` and `disputes_on_hold` on `GET /api/withdrawals/available-balance`, outside this SDK). A won dispute releases the hold; a lost one is booked once. **On a lost coin purchase dispute**, INVO takes back the coins the player still holds (never below zero) and charges you for coins the player had already spent, at the price paid per coin before tax: `spent_coins_charged_usd` on the closing `purchase.disputed` (`"0.00"` when nothing was charged). Nothing is charged when the chargeback guarantee covers the dispute.
504
+
503
505
  **Sends and transfers.** The fee is 10% of the amount moved, a network standard that is the same for every title: 3.5% to the sending title, 3.5% to the receiving title and 3% to INVO. Moving 100.00: the fee is 10.00 (3.50 to the sending title, 3.50 to the receiving title, 3.00 to INVO) and the recipient gets 90.00. A move inside one title earns that title both shares, 7.00, and INVO 3.00. Reconcile from the webhook figures rather than recomputing.
504
506
 
505
- **Payouts.** INVO pays you, the partner, and you pay your own players from your own funds; INVO does not pay players. Payouts INVO makes on its schedule (the 1st and 16th of each month, UTC, $100 minimum) are free. A payout of your balance to your bank that you request on demand (developer withdrawals and partner payouts) carries a payout fee of 1% of the amount, capped at $500 per payout, with a $100 minimum; negotiated rates may apply. Creator payouts keep the payout fee. The fee is deducted from the payout: `payout.status_changed` carries `offboarding_fee_pct`, `offboarding_fee_usd`, `offboarding_fee_cap_usd` and `net_payout_usd` (what reaches your bank). Negotiated or custom rates for any fee here are available on request.
507
+ **Payouts.** INVO pays you, the partner, and you pay your own players from your own funds; INVO does not pay players. Payouts INVO makes on its schedule (the 1st and 16th of each month, UTC, $10 minimum) are free. A payout of your balance to your bank that you request on demand (developer withdrawals and partner payouts) carries a payout fee of 1% of the amount, capped at $500 per payout, with a $10 minimum (the minimum was $100 until 2026-10-20); negotiated rates may apply. Creator payouts keep the payout fee. The fee is deducted from the payout: `payout.status_changed` carries `offboarding_fee_pct`, `offboarding_fee_usd`, `offboarding_fee_cap_usd` and `net_payout_usd` (what reaches your bank). Negotiated or custom rates for any fee here are available on request.
506
508
 
507
509
  **What the tier changes in what the SDK returns** (all additive):
508
510
 
@@ -641,7 +643,7 @@ Rules worth taking literally:
641
643
 
642
644
  ### Payment rails (neutral names)
643
645
 
644
- The `rail` selects the in-page experience — all branded INVO, no visible redirect:
646
+ The `rail` selects the in-page experience, with no visible redirect. Every rail's page shows the INVO logo by default, or your game's own logo once you upload one in the INVO console (Game settings, Checkout branding), with a small "Secured by INVO" line at the bottom; the same logo appears on the hosted card page and the subscription payment confirmation page. There is no SDK call to set it. See [Use your own logo on checkout](https://docs.invo.network/docs/currency-purchase#checkout-branding).
645
647
  - `"platform"` (default) — cards plus **Apple Pay / Google Pay / Link** (rendered automatically on supported devices) and international billing addresses. It's a web checkout, so there's no app-store commission.
646
648
  - `"game"` — regional / game-store methods (may redirect to the regional hosted page).
647
649
  - `"steam"` — Steam titles hand off to the in-client Steam flow.
@@ -989,6 +991,8 @@ const handle = invo.platformCommerce.mountCheckout("#checkout", checkoutUrl, {
989
991
  ```ts
990
992
  const s = await server.platformCommerce.getStatus(r.orderId);
991
993
  // s.status: "completed" (balance immediately; card after the webhook) | "pending_payment" | "refunded"
994
+ // Once settled: s.invoFeeUsd (everything INVO kept on the sale) and s.partnerShareUsd (what you
995
+ // earned), USD strings; null until the sale settles. getPurchaseHistory() entries carry the same.
992
996
 
993
997
  const ref = await server.platformCommerce.refund({ orderId: r.orderId, reason: "customer request" });
994
998
  // or refund({ clientRequestId }). Pass EXACTLY ONE id.
@@ -2545,7 +2549,7 @@ the client uses `getMyRewards()` with the player token instead.
2545
2549
  | `getPlayerRewards` | 400 | `INVALID_PLAYER_EMAIL` | `err.isInvalidPlayerEmail` |
2546
2550
  | `getPlayerRewards` | 401 | `INVALID_GAME_SECRET` (missing or wrong key, or a per-channel key: this read takes the server secret only) | |
2547
2551
  | `getPlayerRewards` | 404 | `PLAYER_NOT_FOUND` (no player with this email in this game) | `err.isPlayerNotFound` |
2548
- | any | 429 | (do not match on a code) | treat any 429 as retryable after a pause; `err.retryAfter` (reads are retried automatically first) |
2552
+ | any | 429 | `RATE_LIMITED` on every rate-limit refusal (some endpoints send their own throttle body) | `err.isRateLimited` (true on any 429); wait `err.retryAfter` seconds and retry (reads are retried automatically first) |
2549
2553
  | `redeemReward` | 409 | `already_redeemed` | `err.isRewardAlreadyRedeemed` |
2550
2554
  | `redeemReward` | 404 | `vault_entry_not_found` | `err.isRewardNotFound` |
2551
2555
  | `redeemReward` | 410 | `vault_entry_expired` | `err.isRewardExpired` |
@@ -2709,7 +2713,7 @@ export const POST = createWebhookHandler({
2709
2713
  |---|---|---|
2710
2714
  | `purchase.completed` | every currency-purchase rail, **and every paid card subscription renewal** | grant currency (payload: `transaction_id, order_id, player_email, identity_id, usd_amount, currency_amount, currency_name, new_balance, rail`, `metadata`). `metadata` echoes what you passed to `createCheckout`/`purchaseCurrency` (all rails); `order_id` is also on every webhook as a secondary reconciliation key (`getOrderDetails`). Card purchases also carry `partner_fee_usd` and `international_card_fee_usd`, the card fees charged to you (the player paid the listed price). **Skip it when `metadata.source` is `"subscription_renewal"`**: those coins are spent by the renewal itself; grant on `subscription.renewed`. |
2711
2715
  | `purchase.failed` | `platform` rail only | handle failures |
2712
- | `purchase.disputed` | `platform` rail, and `steam` chargebacks | handle disputes. A lost chargeback takes back up to the purchase's coins from the available balance, never below zero. On a lost Platform Commerce card sale or subscription charge dispute (`order_type`), `guarantee_covered: true` means INVO's chargeback guarantee covers it (a fraud chargeback): your share is not reversed or held and no dispute fee is passed to you. Otherwise a lost dispute costs you what a refund would: your share is reversed and INVO's card fee stays charged to you, on a Platform Commerce sale and on every subscription charge (`card_fee_charged_to_partner_usd`, and `partner_debited_usd` = share reversed plus that fee, since 2026-09-28). A subscription dispute also carries `processing_fee_usd`, which reads `"0.00"`. Coin purchase disputes carry none of these keys: a lost one takes back the player's coins, not your share. A Steam chargeback carries the same keys as a lost card dispute with `payment_intent_id`, `charge_id` and `dispute_id` `null`, plus `rail: "steam"` and `steam_transid`. A card dispute close also carries `dispute_fee_usd` (string decimal, `"0.00"` when INVO bears the fee, `null` when undecided) and `dispute_fee_charged_to_partner` (boolean or `null`); from November 8, 2026 the dispute fee on an Open-tier card sale is passed through to you at cost. **If you revoke on `purchase.refunded`, handle this too:** a Steam chargeback no longer arrives as `purchase.refunded` |
2716
+ | `purchase.disputed` | `platform` rail, and `steam` chargebacks | handle disputes. A lost chargeback takes back up to the purchase's coins from the available balance, never below zero. On a lost Platform Commerce card sale or subscription charge dispute (`order_type`), `guarantee_covered: true` means INVO's chargeback guarantee covers it (a fraud chargeback): your share is not reversed or held and no dispute fee is passed to you. Otherwise a lost dispute costs you what a refund would: your share is reversed and INVO's card fee stays charged to you, on a Platform Commerce sale and on every subscription charge (`card_fee_charged_to_partner_usd`, and `partner_debited_usd` = share reversed plus that fee, since 2026-09-28). A subscription dispute also carries `processing_fee_usd`, which reads `"0.00"`. Coin purchase disputes carry none of these keys: a lost one takes back the coins the player still holds and, since 2026-10-20, charges you for coins already spent at the price paid (`spent_coins_charged_usd` on the close, `"0.00"` when none). A Steam chargeback carries the same keys as a lost card dispute with `payment_intent_id`, `charge_id` and `dispute_id` `null`, plus `rail: "steam"` and `steam_transid`. A card dispute close also carries `dispute_fee_usd` (string decimal, `"0.00"` when INVO bears the fee, `null` when undecided) and `dispute_fee_charged_to_partner` (boolean or `null`); from November 8, 2026 the dispute fee on an Open-tier card sale is passed through to you at cost. **If you revoke on `purchase.refunded`, handle this too:** a Steam chargeback no longer arrives as `purchase.refunded` |
2713
2717
  | `purchase.refunded` | `game` / `steam` rails | handle refunds. Only coins the player still has from that purchase are taken back, never below zero. A Steam partial refund carries `fully_refunded: false` |
2714
2718
  | `item.purchased` | every item purchase | **grant the in-game item** (payload includes `transaction_id, order_id, player_email, identity_id, item_id, item_name, item_quantity, unit_price, total_price, currency_name, new_balance, fee_breakdown`) |
2715
2719
  | `platform_commerce.purchased` | every Platform Commerce purchase (balance immediately; **card after payment settles**) | **fulfill the ecommerce order** — never on the browser confirm (payload: `transaction_id, order_id, funding_source, player_email, identity_id, item_id, item_name, item_quantity, total_price`; + `unit_price, currency_name, new_balance` on balance; `total_price_usd` on card; `fee_breakdown`) |
@@ -2813,7 +2817,8 @@ Helpers:
2813
2817
  | `.isAlreadyRefunded` | Platform Commerce refund of an already-refunded order (409) — treat as already done |
2814
2818
  | `.isQuoteStale` + `.expectedTotalUsd` | `purchaseCurrency` with an `acknowledgedTotalUsd` below the total INVO would charge now (409); nothing charged: quote again. A higher total is accepted and the true total charged |
2815
2819
  | `.isAmountBelowFee` | deprecated: `AMOUNT_BELOW_FEE` is no longer returned (the partner pays the card fee) |
2816
- | `.retryAfter` | seconds to back off on a 429 throttle |
2820
+ | `.retryAfter` | seconds to back off on a 429 throttle: the body's `retry_after`, else the `Retry-After` header |
2821
+ | `.isRateLimited` | a 429: `.code` `RATE_LIMITED` on every rate-limit refusal since 2026-10-20 (a few endpoints send their own throttle code); wait `.retryAfter` seconds and send the same request again |
2817
2822
  | `.isEnrollmentAuthorizationRequired` | first-enrollment needs the OTP grant → `enrollmentBegin`/`enrollmentVerify` |
2818
2823
  | `.isEnrollmentProofRequired` | another method exists → prove it via `linkDevice` |
2819
2824
  | `.isPhoneShareApprovalRequired` | phone needs owner approval — at register/mint **or** at claim/`confirmReceipt*` (contested receiver phone) → show `.message` (+ `.phoneShareLast4`), retry the same call after approval |
@@ -2867,7 +2872,7 @@ try {
2867
2872
  | `iteratePlayerActivity({ playerEmail, types?, pageSize? })` | async iterator over every `PlayerActivityEntry`, following `nextCursor` |
2868
2873
  | `getItemOrderDetails({ orderId? \| transactionId? \| clientRequestId? })` | `{ order, financialSummary, statusTimeline, raw }` |
2869
2874
  | `platformCommerce.purchase(input)` | `{ status, fundingSource, orderId?, transactionId?, newBalance?, financialBreakdown?, sessionId?, checkoutUrl?, expiresAt?, amountUsd?, idempotentReplay?, raw }` — **ecommerce** (platform tenant); `balance` settles now, `card` returns a hosted-checkout `checkoutUrl` |
2870
- | `platformCommerce.getStatus(orderId)` | `{ orderId, status, gameCurrencyAmount?, usdAmount?, paymentMethod?, createdAt?, receiptNumber?, receiptUrl?, raw }` |
2875
+ | `platformCommerce.getStatus(orderId)` | `{ orderId, status, gameCurrencyAmount?, usdAmount?, paymentMethod?, createdAt?, receiptNumber?, receiptUrl?, invoFeeUsd?, partnerShareUsd?, raw }` |
2871
2876
  | `platformCommerce.getPurchaseHistory({ playerEmail, limit?, cursor? })` | `{ playerEmail, gameId, purchases, limit, hasMore, nextCursor, raw }`; each purchase is what `getStatus` returns, newest first |
2872
2877
  | `platformCommerce.iteratePurchaseHistory({ playerEmail, pageSize? })` | async iterator over every purchase, following `nextCursor` |
2873
2878
  | `platformCommerce.refund({ orderId? \| clientRequestId?, reason?, refundRemaining?, confirmAdditionalRefund? })` | `{ status, orderId?, fundingSource?, refundedAmount?, amountUnit?, feeRetained?, partialRefund?, adopted?, refundedTotalUsd?, chargeTotalUsd?, remainingUsd?, cardFeeChargedToPartnerUsd?, partnerDebitedUsd?, raw }`; pass **exactly one** id; INVO keeps its fee (on the card leg it stays charged to you: `cardFeeChargedToPartnerUsd`, `partnerDebitedUsd`); `partialRefund`, `refundedTotalUsd`, `chargeTotalUsd`, `remainingUsd` only on a card sale refunded in parts; `adopted` whenever the call recorded an existing refund (a full one included) |
@@ -1,4 +1,4 @@
1
- import { InvoError, assertSecureBaseUrl, Http, toPurchaseStatusResult, toPhoneChangeApprovalsResult, phoneChangeSignalMessage, toApprovePhoneChangeResult, toDestinationsResult, toLoyaltyCardsResult, toLoyaltyVaultResult, toRedeemRewardResult, toRewardsPageLink, buildGameEventBody, toReportGameEventResult } from './chunk-TCT2QSVB.js';
1
+ import { InvoError, assertSecureBaseUrl, Http, toPurchaseStatusResult, toPhoneChangeApprovalsResult, phoneChangeSignalMessage, toApprovePhoneChangeResult, toDestinationsResult, toLoyaltyCardsResult, toLoyaltyVaultResult, toRedeemRewardResult, toRewardsPageLink, buildGameEventBody, toReportGameEventResult } from './chunk-LMN2V4YT.js';
2
2
 
3
3
  // src/shared/webauthn.ts
4
4
  function malformedOptions(field) {
@@ -1586,5 +1586,5 @@ var InvoClient = class {
1586
1586
  };
1587
1587
 
1588
1588
  export { CheckoutClient, InvoClient, PlatformCommerceClient };
1589
- //# sourceMappingURL=chunk-7O5JT3LK.js.map
1590
- //# sourceMappingURL=chunk-7O5JT3LK.js.map
1589
+ //# sourceMappingURL=chunk-5T75PCZN.js.map
1590
+ //# sourceMappingURL=chunk-5T75PCZN.js.map
@@ -0,0 +1,6 @@
1
+ // src/version.ts
2
+ var SDK_VERSION = "3.31.0";
3
+
4
+ export { SDK_VERSION };
5
+ //# sourceMappingURL=chunk-CI7PHE6L.js.map
6
+ //# sourceMappingURL=chunk-CI7PHE6L.js.map
@@ -11,6 +11,7 @@ var InvoError = class _InvoError extends Error {
11
11
  this.status = args.status;
12
12
  this.body = args.body ?? null;
13
13
  this.requestId = args.requestId;
14
+ this.retryAfterHeader = args.retryAfterHeader;
14
15
  Object.setPrototypeOf(this, _InvoError.prototype);
15
16
  }
16
17
  /** True if this is the "recipient isn't passkey-enrolled, fall back to claim code" signal. */
@@ -1098,11 +1099,27 @@ var InvoError = class _InvoError extends Error {
1098
1099
  get isRewardExpired() {
1099
1100
  return this.code === "vault_entry_expired";
1100
1101
  }
1101
- /** Seconds to wait before retrying, when the backend throttled the call (429 `retry_after`). */
1102
+ /**
1103
+ * Seconds to wait before retrying, when the backend throttled the call: the body's
1104
+ * `retry_after`, else the `Retry-After` header (seconds). Every INVO rate-limit 429 carries
1105
+ * both (since 2026-10-20). `undefined` when neither is a usable number of seconds.
1106
+ */
1102
1107
  get retryAfter() {
1103
1108
  const v = this.bodyObject()["retry_after"];
1104
1109
  const n = typeof v === "string" ? v.trim() === "" ? NaN : Number(v) : v;
1105
- return typeof n === "number" && Number.isFinite(n) && n >= 0 ? n : void 0;
1110
+ if (typeof n === "number" && Number.isFinite(n) && n >= 0) return n;
1111
+ const h = this.retryAfterHeader?.trim();
1112
+ if (h && /^\d+(\.\d+)?$/.test(h)) return Number(h);
1113
+ return void 0;
1114
+ }
1115
+ /**
1116
+ * True when INVO refused the call for going over a rate limit (additive, 3.31.0): `error_code`
1117
+ * `"RATE_LIMITED"` (every rate-limit 429 carries it since 2026-10-20), or any other 429 (an
1118
+ * older release, or an endpoint with its own throttle body). Wait {@link retryAfter} seconds
1119
+ * and send the same request again. Branch on this, not on the message.
1120
+ */
1121
+ get isRateLimited() {
1122
+ return this.code === "RATE_LIMITED" || this.code === "rate_limited" || this.status === 429;
1106
1123
  }
1107
1124
  /** `body` as a plain object, or `{}` if it's a string/number/null (non-JSON responses).
1108
1125
  * The `in` operator throws on primitives, so callers must go through this. */
@@ -1110,7 +1127,7 @@ var InvoError = class _InvoError extends Error {
1110
1127
  return this.body && typeof this.body === "object" ? this.body : {};
1111
1128
  }
1112
1129
  };
1113
- function errorFromResponse(status, body, requestId) {
1130
+ function errorFromResponse(status, body, requestId, retryAfterHeader) {
1114
1131
  let message = `INVO request failed (HTTP ${status})`;
1115
1132
  let code;
1116
1133
  let rawCode;
@@ -1132,7 +1149,7 @@ function errorFromResponse(status, body, requestId) {
1132
1149
  } else if (typeof body === "string" && body.trim()) {
1133
1150
  message = body;
1134
1151
  }
1135
- return new InvoError({ message, code, rawCode, publicCode, status, body, requestId });
1152
+ return new InvoError({ message, code, rawCode, publicCode, status, body, requestId, retryAfterHeader });
1136
1153
  }
1137
1154
 
1138
1155
  // src/shared/http.ts
@@ -1266,7 +1283,7 @@ var _Http = class _Http {
1266
1283
  requestId
1267
1284
  });
1268
1285
  if (!res.ok) {
1269
- const err = errorFromResponse(res.status, parsed, requestId);
1286
+ const err = errorFromResponse(res.status, parsed, requestId, pickRetryAfterHeader(res.headers));
1270
1287
  let wait;
1271
1288
  if (idempotent && attempt < this.maxRetries && _Http.RETRIABLE_STATUS.has(res.status)) {
1272
1289
  if (res.status === 429) {
@@ -1324,6 +1341,10 @@ function pickRequestId(headers) {
1324
1341
  if (!headers || typeof headers.get !== "function") return void 0;
1325
1342
  return headers.get("x-invo-request-id") ?? headers.get("x-request-id") ?? void 0;
1326
1343
  }
1344
+ function pickRetryAfterHeader(headers) {
1345
+ if (!headers || typeof headers.get !== "function") return void 0;
1346
+ return headers.get("retry-after") ?? void 0;
1347
+ }
1327
1348
  function retryAfterMs(parsed, headers) {
1328
1349
  if (parsed && typeof parsed === "object") {
1329
1350
  const v = parsed["retry_after"];
@@ -1713,5 +1734,5 @@ function toApprovePhoneChangeResult(raw, changeRequestId) {
1713
1734
  }
1714
1735
 
1715
1736
  export { Http, InvoError, assertSecureBaseUrl, buildGameEventBody, creditFields, isPurchaseCredited, isPurchaseExpired, isPurchaseRefunded, isPurchaseRefused, newEventId, nothingWasCharged, phoneChangeSignalMessage, receiptFields, toApprovePhoneChangeResult, toDestinationsResult, toLoyaltyCardsResult, toLoyaltyVaultResult, toPhoneChangeApprovalsResult, toPhoneChangeRequest, toPurchaseStatusResult, toRedeemRewardResult, toReportGameEventResult, toRequestPhoneChangeResult, toRewardsPageLink };
1716
- //# sourceMappingURL=chunk-TCT2QSVB.js.map
1717
- //# sourceMappingURL=chunk-TCT2QSVB.js.map
1737
+ //# sourceMappingURL=chunk-LMN2V4YT.js.map
1738
+ //# sourceMappingURL=chunk-LMN2V4YT.js.map
@@ -1,5 +1,5 @@
1
- import { SDK_VERSION } from './chunk-CSIEPFCV.js';
2
- import { InvoError, assertSecureBaseUrl, Http, toRequestPhoneChangeResult, toPhoneChangeRequest, toPurchaseStatusResult, receiptFields, creditFields, toLoyaltyCardsResult, buildGameEventBody, toReportGameEventResult, toDestinationsResult } from './chunk-TCT2QSVB.js';
1
+ import { SDK_VERSION } from './chunk-CI7PHE6L.js';
2
+ import { InvoError, assertSecureBaseUrl, Http, toRequestPhoneChangeResult, toPhoneChangeRequest, toPurchaseStatusResult, receiptFields, creditFields, toLoyaltyCardsResult, buildGameEventBody, toReportGameEventResult, toDestinationsResult } from './chunk-LMN2V4YT.js';
3
3
  import { createHmac, timingSafeEqual } from 'crypto';
4
4
 
5
5
  // src/payouts.ts
@@ -701,9 +701,17 @@ function toPlatformOrderStatus(raw, fallbackOrderId) {
701
701
  paymentMethod: raw["payment_method"],
702
702
  createdAt: raw["created_at"],
703
703
  ...receiptFields(raw),
704
+ ...feeSplitFields(raw),
704
705
  raw
705
706
  };
706
707
  }
708
+ function feeSplitFields(raw) {
709
+ const out = {};
710
+ const pick = (v) => v === null ? null : typeof v === "string" ? v : typeof v === "number" && Number.isFinite(v) ? v.toFixed(2) : null;
711
+ if ("invo_fee_usd" in raw) out.invoFeeUsd = pick(raw["invo_fee_usd"]);
712
+ if ("partner_share_usd" in raw) out.partnerShareUsd = pick(raw["partner_share_usd"]);
713
+ return out;
714
+ }
707
715
  function nextCursorOf(raw) {
708
716
  const c = raw["next_cursor"];
709
717
  return typeof c === "string" && c ? c : null;
@@ -918,7 +926,9 @@ var PlatformCommerceServer = class {
918
926
  * Send the buyer to `checkoutUrl` — INVO's hosted page owns the card form, wallets,
919
927
  * billing address, and 3-D Secure (there is NO billing address in this request, and no
920
928
  * client payment code to write; optionally embed via
921
- * `InvoClient.platformCommerce.mountCheckout`). `totalPrice` is USD, at least $0.50;
929
+ * `InvoClient.platformCommerce.mountCheckout`). The page shows the INVO logo by
930
+ * default, or the game's own logo when one is set in the INVO console (Game settings,
931
+ * Checkout branding). `totalPrice` is USD, at least $0.50;
922
932
  * the maximum is an INVO setting ($100,000.00 by default) and is enforced on the
923
933
  * request, not here, so read the live figure off `ABOVE_CARD_MAXIMUM` rather than
924
934
  * pinning one.
@@ -1021,7 +1031,8 @@ var PlatformCommerceServer = class {
1021
1031
  };
1022
1032
  }
1023
1033
  /** Poll an order's status: `completed` (balance immediately; card after the webhook),
1024
- * `pending_payment` (card awaiting confirmation), or `refunded`. */
1034
+ * `pending_payment` (card awaiting confirmation), or `refunded`. Once the sale has settled,
1035
+ * `invoFeeUsd` / `partnerShareUsd` say what INVO kept and what you earned (additive). */
1025
1036
  async getStatus(orderId, opts) {
1026
1037
  if (orderId == null || String(orderId).trim() === "") {
1027
1038
  throw invalidInput2("orderId", orderId, "is required");
@@ -1967,7 +1978,9 @@ var CardsServer = class {
1967
1978
  * is never re-created or renamed by this call; `playerName` / `playerPhone` are used
1968
1979
  * only when the member is new. Send the member to `result.cardSetupUrl` top-level (do
1969
1980
  * not frame it). The page says in words that no money moves, saves the card, and then
1970
- * redirects to `successUrl` (or shows "Card saved" when you gave none). The saved card
1981
+ * redirects to `successUrl` (or shows "Card saved" when you gave none). It shows the
1982
+ * INVO logo by default, or the game's own logo when one is set in the INVO console
1983
+ * (Game settings, Checkout branding). The saved card
1971
1984
  * appears in {@link list} immediately, carries the off-session consent a subscription
1972
1985
  * needs, and is indistinguishable from one saved any other way. There is no event for
1973
1986
  * a saved card; `cards.list` is the signal.
@@ -2493,7 +2506,9 @@ var InvoServer = class {
2493
2506
  /** Create a hosted checkout session (the recommended purchase path). Open the
2494
2507
  * returned checkoutUrl in a WebView/redirect or an iframe; the INVO-hosted page
2495
2508
  * handles cards, saved cards, and 3-D Secure. Crediting is server-side via the
2496
- * purchase.completed webhook. */
2509
+ * purchase.completed webhook. The page shows the INVO logo by default, or the game's
2510
+ * own logo when one is set in the INVO console (Game settings, Checkout branding);
2511
+ * there is no SDK call to set it. */
2497
2512
  async createCheckout(input, opts) {
2498
2513
  if (typeof input.playerEmail !== "string" || !input.playerEmail.trim()) {
2499
2514
  throw invalidInput2("playerEmail", input.playerEmail, "is required");
@@ -3787,5 +3802,5 @@ var InvoServer = class {
3787
3802
  };
3788
3803
 
3789
3804
  export { CardsServer, DEMO_KEY_PREFIX, EnvironmentUnknownError, InvoServer, PRODUCTION_BASE_URL, PayoutsServer, PlatformCommerceServer, SANDBOX_BASE_URL, SandboxServer, SandboxSubscriptionsServer, SubscriptionsServer, baseUrlForKey, createWebhookHandler, isDemoKey, isRefundPendingApproval, resolveEnvironment, verifyInvoSignature, verifyWebhook, verifyWebhookAsync };
3790
- //# sourceMappingURL=chunk-JJPAUW2S.js.map
3791
- //# sourceMappingURL=chunk-JJPAUW2S.js.map
3805
+ //# sourceMappingURL=chunk-UW66W2N6.js.map
3806
+ //# sourceMappingURL=chunk-UW66W2N6.js.map
@@ -107,6 +107,7 @@ var InvoError = class _InvoError extends Error {
107
107
  this.status = args.status;
108
108
  this.body = args.body ?? null;
109
109
  this.requestId = args.requestId;
110
+ this.retryAfterHeader = args.retryAfterHeader;
110
111
  Object.setPrototypeOf(this, _InvoError.prototype);
111
112
  }
112
113
  /** True if this is the "recipient isn't passkey-enrolled, fall back to claim code" signal. */
@@ -1194,11 +1195,27 @@ var InvoError = class _InvoError extends Error {
1194
1195
  get isRewardExpired() {
1195
1196
  return this.code === "vault_entry_expired";
1196
1197
  }
1197
- /** Seconds to wait before retrying, when the backend throttled the call (429 `retry_after`). */
1198
+ /**
1199
+ * Seconds to wait before retrying, when the backend throttled the call: the body's
1200
+ * `retry_after`, else the `Retry-After` header (seconds). Every INVO rate-limit 429 carries
1201
+ * both (since 2026-10-20). `undefined` when neither is a usable number of seconds.
1202
+ */
1198
1203
  get retryAfter() {
1199
1204
  const v = this.bodyObject()["retry_after"];
1200
1205
  const n = typeof v === "string" ? v.trim() === "" ? NaN : Number(v) : v;
1201
- return typeof n === "number" && Number.isFinite(n) && n >= 0 ? n : void 0;
1206
+ if (typeof n === "number" && Number.isFinite(n) && n >= 0) return n;
1207
+ const h = this.retryAfterHeader?.trim();
1208
+ if (h && /^\d+(\.\d+)?$/.test(h)) return Number(h);
1209
+ return void 0;
1210
+ }
1211
+ /**
1212
+ * True when INVO refused the call for going over a rate limit (additive, 3.31.0): `error_code`
1213
+ * `"RATE_LIMITED"` (every rate-limit 429 carries it since 2026-10-20), or any other 429 (an
1214
+ * older release, or an endpoint with its own throttle body). Wait {@link retryAfter} seconds
1215
+ * and send the same request again. Branch on this, not on the message.
1216
+ */
1217
+ get isRateLimited() {
1218
+ return this.code === "RATE_LIMITED" || this.code === "rate_limited" || this.status === 429;
1202
1219
  }
1203
1220
  /** `body` as a plain object, or `{}` if it's a string/number/null (non-JSON responses).
1204
1221
  * The `in` operator throws on primitives, so callers must go through this. */
@@ -1206,7 +1223,7 @@ var InvoError = class _InvoError extends Error {
1206
1223
  return this.body && typeof this.body === "object" ? this.body : {};
1207
1224
  }
1208
1225
  };
1209
- function errorFromResponse(status, body, requestId) {
1226
+ function errorFromResponse(status, body, requestId, retryAfterHeader) {
1210
1227
  let message = `INVO request failed (HTTP ${status})`;
1211
1228
  let code;
1212
1229
  let rawCode;
@@ -1228,7 +1245,7 @@ function errorFromResponse(status, body, requestId) {
1228
1245
  } else if (typeof body === "string" && body.trim()) {
1229
1246
  message = body;
1230
1247
  }
1231
- return new InvoError({ message, code, rawCode, publicCode, status, body, requestId });
1248
+ return new InvoError({ message, code, rawCode, publicCode, status, body, requestId, retryAfterHeader });
1232
1249
  }
1233
1250
 
1234
1251
  // src/shared/http.ts
@@ -1362,7 +1379,7 @@ var _Http = class _Http {
1362
1379
  requestId
1363
1380
  });
1364
1381
  if (!res.ok) {
1365
- const err = errorFromResponse(res.status, parsed, requestId);
1382
+ const err = errorFromResponse(res.status, parsed, requestId, pickRetryAfterHeader(res.headers));
1366
1383
  let wait;
1367
1384
  if (idempotent && attempt < this.maxRetries && _Http.RETRIABLE_STATUS.has(res.status)) {
1368
1385
  if (res.status === 429) {
@@ -1420,6 +1437,10 @@ function pickRequestId(headers) {
1420
1437
  if (!headers || typeof headers.get !== "function") return void 0;
1421
1438
  return headers.get("x-invo-request-id") ?? headers.get("x-request-id") ?? void 0;
1422
1439
  }
1440
+ function pickRetryAfterHeader(headers) {
1441
+ if (!headers || typeof headers.get !== "function") return void 0;
1442
+ return headers.get("retry-after") ?? void 0;
1443
+ }
1423
1444
  function retryAfterMs(parsed, headers) {
1424
1445
  if (parsed && typeof parsed === "object") {
1425
1446
  const v = parsed["retry_after"];
@@ -1711,7 +1732,7 @@ function toPhoneChangeRequest(raw) {
1711
1732
  }
1712
1733
 
1713
1734
  // src/version.ts
1714
- var SDK_VERSION = "3.30.3";
1735
+ var SDK_VERSION = "3.31.0";
1715
1736
 
1716
1737
  // src/payouts.ts
1717
1738
  var AMOUNT = /^\d+(\.\d{1,2})?$/;
@@ -2265,9 +2286,17 @@ function toPlatformOrderStatus(raw, fallbackOrderId) {
2265
2286
  paymentMethod: raw["payment_method"],
2266
2287
  createdAt: raw["created_at"],
2267
2288
  ...receiptFields(raw),
2289
+ ...feeSplitFields(raw),
2268
2290
  raw
2269
2291
  };
2270
2292
  }
2293
+ function feeSplitFields(raw) {
2294
+ const out = {};
2295
+ const pick = (v) => v === null ? null : typeof v === "string" ? v : typeof v === "number" && Number.isFinite(v) ? v.toFixed(2) : null;
2296
+ if ("invo_fee_usd" in raw) out.invoFeeUsd = pick(raw["invo_fee_usd"]);
2297
+ if ("partner_share_usd" in raw) out.partnerShareUsd = pick(raw["partner_share_usd"]);
2298
+ return out;
2299
+ }
2271
2300
  function nextCursorOf(raw) {
2272
2301
  const c = raw["next_cursor"];
2273
2302
  return typeof c === "string" && c ? c : null;
@@ -2482,7 +2511,9 @@ var PlatformCommerceServer = class {
2482
2511
  * Send the buyer to `checkoutUrl` — INVO's hosted page owns the card form, wallets,
2483
2512
  * billing address, and 3-D Secure (there is NO billing address in this request, and no
2484
2513
  * client payment code to write; optionally embed via
2485
- * `InvoClient.platformCommerce.mountCheckout`). `totalPrice` is USD, at least $0.50;
2514
+ * `InvoClient.platformCommerce.mountCheckout`). The page shows the INVO logo by
2515
+ * default, or the game's own logo when one is set in the INVO console (Game settings,
2516
+ * Checkout branding). `totalPrice` is USD, at least $0.50;
2486
2517
  * the maximum is an INVO setting ($100,000.00 by default) and is enforced on the
2487
2518
  * request, not here, so read the live figure off `ABOVE_CARD_MAXIMUM` rather than
2488
2519
  * pinning one.
@@ -2585,7 +2616,8 @@ var PlatformCommerceServer = class {
2585
2616
  };
2586
2617
  }
2587
2618
  /** Poll an order's status: `completed` (balance immediately; card after the webhook),
2588
- * `pending_payment` (card awaiting confirmation), or `refunded`. */
2619
+ * `pending_payment` (card awaiting confirmation), or `refunded`. Once the sale has settled,
2620
+ * `invoFeeUsd` / `partnerShareUsd` say what INVO kept and what you earned (additive). */
2589
2621
  async getStatus(orderId, opts) {
2590
2622
  if (orderId == null || String(orderId).trim() === "") {
2591
2623
  throw invalidInput2("orderId", orderId, "is required");
@@ -3531,7 +3563,9 @@ var CardsServer = class {
3531
3563
  * is never re-created or renamed by this call; `playerName` / `playerPhone` are used
3532
3564
  * only when the member is new. Send the member to `result.cardSetupUrl` top-level (do
3533
3565
  * not frame it). The page says in words that no money moves, saves the card, and then
3534
- * redirects to `successUrl` (or shows "Card saved" when you gave none). The saved card
3566
+ * redirects to `successUrl` (or shows "Card saved" when you gave none). It shows the
3567
+ * INVO logo by default, or the game's own logo when one is set in the INVO console
3568
+ * (Game settings, Checkout branding). The saved card
3535
3569
  * appears in {@link list} immediately, carries the off-session consent a subscription
3536
3570
  * needs, and is indistinguishable from one saved any other way. There is no event for
3537
3571
  * a saved card; `cards.list` is the signal.
@@ -4057,7 +4091,9 @@ var InvoServer = class {
4057
4091
  /** Create a hosted checkout session (the recommended purchase path). Open the
4058
4092
  * returned checkoutUrl in a WebView/redirect or an iframe; the INVO-hosted page
4059
4093
  * handles cards, saved cards, and 3-D Secure. Crediting is server-side via the
4060
- * purchase.completed webhook. */
4094
+ * purchase.completed webhook. The page shows the INVO logo by default, or the game's
4095
+ * own logo when one is set in the INVO console (Game settings, Checkout branding);
4096
+ * there is no SDK call to set it. */
4061
4097
  async createCheckout(input, opts) {
4062
4098
  if (typeof input.playerEmail !== "string" || !input.playerEmail.trim()) {
4063
4099
  throw invalidInput2("playerEmail", input.playerEmail, "is required");
@@ -1,9 +1,9 @@
1
- import { I as InvoServer, a as InvoEnvironment } from './server-B5BTXYXy.cjs';
2
- export { D as DEMO_KEY_PREFIX, E as EnvironmentUnknownError, P as PRODUCTION_BASE_URL, S as SANDBOX_BASE_URL, b as baseUrlForKey, i as isDemoKey, r as resolveEnvironment, v as verifyInvoSignature } from './server-B5BTXYXy.cjs';
1
+ import { I as InvoServer, a as InvoEnvironment } from './server-D9bKfiY6.cjs';
2
+ export { D as DEMO_KEY_PREFIX, E as EnvironmentUnknownError, P as PRODUCTION_BASE_URL, S as SANDBOX_BASE_URL, b as baseUrlForKey, i as isDemoKey, r as resolveEnvironment, v as verifyInvoSignature } from './server-D9bKfiY6.cjs';
3
3
  import { G as GameCurrencyKind, a as GamePurchaseStatus, b as GameEconomyConfig } from './types-jUxfYjiD.cjs';
4
4
  export { c as GameCatalog, d as GameCatalogItem, e as GameCheckout, f as GameCurrencyBalance, g as GameErrorBody, h as GameItemPurchase, i as GamePlayer, j as GamePremiumPack, k as GamePurchase, l as GameSession, m as GameTransferInput, n as GameTransferKind, o as GameTransferStart, p as GameTransferStatus, q as GameWallet } from './types-jUxfYjiD.cjs';
5
- export { I as InvoError } from './types-a9zeN1UE.cjs';
6
- export { S as SDK_VERSION } from './version-lfflokBD.cjs';
5
+ export { I as InvoError } from './types-CBanzneD.cjs';
6
+ export { S as SDK_VERSION } from './version-B4Eincjj.cjs';
7
7
  import './loyalty-events-CmDw2ZoR.cjs';
8
8
 
9
9
  interface StoredPlayer {
@@ -1,9 +1,9 @@
1
- import { I as InvoServer, a as InvoEnvironment } from './server-C9gIZ2Wx.js';
2
- export { D as DEMO_KEY_PREFIX, E as EnvironmentUnknownError, P as PRODUCTION_BASE_URL, S as SANDBOX_BASE_URL, b as baseUrlForKey, i as isDemoKey, r as resolveEnvironment, v as verifyInvoSignature } from './server-C9gIZ2Wx.js';
1
+ import { I as InvoServer, a as InvoEnvironment } from './server-CaALJEML.js';
2
+ export { D as DEMO_KEY_PREFIX, E as EnvironmentUnknownError, P as PRODUCTION_BASE_URL, S as SANDBOX_BASE_URL, b as baseUrlForKey, i as isDemoKey, r as resolveEnvironment, v as verifyInvoSignature } from './server-CaALJEML.js';
3
3
  import { G as GameCurrencyKind, a as GamePurchaseStatus, b as GameEconomyConfig } from './types-jUxfYjiD.js';
4
4
  export { c as GameCatalog, d as GameCatalogItem, e as GameCheckout, f as GameCurrencyBalance, g as GameErrorBody, h as GameItemPurchase, i as GamePlayer, j as GamePremiumPack, k as GamePurchase, l as GameSession, m as GameTransferInput, n as GameTransferKind, o as GameTransferStart, p as GameTransferStatus, q as GameWallet } from './types-jUxfYjiD.js';
5
- export { I as InvoError } from './types-a9zeN1UE.js';
6
- export { S as SDK_VERSION } from './version-lfflokBD.js';
5
+ export { I as InvoError } from './types-CBanzneD.js';
6
+ export { S as SDK_VERSION } from './version-B4Eincjj.js';
7
7
  import './loyalty-events-CmDw2ZoR.js';
8
8
 
9
9
  interface StoredPlayer {
@@ -1,8 +1,8 @@
1
- import { isDemoKey, SANDBOX_BASE_URL, PRODUCTION_BASE_URL, InvoServer, resolveEnvironment, verifyWebhook } from './chunk-JJPAUW2S.js';
2
- export { DEMO_KEY_PREFIX, EnvironmentUnknownError, InvoServer, PRODUCTION_BASE_URL, SANDBOX_BASE_URL, baseUrlForKey, isDemoKey, resolveEnvironment, verifyInvoSignature } from './chunk-JJPAUW2S.js';
3
- export { SDK_VERSION } from './chunk-CSIEPFCV.js';
4
- import { InvoError } from './chunk-TCT2QSVB.js';
5
- export { InvoError } from './chunk-TCT2QSVB.js';
1
+ import { isDemoKey, SANDBOX_BASE_URL, PRODUCTION_BASE_URL, InvoServer, resolveEnvironment, verifyWebhook } from './chunk-UW66W2N6.js';
2
+ export { DEMO_KEY_PREFIX, EnvironmentUnknownError, InvoServer, PRODUCTION_BASE_URL, SANDBOX_BASE_URL, baseUrlForKey, isDemoKey, resolveEnvironment, verifyInvoSignature } from './chunk-UW66W2N6.js';
3
+ export { SDK_VERSION } from './chunk-CI7PHE6L.js';
4
+ import { InvoError } from './chunk-LMN2V4YT.js';
5
+ export { InvoError } from './chunk-LMN2V4YT.js';
6
6
  import { createHash, randomBytes } from 'crypto';
7
7
  import { promises, readFileSync, mkdirSync, writeFileSync } from 'fs';
8
8
  import * as path from 'path';
package/dist/game.cjs CHANGED
@@ -13,6 +13,7 @@ var InvoError = class _InvoError extends Error {
13
13
  this.status = args.status;
14
14
  this.body = args.body ?? null;
15
15
  this.requestId = args.requestId;
16
+ this.retryAfterHeader = args.retryAfterHeader;
16
17
  Object.setPrototypeOf(this, _InvoError.prototype);
17
18
  }
18
19
  /** True if this is the "recipient isn't passkey-enrolled, fall back to claim code" signal. */
@@ -1100,11 +1101,27 @@ var InvoError = class _InvoError extends Error {
1100
1101
  get isRewardExpired() {
1101
1102
  return this.code === "vault_entry_expired";
1102
1103
  }
1103
- /** Seconds to wait before retrying, when the backend throttled the call (429 `retry_after`). */
1104
+ /**
1105
+ * Seconds to wait before retrying, when the backend throttled the call: the body's
1106
+ * `retry_after`, else the `Retry-After` header (seconds). Every INVO rate-limit 429 carries
1107
+ * both (since 2026-10-20). `undefined` when neither is a usable number of seconds.
1108
+ */
1104
1109
  get retryAfter() {
1105
1110
  const v = this.bodyObject()["retry_after"];
1106
1111
  const n = typeof v === "string" ? v.trim() === "" ? NaN : Number(v) : v;
1107
- return typeof n === "number" && Number.isFinite(n) && n >= 0 ? n : void 0;
1112
+ if (typeof n === "number" && Number.isFinite(n) && n >= 0) return n;
1113
+ const h = this.retryAfterHeader?.trim();
1114
+ if (h && /^\d+(\.\d+)?$/.test(h)) return Number(h);
1115
+ return void 0;
1116
+ }
1117
+ /**
1118
+ * True when INVO refused the call for going over a rate limit (additive, 3.31.0): `error_code`
1119
+ * `"RATE_LIMITED"` (every rate-limit 429 carries it since 2026-10-20), or any other 429 (an
1120
+ * older release, or an endpoint with its own throttle body). Wait {@link retryAfter} seconds
1121
+ * and send the same request again. Branch on this, not on the message.
1122
+ */
1123
+ get isRateLimited() {
1124
+ return this.code === "RATE_LIMITED" || this.code === "rate_limited" || this.status === 429;
1108
1125
  }
1109
1126
  /** `body` as a plain object, or `{}` if it's a string/number/null (non-JSON responses).
1110
1127
  * The `in` operator throws on primitives, so callers must go through this. */
@@ -1112,7 +1129,7 @@ var InvoError = class _InvoError extends Error {
1112
1129
  return this.body && typeof this.body === "object" ? this.body : {};
1113
1130
  }
1114
1131
  };
1115
- function errorFromResponse(status, body, requestId) {
1132
+ function errorFromResponse(status, body, requestId, retryAfterHeader) {
1116
1133
  let message = `INVO request failed (HTTP ${status})`;
1117
1134
  let code;
1118
1135
  let rawCode;
@@ -1134,7 +1151,7 @@ function errorFromResponse(status, body, requestId) {
1134
1151
  } else if (typeof body === "string" && body.trim()) {
1135
1152
  message = body;
1136
1153
  }
1137
- return new InvoError({ message, code, rawCode, publicCode, status, body, requestId });
1154
+ return new InvoError({ message, code, rawCode, publicCode, status, body, requestId, retryAfterHeader });
1138
1155
  }
1139
1156
 
1140
1157
  // src/shared/loyalty-events.ts
@@ -1333,7 +1350,7 @@ var _Http = class _Http {
1333
1350
  requestId
1334
1351
  });
1335
1352
  if (!res.ok) {
1336
- const err = errorFromResponse(res.status, parsed, requestId);
1353
+ const err = errorFromResponse(res.status, parsed, requestId, pickRetryAfterHeader(res.headers));
1337
1354
  let wait;
1338
1355
  if (idempotent && attempt < this.maxRetries && _Http.RETRIABLE_STATUS.has(res.status)) {
1339
1356
  if (res.status === 429) {
@@ -1391,6 +1408,10 @@ function pickRequestId(headers) {
1391
1408
  if (!headers || typeof headers.get !== "function") return void 0;
1392
1409
  return headers.get("x-invo-request-id") ?? headers.get("x-request-id") ?? void 0;
1393
1410
  }
1411
+ function pickRetryAfterHeader(headers) {
1412
+ if (!headers || typeof headers.get !== "function") return void 0;
1413
+ return headers.get("retry-after") ?? void 0;
1414
+ }
1394
1415
  function retryAfterMs(parsed, headers) {
1395
1416
  if (parsed && typeof parsed === "object") {
1396
1417
  const v = parsed["retry_after"];
@@ -4833,7 +4854,7 @@ function mountInvoUI(container, economy, options = {}) {
4833
4854
  }
4834
4855
 
4835
4856
  // src/version.ts
4836
- var SDK_VERSION = "3.30.3";
4857
+ var SDK_VERSION = "3.31.0";
4837
4858
 
4838
4859
  exports.InvoGameEconomy = InvoGameEconomy;
4839
4860
  exports.InvoGameError = InvoGameError;