@invonetwork/web-sdk 3.14.2 → 3.16.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,17 @@
1
1
  # Changelog
2
2
 
3
+ ## 3.16.0
4
+
5
+ ### Minor Changes
6
+
7
+ - 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.
8
+
9
+ ## 3.15.0
10
+
11
+ ### Minor Changes
12
+
13
+ - 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.
14
+
3
15
  ## 3.14.2
4
16
 
5
17
  ### 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.14.2`, 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.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 charges are now **4% + $0.30** on Open and **5% + $0.50** on Merchant of Record, international card and currency conversion costs on subscriptions pass through at cost, chargeback handling by tier, 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)** (3.5% + $0.30): `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 to **7% + $0.30** (it is its own rate; item purchases stay at 10/90); **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.16.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.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 charges are now **4% + $0.30** on Open and **5% + $0.50** on Merchant of Record, international card and currency conversion costs on subscriptions pass through at cost, chargeback handling by tier, 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)** (3.5% + $0.30): `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 to **7% + $0.30** (it is its own rate; item purchases stay at 10/90); **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
@@ -354,6 +354,9 @@ const { checkoutUrl, sessionId, sessionToken, expiresAt, expiresInSeconds } = aw
354
354
  });
355
355
  // → send the browser to checkoutUrl. Token TTL is expiresInSeconds (~900s / 15 min).
356
356
  // sessionToken is the credential for the status read below (INVO's own session_token field).
357
+ // A checkout session SELLS GAME CURRENCY. metadata is opaque: it is echoed back, never read as
358
+ // an item. Sending item_id / item_name in it returns a `warnings` entry
359
+ // (code ITEM_METADATA_ON_CURRENCY_SESSION); to sell an item use platformCommerce.purchase.
357
360
  // Reloading the URL after a completed payment is idempotent — it shows an already-complete
358
361
  // success screen (no error), so you don't have to guard against a refresh.
359
362
  ```
@@ -688,6 +691,7 @@ const item = await server.purchaseItem({
688
691
 
689
692
  - **Grant the item off the `item.purchased` webhook**, not just this response. INVO debits currency and records the purchase; **your game owns the item catalog and grants the item.** The webhook fires atomically with the spend.
690
693
  - **Idempotent** on `clientRequestId` — a duplicate throws `409` (`err.isDuplicateRequest`).
694
+ - `totalPrice` is rounded to cents. A spend so small that INVO's fee would round to zero throws `400` (`err.isAmountBelowMinimum`).
691
695
  - **Insufficient balance** throws `400` (`err.isInsufficientBalance`; `required_amount` + `current_balance` on `err.body`).
692
696
  - **Throttled** calls throw `429` with `err.retryAfter` (seconds).
693
697
  - Client-side validation (missing fields, quantity outside `1..1000`, bad price, total ≠ unit×qty) throws `INVALID_INPUT` **before** any network call.
@@ -787,7 +791,7 @@ await server.platformCommerce.refund({ orderId, refundRemaining: true });
787
791
  - `err.isRefundNotCompleted` (502 `REFUND_NOT_COMPLETED`): the card refund failed, was canceled or still needs an action. Nothing was recorded; retry (a refund that was in fact created is recorded on the retry, never issued twice).
788
792
  - `platform_commerce.refunded` for a sale refunded in parts also carries `partial_refund`, `refunded_total_usd` and `charge_total_usd` (`refunded_amount` is that refund's own amount); a one-shot full refund sends none of them.
789
793
 
790
- - **Idempotency on `clientRequestId`:** a duplicate BALANCE purchase throws `409` (`err.isDuplicateRequest`); a duplicate CARD purchase **replays the same checkout session** (`r.idempotentReplay === true`, same URL — never a second charge), so a lost card-leg response is safely recovered by retrying with the *same* `clientRequestId`.
794
+ - **Idempotency on `clientRequestId`:** a duplicate BALANCE purchase throws `409` (`err.isDuplicateRequest`); a duplicate CARD purchase **replays the same checkout session** (`r.idempotentReplay === true`, same URL — never a second charge), so a lost card-leg response is safely recovered by retrying with the *same* `clientRequestId`. If INVO cannot replay the session and a payment already exists for that `clientRequestId`, the card purchase throws `409` `err.isDuplicateClientRequestId` (`err.isDuplicateRequest` is also true) with `order_id` and `order_status` on `err.body`; read that order with `getStatus` instead of starting another payment. A refund by `clientRequestId` finds card orders as well as balance orders.
791
795
  - INVO fee: **3.5% flat** (balance) · **3.5% + $0.30** (card). Too-small amounts throw `err.isAmountBelowMinimum` / `err.isBelowCardMinimum` (card < $0.50); a card total over INVO's maximum single card charge comes back as `err.isAboveCardMaximum` (400) with the live figure in `err.message`.
792
796
  - Client-side validation (missing fields, bad funding source, quantity outside `1..1000`, total ≠ unit×qty, card total under $0.50, non-E.164 `playerPhone`) throws **before** any network call. The card **maximum** is deliberately not among them: see [The card maximum is INVO's, not the SDK's](#the-card-maximum-is-invos-not-the-sdks).
793
797
  - Fulfill on the **`platform_commerce.purchased`** webhook; handle **`platform_commerce.refunded`** for reversals.
@@ -822,11 +826,13 @@ Each period INVO works out what the period is worth in coins (card: price × the
822
826
 
823
827
  A card subscription needs a card saved for later, off-session use. **The recommended way to save one is the INVO-hosted card page:** two server-to-server calls and one redirect, **no browser code**, and nothing in your integration references a card processor or loads its script, so INVO can change processor without you changing anything. Your PCI scope does not change: the subscription endpoints never receive card data and neither does this SDK.
824
828
 
825
- **1. Mint a card-setup session on your server.** The member must already exist in your title; this call never creates players.
829
+ **1. Mint a card-setup session on your server.** A member your title already knows needs only `playerEmail`. For a **brand-new member** (a first-time signup) also send `playerName`, and optionally `playerPhone` (E.164): INVO creates the member exactly as `subscriptions.create` would, then mints the link. Without `playerName` an unknown member is refused with `404 PLAYER_NOT_FOUND` and nothing is created. A known member is never re-created or renamed by this call; `playerName` and `playerPhone` are used only when the member is new.
826
830
 
827
831
  ```ts
828
832
  const session = await server.cards.createSetupSession({
829
833
  playerEmail: "member@example.com",
834
+ playerName: "Member", // creates the member if they are new (3.15.0 or later)
835
+ // playerPhone: "+15555550100", // optional, E.164; used only when the member is created
830
836
  successUrl: "https://your.game/billing/card-saved?member=7", // optional: where the page sends the member after the save; put your own correlation id here
831
837
  });
832
838
  // session.sessionId, session.cardSetupUrl, session.expiresAt (10 minutes from now)
@@ -848,7 +854,7 @@ const r = await server.subscriptions.create({
848
854
  });
849
855
  ```
850
856
 
851
- **A brand-new member (no player in your title yet).** The card page needs an existing player and there is no create-player call, so bring the member into your title first. Two ways that move no money: `subscriptions.create` with `trialDays` creates the player and a `trialing` subscription (`firstCharge.status: "skipped_trial"`); or a card-less `subscriptions.create` (no `playerCardId`, no saved card yet) creates the player and the subscription, and its first charge is recorded as failed with `failureCode: "no_payment_method"` (outcome `insufficient_funds`), so the subscription sits in dunning with access retained. Then mint the card session and send the member to the page. After the save either call `subscriptions.setPaymentMethod(id, { playerCardId })` or do nothing: INVO adopts the member's newest saved card at the next attempt and attaches it. A currency purchase also creates the player, and with `save_card: true` saves the card in the same step.
857
+ **A brand-new member (no player in your title yet).** Send `playerName` with `createSetupSession` and the card page goes first: INVO creates the member, the member saves their card, and your `subscriptions.create` finds it. This is the order a [paid trial](#paid-trials) for a new signup needs. The older orders still work: a `subscriptions.create` first (with `trialDays`, or card-less, in which case its first charge fails with `failureCode: "no_payment_method"` and the subscription sits in dunning until the card saved afterwards is adopted at the next attempt), or a currency purchase with `save_card: true`, which creates the player and saves the card in one step. The processor-bound `cards.beginSetup` still never creates players.
852
858
 
853
859
  **What to expect.**
854
860
 
@@ -865,8 +871,10 @@ const r = await server.subscriptions.create({
865
871
  | Helper / code | HTTP | Meaning |
866
872
  |---|---|---|
867
873
  | `.isInvalidPlayerEmail` (`INVALID_PLAYER_EMAIL`) | 400 | `playerEmail` is not an email address (INVO checks for an `@`). A missing or blank `playerEmail` never reaches INVO: the SDK throws `INVALID_INPUT` with `.status === 0` first |
868
- | `.isPlayerNotFound` (`PLAYER_NOT_FOUND`) | 404 | the member does not exist in this title yet. Create the player first (any call that creates players, for example a currency purchase); the card page never creates one |
869
- | `.isInvalidInput` (`INVALID_INPUT`) | 400 | `successUrl` or `cancelUrl` uses a script scheme (`javascript:`, `data:`, `vbscript:`). http(s) and app deep-link schemes are fine. The SDK refuses the same values before the network with `.status === 0` |
874
+ | `.isPlayerNotFound` (`PLAYER_NOT_FOUND`) | 404 | the member does not exist in this title yet and no `playerName` was sent. Send `playerName` to create the member with their card |
875
+ | `.isInvalidInput` (`INVALID_INPUT`) | 400 | `successUrl` or `cancelUrl` uses a script scheme (`javascript:`, `data:`, `vbscript:`; http(s) and app deep-link schemes are fine), or, when the member is new, `playerName` is over 255 characters or `playerPhone` over 30. The SDK refuses script schemes, a blank or over-long `playerName` and a non-E.164 `playerPhone` before the network with `.status === 0` |
876
+ | `.isPhoneShareApprovalRequired` (`PHONE_SHARE_APPROVAL_REQUIRED`) | 409 | creating the new member needs the approval of whoever already holds `playerPhone`; the same body and handling as on `subscriptions.create` |
877
+ | `.isPlayerCreateFailed` (`PLAYER_CREATE_FAILED`) | 503 | the new member could not be created; nothing was created and no link was minted. Call again |
870
878
  | no code, `err.status === 401` | 401 | the game key is missing or wrong for this environment (body is `{ message }`) |
871
879
  | no code, `err.status === 403` | 403 | the game is not `live` or `testing` |
872
880
  | `err.status === 503` (the `error_code` names the cause) | 503 | card setup is not available right now; retry shortly |
@@ -876,7 +884,8 @@ Rate limit: 2000 per minute per game key with a per-IP floor; on a 429 honour `e
876
884
  **The processor-bound alternative: `cards.beginSetup` / `cards.confirmSetup`.** Use these only if you already run a card form in your own client against INVO's current card processor. `beginSetup` hands back a `clientSecret` that only that processor's client library can consume, so the browser code you write for it is bound to the processor of the day and will need rework when INVO changes processor. `createSetupSession` does not have that problem, which is why it is the recommended path.
877
885
 
878
886
  ```ts
879
- // The processor-bound alternative (charges nothing). The player must already exist in this game.
887
+ // The processor-bound alternative (charges nothing). The player must already exist in this game:
888
+ // beginSetup never creates players (createSetupSession with playerName does).
880
889
  const setup = await server.cards.beginSetup({
881
890
  playerEmail: "member@example.com",
882
891
  setupReference: "setup-guild-42-member-7", // idempotency anchor: resend the same value on a retry
@@ -989,10 +998,34 @@ const r = await server.subscriptions.create({
989
998
 
990
999
  - **Period 1 is the trial window** and is charged `trialAmountUsd` inside the `create` call, through the same first charge as any subscription. `firstCharge` reports it as any first charge is reported (`paid`, `requires_action`, `failed`, `pending`) with the trial price; `skipped_trial` is never returned for a paid trial. `subscription.renewed` fires for period 1 with `is_trial: true` and `amount_usd: "1.00"`.
991
1000
  - **At the trial end INVO charges `amountUsd` as period 2** (`subscription.renewed` with `period_seq: 2`, `is_trial: false`) and billing continues as normal. This is not a price change: nothing is staged and the doubling rule does not apply.
992
- - **Save the card first.** Without a usable saved card the create is refused with `400 PAYMENT_METHOD_REQUIRED` (`err.isPaymentMethodRequired`) and nothing is created.
1001
+ - **Save the card first.** Without a usable saved card the create is refused with `400 PAYMENT_METHOD_REQUIRED` (`err.isPaymentMethodRequired`) and nothing is created. For a **brand-new signup**, save the card through the hosted card page with `playerName`, which creates the member:
1002
+
1003
+ ```ts
1004
+ // 1. create the member and mint the card link in one call
1005
+ const session = await server.cards.createSetupSession({
1006
+ playerEmail: "new@example.com",
1007
+ playerName: "New Member",
1008
+ successUrl: "https://your.game/billing/card-saved?member=new",
1009
+ });
1010
+ // 2. send the member to session.cardSetupUrl (top-level); they return to successUrl
1011
+ // 3. read the card, then subscribe with the paid trial
1012
+ const { cards } = await server.cards.list("new@example.com");
1013
+ const r = await server.subscriptions.create({
1014
+ clientRequestId: "new-member-pro",
1015
+ playerEmail: "new@example.com",
1016
+ playerName: "New Member",
1017
+ itemId: "pro-membership",
1018
+ amountUsd: "29.00",
1019
+ trialDays: 7,
1020
+ trialAmountUsd: "1.00",
1021
+ playerCardId: cards[0].id,
1022
+ consent: { consentAt: new Date().toISOString(), disclosedAmountUsd: "29.00", disclosedInterval: "month",
1023
+ disclosedTrialAmountUsd: "1.00", disclosedTrialDays: 7 },
1024
+ });
1025
+ ```
993
1026
  - **A refused trial charge ends it.** The subscription goes straight to `expired`, `firstCharge.status` is `failed` with `nextRetryAt: null`, and you receive `subscription.payment_failed` then `subscription.expired` with `expire_cause: "trial_payment_failed"`. Subscribe again with a **new** `clientRequestId` once the member has a working card. A temporary processing error is not a refusal: that goes to ordinary dunning and is retried.
994
1027
  - **Events about the trial period** (`payment_failed`, `past_due`, `authentication_required`, `expired`) carry `is_trial: true` and `trial_amount_usd`; their `amount_usd` is still the regular price and `amount_due_usd` is the trial price. The keys are absent on every other event of those types.
995
- - **Refusals:** `err.isTrialAmountRequiresTrial` (no `trialDays`/`trialEnd`), `err.isTrialAmountNotSupportedForFunding` (`walletOnly: true`, or the Steam rail), `err.isTrialAmountInvalid` (below $0.50 or not below `amountUsd`), `err.isConsentDisclosedTrialInvalid` (a malformed `disclosedTrial*` field). The first two, and a malformed amount, are also caught by the SDK before the network. A changed `trialAmountUsd` on a replay is `err.isIdempotentReplayMismatch` with `trial_amount_usd` in `err.mismatchedFields`.
1028
+ - **Refusals:** `err.isTrialAmountRequiresTrial` (no `trialDays`/`trialEnd`), `err.isTrialAmountNotSupportedForFunding` (`walletOnly: true`, or the Steam rail), `err.isTrialAmountInvalid` (below $0.50 or not below `amountUsd`), `err.isTrialAmountBelowFeeFloor` (the trial price would leave you nothing after INVO's card fee; the message names the smallest price accepted), `err.isConsentDisclosedTrialInvalid` (a malformed `disclosedTrial*` field). The first two, and a malformed amount, are also caught by the SDK before the network. A changed `trialAmountUsd` on a replay is `err.isIdempotentReplayMismatch` with `trial_amount_usd` in `err.mismatchedFields`.
996
1029
  - The trial period is refundable like any other period.
997
1030
 
998
1031
  ### The Steam road
@@ -1210,6 +1243,7 @@ Match on `err.code` (and on `body.status` where the body carries one), never on
1210
1243
  | `.isIdempotentReplayMismatch` + `.mismatchedFields` | (409) same key, same player + item, different material terms (`trial_amount_usd` included). Use `changeAmount`/`setPaymentMethod`, or a new key |
1211
1244
  | `.isPaymentMethodRequired` | (400) a paid trial with no usable saved card; nothing was created. Save a card first. (Also `setPaymentMethod` without a card id) |
1212
1245
  | `.isTrialAmountRequiresTrial` / `.isTrialAmountNotSupportedForFunding` / `.isTrialAmountInvalid` | (400) `trialAmountUsd` without a trial; with `walletOnly: true` or on Steam; below $0.50 or not below `amountUsd` |
1246
+ | `.isTrialAmountBelowFeeFloor` | (400) the trial price would leave you nothing after INVO's card fee; nothing was created. `err.message` names the smallest trial price accepted |
1213
1247
  | `.isConsentDisclosedTrialInvalid` | (400) a malformed `disclosedTrialAmountUsd` / `disclosedTrialDays` / `disclosedTrialEnd`; `err.code` says which |
1214
1248
  | `.isFlowPaused` | (503) maintenance pause. Retry later with the **same** key |
1215
1249
  | `.isSubscriptionTerminal` | (409) the subscription is `canceled`/`expired`. Start a new one |
@@ -1232,7 +1266,8 @@ Match on `err.code` (and on `body.status` where the body carries one), never on
1232
1266
  | `WALLET_ONLY_SUBSCRIPTION` / `WALLET_ONLY_CONFLICT` | `walletOnly: true` with a card; or a wallet-only subscription needs `walletOnly: false` beside the new card (`walletOnly` is deprecated: such a subscription can never be paid) |
1233
1267
  | `NO_PAID_PERIOD` / `PERIOD_NOT_REFUNDABLE` / `AMOUNT_EXCEEDS_REMAINING` | refund refusals (the last carries `remaining_refundable_usd`) |
1234
1268
  | `AMOUNT_TOO_SMALL_FOR_STEAM` / `STEAM_CHARGE_UNPLANNABLE` / `STEAM_UNAVAILABLE` / `STEAM_ERROR` | Steam init refusals; the last three abandoned the row (its id on `.existingSubscriptionId`): retry with a **new** key |
1235
- | `.isPlayerNotFound` / `.isInvalidPlayerEmail` / `.isInvalidInput` | (404 / 400 / 400) `cards.createSetupSession`: the member does not exist yet (the card page never creates players); `playerEmail` is not an email; `successUrl`/`cancelUrl` uses a script scheme (`isInvalidInput` is also the SDK's own pre-network guard code, at `.status === 0`) |
1269
+ | `.isPlayerNotFound` / `.isInvalidPlayerEmail` / `.isInvalidInput` | (404 / 400 / 400) `cards.createSetupSession`: the member does not exist yet and no `playerName` was sent (send it to create them); `playerEmail` is not an email; `successUrl`/`cancelUrl` uses a script scheme, or a new member's `playerName` / `playerPhone` is too long (`isInvalidInput` is also the SDK's own pre-network guard code, at `.status === 0`) |
1270
+ | `.isPlayerCreateFailed` / `.isPhoneShareApprovalRequired` | (503 / 409) `cards.createSetupSession` with `playerName` for a new member: the member could not be created (call again), or their phone is already another member's and needs that holder's approval |
1236
1271
  | `SETUP_REFERENCE_REUSED` / `PLAYER_NOT_FOUND` / `CARD_DECLINED` / `RAW_CARD_NOT_SUPPORTED` / `CARD_PERSIST_FAILED` | the processor-bound card capture (`beginSetup`/`confirmSetup`); on `CARD_PERSIST_FAILED` (500) retry `confirmSetup` with the same `setupIntentId` |
1237
1272
 
1238
1273
  Client-side guards (missing key, a `sub_`-prefixed key, a bad amount, a non-E.164 `playerPhone`, a trial or card field on Steam, `trialAmountUsd` without a trial or with `walletOnly: true`, a web session without `playerIp`, a missing `sandboxClockKey`) throw `InvoError` with `.status === 0` **before** any network call.
@@ -1408,6 +1443,7 @@ try {
1408
1443
  text saying the currency was returned, instead of silence. `transfer.claim_expired` +
1409
1444
  `transfer.refunded` remain the source of truth — reconcile off those, not the messages.
1410
1445
  - **`err.isPhoneShareApprovalRequired` on `confirmReceipt*` / `claimTransfer` / `claimCurrency`** (409): the receiver phone is contested, so INVO **holds the money** and texts the phone owner to approve. Not a failure — show `err.message` verbatim (`err.phoneShareLast4` names the phone), then **retry the same call** once approved (it succeeds idempotently); on denial/expiry the sender is refunded. Same handling as the initiate-time phone-share 409.
1446
+ - **`err.isIdentityCheckUnavailable` on `confirmReceipt*` / `claimTransfer` / `claimCurrency`** (503, retryable): INVO could not check the claim just now. Nothing was moved; retry the same call after a few seconds.
1411
1447
  - **Both games must be Live.** `initiateSend`/`initiateTransfer` throw `403` if either side is still in testing, and the two cases are **deliberately separate** because the fix differs: `err.isSourceGameNotLive` is **your** game (self-serve — switch it to Live in the console under Game Settings → Status), `err.isTargetGameNotLive` is the **destination** game, usually owned by another developer, so you can't flip it — show `err.message` and steer the player elsewhere via `getDestinations`. `err.gameStatus` carries the current state. Don't merge these into one "not live" branch; it produces a "go fix it" button that leads nowhere half the time.
1412
1448
  - **Steam titles** (dark until a title is Steam-distributed): `initiateSend`/`initiateTransfer` can throw `err.isSteamValueNonTransferable` (moving more than the non-Steam balance to a non-Steam destination — show `err.message`, cap the amount at `err.steamTransferableMax`; `err.steamOriginAmount` is the Steam-locked portion) or `err.isNonSteamValueIntoSteamBlocked` (non-Steam value into a Steam title). Prevent both up front: `getDestinations` rows carry **`acceptsSteamOriginValue`** — disable non-Steam destinations for a player holding Steam-purchased currency. **This is a rule about currency moving between titles, not about spending.** A player can spend any balance on items in any title, Steam-distributed or not, including currency bought through Steam, so an item purchase never fails on origin and there is nothing to branch on there.
1413
1449
  - Transfer self-claim may be disabled for your tenant; if it is, surface the claim-code path instead.
@@ -2116,8 +2152,8 @@ export const POST = createWebhookHandler({
2116
2152
  | Event | Fires for | Use it to |
2117
2153
  |---|---|---|
2118
2154
  | `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`). **Skip it when `metadata.source` is `"subscription_renewal"`**: those coins are spent by the renewal itself; grant on `subscription.renewed`. |
2119
- | `purchase.failed` / `purchase.disputed` | `platform` rail only | handle failures/disputes |
2120
- | `purchase.refunded` | `game` / `steam` rails | handle refunds |
2155
+ | `purchase.failed` / `purchase.disputed` | `platform` rail only | handle failures/disputes. A lost chargeback takes back up to the purchase's coins from the available balance, never below zero |
2156
+ | `purchase.refunded` | `game` / `steam` rails | handle refunds. Only coins the player still has from that purchase are taken back, never below zero |
2121
2157
  | `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`) |
2122
2158
  | `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`) |
2123
2159
  | `platform_commerce.refunded` | a Platform Commerce refund | handle the reversal (payload: `order_id, funding_source, player_email, refunded_amount, amount_unit, fee_retained`) |
@@ -2210,6 +2246,8 @@ Helpers:
2210
2246
  | `.isReceiverNotEnrolled` | recipient has no passkey → switch to claim-code entry |
2211
2247
  | `.isInsufficientBalance` | item purchase failed (400); `required_amount` + `current_balance` on `.body` |
2212
2248
  | `.isDuplicateRequest` | idempotency-keyed request was a duplicate (409) |
2249
+ | `.isDuplicateClientRequestId` | Platform Commerce card purchase whose `clientRequestId` already has a payment (409); `order_id` + `order_status` on `.body` |
2250
+ | `.isIdentityCheckUnavailable` | a claim or confirm-receipt could not be checked just now (503); nothing moved, retry in a few seconds |
2213
2251
  | `.isNotPlatformTenant` | Platform Commerce called by a non-platform tenant (403) — use `purchaseItem`/`createCheckout` instead |
2214
2252
  | `.isAmountBelowMinimum` / `.isBelowCardMinimum` / `.isAboveCardMaximum` | amount too small for the fee to round up / card charge under $0.50 / card charge over INVO's maximum single card charge, which is a runtime setting (400) |
2215
2253
  | `.isAlreadyRefunded` | Platform Commerce refund of an already-refunded order (409) — treat as already done |
@@ -2251,7 +2289,7 @@ try {
2251
2289
  | `mintPlayerToken({ playerEmail, playerPhone? })` | `{ token, expiresAt, identityId }` — session mint for an **existing** player (404 if unknown); `playerPhone` optional/validated-if-present (see [Player token](#player-token-session-mint-for-an-existing-player)) |
2252
2290
  | `initiateSend(input)` | `{ transactionId, verificationMethod, guardianApproval?, raw }` |
2253
2291
  | `initiateTransfer(input)` | `{ transactionId, verificationMethod, guardianApproval?, raw }` |
2254
- | `createCheckout(input)` | `{ sessionId, checkoutUrl, sessionToken?, expiresAt, expiresInSeconds, raw }`, where `sessionToken` is INVO's own `session_token` field (falling back to the `checkoutUrl` query string on a backend that predates it) and is the credential for the [status read](#did-the-purchase-go-through-the-status-read) |
2292
+ | `createCheckout(input)` | `{ sessionId, checkoutUrl, sessionToken?, expiresAt, expiresInSeconds, warnings?, raw }`, where `sessionToken` is INVO's own `session_token` field (falling back to the `checkoutUrl` query string on a backend that predates it) and is the credential for the [status read](#did-the-purchase-go-through-the-status-read) |
2255
2293
  | `quoteCurrencyPurchase({ playerEmail, usdAmount, country?, subdivision? })` | `CurrencyPurchaseQuote`: `{ totalUsd, amountCents, subtotalUsd, processingFeeUsd, coins, currencyName, breakdown, ifUnacknowledged, raw }`; moves no money; send `totalUsd` back as `acknowledgedTotalUsd` (see [INVO's card fee](#invos-card-fee-quote-show-acknowledge)) |
2256
2294
  | `purchaseCurrency(input)` | `{ status, clientSecret?, paymentIntentId?, paymentUrl?, transactionId?, orderId?, newBalance?, processingFeeUsd?, feeTakenFrom?, coinsCredited?, chargeTotalUsd?, receiptNumber?, receiptUrl?, raw }`; optional `acknowledgedTotalUsd` input; `receiptNumber` / `receiptUrl` on Merchant of Record only |
2257
2295
  | `confirmPayment({ paymentIntentId, orderId? })` | `{ status, transactionId?, newBalance?, credited?, reasonCode?, raw }`; report success only on `credited: true` |
@@ -2271,7 +2309,7 @@ try {
2271
2309
  | `subscriptions.refund(id, { clientRequestId, periodSeq?, amountUsd?, reason? })` | `RefundResult` (one interface; branch with `isRefundPendingApproval(r)`): `status: "refunded"` (the receipt: `isFullRefund, fundingShape, balanceDeltaCoins, cardRefundedUsd, partnerRevenueReversedUsd, revenueShareAttribution, idempotentReplay`, plus `subscriptionCanceled, subscriptionStatus, processingFeeUsd, processingFeeBasis, partnerTotalReversedUsd, initiation, refundRequestId, warnings?, raw`) or `"pending_approval"` (HTTP 202, over the daily limit, nothing moved: the same fields plus `requestId, requestStatus, requestedAmountUsd, requestedAt, dailyCapUsd, executedTodayUsd, message`, required on the narrowed `RefundPendingApproval`); idempotent on `clientRequestId` (a replay, `idempotentReplay: true`, never carries `newBalance` or `revenueShareAttribution`); a full refund cancels the subscription; Steam-charged periods throw `isSteamRefundNotSupported` |
2272
2310
  | `subscriptions.steamInit(input)` | `SteamInitResult` — `{ status, subscriptionStatus, idempotentReplay, pendingReuse, subscription, subscriptionId, orderId, steamOrderId, steamTransid, steamCheckoutUrl, amountUsd, amountCoins, steamChargeUsd, recurringAmountUsd, firstCharge, message, raw }`; **Steam rail**, nothing charged until finalize; match the Steam client callback on `steamOrderId` |
2273
2311
  | `subscriptions.steamFinalize(subscriptionId)` | `SteamFinalizeSubscriptionResult` — the `SubscriptionResult` plus `{ alreadyProcessed, steamAgreementStatus, sandboxAutoApproved }`; `isNotAuthorized` (409) is the normal wait state |
2274
- | `cards.createSetupSession({ playerEmail, successUrl?, cancelUrl?, metadata? })` | `CardSetupSessionResult`: `{ sessionId, cardSetupUrl, expiresAt, raw }`. **The recommended card capture for subscriptions**: mint a 10-minute link to the INVO-hosted card page, send the member to `cardSetupUrl` (top-level), then read the card's `id` from `cards.list`; no browser code, no processor named; never auto-retried; `isPlayerNotFound` / `isInvalidPlayerEmail` / `isInvalidInput` |
2312
+ | `cards.createSetupSession({ playerEmail, playerName?, playerPhone?, successUrl?, cancelUrl?, metadata? })` | `CardSetupSessionResult`: `{ sessionId, cardSetupUrl, expiresAt, raw }`. **The recommended card capture for subscriptions**: mint a 10-minute link to the INVO-hosted card page, send the member to `cardSetupUrl` (top-level), then read the card's `id` from `cards.list`; no browser code, no processor named; never auto-retried. `playerName` creates a brand-new member (never renames a known one); `isPlayerNotFound` / `isInvalidPlayerEmail` / `isInvalidInput` / `isPhoneShareApprovalRequired` / `isPlayerCreateFailed` |
2275
2313
  | `cards.beginSetup({ playerEmail, setupReference, paymentMethodId? })` | `CardSetupResult`: `{ status, setupIntentId, clientSecret?, publishableKey?, card, alreadySaved, raw }`; the **processor-bound** card capture (you run the card form; charges nothing; idempotent on `setupReference`) |
2276
2314
  | `cards.confirmSetup({ setupIntentId })` | `{ status, setupIntentId, card, alreadySaved, raw }`: finish a client-confirmed setup on the processor-bound path |
2277
2315
  | `cards.list(playerEmail)` | `{ cards: SavedCard[], raw }` — unexpired cards, newest first; `card.id` is the `playerCardId` |
@@ -196,9 +196,19 @@ var InvoError = class _InvoError extends Error {
196
196
  get isPhoneShareAlreadyApproved() {
197
197
  return this.code === "PHONE_SHARE_ALREADY_APPROVED";
198
198
  }
199
- /** True if an idempotency-keyed request was a duplicate (item / platform purchase → 409). */
199
+ /** True if an idempotency-keyed request was a duplicate (item / platform purchase → 409).
200
+ * Also true for {@link isDuplicateClientRequestId}. */
200
201
  get isDuplicateRequest() {
201
- return this.code === "DUPLICATE_REQUEST" || this.status === 409 && /duplicate/i.test(this.message);
202
+ return this.code === "DUPLICATE_REQUEST" || this.code === "DUPLICATE_CLIENT_REQUEST_ID" || this.status === 409 && /duplicate/i.test(this.message);
203
+ }
204
+ /**
205
+ * True when a Platform Commerce CARD purchase reused a `clientRequestId` that already has a
206
+ * payment in progress or done (`DUPLICATE_CLIENT_REQUEST_ID`, 409). The body carries
207
+ * `order_id` and `order_status` for that order. Read it with `platformCommerce.getStatus`
208
+ * rather than starting a second payment.
209
+ */
210
+ get isDuplicateClientRequestId() {
211
+ return this.code === "DUPLICATE_CLIENT_REQUEST_ID";
202
212
  }
203
213
  /**
204
214
  * True if a Platform Commerce call was rejected because the tenant isn't a platform
@@ -209,8 +219,9 @@ var InvoError = class _InvoError extends Error {
209
219
  get isNotPlatformTenant() {
210
220
  return this.code === "NOT_A_PLATFORM_TENANT";
211
221
  }
212
- /** True if a Platform Commerce purchase was too small for the fee to round above zero
213
- * (`AMOUNT_BELOW_MINIMUM`, 400) — raise the amount. */
222
+ /** True if a Platform Commerce purchase, or a `purchaseItem` spend, was too small for the
223
+ * fee to round above zero (`AMOUNT_BELOW_MINIMUM`, 400) — raise the amount. `purchaseItem`
224
+ * rounds `totalPrice` to cents before this check. */
214
225
  get isAmountBelowMinimum() {
215
226
  return this.code === "AMOUNT_BELOW_MINIMUM";
216
227
  }
@@ -581,6 +592,15 @@ var InvoError = class _InvoError extends Error {
581
592
  get isTrialAmountInvalid() {
582
593
  return this.code === "TRIAL_AMOUNT_INVALID";
583
594
  }
595
+ /**
596
+ * True when a paid trial's `trialAmountUsd` would leave you nothing after INVO's card fee
597
+ * (`TRIAL_AMOUNT_BELOW_FEE_FLOOR`, 400). Nothing was created. The message names the smallest
598
+ * trial price accepted for your account. A subscription already created is not affected: a
599
+ * replay of its `clientRequestId` answers as before.
600
+ */
601
+ get isTrialAmountBelowFeeFloor() {
602
+ return this.code === "TRIAL_AMOUNT_BELOW_FEE_FLOOR";
603
+ }
584
604
  /** True when `trialAmountUsd` was sent without `trialDays` or `trialEnd` (`TRIAL_AMOUNT_REQUIRES_TRIAL`, 400). */
585
605
  get isTrialAmountRequiresTrial() {
586
606
  return this.code === "TRIAL_AMOUNT_REQUIRES_TRIAL";
@@ -744,14 +764,23 @@ var InvoError = class _InvoError extends Error {
744
764
  // ---- Card setup session (the INVO-hosted card page) ----
745
765
  /**
746
766
  * True when `cards.createSetupSession` was refused because the member does not exist
747
- * in this game yet (`PLAYER_NOT_FOUND`, 404). The card page never creates players;
748
- * create the member first (any endpoint that creates players, for example a currency
749
- * purchase), then mint the session again. The same code comes back from
750
- * `cards.beginSetup` and from `mintPlayerToken` for the same reason.
767
+ * in this game yet (`PLAYER_NOT_FOUND`, 404) and no `playerName` was sent. Send
768
+ * `playerName` (and optionally `playerPhone`) to create the member with their card.
769
+ * The same code comes back from `cards.beginSetup` and from `mintPlayerToken` for the
770
+ * same reason; those two never create players, so create the member first (for
771
+ * example with `createSetupSession` and a `playerName`, or a currency purchase).
751
772
  */
752
773
  get isPlayerNotFound() {
753
774
  return this.code === "PLAYER_NOT_FOUND";
754
775
  }
776
+ /**
777
+ * True when `cards.createSetupSession` was asked to create a new member (`playerName`
778
+ * sent) and INVO could not create them (`PLAYER_CREATE_FAILED`, 503). Nothing was
779
+ * created and no link was minted; call again.
780
+ */
781
+ get isPlayerCreateFailed() {
782
+ return this.code === "PLAYER_CREATE_FAILED";
783
+ }
755
784
  /**
756
785
  * True when `cards.createSetupSession` was refused because `playerEmail` was missing or
757
786
  * is not an email address (`INVALID_PLAYER_EMAIL`, 400).
@@ -764,7 +793,8 @@ var InvoError = class _InvoError extends Error {
764
793
  * `status === 0` is this SDK refusing a value before the network (every client-side
765
794
  * guard uses this code); `status === 400` is INVO refusing one, on
766
795
  * `cards.createSetupSession` a `successUrl` / `cancelUrl` that uses a script scheme
767
- * (`javascript:`, `data:`, `vbscript:`). http(s) and app deep-link schemes are fine.
796
+ * (`javascript:`, `data:`, `vbscript:`; http(s) and app deep-link schemes are fine), or,
797
+ * when the member is new, a `playerName` over 255 characters or a `playerPhone` over 30.
768
798
  */
769
799
  get isInvalidInput() {
770
800
  return this.code === "INVALID_INPUT";
@@ -796,6 +826,14 @@ var InvoError = class _InvoError extends Error {
796
826
  get isCheckoutSessionExpired() {
797
827
  return this.code === "SESSION_EXPIRED";
798
828
  }
829
+ /**
830
+ * True when a claim or a confirm-receipt could not be checked just now
831
+ * (`IDENTITY_CHECK_UNAVAILABLE`, 503). Nothing was moved. Retry after a few seconds. Distinct
832
+ * from `CONFIRMATION_SEND_FAILED`, which means a confirmation text could not be sent.
833
+ */
834
+ get isIdentityCheckUnavailable() {
835
+ return this.code === "IDENTITY_CHECK_UNAVAILABLE";
836
+ }
799
837
  /** Seconds to wait before retrying, when the backend throttled the call (429 `retry_after`). */
800
838
  get retryAfter() {
801
839
  const v = this.bodyObject()["retry_after"];
@@ -1096,5 +1134,5 @@ function receiptFields(raw) {
1096
1134
  }
1097
1135
 
1098
1136
  export { Http, InvoError, assertSecureBaseUrl, creditFields, receiptFields, toDestinationsResult };
1099
- //# sourceMappingURL=chunk-BLY4NUMG.js.map
1100
- //# sourceMappingURL=chunk-BLY4NUMG.js.map
1137
+ //# sourceMappingURL=chunk-JGDNPNQX.js.map
1138
+ //# sourceMappingURL=chunk-JGDNPNQX.js.map
package/dist/index.cjs CHANGED
@@ -198,9 +198,19 @@ var InvoError = class _InvoError extends Error {
198
198
  get isPhoneShareAlreadyApproved() {
199
199
  return this.code === "PHONE_SHARE_ALREADY_APPROVED";
200
200
  }
201
- /** True if an idempotency-keyed request was a duplicate (item / platform purchase → 409). */
201
+ /** True if an idempotency-keyed request was a duplicate (item / platform purchase → 409).
202
+ * Also true for {@link isDuplicateClientRequestId}. */
202
203
  get isDuplicateRequest() {
203
- return this.code === "DUPLICATE_REQUEST" || this.status === 409 && /duplicate/i.test(this.message);
204
+ return this.code === "DUPLICATE_REQUEST" || this.code === "DUPLICATE_CLIENT_REQUEST_ID" || this.status === 409 && /duplicate/i.test(this.message);
205
+ }
206
+ /**
207
+ * True when a Platform Commerce CARD purchase reused a `clientRequestId` that already has a
208
+ * payment in progress or done (`DUPLICATE_CLIENT_REQUEST_ID`, 409). The body carries
209
+ * `order_id` and `order_status` for that order. Read it with `platformCommerce.getStatus`
210
+ * rather than starting a second payment.
211
+ */
212
+ get isDuplicateClientRequestId() {
213
+ return this.code === "DUPLICATE_CLIENT_REQUEST_ID";
204
214
  }
205
215
  /**
206
216
  * True if a Platform Commerce call was rejected because the tenant isn't a platform
@@ -211,8 +221,9 @@ var InvoError = class _InvoError extends Error {
211
221
  get isNotPlatformTenant() {
212
222
  return this.code === "NOT_A_PLATFORM_TENANT";
213
223
  }
214
- /** True if a Platform Commerce purchase was too small for the fee to round above zero
215
- * (`AMOUNT_BELOW_MINIMUM`, 400) — raise the amount. */
224
+ /** True if a Platform Commerce purchase, or a `purchaseItem` spend, was too small for the
225
+ * fee to round above zero (`AMOUNT_BELOW_MINIMUM`, 400) — raise the amount. `purchaseItem`
226
+ * rounds `totalPrice` to cents before this check. */
216
227
  get isAmountBelowMinimum() {
217
228
  return this.code === "AMOUNT_BELOW_MINIMUM";
218
229
  }
@@ -583,6 +594,15 @@ var InvoError = class _InvoError extends Error {
583
594
  get isTrialAmountInvalid() {
584
595
  return this.code === "TRIAL_AMOUNT_INVALID";
585
596
  }
597
+ /**
598
+ * True when a paid trial's `trialAmountUsd` would leave you nothing after INVO's card fee
599
+ * (`TRIAL_AMOUNT_BELOW_FEE_FLOOR`, 400). Nothing was created. The message names the smallest
600
+ * trial price accepted for your account. A subscription already created is not affected: a
601
+ * replay of its `clientRequestId` answers as before.
602
+ */
603
+ get isTrialAmountBelowFeeFloor() {
604
+ return this.code === "TRIAL_AMOUNT_BELOW_FEE_FLOOR";
605
+ }
586
606
  /** True when `trialAmountUsd` was sent without `trialDays` or `trialEnd` (`TRIAL_AMOUNT_REQUIRES_TRIAL`, 400). */
587
607
  get isTrialAmountRequiresTrial() {
588
608
  return this.code === "TRIAL_AMOUNT_REQUIRES_TRIAL";
@@ -746,14 +766,23 @@ var InvoError = class _InvoError extends Error {
746
766
  // ---- Card setup session (the INVO-hosted card page) ----
747
767
  /**
748
768
  * True when `cards.createSetupSession` was refused because the member does not exist
749
- * in this game yet (`PLAYER_NOT_FOUND`, 404). The card page never creates players;
750
- * create the member first (any endpoint that creates players, for example a currency
751
- * purchase), then mint the session again. The same code comes back from
752
- * `cards.beginSetup` and from `mintPlayerToken` for the same reason.
769
+ * in this game yet (`PLAYER_NOT_FOUND`, 404) and no `playerName` was sent. Send
770
+ * `playerName` (and optionally `playerPhone`) to create the member with their card.
771
+ * The same code comes back from `cards.beginSetup` and from `mintPlayerToken` for the
772
+ * same reason; those two never create players, so create the member first (for
773
+ * example with `createSetupSession` and a `playerName`, or a currency purchase).
753
774
  */
754
775
  get isPlayerNotFound() {
755
776
  return this.code === "PLAYER_NOT_FOUND";
756
777
  }
778
+ /**
779
+ * True when `cards.createSetupSession` was asked to create a new member (`playerName`
780
+ * sent) and INVO could not create them (`PLAYER_CREATE_FAILED`, 503). Nothing was
781
+ * created and no link was minted; call again.
782
+ */
783
+ get isPlayerCreateFailed() {
784
+ return this.code === "PLAYER_CREATE_FAILED";
785
+ }
757
786
  /**
758
787
  * True when `cards.createSetupSession` was refused because `playerEmail` was missing or
759
788
  * is not an email address (`INVALID_PLAYER_EMAIL`, 400).
@@ -766,7 +795,8 @@ var InvoError = class _InvoError extends Error {
766
795
  * `status === 0` is this SDK refusing a value before the network (every client-side
767
796
  * guard uses this code); `status === 400` is INVO refusing one, on
768
797
  * `cards.createSetupSession` a `successUrl` / `cancelUrl` that uses a script scheme
769
- * (`javascript:`, `data:`, `vbscript:`). http(s) and app deep-link schemes are fine.
798
+ * (`javascript:`, `data:`, `vbscript:`; http(s) and app deep-link schemes are fine), or,
799
+ * when the member is new, a `playerName` over 255 characters or a `playerPhone` over 30.
770
800
  */
771
801
  get isInvalidInput() {
772
802
  return this.code === "INVALID_INPUT";
@@ -798,6 +828,14 @@ var InvoError = class _InvoError extends Error {
798
828
  get isCheckoutSessionExpired() {
799
829
  return this.code === "SESSION_EXPIRED";
800
830
  }
831
+ /**
832
+ * True when a claim or a confirm-receipt could not be checked just now
833
+ * (`IDENTITY_CHECK_UNAVAILABLE`, 503). Nothing was moved. Retry after a few seconds. Distinct
834
+ * from `CONFIRMATION_SEND_FAILED`, which means a confirmation text could not be sent.
835
+ */
836
+ get isIdentityCheckUnavailable() {
837
+ return this.code === "IDENTITY_CHECK_UNAVAILABLE";
838
+ }
801
839
  /** Seconds to wait before retrying, when the backend throttled the call (429 `retry_after`). */
802
840
  get retryAfter() {
803
841
  const v = this.bodyObject()["retry_after"];
package/dist/index.d.cts CHANGED
@@ -1,5 +1,5 @@
1
- import { A as ApproveResult, C as ConfirmReceiptResult, P as PurchaseStatusResult, a as PurchaseCredited, b as PurchaseExpired, c as PurchaseRefunded, d as PurchaseRefused, e as CheckoutClientConfig, H as Http, f as PurchaseStatusInput, g as CallOptions, W as WaitForPurchaseInput, M as MountCheckoutOptions, h as CheckoutMountHandle, i as ClientConfig, L as LinkDeviceResult, j as PendingCollectResult, D as DestinationsQuery, k as DestinationsResult, B as BalanceResult, E as EnrollmentBeginResult, l as EnrollmentVerifyResult, R as RecoveryBeginResult, m as RecoveryCompleteResult } from './types-CD83iV3D.cjs';
2
- export { n as BalanceRow, o as CheckoutPurchaseStatus, p as DestinationGame, I as InvoError, q as InvoErrorInfo, r as InvoHooks, s as InvoRequestInfo, t as InvoResponseInfo, u as PendingCollectItem, v as PurchaseRefusalReason, w as Rail, V as VerificationMethod } from './types-CD83iV3D.cjs';
1
+ import { A as ApproveResult, C as ConfirmReceiptResult, P as PurchaseStatusResult, a as PurchaseCredited, b as PurchaseExpired, c as PurchaseRefunded, d as PurchaseRefused, e as CheckoutClientConfig, H as Http, f as PurchaseStatusInput, g as CallOptions, W as WaitForPurchaseInput, M as MountCheckoutOptions, h as CheckoutMountHandle, i as ClientConfig, L as LinkDeviceResult, j as PendingCollectResult, D as DestinationsQuery, k as DestinationsResult, B as BalanceResult, E as EnrollmentBeginResult, l as EnrollmentVerifyResult, R as RecoveryBeginResult, m as RecoveryCompleteResult } from './types-CjJARoLk.cjs';
2
+ export { n as BalanceRow, o as CheckoutPurchaseStatus, p as DestinationGame, I as InvoError, q as InvoErrorInfo, r as InvoHooks, s as InvoRequestInfo, t as InvoResponseInfo, u as PendingCollectItem, v as PurchaseRefusalReason, w as Rail, V as VerificationMethod } from './types-CjJARoLk.cjs';
3
3
 
4
4
  /** The four device-approval flows (`begin.flow`). */
5
5
  type HostedFlow = "transfer" | "send" | "send_receipt" | "transfer_receipt";
package/dist/index.d.ts CHANGED
@@ -1,5 +1,5 @@
1
- import { A as ApproveResult, C as ConfirmReceiptResult, P as PurchaseStatusResult, a as PurchaseCredited, b as PurchaseExpired, c as PurchaseRefunded, d as PurchaseRefused, e as CheckoutClientConfig, H as Http, f as PurchaseStatusInput, g as CallOptions, W as WaitForPurchaseInput, M as MountCheckoutOptions, h as CheckoutMountHandle, i as ClientConfig, L as LinkDeviceResult, j as PendingCollectResult, D as DestinationsQuery, k as DestinationsResult, B as BalanceResult, E as EnrollmentBeginResult, l as EnrollmentVerifyResult, R as RecoveryBeginResult, m as RecoveryCompleteResult } from './types-CD83iV3D.js';
2
- export { n as BalanceRow, o as CheckoutPurchaseStatus, p as DestinationGame, I as InvoError, q as InvoErrorInfo, r as InvoHooks, s as InvoRequestInfo, t as InvoResponseInfo, u as PendingCollectItem, v as PurchaseRefusalReason, w as Rail, V as VerificationMethod } from './types-CD83iV3D.js';
1
+ import { A as ApproveResult, C as ConfirmReceiptResult, P as PurchaseStatusResult, a as PurchaseCredited, b as PurchaseExpired, c as PurchaseRefunded, d as PurchaseRefused, e as CheckoutClientConfig, H as Http, f as PurchaseStatusInput, g as CallOptions, W as WaitForPurchaseInput, M as MountCheckoutOptions, h as CheckoutMountHandle, i as ClientConfig, L as LinkDeviceResult, j as PendingCollectResult, D as DestinationsQuery, k as DestinationsResult, B as BalanceResult, E as EnrollmentBeginResult, l as EnrollmentVerifyResult, R as RecoveryBeginResult, m as RecoveryCompleteResult } from './types-CjJARoLk.js';
2
+ export { n as BalanceRow, o as CheckoutPurchaseStatus, p as DestinationGame, I as InvoError, q as InvoErrorInfo, r as InvoHooks, s as InvoRequestInfo, t as InvoResponseInfo, u as PendingCollectItem, v as PurchaseRefusalReason, w as Rail, V as VerificationMethod } from './types-CjJARoLk.js';
3
3
 
4
4
  /** The four device-approval flows (`begin.flow`). */
5
5
  type HostedFlow = "transfer" | "send" | "send_receipt" | "transfer_receipt";
package/dist/index.js CHANGED
@@ -1,5 +1,5 @@
1
- import { InvoError, assertSecureBaseUrl, Http, toDestinationsResult, receiptFields } from './chunk-BLY4NUMG.js';
2
- export { InvoError } from './chunk-BLY4NUMG.js';
1
+ import { InvoError, assertSecureBaseUrl, Http, toDestinationsResult, receiptFields } from './chunk-JGDNPNQX.js';
2
+ export { InvoError } from './chunk-JGDNPNQX.js';
3
3
 
4
4
  // src/shared/webauthn.ts
5
5
  function malformedOptions(field) {