@invonetwork/web-sdk 3.9.0 → 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";
@@ -878,7 +954,12 @@ function toDestinationsResult(raw, direction) {
878
954
  }
879
955
 
880
956
  // src/version.ts
881
- var SDK_VERSION = "3.9.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
+ }
882
963
  var DEFAULT_TOLERANCE_SEC = 300;
883
964
  var ENCODER = new TextEncoder();
884
965
  function toBytes(body) {
@@ -1561,6 +1642,79 @@ function toSavedCard(row) {
1561
1642
  function nullableString(v) {
1562
1643
  return v == null ? null : String(v);
1563
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
+ }
1564
1718
  function toSubscription(row) {
1565
1719
  const r = row && typeof row === "object" ? row : {};
1566
1720
  const share = r["revenue_share"];
@@ -1768,8 +1922,13 @@ var SubscriptionsServer = class {
1768
1922
  * `err.existingSubscriptionId`) at best and a second subscription at worst. Same key
1769
1923
  * with different terms is `err.isIdempotentReplayMismatch` (`err.mismatchedFields`).
1770
1924
  *
1771
- * Card selection: `playerCardId` names one (from `cards.list`); omitted, INVO attaches
1772
- * 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"`).
1773
1932
  * Requires the game to be `live` (`err.isGameNotLive`).
1774
1933
  */
1775
1934
  async create(input, opts) {
@@ -1970,9 +2129,9 @@ var SubscriptionsServer = class {
1970
2129
  /**
1971
2130
  * Card subscriptions only. Attach a card (`{ playerCardId }`, an `id` from
1972
2131
  * `cards.list` belonging to this player, unexpired) or make the subscription wallet-only
1973
- * (`{ walletOnly: true }`). On a wallet-only subscription pass `walletOnly: false`
1974
- * beside the card to convert it back. The new card is used from the next charge,
1975
- * 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.
1976
2135
  *
1977
2136
  * `err.isNotACardSubscription` on Steam; `err.isSubscriptionTerminal` on a terminal row.
1978
2137
  */
@@ -2010,16 +2169,35 @@ var SubscriptionsServer = class {
2010
2169
  * Refund a billed period (card rail). Idempotent on `clientRequestId`: a repeat returns
2011
2170
  * the stored receipt with `idempotentReplay: true` and moves nothing.
2012
2171
  *
2013
- * A full refund returns the card charge and reclaims the coins that charge minted
2014
- * (`balanceDeltaCoins` is signed and can be negative); a partial refund credits the
2015
- * wallet in coins at the 10:1 peg. Your revenue is reversed for the refunded portion
2016
- * (`partnerRevenueReversedUsd`); INVO's fee is retained. The subscription is NOT
2017
- * cancelled by a refund. Refunds of Steam-CHARGED periods are not supported yet; do not
2018
- * call this on them.
2019
- *
2020
- * Refusals: `NO_PAID_PERIOD` (409, nothing collected yet), `PERIOD_NOT_REFUNDABLE`,
2021
- * `ALREADY_REFUNDED` (`err.isAlreadyRefunded`), `AMOUNT_EXCEEDS_REMAINING` (body carries
2022
- * `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`.
2023
2201
  */
2024
2202
  async refund(subscriptionId, input, opts) {
2025
2203
  assertSubscriptionId(subscriptionId);
@@ -2045,44 +2223,7 @@ var SubscriptionsServer = class {
2045
2223
  // Idempotent on client_request_id: a lost-response retry returns the stored receipt.
2046
2224
  { idempotent: true, signal: opts?.signal }
2047
2225
  );
2048
- const attr = raw["revenue_share_attribution"];
2049
- const a = attr && typeof attr === "object" ? attr : null;
2050
- return {
2051
- status: String(raw["status"] ?? ""),
2052
- idempotentReplay: raw["idempotent_replay"] === true,
2053
- refundKey: nullableString(raw["refund_key"]),
2054
- clientRequestId: nullableString(raw["client_request_id"]) ?? input.clientRequestId,
2055
- subscriptionId: String(raw["subscription_id"] ?? subscriptionId),
2056
- periodSeq: raw["period_seq"] == null ? null : Number(raw["period_seq"]),
2057
- transactionId: nullableString(raw["transaction_id"]),
2058
- refundedAmountUsd: nullableString(raw["refunded_amount_usd"]),
2059
- totalRefundedAmountUsd: nullableString(raw["total_refunded_amount_usd"]),
2060
- remainingRefundableUsd: nullableString(raw["remaining_refundable_usd"]),
2061
- isFullRefund: raw["is_full_refund"] === true,
2062
- fundingShape: nullableString(raw["funding_shape"]),
2063
- balanceDeltaCoins: nullableString(raw["balance_delta_coins"]),
2064
- cardRefundedUsd: nullableString(raw["card_refunded_usd"]),
2065
- // Neutral field only; the vendor-named sibling is deliberately not read.
2066
- processorRefundReference: nullableString(raw["processor_refund_reference"]),
2067
- processorRefundAdopted: raw["processor_refund_adopted"] === true,
2068
- invoFeeRetained: raw["invo_fee_retained"] === true,
2069
- partnerRevenueReversedUsd: nullableString(raw["partner_revenue_reversed_usd"]),
2070
- partnerRevenueReversalMode: nullableString(raw["partner_revenue_reversal_mode"]),
2071
- reason: nullableString(raw["reason"]),
2072
- refundedAt: nullableString(raw["refunded_at"]),
2073
- newBalance: nullableString(raw["new_balance"]),
2074
- revenueShareAttribution: a ? {
2075
- recipientPlayerId: Number(a["recipient_player_id"] ?? 0),
2076
- percent: String(a["percent"] ?? ""),
2077
- originalAttributedAmountUsd: String(a["original_attributed_amount_usd"] ?? ""),
2078
- refundedAttributedAmountUsd: String(a["refunded_attributed_amount_usd"] ?? ""),
2079
- netAttributedAmountUsd: String(a["net_attributed_amount_usd"] ?? ""),
2080
- settledByInvo: a["settled_by_invo"] === true,
2081
- raw: a
2082
- } : null,
2083
- note: typeof raw["note"] === "string" ? raw["note"] : void 0,
2084
- raw
2085
- };
2226
+ return toRefundResult(raw, subscriptionId, input.clientRequestId);
2086
2227
  }
2087
2228
  /**
2088
2229
  * Start a STEAM-rail subscription: creates it in `pending_steam_authorization`, opens
@@ -2407,7 +2548,8 @@ var SandboxSubscriptionsServer = class {
2407
2548
  }
2408
2549
  /**
2409
2550
  * Run the renewal immediately. **Charges the test card** (or the Steam stand-in): the
2410
- * 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`,
2411
2553
  * and on failure the real dunning. Read `engineStats` (`renewed: 1` on success). A
2412
2554
  * cancel-at-period-end row answers `action: "retired-at-period-end"`, `retired: true`.
2413
2555
  * `409 PERIOD_TOO_FAR_AHEAD` means you forced twice without advancing the clock.
@@ -3613,6 +3755,7 @@ exports.SandboxServer = SandboxServer;
3613
3755
  exports.SandboxSubscriptionsServer = SandboxSubscriptionsServer;
3614
3756
  exports.SubscriptionsServer = SubscriptionsServer;
3615
3757
  exports.createWebhookHandler = createWebhookHandler;
3758
+ exports.isRefundPendingApproval = isRefundPendingApproval;
3616
3759
  exports.verifyWebhook = verifyWebhook;
3617
3760
  exports.verifyWebhookAsync = verifyWebhookAsync;
3618
3761
  //# sourceMappingURL=server.cjs.map