@invonetwork/web-sdk 3.12.1 → 3.14.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.cts CHANGED
@@ -1,12 +1,12 @@
1
- import { I as InvoError, H as Http, x as AuthHeader, y as CardSetupSessionInput, g as CallOptions, z as CardSetupSessionResult, F as CardSetupInput, G as CardSetupResult, J as CardSetupConfirmInput, K as CardSetupConfirmResult, N as PlayerCardsResult, O as PlatformPurchaseInput, Q as PlatformPurchaseResult, S as PlatformOrderStatusResult, T as PlatformRefundInput, U as PlatformRefundResult, X as CreateSubscriptionInput, Y as SubscriptionResult, Z as GetSubscriptionOptions, _ as GetSubscriptionResult, $ as ListSubscriptionsOptions, a0 as SubscriptionListResult, a1 as CancelSubscriptionOptions, a2 as CancelResult, a3 as ChangeAmountResult, a4 as SetPaymentMethodInput, a5 as SetPaymentMethodResult, a6 as RefundSubscriptionInput, a7 as RefundResult, a8 as SteamSubscriptionInitInput, a9 as SteamInitResult, aa as SteamFinalizeSubscriptionResult, ab as SandboxClockResult, ac as SandboxFailureOutcome, ad as SandboxForceFailureOptions, ae as SandboxForceAuthChallengeOptions, af as ServerConfig, ag as PlayerToken, ah as InitiateSendInput, ai as InitiateResult, aj as InitiateTransferInput, ak as CreateCheckoutInput, al as CreateCheckoutResult, am as PurchaseInput, an as PurchaseResult, ao as ConfirmPaymentResult, ap as OrderDetailsResult, aq as SteamPacksQuery, ar as SteamPacksResult, as as SteamInitPurchaseInput, at as SteamInitPurchaseResult, au as SteamFinalizeInput, av as SteamFinalizeResult, aw as PurchaseItemInput, ax as PurchaseItemResult, ay as ItemHistoryQuery, az as ItemHistoryResult, aA as ItemOrderQuery, aB as PlayerBalanceQuery, aC as PlayerBalanceResult, aD as InboundPendingQuery, aE as InboundPendingResult, aF as LinkedIdentitiesQuery, aG as LinkedIdentitiesResult, aH as SmsVerifyResult, aI as ClaimTransferInput, aJ as ClaimResult, aK as ClaimCurrencyInput, aL as TransactionStatusResult, aM as GuardianApprovalStatusResult, aN as ServerDestinationsQuery, k as DestinationsResult, aO as PhoneShareContact, aP as PhoneShareInitiateResult, aQ as PhoneShareApproveInput, aR as PhoneShareApproveResult, aS as PhoneShareStatusResult, aT as BeginDeviceApprovalInput, aU as DeviceApprovalGrant, aV as PollDeviceApprovalInput, aW as DeviceApprovalPollResult, aX as ConfirmDeviceEnrollmentInput, aY as ConfirmDeviceEnrollmentResult, aZ as ApproveWithDeviceCodeInput, a_ as DeviceApprovalSettleResult, a$ as CompleteDeviceApprovalInput, b0 as CompleteDeviceApprovalResult } from './types-CT0Ksonp.cjs';
2
- export { b1 as CardSetupStatus, b2 as CurrencyBalance, p as DestinationGame, b3 as DeviceApprovalChannel, b4 as DeviceApprovalEnrollment, b5 as DeviceApprovalFlow, b6 as DeviceApprovalPollStatus, b7 as DeviceEnrollmentDecision, b8 as DeviceEnrollmentRespond, b9 as FirstCharge, ba as FirstChargeStatus, bb as FundingSource, bc as InboundPendingItem, q as InvoErrorInfo, r as InvoHooks, s as InvoRequestInfo, t as InvoResponseInfo, bd as LinkedIdentityEmail, be as PlatformPurchaseStatus, w as Rail, bf as RefundInitiation, bg as RefundPendingApproval, bh as RefundProcessingFeeBasis, bi as RefundReceipt, bj as RefundRevenueShareAttribution, bk as RefundWarning, bl as SandboxClockState, bm as SavedCard, bn as SteamPack, bo as SteamUserSession, bp as Subscription, bq as SubscriptionBaseInput, br as SubscriptionConsent, bs as SubscriptionConsentInput, bt as SubscriptionFundingRail, bu as SubscriptionInterval, bv as SubscriptionRevenueShare, bw as SubscriptionRevenueShareInput, bx as SubscriptionStatus, V as VerificationMethod, by as isRefundPendingApproval } from './types-CT0Ksonp.cjs';
1
+ import { I as InvoError, H as Http, x as AuthHeader, y as CardSetupSessionInput, g as CallOptions, z as CardSetupSessionResult, F as CardSetupInput, G as CardSetupResult, J as CardSetupConfirmInput, K as CardSetupConfirmResult, N as PlayerCardsResult, O as PlatformPurchaseInput, Q as PlatformPurchaseResult, S as PlatformOrderStatusResult, T as PlatformRefundInput, U as PlatformRefundResult, X as CreateSubscriptionInput, Y as SubscriptionResult, Z as GetSubscriptionOptions, _ as GetSubscriptionResult, $ as ListSubscriptionsOptions, a0 as SubscriptionListResult, a1 as CancelSubscriptionOptions, a2 as CancelResult, a3 as ChangeAmountResult, a4 as SetPaymentMethodInput, a5 as SetPaymentMethodResult, a6 as RefundSubscriptionInput, a7 as RefundResult, a8 as SteamSubscriptionInitInput, a9 as SteamInitResult, aa as SteamFinalizeSubscriptionResult, ab as SandboxClockResult, ac as SandboxFailureOutcome, ad as SandboxForceFailureOptions, ae as SandboxForceAuthChallengeOptions, af as ServerConfig, ag as PlayerToken, ah as InitiateSendInput, ai as InitiateResult, aj as InitiateTransferInput, ak as CreateCheckoutInput, al as CreateCheckoutResult, am as PurchaseInput, an as PurchaseResult, ao as CurrencyPurchaseQuoteInput, ap as CurrencyPurchaseQuote, aq as ConfirmPaymentResult, ar as OrderDetailsResult, as as SteamPacksQuery, at as SteamPacksResult, au as SteamInitPurchaseInput, av as SteamInitPurchaseResult, aw as SteamFinalizeInput, ax as SteamFinalizeResult, ay as PurchaseItemInput, az as PurchaseItemResult, aA as ItemHistoryQuery, aB as ItemHistoryResult, aC as ItemOrderQuery, aD as PlayerBalanceQuery, aE as PlayerBalanceResult, aF as InboundPendingQuery, aG as InboundPendingResult, aH as LinkedIdentitiesQuery, aI as LinkedIdentitiesResult, aJ as SmsVerifyResult, aK as ClaimTransferInput, aL as ClaimResult, aM as ClaimCurrencyInput, aN as TransactionStatusResult, aO as GuardianApprovalStatusResult, aP as ServerDestinationsQuery, k as DestinationsResult, aQ as PhoneShareContact, aR as PhoneShareInitiateResult, aS as PhoneShareApproveInput, aT as PhoneShareApproveResult, aU as PhoneShareStatusResult, aV as BeginDeviceApprovalInput, aW as DeviceApprovalGrant, aX as PollDeviceApprovalInput, aY as DeviceApprovalPollResult, aZ as ConfirmDeviceEnrollmentInput, a_ as ConfirmDeviceEnrollmentResult, a$ as ApproveWithDeviceCodeInput, b0 as DeviceApprovalSettleResult, b1 as CompleteDeviceApprovalInput, b2 as CompleteDeviceApprovalResult } from './types-CD83iV3D.cjs';
2
+ export { b3 as CardSetupStatus, b4 as CurrencyBalance, b5 as CurrencyPurchaseQuoteBreakdown, p as DestinationGame, b6 as DeviceApprovalChannel, b7 as DeviceApprovalEnrollment, b8 as DeviceApprovalFlow, b9 as DeviceApprovalPollStatus, ba as DeviceEnrollmentDecision, bb as DeviceEnrollmentRespond, bc as FeeTakenFrom, bd as FirstCharge, be as FirstChargeStatus, bf as FundingSource, bg as InboundPendingItem, q as InvoErrorInfo, r as InvoHooks, s as InvoRequestInfo, t as InvoResponseInfo, bh as LinkedIdentityEmail, bi as PlatformPurchaseStatus, w as Rail, bj as RefundInitiation, bk as RefundPendingApproval, bl as RefundProcessingFeeBasis, bm as RefundReceipt, bn as RefundRevenueShareAttribution, bo as RefundWarning, bp as SandboxClockState, bq as SavedCard, br as SteamPack, bs as SteamUserSession, bt as Subscription, bu as SubscriptionBaseInput, bv as SubscriptionConsent, bw as SubscriptionConsentInput, bx as SubscriptionFundingRail, by as SubscriptionInterval, bz as SubscriptionRevenueShare, bA as SubscriptionRevenueShareInput, bB as SubscriptionStatus, bC as UnacknowledgedPurchaseOutcome, V as VerificationMethod, bD as isRefundPendingApproval } from './types-CD83iV3D.cjs';
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.12.1";
9
+ declare const SDK_VERSION = "3.14.0";
10
10
 
11
11
  interface VerifyWebhookOptions {
12
12
  /** Max age of the signed timestamp, in seconds. Default 300 (5 min). */
@@ -52,6 +52,19 @@ interface PurchaseCompletedData {
52
52
  * its `mint_order_id` equals this event's `order_id`.
53
53
  */
54
54
  metadata?: Record<string, unknown>;
55
+ /**
56
+ * Why the tax is what it is. `"partner_responsible"` on an Open-tier account (you are the
57
+ * seller; INVO charged no tax); on Merchant of Record, how INVO handled it (for example
58
+ * `"collected"`). Treat an unknown value as informational.
59
+ */
60
+ tax_treatment?: string | null;
61
+ /**
62
+ * Merchant of Record accounts only (card sales): the receipt INVO issued to the buyer.
63
+ * Absent on Open accounts and storefront rails.
64
+ */
65
+ receipt_number?: string;
66
+ /** Merchant of Record only: link to the printable receipt page. Anyone with it can read it. */
67
+ receipt_url?: string;
55
68
  [key: string]: unknown;
56
69
  }
57
70
  interface PurchaseEventData {
@@ -61,6 +74,13 @@ interface PurchaseEventData {
61
74
  identity_id?: string;
62
75
  /** Present on purchase.disputed, e.g. "lost". */
63
76
  dispute_status?: string;
77
+ /**
78
+ * Merchant of Record accounts only (on `purchase.refunded`, card refunds): the REFUND receipt INVO issued to the
79
+ * buyer. Absent on Open accounts, and while a refund is still pending.
80
+ */
81
+ receipt_number?: string;
82
+ /** Merchant of Record only: link to the printable refund receipt page. */
83
+ receipt_url?: string;
64
84
  [key: string]: unknown;
65
85
  }
66
86
  interface ItemPurchasedData {
@@ -101,6 +121,13 @@ interface PlatformCommercePurchasedData {
101
121
  /** Card leg only (the USD charged). */
102
122
  total_price_usd?: string;
103
123
  fee_breakdown?: Record<string, unknown>;
124
+ /**
125
+ * Merchant of Record accounts only (card sales): the receipt INVO issued to the buyer.
126
+ * Absent on Open accounts and storefront rails.
127
+ */
128
+ receipt_number?: string;
129
+ /** Merchant of Record only: link to the printable receipt page. Anyone with it can read it. */
130
+ receipt_url?: string;
104
131
  [key: string]: unknown;
105
132
  }
106
133
  /** `platform_commerce.refunded` — a Platform Commerce purchase was refunded. INVO keeps
@@ -117,6 +144,13 @@ interface PlatformCommerceRefundedData {
117
144
  /** `"usd"` (card) or the literal `"currency"` (balance). */
118
145
  amount_unit: string;
119
146
  fee_retained: boolean;
147
+ /**
148
+ * Merchant of Record accounts only (card refunds): the REFUND receipt INVO issued to the
149
+ * buyer. Absent on Open accounts, and while a refund is still pending.
150
+ */
151
+ receipt_number?: string;
152
+ /** Merchant of Record only: link to the printable refund receipt page. */
153
+ receipt_url?: string;
120
154
  [key: string]: unknown;
121
155
  }
122
156
  interface TransferEventData {
@@ -160,6 +194,18 @@ interface SubscriptionEventCommon {
160
194
  metadata: Record<string, unknown> | null;
161
195
  [key: string]: unknown;
162
196
  }
197
+ /**
198
+ * The two keys an event about period 1 of a PAID trial carries (`subscription.payment_failed`,
199
+ * `past_due`, `authentication_required` and `expired`). The shared `amount_usd` is the regular
200
+ * price; `amount_due_usd` and `trial_amount_usd` are the trial price. Absent on every other
201
+ * event of these types, so test for presence.
202
+ */
203
+ interface SubscriptionTrialEventFields {
204
+ /** `true` when present. */
205
+ is_trial?: boolean;
206
+ /** The paid-trial price, decimal string. */
207
+ trial_amount_usd?: string;
208
+ }
163
209
  /**
164
210
  * How a renewal was funded.
165
211
  *
@@ -221,6 +267,12 @@ interface SubscriptionRenewedData {
221
267
  subscription_id: string;
222
268
  item_id: string;
223
269
  period_seq: number;
270
+ /**
271
+ * `true` only on the event for period 1 of a PAID trial, whose `amount_usd` is then the trial
272
+ * price; `false` on every other renewal. INVO sends it on every event from 2026-09-23 on;
273
+ * optional here only because an event from an older backend does not carry it.
274
+ */
275
+ is_trial?: boolean;
224
276
  transaction_id: string;
225
277
  order_id: string;
226
278
  mint_order_id: string | null;
@@ -239,6 +291,13 @@ interface SubscriptionRenewedData {
239
291
  split: SubscriptionRenewalSplit;
240
292
  revenue_share_attribution: SubscriptionRevenueShareAttribution | null;
241
293
  metadata: Record<string, unknown> | null;
294
+ /**
295
+ * Merchant of Record accounts only (card sales): the receipt INVO issued to the buyer.
296
+ * Absent on Open accounts and storefront rails.
297
+ */
298
+ receipt_number?: string;
299
+ /** Merchant of Record only: link to the printable receipt page. Anyone with it can read it. */
300
+ receipt_url?: string;
242
301
  [key: string]: unknown;
243
302
  }
244
303
  /**
@@ -246,7 +305,7 @@ interface SubscriptionRenewedData {
246
305
  * access. Does not revoke anything. On the final failure `retry_at` and `grace_period_end`
247
306
  * are `null`, `retries_remaining` is `0`, and `subscription.expired` follows.
248
307
  */
249
- interface SubscriptionPaymentFailedData extends SubscriptionEventCommon {
308
+ interface SubscriptionPaymentFailedData extends SubscriptionEventCommon, SubscriptionTrialEventFields {
250
309
  attempt_no: number;
251
310
  period_start: string;
252
311
  period_end: string;
@@ -271,7 +330,7 @@ interface SubscriptionPaymentFailedData extends SubscriptionEventCommon {
271
330
  access_retained: boolean;
272
331
  }
273
332
  /** `subscription.past_due`: fires ONCE when the subscription enters `past_due`, not on every retry. */
274
- interface SubscriptionPastDueData extends SubscriptionEventCommon {
333
+ interface SubscriptionPastDueData extends SubscriptionEventCommon, SubscriptionTrialEventFields {
275
334
  amount_due_usd: string;
276
335
  grace_period_end: string | null;
277
336
  retry_at: string | null;
@@ -285,7 +344,7 @@ interface SubscriptionPastDueData extends SubscriptionEventCommon {
285
344
  * 2026-09-17 the full period price, the same figure as `amount_due_usd` (a challenge opened
286
345
  * before that date can still show the older wallet-shortfall figure).
287
346
  */
288
- interface SubscriptionAuthenticationRequiredData extends SubscriptionEventCommon {
347
+ interface SubscriptionAuthenticationRequiredData extends SubscriptionEventCommon, SubscriptionTrialEventFields {
289
348
  attempt_no: number;
290
349
  period_start: string;
291
350
  period_end: string;
@@ -321,9 +380,12 @@ interface SubscriptionCanceledData extends SubscriptionEventCommon {
321
380
  * (the last instant the member paid for; `null` if nothing was ever collected), not at
322
381
  * `ended_at`. A never-authorised Steam row carries `failure_code: "steam_authorization_abandoned"`.
323
382
  * `failure_code: "steam_containment"` is no longer sent (spending is not restricted by which
324
- * rail bought the currency).
383
+ * rail bought the currency). A refused PAID-trial charge ends the subscription at once with
384
+ * `expire_cause: "trial_payment_failed"`, `is_trial: true`, `period_seq: 1` and
385
+ * `final_period_end: null` (it follows a `subscription.payment_failed` with
386
+ * `retries_remaining: 0`).
325
387
  */
326
- interface SubscriptionExpiredData extends SubscriptionEventCommon {
388
+ interface SubscriptionExpiredData extends SubscriptionEventCommon, SubscriptionTrialEventFields {
327
389
  failed_period_start: string | null;
328
390
  failed_period_end: string | null;
329
391
  final_attempt_no: number | null;
@@ -333,6 +395,11 @@ interface SubscriptionExpiredData extends SubscriptionEventCommon {
333
395
  ended_at: string;
334
396
  final_period_end: string | null;
335
397
  access_retained: boolean;
398
+ /**
399
+ * Present only when the expiry was not the ordinary end of dunning: `"trial_payment_failed"`
400
+ * when a paid trial's own charge was refused. Absent on an ordinary expiry.
401
+ */
402
+ expire_cause?: string;
336
403
  }
337
404
  /** The `refund` block on `subscription.refunded`. */
338
405
  interface SubscriptionRefundDetail {
@@ -390,6 +457,13 @@ interface SubscriptionRefundedData {
390
457
  refund_request_id?: string | null;
391
458
  /** Additive (2026-09-17). `true` when this refund cancelled the subscription. */
392
459
  subscription_canceled?: boolean;
460
+ /**
461
+ * Merchant of Record accounts only (card refunds): the REFUND receipt INVO issued to the
462
+ * buyer. Absent on Open accounts, and while a refund is still pending.
463
+ */
464
+ receipt_number?: string;
465
+ /** Merchant of Record only: link to the printable refund receipt page. */
466
+ receipt_url?: string;
393
467
  [key: string]: unknown;
394
468
  }
395
469
  /**
@@ -564,7 +638,7 @@ declare function createWebhookHandler(opts: WebhookHandlerOptions): (request: Re
564
638
  /**
565
639
  * Platform Commerce — the ECOMMERCE surface (server side). A PLATFORM tenant (a non-game
566
640
  * app: vertical video, creator merch, marketplace) sells items funded by INVO balance OR a
567
- * real card, with INVO as merchant of record and full refunds. This is NOT item purchase
641
+ * real card, with full refunds (the seller of record depends on the account tier). This is NOT item purchase
568
642
  * (§4.8) — that is a GAME tenant spending a player's existing game currency on an in-game
569
643
  * item (balance only, no card, no refund). Different endpoints, different fee, different
570
644
  * settlement. Reached as `invo.platformCommerce.*`.
@@ -648,6 +722,15 @@ declare class SubscriptionsServer {
648
722
  * `failureCode: "no_payment_method"`, whatever the member's balance: save a card first.
649
723
  * `walletOnly: true` is deprecated: it never charges a card, so such a subscription can never
650
724
  * be paid (`failureCode: "wallet_only"`).
725
+ *
726
+ * PAID TRIAL: send `trialAmountUsd` with `trialDays` or `trialEnd` (for example $1.00 for 7
727
+ * days, then `amountUsd` monthly). Period 1 is charged the trial price inside this call, so a
728
+ * usable saved card is required (`400 PAYMENT_METHOD_REQUIRED`, `err.isPaymentMethodRequired`),
729
+ * `firstCharge` reports the trial charge (never `skipped_trial`), and a refused trial charge
730
+ * ends the subscription at once (`expired`, no retry). Other refusals:
731
+ * `err.isTrialAmountRequiresTrial`, `err.isTrialAmountNotSupportedForFunding`,
732
+ * `err.isTrialAmountInvalid` (below $0.50, or not less than `amountUsd`),
733
+ * `err.isConsentDisclosedTrialInvalid`.
651
734
  * Requires the game to be `live` (`err.isGameNotLive`).
652
735
  */
653
736
  create(input: CreateSubscriptionInput, opts?: CallOptions): Promise<SubscriptionResult>;
@@ -1014,9 +1097,43 @@ declare class InvoServer {
1014
1097
  * (run client-side 3-D Secure with clientSecret, then call confirmPayment).
1015
1098
  * - rail "game": returns status "pending_payment" + paymentUrl (redirect the browser).
1016
1099
  * - rail "steam": NOT a browser flow — the backend returns WRONG_RAIL_ENDPOINT.
1100
+ *
1101
+ * INVO's card fee (3.5% + $0.30 on Open, 5% + $0.30 on Merchant of Record, never less than the card cost). Two shapes, chosen by
1102
+ * what you send:
1103
+ * - with `acknowledgedTotalUsd` (the `totalUsd` from {@link quoteCurrencyPurchase}): the
1104
+ * card is charged that total and the coins are priced off `usdAmount`. A total that no
1105
+ * longer matches throws `409 QUOTE_STALE` (`err.isQuoteStale`); nothing was charged.
1106
+ * - without it: the card is charged exactly `usdAmount`, never more, and the fee comes out
1107
+ * of the coins. An amount too small to carry the fee throws `400 AMOUNT_BELOW_FEE`
1108
+ * (`err.isAmountBelowFee`); nothing was charged.
1109
+ *
1110
+ * A `success` result reports `processingFeeUsd`, `feeTakenFrom`, `coinsCredited` and
1111
+ * `chargeTotalUsd`.
1017
1112
  */
1018
1113
  purchaseCurrency(input: PurchaseInput, opts?: CallOptions): Promise<PurchaseResult>;
1019
- /** Complete the card-rail 3-D Secure step after the client finished card action. */
1114
+ /**
1115
+ * What a card purchase of coins will cost, BEFORE charging for it. Moves no money and
1116
+ * creates nothing, so it is safe to call on every price render (`POST
1117
+ * /api/currency-purchases/quote`, authenticated by your game secret like the purchase).
1118
+ *
1119
+ * INVO's card fee on a coin purchase is 3.5% + $0.30 of the price on the Open tier (5% + $0.30 on Merchant of Record), never less than the
1120
+ * card cost. `totalUsd` is the price plus that fee (plus any tax, when you pass `country`):
1121
+ * $10.00 quotes a $10.65 total. Show the player `totalUsd`, then send the same figure back
1122
+ * as `acknowledgedTotalUsd` on {@link purchaseCurrency}; the card is charged exactly that
1123
+ * and the player gets the coins for the full price. `ifUnacknowledged` shows the other
1124
+ * outcome: the card charged exactly `usdAmount` and the fee taken out of the coins ($10.00
1125
+ * gives 93.70 coins at the default 10 per USD), or `null` when the amount cannot carry the
1126
+ * fee.
1127
+ *
1128
+ * Refusals: `400 INVALID_INPUT` (amount missing, not above zero, or above INVO's card
1129
+ * maximum), `400 CURRENCY_NOT_CONFIGURED`, `503 RATE_UNAVAILABLE`.
1130
+ */
1131
+ quoteCurrencyPurchase(input: CurrencyPurchaseQuoteInput, opts?: CallOptions): Promise<CurrencyPurchaseQuote>;
1132
+ /**
1133
+ * Complete the card-rail 3-D Secure step after the client finished card action.
1134
+ * `status: "success"` means the payment succeeded; tell the buyer the purchase is complete
1135
+ * only when `credited` is `true` (see {@link ConfirmPaymentResult.credited}).
1136
+ */
1020
1137
  confirmPayment(input: {
1021
1138
  paymentIntentId: string;
1022
1139
  orderId?: string;
@@ -1331,4 +1448,4 @@ declare class InvoServer {
1331
1448
  private toInitiateResult;
1332
1449
  }
1333
1450
 
1334
- 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 };
1451
+ 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, CurrencyPurchaseQuote, CurrencyPurchaseQuoteInput, 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, type SubscriptionTrialEventFields, SubscriptionsServer, TransactionStatusResult, type TransferEventData, type VerifyWebhookOptions, type WebhookHandlerOptions, createWebhookHandler, verifyWebhook, verifyWebhookAsync };
package/dist/server.d.ts CHANGED
@@ -1,12 +1,12 @@
1
- import { I as InvoError, H as Http, x as AuthHeader, y as CardSetupSessionInput, g as CallOptions, z as CardSetupSessionResult, F as CardSetupInput, G as CardSetupResult, J as CardSetupConfirmInput, K as CardSetupConfirmResult, N as PlayerCardsResult, O as PlatformPurchaseInput, Q as PlatformPurchaseResult, S as PlatformOrderStatusResult, T as PlatformRefundInput, U as PlatformRefundResult, X as CreateSubscriptionInput, Y as SubscriptionResult, Z as GetSubscriptionOptions, _ as GetSubscriptionResult, $ as ListSubscriptionsOptions, a0 as SubscriptionListResult, a1 as CancelSubscriptionOptions, a2 as CancelResult, a3 as ChangeAmountResult, a4 as SetPaymentMethodInput, a5 as SetPaymentMethodResult, a6 as RefundSubscriptionInput, a7 as RefundResult, a8 as SteamSubscriptionInitInput, a9 as SteamInitResult, aa as SteamFinalizeSubscriptionResult, ab as SandboxClockResult, ac as SandboxFailureOutcome, ad as SandboxForceFailureOptions, ae as SandboxForceAuthChallengeOptions, af as ServerConfig, ag as PlayerToken, ah as InitiateSendInput, ai as InitiateResult, aj as InitiateTransferInput, ak as CreateCheckoutInput, al as CreateCheckoutResult, am as PurchaseInput, an as PurchaseResult, ao as ConfirmPaymentResult, ap as OrderDetailsResult, aq as SteamPacksQuery, ar as SteamPacksResult, as as SteamInitPurchaseInput, at as SteamInitPurchaseResult, au as SteamFinalizeInput, av as SteamFinalizeResult, aw as PurchaseItemInput, ax as PurchaseItemResult, ay as ItemHistoryQuery, az as ItemHistoryResult, aA as ItemOrderQuery, aB as PlayerBalanceQuery, aC as PlayerBalanceResult, aD as InboundPendingQuery, aE as InboundPendingResult, aF as LinkedIdentitiesQuery, aG as LinkedIdentitiesResult, aH as SmsVerifyResult, aI as ClaimTransferInput, aJ as ClaimResult, aK as ClaimCurrencyInput, aL as TransactionStatusResult, aM as GuardianApprovalStatusResult, aN as ServerDestinationsQuery, k as DestinationsResult, aO as PhoneShareContact, aP as PhoneShareInitiateResult, aQ as PhoneShareApproveInput, aR as PhoneShareApproveResult, aS as PhoneShareStatusResult, aT as BeginDeviceApprovalInput, aU as DeviceApprovalGrant, aV as PollDeviceApprovalInput, aW as DeviceApprovalPollResult, aX as ConfirmDeviceEnrollmentInput, aY as ConfirmDeviceEnrollmentResult, aZ as ApproveWithDeviceCodeInput, a_ as DeviceApprovalSettleResult, a$ as CompleteDeviceApprovalInput, b0 as CompleteDeviceApprovalResult } from './types-CT0Ksonp.js';
2
- export { b1 as CardSetupStatus, b2 as CurrencyBalance, p as DestinationGame, b3 as DeviceApprovalChannel, b4 as DeviceApprovalEnrollment, b5 as DeviceApprovalFlow, b6 as DeviceApprovalPollStatus, b7 as DeviceEnrollmentDecision, b8 as DeviceEnrollmentRespond, b9 as FirstCharge, ba as FirstChargeStatus, bb as FundingSource, bc as InboundPendingItem, q as InvoErrorInfo, r as InvoHooks, s as InvoRequestInfo, t as InvoResponseInfo, bd as LinkedIdentityEmail, be as PlatformPurchaseStatus, w as Rail, bf as RefundInitiation, bg as RefundPendingApproval, bh as RefundProcessingFeeBasis, bi as RefundReceipt, bj as RefundRevenueShareAttribution, bk as RefundWarning, bl as SandboxClockState, bm as SavedCard, bn as SteamPack, bo as SteamUserSession, bp as Subscription, bq as SubscriptionBaseInput, br as SubscriptionConsent, bs as SubscriptionConsentInput, bt as SubscriptionFundingRail, bu as SubscriptionInterval, bv as SubscriptionRevenueShare, bw as SubscriptionRevenueShareInput, bx as SubscriptionStatus, V as VerificationMethod, by as isRefundPendingApproval } from './types-CT0Ksonp.js';
1
+ import { I as InvoError, H as Http, x as AuthHeader, y as CardSetupSessionInput, g as CallOptions, z as CardSetupSessionResult, F as CardSetupInput, G as CardSetupResult, J as CardSetupConfirmInput, K as CardSetupConfirmResult, N as PlayerCardsResult, O as PlatformPurchaseInput, Q as PlatformPurchaseResult, S as PlatformOrderStatusResult, T as PlatformRefundInput, U as PlatformRefundResult, X as CreateSubscriptionInput, Y as SubscriptionResult, Z as GetSubscriptionOptions, _ as GetSubscriptionResult, $ as ListSubscriptionsOptions, a0 as SubscriptionListResult, a1 as CancelSubscriptionOptions, a2 as CancelResult, a3 as ChangeAmountResult, a4 as SetPaymentMethodInput, a5 as SetPaymentMethodResult, a6 as RefundSubscriptionInput, a7 as RefundResult, a8 as SteamSubscriptionInitInput, a9 as SteamInitResult, aa as SteamFinalizeSubscriptionResult, ab as SandboxClockResult, ac as SandboxFailureOutcome, ad as SandboxForceFailureOptions, ae as SandboxForceAuthChallengeOptions, af as ServerConfig, ag as PlayerToken, ah as InitiateSendInput, ai as InitiateResult, aj as InitiateTransferInput, ak as CreateCheckoutInput, al as CreateCheckoutResult, am as PurchaseInput, an as PurchaseResult, ao as CurrencyPurchaseQuoteInput, ap as CurrencyPurchaseQuote, aq as ConfirmPaymentResult, ar as OrderDetailsResult, as as SteamPacksQuery, at as SteamPacksResult, au as SteamInitPurchaseInput, av as SteamInitPurchaseResult, aw as SteamFinalizeInput, ax as SteamFinalizeResult, ay as PurchaseItemInput, az as PurchaseItemResult, aA as ItemHistoryQuery, aB as ItemHistoryResult, aC as ItemOrderQuery, aD as PlayerBalanceQuery, aE as PlayerBalanceResult, aF as InboundPendingQuery, aG as InboundPendingResult, aH as LinkedIdentitiesQuery, aI as LinkedIdentitiesResult, aJ as SmsVerifyResult, aK as ClaimTransferInput, aL as ClaimResult, aM as ClaimCurrencyInput, aN as TransactionStatusResult, aO as GuardianApprovalStatusResult, aP as ServerDestinationsQuery, k as DestinationsResult, aQ as PhoneShareContact, aR as PhoneShareInitiateResult, aS as PhoneShareApproveInput, aT as PhoneShareApproveResult, aU as PhoneShareStatusResult, aV as BeginDeviceApprovalInput, aW as DeviceApprovalGrant, aX as PollDeviceApprovalInput, aY as DeviceApprovalPollResult, aZ as ConfirmDeviceEnrollmentInput, a_ as ConfirmDeviceEnrollmentResult, a$ as ApproveWithDeviceCodeInput, b0 as DeviceApprovalSettleResult, b1 as CompleteDeviceApprovalInput, b2 as CompleteDeviceApprovalResult } from './types-CD83iV3D.js';
2
+ export { b3 as CardSetupStatus, b4 as CurrencyBalance, b5 as CurrencyPurchaseQuoteBreakdown, p as DestinationGame, b6 as DeviceApprovalChannel, b7 as DeviceApprovalEnrollment, b8 as DeviceApprovalFlow, b9 as DeviceApprovalPollStatus, ba as DeviceEnrollmentDecision, bb as DeviceEnrollmentRespond, bc as FeeTakenFrom, bd as FirstCharge, be as FirstChargeStatus, bf as FundingSource, bg as InboundPendingItem, q as InvoErrorInfo, r as InvoHooks, s as InvoRequestInfo, t as InvoResponseInfo, bh as LinkedIdentityEmail, bi as PlatformPurchaseStatus, w as Rail, bj as RefundInitiation, bk as RefundPendingApproval, bl as RefundProcessingFeeBasis, bm as RefundReceipt, bn as RefundRevenueShareAttribution, bo as RefundWarning, bp as SandboxClockState, bq as SavedCard, br as SteamPack, bs as SteamUserSession, bt as Subscription, bu as SubscriptionBaseInput, bv as SubscriptionConsent, bw as SubscriptionConsentInput, bx as SubscriptionFundingRail, by as SubscriptionInterval, bz as SubscriptionRevenueShare, bA as SubscriptionRevenueShareInput, bB as SubscriptionStatus, bC as UnacknowledgedPurchaseOutcome, V as VerificationMethod, bD as isRefundPendingApproval } from './types-CD83iV3D.js';
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.12.1";
9
+ declare const SDK_VERSION = "3.14.0";
10
10
 
11
11
  interface VerifyWebhookOptions {
12
12
  /** Max age of the signed timestamp, in seconds. Default 300 (5 min). */
@@ -52,6 +52,19 @@ interface PurchaseCompletedData {
52
52
  * its `mint_order_id` equals this event's `order_id`.
53
53
  */
54
54
  metadata?: Record<string, unknown>;
55
+ /**
56
+ * Why the tax is what it is. `"partner_responsible"` on an Open-tier account (you are the
57
+ * seller; INVO charged no tax); on Merchant of Record, how INVO handled it (for example
58
+ * `"collected"`). Treat an unknown value as informational.
59
+ */
60
+ tax_treatment?: string | null;
61
+ /**
62
+ * Merchant of Record accounts only (card sales): the receipt INVO issued to the buyer.
63
+ * Absent on Open accounts and storefront rails.
64
+ */
65
+ receipt_number?: string;
66
+ /** Merchant of Record only: link to the printable receipt page. Anyone with it can read it. */
67
+ receipt_url?: string;
55
68
  [key: string]: unknown;
56
69
  }
57
70
  interface PurchaseEventData {
@@ -61,6 +74,13 @@ interface PurchaseEventData {
61
74
  identity_id?: string;
62
75
  /** Present on purchase.disputed, e.g. "lost". */
63
76
  dispute_status?: string;
77
+ /**
78
+ * Merchant of Record accounts only (on `purchase.refunded`, card refunds): the REFUND receipt INVO issued to the
79
+ * buyer. Absent on Open accounts, and while a refund is still pending.
80
+ */
81
+ receipt_number?: string;
82
+ /** Merchant of Record only: link to the printable refund receipt page. */
83
+ receipt_url?: string;
64
84
  [key: string]: unknown;
65
85
  }
66
86
  interface ItemPurchasedData {
@@ -101,6 +121,13 @@ interface PlatformCommercePurchasedData {
101
121
  /** Card leg only (the USD charged). */
102
122
  total_price_usd?: string;
103
123
  fee_breakdown?: Record<string, unknown>;
124
+ /**
125
+ * Merchant of Record accounts only (card sales): the receipt INVO issued to the buyer.
126
+ * Absent on Open accounts and storefront rails.
127
+ */
128
+ receipt_number?: string;
129
+ /** Merchant of Record only: link to the printable receipt page. Anyone with it can read it. */
130
+ receipt_url?: string;
104
131
  [key: string]: unknown;
105
132
  }
106
133
  /** `platform_commerce.refunded` — a Platform Commerce purchase was refunded. INVO keeps
@@ -117,6 +144,13 @@ interface PlatformCommerceRefundedData {
117
144
  /** `"usd"` (card) or the literal `"currency"` (balance). */
118
145
  amount_unit: string;
119
146
  fee_retained: boolean;
147
+ /**
148
+ * Merchant of Record accounts only (card refunds): the REFUND receipt INVO issued to the
149
+ * buyer. Absent on Open accounts, and while a refund is still pending.
150
+ */
151
+ receipt_number?: string;
152
+ /** Merchant of Record only: link to the printable refund receipt page. */
153
+ receipt_url?: string;
120
154
  [key: string]: unknown;
121
155
  }
122
156
  interface TransferEventData {
@@ -160,6 +194,18 @@ interface SubscriptionEventCommon {
160
194
  metadata: Record<string, unknown> | null;
161
195
  [key: string]: unknown;
162
196
  }
197
+ /**
198
+ * The two keys an event about period 1 of a PAID trial carries (`subscription.payment_failed`,
199
+ * `past_due`, `authentication_required` and `expired`). The shared `amount_usd` is the regular
200
+ * price; `amount_due_usd` and `trial_amount_usd` are the trial price. Absent on every other
201
+ * event of these types, so test for presence.
202
+ */
203
+ interface SubscriptionTrialEventFields {
204
+ /** `true` when present. */
205
+ is_trial?: boolean;
206
+ /** The paid-trial price, decimal string. */
207
+ trial_amount_usd?: string;
208
+ }
163
209
  /**
164
210
  * How a renewal was funded.
165
211
  *
@@ -221,6 +267,12 @@ interface SubscriptionRenewedData {
221
267
  subscription_id: string;
222
268
  item_id: string;
223
269
  period_seq: number;
270
+ /**
271
+ * `true` only on the event for period 1 of a PAID trial, whose `amount_usd` is then the trial
272
+ * price; `false` on every other renewal. INVO sends it on every event from 2026-09-23 on;
273
+ * optional here only because an event from an older backend does not carry it.
274
+ */
275
+ is_trial?: boolean;
224
276
  transaction_id: string;
225
277
  order_id: string;
226
278
  mint_order_id: string | null;
@@ -239,6 +291,13 @@ interface SubscriptionRenewedData {
239
291
  split: SubscriptionRenewalSplit;
240
292
  revenue_share_attribution: SubscriptionRevenueShareAttribution | null;
241
293
  metadata: Record<string, unknown> | null;
294
+ /**
295
+ * Merchant of Record accounts only (card sales): the receipt INVO issued to the buyer.
296
+ * Absent on Open accounts and storefront rails.
297
+ */
298
+ receipt_number?: string;
299
+ /** Merchant of Record only: link to the printable receipt page. Anyone with it can read it. */
300
+ receipt_url?: string;
242
301
  [key: string]: unknown;
243
302
  }
244
303
  /**
@@ -246,7 +305,7 @@ interface SubscriptionRenewedData {
246
305
  * access. Does not revoke anything. On the final failure `retry_at` and `grace_period_end`
247
306
  * are `null`, `retries_remaining` is `0`, and `subscription.expired` follows.
248
307
  */
249
- interface SubscriptionPaymentFailedData extends SubscriptionEventCommon {
308
+ interface SubscriptionPaymentFailedData extends SubscriptionEventCommon, SubscriptionTrialEventFields {
250
309
  attempt_no: number;
251
310
  period_start: string;
252
311
  period_end: string;
@@ -271,7 +330,7 @@ interface SubscriptionPaymentFailedData extends SubscriptionEventCommon {
271
330
  access_retained: boolean;
272
331
  }
273
332
  /** `subscription.past_due`: fires ONCE when the subscription enters `past_due`, not on every retry. */
274
- interface SubscriptionPastDueData extends SubscriptionEventCommon {
333
+ interface SubscriptionPastDueData extends SubscriptionEventCommon, SubscriptionTrialEventFields {
275
334
  amount_due_usd: string;
276
335
  grace_period_end: string | null;
277
336
  retry_at: string | null;
@@ -285,7 +344,7 @@ interface SubscriptionPastDueData extends SubscriptionEventCommon {
285
344
  * 2026-09-17 the full period price, the same figure as `amount_due_usd` (a challenge opened
286
345
  * before that date can still show the older wallet-shortfall figure).
287
346
  */
288
- interface SubscriptionAuthenticationRequiredData extends SubscriptionEventCommon {
347
+ interface SubscriptionAuthenticationRequiredData extends SubscriptionEventCommon, SubscriptionTrialEventFields {
289
348
  attempt_no: number;
290
349
  period_start: string;
291
350
  period_end: string;
@@ -321,9 +380,12 @@ interface SubscriptionCanceledData extends SubscriptionEventCommon {
321
380
  * (the last instant the member paid for; `null` if nothing was ever collected), not at
322
381
  * `ended_at`. A never-authorised Steam row carries `failure_code: "steam_authorization_abandoned"`.
323
382
  * `failure_code: "steam_containment"` is no longer sent (spending is not restricted by which
324
- * rail bought the currency).
383
+ * rail bought the currency). A refused PAID-trial charge ends the subscription at once with
384
+ * `expire_cause: "trial_payment_failed"`, `is_trial: true`, `period_seq: 1` and
385
+ * `final_period_end: null` (it follows a `subscription.payment_failed` with
386
+ * `retries_remaining: 0`).
325
387
  */
326
- interface SubscriptionExpiredData extends SubscriptionEventCommon {
388
+ interface SubscriptionExpiredData extends SubscriptionEventCommon, SubscriptionTrialEventFields {
327
389
  failed_period_start: string | null;
328
390
  failed_period_end: string | null;
329
391
  final_attempt_no: number | null;
@@ -333,6 +395,11 @@ interface SubscriptionExpiredData extends SubscriptionEventCommon {
333
395
  ended_at: string;
334
396
  final_period_end: string | null;
335
397
  access_retained: boolean;
398
+ /**
399
+ * Present only when the expiry was not the ordinary end of dunning: `"trial_payment_failed"`
400
+ * when a paid trial's own charge was refused. Absent on an ordinary expiry.
401
+ */
402
+ expire_cause?: string;
336
403
  }
337
404
  /** The `refund` block on `subscription.refunded`. */
338
405
  interface SubscriptionRefundDetail {
@@ -390,6 +457,13 @@ interface SubscriptionRefundedData {
390
457
  refund_request_id?: string | null;
391
458
  /** Additive (2026-09-17). `true` when this refund cancelled the subscription. */
392
459
  subscription_canceled?: boolean;
460
+ /**
461
+ * Merchant of Record accounts only (card refunds): the REFUND receipt INVO issued to the
462
+ * buyer. Absent on Open accounts, and while a refund is still pending.
463
+ */
464
+ receipt_number?: string;
465
+ /** Merchant of Record only: link to the printable refund receipt page. */
466
+ receipt_url?: string;
393
467
  [key: string]: unknown;
394
468
  }
395
469
  /**
@@ -564,7 +638,7 @@ declare function createWebhookHandler(opts: WebhookHandlerOptions): (request: Re
564
638
  /**
565
639
  * Platform Commerce — the ECOMMERCE surface (server side). A PLATFORM tenant (a non-game
566
640
  * app: vertical video, creator merch, marketplace) sells items funded by INVO balance OR a
567
- * real card, with INVO as merchant of record and full refunds. This is NOT item purchase
641
+ * real card, with full refunds (the seller of record depends on the account tier). This is NOT item purchase
568
642
  * (§4.8) — that is a GAME tenant spending a player's existing game currency on an in-game
569
643
  * item (balance only, no card, no refund). Different endpoints, different fee, different
570
644
  * settlement. Reached as `invo.platformCommerce.*`.
@@ -648,6 +722,15 @@ declare class SubscriptionsServer {
648
722
  * `failureCode: "no_payment_method"`, whatever the member's balance: save a card first.
649
723
  * `walletOnly: true` is deprecated: it never charges a card, so such a subscription can never
650
724
  * be paid (`failureCode: "wallet_only"`).
725
+ *
726
+ * PAID TRIAL: send `trialAmountUsd` with `trialDays` or `trialEnd` (for example $1.00 for 7
727
+ * days, then `amountUsd` monthly). Period 1 is charged the trial price inside this call, so a
728
+ * usable saved card is required (`400 PAYMENT_METHOD_REQUIRED`, `err.isPaymentMethodRequired`),
729
+ * `firstCharge` reports the trial charge (never `skipped_trial`), and a refused trial charge
730
+ * ends the subscription at once (`expired`, no retry). Other refusals:
731
+ * `err.isTrialAmountRequiresTrial`, `err.isTrialAmountNotSupportedForFunding`,
732
+ * `err.isTrialAmountInvalid` (below $0.50, or not less than `amountUsd`),
733
+ * `err.isConsentDisclosedTrialInvalid`.
651
734
  * Requires the game to be `live` (`err.isGameNotLive`).
652
735
  */
653
736
  create(input: CreateSubscriptionInput, opts?: CallOptions): Promise<SubscriptionResult>;
@@ -1014,9 +1097,43 @@ declare class InvoServer {
1014
1097
  * (run client-side 3-D Secure with clientSecret, then call confirmPayment).
1015
1098
  * - rail "game": returns status "pending_payment" + paymentUrl (redirect the browser).
1016
1099
  * - rail "steam": NOT a browser flow — the backend returns WRONG_RAIL_ENDPOINT.
1100
+ *
1101
+ * INVO's card fee (3.5% + $0.30 on Open, 5% + $0.30 on Merchant of Record, never less than the card cost). Two shapes, chosen by
1102
+ * what you send:
1103
+ * - with `acknowledgedTotalUsd` (the `totalUsd` from {@link quoteCurrencyPurchase}): the
1104
+ * card is charged that total and the coins are priced off `usdAmount`. A total that no
1105
+ * longer matches throws `409 QUOTE_STALE` (`err.isQuoteStale`); nothing was charged.
1106
+ * - without it: the card is charged exactly `usdAmount`, never more, and the fee comes out
1107
+ * of the coins. An amount too small to carry the fee throws `400 AMOUNT_BELOW_FEE`
1108
+ * (`err.isAmountBelowFee`); nothing was charged.
1109
+ *
1110
+ * A `success` result reports `processingFeeUsd`, `feeTakenFrom`, `coinsCredited` and
1111
+ * `chargeTotalUsd`.
1017
1112
  */
1018
1113
  purchaseCurrency(input: PurchaseInput, opts?: CallOptions): Promise<PurchaseResult>;
1019
- /** Complete the card-rail 3-D Secure step after the client finished card action. */
1114
+ /**
1115
+ * What a card purchase of coins will cost, BEFORE charging for it. Moves no money and
1116
+ * creates nothing, so it is safe to call on every price render (`POST
1117
+ * /api/currency-purchases/quote`, authenticated by your game secret like the purchase).
1118
+ *
1119
+ * INVO's card fee on a coin purchase is 3.5% + $0.30 of the price on the Open tier (5% + $0.30 on Merchant of Record), never less than the
1120
+ * card cost. `totalUsd` is the price plus that fee (plus any tax, when you pass `country`):
1121
+ * $10.00 quotes a $10.65 total. Show the player `totalUsd`, then send the same figure back
1122
+ * as `acknowledgedTotalUsd` on {@link purchaseCurrency}; the card is charged exactly that
1123
+ * and the player gets the coins for the full price. `ifUnacknowledged` shows the other
1124
+ * outcome: the card charged exactly `usdAmount` and the fee taken out of the coins ($10.00
1125
+ * gives 93.70 coins at the default 10 per USD), or `null` when the amount cannot carry the
1126
+ * fee.
1127
+ *
1128
+ * Refusals: `400 INVALID_INPUT` (amount missing, not above zero, or above INVO's card
1129
+ * maximum), `400 CURRENCY_NOT_CONFIGURED`, `503 RATE_UNAVAILABLE`.
1130
+ */
1131
+ quoteCurrencyPurchase(input: CurrencyPurchaseQuoteInput, opts?: CallOptions): Promise<CurrencyPurchaseQuote>;
1132
+ /**
1133
+ * Complete the card-rail 3-D Secure step after the client finished card action.
1134
+ * `status: "success"` means the payment succeeded; tell the buyer the purchase is complete
1135
+ * only when `credited` is `true` (see {@link ConfirmPaymentResult.credited}).
1136
+ */
1020
1137
  confirmPayment(input: {
1021
1138
  paymentIntentId: string;
1022
1139
  orderId?: string;
@@ -1331,4 +1448,4 @@ declare class InvoServer {
1331
1448
  private toInitiateResult;
1332
1449
  }
1333
1450
 
1334
- 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 };
1451
+ 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, CurrencyPurchaseQuote, CurrencyPurchaseQuoteInput, 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, type SubscriptionTrialEventFields, SubscriptionsServer, TransactionStatusResult, type TransferEventData, type VerifyWebhookOptions, type WebhookHandlerOptions, createWebhookHandler, verifyWebhook, verifyWebhookAsync };