@invonetwork/web-sdk 3.14.1 → 3.15.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.15.0
4
+
5
+ ### Minor Changes
6
+
7
+ - 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.
8
+
9
+ ## 3.14.2
10
+
11
+ ### Patch Changes
12
+
13
+ - README: the Merchant of Record chargeback threshold is measured on the previous complete calendar month. Documentation only.
14
+
3
15
  ## 3.14.1
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.1`, 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.15.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.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
@@ -300,7 +300,7 @@ Every INVO developer account is on one of two tiers. The SDK calls are the same
300
300
  | Chargebacks | the disputed amount comes out of your share; on subscription charges the dispute fee is passed through too | INVO manages the dispute and pays the dispute fee; the disputed amount comes out of your share and is restored if INVO wins |
301
301
  | Item purchases (coins spent on an item) | 10% | 10% |
302
302
 
303
- On both tiers every card charge runs on INVO's card rail and INVO pays you out, as today. On subscription card charges made on a card issued outside the United States, or needing a currency conversion, the extra processing cost is passed through to you at INVO's actual cost, reported separately from INVO's fee. On Merchant of Record, if your chargeback rate (disputed card charges divided by successful card charges in a calendar month) goes above 0.75%, dispute fees on your subscription charges pass through 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/
303
+ On both tiers every card charge runs on INVO's card rail and INVO pays you out, as today. On subscription card charges made on a card issued outside the United States, or needing a currency conversion, the extra processing cost is passed through to you at INVO's actual cost, reported separately from INVO's fee. 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 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/
304
304
 
305
305
  **What the tier changes in what the SDK returns** (all additive):
306
306
 
@@ -822,11 +822,13 @@ Each period INVO works out what the period is worth in coins (card: price × the
822
822
 
823
823
  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
824
 
825
- **1. Mint a card-setup session on your server.** The member must already exist in your title; this call never creates players.
825
+ **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
826
 
827
827
  ```ts
828
828
  const session = await server.cards.createSetupSession({
829
829
  playerEmail: "member@example.com",
830
+ playerName: "Member", // creates the member if they are new (3.15.0 or later)
831
+ // playerPhone: "+15555550100", // optional, E.164; used only when the member is created
830
832
  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
833
  });
832
834
  // session.sessionId, session.cardSetupUrl, session.expiresAt (10 minutes from now)
@@ -848,7 +850,7 @@ const r = await server.subscriptions.create({
848
850
  });
849
851
  ```
850
852
 
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.
853
+ **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
854
 
853
855
  **What to expect.**
854
856
 
@@ -865,8 +867,10 @@ const r = await server.subscriptions.create({
865
867
  | Helper / code | HTTP | Meaning |
866
868
  |---|---|---|
867
869
  | `.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` |
870
+ | `.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 |
871
+ | `.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` |
872
+ | `.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` |
873
+ | `.isPlayerCreateFailed` (`PLAYER_CREATE_FAILED`) | 503 | the new member could not be created; nothing was created and no link was minted. Call again |
870
874
  | no code, `err.status === 401` | 401 | the game key is missing or wrong for this environment (body is `{ message }`) |
871
875
  | no code, `err.status === 403` | 403 | the game is not `live` or `testing` |
872
876
  | `err.status === 503` (the `error_code` names the cause) | 503 | card setup is not available right now; retry shortly |
@@ -876,7 +880,8 @@ Rate limit: 2000 per minute per game key with a per-IP floor; on a 429 honour `e
876
880
  **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
881
 
878
882
  ```ts
879
- // The processor-bound alternative (charges nothing). The player must already exist in this game.
883
+ // The processor-bound alternative (charges nothing). The player must already exist in this game:
884
+ // beginSetup never creates players (createSetupSession with playerName does).
880
885
  const setup = await server.cards.beginSetup({
881
886
  playerEmail: "member@example.com",
882
887
  setupReference: "setup-guild-42-member-7", // idempotency anchor: resend the same value on a retry
@@ -989,7 +994,31 @@ const r = await server.subscriptions.create({
989
994
 
990
995
  - **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
996
  - **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.
997
+ - **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:
998
+
999
+ ```ts
1000
+ // 1. create the member and mint the card link in one call
1001
+ const session = await server.cards.createSetupSession({
1002
+ playerEmail: "new@example.com",
1003
+ playerName: "New Member",
1004
+ successUrl: "https://your.game/billing/card-saved?member=new",
1005
+ });
1006
+ // 2. send the member to session.cardSetupUrl (top-level); they return to successUrl
1007
+ // 3. read the card, then subscribe with the paid trial
1008
+ const { cards } = await server.cards.list("new@example.com");
1009
+ const r = await server.subscriptions.create({
1010
+ clientRequestId: "new-member-pro",
1011
+ playerEmail: "new@example.com",
1012
+ playerName: "New Member",
1013
+ itemId: "pro-membership",
1014
+ amountUsd: "29.00",
1015
+ trialDays: 7,
1016
+ trialAmountUsd: "1.00",
1017
+ playerCardId: cards[0].id,
1018
+ consent: { consentAt: new Date().toISOString(), disclosedAmountUsd: "29.00", disclosedInterval: "month",
1019
+ disclosedTrialAmountUsd: "1.00", disclosedTrialDays: 7 },
1020
+ });
1021
+ ```
993
1022
  - **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
1023
  - **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
1024
  - **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`.
@@ -1232,7 +1261,8 @@ Match on `err.code` (and on `body.status` where the body carries one), never on
1232
1261
  | `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
1262
  | `NO_PAID_PERIOD` / `PERIOD_NOT_REFUNDABLE` / `AMOUNT_EXCEEDS_REMAINING` | refund refusals (the last carries `remaining_refundable_usd`) |
1234
1263
  | `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`) |
1264
+ | `.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`) |
1265
+ | `.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
1266
  | `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
1267
 
1238
1268
  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.
@@ -2271,7 +2301,7 @@ try {
2271
2301
  | `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
2302
  | `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
2303
  | `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` |
2304
+ | `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
2305
  | `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
2306
  | `cards.confirmSetup({ setupIntentId })` | `{ status, setupIntentId, card, alreadySaved, raw }`: finish a client-confirmed setup on the processor-bound path |
2277
2307
  | `cards.list(playerEmail)` | `{ cards: SavedCard[], raw }` — unexpired cards, newest first; `card.id` is the `playerCardId` |
@@ -744,14 +744,23 @@ var InvoError = class _InvoError extends Error {
744
744
  // ---- Card setup session (the INVO-hosted card page) ----
745
745
  /**
746
746
  * 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.
747
+ * in this game yet (`PLAYER_NOT_FOUND`, 404) and no `playerName` was sent. Send
748
+ * `playerName` (and optionally `playerPhone`) to create the member with their card.
749
+ * The same code comes back from `cards.beginSetup` and from `mintPlayerToken` for the
750
+ * same reason; those two never create players, so create the member first (for
751
+ * example with `createSetupSession` and a `playerName`, or a currency purchase).
751
752
  */
752
753
  get isPlayerNotFound() {
753
754
  return this.code === "PLAYER_NOT_FOUND";
754
755
  }
756
+ /**
757
+ * True when `cards.createSetupSession` was asked to create a new member (`playerName`
758
+ * sent) and INVO could not create them (`PLAYER_CREATE_FAILED`, 503). Nothing was
759
+ * created and no link was minted; call again.
760
+ */
761
+ get isPlayerCreateFailed() {
762
+ return this.code === "PLAYER_CREATE_FAILED";
763
+ }
755
764
  /**
756
765
  * True when `cards.createSetupSession` was refused because `playerEmail` was missing or
757
766
  * is not an email address (`INVALID_PLAYER_EMAIL`, 400).
@@ -764,7 +773,8 @@ var InvoError = class _InvoError extends Error {
764
773
  * `status === 0` is this SDK refusing a value before the network (every client-side
765
774
  * guard uses this code); `status === 400` is INVO refusing one, on
766
775
  * `cards.createSetupSession` a `successUrl` / `cancelUrl` that uses a script scheme
767
- * (`javascript:`, `data:`, `vbscript:`). http(s) and app deep-link schemes are fine.
776
+ * (`javascript:`, `data:`, `vbscript:`; http(s) and app deep-link schemes are fine), or,
777
+ * when the member is new, a `playerName` over 255 characters or a `playerPhone` over 30.
768
778
  */
769
779
  get isInvalidInput() {
770
780
  return this.code === "INVALID_INPUT";
@@ -1096,5 +1106,5 @@ function receiptFields(raw) {
1096
1106
  }
1097
1107
 
1098
1108
  export { Http, InvoError, assertSecureBaseUrl, creditFields, receiptFields, toDestinationsResult };
1099
- //# sourceMappingURL=chunk-BLY4NUMG.js.map
1100
- //# sourceMappingURL=chunk-BLY4NUMG.js.map
1109
+ //# sourceMappingURL=chunk-U4DEHGN4.js.map
1110
+ //# sourceMappingURL=chunk-U4DEHGN4.js.map
package/dist/index.cjs CHANGED
@@ -746,14 +746,23 @@ var InvoError = class _InvoError extends Error {
746
746
  // ---- Card setup session (the INVO-hosted card page) ----
747
747
  /**
748
748
  * 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.
749
+ * in this game yet (`PLAYER_NOT_FOUND`, 404) and no `playerName` was sent. Send
750
+ * `playerName` (and optionally `playerPhone`) to create the member with their card.
751
+ * The same code comes back from `cards.beginSetup` and from `mintPlayerToken` for the
752
+ * same reason; those two never create players, so create the member first (for
753
+ * example with `createSetupSession` and a `playerName`, or a currency purchase).
753
754
  */
754
755
  get isPlayerNotFound() {
755
756
  return this.code === "PLAYER_NOT_FOUND";
756
757
  }
758
+ /**
759
+ * True when `cards.createSetupSession` was asked to create a new member (`playerName`
760
+ * sent) and INVO could not create them (`PLAYER_CREATE_FAILED`, 503). Nothing was
761
+ * created and no link was minted; call again.
762
+ */
763
+ get isPlayerCreateFailed() {
764
+ return this.code === "PLAYER_CREATE_FAILED";
765
+ }
757
766
  /**
758
767
  * True when `cards.createSetupSession` was refused because `playerEmail` was missing or
759
768
  * is not an email address (`INVALID_PLAYER_EMAIL`, 400).
@@ -766,7 +775,8 @@ var InvoError = class _InvoError extends Error {
766
775
  * `status === 0` is this SDK refusing a value before the network (every client-side
767
776
  * guard uses this code); `status === 400` is INVO refusing one, on
768
777
  * `cards.createSetupSession` a `successUrl` / `cancelUrl` that uses a script scheme
769
- * (`javascript:`, `data:`, `vbscript:`). http(s) and app deep-link schemes are fine.
778
+ * (`javascript:`, `data:`, `vbscript:`; http(s) and app deep-link schemes are fine), or,
779
+ * when the member is new, a `playerName` over 255 characters or a `playerPhone` over 30.
770
780
  */
771
781
  get isInvalidInput() {
772
782
  return this.code === "INVALID_INPUT";
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-6uXUVBrm.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-6uXUVBrm.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-6uXUVBrm.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-6uXUVBrm.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-U4DEHGN4.js';
2
+ export { InvoError } from './chunk-U4DEHGN4.js';
3
3
 
4
4
  // src/shared/webauthn.ts
5
5
  function malformedOptions(field) {
package/dist/server.cjs CHANGED
@@ -748,14 +748,23 @@ var InvoError = class _InvoError extends Error {
748
748
  // ---- Card setup session (the INVO-hosted card page) ----
749
749
  /**
750
750
  * True when `cards.createSetupSession` was refused because the member does not exist
751
- * in this game yet (`PLAYER_NOT_FOUND`, 404). The card page never creates players;
752
- * create the member first (any endpoint that creates players, for example a currency
753
- * purchase), then mint the session again. The same code comes back from
754
- * `cards.beginSetup` and from `mintPlayerToken` for the same reason.
751
+ * in this game yet (`PLAYER_NOT_FOUND`, 404) and no `playerName` was sent. Send
752
+ * `playerName` (and optionally `playerPhone`) to create the member with their card.
753
+ * The same code comes back from `cards.beginSetup` and from `mintPlayerToken` for the
754
+ * same reason; those two never create players, so create the member first (for
755
+ * example with `createSetupSession` and a `playerName`, or a currency purchase).
755
756
  */
756
757
  get isPlayerNotFound() {
757
758
  return this.code === "PLAYER_NOT_FOUND";
758
759
  }
760
+ /**
761
+ * True when `cards.createSetupSession` was asked to create a new member (`playerName`
762
+ * sent) and INVO could not create them (`PLAYER_CREATE_FAILED`, 503). Nothing was
763
+ * created and no link was minted; call again.
764
+ */
765
+ get isPlayerCreateFailed() {
766
+ return this.code === "PLAYER_CREATE_FAILED";
767
+ }
759
768
  /**
760
769
  * True when `cards.createSetupSession` was refused because `playerEmail` was missing or
761
770
  * is not an email address (`INVALID_PLAYER_EMAIL`, 400).
@@ -768,7 +777,8 @@ var InvoError = class _InvoError extends Error {
768
777
  * `status === 0` is this SDK refusing a value before the network (every client-side
769
778
  * guard uses this code); `status === 400` is INVO refusing one, on
770
779
  * `cards.createSetupSession` a `successUrl` / `cancelUrl` that uses a script scheme
771
- * (`javascript:`, `data:`, `vbscript:`). http(s) and app deep-link schemes are fine.
780
+ * (`javascript:`, `data:`, `vbscript:`; http(s) and app deep-link schemes are fine), or,
781
+ * when the member is new, a `playerName` over 255 characters or a `playerPhone` over 30.
772
782
  */
773
783
  get isInvalidInput() {
774
784
  return this.code === "INVALID_INPUT";
@@ -1100,7 +1110,7 @@ function receiptFields(raw) {
1100
1110
  }
1101
1111
 
1102
1112
  // src/version.ts
1103
- var SDK_VERSION = "3.14.1";
1113
+ var SDK_VERSION = "3.15.0";
1104
1114
 
1105
1115
  // src/shared/types.ts
1106
1116
  function isRefundPendingApproval(r) {
@@ -2609,9 +2619,14 @@ var CardsServer = class {
2609
2619
  * one, then `cards.list`) and one redirect. No browser code, no processor script, no
2610
2620
  * client secret; INVO can change card processor without you changing anything.
2611
2621
  *
2612
- * The member must already exist in this game (`err.isPlayerNotFound`, 404); the page
2613
- * never creates players. Send the member to `result.cardSetupUrl` top-level (do not
2614
- * frame it). The page says in words that no money moves, saves the card, and then
2622
+ * A member this game already knows needs only `playerEmail`. A BRAND-NEW member (a
2623
+ * first-time signup, for example before a paid trial) is created here when you also
2624
+ * send `playerName` (and optionally `playerPhone`), exactly as `subscriptions.create`
2625
+ * creates one: same phone-share gate, same wallet binding. Without `playerName` an
2626
+ * unknown member is `err.isPlayerNotFound` (404) and nothing is created. A known member
2627
+ * is never re-created or renamed by this call; `playerName` / `playerPhone` are used
2628
+ * only when the member is new. Send the member to `result.cardSetupUrl` top-level (do
2629
+ * not frame it). The page says in words that no money moves, saves the card, and then
2615
2630
  * redirects to `successUrl` (or shows "Card saved" when you gave none). The saved card
2616
2631
  * appears in {@link list} immediately, carries the off-session consent a subscription
2617
2632
  * needs, and is indistinguishable from one saved any other way. There is no event for
@@ -2626,10 +2641,15 @@ var CardsServer = class {
2626
2641
  *
2627
2642
  * Refusals: `err.isInvalidPlayerEmail` (400, a non-email string; a missing or blank
2628
2643
  * `playerEmail` is refused here first with `status: 0`), `err.isPlayerNotFound` (404),
2629
- * `err.isInvalidInput` (400: a script-scheme `successUrl` / `cancelUrl`; the SDK
2630
- * refuses the same values first with `status: 0`), 401 / 403 on the key or the game
2631
- * (body `{ message }`, no code), 503 when card setup is not available right now.
2632
- * Never auto-retried: each call mints a fresh link, so on a timeout call it again.
2644
+ * `err.isInvalidInput` (400: a script-scheme `successUrl` / `cancelUrl`, or, when the
2645
+ * member is new, a `playerName` over 255 characters or a `playerPhone` over 30; the SDK
2646
+ * refuses script schemes, a blank or over-long `playerName` and a non-E.164
2647
+ * `playerPhone` first with `status: 0`), `err.isPhoneShareApprovalRequired` (409, creating the member needs the
2648
+ * existing phone owner's approval; same body as `subscriptions.create`),
2649
+ * `err.isPlayerCreateFailed` (503, the member could not be created; call again),
2650
+ * 401 / 403 on the key or the game (body `{ message }`, no code), 503 when card setup
2651
+ * is not available right now. Never auto-retried: each call mints a fresh link, so on a
2652
+ * timeout call it again.
2633
2653
  */
2634
2654
  async createSetupSession(input, opts) {
2635
2655
  if (typeof input.playerEmail !== "string" || !input.playerEmail.trim()) {
@@ -2646,7 +2666,16 @@ var CardsServer = class {
2646
2666
  if (input.metadata !== void 0 && (input.metadata === null || typeof input.metadata !== "object" || Array.isArray(input.metadata))) {
2647
2667
  throw invalidInput("metadata", input.metadata, "must be a plain object");
2648
2668
  }
2669
+ if (input.playerName !== void 0) {
2670
+ if (typeof input.playerName !== "string" || !input.playerName.trim()) {
2671
+ throw invalidInput("playerName", input.playerName, "must be a non-empty string");
2672
+ }
2673
+ if (input.playerName.trim().length > 255) throw invalidInput("playerName", input.playerName, "must be at most 255 characters");
2674
+ }
2675
+ if (input.playerPhone !== void 0) assertE164(input.playerPhone, "playerPhone");
2649
2676
  const body = { player_email: input.playerEmail };
2677
+ if (input.playerName) body["player_name"] = input.playerName;
2678
+ if (input.playerPhone) body["player_phone"] = input.playerPhone;
2650
2679
  if (input.successUrl) body["success_url"] = input.successUrl;
2651
2680
  if (input.cancelUrl) body["cancel_url"] = input.cancelUrl;
2652
2681
  if (input.metadata) body["metadata"] = input.metadata;
package/dist/server.d.cts CHANGED
@@ -1,12 +1,12 @@
1
- import { I as InvoError, H as Http, x as AuthHeader, y as CardSetupSessionInput, g as CallOptions, z as CardSetupSessionResult, F as CardSetupInput, G as CardSetupResult, J as CardSetupConfirmInput, K as CardSetupConfirmResult, N as PlayerCardsResult, O as PlatformPurchaseInput, Q as PlatformPurchaseResult, S as PlatformOrderStatusResult, T as PlatformRefundInput, U as PlatformRefundResult, X as CreateSubscriptionInput, Y as SubscriptionResult, Z as GetSubscriptionOptions, _ as GetSubscriptionResult, $ as ListSubscriptionsOptions, a0 as SubscriptionListResult, a1 as CancelSubscriptionOptions, a2 as CancelResult, a3 as ChangeAmountResult, a4 as SetPaymentMethodInput, a5 as SetPaymentMethodResult, a6 as RefundSubscriptionInput, a7 as RefundResult, a8 as SteamSubscriptionInitInput, a9 as SteamInitResult, aa as SteamFinalizeSubscriptionResult, ab as SandboxClockResult, ac as SandboxFailureOutcome, ad as SandboxForceFailureOptions, ae as SandboxForceAuthChallengeOptions, af as ServerConfig, ag as PlayerToken, ah as InitiateSendInput, ai as InitiateResult, aj as InitiateTransferInput, ak as CreateCheckoutInput, al as CreateCheckoutResult, am as PurchaseInput, an as PurchaseResult, ao as CurrencyPurchaseQuoteInput, ap as CurrencyPurchaseQuote, aq as ConfirmPaymentResult, ar as OrderDetailsResult, as as SteamPacksQuery, at as SteamPacksResult, au as SteamInitPurchaseInput, av as SteamInitPurchaseResult, aw as SteamFinalizeInput, ax as SteamFinalizeResult, ay as PurchaseItemInput, az as PurchaseItemResult, aA as ItemHistoryQuery, aB as ItemHistoryResult, aC as ItemOrderQuery, aD as PlayerBalanceQuery, aE as PlayerBalanceResult, aF as InboundPendingQuery, aG as InboundPendingResult, aH as LinkedIdentitiesQuery, aI as LinkedIdentitiesResult, aJ as SmsVerifyResult, aK as ClaimTransferInput, aL as ClaimResult, aM as ClaimCurrencyInput, aN as TransactionStatusResult, aO as GuardianApprovalStatusResult, aP as ServerDestinationsQuery, k as DestinationsResult, aQ as PhoneShareContact, aR as PhoneShareInitiateResult, aS as PhoneShareApproveInput, aT as PhoneShareApproveResult, aU as PhoneShareStatusResult, aV as BeginDeviceApprovalInput, aW as DeviceApprovalGrant, aX as PollDeviceApprovalInput, aY as DeviceApprovalPollResult, aZ as ConfirmDeviceEnrollmentInput, a_ as ConfirmDeviceEnrollmentResult, a$ as ApproveWithDeviceCodeInput, b0 as DeviceApprovalSettleResult, b1 as CompleteDeviceApprovalInput, b2 as CompleteDeviceApprovalResult } from './types-CD83iV3D.cjs';
2
- export { b3 as CardSetupStatus, b4 as CurrencyBalance, b5 as CurrencyPurchaseQuoteBreakdown, p as DestinationGame, b6 as DeviceApprovalChannel, b7 as DeviceApprovalEnrollment, b8 as DeviceApprovalFlow, b9 as DeviceApprovalPollStatus, ba as DeviceEnrollmentDecision, bb as DeviceEnrollmentRespond, bc as FeeTakenFrom, bd as FirstCharge, be as FirstChargeStatus, bf as FundingSource, bg as InboundPendingItem, q as InvoErrorInfo, r as InvoHooks, s as InvoRequestInfo, t as InvoResponseInfo, bh as LinkedIdentityEmail, bi as PlatformPurchaseStatus, w as Rail, bj as RefundInitiation, bk as RefundPendingApproval, bl as RefundProcessingFeeBasis, bm as RefundReceipt, bn as RefundRevenueShareAttribution, bo as RefundWarning, bp as SandboxClockState, bq as SavedCard, br as SteamPack, bs as SteamUserSession, bt as Subscription, bu as SubscriptionBaseInput, bv as SubscriptionConsent, bw as SubscriptionConsentInput, bx as SubscriptionFundingRail, by as SubscriptionInterval, bz as SubscriptionRevenueShare, bA as SubscriptionRevenueShareInput, bB as SubscriptionStatus, bC as UnacknowledgedPurchaseOutcome, V as VerificationMethod, bD as isRefundPendingApproval } from './types-CD83iV3D.cjs';
1
+ import { I as InvoError, H as Http, x as AuthHeader, y as CardSetupSessionInput, g as CallOptions, z as CardSetupSessionResult, F as CardSetupInput, G as CardSetupResult, J as CardSetupConfirmInput, K as CardSetupConfirmResult, N as PlayerCardsResult, O as PlatformPurchaseInput, Q as PlatformPurchaseResult, S as PlatformOrderStatusResult, T as PlatformRefundInput, U as PlatformRefundResult, X as CreateSubscriptionInput, Y as SubscriptionResult, Z as GetSubscriptionOptions, _ as GetSubscriptionResult, $ as ListSubscriptionsOptions, a0 as SubscriptionListResult, a1 as CancelSubscriptionOptions, a2 as CancelResult, a3 as ChangeAmountResult, a4 as SetPaymentMethodInput, a5 as SetPaymentMethodResult, a6 as RefundSubscriptionInput, a7 as RefundResult, a8 as SteamSubscriptionInitInput, a9 as SteamInitResult, aa as SteamFinalizeSubscriptionResult, ab as SandboxClockResult, ac as SandboxFailureOutcome, ad as SandboxForceFailureOptions, ae as SandboxForceAuthChallengeOptions, af as ServerConfig, ag as PlayerToken, ah as InitiateSendInput, ai as InitiateResult, aj as InitiateTransferInput, ak as CreateCheckoutInput, al as CreateCheckoutResult, am as PurchaseInput, an as PurchaseResult, ao as CurrencyPurchaseQuoteInput, ap as CurrencyPurchaseQuote, aq as ConfirmPaymentResult, ar as OrderDetailsResult, as as SteamPacksQuery, at as SteamPacksResult, au as SteamInitPurchaseInput, av as SteamInitPurchaseResult, aw as SteamFinalizeInput, ax as SteamFinalizeResult, ay as PurchaseItemInput, az as PurchaseItemResult, aA as ItemHistoryQuery, aB as ItemHistoryResult, aC as ItemOrderQuery, aD as PlayerBalanceQuery, aE as PlayerBalanceResult, aF as InboundPendingQuery, aG as InboundPendingResult, aH as LinkedIdentitiesQuery, aI as LinkedIdentitiesResult, aJ as SmsVerifyResult, aK as ClaimTransferInput, aL as ClaimResult, aM as ClaimCurrencyInput, aN as TransactionStatusResult, aO as GuardianApprovalStatusResult, aP as ServerDestinationsQuery, k as DestinationsResult, aQ as PhoneShareContact, aR as PhoneShareInitiateResult, aS as PhoneShareApproveInput, aT as PhoneShareApproveResult, aU as PhoneShareStatusResult, aV as BeginDeviceApprovalInput, aW as DeviceApprovalGrant, aX as PollDeviceApprovalInput, aY as DeviceApprovalPollResult, aZ as ConfirmDeviceEnrollmentInput, a_ as ConfirmDeviceEnrollmentResult, a$ as ApproveWithDeviceCodeInput, b0 as DeviceApprovalSettleResult, b1 as CompleteDeviceApprovalInput, b2 as CompleteDeviceApprovalResult } from './types-6uXUVBrm.cjs';
2
+ export { b3 as CardSetupStatus, b4 as CurrencyBalance, b5 as CurrencyPurchaseQuoteBreakdown, p as DestinationGame, b6 as DeviceApprovalChannel, b7 as DeviceApprovalEnrollment, b8 as DeviceApprovalFlow, b9 as DeviceApprovalPollStatus, ba as DeviceEnrollmentDecision, bb as DeviceEnrollmentRespond, bc as FeeTakenFrom, bd as FirstCharge, be as FirstChargeStatus, bf as FundingSource, bg as InboundPendingItem, q as InvoErrorInfo, r as InvoHooks, s as InvoRequestInfo, t as InvoResponseInfo, bh as LinkedIdentityEmail, bi as PlatformPurchaseStatus, w as Rail, bj as RefundInitiation, bk as RefundPendingApproval, bl as RefundProcessingFeeBasis, bm as RefundReceipt, bn as RefundRevenueShareAttribution, bo as RefundWarning, bp as SandboxClockState, bq as SavedCard, br as SteamPack, bs as SteamUserSession, bt as Subscription, bu as SubscriptionBaseInput, bv as SubscriptionConsent, bw as SubscriptionConsentInput, bx as SubscriptionFundingRail, by as SubscriptionInterval, bz as SubscriptionRevenueShare, bA as SubscriptionRevenueShareInput, bB as SubscriptionStatus, bC as UnacknowledgedPurchaseOutcome, V as VerificationMethod, bD as isRefundPendingApproval } from './types-6uXUVBrm.cjs';
3
3
 
4
4
  /**
5
5
  * The package version, as sent in the server User-Agent. A test pins this to
6
6
  * `package.json` so it cannot drift silently (it did: the UA read 3.0.0 through 3.7.0).
7
7
  * Bump it with the changeset flow.
8
8
  */
9
- declare const SDK_VERSION = "3.14.1";
9
+ declare const SDK_VERSION = "3.15.0";
10
10
 
11
11
  interface VerifyWebhookOptions {
12
12
  /** Max age of the signed timestamp, in seconds. Default 300 (5 min). */
@@ -884,9 +884,14 @@ declare class CardsServer {
884
884
  * one, then `cards.list`) and one redirect. No browser code, no processor script, no
885
885
  * client secret; INVO can change card processor without you changing anything.
886
886
  *
887
- * The member must already exist in this game (`err.isPlayerNotFound`, 404); the page
888
- * never creates players. Send the member to `result.cardSetupUrl` top-level (do not
889
- * frame it). The page says in words that no money moves, saves the card, and then
887
+ * A member this game already knows needs only `playerEmail`. A BRAND-NEW member (a
888
+ * first-time signup, for example before a paid trial) is created here when you also
889
+ * send `playerName` (and optionally `playerPhone`), exactly as `subscriptions.create`
890
+ * creates one: same phone-share gate, same wallet binding. Without `playerName` an
891
+ * unknown member is `err.isPlayerNotFound` (404) and nothing is created. A known member
892
+ * is never re-created or renamed by this call; `playerName` / `playerPhone` are used
893
+ * only when the member is new. Send the member to `result.cardSetupUrl` top-level (do
894
+ * not frame it). The page says in words that no money moves, saves the card, and then
890
895
  * redirects to `successUrl` (or shows "Card saved" when you gave none). The saved card
891
896
  * appears in {@link list} immediately, carries the off-session consent a subscription
892
897
  * needs, and is indistinguishable from one saved any other way. There is no event for
@@ -901,10 +906,15 @@ declare class CardsServer {
901
906
  *
902
907
  * Refusals: `err.isInvalidPlayerEmail` (400, a non-email string; a missing or blank
903
908
  * `playerEmail` is refused here first with `status: 0`), `err.isPlayerNotFound` (404),
904
- * `err.isInvalidInput` (400: a script-scheme `successUrl` / `cancelUrl`; the SDK
905
- * refuses the same values first with `status: 0`), 401 / 403 on the key or the game
906
- * (body `{ message }`, no code), 503 when card setup is not available right now.
907
- * Never auto-retried: each call mints a fresh link, so on a timeout call it again.
909
+ * `err.isInvalidInput` (400: a script-scheme `successUrl` / `cancelUrl`, or, when the
910
+ * member is new, a `playerName` over 255 characters or a `playerPhone` over 30; the SDK
911
+ * refuses script schemes, a blank or over-long `playerName` and a non-E.164
912
+ * `playerPhone` first with `status: 0`), `err.isPhoneShareApprovalRequired` (409, creating the member needs the
913
+ * existing phone owner's approval; same body as `subscriptions.create`),
914
+ * `err.isPlayerCreateFailed` (503, the member could not be created; call again),
915
+ * 401 / 403 on the key or the game (body `{ message }`, no code), 503 when card setup
916
+ * is not available right now. Never auto-retried: each call mints a fresh link, so on a
917
+ * timeout call it again.
908
918
  */
909
919
  createSetupSession(input: CardSetupSessionInput, opts?: CallOptions): Promise<CardSetupSessionResult>;
910
920
  /**
package/dist/server.d.ts CHANGED
@@ -1,12 +1,12 @@
1
- import { I as InvoError, H as Http, x as AuthHeader, y as CardSetupSessionInput, g as CallOptions, z as CardSetupSessionResult, F as CardSetupInput, G as CardSetupResult, J as CardSetupConfirmInput, K as CardSetupConfirmResult, N as PlayerCardsResult, O as PlatformPurchaseInput, Q as PlatformPurchaseResult, S as PlatformOrderStatusResult, T as PlatformRefundInput, U as PlatformRefundResult, X as CreateSubscriptionInput, Y as SubscriptionResult, Z as GetSubscriptionOptions, _ as GetSubscriptionResult, $ as ListSubscriptionsOptions, a0 as SubscriptionListResult, a1 as CancelSubscriptionOptions, a2 as CancelResult, a3 as ChangeAmountResult, a4 as SetPaymentMethodInput, a5 as SetPaymentMethodResult, a6 as RefundSubscriptionInput, a7 as RefundResult, a8 as SteamSubscriptionInitInput, a9 as SteamInitResult, aa as SteamFinalizeSubscriptionResult, ab as SandboxClockResult, ac as SandboxFailureOutcome, ad as SandboxForceFailureOptions, ae as SandboxForceAuthChallengeOptions, af as ServerConfig, ag as PlayerToken, ah as InitiateSendInput, ai as InitiateResult, aj as InitiateTransferInput, ak as CreateCheckoutInput, al as CreateCheckoutResult, am as PurchaseInput, an as PurchaseResult, ao as CurrencyPurchaseQuoteInput, ap as CurrencyPurchaseQuote, aq as ConfirmPaymentResult, ar as OrderDetailsResult, as as SteamPacksQuery, at as SteamPacksResult, au as SteamInitPurchaseInput, av as SteamInitPurchaseResult, aw as SteamFinalizeInput, ax as SteamFinalizeResult, ay as PurchaseItemInput, az as PurchaseItemResult, aA as ItemHistoryQuery, aB as ItemHistoryResult, aC as ItemOrderQuery, aD as PlayerBalanceQuery, aE as PlayerBalanceResult, aF as InboundPendingQuery, aG as InboundPendingResult, aH as LinkedIdentitiesQuery, aI as LinkedIdentitiesResult, aJ as SmsVerifyResult, aK as ClaimTransferInput, aL as ClaimResult, aM as ClaimCurrencyInput, aN as TransactionStatusResult, aO as GuardianApprovalStatusResult, aP as ServerDestinationsQuery, k as DestinationsResult, aQ as PhoneShareContact, aR as PhoneShareInitiateResult, aS as PhoneShareApproveInput, aT as PhoneShareApproveResult, aU as PhoneShareStatusResult, aV as BeginDeviceApprovalInput, aW as DeviceApprovalGrant, aX as PollDeviceApprovalInput, aY as DeviceApprovalPollResult, aZ as ConfirmDeviceEnrollmentInput, a_ as ConfirmDeviceEnrollmentResult, a$ as ApproveWithDeviceCodeInput, b0 as DeviceApprovalSettleResult, b1 as CompleteDeviceApprovalInput, b2 as CompleteDeviceApprovalResult } from './types-CD83iV3D.js';
2
- export { b3 as CardSetupStatus, b4 as CurrencyBalance, b5 as CurrencyPurchaseQuoteBreakdown, p as DestinationGame, b6 as DeviceApprovalChannel, b7 as DeviceApprovalEnrollment, b8 as DeviceApprovalFlow, b9 as DeviceApprovalPollStatus, ba as DeviceEnrollmentDecision, bb as DeviceEnrollmentRespond, bc as FeeTakenFrom, bd as FirstCharge, be as FirstChargeStatus, bf as FundingSource, bg as InboundPendingItem, q as InvoErrorInfo, r as InvoHooks, s as InvoRequestInfo, t as InvoResponseInfo, bh as LinkedIdentityEmail, bi as PlatformPurchaseStatus, w as Rail, bj as RefundInitiation, bk as RefundPendingApproval, bl as RefundProcessingFeeBasis, bm as RefundReceipt, bn as RefundRevenueShareAttribution, bo as RefundWarning, bp as SandboxClockState, bq as SavedCard, br as SteamPack, bs as SteamUserSession, bt as Subscription, bu as SubscriptionBaseInput, bv as SubscriptionConsent, bw as SubscriptionConsentInput, bx as SubscriptionFundingRail, by as SubscriptionInterval, bz as SubscriptionRevenueShare, bA as SubscriptionRevenueShareInput, bB as SubscriptionStatus, bC as UnacknowledgedPurchaseOutcome, V as VerificationMethod, bD as isRefundPendingApproval } from './types-CD83iV3D.js';
1
+ import { I as InvoError, H as Http, x as AuthHeader, y as CardSetupSessionInput, g as CallOptions, z as CardSetupSessionResult, F as CardSetupInput, G as CardSetupResult, J as CardSetupConfirmInput, K as CardSetupConfirmResult, N as PlayerCardsResult, O as PlatformPurchaseInput, Q as PlatformPurchaseResult, S as PlatformOrderStatusResult, T as PlatformRefundInput, U as PlatformRefundResult, X as CreateSubscriptionInput, Y as SubscriptionResult, Z as GetSubscriptionOptions, _ as GetSubscriptionResult, $ as ListSubscriptionsOptions, a0 as SubscriptionListResult, a1 as CancelSubscriptionOptions, a2 as CancelResult, a3 as ChangeAmountResult, a4 as SetPaymentMethodInput, a5 as SetPaymentMethodResult, a6 as RefundSubscriptionInput, a7 as RefundResult, a8 as SteamSubscriptionInitInput, a9 as SteamInitResult, aa as SteamFinalizeSubscriptionResult, ab as SandboxClockResult, ac as SandboxFailureOutcome, ad as SandboxForceFailureOptions, ae as SandboxForceAuthChallengeOptions, af as ServerConfig, ag as PlayerToken, ah as InitiateSendInput, ai as InitiateResult, aj as InitiateTransferInput, ak as CreateCheckoutInput, al as CreateCheckoutResult, am as PurchaseInput, an as PurchaseResult, ao as CurrencyPurchaseQuoteInput, ap as CurrencyPurchaseQuote, aq as ConfirmPaymentResult, ar as OrderDetailsResult, as as SteamPacksQuery, at as SteamPacksResult, au as SteamInitPurchaseInput, av as SteamInitPurchaseResult, aw as SteamFinalizeInput, ax as SteamFinalizeResult, ay as PurchaseItemInput, az as PurchaseItemResult, aA as ItemHistoryQuery, aB as ItemHistoryResult, aC as ItemOrderQuery, aD as PlayerBalanceQuery, aE as PlayerBalanceResult, aF as InboundPendingQuery, aG as InboundPendingResult, aH as LinkedIdentitiesQuery, aI as LinkedIdentitiesResult, aJ as SmsVerifyResult, aK as ClaimTransferInput, aL as ClaimResult, aM as ClaimCurrencyInput, aN as TransactionStatusResult, aO as GuardianApprovalStatusResult, aP as ServerDestinationsQuery, k as DestinationsResult, aQ as PhoneShareContact, aR as PhoneShareInitiateResult, aS as PhoneShareApproveInput, aT as PhoneShareApproveResult, aU as PhoneShareStatusResult, aV as BeginDeviceApprovalInput, aW as DeviceApprovalGrant, aX as PollDeviceApprovalInput, aY as DeviceApprovalPollResult, aZ as ConfirmDeviceEnrollmentInput, a_ as ConfirmDeviceEnrollmentResult, a$ as ApproveWithDeviceCodeInput, b0 as DeviceApprovalSettleResult, b1 as CompleteDeviceApprovalInput, b2 as CompleteDeviceApprovalResult } from './types-6uXUVBrm.js';
2
+ export { b3 as CardSetupStatus, b4 as CurrencyBalance, b5 as CurrencyPurchaseQuoteBreakdown, p as DestinationGame, b6 as DeviceApprovalChannel, b7 as DeviceApprovalEnrollment, b8 as DeviceApprovalFlow, b9 as DeviceApprovalPollStatus, ba as DeviceEnrollmentDecision, bb as DeviceEnrollmentRespond, bc as FeeTakenFrom, bd as FirstCharge, be as FirstChargeStatus, bf as FundingSource, bg as InboundPendingItem, q as InvoErrorInfo, r as InvoHooks, s as InvoRequestInfo, t as InvoResponseInfo, bh as LinkedIdentityEmail, bi as PlatformPurchaseStatus, w as Rail, bj as RefundInitiation, bk as RefundPendingApproval, bl as RefundProcessingFeeBasis, bm as RefundReceipt, bn as RefundRevenueShareAttribution, bo as RefundWarning, bp as SandboxClockState, bq as SavedCard, br as SteamPack, bs as SteamUserSession, bt as Subscription, bu as SubscriptionBaseInput, bv as SubscriptionConsent, bw as SubscriptionConsentInput, bx as SubscriptionFundingRail, by as SubscriptionInterval, bz as SubscriptionRevenueShare, bA as SubscriptionRevenueShareInput, bB as SubscriptionStatus, bC as UnacknowledgedPurchaseOutcome, V as VerificationMethod, bD as isRefundPendingApproval } from './types-6uXUVBrm.js';
3
3
 
4
4
  /**
5
5
  * The package version, as sent in the server User-Agent. A test pins this to
6
6
  * `package.json` so it cannot drift silently (it did: the UA read 3.0.0 through 3.7.0).
7
7
  * Bump it with the changeset flow.
8
8
  */
9
- declare const SDK_VERSION = "3.14.1";
9
+ declare const SDK_VERSION = "3.15.0";
10
10
 
11
11
  interface VerifyWebhookOptions {
12
12
  /** Max age of the signed timestamp, in seconds. Default 300 (5 min). */
@@ -884,9 +884,14 @@ declare class CardsServer {
884
884
  * one, then `cards.list`) and one redirect. No browser code, no processor script, no
885
885
  * client secret; INVO can change card processor without you changing anything.
886
886
  *
887
- * The member must already exist in this game (`err.isPlayerNotFound`, 404); the page
888
- * never creates players. Send the member to `result.cardSetupUrl` top-level (do not
889
- * frame it). The page says in words that no money moves, saves the card, and then
887
+ * A member this game already knows needs only `playerEmail`. A BRAND-NEW member (a
888
+ * first-time signup, for example before a paid trial) is created here when you also
889
+ * send `playerName` (and optionally `playerPhone`), exactly as `subscriptions.create`
890
+ * creates one: same phone-share gate, same wallet binding. Without `playerName` an
891
+ * unknown member is `err.isPlayerNotFound` (404) and nothing is created. A known member
892
+ * is never re-created or renamed by this call; `playerName` / `playerPhone` are used
893
+ * only when the member is new. Send the member to `result.cardSetupUrl` top-level (do
894
+ * not frame it). The page says in words that no money moves, saves the card, and then
890
895
  * redirects to `successUrl` (or shows "Card saved" when you gave none). The saved card
891
896
  * appears in {@link list} immediately, carries the off-session consent a subscription
892
897
  * needs, and is indistinguishable from one saved any other way. There is no event for
@@ -901,10 +906,15 @@ declare class CardsServer {
901
906
  *
902
907
  * Refusals: `err.isInvalidPlayerEmail` (400, a non-email string; a missing or blank
903
908
  * `playerEmail` is refused here first with `status: 0`), `err.isPlayerNotFound` (404),
904
- * `err.isInvalidInput` (400: a script-scheme `successUrl` / `cancelUrl`; the SDK
905
- * refuses the same values first with `status: 0`), 401 / 403 on the key or the game
906
- * (body `{ message }`, no code), 503 when card setup is not available right now.
907
- * Never auto-retried: each call mints a fresh link, so on a timeout call it again.
909
+ * `err.isInvalidInput` (400: a script-scheme `successUrl` / `cancelUrl`, or, when the
910
+ * member is new, a `playerName` over 255 characters or a `playerPhone` over 30; the SDK
911
+ * refuses script schemes, a blank or over-long `playerName` and a non-E.164
912
+ * `playerPhone` first with `status: 0`), `err.isPhoneShareApprovalRequired` (409, creating the member needs the
913
+ * existing phone owner's approval; same body as `subscriptions.create`),
914
+ * `err.isPlayerCreateFailed` (503, the member could not be created; call again),
915
+ * 401 / 403 on the key or the game (body `{ message }`, no code), 503 when card setup
916
+ * is not available right now. Never auto-retried: each call mints a fresh link, so on a
917
+ * timeout call it again.
908
918
  */
909
919
  createSetupSession(input: CardSetupSessionInput, opts?: CallOptions): Promise<CardSetupSessionResult>;
910
920
  /**
package/dist/server.js CHANGED
@@ -1,9 +1,9 @@
1
- import { InvoError, receiptFields, assertSecureBaseUrl, Http, creditFields, toDestinationsResult } from './chunk-BLY4NUMG.js';
2
- export { InvoError } from './chunk-BLY4NUMG.js';
1
+ import { InvoError, receiptFields, assertSecureBaseUrl, Http, creditFields, toDestinationsResult } from './chunk-U4DEHGN4.js';
2
+ export { InvoError } from './chunk-U4DEHGN4.js';
3
3
  import { createHmac, timingSafeEqual } from 'crypto';
4
4
 
5
5
  // src/version.ts
6
- var SDK_VERSION = "3.14.1";
6
+ var SDK_VERSION = "3.15.0";
7
7
 
8
8
  // src/shared/types.ts
9
9
  function isRefundPendingApproval(r) {
@@ -1512,9 +1512,14 @@ var CardsServer = class {
1512
1512
  * one, then `cards.list`) and one redirect. No browser code, no processor script, no
1513
1513
  * client secret; INVO can change card processor without you changing anything.
1514
1514
  *
1515
- * The member must already exist in this game (`err.isPlayerNotFound`, 404); the page
1516
- * never creates players. Send the member to `result.cardSetupUrl` top-level (do not
1517
- * frame it). The page says in words that no money moves, saves the card, and then
1515
+ * A member this game already knows needs only `playerEmail`. A BRAND-NEW member (a
1516
+ * first-time signup, for example before a paid trial) is created here when you also
1517
+ * send `playerName` (and optionally `playerPhone`), exactly as `subscriptions.create`
1518
+ * creates one: same phone-share gate, same wallet binding. Without `playerName` an
1519
+ * unknown member is `err.isPlayerNotFound` (404) and nothing is created. A known member
1520
+ * is never re-created or renamed by this call; `playerName` / `playerPhone` are used
1521
+ * only when the member is new. Send the member to `result.cardSetupUrl` top-level (do
1522
+ * not frame it). The page says in words that no money moves, saves the card, and then
1518
1523
  * redirects to `successUrl` (or shows "Card saved" when you gave none). The saved card
1519
1524
  * appears in {@link list} immediately, carries the off-session consent a subscription
1520
1525
  * needs, and is indistinguishable from one saved any other way. There is no event for
@@ -1529,10 +1534,15 @@ var CardsServer = class {
1529
1534
  *
1530
1535
  * Refusals: `err.isInvalidPlayerEmail` (400, a non-email string; a missing or blank
1531
1536
  * `playerEmail` is refused here first with `status: 0`), `err.isPlayerNotFound` (404),
1532
- * `err.isInvalidInput` (400: a script-scheme `successUrl` / `cancelUrl`; the SDK
1533
- * refuses the same values first with `status: 0`), 401 / 403 on the key or the game
1534
- * (body `{ message }`, no code), 503 when card setup is not available right now.
1535
- * Never auto-retried: each call mints a fresh link, so on a timeout call it again.
1537
+ * `err.isInvalidInput` (400: a script-scheme `successUrl` / `cancelUrl`, or, when the
1538
+ * member is new, a `playerName` over 255 characters or a `playerPhone` over 30; the SDK
1539
+ * refuses script schemes, a blank or over-long `playerName` and a non-E.164
1540
+ * `playerPhone` first with `status: 0`), `err.isPhoneShareApprovalRequired` (409, creating the member needs the
1541
+ * existing phone owner's approval; same body as `subscriptions.create`),
1542
+ * `err.isPlayerCreateFailed` (503, the member could not be created; call again),
1543
+ * 401 / 403 on the key or the game (body `{ message }`, no code), 503 when card setup
1544
+ * is not available right now. Never auto-retried: each call mints a fresh link, so on a
1545
+ * timeout call it again.
1536
1546
  */
1537
1547
  async createSetupSession(input, opts) {
1538
1548
  if (typeof input.playerEmail !== "string" || !input.playerEmail.trim()) {
@@ -1549,7 +1559,16 @@ var CardsServer = class {
1549
1559
  if (input.metadata !== void 0 && (input.metadata === null || typeof input.metadata !== "object" || Array.isArray(input.metadata))) {
1550
1560
  throw invalidInput("metadata", input.metadata, "must be a plain object");
1551
1561
  }
1562
+ if (input.playerName !== void 0) {
1563
+ if (typeof input.playerName !== "string" || !input.playerName.trim()) {
1564
+ throw invalidInput("playerName", input.playerName, "must be a non-empty string");
1565
+ }
1566
+ if (input.playerName.trim().length > 255) throw invalidInput("playerName", input.playerName, "must be at most 255 characters");
1567
+ }
1568
+ if (input.playerPhone !== void 0) assertE164(input.playerPhone, "playerPhone");
1552
1569
  const body = { player_email: input.playerEmail };
1570
+ if (input.playerName) body["player_name"] = input.playerName;
1571
+ if (input.playerPhone) body["player_phone"] = input.playerPhone;
1553
1572
  if (input.successUrl) body["success_url"] = input.successUrl;
1554
1573
  if (input.cancelUrl) body["cancel_url"] = input.cancelUrl;
1555
1574
  if (input.metadata) body["metadata"] = input.metadata;
@@ -560,12 +560,19 @@ declare class InvoError extends Error {
560
560
  get isGameNotLive(): boolean;
561
561
  /**
562
562
  * True when `cards.createSetupSession` was refused because the member does not exist
563
- * in this game yet (`PLAYER_NOT_FOUND`, 404). The card page never creates players;
564
- * create the member first (any endpoint that creates players, for example a currency
565
- * purchase), then mint the session again. The same code comes back from
566
- * `cards.beginSetup` and from `mintPlayerToken` for the same reason.
563
+ * in this game yet (`PLAYER_NOT_FOUND`, 404) and no `playerName` was sent. Send
564
+ * `playerName` (and optionally `playerPhone`) to create the member with their card.
565
+ * The same code comes back from `cards.beginSetup` and from `mintPlayerToken` for the
566
+ * same reason; those two never create players, so create the member first (for
567
+ * example with `createSetupSession` and a `playerName`, or a currency purchase).
567
568
  */
568
569
  get isPlayerNotFound(): boolean;
570
+ /**
571
+ * True when `cards.createSetupSession` was asked to create a new member (`playerName`
572
+ * sent) and INVO could not create them (`PLAYER_CREATE_FAILED`, 503). Nothing was
573
+ * created and no link was minted; call again.
574
+ */
575
+ get isPlayerCreateFailed(): boolean;
569
576
  /**
570
577
  * True when `cards.createSetupSession` was refused because `playerEmail` was missing or
571
578
  * is not an email address (`INVALID_PLAYER_EMAIL`, 400).
@@ -576,7 +583,8 @@ declare class InvoError extends Error {
576
583
  * `status === 0` is this SDK refusing a value before the network (every client-side
577
584
  * guard uses this code); `status === 400` is INVO refusing one, on
578
585
  * `cards.createSetupSession` a `successUrl` / `cancelUrl` that uses a script scheme
579
- * (`javascript:`, `data:`, `vbscript:`). http(s) and app deep-link schemes are fine.
586
+ * (`javascript:`, `data:`, `vbscript:`; http(s) and app deep-link schemes are fine), or,
587
+ * when the member is new, a `playerName` over 255 characters or a `playerPhone` over 30.
580
588
  */
581
589
  get isInvalidInput(): boolean;
582
590
  /**
@@ -2576,8 +2584,26 @@ interface PlayerCardsResult {
2576
2584
  }
2577
2585
  /** Input for `cards.createSetupSession`. */
2578
2586
  interface CardSetupSessionInput {
2579
- /** Must already exist in this game. The card page never creates players (`404 PLAYER_NOT_FOUND`). */
2587
+ /**
2588
+ * The member's email. A member this game already knows needs nothing else. An unknown
2589
+ * member is `404 PLAYER_NOT_FOUND` unless `playerName` is sent, in which case INVO
2590
+ * creates them.
2591
+ */
2580
2592
  playerEmail: string;
2593
+ /**
2594
+ * Creates the member when they are new to this game (as `subscriptions.create` does),
2595
+ * so a first-time signup can save a card before a paid trial. Max 255 characters. Used
2596
+ * only when the member is new: a known member is never renamed by this call. Omit it to
2597
+ * keep the old behaviour (an unknown member is refused with `404 PLAYER_NOT_FOUND`).
2598
+ */
2599
+ playerName?: string;
2600
+ /**
2601
+ * E.164 (for example `"+15555550100"`); the SDK refuses any other form before the
2602
+ * network. Used only when `playerName` creates a new member; ignored for a known member.
2603
+ * A phone already on another member can answer `409 PHONE_SHARE_APPROVAL_REQUIRED`
2604
+ * (`err.isPhoneShareApprovalRequired`).
2605
+ */
2606
+ playerPhone?: string;
2581
2607
  /**
2582
2608
  * Where the page sends the member after the card is saved. Absent: the page shows
2583
2609
  * "Card saved, you can close this window". http(s) and app deep-link schemes only; a
@@ -560,12 +560,19 @@ declare class InvoError extends Error {
560
560
  get isGameNotLive(): boolean;
561
561
  /**
562
562
  * True when `cards.createSetupSession` was refused because the member does not exist
563
- * in this game yet (`PLAYER_NOT_FOUND`, 404). The card page never creates players;
564
- * create the member first (any endpoint that creates players, for example a currency
565
- * purchase), then mint the session again. The same code comes back from
566
- * `cards.beginSetup` and from `mintPlayerToken` for the same reason.
563
+ * in this game yet (`PLAYER_NOT_FOUND`, 404) and no `playerName` was sent. Send
564
+ * `playerName` (and optionally `playerPhone`) to create the member with their card.
565
+ * The same code comes back from `cards.beginSetup` and from `mintPlayerToken` for the
566
+ * same reason; those two never create players, so create the member first (for
567
+ * example with `createSetupSession` and a `playerName`, or a currency purchase).
567
568
  */
568
569
  get isPlayerNotFound(): boolean;
570
+ /**
571
+ * True when `cards.createSetupSession` was asked to create a new member (`playerName`
572
+ * sent) and INVO could not create them (`PLAYER_CREATE_FAILED`, 503). Nothing was
573
+ * created and no link was minted; call again.
574
+ */
575
+ get isPlayerCreateFailed(): boolean;
569
576
  /**
570
577
  * True when `cards.createSetupSession` was refused because `playerEmail` was missing or
571
578
  * is not an email address (`INVALID_PLAYER_EMAIL`, 400).
@@ -576,7 +583,8 @@ declare class InvoError extends Error {
576
583
  * `status === 0` is this SDK refusing a value before the network (every client-side
577
584
  * guard uses this code); `status === 400` is INVO refusing one, on
578
585
  * `cards.createSetupSession` a `successUrl` / `cancelUrl` that uses a script scheme
579
- * (`javascript:`, `data:`, `vbscript:`). http(s) and app deep-link schemes are fine.
586
+ * (`javascript:`, `data:`, `vbscript:`; http(s) and app deep-link schemes are fine), or,
587
+ * when the member is new, a `playerName` over 255 characters or a `playerPhone` over 30.
580
588
  */
581
589
  get isInvalidInput(): boolean;
582
590
  /**
@@ -2576,8 +2584,26 @@ interface PlayerCardsResult {
2576
2584
  }
2577
2585
  /** Input for `cards.createSetupSession`. */
2578
2586
  interface CardSetupSessionInput {
2579
- /** Must already exist in this game. The card page never creates players (`404 PLAYER_NOT_FOUND`). */
2587
+ /**
2588
+ * The member's email. A member this game already knows needs nothing else. An unknown
2589
+ * member is `404 PLAYER_NOT_FOUND` unless `playerName` is sent, in which case INVO
2590
+ * creates them.
2591
+ */
2580
2592
  playerEmail: string;
2593
+ /**
2594
+ * Creates the member when they are new to this game (as `subscriptions.create` does),
2595
+ * so a first-time signup can save a card before a paid trial. Max 255 characters. Used
2596
+ * only when the member is new: a known member is never renamed by this call. Omit it to
2597
+ * keep the old behaviour (an unknown member is refused with `404 PLAYER_NOT_FOUND`).
2598
+ */
2599
+ playerName?: string;
2600
+ /**
2601
+ * E.164 (for example `"+15555550100"`); the SDK refuses any other form before the
2602
+ * network. Used only when `playerName` creates a new member; ignored for a known member.
2603
+ * A phone already on another member can answer `409 PHONE_SHARE_APPROVAL_REQUIRED`
2604
+ * (`err.isPhoneShareApprovalRequired`).
2605
+ */
2606
+ playerPhone?: string;
2581
2607
  /**
2582
2608
  * Where the page sends the member after the card is saved. Absent: the page shows
2583
2609
  * "Card saved, you can close this window". http(s) and app deep-link schemes only; a
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@invonetwork/web-sdk",
3
- "version": "3.14.1",
3
+ "version": "3.15.0",
4
4
  "description": "INVO Web SDK — currency purchase + passkey (WebAuthn) verification for partner web platforms.",
5
5
  "license": "SEE LICENSE IN LICENSE",
6
6
  "private": false,