@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.d.ts CHANGED
@@ -1,12 +1,12 @@
1
- import { I as InvoError, H as Http, o as AuthHeader, p as CardSetupInput, c as CallOptions, q as CardSetupResult, r as CardSetupConfirmInput, s as CardSetupConfirmResult, t as PlayerCardsResult, u as PlatformPurchaseInput, v as PlatformPurchaseResult, w as PlatformOrderStatusResult, x as PlatformRefundInput, y as PlatformRefundResult, z as CreateSubscriptionInput, S as SubscriptionResult, G as GetSubscriptionOptions, F as GetSubscriptionResult, J as ListSubscriptionsOptions, K as SubscriptionListResult, N as CancelSubscriptionOptions, O as CancelResult, Q as ChangeAmountResult, T as SetPaymentMethodInput, U as SetPaymentMethodResult, W as RefundSubscriptionInput, X as RefundResult, Y as SteamSubscriptionInitInput, Z as SteamInitResult, _ as SteamFinalizeSubscriptionResult, $ as SandboxClockResult, a0 as SandboxFailureOutcome, a1 as SandboxForceFailureOptions, a2 as SandboxForceAuthChallengeOptions, a3 as ServerConfig, a4 as PlayerToken, a5 as InitiateSendInput, a6 as InitiateResult, a7 as InitiateTransferInput, a8 as CreateCheckoutInput, a9 as CreateCheckoutResult, aa as PurchaseInput, ab as PurchaseResult, ac as ConfirmPaymentResult, ad as OrderDetailsResult, ae as SteamPacksQuery, af as SteamPacksResult, ag as SteamInitPurchaseInput, ah as SteamInitPurchaseResult, ai as SteamFinalizeInput, aj as SteamFinalizeResult, ak as PurchaseItemInput, al as PurchaseItemResult, am as ItemHistoryQuery, an as ItemHistoryResult, ao as ItemOrderQuery, ap as PlayerBalanceQuery, aq as PlayerBalanceResult, ar as InboundPendingQuery, as as InboundPendingResult, at as LinkedIdentitiesQuery, au as LinkedIdentitiesResult, av as SmsVerifyResult, aw as ClaimTransferInput, ax as ClaimResult, ay as ClaimCurrencyInput, az as TransactionStatusResult, aA as GuardianApprovalStatusResult, aB as ServerDestinationsQuery, d as DestinationsResult, aC as PhoneShareContact, aD as PhoneShareInitiateResult, aE as PhoneShareApproveInput, aF as PhoneShareApproveResult, aG as PhoneShareStatusResult, aH as BeginDeviceApprovalInput, aI as DeviceApprovalGrant, aJ as PollDeviceApprovalInput, aK as DeviceApprovalPollResult, aL as ConfirmDeviceEnrollmentInput, aM as ConfirmDeviceEnrollmentResult, aN as ApproveWithDeviceCodeInput, aO as DeviceApprovalSettleResult, aP as CompleteDeviceApprovalInput, aQ as CompleteDeviceApprovalResult } from './types-DqRuqbqI.js';
2
- export { aR as CardSetupStatus, aS as CurrencyBalance, h as DestinationGame, aT as DeviceApprovalChannel, aU as DeviceApprovalEnrollment, aV as DeviceApprovalFlow, aW as DeviceApprovalPollStatus, aX as DeviceEnrollmentDecision, aY as DeviceEnrollmentRespond, aZ as FirstCharge, a_ as FirstChargeStatus, a$ as FundingSource, b0 as InboundPendingItem, i as InvoErrorInfo, j as InvoHooks, k as InvoRequestInfo, l as InvoResponseInfo, b1 as LinkedIdentityEmail, b2 as PlatformPurchaseStatus, n as Rail, b3 as RefundRevenueShareAttribution, b4 as SandboxClockState, b5 as SavedCard, b6 as SteamPack, b7 as SteamUserSession, b8 as Subscription, b9 as SubscriptionBaseInput, ba as SubscriptionConsent, bb as SubscriptionConsentInput, bc as SubscriptionFundingRail, bd as SubscriptionInterval, be as SubscriptionRevenueShare, bf as SubscriptionRevenueShareInput, bg as SubscriptionStatus, V as VerificationMethod } from './types-DqRuqbqI.js';
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.js';
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.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.8.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;
393
+ [key: string]: unknown;
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;
338
419
  [key: string]: unknown;
339
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}.
592
707
  *
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`.
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).
720
+ *
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
  /**
@@ -643,16 +775,58 @@ declare class SubscriptionsServer {
643
775
  /**
644
776
  * Saved cards for off-session (recurring) use: the card capture a card subscription
645
777
  * needs. Reached as `invo.cards.*`. The subscription endpoints never receive card data
646
- * and neither does this SDK: the card form on the client tokenises it. A card saved
647
- * through the hosted checkout, or through a `savedCardId` purchase, does NOT carry the
648
- * off-session consent a subscription needs; capture it here (or with a
649
- * `purchaseCurrency` that sets `save_card: true`).
778
+ * and neither does this SDK.
779
+ *
780
+ * THE RECOMMENDED CAPTURE IS {@link createSetupSession}: INVO hosts the card page, you
781
+ * mint a link server-side and send the member to it, and nothing in your integration
782
+ * references a card processor or loads its script. {@link beginSetup} /
783
+ * {@link confirmSetup} are the processor-bound alternative for a partner who already
784
+ * runs a card form in their own client against INVO's current processor.
785
+ *
786
+ * A card saved through the hosted CHECKOUT page, or through a `savedCardId` purchase,
787
+ * does NOT carry the off-session consent a subscription needs; capture it here (or with
788
+ * a `purchaseCurrency` that sets `save_card: true`).
650
789
  */
651
790
  declare class CardsServer {
652
791
  private readonly http;
653
792
  private readonly auth;
654
793
  constructor(http: Http, auth: AuthHeader);
655
794
  /**
795
+ * Mint a short-lived session for the INVO-hosted card page and return its URL. THE
796
+ * RECOMMENDED WAY TO SAVE A CARD FOR A SUBSCRIPTION: two server-to-server calls (this
797
+ * one, then `cards.list`) and one redirect. No browser code, no processor script, no
798
+ * client secret; INVO can change card processor without you changing anything.
799
+ *
800
+ * The member must already exist in this game (`err.isPlayerNotFound`, 404); the page
801
+ * never creates players. Send the member to `result.cardSetupUrl` top-level (do not
802
+ * frame it). The page says in words that no money moves, saves the card, and then
803
+ * redirects to `successUrl` (or shows "Card saved" when you gave none). The saved card
804
+ * appears in {@link list} immediately, carries the off-session consent a subscription
805
+ * needs, and is indistinguishable from one saved any other way. There is no event for
806
+ * a saved card; `cards.list` is the signal.
807
+ *
808
+ * The session lives 10 minutes (entering a card is one sitting); mint it when the
809
+ * member is about to use it. The link may be reloaded freely before the save; once the
810
+ * card is saved the link is spent and reopening it returns the same card again.
811
+ * `successUrl` is redirected to verbatim (nothing appended) and `metadata` is stored on
812
+ * the session and not returned anywhere today, so put your own correlation id in
813
+ * `successUrl`.
814
+ *
815
+ * Refusals: `err.isInvalidPlayerEmail` (400, a non-email string; a missing or blank
816
+ * `playerEmail` is refused here first with `status: 0`), `err.isPlayerNotFound` (404),
817
+ * `err.isInvalidInput` (400: a script-scheme `successUrl` / `cancelUrl`; the SDK
818
+ * refuses the same values first with `status: 0`), 401 / 403 on the key or the game
819
+ * (body `{ message }`, no code), 503 when card setup is not available right now.
820
+ * Never auto-retried: each call mints a fresh link, so on a timeout call it again.
821
+ */
822
+ createSetupSession(input: CardSetupSessionInput, opts?: CallOptions): Promise<CardSetupSessionResult>;
823
+ /**
824
+ * THE PROCESSOR-BOUND ALTERNATIVE to {@link createSetupSession}. Use it only if you
825
+ * already run a card form in your own client against INVO's current card processor:
826
+ * the `clientSecret` it hands back can only be consumed by that processor's client
827
+ * library, so the browser code you write for it will need rework when INVO changes
828
+ * processor. `createSetupSession` does not have that problem.
829
+ *
656
830
  * Begin saving a card (charges nothing). The player must already exist in this game
657
831
  * (`404 PLAYER_NOT_FOUND`). Idempotent on `setupReference`: resend the same value on a
658
832
  * retry and you get the same setup back (`409 SETUP_REFERENCE_REUSED` if you reuse it
@@ -667,6 +841,9 @@ declare class CardsServer {
667
841
  */
668
842
  beginSetup(input: CardSetupInput, opts?: CallOptions): Promise<CardSetupResult>;
669
843
  /**
844
+ * The second half of the processor-bound alternative (see {@link beginSetup}); not
845
+ * needed on the {@link createSetupSession} path, where INVO's page completes the save.
846
+ *
670
847
  * Finish a client-confirmed setup and save the card. Idempotent on `setupIntentId`.
671
848
  * While the client has not finished, this throws a 400 with body
672
849
  * `status: "still_requires_action"`. On `500 CARD_PERSIST_FAILED` (authorised but not
@@ -677,7 +854,8 @@ declare class CardsServer {
677
854
  * A member's unexpired saved cards, newest first. An unknown player is `{ cards: [] }`.
678
855
  * The `id` is the value you pass as `playerCardId`; INVO never returns processor
679
856
  * identifiers for a card. Served from a short cache (about 60 s); a card saved through
680
- * `beginSetup` / `confirmSetup` appears immediately.
857
+ * the hosted card page (`createSetupSession`) or through `beginSetup` / `confirmSetup`
858
+ * appears immediately. This read is the signal that the hosted page saved a card.
681
859
  */
682
860
  list(playerEmail: string, opts?: CallOptions): Promise<PlayerCardsResult>;
683
861
  }
@@ -712,7 +890,8 @@ declare class SandboxSubscriptionsServer {
712
890
  advanceClock(subscriptionId: string, intervals?: number, opts?: CallOptions): Promise<SandboxClockResult>;
713
891
  /**
714
892
  * Run the renewal immediately. **Charges the test card** (or the Steam stand-in): the
715
- * 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`,
716
895
  * and on failure the real dunning. Read `engineStats` (`renewed: 1` on success). A
717
896
  * cancel-at-period-end row answers `action: "retired-at-period-end"`, `retired: true`.
718
897
  * `409 PERIOD_TOO_FAR_AHEAD` means you forced twice without advancing the clock.
@@ -1148,4 +1327,4 @@ declare class InvoServer {
1148
1327
  private toInitiateResult;
1149
1328
  }
1150
1329
 
1151
- export { ApproveWithDeviceCodeInput, BeginDeviceApprovalInput, CallOptions, CancelResult, CancelSubscriptionOptions, CardSetupConfirmInput, CardSetupConfirmResult, CardSetupInput, CardSetupResult, 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 };