@invonetwork/web-sdk 3.9.0 → 3.10.1

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.d.cts CHANGED
@@ -1,12 +1,12 @@
1
- import { I as InvoError, H as Http, o as AuthHeader, p as CardSetupSessionInput, c as CallOptions, q as CardSetupSessionResult, r as CardSetupInput, s as CardSetupResult, t as CardSetupConfirmInput, u as CardSetupConfirmResult, v as PlayerCardsResult, w as PlatformPurchaseInput, x as PlatformPurchaseResult, y as PlatformOrderStatusResult, z as PlatformRefundInput, F as PlatformRefundResult, G as CreateSubscriptionInput, S as SubscriptionResult, J as GetSubscriptionOptions, K as GetSubscriptionResult, N as ListSubscriptionsOptions, O as SubscriptionListResult, Q as CancelSubscriptionOptions, T as CancelResult, U as ChangeAmountResult, W as SetPaymentMethodInput, X as SetPaymentMethodResult, Y as RefundSubscriptionInput, Z as RefundResult, _ as SteamSubscriptionInitInput, $ as SteamInitResult, a0 as SteamFinalizeSubscriptionResult, a1 as SandboxClockResult, a2 as SandboxFailureOutcome, a3 as SandboxForceFailureOptions, a4 as SandboxForceAuthChallengeOptions, a5 as ServerConfig, a6 as PlayerToken, a7 as InitiateSendInput, a8 as InitiateResult, a9 as InitiateTransferInput, aa as CreateCheckoutInput, ab as CreateCheckoutResult, ac as PurchaseInput, ad as PurchaseResult, ae as ConfirmPaymentResult, af as OrderDetailsResult, ag as SteamPacksQuery, ah as SteamPacksResult, ai as SteamInitPurchaseInput, aj as SteamInitPurchaseResult, ak as SteamFinalizeInput, al as SteamFinalizeResult, am as PurchaseItemInput, an as PurchaseItemResult, ao as ItemHistoryQuery, ap as ItemHistoryResult, aq as ItemOrderQuery, ar as PlayerBalanceQuery, as as PlayerBalanceResult, at as InboundPendingQuery, au as InboundPendingResult, av as LinkedIdentitiesQuery, aw as LinkedIdentitiesResult, ax as SmsVerifyResult, ay as ClaimTransferInput, az as ClaimResult, aA as ClaimCurrencyInput, aB as TransactionStatusResult, aC as GuardianApprovalStatusResult, aD as ServerDestinationsQuery, d as DestinationsResult, aE as PhoneShareContact, aF as PhoneShareInitiateResult, aG as PhoneShareApproveInput, aH as PhoneShareApproveResult, aI as PhoneShareStatusResult, aJ as BeginDeviceApprovalInput, aK as DeviceApprovalGrant, aL as PollDeviceApprovalInput, aM as DeviceApprovalPollResult, aN as ConfirmDeviceEnrollmentInput, aO as ConfirmDeviceEnrollmentResult, aP as ApproveWithDeviceCodeInput, aQ as DeviceApprovalSettleResult, aR as CompleteDeviceApprovalInput, aS as CompleteDeviceApprovalResult } from './types-CUzSzV8-.cjs';
2
- export { aT as CardSetupStatus, aU as CurrencyBalance, h as DestinationGame, aV as DeviceApprovalChannel, aW as DeviceApprovalEnrollment, aX as DeviceApprovalFlow, aY as DeviceApprovalPollStatus, aZ as DeviceEnrollmentDecision, a_ as DeviceEnrollmentRespond, a$ as FirstCharge, b0 as FirstChargeStatus, b1 as FundingSource, b2 as InboundPendingItem, i as InvoErrorInfo, j as InvoHooks, k as InvoRequestInfo, l as InvoResponseInfo, b3 as LinkedIdentityEmail, b4 as PlatformPurchaseStatus, n as Rail, b5 as RefundRevenueShareAttribution, b6 as SandboxClockState, b7 as SavedCard, b8 as SteamPack, b9 as SteamUserSession, ba as Subscription, bb as SubscriptionBaseInput, bc as SubscriptionConsent, bd as SubscriptionConsentInput, be as SubscriptionFundingRail, bf as SubscriptionInterval, bg as SubscriptionRevenueShare, bh as SubscriptionRevenueShareInput, bi as SubscriptionStatus, V as VerificationMethod } from './types-CUzSzV8-.cjs';
1
+ import { I as InvoError, H as Http, o as AuthHeader, p as CardSetupSessionInput, c as CallOptions, q as CardSetupSessionResult, r as CardSetupInput, s as CardSetupResult, t as CardSetupConfirmInput, u as CardSetupConfirmResult, v as PlayerCardsResult, w as PlatformPurchaseInput, x as PlatformPurchaseResult, y as PlatformOrderStatusResult, z as PlatformRefundInput, F as PlatformRefundResult, G as CreateSubscriptionInput, S as SubscriptionResult, J as GetSubscriptionOptions, K as GetSubscriptionResult, N as ListSubscriptionsOptions, O as SubscriptionListResult, Q as CancelSubscriptionOptions, T as CancelResult, U as ChangeAmountResult, W as SetPaymentMethodInput, X as SetPaymentMethodResult, Y as RefundSubscriptionInput, Z as RefundResult, _ as SteamSubscriptionInitInput, $ as SteamInitResult, a0 as SteamFinalizeSubscriptionResult, a1 as SandboxClockResult, a2 as SandboxFailureOutcome, a3 as SandboxForceFailureOptions, a4 as SandboxForceAuthChallengeOptions, a5 as ServerConfig, a6 as PlayerToken, a7 as InitiateSendInput, a8 as InitiateResult, a9 as InitiateTransferInput, aa as CreateCheckoutInput, ab as CreateCheckoutResult, ac as PurchaseInput, ad as PurchaseResult, ae as ConfirmPaymentResult, af as OrderDetailsResult, ag as SteamPacksQuery, ah as SteamPacksResult, ai as SteamInitPurchaseInput, aj as SteamInitPurchaseResult, ak as SteamFinalizeInput, al as SteamFinalizeResult, am as PurchaseItemInput, an as PurchaseItemResult, ao as ItemHistoryQuery, ap as ItemHistoryResult, aq as ItemOrderQuery, ar as PlayerBalanceQuery, as as PlayerBalanceResult, at as InboundPendingQuery, au as InboundPendingResult, av as LinkedIdentitiesQuery, aw as LinkedIdentitiesResult, ax as SmsVerifyResult, ay as ClaimTransferInput, az as ClaimResult, aA as ClaimCurrencyInput, aB as TransactionStatusResult, aC as GuardianApprovalStatusResult, aD as ServerDestinationsQuery, d as DestinationsResult, aE as PhoneShareContact, aF as PhoneShareInitiateResult, aG as PhoneShareApproveInput, aH as PhoneShareApproveResult, aI as PhoneShareStatusResult, aJ as BeginDeviceApprovalInput, aK as DeviceApprovalGrant, aL as PollDeviceApprovalInput, aM as DeviceApprovalPollResult, aN as ConfirmDeviceEnrollmentInput, aO as ConfirmDeviceEnrollmentResult, aP as ApproveWithDeviceCodeInput, aQ as DeviceApprovalSettleResult, aR as CompleteDeviceApprovalInput, aS as CompleteDeviceApprovalResult } from './types-CBxpXgAM.cjs';
2
+ export { aT as CardSetupStatus, aU as CurrencyBalance, h as DestinationGame, aV as DeviceApprovalChannel, aW as DeviceApprovalEnrollment, aX as DeviceApprovalFlow, aY as DeviceApprovalPollStatus, aZ as DeviceEnrollmentDecision, a_ as DeviceEnrollmentRespond, a$ as FirstCharge, b0 as FirstChargeStatus, b1 as FundingSource, b2 as InboundPendingItem, i as InvoErrorInfo, j as InvoHooks, k as InvoRequestInfo, l as InvoResponseInfo, b3 as LinkedIdentityEmail, b4 as PlatformPurchaseStatus, n as Rail, b5 as RefundInitiation, b6 as RefundPendingApproval, b7 as RefundProcessingFeeBasis, b8 as RefundReceipt, b9 as RefundRevenueShareAttribution, ba as RefundWarning, bb as SandboxClockState, bc as SavedCard, bd as SteamPack, be as SteamUserSession, bf as Subscription, bg as SubscriptionBaseInput, bh as SubscriptionConsent, bi as SubscriptionConsentInput, bj as SubscriptionFundingRail, bk as SubscriptionInterval, bl as SubscriptionRevenueShare, bm as SubscriptionRevenueShareInput, bn as SubscriptionStatus, V as VerificationMethod, bo as isRefundPendingApproval } from './types-CBxpXgAM.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.9.0";
9
+ declare const SDK_VERSION = "3.10.0";
10
10
 
11
11
  interface VerifyWebhookOptions {
12
12
  /** Max age of the signed timestamp, in seconds. Default 300 (5 min). */
@@ -40,7 +40,17 @@ interface PurchaseCompletedData {
40
40
  * real answer ("unattributed"), read it as one.
41
41
  */
42
42
  channel?: string | null;
43
- /** The metadata you passed to createCheckout/purchaseCurrency/steamInitPurchase, echoed back (all rails). */
43
+ /**
44
+ * The metadata you passed to createCheckout/purchaseCurrency/steamInitPurchase, echoed back
45
+ * (all rails).
46
+ *
47
+ * **Subscription renewals also emit `purchase.completed`** (every paid card renewal, for the
48
+ * coins its charge minted). Those carry `metadata.source === "subscription_renewal"` and
49
+ * `metadata.subscription_id` (plus `period_seq`, `attempt_no`, `item_id`, `funding_rail`,
50
+ * and `funding_model: "card_only"` on the card rail). **Do not grant currency or access from
51
+ * them**: the renewal spends those coins in the same step. Act on `subscription.renewed`;
52
+ * its `mint_order_id` equals this event's `order_id`.
53
+ */
44
54
  metadata?: Record<string, unknown>;
45
55
  [key: string]: unknown;
46
56
  }
@@ -150,10 +160,18 @@ interface SubscriptionEventCommon {
150
160
  metadata: Record<string, unknown> | null;
151
161
  [key: string]: unknown;
152
162
  }
153
- /** How a renewal was funded: wallet first, then the rail for the shortfall only. */
163
+ /**
164
+ * How a renewal was funded.
165
+ *
166
+ * Card rail (card only since 2026-09-17): the card pays the full price, so
167
+ * `balance_applied_coins` is always `"0.00"`, `card_charged_usd` is the price, `minted_coins`
168
+ * equals the event's `amount_coins`, and `new_balance` is the member's unchanged balance.
169
+ * Steam rail: the wallet is spent first and Steam tops up the shortfall only.
170
+ */
154
171
  interface SubscriptionRenewalFunding {
155
- /** The pre-existing wallet portion, in coins. */
172
+ /** The pre-existing wallet portion, in coins. Always `"0.00"` on the card rail. */
156
173
  balance_applied_coins: string;
174
+ /** On the card rail, the full period price. */
157
175
  card_charged_usd: string;
158
176
  /** "card" | "steam". */
159
177
  rail: string;
@@ -163,7 +181,8 @@ interface SubscriptionRenewalFunding {
163
181
  [key: string]: unknown;
164
182
  }
165
183
  /**
166
- * The fee split for one renewal. On Steam, `basis` is `"steam_net"` and `total_usd` is
184
+ * The fee split for one renewal. On the card rail INVO's fee is its percentage plus $0.30 on
185
+ * the full price. On Steam, `basis` is `"steam_net"` and `total_usd` is
167
186
  * what the coins are worth after Valve's share and VAT, NOT the price (the price is the
168
187
  * event's top-level `amount_usd`).
169
188
  */
@@ -191,7 +210,12 @@ interface SubscriptionRevenueShareAttribution {
191
210
  * `subscription.renewed`: THE SOURCE OF TRUTH FOR ENTITLEMENT. Fires once per successfully
192
211
  * charged period, including period 1. Extend access to `period_end` (the new `paid_through`).
193
212
  * `period_start`/`period_end` are the period JUST PAID; `current_period_*` and
194
- * `next_charge_at` are the NEW window. `mint_order_id` is `null` when the wallet covered it.
213
+ * `next_charge_at` are the NEW window. `mint_order_id` is never `null` on a card renewal; on
214
+ * Steam it is `null` when the wallet covered the period.
215
+ *
216
+ * Every paid card renewal also emits `purchase.completed` (with
217
+ * `data.metadata.source === "subscription_renewal"`) for the coins its charge minted. Do not
218
+ * grant anything from that event; its `order_id` is this event's `mint_order_id`.
195
219
  */
196
220
  interface SubscriptionRenewedData {
197
221
  subscription_id: string;
@@ -230,6 +254,14 @@ interface SubscriptionPaymentFailedData extends SubscriptionEventCommon {
230
254
  /** "card_declined" | "insufficient_funds" | "error". */
231
255
  outcome: string;
232
256
  reason: string;
257
+ /**
258
+ * Why the attempt failed. Card rail: `card_declined`, `no_payment_method` (no saved card;
259
+ * the coin wallet never pays a card subscription), `wallet_only` (a deprecated wallet-only
260
+ * subscription, which can never be paid), `wallet_negative` (the member's coin balance is
261
+ * below zero; nothing was charged), `card_expired`, `card_detached`, `card_mismatch`,
262
+ * `no_customer_snapshot`, `processing_error`, `settlement_error`. Steam: `steam_*` codes.
263
+ * Treat unknown values as a generic failure.
264
+ */
233
265
  failure_code: string;
234
266
  failure_message: string | null;
235
267
  first_failure: boolean;
@@ -249,8 +281,9 @@ interface SubscriptionPastDueData extends SubscriptionEventCommon {
249
281
  /**
250
282
  * `subscription.authentication_required`: NOT a failure. Card rail only. Nothing was
251
283
  * charged and no retry was consumed. Relay `confirmation_url` (a single-use bearer link)
252
- * to the member before `expires_at`. `card_amount_usd` is what the card is asked for (the
253
- * wallet shortfall), which differs from `amount_due_usd` when the member holds a balance.
284
+ * to the member before `expires_at`. `card_amount_usd` is what the card is asked for: since
285
+ * 2026-09-17 the full period price, the same figure as `amount_due_usd` (a challenge opened
286
+ * before that date can still show the older wallet-shortfall figure).
254
287
  */
255
288
  interface SubscriptionAuthenticationRequiredData extends SubscriptionEventCommon {
256
289
  attempt_no: number;
@@ -267,7 +300,9 @@ interface SubscriptionAuthenticationRequiredData extends SubscriptionEventCommon
267
300
  /**
268
301
  * `subscription.canceled`: fires once, at the moment cancellation is requested, in both
269
302
  * modes. Revoke at `access_until`. `canceled_by` is `"partner"` for your API call and
270
- * `"steam"` when the member cancelled the agreement from their Steam account.
303
+ * `"steam"` when the member cancelled the agreement from their Steam account. A full refund
304
+ * also cancels the subscription immediately: that event carries `canceled_by: "partner"` and
305
+ * `cancel_cause: "full_refund"`; it and `subscription.refunded` are sent together and may arrive in any order.
271
306
  */
272
307
  interface SubscriptionCanceledData extends SubscriptionEventCommon {
273
308
  effective_at: string;
@@ -278,13 +313,15 @@ interface SubscriptionCanceledData extends SubscriptionEventCommon {
278
313
  reason: string | null;
279
314
  /** "partner" | "steam". */
280
315
  canceled_by: string;
316
+ /** Present only when the cancellation was a side effect: `"full_refund"`. Absent on an ordinary cancel. */
317
+ cancel_cause?: string;
281
318
  }
282
319
  /**
283
320
  * `subscription.expired`: THE EVENT THAT REVOKES ENTITLEMENT. Revoke at `final_period_end`
284
321
  * (the last instant the member paid for; `null` if nothing was ever collected), not at
285
- * `ended_at`. A never-authorised Steam row carries `failure_code: "steam_authorization_abandoned"`;
286
- * a Steam subscription retired because its value could no longer be spent in this game
287
- * carries `failure_code: "steam_containment"`, with NO `payment_failed` before it.
322
+ * `ended_at`. A never-authorised Steam row carries `failure_code: "steam_authorization_abandoned"`.
323
+ * `failure_code: "steam_containment"` is no longer sent (spending is not restricted by which
324
+ * rail bought the currency).
288
325
  */
289
326
  interface SubscriptionExpiredData extends SubscriptionEventCommon {
290
327
  failed_period_start: string | null;
@@ -310,12 +347,24 @@ interface SubscriptionRefundDetail {
310
347
  partner_revenue_reversed_usd: string;
311
348
  /** "full" | "prorata". */
312
349
  partner_revenue_reversal_mode: string;
350
+ /** Additive (2026-09-17). The card processor fee you bear on a card refund; `"0.00"` on a coin refund. */
351
+ processing_fee_usd?: string;
352
+ /** Additive (2026-09-17). "actual" | "estimated" | "none". */
353
+ processing_fee_basis?: string;
354
+ /** Additive (2026-09-17). Always "partner". */
355
+ processing_fee_borne_by?: string;
356
+ /** Additive (2026-09-17). Revenue reversed plus the processor fee: everything this refund took from your revenue. */
357
+ partner_total_reversed_usd?: string;
313
358
  [key: string]: unknown;
314
359
  }
315
360
  /**
316
361
  * `subscription.refunded`: its own shape. Your revenue for the refunded portion is
317
- * reversed (`refund.partner_revenue_reversed_usd`); INVO's fee is retained. The
318
- * subscription itself is not cancelled by a refund.
362
+ * reversed (`refund.partner_revenue_reversed_usd`); INVO's fee is retained; on a card refund
363
+ * you also bear the processor fee (`refund.processing_fee_usd`). "What did I earn" subtracts
364
+ * `refund.partner_total_reversed_usd` (older events without it: `partner_revenue_reversed_usd`).
365
+ * A FULL refund cancels the subscription (`subscription_canceled: true`), and a
366
+ * `subscription.canceled` with `cancel_cause: "full_refund"` is sent with it (sent together and may arrive in any order).
367
+ * A partial one does not.
319
368
  */
320
369
  interface SubscriptionRefundedData {
321
370
  subscription_id: string;
@@ -335,8 +384,58 @@ interface SubscriptionRefundedData {
335
384
  refund: SubscriptionRefundDetail;
336
385
  revenue_share_attribution: Record<string, unknown> | null;
337
386
  metadata: Record<string, unknown> | null;
387
+ /** Additive (2026-09-17). "self_serve" | "approved_request". */
388
+ initiation?: string;
389
+ /** Additive (2026-09-17). The refund request INVO approved, or `null`. */
390
+ refund_request_id?: string | null;
391
+ /** Additive (2026-09-17). `true` when this refund cancelled the subscription. */
392
+ subscription_canceled?: boolean;
338
393
  [key: string]: unknown;
339
394
  }
395
+ /**
396
+ * `subscription.refund_requested`: a refund over your game's daily self-serve limit became a
397
+ * refund request (your `/refund` call answered 202 `pending_approval`). Nothing has moved.
398
+ * Not the common subscription block: it describes the request.
399
+ */
400
+ interface SubscriptionRefundRequestData {
401
+ /** `SRR...`. */
402
+ request_id: string;
403
+ /** "pending" | "approved" | "rejected". */
404
+ status: string;
405
+ subscription_id: string;
406
+ item_id: string;
407
+ period_seq: number;
408
+ client_request_id: string;
409
+ /** The amount asked for. */
410
+ amount_usd: string;
411
+ /** Your reason, or `null` when you sent none. */
412
+ reason: string | null;
413
+ requested_at: string;
414
+ daily_cap_usd: string;
415
+ executed_today_usd: string;
416
+ player_email: string | null;
417
+ identity_id: string | null;
418
+ metadata: Record<string, unknown> | null;
419
+ [key: string]: unknown;
420
+ }
421
+ /**
422
+ * `subscription.refund_approved`: INVO approved the request and the refund ran;
423
+ * `subscription.refunded` (and `subscription.canceled` on a full refund) are sent in the same
424
+ * step and may arrive before or after this event. A retry of your `clientRequestId` now returns the receipt.
425
+ */
426
+ interface SubscriptionRefundApprovedData extends SubscriptionRefundRequestData {
427
+ decided_at: string;
428
+ /** The refund transaction. */
429
+ transaction_id: string;
430
+ }
431
+ /**
432
+ * `subscription.refund_rejected`: INVO rejected the request; nothing moved. Your
433
+ * `clientRequestId` now answers `409 REFUND_REQUEST_REJECTED`; use a new one to try again.
434
+ */
435
+ interface SubscriptionRefundRejectedData extends SubscriptionRefundRequestData {
436
+ decided_at: string;
437
+ decision_reason: string | null;
438
+ }
340
439
  type PurchaseEventType = "purchase.failed" | "purchase.refunded" | "purchase.disputed" | "purchase.fraud_warning";
341
440
  type TransferEventType = "transfer.sent" | "transfer.received" | "transfer.claim_pending" | "transfer.claim_expired" | "transfer.refunded";
342
441
  /**
@@ -382,6 +481,15 @@ type InvoWebhookEvent = (WebhookBase & {
382
481
  }) | (WebhookBase & {
383
482
  event_type: "subscription.refunded";
384
483
  data: SubscriptionRefundedData;
484
+ }) | (WebhookBase & {
485
+ event_type: "subscription.refund_requested";
486
+ data: SubscriptionRefundRequestData;
487
+ }) | (WebhookBase & {
488
+ event_type: "subscription.refund_approved";
489
+ data: SubscriptionRefundApprovedData;
490
+ }) | (WebhookBase & {
491
+ event_type: "subscription.refund_rejected";
492
+ data: SubscriptionRefundRejectedData;
385
493
  }) | (WebhookBase & {
386
494
  event_type: "payout.status_changed";
387
495
  data: Record<string, unknown>;
@@ -530,8 +638,13 @@ declare class SubscriptionsServer {
530
638
  * `err.existingSubscriptionId`) at best and a second subscription at worst. Same key
531
639
  * with different terms is `err.isIdempotentReplayMismatch` (`err.mismatchedFields`).
532
640
  *
533
- * Card selection: `playerCardId` names one (from `cards.list`); omitted, INVO attaches
534
- * the member's newest unexpired saved card; `walletOnly: true` never charges a card.
641
+ * Card only (since 2026-09-17): the card is charged the full price every period and the
642
+ * member's coin wallet never pays and never moves. Card selection: `playerCardId` names one
643
+ * (from `cards.list`); omitted, INVO attaches the member's newest unexpired saved card. With
644
+ * no saved card the subscription is still created (201) but `firstCharge` is `failed` with
645
+ * `failureCode: "no_payment_method"`, whatever the member's balance: save a card first.
646
+ * `walletOnly: true` is deprecated: it never charges a card, so such a subscription can never
647
+ * be paid (`failureCode: "wallet_only"`).
535
648
  * Requires the game to be `live` (`err.isGameNotLive`).
536
649
  */
537
650
  create(input: CreateSubscriptionInput, opts?: CallOptions): Promise<SubscriptionResult>;
@@ -572,9 +685,9 @@ declare class SubscriptionsServer {
572
685
  /**
573
686
  * Card subscriptions only. Attach a card (`{ playerCardId }`, an `id` from
574
687
  * `cards.list` belonging to this player, unexpired) or make the subscription wallet-only
575
- * (`{ walletOnly: true }`). On a wallet-only subscription pass `walletOnly: false`
576
- * beside the card to convert it back. The new card is used from the next charge,
577
- * including a pending retry in dunning.
688
+ * (`{ walletOnly: true }`, deprecated: a wallet-only card subscription can never be paid).
689
+ * On a wallet-only subscription pass `walletOnly: false` beside the card to convert it
690
+ * back. The new card is used from the next charge, including a pending retry in dunning.
578
691
  *
579
692
  * `err.isNotACardSubscription` on Steam; `err.isSubscriptionTerminal` on a terminal row.
580
693
  */
@@ -583,16 +696,35 @@ declare class SubscriptionsServer {
583
696
  * Refund a billed period (card rail). Idempotent on `clientRequestId`: a repeat returns
584
697
  * the stored receipt with `idempotentReplay: true` and moves nothing.
585
698
  *
586
- * A full refund returns the card charge and reclaims the coins that charge minted
587
- * (`balanceDeltaCoins` is signed and can be negative); a partial refund credits the
588
- * wallet in coins at the 10:1 peg. Your revenue is reversed for the refunded portion
589
- * (`partnerRevenueReversedUsd`); INVO's fee is retained. The subscription is NOT
590
- * cancelled by a refund. Refunds of Steam-CHARGED periods are not supported yet; do not
591
- * call this on them.
699
+ * **Branch on `status`.** `"refunded"` (HTTP 200): the refund ran. `"pending_approval"`
700
+ * (HTTP 202): the refund would exceed the game's daily self-serve limit ($500 per UTC day
701
+ * by default), NOTHING moved, and INVO reviews it as a refund request (`requestId`); the
702
+ * outcome arrives as `subscription.refund_approved` (sent together with
703
+ * `subscription.refunded`, and `subscription.canceled` on a full refund, in any order) or
704
+ * `subscription.refund_rejected`. The 202 carries every receipt field with nothing moved
705
+ * (`refundedAmountUsd` is `"0.00"`; `totalRefundedAmountUsd` and `remainingRefundableUsd`
706
+ * carry the period's real values). Check it with {@link isRefundPendingApproval}.
707
+ *
708
+ * A card-only period (every card period charged since 2026-09-17) is refunded in cash, full
709
+ * or partial: `cardRefundedUsd` equals the amount and `balanceDeltaCoins` is `"0.00"`. A
710
+ * period charged before that keeps the earlier rule: a full refund returns the card charge
711
+ * and reclaims the coins it minted (`balanceDeltaCoins` is signed), a partial refund
712
+ * credits coins. Your revenue is reversed for the refunded portion
713
+ * (`partnerRevenueReversedUsd`), INVO's fee is retained, and on a card refund you bear the
714
+ * processor fee (`processingFeeUsd`; `partnerTotalReversedUsd` is the sum). **A full refund
715
+ * cancels the subscription** (`subscriptionCanceled`, and a `subscription.canceled` event
716
+ * with `cancel_cause: "full_refund"`, sent together with `subscription.refunded` in any
717
+ * order); a partial one does not. INVO emails the member.
718
+ * Refunds run within 30 days of the period's charge. Send a `reason`: it is recommended now
719
+ * and will be required later (`warnings` says so when it is missing).
592
720
  *
593
- * Refusals: `NO_PAID_PERIOD` (409, nothing collected yet), `PERIOD_NOT_REFUNDABLE`,
594
- * `ALREADY_REFUNDED` (`err.isAlreadyRefunded`), `AMOUNT_EXCEEDS_REMAINING` (body carries
595
- * `remaining_refundable_usd`), `err.isFlowPaused`.
721
+ * Refusals: `err.isRefundsNotEnabled` (403), `err.isRefundWindowClosed` (409),
722
+ * `err.isRefundRequestPending` (409, `err.refundRequestId`), `err.isRefundRequestRejected`
723
+ * (409, use a new key), `err.isConcurrentRequest` (409, retry with the same key),
724
+ * `err.isRefundMismatch` (502, contact INVO), `NO_PAID_PERIOD` (409, nothing collected yet),
725
+ * `PERIOD_NOT_REFUNDABLE`, `ALREADY_REFUNDED` (`err.isAlreadyRefunded`),
726
+ * `AMOUNT_EXCEEDS_REMAINING` (body carries `remaining_refundable_usd`),
727
+ * `err.isSteamRefundNotSupported`, `err.isFlowPaused`.
596
728
  */
597
729
  refund(subscriptionId: string, input: RefundSubscriptionInput, opts?: CallOptions): Promise<RefundResult>;
598
730
  /**
@@ -758,7 +890,8 @@ declare class SandboxSubscriptionsServer {
758
890
  advanceClock(subscriptionId: string, intervals?: number, opts?: CallOptions): Promise<SandboxClockResult>;
759
891
  /**
760
892
  * Run the renewal immediately. **Charges the test card** (or the Steam stand-in): the
761
- * real money path, wallet read, shortfall, mint, spend, split, `subscription.renewed`,
893
+ * real money path (card: the full price; Steam: wallet first, then the shortfall), mint,
894
+ * spend, split, `subscription.renewed`,
762
895
  * and on failure the real dunning. Read `engineStats` (`renewed: 1` on success). A
763
896
  * cancel-at-period-end row answers `action: "retired-at-period-end"`, `retired: true`.
764
897
  * `409 PERIOD_TOO_FAR_AHEAD` means you forced twice without advancing the clock.
@@ -1194,4 +1327,4 @@ declare class InvoServer {
1194
1327
  private toInitiateResult;
1195
1328
  }
1196
1329
 
1197
- export { ApproveWithDeviceCodeInput, BeginDeviceApprovalInput, CallOptions, CancelResult, CancelSubscriptionOptions, CardSetupConfirmInput, CardSetupConfirmResult, CardSetupInput, CardSetupResult, CardSetupSessionInput, CardSetupSessionResult, CardsServer, ChangeAmountResult, ClaimCurrencyInput, ClaimResult, ClaimTransferInput, CompleteDeviceApprovalInput, CompleteDeviceApprovalResult, ConfirmDeviceEnrollmentInput, ConfirmDeviceEnrollmentResult, ConfirmPaymentResult, CreateCheckoutInput, CreateCheckoutResult, CreateSubscriptionInput, DestinationsResult, DeviceApprovalGrant, DeviceApprovalPollResult, DeviceApprovalSettleResult, GetSubscriptionOptions, GetSubscriptionResult, GuardianApprovalStatusResult, InboundPendingQuery, InboundPendingResult, InitiateResult, InitiateSendInput, InitiateTransferInput, InvoError, InvoServer, type InvoWebhookEvent, ItemHistoryQuery, ItemHistoryResult, ItemOrderQuery, type ItemPurchasedData, LinkedIdentitiesQuery, LinkedIdentitiesResult, ListSubscriptionsOptions, OrderDetailsResult, PhoneShareApproveInput, PhoneShareApproveResult, PhoneShareContact, PhoneShareInitiateResult, PhoneShareStatusResult, type PlatformCommercePurchasedData, type PlatformCommerceRefundedData, PlatformCommerceServer, PlatformOrderStatusResult, PlatformPurchaseInput, PlatformPurchaseResult, PlatformRefundInput, PlatformRefundResult, PlayerBalanceQuery, PlayerBalanceResult, PlayerCardsResult, PlayerToken, PollDeviceApprovalInput, type PurchaseCompletedData, type PurchaseEventData, PurchaseInput, PurchaseItemInput, PurchaseItemResult, PurchaseResult, RefundResult, RefundSubscriptionInput, SDK_VERSION, SandboxClockResult, SandboxFailureOutcome, SandboxForceAuthChallengeOptions, SandboxForceFailureOptions, SandboxServer, SandboxSubscriptionsServer, ServerConfig, ServerDestinationsQuery, SetPaymentMethodInput, SetPaymentMethodResult, SmsVerifyResult, SteamFinalizeInput, SteamFinalizeResult, SteamFinalizeSubscriptionResult, SteamInitPurchaseInput, SteamInitPurchaseResult, SteamInitResult, SteamPacksQuery, SteamPacksResult, SteamSubscriptionInitInput, type SubscriptionAuthenticationRequiredData, type SubscriptionCanceledData, type SubscriptionEventCommon, type SubscriptionExpiredData, SubscriptionListResult, type SubscriptionPastDueData, type SubscriptionPaymentFailedData, type SubscriptionRefundDetail, type SubscriptionRefundedData, type SubscriptionRenewalFunding, type SubscriptionRenewalSplit, type SubscriptionRenewedData, SubscriptionResult, type SubscriptionRevenueShareAttribution, SubscriptionsServer, TransactionStatusResult, type TransferEventData, type VerifyWebhookOptions, type WebhookHandlerOptions, createWebhookHandler, verifyWebhook, verifyWebhookAsync };
1330
+ export { ApproveWithDeviceCodeInput, BeginDeviceApprovalInput, CallOptions, CancelResult, CancelSubscriptionOptions, CardSetupConfirmInput, CardSetupConfirmResult, CardSetupInput, CardSetupResult, CardSetupSessionInput, CardSetupSessionResult, CardsServer, ChangeAmountResult, ClaimCurrencyInput, ClaimResult, ClaimTransferInput, CompleteDeviceApprovalInput, CompleteDeviceApprovalResult, ConfirmDeviceEnrollmentInput, ConfirmDeviceEnrollmentResult, ConfirmPaymentResult, CreateCheckoutInput, CreateCheckoutResult, CreateSubscriptionInput, DestinationsResult, DeviceApprovalGrant, DeviceApprovalPollResult, DeviceApprovalSettleResult, GetSubscriptionOptions, GetSubscriptionResult, GuardianApprovalStatusResult, InboundPendingQuery, InboundPendingResult, InitiateResult, InitiateSendInput, InitiateTransferInput, InvoError, InvoServer, type InvoWebhookEvent, ItemHistoryQuery, ItemHistoryResult, ItemOrderQuery, type ItemPurchasedData, LinkedIdentitiesQuery, LinkedIdentitiesResult, ListSubscriptionsOptions, OrderDetailsResult, PhoneShareApproveInput, PhoneShareApproveResult, PhoneShareContact, PhoneShareInitiateResult, PhoneShareStatusResult, type PlatformCommercePurchasedData, type PlatformCommerceRefundedData, PlatformCommerceServer, PlatformOrderStatusResult, PlatformPurchaseInput, PlatformPurchaseResult, PlatformRefundInput, PlatformRefundResult, PlayerBalanceQuery, PlayerBalanceResult, PlayerCardsResult, PlayerToken, PollDeviceApprovalInput, type PurchaseCompletedData, type PurchaseEventData, PurchaseInput, PurchaseItemInput, PurchaseItemResult, PurchaseResult, RefundResult, RefundSubscriptionInput, SDK_VERSION, SandboxClockResult, SandboxFailureOutcome, SandboxForceAuthChallengeOptions, SandboxForceFailureOptions, SandboxServer, SandboxSubscriptionsServer, ServerConfig, ServerDestinationsQuery, SetPaymentMethodInput, SetPaymentMethodResult, SmsVerifyResult, SteamFinalizeInput, SteamFinalizeResult, SteamFinalizeSubscriptionResult, SteamInitPurchaseInput, SteamInitPurchaseResult, SteamInitResult, SteamPacksQuery, SteamPacksResult, SteamSubscriptionInitInput, type SubscriptionAuthenticationRequiredData, type SubscriptionCanceledData, type SubscriptionEventCommon, type SubscriptionExpiredData, SubscriptionListResult, type SubscriptionPastDueData, type SubscriptionPaymentFailedData, type SubscriptionRefundApprovedData, type SubscriptionRefundDetail, type SubscriptionRefundRejectedData, type SubscriptionRefundRequestData, type SubscriptionRefundedData, type SubscriptionRenewalFunding, type SubscriptionRenewalSplit, type SubscriptionRenewedData, SubscriptionResult, type SubscriptionRevenueShareAttribution, SubscriptionsServer, TransactionStatusResult, type TransferEventData, type VerifyWebhookOptions, type WebhookHandlerOptions, createWebhookHandler, verifyWebhook, verifyWebhookAsync };