@invonetwork/web-sdk 3.8.1 → 3.10.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/dist/server.cjs CHANGED
@@ -534,6 +534,82 @@ var InvoError = class _InvoError extends Error {
534
534
  get isSteamRefundNotSupported() {
535
535
  return this.code === "STEAM_REFUND_NOT_SUPPORTED";
536
536
  }
537
+ /**
538
+ * True when `subscriptions.refund` was refused because refunds are turned off for this
539
+ * game (`REFUNDS_NOT_ENABLED`, 403). Refunds are on by default for every game; INVO turns
540
+ * them off per game. Contact INVO.
541
+ */
542
+ get isRefundsNotEnabled() {
543
+ return this.code === "REFUNDS_NOT_ENABLED";
544
+ }
545
+ /**
546
+ * True when `subscriptions.refund` targeted a period charged more than 30 days ago
547
+ * (`REFUND_WINDOW_CLOSED`, 409). See `periodChargedAt`, `refundWindowDays` and
548
+ * `refundWindowClosedAt`. A retry of a refund that already ran still returns its receipt.
549
+ */
550
+ get isRefundWindowClosed() {
551
+ return this.code === "REFUND_WINDOW_CLOSED";
552
+ }
553
+ /**
554
+ * True when a refund request for this period is waiting for INVO's review
555
+ * (`REFUND_REQUEST_PENDING`, 409). No other refund of the period can run until it is
556
+ * decided. The request id is on `refundRequestId`.
557
+ */
558
+ get isRefundRequestPending() {
559
+ return this.code === "REFUND_REQUEST_PENDING";
560
+ }
561
+ /**
562
+ * True when this `clientRequestId` was filed as a refund request and INVO rejected it
563
+ * (`REFUND_REQUEST_REJECTED`, 409). See `refundRequestId` and `decisionReason`. To try
564
+ * again use a NEW `clientRequestId`.
565
+ */
566
+ get isRefundRequestRejected() {
567
+ return this.code === "REFUND_REQUEST_REJECTED";
568
+ }
569
+ /**
570
+ * True when two requests collided (`CONCURRENT_REQUEST`, 409): two creates for a
571
+ * brand-new player, or two refund requests for one period filed at the same moment.
572
+ * Retry with the SAME key.
573
+ */
574
+ get isConcurrentRequest() {
575
+ return this.code === "CONCURRENT_REQUEST";
576
+ }
577
+ /**
578
+ * True when a subscription refund needs manual reconciliation (`REFUND_MISMATCH`, 502):
579
+ * the card processor already holds a refund for this request with a different amount, or
580
+ * the charge was already fully refunded outside this flow. Contact INVO; do not retry-loop.
581
+ */
582
+ get isRefundMismatch() {
583
+ return this.code === "REFUND_MISMATCH";
584
+ }
585
+ /**
586
+ * The refund request id (`request_id`) on `REFUND_REQUEST_PENDING` and
587
+ * `REFUND_REQUEST_REJECTED`. Not the backend request id, which is {@link requestId}.
588
+ */
589
+ get refundRequestId() {
590
+ const v = this.bodyObject()["request_id"];
591
+ return typeof v === "string" && v ? v : void 0;
592
+ }
593
+ /** INVO's reason on `REFUND_REQUEST_REJECTED` (may be absent). */
594
+ get decisionReason() {
595
+ const v = this.bodyObject()["decision_reason"];
596
+ return typeof v === "string" && v ? v : void 0;
597
+ }
598
+ /** On `REFUND_WINDOW_CLOSED`: when the period was charged (ISO 8601). */
599
+ get periodChargedAt() {
600
+ const v = this.bodyObject()["period_charged_at"];
601
+ return typeof v === "string" && v ? v : void 0;
602
+ }
603
+ /** On `REFUND_WINDOW_CLOSED`: the window length in days (30). */
604
+ get refundWindowDays() {
605
+ const v = this.bodyObject()["refund_window_days"];
606
+ return typeof v === "number" && Number.isFinite(v) ? v : void 0;
607
+ }
608
+ /** On `REFUND_WINDOW_CLOSED`: when the window closed (ISO 8601). */
609
+ get refundWindowClosedAt() {
610
+ const v = this.bodyObject()["window_closed_at"];
611
+ return typeof v === "string" && v ? v : void 0;
612
+ }
537
613
  /** True when the subscription is `canceled` or `expired` and the call cannot apply (`SUBSCRIPTION_TERMINAL`, 409). Start a new one. */
538
614
  get isSubscriptionTerminal() {
539
615
  return this.code === "SUBSCRIPTION_TERMINAL";
@@ -567,6 +643,34 @@ var InvoError = class _InvoError extends Error {
567
643
  get isGameNotLive() {
568
644
  return this.code === "GAME_NOT_LIVE";
569
645
  }
646
+ // ---- Card setup session (the INVO-hosted card page) ----
647
+ /**
648
+ * True when `cards.createSetupSession` was refused because the member does not exist
649
+ * in this game yet (`PLAYER_NOT_FOUND`, 404). The card page never creates players;
650
+ * create the member first (any endpoint that creates players, for example a currency
651
+ * purchase), then mint the session again. The same code comes back from
652
+ * `cards.beginSetup` and from `mintPlayerToken` for the same reason.
653
+ */
654
+ get isPlayerNotFound() {
655
+ return this.code === "PLAYER_NOT_FOUND";
656
+ }
657
+ /**
658
+ * True when `cards.createSetupSession` was refused because `playerEmail` was missing or
659
+ * is not an email address (`INVALID_PLAYER_EMAIL`, 400).
660
+ */
661
+ get isInvalidPlayerEmail() {
662
+ return this.code === "INVALID_PLAYER_EMAIL";
663
+ }
664
+ /**
665
+ * True on an `INVALID_INPUT` refusal. Two sources, told apart by `status`:
666
+ * `status === 0` is this SDK refusing a value before the network (every client-side
667
+ * guard uses this code); `status === 400` is INVO refusing one, on
668
+ * `cards.createSetupSession` a `successUrl` / `cancelUrl` that uses a script scheme
669
+ * (`javascript:`, `data:`, `vbscript:`). http(s) and app deep-link schemes are fine.
670
+ */
671
+ get isInvalidInput() {
672
+ return this.code === "INVALID_INPUT";
673
+ }
570
674
  /** Seconds to wait before retrying, when the backend throttled the call (429 `retry_after`). */
571
675
  get retryAfter() {
572
676
  const v = this.bodyObject()["retry_after"];
@@ -850,7 +954,12 @@ function toDestinationsResult(raw, direction) {
850
954
  }
851
955
 
852
956
  // src/version.ts
853
- var SDK_VERSION = "3.8.0";
957
+ var SDK_VERSION = "3.10.0";
958
+
959
+ // src/shared/types.ts
960
+ function isRefundPendingApproval(r) {
961
+ return r.status === "pending_approval";
962
+ }
854
963
  var DEFAULT_TOLERANCE_SEC = 300;
855
964
  var ENCODER = new TextEncoder();
856
965
  function toBytes(body) {
@@ -1533,6 +1642,79 @@ function toSavedCard(row) {
1533
1642
  function nullableString(v) {
1534
1643
  return v == null ? null : String(v);
1535
1644
  }
1645
+ function optionalString(r, key) {
1646
+ return key in r ? nullableString(r[key]) : void 0;
1647
+ }
1648
+ function toRefundWarnings(v) {
1649
+ if (!Array.isArray(v)) return void 0;
1650
+ return v.filter((w) => !!w && typeof w === "object").map((w) => ({ code: String(w["code"] ?? ""), message: String(w["message"] ?? "") }));
1651
+ }
1652
+ function toRefundResult(raw, subscriptionId, clientRequestId) {
1653
+ const attr = raw["revenue_share_attribution"];
1654
+ const a = attr && typeof attr === "object" ? attr : null;
1655
+ const base = {
1656
+ status: String(raw["status"] ?? ""),
1657
+ idempotentReplay: raw["idempotent_replay"] === true,
1658
+ refundKey: nullableString(raw["refund_key"]),
1659
+ clientRequestId: nullableString(raw["client_request_id"]) ?? clientRequestId,
1660
+ subscriptionId: String(raw["subscription_id"] ?? subscriptionId),
1661
+ periodSeq: raw["period_seq"] == null ? null : Number(raw["period_seq"]),
1662
+ transactionId: nullableString(raw["transaction_id"]),
1663
+ refundedAmountUsd: nullableString(raw["refunded_amount_usd"]),
1664
+ totalRefundedAmountUsd: nullableString(raw["total_refunded_amount_usd"]),
1665
+ remainingRefundableUsd: nullableString(raw["remaining_refundable_usd"]),
1666
+ isFullRefund: raw["is_full_refund"] === true,
1667
+ fundingShape: nullableString(raw["funding_shape"]),
1668
+ balanceDeltaCoins: nullableString(raw["balance_delta_coins"]),
1669
+ cardRefundedUsd: nullableString(raw["card_refunded_usd"]),
1670
+ // Neutral field only; the vendor-named sibling is deliberately not read.
1671
+ processorRefundReference: nullableString(raw["processor_refund_reference"]),
1672
+ processorRefundAdopted: raw["processor_refund_adopted"] === true,
1673
+ invoFeeRetained: raw["invo_fee_retained"] === true,
1674
+ partnerRevenueReversedUsd: nullableString(raw["partner_revenue_reversed_usd"]),
1675
+ partnerRevenueReversalMode: nullableString(raw["partner_revenue_reversal_mode"]),
1676
+ reason: nullableString(raw["reason"]),
1677
+ refundedAt: nullableString(raw["refunded_at"]),
1678
+ newBalance: nullableString(raw["new_balance"]),
1679
+ revenueShareAttribution: a ? {
1680
+ recipientPlayerId: Number(a["recipient_player_id"] ?? 0),
1681
+ percent: String(a["percent"] ?? ""),
1682
+ originalAttributedAmountUsd: String(a["original_attributed_amount_usd"] ?? ""),
1683
+ refundedAttributedAmountUsd: String(a["refunded_attributed_amount_usd"] ?? ""),
1684
+ netAttributedAmountUsd: String(a["net_attributed_amount_usd"] ?? ""),
1685
+ settledByInvo: a["settled_by_invo"] === true,
1686
+ raw: a
1687
+ } : null,
1688
+ note: typeof raw["note"] === "string" ? raw["note"] : void 0,
1689
+ // ---- additive (2026-09-17): undefined when the body predates them ----
1690
+ warnings: toRefundWarnings(raw["warnings"]),
1691
+ subscriptionCanceled: "subscription_canceled" in raw ? raw["subscription_canceled"] === true : void 0,
1692
+ subscriptionStatus: optionalString(raw, "subscription_status"),
1693
+ processingFeeUsd: optionalString(raw, "processing_fee_usd"),
1694
+ processingFeeBasis: optionalString(raw, "processing_fee_basis"),
1695
+ processingFeeBorneBy: optionalString(raw, "processing_fee_borne_by"),
1696
+ processingFeeTransactionId: optionalString(raw, "processing_fee_transaction_id"),
1697
+ partnerTotalReversedUsd: optionalString(raw, "partner_total_reversed_usd"),
1698
+ initiation: optionalString(raw, "initiation"),
1699
+ refundRequestId: optionalString(raw, "refund_request_id"),
1700
+ raw
1701
+ };
1702
+ if (base.status === "pending_approval") {
1703
+ const pending = {
1704
+ ...base,
1705
+ status: "pending_approval",
1706
+ requestId: String(raw["request_id"] ?? raw["refund_request_id"] ?? ""),
1707
+ requestStatus: String(raw["request_status"] ?? ""),
1708
+ requestedAmountUsd: nullableString(raw["requested_amount_usd"]),
1709
+ requestedAt: nullableString(raw["requested_at"]),
1710
+ dailyCapUsd: nullableString(raw["daily_cap_usd"]),
1711
+ executedTodayUsd: nullableString(raw["executed_today_usd"]),
1712
+ message: nullableString(raw["message"])
1713
+ };
1714
+ return pending;
1715
+ }
1716
+ return base;
1717
+ }
1536
1718
  function toSubscription(row) {
1537
1719
  const r = row && typeof row === "object" ? row : {};
1538
1720
  const share = r["revenue_share"];
@@ -1580,6 +1762,9 @@ function toSubscription(row) {
1580
1762
  } : null,
1581
1763
  paidThrough: nullableString(r["paid_through"]),
1582
1764
  amountCoinsEstimate: r["amount_coins_estimate"] == null ? void 0 : String(r["amount_coins_estimate"]),
1765
+ // `include_player` puts these two ON the object (there is no separate block).
1766
+ ..."player_email" in r ? { playerEmail: nullableString(r["player_email"]) } : {},
1767
+ ..."player_name" in r ? { playerName: nullableString(r["player_name"]) } : {},
1583
1768
  raw: r
1584
1769
  };
1585
1770
  }
@@ -1737,8 +1922,13 @@ var SubscriptionsServer = class {
1737
1922
  * `err.existingSubscriptionId`) at best and a second subscription at worst. Same key
1738
1923
  * with different terms is `err.isIdempotentReplayMismatch` (`err.mismatchedFields`).
1739
1924
  *
1740
- * Card selection: `playerCardId` names one (from `cards.list`); omitted, INVO attaches
1741
- * the member's newest unexpired saved card; `walletOnly: true` never charges a card.
1925
+ * Card only (since 2026-09-17): the card is charged the full price every period and the
1926
+ * member's coin wallet never pays and never moves. Card selection: `playerCardId` names one
1927
+ * (from `cards.list`); omitted, INVO attaches the member's newest unexpired saved card. With
1928
+ * no saved card the subscription is still created (201) but `firstCharge` is `failed` with
1929
+ * `failureCode: "no_payment_method"`, whatever the member's balance: save a card first.
1930
+ * `walletOnly: true` is deprecated: it never charges a card, so such a subscription can never
1931
+ * be paid (`failureCode: "wallet_only"`).
1742
1932
  * Requires the game to be `live` (`err.isGameNotLive`).
1743
1933
  */
1744
1934
  async create(input, opts) {
@@ -1795,11 +1985,10 @@ var SubscriptionsServer = class {
1795
1985
  this.auth,
1796
1986
  { signal: opts?.signal }
1797
1987
  );
1798
- return {
1799
- subscription: toSubscription(raw["subscription"]),
1800
- player: raw["player"] && typeof raw["player"] === "object" ? raw["player"] : void 0,
1801
- raw
1802
- };
1988
+ const subscription = toSubscription(raw["subscription"]);
1989
+ const row = subscription.raw;
1990
+ const player = "player_email" in row || "player_name" in row ? { player_email: row["player_email"] ?? null, player_name: row["player_name"] ?? null } : void 0;
1991
+ return { subscription, player, raw };
1803
1992
  }
1804
1993
  /**
1805
1994
  * List a member's subscriptions, newest first, paged (`limit` 1..100, `offset`
@@ -1940,9 +2129,9 @@ var SubscriptionsServer = class {
1940
2129
  /**
1941
2130
  * Card subscriptions only. Attach a card (`{ playerCardId }`, an `id` from
1942
2131
  * `cards.list` belonging to this player, unexpired) or make the subscription wallet-only
1943
- * (`{ walletOnly: true }`). On a wallet-only subscription pass `walletOnly: false`
1944
- * beside the card to convert it back. The new card is used from the next charge,
1945
- * including a pending retry in dunning.
2132
+ * (`{ walletOnly: true }`, deprecated: a wallet-only card subscription can never be paid).
2133
+ * On a wallet-only subscription pass `walletOnly: false` beside the card to convert it
2134
+ * back. The new card is used from the next charge, including a pending retry in dunning.
1946
2135
  *
1947
2136
  * `err.isNotACardSubscription` on Steam; `err.isSubscriptionTerminal` on a terminal row.
1948
2137
  */
@@ -1980,16 +2169,35 @@ var SubscriptionsServer = class {
1980
2169
  * Refund a billed period (card rail). Idempotent on `clientRequestId`: a repeat returns
1981
2170
  * the stored receipt with `idempotentReplay: true` and moves nothing.
1982
2171
  *
1983
- * A full refund returns the card charge and reclaims the coins that charge minted
1984
- * (`balanceDeltaCoins` is signed and can be negative); a partial refund credits the
1985
- * wallet in coins at the 10:1 peg. Your revenue is reversed for the refunded portion
1986
- * (`partnerRevenueReversedUsd`); INVO's fee is retained. The subscription is NOT
1987
- * cancelled by a refund. Refunds of Steam-CHARGED periods are not supported yet; do not
1988
- * call this on them.
1989
- *
1990
- * Refusals: `NO_PAID_PERIOD` (409, nothing collected yet), `PERIOD_NOT_REFUNDABLE`,
1991
- * `ALREADY_REFUNDED` (`err.isAlreadyRefunded`), `AMOUNT_EXCEEDS_REMAINING` (body carries
1992
- * `remaining_refundable_usd`), `err.isFlowPaused`.
2172
+ * **Branch on `status`.** `"refunded"` (HTTP 200): the refund ran. `"pending_approval"`
2173
+ * (HTTP 202): the refund would exceed the game's daily self-serve limit ($500 per UTC day
2174
+ * by default), NOTHING moved, and INVO reviews it as a refund request (`requestId`); the
2175
+ * outcome arrives as `subscription.refund_approved` (sent together with
2176
+ * `subscription.refunded`, and `subscription.canceled` on a full refund, in any order) or
2177
+ * `subscription.refund_rejected`. The 202 carries every receipt field with nothing moved
2178
+ * (`refundedAmountUsd` is `"0.00"`; `totalRefundedAmountUsd` and `remainingRefundableUsd`
2179
+ * carry the period's real values). Check it with {@link isRefundPendingApproval}.
2180
+ *
2181
+ * A card-only period (every card period charged since 2026-09-17) is refunded in cash, full
2182
+ * or partial: `cardRefundedUsd` equals the amount and `balanceDeltaCoins` is `"0.00"`. A
2183
+ * period charged before that keeps the earlier rule: a full refund returns the card charge
2184
+ * and reclaims the coins it minted (`balanceDeltaCoins` is signed), a partial refund
2185
+ * credits coins. Your revenue is reversed for the refunded portion
2186
+ * (`partnerRevenueReversedUsd`), INVO's fee is retained, and on a card refund you bear the
2187
+ * processor fee (`processingFeeUsd`; `partnerTotalReversedUsd` is the sum). **A full refund
2188
+ * cancels the subscription** (`subscriptionCanceled`, and a `subscription.canceled` event
2189
+ * with `cancel_cause: "full_refund"`, sent together with `subscription.refunded` in any
2190
+ * order); a partial one does not. INVO emails the member.
2191
+ * Refunds run within 30 days of the period's charge. Send a `reason`: it is recommended now
2192
+ * and will be required later (`warnings` says so when it is missing).
2193
+ *
2194
+ * Refusals: `err.isRefundsNotEnabled` (403), `err.isRefundWindowClosed` (409),
2195
+ * `err.isRefundRequestPending` (409, `err.refundRequestId`), `err.isRefundRequestRejected`
2196
+ * (409, use a new key), `err.isConcurrentRequest` (409, retry with the same key),
2197
+ * `err.isRefundMismatch` (502, contact INVO), `NO_PAID_PERIOD` (409, nothing collected yet),
2198
+ * `PERIOD_NOT_REFUNDABLE`, `ALREADY_REFUNDED` (`err.isAlreadyRefunded`),
2199
+ * `AMOUNT_EXCEEDS_REMAINING` (body carries `remaining_refundable_usd`),
2200
+ * `err.isSteamRefundNotSupported`, `err.isFlowPaused`.
1993
2201
  */
1994
2202
  async refund(subscriptionId, input, opts) {
1995
2203
  assertSubscriptionId(subscriptionId);
@@ -2015,44 +2223,7 @@ var SubscriptionsServer = class {
2015
2223
  // Idempotent on client_request_id: a lost-response retry returns the stored receipt.
2016
2224
  { idempotent: true, signal: opts?.signal }
2017
2225
  );
2018
- const attr = raw["revenue_share_attribution"];
2019
- const a = attr && typeof attr === "object" ? attr : null;
2020
- return {
2021
- status: String(raw["status"] ?? ""),
2022
- idempotentReplay: raw["idempotent_replay"] === true,
2023
- refundKey: nullableString(raw["refund_key"]),
2024
- clientRequestId: nullableString(raw["client_request_id"]) ?? input.clientRequestId,
2025
- subscriptionId: String(raw["subscription_id"] ?? subscriptionId),
2026
- periodSeq: raw["period_seq"] == null ? null : Number(raw["period_seq"]),
2027
- transactionId: nullableString(raw["transaction_id"]),
2028
- refundedAmountUsd: nullableString(raw["refunded_amount_usd"]),
2029
- totalRefundedAmountUsd: nullableString(raw["total_refunded_amount_usd"]),
2030
- remainingRefundableUsd: nullableString(raw["remaining_refundable_usd"]),
2031
- isFullRefund: raw["is_full_refund"] === true,
2032
- fundingShape: nullableString(raw["funding_shape"]),
2033
- balanceDeltaCoins: nullableString(raw["balance_delta_coins"]),
2034
- cardRefundedUsd: nullableString(raw["card_refunded_usd"]),
2035
- // Neutral field only; the vendor-named sibling is deliberately not read.
2036
- processorRefundReference: nullableString(raw["processor_refund_reference"]),
2037
- processorRefundAdopted: raw["processor_refund_adopted"] === true,
2038
- invoFeeRetained: raw["invo_fee_retained"] === true,
2039
- partnerRevenueReversedUsd: nullableString(raw["partner_revenue_reversed_usd"]),
2040
- partnerRevenueReversalMode: nullableString(raw["partner_revenue_reversal_mode"]),
2041
- reason: nullableString(raw["reason"]),
2042
- refundedAt: nullableString(raw["refunded_at"]),
2043
- newBalance: nullableString(raw["new_balance"]),
2044
- revenueShareAttribution: a ? {
2045
- recipientPlayerId: Number(a["recipient_player_id"] ?? 0),
2046
- percent: String(a["percent"] ?? ""),
2047
- originalAttributedAmountUsd: String(a["original_attributed_amount_usd"] ?? ""),
2048
- refundedAttributedAmountUsd: String(a["refunded_attributed_amount_usd"] ?? ""),
2049
- netAttributedAmountUsd: String(a["net_attributed_amount_usd"] ?? ""),
2050
- settledByInvo: a["settled_by_invo"] === true,
2051
- raw: a
2052
- } : null,
2053
- note: typeof raw["note"] === "string" ? raw["note"] : void 0,
2054
- raw
2055
- };
2226
+ return toRefundResult(raw, subscriptionId, input.clientRequestId);
2056
2227
  }
2057
2228
  /**
2058
2229
  * Start a STEAM-rail subscription: creates it in `pending_steam_authorization`, opens
@@ -2168,12 +2339,81 @@ var SubscriptionsServer = class {
2168
2339
  };
2169
2340
  }
2170
2341
  };
2342
+ var SCRIPT_SCHEME = /^\s*(javascript|data|vbscript):/i;
2171
2343
  var CardsServer = class {
2172
2344
  constructor(http, auth) {
2173
2345
  this.http = http;
2174
2346
  this.auth = auth;
2175
2347
  }
2176
2348
  /**
2349
+ * Mint a short-lived session for the INVO-hosted card page and return its URL. THE
2350
+ * RECOMMENDED WAY TO SAVE A CARD FOR A SUBSCRIPTION: two server-to-server calls (this
2351
+ * one, then `cards.list`) and one redirect. No browser code, no processor script, no
2352
+ * client secret; INVO can change card processor without you changing anything.
2353
+ *
2354
+ * The member must already exist in this game (`err.isPlayerNotFound`, 404); the page
2355
+ * never creates players. Send the member to `result.cardSetupUrl` top-level (do not
2356
+ * frame it). The page says in words that no money moves, saves the card, and then
2357
+ * redirects to `successUrl` (or shows "Card saved" when you gave none). The saved card
2358
+ * appears in {@link list} immediately, carries the off-session consent a subscription
2359
+ * needs, and is indistinguishable from one saved any other way. There is no event for
2360
+ * a saved card; `cards.list` is the signal.
2361
+ *
2362
+ * The session lives 10 minutes (entering a card is one sitting); mint it when the
2363
+ * member is about to use it. The link may be reloaded freely before the save; once the
2364
+ * card is saved the link is spent and reopening it returns the same card again.
2365
+ * `successUrl` is redirected to verbatim (nothing appended) and `metadata` is stored on
2366
+ * the session and not returned anywhere today, so put your own correlation id in
2367
+ * `successUrl`.
2368
+ *
2369
+ * Refusals: `err.isInvalidPlayerEmail` (400, a non-email string; a missing or blank
2370
+ * `playerEmail` is refused here first with `status: 0`), `err.isPlayerNotFound` (404),
2371
+ * `err.isInvalidInput` (400: a script-scheme `successUrl` / `cancelUrl`; the SDK
2372
+ * refuses the same values first with `status: 0`), 401 / 403 on the key or the game
2373
+ * (body `{ message }`, no code), 503 when card setup is not available right now.
2374
+ * Never auto-retried: each call mints a fresh link, so on a timeout call it again.
2375
+ */
2376
+ async createSetupSession(input, opts) {
2377
+ if (typeof input.playerEmail !== "string" || !input.playerEmail.trim()) {
2378
+ throw invalidInput("playerEmail", input.playerEmail, "is required");
2379
+ }
2380
+ for (const [label, value] of [
2381
+ ["successUrl", input.successUrl],
2382
+ ["cancelUrl", input.cancelUrl]
2383
+ ]) {
2384
+ if (value === void 0) continue;
2385
+ if (typeof value !== "string" || !value.trim()) throw invalidInput(label, value, "must be a non-empty URL");
2386
+ if (SCRIPT_SCHEME.test(value)) throw invalidInput(label, value, "must not use a script scheme");
2387
+ }
2388
+ if (input.metadata !== void 0 && (input.metadata === null || typeof input.metadata !== "object" || Array.isArray(input.metadata))) {
2389
+ throw invalidInput("metadata", input.metadata, "must be a plain object");
2390
+ }
2391
+ const body = { player_email: input.playerEmail };
2392
+ if (input.successUrl) body["success_url"] = input.successUrl;
2393
+ if (input.cancelUrl) body["cancel_url"] = input.cancelUrl;
2394
+ if (input.metadata) body["metadata"] = input.metadata;
2395
+ const raw = await this.http.post(
2396
+ "/api/checkout/card-setup-sessions",
2397
+ body,
2398
+ this.auth,
2399
+ { signal: opts?.signal }
2400
+ // not idempotent: every call mints a new session (same rule as createCheckout)
2401
+ );
2402
+ return {
2403
+ sessionId: String(raw["session_id"] ?? ""),
2404
+ // Load-bearing: the member must be sent here. A 2xx without it is a broken response.
2405
+ cardSetupUrl: requireField(raw["card_setup_url"], "card_setup_url", raw),
2406
+ expiresAt: String(raw["expires_at"] ?? ""),
2407
+ raw
2408
+ };
2409
+ }
2410
+ /**
2411
+ * THE PROCESSOR-BOUND ALTERNATIVE to {@link createSetupSession}. Use it only if you
2412
+ * already run a card form in your own client against INVO's current card processor:
2413
+ * the `clientSecret` it hands back can only be consumed by that processor's client
2414
+ * library, so the browser code you write for it will need rework when INVO changes
2415
+ * processor. `createSetupSession` does not have that problem.
2416
+ *
2177
2417
  * Begin saving a card (charges nothing). The player must already exist in this game
2178
2418
  * (`404 PLAYER_NOT_FOUND`). Idempotent on `setupReference`: resend the same value on a
2179
2419
  * retry and you get the same setup back (`409 SETUP_REFERENCE_REUSED` if you reuse it
@@ -2217,6 +2457,9 @@ var CardsServer = class {
2217
2457
  };
2218
2458
  }
2219
2459
  /**
2460
+ * The second half of the processor-bound alternative (see {@link beginSetup}); not
2461
+ * needed on the {@link createSetupSession} path, where INVO's page completes the save.
2462
+ *
2220
2463
  * Finish a client-confirmed setup and save the card. Idempotent on `setupIntentId`.
2221
2464
  * While the client has not finished, this throws a 400 with body
2222
2465
  * `status: "still_requires_action"`. On `500 CARD_PERSIST_FAILED` (authorised but not
@@ -2245,7 +2488,8 @@ var CardsServer = class {
2245
2488
  * A member's unexpired saved cards, newest first. An unknown player is `{ cards: [] }`.
2246
2489
  * The `id` is the value you pass as `playerCardId`; INVO never returns processor
2247
2490
  * identifiers for a card. Served from a short cache (about 60 s); a card saved through
2248
- * `beginSetup` / `confirmSetup` appears immediately.
2491
+ * the hosted card page (`createSetupSession`) or through `beginSetup` / `confirmSetup`
2492
+ * appears immediately. This read is the signal that the hosted page saved a card.
2249
2493
  */
2250
2494
  async list(playerEmail, opts) {
2251
2495
  if (typeof playerEmail !== "string" || !playerEmail.trim()) {
@@ -2304,7 +2548,8 @@ var SandboxSubscriptionsServer = class {
2304
2548
  }
2305
2549
  /**
2306
2550
  * Run the renewal immediately. **Charges the test card** (or the Steam stand-in): the
2307
- * real money path, wallet read, shortfall, mint, spend, split, `subscription.renewed`,
2551
+ * real money path (card: the full price; Steam: wallet first, then the shortfall), mint,
2552
+ * spend, split, `subscription.renewed`,
2308
2553
  * and on failure the real dunning. Read `engineStats` (`renewed: 1` on success). A
2309
2554
  * cancel-at-period-end row answers `action: "retired-at-period-end"`, `retired: true`.
2310
2555
  * `409 PERIOD_TOO_FAR_AHEAD` means you forced twice without advancing the clock.
@@ -3510,6 +3755,7 @@ exports.SandboxServer = SandboxServer;
3510
3755
  exports.SandboxSubscriptionsServer = SandboxSubscriptionsServer;
3511
3756
  exports.SubscriptionsServer = SubscriptionsServer;
3512
3757
  exports.createWebhookHandler = createWebhookHandler;
3758
+ exports.isRefundPendingApproval = isRefundPendingApproval;
3513
3759
  exports.verifyWebhook = verifyWebhook;
3514
3760
  exports.verifyWebhookAsync = verifyWebhookAsync;
3515
3761
  //# sourceMappingURL=server.cjs.map