@invonetwork/web-sdk 3.12.0 → 3.13.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, 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-DUo5NAzj.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-DUo5NAzj.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.0";
9
+ declare const SDK_VERSION = "3.13.0";
10
10
 
11
11
  interface VerifyWebhookOptions {
12
12
  /** Max age of the signed timestamp, in seconds. Default 300 (5 min). */
@@ -160,6 +160,18 @@ interface SubscriptionEventCommon {
160
160
  metadata: Record<string, unknown> | null;
161
161
  [key: string]: unknown;
162
162
  }
163
+ /**
164
+ * The two keys an event about period 1 of a PAID trial carries (`subscription.payment_failed`,
165
+ * `past_due`, `authentication_required` and `expired`). The shared `amount_usd` is the regular
166
+ * price; `amount_due_usd` and `trial_amount_usd` are the trial price. Absent on every other
167
+ * event of these types, so test for presence.
168
+ */
169
+ interface SubscriptionTrialEventFields {
170
+ /** `true` when present. */
171
+ is_trial?: boolean;
172
+ /** The paid-trial price, decimal string. */
173
+ trial_amount_usd?: string;
174
+ }
163
175
  /**
164
176
  * How a renewal was funded.
165
177
  *
@@ -221,6 +233,12 @@ interface SubscriptionRenewedData {
221
233
  subscription_id: string;
222
234
  item_id: string;
223
235
  period_seq: number;
236
+ /**
237
+ * `true` only on the event for period 1 of a PAID trial, whose `amount_usd` is then the trial
238
+ * price; `false` on every other renewal. INVO sends it on every event from 2026-09-23 on;
239
+ * optional here only because an event from an older backend does not carry it.
240
+ */
241
+ is_trial?: boolean;
224
242
  transaction_id: string;
225
243
  order_id: string;
226
244
  mint_order_id: string | null;
@@ -246,7 +264,7 @@ interface SubscriptionRenewedData {
246
264
  * access. Does not revoke anything. On the final failure `retry_at` and `grace_period_end`
247
265
  * are `null`, `retries_remaining` is `0`, and `subscription.expired` follows.
248
266
  */
249
- interface SubscriptionPaymentFailedData extends SubscriptionEventCommon {
267
+ interface SubscriptionPaymentFailedData extends SubscriptionEventCommon, SubscriptionTrialEventFields {
250
268
  attempt_no: number;
251
269
  period_start: string;
252
270
  period_end: string;
@@ -271,7 +289,7 @@ interface SubscriptionPaymentFailedData extends SubscriptionEventCommon {
271
289
  access_retained: boolean;
272
290
  }
273
291
  /** `subscription.past_due`: fires ONCE when the subscription enters `past_due`, not on every retry. */
274
- interface SubscriptionPastDueData extends SubscriptionEventCommon {
292
+ interface SubscriptionPastDueData extends SubscriptionEventCommon, SubscriptionTrialEventFields {
275
293
  amount_due_usd: string;
276
294
  grace_period_end: string | null;
277
295
  retry_at: string | null;
@@ -285,7 +303,7 @@ interface SubscriptionPastDueData extends SubscriptionEventCommon {
285
303
  * 2026-09-17 the full period price, the same figure as `amount_due_usd` (a challenge opened
286
304
  * before that date can still show the older wallet-shortfall figure).
287
305
  */
288
- interface SubscriptionAuthenticationRequiredData extends SubscriptionEventCommon {
306
+ interface SubscriptionAuthenticationRequiredData extends SubscriptionEventCommon, SubscriptionTrialEventFields {
289
307
  attempt_no: number;
290
308
  period_start: string;
291
309
  period_end: string;
@@ -321,9 +339,12 @@ interface SubscriptionCanceledData extends SubscriptionEventCommon {
321
339
  * (the last instant the member paid for; `null` if nothing was ever collected), not at
322
340
  * `ended_at`. A never-authorised Steam row carries `failure_code: "steam_authorization_abandoned"`.
323
341
  * `failure_code: "steam_containment"` is no longer sent (spending is not restricted by which
324
- * rail bought the currency).
342
+ * rail bought the currency). A refused PAID-trial charge ends the subscription at once with
343
+ * `expire_cause: "trial_payment_failed"`, `is_trial: true`, `period_seq: 1` and
344
+ * `final_period_end: null` (it follows a `subscription.payment_failed` with
345
+ * `retries_remaining: 0`).
325
346
  */
326
- interface SubscriptionExpiredData extends SubscriptionEventCommon {
347
+ interface SubscriptionExpiredData extends SubscriptionEventCommon, SubscriptionTrialEventFields {
327
348
  failed_period_start: string | null;
328
349
  failed_period_end: string | null;
329
350
  final_attempt_no: number | null;
@@ -333,6 +354,11 @@ interface SubscriptionExpiredData extends SubscriptionEventCommon {
333
354
  ended_at: string;
334
355
  final_period_end: string | null;
335
356
  access_retained: boolean;
357
+ /**
358
+ * Present only when the expiry was not the ordinary end of dunning: `"trial_payment_failed"`
359
+ * when a paid trial's own charge was refused. Absent on an ordinary expiry.
360
+ */
361
+ expire_cause?: string;
336
362
  }
337
363
  /** The `refund` block on `subscription.refunded`. */
338
364
  interface SubscriptionRefundDetail {
@@ -564,7 +590,7 @@ declare function createWebhookHandler(opts: WebhookHandlerOptions): (request: Re
564
590
  /**
565
591
  * Platform Commerce — the ECOMMERCE surface (server side). A PLATFORM tenant (a non-game
566
592
  * 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
593
+ * real card, with full refunds (the seller of record depends on the account tier). This is NOT item purchase
568
594
  * (§4.8) — that is a GAME tenant spending a player's existing game currency on an in-game
569
595
  * item (balance only, no card, no refund). Different endpoints, different fee, different
570
596
  * settlement. Reached as `invo.platformCommerce.*`.
@@ -648,6 +674,15 @@ declare class SubscriptionsServer {
648
674
  * `failureCode: "no_payment_method"`, whatever the member's balance: save a card first.
649
675
  * `walletOnly: true` is deprecated: it never charges a card, so such a subscription can never
650
676
  * be paid (`failureCode: "wallet_only"`).
677
+ *
678
+ * PAID TRIAL: send `trialAmountUsd` with `trialDays` or `trialEnd` (for example $1.00 for 7
679
+ * days, then `amountUsd` monthly). Period 1 is charged the trial price inside this call, so a
680
+ * usable saved card is required (`400 PAYMENT_METHOD_REQUIRED`, `err.isPaymentMethodRequired`),
681
+ * `firstCharge` reports the trial charge (never `skipped_trial`), and a refused trial charge
682
+ * ends the subscription at once (`expired`, no retry). Other refusals:
683
+ * `err.isTrialAmountRequiresTrial`, `err.isTrialAmountNotSupportedForFunding`,
684
+ * `err.isTrialAmountInvalid` (below $0.50, or not less than `amountUsd`),
685
+ * `err.isConsentDisclosedTrialInvalid`.
651
686
  * Requires the game to be `live` (`err.isGameNotLive`).
652
687
  */
653
688
  create(input: CreateSubscriptionInput, opts?: CallOptions): Promise<SubscriptionResult>;
@@ -700,8 +735,9 @@ declare class SubscriptionsServer {
700
735
  * the stored receipt with `idempotentReplay: true` and moves nothing.
701
736
  *
702
737
  * **Branch on `status`.** `"refunded"` (HTTP 200): the refund ran. `"pending_approval"`
703
- * (HTTP 202): the refund would exceed the game's daily self-serve limit ($500 per UTC day
704
- * by default), NOTHING moved, and INVO reviews it as a refund request (`requestId`); the
738
+ * (HTTP 202): the refund would exceed the game's daily self-serve limit per UTC day (by
739
+ * default never lower than the largest single subscription charge, so a single period
740
+ * always runs unless INVO set a lower limit for the game), NOTHING moved, and INVO reviews it as a refund request (`requestId`); the
705
741
  * outcome arrives as `subscription.refund_approved` (sent together with
706
742
  * `subscription.refunded`, and `subscription.canceled` on a full refund, in any order) or
707
743
  * `subscription.refund_rejected`. The 202 carries every receipt field with nothing moved
@@ -1013,8 +1049,38 @@ declare class InvoServer {
1013
1049
  * (run client-side 3-D Secure with clientSecret, then call confirmPayment).
1014
1050
  * - rail "game": returns status "pending_payment" + paymentUrl (redirect the browser).
1015
1051
  * - rail "steam": NOT a browser flow — the backend returns WRONG_RAIL_ENDPOINT.
1052
+ *
1053
+ * INVO's card fee (3.5% + $0.30, never less than the card cost). Two shapes, chosen by
1054
+ * what you send:
1055
+ * - with `acknowledgedTotalUsd` (the `totalUsd` from {@link quoteCurrencyPurchase}): the
1056
+ * card is charged that total and the coins are priced off `usdAmount`. A total that no
1057
+ * longer matches throws `409 QUOTE_STALE` (`err.isQuoteStale`); nothing was charged.
1058
+ * - without it: the card is charged exactly `usdAmount`, never more, and the fee comes out
1059
+ * of the coins. An amount too small to carry the fee throws `400 AMOUNT_BELOW_FEE`
1060
+ * (`err.isAmountBelowFee`); nothing was charged.
1061
+ *
1062
+ * A `success` result reports `processingFeeUsd`, `feeTakenFrom`, `coinsCredited` and
1063
+ * `chargeTotalUsd`.
1016
1064
  */
1017
1065
  purchaseCurrency(input: PurchaseInput, opts?: CallOptions): Promise<PurchaseResult>;
1066
+ /**
1067
+ * What a card purchase of coins will cost, BEFORE charging for it. Moves no money and
1068
+ * creates nothing, so it is safe to call on every price render (`POST
1069
+ * /api/currency-purchases/quote`, authenticated by your game secret like the purchase).
1070
+ *
1071
+ * INVO's card fee on a coin purchase is 3.5% + $0.30 of the price, never less than the
1072
+ * card cost. `totalUsd` is the price plus that fee (plus any tax, when you pass `country`):
1073
+ * $10.00 quotes a $10.65 total. Show the player `totalUsd`, then send the same figure back
1074
+ * as `acknowledgedTotalUsd` on {@link purchaseCurrency}; the card is charged exactly that
1075
+ * and the player gets the coins for the full price. `ifUnacknowledged` shows the other
1076
+ * outcome: the card charged exactly `usdAmount` and the fee taken out of the coins ($10.00
1077
+ * gives 93.70 coins at the default 10 per USD), or `null` when the amount cannot carry the
1078
+ * fee.
1079
+ *
1080
+ * Refusals: `400 INVALID_INPUT` (amount missing, not above zero, or above INVO's card
1081
+ * maximum), `400 CURRENCY_NOT_CONFIGURED`, `503 RATE_UNAVAILABLE`.
1082
+ */
1083
+ quoteCurrencyPurchase(input: CurrencyPurchaseQuoteInput, opts?: CallOptions): Promise<CurrencyPurchaseQuote>;
1018
1084
  /** Complete the card-rail 3-D Secure step after the client finished card action. */
1019
1085
  confirmPayment(input: {
1020
1086
  paymentIntentId: string;
@@ -1330,4 +1396,4 @@ declare class InvoServer {
1330
1396
  private toInitiateResult;
1331
1397
  }
1332
1398
 
1333
- 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 };
1399
+ 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.js CHANGED
@@ -1,9 +1,9 @@
1
- import { InvoError, assertSecureBaseUrl, Http, toDestinationsResult } from './chunk-5BMM5ZTW.js';
2
- export { InvoError } from './chunk-5BMM5ZTW.js';
1
+ import { InvoError, assertSecureBaseUrl, Http, toDestinationsResult } from './chunk-NJIZMM4H.js';
2
+ export { InvoError } from './chunk-NJIZMM4H.js';
3
3
  import { createHmac, timingSafeEqual } from 'crypto';
4
4
 
5
5
  // src/version.ts
6
- var SDK_VERSION = "3.12.0";
6
+ var SDK_VERSION = "3.13.0";
7
7
 
8
8
  // src/shared/types.ts
9
9
  function isRefundPendingApproval(r) {
@@ -177,6 +177,56 @@ async function hmacHexSubtle(secret, message) {
177
177
  var DEFAULT_UA = `invonetwork-web-sdk/${SDK_VERSION} (+https://invo.network)`;
178
178
  var MAX_USD_AMOUNT = 999999.99;
179
179
  var MAX_ITEM_PRICE = 999999.99;
180
+ var MAX_ACKNOWLEDGED_TOTAL_USD = 9999999999e-2;
181
+ function assertAcknowledgedTotal(value) {
182
+ parseMoney(value, MAX_ACKNOWLEDGED_TOTAL_USD, "acknowledgedTotalUsd");
183
+ }
184
+ function optionalDecimalString(v) {
185
+ return v == null ? void 0 : String(v);
186
+ }
187
+ function toQuoteBreakdown(row) {
188
+ const r = row && typeof row === "object" ? row : {};
189
+ const nullable = (v) => v == null ? null : String(v);
190
+ return {
191
+ subtotalUsd: String(r["subtotal_usd"] ?? ""),
192
+ taxUsd: String(r["tax_usd"] ?? "0.00"),
193
+ taxTreatment: nullable(r["tax_treatment"]),
194
+ taxNote: String(r["tax_note"] ?? ""),
195
+ taxRatePct: nullable(r["tax_rate_pct"]),
196
+ taxJurisdiction: nullable(r["tax_jurisdiction"]),
197
+ processingFeeUsd: String(r["processing_fee_usd"] ?? ""),
198
+ processingFeeNote: String(r["processing_fee_note"] ?? ""),
199
+ totalUsd: String(r["total_usd"] ?? ""),
200
+ coins: String(r["coins"] ?? ""),
201
+ currencyName: String(r["currency_name"] ?? ""),
202
+ raw: r
203
+ };
204
+ }
205
+ function toUnacknowledgedOutcome(row) {
206
+ if (!row || typeof row !== "object") return null;
207
+ const r = row;
208
+ return {
209
+ chargeTotalUsd: String(r["charge_total_usd"] ?? ""),
210
+ processingFeeUsd: String(r["processing_fee_usd"] ?? ""),
211
+ coins: String(r["coins"] ?? ""),
212
+ feeTakenFrom: String(r["fee_taken_from"] ?? "coins")
213
+ };
214
+ }
215
+ function toCurrencyPurchaseQuote(raw) {
216
+ const breakdown = toQuoteBreakdown(raw["breakdown"]);
217
+ return {
218
+ totalUsd: requireField(raw["total_usd"], "total_usd", raw),
219
+ amountCents: Number(raw["amount_cents"] ?? 0),
220
+ // Top-level since 2026-09-23; the breakdown has always carried the same figures.
221
+ subtotalUsd: String(raw["subtotal_usd"] ?? breakdown.subtotalUsd),
222
+ processingFeeUsd: String(raw["processing_fee_usd"] ?? breakdown.processingFeeUsd),
223
+ coins: String(raw["coins"] ?? breakdown.coins),
224
+ currencyName: String(raw["currency_name"] ?? breakdown.currencyName),
225
+ breakdown,
226
+ ifUnacknowledged: toUnacknowledgedOutcome(raw["if_unacknowledged"]),
227
+ raw
228
+ };
229
+ }
180
230
  function invalidInput(label, value, why) {
181
231
  return new InvoError({
182
232
  message: `${label} ${why} (got ${JSON.stringify(value)}).`,
@@ -794,6 +844,7 @@ function toSubscription(row) {
794
844
  nextChargeAt: nullableString(r["next_charge_at"]),
795
845
  cancelAtPeriodEnd: r["cancel_at_period_end"] === true,
796
846
  trialEnd: nullableString(r["trial_end"]),
847
+ trialAmountUsd: nullableString(r["trial_amount_usd"]),
797
848
  canceledAt: nullableString(r["canceled_at"]),
798
849
  endedAt: nullableString(r["ended_at"]),
799
850
  walletOnly: r["wallet_only"] === true,
@@ -807,7 +858,10 @@ function toSubscription(row) {
807
858
  consent_user_agent: nullableString(consent["consent_user_agent"]),
808
859
  disclosed_amount_usd: nullableString(consent["disclosed_amount_usd"]),
809
860
  disclosed_interval: nullableString(consent["disclosed_interval"]),
810
- terms_version: nullableString(consent["terms_version"])
861
+ terms_version: nullableString(consent["terms_version"]),
862
+ disclosed_trial_amount_usd: nullableString(consent["disclosed_trial_amount_usd"]),
863
+ disclosed_trial_days: typeof consent["disclosed_trial_days"] === "number" ? consent["disclosed_trial_days"] : null,
864
+ disclosed_trial_end: nullableString(consent["disclosed_trial_end"])
811
865
  },
812
866
  createdAt: String(r["created_at"] ?? ""),
813
867
  updatedAt: String(r["updated_at"] ?? ""),
@@ -819,6 +873,8 @@ function toSubscription(row) {
819
873
  } : null,
820
874
  paidThrough: nullableString(r["paid_through"]),
821
875
  amountCoinsEstimate: r["amount_coins_estimate"] == null ? void 0 : String(r["amount_coins_estimate"]),
876
+ // Present (possibly null) only on create/finalize bodies from 2026-09-23 on.
877
+ ..."trial_amount_coins_estimate" in r ? { trialAmountCoinsEstimate: nullableString(r["trial_amount_coins_estimate"]) } : {},
822
878
  // `include_player` puts these two ON the object (there is no separate block).
823
879
  ..."player_email" in r ? { playerEmail: nullableString(r["player_email"]) } : {},
824
880
  ..."player_name" in r ? { playerName: nullableString(r["player_name"]) } : {},
@@ -936,6 +992,9 @@ function subscriptionBaseBody(input) {
936
992
  if (c.disclosedAmountUsd !== void 0) consent["disclosed_amount_usd"] = c.disclosedAmountUsd;
937
993
  if (c.disclosedInterval !== void 0) consent["disclosed_interval"] = c.disclosedInterval;
938
994
  if (c.termsVersion !== void 0) consent["terms_version"] = c.termsVersion;
995
+ if (c.disclosedTrialAmountUsd !== void 0) consent["disclosed_trial_amount_usd"] = c.disclosedTrialAmountUsd;
996
+ if (c.disclosedTrialDays !== void 0) consent["disclosed_trial_days"] = c.disclosedTrialDays;
997
+ if (c.disclosedTrialEnd !== void 0) consent["disclosed_trial_end"] = c.disclosedTrialEnd;
939
998
  body["consent"] = consent;
940
999
  }
941
1000
  if (input.revenueShare) {
@@ -986,6 +1045,15 @@ var SubscriptionsServer = class {
986
1045
  * `failureCode: "no_payment_method"`, whatever the member's balance: save a card first.
987
1046
  * `walletOnly: true` is deprecated: it never charges a card, so such a subscription can never
988
1047
  * be paid (`failureCode: "wallet_only"`).
1048
+ *
1049
+ * PAID TRIAL: send `trialAmountUsd` with `trialDays` or `trialEnd` (for example $1.00 for 7
1050
+ * days, then `amountUsd` monthly). Period 1 is charged the trial price inside this call, so a
1051
+ * usable saved card is required (`400 PAYMENT_METHOD_REQUIRED`, `err.isPaymentMethodRequired`),
1052
+ * `firstCharge` reports the trial charge (never `skipped_trial`), and a refused trial charge
1053
+ * ends the subscription at once (`expired`, no retry). Other refusals:
1054
+ * `err.isTrialAmountRequiresTrial`, `err.isTrialAmountNotSupportedForFunding`,
1055
+ * `err.isTrialAmountInvalid` (below $0.50, or not less than `amountUsd`),
1056
+ * `err.isConsentDisclosedTrialInvalid`.
989
1057
  * Requires the game to be `live` (`err.isGameNotLive`).
990
1058
  */
991
1059
  async create(input, opts) {
@@ -1008,6 +1076,23 @@ var SubscriptionsServer = class {
1008
1076
  }
1009
1077
  body["trial_end"] = input.trialEnd;
1010
1078
  }
1079
+ if (input.trialAmountUsd !== void 0) {
1080
+ if (input.trialDays === void 0 && input.trialEnd === void 0) {
1081
+ throw new InvoError({
1082
+ message: "trialAmountUsd requires a trial: send trialDays or trialEnd with it.",
1083
+ code: "TRIAL_AMOUNT_REQUIRES_TRIAL",
1084
+ status: 0
1085
+ });
1086
+ }
1087
+ if (input.walletOnly === true) {
1088
+ throw new InvoError({
1089
+ message: "trialAmountUsd is only available on card-funded subscriptions; it cannot be combined with walletOnly: true.",
1090
+ code: "TRIAL_AMOUNT_NOT_SUPPORTED_FOR_FUNDING",
1091
+ status: 0
1092
+ });
1093
+ }
1094
+ body["trial_amount_usd"] = subscriptionMoney(input.trialAmountUsd, "trialAmountUsd");
1095
+ }
1011
1096
  if (input.walletOnly !== void 0) {
1012
1097
  if (typeof input.walletOnly !== "boolean") {
1013
1098
  throw invalidInput("walletOnly", input.walletOnly, "must be a boolean");
@@ -1227,8 +1312,9 @@ var SubscriptionsServer = class {
1227
1312
  * the stored receipt with `idempotentReplay: true` and moves nothing.
1228
1313
  *
1229
1314
  * **Branch on `status`.** `"refunded"` (HTTP 200): the refund ran. `"pending_approval"`
1230
- * (HTTP 202): the refund would exceed the game's daily self-serve limit ($500 per UTC day
1231
- * by default), NOTHING moved, and INVO reviews it as a refund request (`requestId`); the
1315
+ * (HTTP 202): the refund would exceed the game's daily self-serve limit per UTC day (by
1316
+ * default never lower than the largest single subscription charge, so a single period
1317
+ * always runs unless INVO set a lower limit for the game), NOTHING moved, and INVO reviews it as a refund request (`requestId`); the
1232
1318
  * outcome arrives as `subscription.refund_approved` (sent together with
1233
1319
  * `subscription.refunded`, and `subscription.canceled` on a full refund, in any order) or
1234
1320
  * `subscription.refund_rejected`. The 202 carries every receipt field with nothing moved
@@ -1327,6 +1413,13 @@ var SubscriptionsServer = class {
1327
1413
  throw invalidInput("intervalCount", input.intervalCount, "must be 1 on the Steam rail (monthly and yearly only)");
1328
1414
  }
1329
1415
  const forbidden = input;
1416
+ if (forbidden["trialAmountUsd"] !== void 0) {
1417
+ throw new InvoError({
1418
+ message: "trialAmountUsd is only available on card-funded subscriptions (subscriptions.create). Steam subscriptions have no trials.",
1419
+ code: "TRIAL_AMOUNT_NOT_SUPPORTED_FOR_FUNDING",
1420
+ status: 0
1421
+ });
1422
+ }
1330
1423
  for (const k of ["trialDays", "trialEnd", "walletOnly", "playerCardId"]) {
1331
1424
  if (forbidden[k] !== void 0) {
1332
1425
  throw invalidInput(k, forbidden[k], "is not available on the Steam rail");
@@ -1796,6 +1889,18 @@ var InvoServer = class {
1796
1889
  * (run client-side 3-D Secure with clientSecret, then call confirmPayment).
1797
1890
  * - rail "game": returns status "pending_payment" + paymentUrl (redirect the browser).
1798
1891
  * - rail "steam": NOT a browser flow — the backend returns WRONG_RAIL_ENDPOINT.
1892
+ *
1893
+ * INVO's card fee (3.5% + $0.30, never less than the card cost). Two shapes, chosen by
1894
+ * what you send:
1895
+ * - with `acknowledgedTotalUsd` (the `totalUsd` from {@link quoteCurrencyPurchase}): the
1896
+ * card is charged that total and the coins are priced off `usdAmount`. A total that no
1897
+ * longer matches throws `409 QUOTE_STALE` (`err.isQuoteStale`); nothing was charged.
1898
+ * - without it: the card is charged exactly `usdAmount`, never more, and the fee comes out
1899
+ * of the coins. An amount too small to carry the fee throws `400 AMOUNT_BELOW_FEE`
1900
+ * (`err.isAmountBelowFee`); nothing was charged.
1901
+ *
1902
+ * A `success` result reports `processingFeeUsd`, `feeTakenFrom`, `coinsCredited` and
1903
+ * `chargeTotalUsd`.
1799
1904
  */
1800
1905
  async purchaseCurrency(input, opts) {
1801
1906
  if (typeof input.playerEmail !== "string" || !input.playerEmail.trim()) {
@@ -1821,6 +1926,10 @@ var InvoServer = class {
1821
1926
  usd_amount: input.usdAmount,
1822
1927
  purchase_reference: input.purchaseReference
1823
1928
  };
1929
+ if (input.acknowledgedTotalUsd !== void 0) {
1930
+ assertAcknowledgedTotal(input.acknowledgedTotalUsd);
1931
+ body["acknowledged_total_usd"] = input.acknowledgedTotalUsd;
1932
+ }
1824
1933
  if (input.rail) body["rail"] = input.rail;
1825
1934
  if (input.paymentMethodId) body["payment_method_id"] = input.paymentMethodId;
1826
1935
  if (input.savedCardId) body["saved_card_id"] = input.savedCardId;
@@ -1842,9 +1951,47 @@ var InvoServer = class {
1842
1951
  transactionId: raw["transaction_id"],
1843
1952
  orderId: raw["order_id"],
1844
1953
  newBalance: raw["new_balance"] ?? null,
1954
+ processingFeeUsd: optionalDecimalString(raw["processing_fee_usd"]),
1955
+ feeTakenFrom: optionalDecimalString(raw["fee_taken_from"]),
1956
+ coinsCredited: optionalDecimalString(raw["coins_credited"]),
1957
+ chargeTotalUsd: optionalDecimalString(raw["charge_total_usd"]),
1845
1958
  raw
1846
1959
  };
1847
1960
  }
1961
+ /**
1962
+ * What a card purchase of coins will cost, BEFORE charging for it. Moves no money and
1963
+ * creates nothing, so it is safe to call on every price render (`POST
1964
+ * /api/currency-purchases/quote`, authenticated by your game secret like the purchase).
1965
+ *
1966
+ * INVO's card fee on a coin purchase is 3.5% + $0.30 of the price, never less than the
1967
+ * card cost. `totalUsd` is the price plus that fee (plus any tax, when you pass `country`):
1968
+ * $10.00 quotes a $10.65 total. Show the player `totalUsd`, then send the same figure back
1969
+ * as `acknowledgedTotalUsd` on {@link purchaseCurrency}; the card is charged exactly that
1970
+ * and the player gets the coins for the full price. `ifUnacknowledged` shows the other
1971
+ * outcome: the card charged exactly `usdAmount` and the fee taken out of the coins ($10.00
1972
+ * gives 93.70 coins at the default 10 per USD), or `null` when the amount cannot carry the
1973
+ * fee.
1974
+ *
1975
+ * Refusals: `400 INVALID_INPUT` (amount missing, not above zero, or above INVO's card
1976
+ * maximum), `400 CURRENCY_NOT_CONFIGURED`, `503 RATE_UNAVAILABLE`.
1977
+ */
1978
+ async quoteCurrencyPurchase(input, opts) {
1979
+ assertUsdAmount(input.usdAmount);
1980
+ const body = {
1981
+ player_email: input.playerEmail,
1982
+ usd_amount: input.usdAmount
1983
+ };
1984
+ if (input.country) body["country"] = input.country;
1985
+ if (input.subdivision) body["subdivision"] = input.subdivision;
1986
+ const raw = await this.http.post(
1987
+ "/api/currency-purchases/quote",
1988
+ body,
1989
+ this.auth,
1990
+ { idempotent: true, signal: opts?.signal }
1991
+ // a read: it moves no money and creates nothing
1992
+ );
1993
+ return toCurrencyPurchaseQuote(raw);
1994
+ }
1848
1995
  /** Complete the card-rail 3-D Secure step after the client finished card action. */
1849
1996
  async confirmPayment(input, opts) {
1850
1997
  const body = { payment_intent_id: input.paymentIntentId };