@invonetwork/web-sdk 3.27.0 → 3.29.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,2127 +1,3 @@
1
- import { I as InvoError, H as Http, a2 as AuthHeader, g as CallOptions, a3 as PlatformPurchaseInput, a4 as PlatformPurchaseResult, a5 as PlatformOrderStatusResult, a6 as PlatformPurchaseHistoryQuery, a7 as PlatformPurchaseHistoryResult, a8 as PlatformRefundInput, a9 as PlatformRefundResult, aa as CreateSubscriptionInput, ab as SubscriptionResult, ac as GetSubscriptionOptions, ad as GetSubscriptionResult, ae as ListSubscriptionsOptions, af as SubscriptionListResult, ag as CancelSubscriptionOptions, ah as CancelResult, ai as ChangeAmountResult, aj as SetPaymentMethodInput, ak as SetPaymentMethodResult, al as RefundSubscriptionInput, am as RefundResult, an as SteamSubscriptionInitInput, ao as SteamInitResult, ap as SteamFinalizeSubscriptionResult, aq as CardSetupSessionInput, ar as CardSetupSessionResult, as as CardSetupInput, at as CardSetupResult, au as CardSetupConfirmInput, av as CardSetupConfirmResult, aw as PlayerCardsResult, ax as SandboxClockResult, ay as SandboxFailureOutcome, az as SandboxForceFailureOptions, aA as SandboxForceAuthChallengeOptions, aB as ServerConfig, aC as MintPlayerTokenInput, aD as PlayerToken, aE as RegisterPlayerInput, aF as RegisterPlayerResult, aG as UpdatePlayerPhoneInput, aH as UpdatePlayerPhoneResult, aI as RequestPhoneChangeInput, aJ as RequestPhoneChangeResult, aK as PhoneChangeRequest, aL as InitiateSendInput, aM as InitiateResult, aN as InitiateTransferInput, aO as CreateCheckoutInput, aP as CreateCheckoutResult, aQ as PurchaseInput, aR as PurchaseResult, aS as CurrencyPurchaseQuoteInput, aT as CurrencyPurchaseQuote, aU as ConfirmPaymentResult, aV as OrderDetailsResult, aW as SteamPacksQuery, aX as SteamPacksResult, aY as SteamInitPurchaseInput, aZ as SteamInitPurchaseResult, a_ as SteamFinalizeInput, a$ as SteamFinalizeResult, b0 as PurchaseItemInput, b1 as PurchaseItemResult, b2 as ItemHistoryQuery, b3 as ItemHistoryResult, b4 as ItemOrderQuery, b5 as PlayerActivityQuery, b6 as PlayerActivityResult, b7 as PlayerActivityEntry, b8 as PlayerBalanceQuery, b9 as PlayerBalanceResult, o as LoyaltyCardsResult, ba as ReportServerGameEventInput, s as ReportGameEventResult, bb as InboundPendingQuery, bc as InboundPendingResult, bd as LinkedIdentitiesQuery, be as LinkedIdentitiesResult, bf as SmsVerifyResult, bg as ClaimTransferInput, bh as ClaimResult, bi as ClaimCurrencyInput, bj as TransactionStatusResult, bk as GuardianApprovalStatusResult, bl as ServerDestinationsQuery, n as DestinationsResult, bm as PhoneShareContact, bn as PhoneShareInitiateResult, bo as PhoneShareApproveInput, bp as PhoneShareApproveResult, bq as PhoneShareStatusResult, br as BeginDeviceApprovalInput, bs as DeviceApprovalGrant, bt as PollDeviceApprovalInput, bu as DeviceApprovalPollResult, bv as ConfirmDeviceEnrollmentInput, bw as ConfirmDeviceEnrollmentResult, bx as ApproveWithDeviceCodeInput, by as DeviceApprovalSettleResult, bz as CompleteDeviceApprovalInput, bA as CompleteDeviceApprovalResult } from './types-_lIm74kd.js';
2
- export { bB as CardSetupStatus, bC as CheckoutWarning, y as ClaimDelivery, bD as CurrencyBalance, bE as CurrencyPurchaseQuoteBreakdown, z as DestinationGame, bF as DeviceApprovalChannel, bG as DeviceApprovalEnrollment, bH as DeviceApprovalFlow, bI as DeviceApprovalPollStatus, bJ as DeviceEnrollmentDecision, bK as DeviceEnrollmentRespond, bL as ExpiryReason, bM as FeeTakenFrom, bN as FirstCharge, bO as FirstChargeStatus, bP as FundingSource, G as GameEventType, bQ as InboundPendingItem, F as InvoErrorInfo, J as InvoHooks, K as InvoRequestInfo, N as InvoResponseInfo, bR as LinkedIdentityEmail, O as LoyaltyCard, Q as LoyaltyCardReward, S as LoyaltyCardStep, T as LoyaltyRewardState, U as LoyaltyStepProgress, V as LoyaltyStepState, bS as MinPurchaseWarning, bT as PhoneChangeConfirmation, bU as PhoneChangeRequestStatus, bV as PlatformPurchaseStatus, bW as PlayerActivityType, a0 as Rail, bX as RefundInitiation, bY as RefundPendingApproval, bZ as RefundProcessingFeeBasis, b_ as RefundReceipt, b$ as RefundRevenueShareAttribution, c0 as RefundWarning, r as ReportGameEventInput, c1 as SandboxClockState, c2 as SavedCard, c3 as SteamPack, c4 as SteamUserSession, c5 as Subscription, c6 as SubscriptionBaseInput, c7 as SubscriptionConsent, c8 as SubscriptionConsentInput, c9 as SubscriptionFundingRail, ca as SubscriptionInterval, cb as SubscriptionRevenueShare, cc as SubscriptionRevenueShareInput, cd as SubscriptionStatus, ce as UnacknowledgedPurchaseOutcome, a1 as VerificationMethod, cf as isRefundPendingApproval } from './types-_lIm74kd.js';
3
- export { S as SDK_VERSION } from './version-BXFwI0-s.js';
4
-
5
- interface VerifyWebhookOptions {
6
- /** Max age of the signed timestamp, in seconds. Default 300 (5 min). */
7
- toleranceSec?: number;
8
- /** Override the current time (unix seconds) — for tests. Defaults to Date.now(). */
9
- nowSec?: number;
10
- }
11
- interface WebhookBase {
12
- event_id: string;
13
- idempotency_key: string;
14
- schema_version: string;
15
- created_at: string;
16
- /** Your game_id. */
17
- tenant_id: string;
18
- }
19
- interface PurchaseCompletedData {
20
- transaction_id: string;
21
- order_id: string;
22
- player_email: string;
23
- identity_id: string;
24
- usd_amount: string;
25
- currency_amount: string;
26
- currency_name: string;
27
- new_balance: string;
28
- /** Which settlement rail carried the money. Provider-neutral. */
29
- rail: string;
30
- /**
31
- * Which STOREFRONT the purchase came from — "steam" / "ios" / "android" /
32
- * "web" / "console" — beside the rail it was paid on. Read off the order,
33
- * not the request. `null` when the caller used a legacy game key: that is a
34
- * real answer ("unattributed"), read it as one.
35
- */
36
- channel?: string | null;
37
- /**
38
- * The metadata you passed to createCheckout/purchaseCurrency/steamInitPurchase, echoed back
39
- * (all rails).
40
- *
41
- * **Subscription renewals also emit `purchase.completed`** (every paid card renewal, for the
42
- * coins its charge minted). Those carry `metadata.source === "subscription_renewal"` and
43
- * `metadata.subscription_id` (plus `period_seq`, `attempt_no`, `item_id`, `funding_rail`,
44
- * and `funding_model: "card_only"` on the card rail). **Do not grant currency or access from
45
- * them**: the renewal spends those coins in the same step. Act on `subscription.renewed`;
46
- * its `mint_order_id` equals this event's `order_id`.
47
- */
48
- metadata?: Record<string, unknown>;
49
- /**
50
- * Why the tax is what it is. `"partner_responsible"` on an Open-tier account (you are the
51
- * seller; INVO charged no tax); on Merchant of Record, how INVO handled it (for example
52
- * `"collected"`). Treat an unknown value as informational.
53
- */
54
- tax_treatment?: string | null;
55
- /**
56
- * Merchant of Record accounts only (card sales): the receipt INVO issued to the buyer.
57
- * Absent on Open accounts and storefront rails.
58
- */
59
- receipt_number?: string;
60
- /** Merchant of Record only: link to the printable receipt page. Anyone with it can read it. */
61
- receipt_url?: string;
62
- /**
63
- * Additive (2026-09 pricing). INVO's card fee charged to you for this purchase, USD decimal
64
- * string: 3.5% + $0.30 on Open, 5.5% + $0.50 on Merchant of Record. The buyer paid the listed
65
- * price (plus any tax) and received the listed coins; the fee nets against your earnings.
66
- * Card purchases only; absent on purchases through a third-party storefront or payment rail,
67
- * on an order charged before the 2026-09 pricing, and from backends that do not send it.
68
- * `null` when the fee could not be booked when the purchase completed (the purchase itself
69
- * succeeded; INVO books the fee shortly after).
70
- */
71
- partner_fee_usd?: string | null;
72
- /**
73
- * Additive (2026-09 pricing). The international card fee charged to you, USD decimal string:
74
- * 1.5% of the listed price (before tax) on a card issued outside the US, `"0.00"` otherwise
75
- * (a card whose country is unknown counts as domestic). Separate from `partner_fee_usd`.
76
- * Card purchases only; absent and `null` on the same terms as `partner_fee_usd`.
77
- */
78
- international_card_fee_usd?: string | null;
79
- [key: string]: unknown;
80
- }
81
- interface PurchaseEventData {
82
- transaction_id: string;
83
- order_id?: string;
84
- player_email?: string;
85
- identity_id?: string;
86
- /** Present on purchase.disputed, e.g. "lost". */
87
- dispute_status?: string;
88
- /**
89
- * Additive (2026-09 pricing), on a LOST purchase.disputed for a Platform Commerce card sale
90
- * or a subscription charge (`order_type` `"platform_commerce"` or `"subscription_renewal"`).
91
- * `true` when INVO's chargeback guarantee covers this dispute: a fraud chargeback on a card
92
- * sale, which INVO absorbs, so your share is not reversed or held and no dispute fee is passed
93
- * to you. The guarantee is a Merchant of Record term; Open-tier card payments made before
94
- * November 8, 2026 keep it, later ones do not (`false`, passed through at cost). `false`
95
- * for any other dispute, handled as before. Never sent on a coin purchase
96
- * dispute (a lost coin chargeback takes back the player's coins, not your share, so there is
97
- * nothing to cover), nor on an opened or won event. Do not read absence as either value.
98
- */
99
- guarantee_covered?: boolean;
100
- /**
101
- * Additive, on a lost purchase.disputed for an order that sold no coins: `"platform_commerce"`
102
- * or `"subscription_renewal"`. Absent on a coin purchase dispute.
103
- */
104
- order_type?: string;
105
- /**
106
- * Additive, on a lost Platform Commerce or subscription purchase.disputed: your share of the
107
- * sale reversed, USD decimal string (`"0.00"` when the chargeback guarantee covered it).
108
- */
109
- developer_revenue_reversed_usd?: string | null;
110
- /**
111
- * Additive (2026-09-27), on a lost subscription purchase.disputed. Since 2026-09-28
112
- * (D-PRICE-012) always `"0.00"`: a lost dispute charges INVO's card fee instead
113
- * (`card_fee_charged_to_partner_usd`), not a separate processor fee. `null` where it does not
114
- * apply (for example a Platform Commerce dispute). Absent on coin purchase disputes.
115
- */
116
- processing_fee_usd?: string | null;
117
- /**
118
- * Additive (2026-09-28, D-PRICE-012), on a lost Platform Commerce or subscription
119
- * purchase.disputed: INVO's card fee on the lost amount, charged to you, USD decimal string.
120
- * A lost dispute not covered by the chargeback guarantee costs you exactly what a refund of
121
- * the same charge does, on every charge. `"0.00"` when the guarantee covered it; `null` where
122
- * it does not apply (including a settlement replay). Absent on coin purchase disputes.
123
- */
124
- card_fee_charged_to_partner_usd?: string | null;
125
- /**
126
- * Additive (2026-09-28, D-PRICE-012), same events: your whole debit for the lost dispute,
127
- * `developer_revenue_reversed_usd` plus `card_fee_charged_to_partner_usd`. `"0.00"` when the
128
- * guarantee covered it; `null` where it does not apply.
129
- */
130
- partner_debited_usd?: string | null;
131
- /**
132
- * Additive (2026-10-09), on a card purchase.disputed sent when the dispute closes (won or
133
- * lost): the card network's dispute fee charged to you for this dispute, USD decimal string
134
- * such as `"15.00"`. `"0.00"` when INVO bears it or it was returned to INVO. From November 8,
135
- * 2026, on Open-tier card sales (coin purchases, Platform Commerce card sales and subscription
136
- * charges), the dispute fee is passed through to you at cost. `null` when it cannot be decided.
137
- * A lost dispute is purchase.disputed with `dispute_status` `"lost"`; there is no separate
138
- * lost-dispute event. Absent on older events and storefront chargebacks; do not read absence
139
- * as zero.
140
- */
141
- dispute_fee_usd?: string | null;
142
- /**
143
- * Additive (2026-10-09), same events: `true` when `dispute_fee_usd` is above zero (the fee is
144
- * charged to you), `false` when it is not, `null` when it cannot be decided. Absent where
145
- * `dispute_fee_usd` is absent.
146
- */
147
- dispute_fee_charged_to_partner?: boolean | null;
148
- /** On a lost subscription purchase.disputed: the subscription and period it concerns. */
149
- subscription_id?: string | null;
150
- period_seq?: number | null;
151
- /**
152
- * Card-only ids on purchase.disputed. `null` on a storefront chargeback (for example a
153
- * Steam chargeback, which has no payment intent, charge or dispute id).
154
- */
155
- payment_intent_id?: string | null;
156
- charge_id?: string | null;
157
- dispute_id?: string | null;
158
- /**
159
- * The rail the purchase was paid on, where the event carries it: `"steam"` on a Steam
160
- * `purchase.refunded` or `purchase.disputed`.
161
- */
162
- rail?: string;
163
- /** The Steam transaction id, on a Steam `purchase.refunded` or `purchase.disputed`. */
164
- steam_transid?: string;
165
- /** On purchase.refunded: `false` for a partial refund (a Steam partial refund included). */
166
- fully_refunded?: boolean;
167
- /** Coins taken back by this event, or `null` when the player has no balance row. */
168
- currency_debited?: string | null;
169
- /** The player's balance after this event. Never below zero. */
170
- new_balance?: string | null;
171
- /**
172
- * Merchant of Record accounts only (on `purchase.refunded`, card refunds): the REFUND receipt INVO issued to the
173
- * buyer. Absent on Open accounts, and while a refund is still pending.
174
- */
175
- receipt_number?: string;
176
- /** Merchant of Record only: link to the printable refund receipt page. */
177
- receipt_url?: string;
178
- [key: string]: unknown;
179
- }
180
- interface ItemPurchasedData {
181
- transaction_id: string;
182
- order_id: string;
183
- player_email: string;
184
- identity_id: string;
185
- item_id: string;
186
- item_name: string;
187
- item_quantity: number;
188
- unit_price: string;
189
- total_price: string;
190
- currency_name: string;
191
- new_balance: string;
192
- fee_breakdown?: Record<string, unknown>;
193
- [key: string]: unknown;
194
- }
195
- /** `platform_commerce.purchased` — a Platform Commerce (ecommerce) purchase completed
196
- * (balance immediately; card after the payment settles). Fulfill card orders on THIS,
197
- * never on the browser confirmation. */
198
- interface PlatformCommercePurchasedData {
199
- transaction_id: string;
200
- order_id: string | number;
201
- /** "balance" | "card". */
202
- funding_source: string;
203
- player_email: string;
204
- identity_id: string;
205
- item_id: string;
206
- item_name: string;
207
- item_quantity: number;
208
- /** Balance leg only — the network-currency amount. The CARD leg carries `total_price_usd`
209
- * instead (this field is absent there). */
210
- total_price?: string;
211
- /** Balance leg only. */
212
- unit_price?: string;
213
- currency_name?: string;
214
- new_balance?: string;
215
- /** Card leg only (the USD charged). */
216
- total_price_usd?: string;
217
- /**
218
- * `{ total_paid, platform_fee, developer_revenue, ... }`. `platform_fee` is INVO's whole fee
219
- * and INCLUDES the international card fee; `platform_fee + developer_revenue = total_paid`.
220
- * Since the 2026-09 pricing it also carries `international_card_fee_usd` (the part of
221
- * `platform_fee` that is the international card fee, `"0.00"` on a US card and on the
222
- * balance leg), so the card rate part is `platform_fee - international_card_fee_usd`.
223
- */
224
- fee_breakdown?: Record<string, unknown>;
225
- /**
226
- * Additive (2026-09 pricing). The international card fee on this sale, USD decimal string:
227
- * 1.5% of the listed price (before tax) on a card issued outside the US, `"0.00"` otherwise
228
- * and on the balance leg. Already INCLUDED in `fee_breakdown.platform_fee`; do not add it
229
- * again.
230
- */
231
- international_card_fee_usd?: string;
232
- /**
233
- * Merchant of Record accounts only (card sales): the receipt INVO issued to the buyer.
234
- * Absent on Open accounts and storefront rails.
235
- */
236
- receipt_number?: string;
237
- /** Merchant of Record only: link to the printable receipt page. Anyone with it can read it. */
238
- receipt_url?: string;
239
- [key: string]: unknown;
240
- }
241
- /** `platform_commerce.refunded`: a Platform Commerce purchase was refunded. INVO's fee is
242
- * not returned (`fee_retained: true`). On a card refund the fee stays charged to you
243
- * (`card_fee_charged_to_partner_usd`, `partner_debited_usd`). */
244
- interface PlatformCommerceRefundedData {
245
- order_id: string | number;
246
- /** "balance" | "card". */
247
- funding_source: string;
248
- /** Null when the player row no longer exists at refund time. */
249
- player_email: string | null;
250
- /** Nullable for the same reason. */
251
- identity_id?: string | null;
252
- refunded_amount: string;
253
- /** `"usd"` (card) or the literal `"currency"` (balance). */
254
- amount_unit: string;
255
- fee_retained: boolean;
256
- /**
257
- * Merchant of Record accounts only (card refunds): the REFUND receipt INVO issued to the
258
- * buyer. Absent on Open accounts, and while a refund is still pending.
259
- */
260
- receipt_number?: string;
261
- /** Merchant of Record only: link to the printable refund receipt page. */
262
- receipt_url?: string;
263
- /**
264
- * Additive (2026-09 pricing), card refunds only: the part of INVO's card fee on this refund
265
- * that stays charged to you, USD decimal string. The card fee is not returned on a refund.
266
- */
267
- card_fee_charged_to_partner_usd?: string;
268
- /**
269
- * Additive (2026-09 pricing), card refunds only: everything this refund takes from your
270
- * earnings, USD decimal string: your share of the sale reversed plus
271
- * `card_fee_charged_to_partner_usd`.
272
- */
273
- partner_debited_usd?: string;
274
- [key: string]: unknown;
275
- }
276
- interface TransferEventData {
277
- transaction_id: string;
278
- /** "transfer" | "send". */
279
- flow?: string;
280
- amount?: string;
281
- net_amount?: string;
282
- /**
283
- * On `transfer.claim_pending` / `transfer.claim_expired`: `"outbound"` on the copy sent to
284
- * the sending title (drives the sender's UI), `"inbound"` on the copy sent to the
285
- * destination title (drives the receiving player's UI). A move inside one title sends that
286
- * title BOTH copies, each with its own `event_id`: dedupe on `event_id`, not
287
- * `transaction_id`, and act on `direction`.
288
- */
289
- direction?: "inbound" | "outbound" | (string & {});
290
- /** On inbound claim_pending: the recipient's phone (match to your player). */
291
- to_phone?: string;
292
- /** Recipient's opaque identity, present only when the phone maps to a single player. */
293
- to_identity_id?: string | null;
294
- /** On `transfer.claim_pending`: the order id of the send or transfer. */
295
- order_id?: string | null;
296
- /** On `transfer.claim_pending`: what the recipient receives after fees. */
297
- net_transfer_amount?: string;
298
- /** On `transfer.claim_pending`: when the recipient's chance to collect lapses (ISO 8601). */
299
- claim_code_expires_at?: string | null;
300
- from_game_id?: string | number;
301
- to_game_id?: string | number;
302
- from_player_id?: string | number;
303
- /** On `transfer.claim_expired` and an expiry `transfer.refunded`: when it expired (ISO 8601). */
304
- expired_at?: string;
305
- /**
306
- * On `transfer.refunded` after an expiry: `"claim_expired"` or `"pin_expired"` (the latter
307
- * also covers a lapsed in-app approval). Read `expiry_reason` for the precise cause.
308
- */
309
- reason?: string;
310
- /**
311
- * Additive. On `transfer.claim_expired` and an expiry `transfer.refunded`: why it lapsed,
312
- * `"approval_expired"`, `"pin_expired"` or `"claim_expired"`. Absent on older deliveries.
313
- */
314
- expiry_reason?: "approval_expired" | "pin_expired" | "claim_expired" | (string & {});
315
- /** On `transfer.refunded`: the amount returned to the sender. */
316
- refunded_amount?: string;
317
- [key: string]: unknown;
318
- }
319
- /**
320
- * `payout.status_changed`: a payout of your balance to your bank moved to a new status. The
321
- * money fields are decimal strings (USD) or `null`. The payout fee fields are `null` on a
322
- * payout recorded before the fee existed.
323
- */
324
- /** Payout statuses. `cancelled` and `returned` are 3.25.0. */
325
- type PayoutStatus = "requested" | "approved" | "processing" | "completed" | "rejected" | "failed" | "cancelled" | "returned" | (string & {});
326
- /** Why a completed payout came back. A creator payout always reads `"returned"`. */
327
- type ReturnReasonCode = "account_closed" | "no_account" | "invalid_account" | "refused" | "other" | "returned" | (string & {});
328
- interface PayoutStatusChangedData {
329
- payout_id: string | number;
330
- status: PayoutStatus;
331
- previous_status: PayoutStatus | null;
332
- requested_amount_usd: string | null;
333
- /** The payout fee rate applied, percent (for example `"1"`). */
334
- offboarding_fee_pct?: string | null;
335
- /** The payout fee deducted from this payout. */
336
- offboarding_fee_usd?: string | null;
337
- /** What reaches your bank: the requested amount less the payout fee. */
338
- net_payout_usd?: string | null;
339
- /** The cap on the payout fee per payout (for example `"500.00"`); `null` means no cap. */
340
- offboarding_fee_cap_usd?: string | null;
341
- /**
342
- * Additive (3.25.0). On a creator payout, the creator INVO paid (`cp_...`); `null` on a
343
- * payout to your own bank. Never carries the creator's bank or personal details.
344
- */
345
- payee_id?: string | null;
346
- /** Additive (3.25.0). `"standard"` or `"manual"`; `null` before approval. */
347
- payout_method?: "standard" | "manual" | (string & {}) | null;
348
- /** Additive (3.25.0). On `status: "returned"`: when the receiving bank sent it back. */
349
- returned_at?: string | null;
350
- /** On `status: "returned"`. Always `"returned"` on a creator payout. */
351
- return_reason_code?: ReturnReasonCode | null;
352
- /** Additive (3.26.0). A note INVO wrote for you, or `null`. */
353
- partner_message?: string | null;
354
- /** Additive (3.26.0). The payout waits for the account owner's confirmation in the console. */
355
- owner_confirmation_required?: boolean;
356
- [key: string]: unknown;
357
- }
358
- /** Creator statuses (3.25.0). */
359
- type PayeeStatus = "invited" | "details_submitted" | "verified" | "rejected" | "suspended" | "expired" | "closed" | (string & {});
360
- /**
361
- * `payee.status_changed` (3.25.0): a creator you registered for creator payouts was
362
- * registered or changed status. Never carries the creator's name or email. Subscribe to it
363
- * by name.
364
- */
365
- interface PayeeStatusChangedData {
366
- payee_id: string;
367
- partner_reference: string;
368
- status: PayeeStatus;
369
- previous_status: PayeeStatus | null;
370
- payee_type: "individual" | "business" | (string & {});
371
- country: string;
372
- created_via: "api" | "console" | (string & {});
373
- status_changed_at: string;
374
- [key: string]: unknown;
375
- }
376
- /**
377
- * `player.phone_changed`: a player's phone changed (confirmed by the player, or changed by
378
- * INVO support). Sent to every game the player is in. `new_phone` is present only for the
379
- * game that requested the change (`new_phone_included: true`); every other game, and every
380
- * game on a support change, gets `new_phone_masked` only. Store the new `identity_id` and
381
- * re-mint the player's token. Never push the number you have stored back to INVO; if you
382
- * need the full new number and did not receive it, ask the player.
383
- */
384
- interface PlayerPhoneChangedData {
385
- player_email: string;
386
- previous_phone_masked: string | null;
387
- new_phone_masked: string | null;
388
- /** `true` only for the game that requested the change; then `new_phone` is present. */
389
- new_phone_included: boolean;
390
- /** The full new number, E.164. Present only when `new_phone_included` is `true`. */
391
- new_phone?: string;
392
- changed_at: string;
393
- /** `"player"` (confirmed by the player) or `"support"` (changed by INVO support). */
394
- source: "player" | "support" | (string & {});
395
- /** The player's new identity id. */
396
- identity_id: string;
397
- previous_identity_id: string;
398
- [key: string]: unknown;
399
- }
400
- /**
401
- * `identity.passkey_reset`: a player replaced a lost INVO passkey through recovery, on
402
- * INVO's approval or claim page or in your app through `recoveryBegin` /
403
- * `recoveryComplete` (the in-app path sends it since backend 2026-10-12). Sent to the
404
- * game the recovery ran in. Sending money out is paused for that player until
405
- * `cooldown_until`; receiving and collecting still work. Tell the player, or flag the
406
- * account, if they did not start it.
407
- */
408
- interface IdentityPasskeyResetData {
409
- /** The player's opaque identity id (the same id `player.phone_changed` carries). */
410
- identity_id: string;
411
- /** `"hosted_device"`, `"hosted_claim"` or `"sdk"`. */
412
- reset_via: "hosted_device" | "hosted_claim" | "sdk" | (string & {});
413
- /** ISO timestamp: until when sending money out is paused for this player. */
414
- cooldown_until: string | null;
415
- /** How many passkeys were switched off. */
416
- deactivated_count: number;
417
- [key: string]: unknown;
418
- }
419
- /**
420
- * The block every subscription event carries EXCEPT `subscription.renewed` and
421
- * `subscription.refunded`, which have their own shapes. `identity_id` is an opaque,
422
- * stable member id across INVO events; it is not the email.
423
- */
424
- interface SubscriptionEventCommon {
425
- subscription_id: string;
426
- item_id: string;
427
- item_name: string | null;
428
- player_email: string;
429
- identity_id: string;
430
- status: string;
431
- /** The current price, decimal string. */
432
- amount_usd: string;
433
- interval: string;
434
- interval_count: number;
435
- period_seq: number;
436
- current_period_start: string | null;
437
- current_period_end: string | null;
438
- next_charge_at: string | null;
439
- cancel_at_period_end: boolean;
440
- /** "card" | "steam". */
441
- funding_rail: string;
442
- steam_agreement_status: string | null;
443
- metadata: Record<string, unknown> | null;
444
- [key: string]: unknown;
445
- }
446
- /**
447
- * The two keys an event about period 1 of a PAID trial carries (`subscription.payment_failed`,
448
- * `past_due`, `authentication_required` and `expired`). The shared `amount_usd` is the regular
449
- * price; `amount_due_usd` and `trial_amount_usd` are the trial price. Absent on every other
450
- * event of these types, so test for presence.
451
- */
452
- interface SubscriptionTrialEventFields {
453
- /** `true` when present. */
454
- is_trial?: boolean;
455
- /** The paid-trial price, decimal string. */
456
- trial_amount_usd?: string;
457
- }
458
- /**
459
- * How a renewal was funded.
460
- *
461
- * Card rail (card only since 2026-09-17): the card pays the full price, so
462
- * `balance_applied_coins` is always `"0.00"`, `card_charged_usd` is the price, `minted_coins`
463
- * equals the event's `amount_coins`, and `new_balance` is the member's unchanged balance.
464
- * Steam rail: the wallet is spent first and Steam tops up the shortfall only.
465
- */
466
- interface SubscriptionRenewalFunding {
467
- /** The pre-existing wallet portion, in coins. Always `"0.00"` on the card rail. */
468
- balance_applied_coins: string;
469
- /** On the card rail, the full period price. */
470
- card_charged_usd: string;
471
- /** "card" | "steam". */
472
- rail: string;
473
- steam_charged_usd: string;
474
- minted_coins: string;
475
- new_balance: string;
476
- [key: string]: unknown;
477
- }
478
- /**
479
- * The fee split for one renewal. On the card rail INVO's fee (`invo_fee_usd`) is 3.5% + $0.30
480
- * on Open (5.5% + $0.50 on Merchant of Record) of the listed price (before tax). The 1.5%
481
- * international card fee on a card issued outside the US is NOT inside `invo_fee_usd`: it is
482
- * reported separately as `international_card_fee_usd` (also `pass_through_fees_usd`) and charged
483
- * to you on top. Read the figures; do not recompute them. On Steam, `basis` is
484
- * `"steam_net"` and `total_usd` is what the coins are worth after Valve's share and VAT, NOT the price (the price is the
485
- * event's top-level `amount_usd`).
486
- */
487
- interface SubscriptionRenewalSplit {
488
- total_usd: string;
489
- /** "price" (card) | "steam_net" (Steam). */
490
- basis: string;
491
- invo_fee_usd: string;
492
- partner_revenue_usd: string;
493
- invo_fee_coins: string;
494
- partner_revenue_coins: string;
495
- invo_fee_percent: string;
496
- /**
497
- * The international card fee charged to you on this renewal, USD decimal string, billed on
498
- * top of `invo_fee_usd`: `partner_revenue_usd` stays the gross figure and does not include
499
- * it. Since the 2026-09 pricing it is the flat international card fee, and
500
- * `international_card_fee_usd` carries the same figure under its own name. They are ONE
501
- * charge reported twice: never add the two together. `"0.00"` on a US card.
502
- */
503
- pass_through_fees_usd?: string;
504
- /** `"recorded"`, `"none"`, `"pending"` or `"not_applicable"` (no card charge). Treat unknown values as informational. */
505
- pass_through_status?: string;
506
- /**
507
- * Additive (2026-09 pricing). The international card fee on this renewal: 1.5% of the listed
508
- * price (before tax) on a card issued outside the US, `"0.00"` otherwise, while pending, and
509
- * on a charge opened before the 2026-09 pricing. The same figure as
510
- * `pass_through_fees_usd`; do not add them.
511
- */
512
- international_card_fee_usd?: string;
513
- [key: string]: unknown;
514
- }
515
- /** Revenue-share attribution on a renewal. INVO pays nothing (`settled_by_invo: false`). */
516
- interface SubscriptionRevenueShareAttribution {
517
- recipient_player_id: number;
518
- percent: string;
519
- base_usd: string;
520
- attributed_amount_usd: string;
521
- settled_by_invo: boolean;
522
- [key: string]: unknown;
523
- }
524
- /**
525
- * `subscription.renewed`: THE SOURCE OF TRUTH FOR ENTITLEMENT. Fires once per successfully
526
- * charged period, including period 1. Extend access to `period_end` (the new `paid_through`).
527
- * `period_start`/`period_end` are the period JUST PAID; `current_period_*` and
528
- * `next_charge_at` are the NEW window. `mint_order_id` is never `null` on a card renewal; on
529
- * Steam it is `null` when the wallet covered the period.
530
- *
531
- * Every paid card renewal also emits `purchase.completed` (with
532
- * `data.metadata.source === "subscription_renewal"`) for the coins its charge minted. Do not
533
- * grant anything from that event; its `order_id` is this event's `mint_order_id`.
534
- */
535
- interface SubscriptionRenewedData {
536
- subscription_id: string;
537
- item_id: string;
538
- period_seq: number;
539
- /**
540
- * `true` only on the event for period 1 of a PAID trial, whose `amount_usd` is then the trial
541
- * price; `false` on every other renewal. INVO sends it on every event from 2026-09-23 on;
542
- * optional here only because an event from an older backend does not carry it.
543
- */
544
- is_trial?: boolean;
545
- transaction_id: string;
546
- order_id: string;
547
- mint_order_id: string | null;
548
- player_email: string;
549
- identity_id: string;
550
- /** The price the period was billed at (a staged change appears from the period it applies to). */
551
- amount_usd: string;
552
- /** What the period was worth in coins. */
553
- amount_coins: string;
554
- period_start: string;
555
- period_end: string;
556
- current_period_start: string;
557
- current_period_end: string;
558
- next_charge_at: string | null;
559
- funding: SubscriptionRenewalFunding;
560
- split: SubscriptionRenewalSplit;
561
- revenue_share_attribution: SubscriptionRevenueShareAttribution | null;
562
- metadata: Record<string, unknown> | null;
563
- /**
564
- * Merchant of Record accounts only (card sales): the receipt INVO issued to the buyer.
565
- * Absent on Open accounts and storefront rails.
566
- */
567
- receipt_number?: string;
568
- /** Merchant of Record only: link to the printable receipt page. Anyone with it can read it. */
569
- receipt_url?: string;
570
- [key: string]: unknown;
571
- }
572
- /**
573
- * `subscription.payment_failed`: fires on EVERY failed attempt while the member still has
574
- * access. Does not revoke anything. On the final failure `retry_at` and `grace_period_end`
575
- * are `null`, `retries_remaining` is `0`, and `subscription.expired` follows.
576
- */
577
- interface SubscriptionPaymentFailedData extends SubscriptionEventCommon, SubscriptionTrialEventFields {
578
- attempt_no: number;
579
- period_start: string;
580
- period_end: string;
581
- amount_due_usd: string;
582
- /** "card_declined" | "insufficient_funds" | "error". */
583
- outcome: string;
584
- reason: string;
585
- /**
586
- * Why the attempt failed. Card rail: `card_declined`, `no_payment_method` (no saved card;
587
- * the coin wallet never pays a card subscription), `wallet_only` (a deprecated wallet-only
588
- * subscription, which can never be paid), `wallet_negative` (the member's coin balance is
589
- * below zero; nothing was charged), `card_expired`, `card_detached`, `card_mismatch`,
590
- * `no_customer_snapshot`, `processing_error`, `settlement_error`. Steam: `steam_*` codes.
591
- * Treat unknown values as a generic failure.
592
- */
593
- failure_code: string;
594
- failure_message: string | null;
595
- first_failure: boolean;
596
- retry_at: string | null;
597
- retries_remaining: number;
598
- grace_period_end: string | null;
599
- access_retained: boolean;
600
- }
601
- /** `subscription.past_due`: fires ONCE when the subscription enters `past_due`, not on every retry. */
602
- interface SubscriptionPastDueData extends SubscriptionEventCommon, SubscriptionTrialEventFields {
603
- amount_due_usd: string;
604
- grace_period_end: string | null;
605
- retry_at: string | null;
606
- retries_remaining: number;
607
- access_retained: boolean;
608
- }
609
- /**
610
- * `subscription.authentication_required`: NOT a failure. Card rail only. Nothing was
611
- * charged and no retry was consumed. Relay `confirmation_url` (a single-use bearer link)
612
- * to the member before `expires_at`. `card_amount_usd` is what the card is asked for: since
613
- * 2026-09-17 the full period price, the same figure as `amount_due_usd` (a challenge opened
614
- * before that date can still show the older wallet-shortfall figure).
615
- */
616
- interface SubscriptionAuthenticationRequiredData extends SubscriptionEventCommon, SubscriptionTrialEventFields {
617
- attempt_no: number;
618
- period_start: string;
619
- period_end: string;
620
- amount_due_usd: string;
621
- card_amount_usd: string;
622
- confirmation_url: string;
623
- expires_at: string;
624
- reason: string;
625
- access_retained: boolean;
626
- retry_consumed: boolean;
627
- }
628
- /**
629
- * `subscription.canceled`: fires once, at the moment cancellation is requested, in both
630
- * modes. Revoke at `access_until`. `canceled_by` is `"partner"` for your API call and
631
- * `"steam"` when the member cancelled the agreement from their Steam account. A full refund
632
- * also cancels the subscription immediately: that event carries `canceled_by: "partner"` and
633
- * `cancel_cause: "full_refund"`; it and `subscription.refunded` are sent together and may arrive in any order.
634
- */
635
- interface SubscriptionCanceledData extends SubscriptionEventCommon {
636
- effective_at: string;
637
- canceled_at: string | null;
638
- ended_at: string | null;
639
- access_until: string | null;
640
- paid_through: string | null;
641
- reason: string | null;
642
- /** "partner" | "steam". */
643
- canceled_by: string;
644
- /** Present only when the cancellation was a side effect: `"full_refund"`. Absent on an ordinary cancel. */
645
- cancel_cause?: string;
646
- }
647
- /**
648
- * `subscription.expired`: THE EVENT THAT REVOKES ENTITLEMENT. Revoke at `final_period_end`
649
- * (the last instant the member paid for; `null` if nothing was ever collected), not at
650
- * `ended_at`. A never-authorised Steam row carries `failure_code: "steam_authorization_abandoned"`.
651
- * `failure_code: "steam_containment"` is no longer sent (spending is not restricted by which
652
- * rail bought the currency). A refused PAID-trial charge ends the subscription at once with
653
- * `expire_cause: "trial_payment_failed"`, `is_trial: true`, `period_seq: 1` and
654
- * `final_period_end: null` (it follows a `subscription.payment_failed` with
655
- * `retries_remaining: 0`).
656
- */
657
- interface SubscriptionExpiredData extends SubscriptionEventCommon, SubscriptionTrialEventFields {
658
- failed_period_start: string | null;
659
- failed_period_end: string | null;
660
- final_attempt_no: number | null;
661
- attempts_used: number | null;
662
- failure_code: string | null;
663
- failure_message: string | null;
664
- ended_at: string;
665
- final_period_end: string | null;
666
- access_retained: boolean;
667
- /**
668
- * Present only when the expiry was not the ordinary end of dunning: `"trial_payment_failed"`
669
- * when a paid trial's own charge was refused. Absent on an ordinary expiry.
670
- */
671
- expire_cause?: string;
672
- }
673
- /** The `refund` block on `subscription.refunded`. */
674
- interface SubscriptionRefundDetail {
675
- /** "wallet" | "card" | "mixed". */
676
- funding_shape: string;
677
- /** Signed; can be negative. */
678
- balance_delta_coins: string;
679
- card_refunded_usd: string;
680
- processor_refund_adopted: boolean;
681
- new_balance: string;
682
- invo_fee_retained: boolean;
683
- partner_revenue_reversed_usd: string;
684
- /** "full" | "prorata". */
685
- partner_revenue_reversal_mode: string;
686
- /**
687
- * Additive (2026-09-17). Since 2026-09-28 (D-PRICE-012) always `"0.00"`: a card refund charges
688
- * INVO's card fee (`card_fee_charged_to_partner_usd`), not a separate processor fee. Older
689
- * events carried the processor fee here.
690
- */
691
- processing_fee_usd?: string;
692
- /** Additive (2026-09-17). "actual" | "estimated" | "none"; `"none"` since 2026-09-28. */
693
- processing_fee_basis?: string;
694
- /** Additive (2026-09-17). Always "partner". */
695
- processing_fee_borne_by?: string;
696
- /**
697
- * Additive (2026-09-17). Everything this refund took from your revenue; since 2026-09-28 the
698
- * same value as `partner_debited_usd`.
699
- */
700
- partner_total_reversed_usd?: string;
701
- /**
702
- * Additive (2026-09-28, D-PRICE-012). INVO's card fee on the refunded part, charged to you
703
- * (the card fee is not returned on a refund). `"0.00"` on a coin refund. Absent on older events.
704
- */
705
- card_fee_charged_to_partner_usd?: string;
706
- /**
707
- * Additive (2026-09-28, D-PRICE-012). Your whole debit: `partner_revenue_reversed_usd` plus
708
- * `card_fee_charged_to_partner_usd`, the refunded price before tax on a card refund. Absent on
709
- * older events; read `partner_total_reversed_usd` there.
710
- */
711
- partner_debited_usd?: string;
712
- [key: string]: unknown;
713
- }
714
- /**
715
- * `subscription.refunded`: its own shape. Your revenue for the refunded portion is
716
- * reversed (`refund.partner_revenue_reversed_usd`); INVO's fee is retained; on a card refund
717
- * you bear the whole refunded amount, INVO's card fee included (`refund.card_fee_charged_to_partner_usd`,
718
- * since 2026-09-28). "What did I earn" subtracts `refund.partner_debited_usd` (older events:
719
- * `refund.partner_total_reversed_usd`, then `partner_revenue_reversed_usd`).
720
- * A FULL refund cancels the subscription (`subscription_canceled: true`), and a
721
- * `subscription.canceled` with `cancel_cause: "full_refund"` is sent with it (sent together and may arrive in any order).
722
- * A partial one does not.
723
- */
724
- interface SubscriptionRefundedData {
725
- subscription_id: string;
726
- item_id: string;
727
- period_seq: number;
728
- transaction_id: string;
729
- client_request_id: string;
730
- player_email: string;
731
- identity_id: string;
732
- /** The amount refunded by this call. */
733
- amount_usd: string;
734
- total_refunded_amount_usd: string;
735
- period_amount_usd: string;
736
- is_full_refund: boolean;
737
- reason: string | null;
738
- period_status: string;
739
- refund: SubscriptionRefundDetail;
740
- revenue_share_attribution: Record<string, unknown> | null;
741
- metadata: Record<string, unknown> | null;
742
- /** Additive (2026-09-17). "self_serve" | "approved_request". */
743
- initiation?: string;
744
- /** Additive (2026-09-17). The refund request INVO approved, or `null`. */
745
- refund_request_id?: string | null;
746
- /** Additive (2026-09-17). `true` when this refund cancelled the subscription. */
747
- subscription_canceled?: boolean;
748
- /**
749
- * Merchant of Record accounts only (card refunds): the REFUND receipt INVO issued to the
750
- * buyer. Absent on Open accounts, and while a refund is still pending.
751
- */
752
- receipt_number?: string;
753
- /** Merchant of Record only: link to the printable refund receipt page. */
754
- receipt_url?: string;
755
- [key: string]: unknown;
756
- }
757
- /**
758
- * `subscription.refund_requested`: a refund over your game's daily self-serve limit became a
759
- * refund request (your `/refund` call answered 202 `pending_approval`). Nothing has moved.
760
- * Not the common subscription block: it describes the request.
761
- */
762
- interface SubscriptionRefundRequestData {
763
- /** `SRR...`. */
764
- request_id: string;
765
- /** "pending" | "approved" | "rejected". */
766
- status: string;
767
- subscription_id: string;
768
- item_id: string;
769
- period_seq: number;
770
- client_request_id: string;
771
- /** The amount asked for. */
772
- amount_usd: string;
773
- /** Your reason, or `null` when you sent none. */
774
- reason: string | null;
775
- requested_at: string;
776
- daily_cap_usd: string;
777
- executed_today_usd: string;
778
- player_email: string | null;
779
- identity_id: string | null;
780
- metadata: Record<string, unknown> | null;
781
- [key: string]: unknown;
782
- }
783
- /**
784
- * `subscription.refund_approved`: INVO approved the request and the refund ran;
785
- * `subscription.refunded` (and `subscription.canceled` on a full refund) are sent in the same
786
- * step and may arrive before or after this event. A retry of your `clientRequestId` now returns the receipt.
787
- */
788
- interface SubscriptionRefundApprovedData extends SubscriptionRefundRequestData {
789
- decided_at: string;
790
- /** The refund transaction. */
791
- transaction_id: string;
792
- }
793
- /**
794
- * `subscription.refund_rejected`: INVO rejected the request; nothing moved. Your
795
- * `clientRequestId` now answers `409 REFUND_REQUEST_REJECTED`; use a new one to try again.
796
- */
797
- interface SubscriptionRefundRejectedData extends SubscriptionRefundRequestData {
798
- decided_at: string;
799
- decision_reason: string | null;
800
- }
801
- type PurchaseEventType = "purchase.failed" | "purchase.refunded" | "purchase.disputed" | "purchase.fraud_warning";
802
- type TransferEventType = "transfer.sent" | "transfer.received" | "transfer.claim_pending" | "transfer.claim_expired" | "transfer.refunded";
803
- /**
804
- * A verified webhook event. Discriminate on `event_type` to narrow `data`.
805
- * Unknown/future event types fall through to the generic member (data is a record).
806
- */
807
- type InvoWebhookEvent = (WebhookBase & {
808
- event_type: "purchase.completed";
809
- data: PurchaseCompletedData;
810
- }) | (WebhookBase & {
811
- event_type: "item.purchased";
812
- data: ItemPurchasedData;
813
- }) | (WebhookBase & {
814
- event_type: "platform_commerce.purchased";
815
- data: PlatformCommercePurchasedData;
816
- }) | (WebhookBase & {
817
- event_type: "platform_commerce.refunded";
818
- data: PlatformCommerceRefundedData;
819
- }) | (WebhookBase & {
820
- event_type: PurchaseEventType;
821
- data: PurchaseEventData;
822
- }) | (WebhookBase & {
823
- event_type: TransferEventType;
824
- data: TransferEventData;
825
- }) | (WebhookBase & {
826
- event_type: "subscription.renewed";
827
- data: SubscriptionRenewedData;
828
- }) | (WebhookBase & {
829
- event_type: "subscription.payment_failed";
830
- data: SubscriptionPaymentFailedData;
831
- }) | (WebhookBase & {
832
- event_type: "subscription.past_due";
833
- data: SubscriptionPastDueData;
834
- }) | (WebhookBase & {
835
- event_type: "subscription.authentication_required";
836
- data: SubscriptionAuthenticationRequiredData;
837
- }) | (WebhookBase & {
838
- event_type: "subscription.canceled";
839
- data: SubscriptionCanceledData;
840
- }) | (WebhookBase & {
841
- event_type: "subscription.expired";
842
- data: SubscriptionExpiredData;
843
- }) | (WebhookBase & {
844
- event_type: "subscription.refunded";
845
- data: SubscriptionRefundedData;
846
- }) | (WebhookBase & {
847
- event_type: "subscription.refund_requested";
848
- data: SubscriptionRefundRequestData;
849
- }) | (WebhookBase & {
850
- event_type: "subscription.refund_approved";
851
- data: SubscriptionRefundApprovedData;
852
- }) | (WebhookBase & {
853
- event_type: "subscription.refund_rejected";
854
- data: SubscriptionRefundRejectedData;
855
- }) | (WebhookBase & {
856
- event_type: "payout.status_changed";
857
- data: PayoutStatusChangedData;
858
- }) | (WebhookBase & {
859
- event_type: "payee.status_changed";
860
- data: PayeeStatusChangedData;
861
- }) | (WebhookBase & {
862
- event_type: "player.phone_changed";
863
- data: PlayerPhoneChangedData;
864
- }) | (WebhookBase & {
865
- event_type: "identity.passkey_reset";
866
- data: IdentityPasskeyResetData;
867
- }) | (WebhookBase & {
868
- event_type: "webhook.test";
869
- data: Record<string, unknown>;
870
- }) | (WebhookBase & {
871
- event_type: string;
872
- data: Record<string, unknown>;
873
- });
874
- /**
875
- * Verify an Invo webhook and return the parsed, typed event. **Synchronous; uses
876
- * `node:crypto`** — for non-Node runtimes (Cloudflare Workers, Deno, Vercel/Netlify
877
- * Edge, Bun edge) use {@link verifyWebhookAsync}.
878
- *
879
- * @param rawBody The exact raw request body (bytes or string) — never a re-serialized object.
880
- * @param signatureHeader The `X-Invo-Signature` header value.
881
- * @param secret Your signing secret, or an array (to accept old + new during rotation).
882
- * @throws InvoError (status 0): WEBHOOK_SIGNATURE_MISSING | WEBHOOK_SECRET_MISSING |
883
- * WEBHOOK_TIMESTAMP_EXPIRED | WEBHOOK_SIGNATURE_INVALID | WEBHOOK_MALFORMED.
884
- */
885
- declare function verifyWebhook(rawBody: string | Uint8Array, signatureHeader: string | null | undefined, secret: string | string[], opts?: VerifyWebhookOptions): InvoWebhookEvent;
886
- /**
887
- * Cross-runtime async variant of {@link verifyWebhook}. Uses the Web Crypto API
888
- * (`crypto.subtle`) instead of `node:crypto`, so it works on Cloudflare Workers,
889
- * Deno, Vercel/Netlify Edge, Bun, and modern browsers (as well as Node ≥ 18).
890
- * Same arguments, errors, and return value — just `await` it.
891
- */
892
- declare function verifyWebhookAsync(rawBody: string | Uint8Array, signatureHeader: string | null | undefined, secret: string | string[], opts?: VerifyWebhookOptions): Promise<InvoWebhookEvent>;
893
- interface WebhookHandlerOptions {
894
- /** Signing secret, or an array to accept old + new during rotation. */
895
- secret: string | string[];
896
- /** Called with the verified, typed event after the signature passes. De-dupe on
897
- * `ctx.idempotencyKey`. Throw to return a 500 (Invo will retry). */
898
- onEvent: (event: InvoWebhookEvent, ctx: {
899
- idempotencyKey: string | null;
900
- request: Request;
901
- }) => void | Promise<void>;
902
- /** Optional: handle a verification failure. Return a Response to override the default 400. */
903
- onError?: (error: InvoError, request: Request) => void | Response | Promise<void | Response>;
904
- /** Replay tolerance (seconds). Default 300. */
905
- toleranceSec?: number;
906
- }
907
- /**
908
- * Build a webhook route handler from the Fetch API `(Request) => Promise<Response>` —
909
- * works in Next.js App Router route handlers, Cloudflare Workers, Deno, Hono, and Bun.
910
- * It reads the raw body, verifies with {@link verifyWebhookAsync}, and on success calls
911
- * `onEvent` with the typed event and the idempotency key (de-dupe is yours). Verification
912
- * failures return `400`; a throwing `onEvent` returns `500` so Invo retries.
913
- *
914
- * ```ts
915
- * // app/invo/webhooks/route.ts (Next.js)
916
- * export const POST = createWebhookHandler({
917
- * secret: process.env.INVO_WEBHOOK_SECRET!,
918
- * onEvent: async (event, { idempotencyKey }) => { await grantValue(event); },
919
- * });
920
- * ```
921
- */
922
- declare function createWebhookHandler(opts: WebhookHandlerOptions): (request: Request) => Promise<Response>;
923
-
924
- /**
925
- * Partner payouts and creator payouts (3.25.0).
926
- *
927
- * A platform partner can ask INVO to pay out the earnings INVO owes it, and can register
928
- * creators that INVO verifies and pays directly, as INVO's own payees. Creators are INVO's
929
- * customers: you never see their documents, tax id or bank details, only their status and
930
- * the details you registered. Server only: these calls use your game secret key.
931
- *
932
- * Fields keep the server's snake_case names, exactly as the API returns them.
933
- */
934
-
935
- interface Payee {
936
- /** Opaque id, `cp_` followed by 24 hex characters. Store it as a string. */
937
- payee_id: string;
938
- game_id: number | string;
939
- partner_reference: string;
940
- legal_name: string;
941
- email: string;
942
- country: string;
943
- payee_type: "individual" | "business" | (string & {});
944
- status: PayeeStatus;
945
- created_via: "api" | "console" | (string & {});
946
- status_changed_at: string | null;
947
- created_at: string | null;
948
- updated_at: string | null;
949
- /** 3.26.0. `true` once the creator's details were erased; such a creator can't be invited or paid. */
950
- erased?: boolean;
951
- /** 3.26.1. `true` when nothing on INVO's side stops a payout to this creator right now. */
952
- payable?: boolean;
953
- /** 3.26.1. Why `payable` is false: see {@link PayableBlocker}. Empty when payable. */
954
- payable_blockers?: PayableBlocker[];
955
- [key: string]: unknown;
956
- }
957
- /** 3.26.1. `not_payable_now`: no action is needed from you; try again later. */
958
- type PayableBlocker = "erased" | "closed" | "not_verified" | "verification_expired" | "terms_not_accepted" | "bank_not_verified" | "not_payable_now" | (string & {});
959
- interface PayeeInvite {
960
- sent: boolean;
961
- expires_at?: string | null;
962
- error_code?: string;
963
- error?: string;
964
- }
965
- interface RegisterPayeeInput {
966
- /** Your own id for the creator: 1 to 128 of `A-Z a-z 0-9 . _ : @ -`, unique in your account. No personal data. */
967
- partnerReference: string;
968
- /** The creator's legal name, or the registered business name. */
969
- legalName: string;
970
- email: string;
971
- /** ISO 3166-1 alpha-2, for example `"GB"`. */
972
- country: string;
973
- payeeType: "individual" | "business";
974
- }
975
- interface RegisterPayeeResult {
976
- payee: Payee;
977
- /** Present on a new registration. */
978
- invite?: PayeeInvite;
979
- /** `true` when this `partnerReference` was already registered with the same details. */
980
- duplicate: boolean;
981
- raw: Record<string, unknown>;
982
- }
983
- interface ListPayeesQuery {
984
- limit?: number;
985
- offset?: number;
986
- status?: PayeeStatus;
987
- }
988
- interface ListPayeesResult {
989
- total: number;
990
- limit: number;
991
- offset: number;
992
- items: Payee[];
993
- raw: Record<string, unknown>;
994
- }
995
- interface Payout {
996
- id: number;
997
- game_id: number | string;
998
- status: PayoutStatus;
999
- requested_amount_usd: string | null;
1000
- offboarding_fee_pct?: string | null;
1001
- offboarding_fee_usd?: string | null;
1002
- offboarding_fee_cap_usd?: string | null;
1003
- net_payout_usd?: string | null;
1004
- /** On a creator payout, the creator INVO pays; `null` on a payout to your own bank. */
1005
- payee_id?: string | null;
1006
- /** `null` on a creator payout: INVO pays the creator's verified account. */
1007
- bank_account?: Record<string, unknown> | null;
1008
- client_request_id?: string | null;
1009
- paid_at?: string | null;
1010
- returned_at?: string | null;
1011
- /** On `returned`: the bank's reason for a payout to your own bank; always `"returned"` on a creator payout. */
1012
- return_reason_code?: ReturnReasonCode | null;
1013
- /** 3.26.0. A note INVO wrote for you, or `null`. */
1014
- partner_message?: string | null;
1015
- /**
1016
- * 3.26.0. `true` on the first payout to a creator registered with the game secret key: INVO
1017
- * approves it only after the account owner confirms it in the console.
1018
- */
1019
- owner_confirmation_required?: boolean;
1020
- owner_confirmed_at?: string | null;
1021
- created_at?: string | null;
1022
- [key: string]: unknown;
1023
- }
1024
- interface RequestPayoutInput {
1025
- /** USD, positive, at most two decimal places. */
1026
- amountUsd: string | number;
1027
- contactEmail: string;
1028
- /** Pay a verified creator. Send exactly one of `payeeId` or `bankAccountId`. */
1029
- payeeId?: string;
1030
- /** Pay your own verified bank account (id from the INVO console). */
1031
- bankAccountId?: number;
1032
- /** Idempotency key. Reuse it to retry the same request safely. */
1033
- clientRequestId?: string;
1034
- partnerNote?: string;
1035
- additionalEmails?: string[];
1036
- }
1037
- interface RequestPayoutResult {
1038
- payout: Payout;
1039
- /** `true` when `clientRequestId` matched an earlier request with the same amount and creator. */
1040
- duplicate: boolean;
1041
- raw: Record<string, unknown>;
1042
- }
1043
- interface ListPayoutsQuery {
1044
- limit?: number;
1045
- offset?: number;
1046
- status?: PayoutStatus;
1047
- /** Only this creator's payouts. */
1048
- payeeId?: string;
1049
- }
1050
- interface ListPayoutsResult {
1051
- total: number;
1052
- items: Payout[];
1053
- raw: Record<string, unknown>;
1054
- }
1055
- /** `InvoServer.payouts`: partner payouts and creator payouts. */
1056
- declare class PayoutsServer {
1057
- private readonly http;
1058
- private readonly auth;
1059
- constructor(http: Http, auth: AuthHeader);
1060
- /**
1061
- * Register a creator (`POST /api/partner-payees`). INVO emails the creator a link to INVO's
1062
- * own page to give INVO their identity, tax and bank details. `invite.sent` is `false` when
1063
- * INVO did not email the link (`invite.error_code` says why); the creator is registered
1064
- * either way. Refusals: `409 PARTNER_REFERENCE_CONFLICT`, `400 INVALID_INPUT`,
1065
- * `400 COUNTRY_NOT_SUPPORTED`.
1066
- */
1067
- registerPayee(input: RegisterPayeeInput, opts?: CallOptions): Promise<RegisterPayeeResult>;
1068
- /** This game's creators, newest first (`GET /api/partner-payees`). */
1069
- listPayees(q?: ListPayeesQuery, opts?: CallOptions): Promise<ListPayeesResult>;
1070
- /** One creator (`GET /api/partner-payees/{payeeId}`); `404 NOT_FOUND` if not this game's. */
1071
- getPayee(payeeId: string, opts?: CallOptions): Promise<Payee>;
1072
- /**
1073
- * Email the creator a new link (`POST /api/partner-payees/{payeeId}/resend-invite`); the old
1074
- * link stops working. Allowed while the creator is `invited`, `rejected` or `expired`
1075
- * (`409 INVITE_NOT_NEEDED` otherwise); `409 PAYEE_ERASED`; `429 INVITE_RATE_LIMITED` with
1076
- * `retry_after_seconds`. If INVO asked the creator to update their details, the resend sends
1077
- * INVO's update notice again. Never auto-retried.
1078
- */
1079
- resendPayeeInvite(payeeId: string, opts?: CallOptions): Promise<PayeeInvite>;
1080
- /**
1081
- * Remove a creator from your program (`POST /api/partner-payees/{payeeId}/remove`, 3.26.0).
1082
- * The status becomes `closed`. `409 PAYEE_HAS_PAYOUTS_IN_FLIGHT` while a payout to them is in
1083
- * progress, `409 ALREADY_CLOSED`, `409 PAYEE_NOT_CLOSABLE`. Not a block: the same person can
1084
- * be registered again under a new reference. Never auto-retried.
1085
- */
1086
- removePayee(payeeId: string, opts?: CallOptions): Promise<Payee>;
1087
- /**
1088
- * Ask INVO to pay out (`POST /api/partner-payouts/request`). Send exactly one of `payeeId`
1089
- * (INVO pays that verified creator's bank account) or `bankAccountId` (your own verified bank
1090
- * account). The money comes from the earnings INVO owes your game, and the payout fee is
1091
- * taken from the payout. Creator refusals: `404 PAYEE_NOT_FOUND`, `409 PAYEE_NOT_VERIFIED`,
1092
- * `409 PAYEE_VERIFICATION_EXPIRED`, `409 PAYEE_BANK_NOT_VERIFIED`, `409 PAYEE_CLOSED`,
1093
- * `409 PAYEE_TERMS_NOT_ACCEPTED` (the creator hasn't accepted INVO's current Payee Terms yet),
1094
- * `409 PAYEE_NOT_PAYABLE` (can't be paid right now; no action needed; try again later),
1095
- * `409 IDEMPOTENCY_KEY_REUSED`. The first payout to a creator registered with the game key
1096
- * carries `owner_confirmation_required: true`. Retried safely only when `clientRequestId` is
1097
- * set.
1098
- */
1099
- requestPayout(input: RequestPayoutInput, opts?: CallOptions): Promise<RequestPayoutResult>;
1100
- /** One payout (`GET /api/partner-payouts/{payoutId}`). */
1101
- getPayout(payoutIdValue: number, opts?: CallOptions): Promise<Payout>;
1102
- /** Your payouts (`GET /api/partner-payouts`), optionally one creator's (`payeeId`). */
1103
- listPayouts(q?: ListPayoutsQuery, opts?: CallOptions): Promise<ListPayoutsResult>;
1104
- /**
1105
- * Cancel a creator payout that is still `requested`
1106
- * (`POST /api/partner-payouts/{payoutId}/cancel`). Anything past `requested` is
1107
- * `409 PAYOUT_NOT_CANCELLABLE`; a payout to your own bank is `404 NOT_FOUND`.
1108
- */
1109
- cancelPayout(payoutIdValue: number, opts?: CallOptions): Promise<Payout>;
1110
- }
1111
-
1112
- /**
1113
- * @invonetwork/web-sdk/server — NODE entry.
1114
- *
1115
- * InvoServer holds the game secret and runs every server-side call: minting the
1116
- * short-lived player token for the browser, initiating sends/transfers, and the
1117
- * currency-purchase flow (hosted checkout + rail selector). The game secret must
1118
- * NEVER reach the browser.
1119
- *
1120
- * All endpoints here authenticate with the `X-Game-Secret-Key` header.
1121
- */
1122
-
1123
- /**
1124
- * Platform Commerce — the ECOMMERCE surface (server side). A PLATFORM tenant (a non-game
1125
- * app: vertical video, creator merch, marketplace) sells items funded by INVO balance OR a
1126
- * real card, with full refunds (the seller of record depends on the account tier). This is NOT item purchase
1127
- * (§4.8) — that is a GAME tenant spending a player's existing game currency on an in-game
1128
- * item (balance only, no card, no refund). Different endpoints, different fee, different
1129
- * settlement. Reached as `invo.platformCommerce.*`.
1130
- */
1131
- declare class PlatformCommerceServer {
1132
- private readonly http;
1133
- private readonly auth;
1134
- constructor(http: Http, auth: AuthHeader);
1135
- /**
1136
- * Create a purchase. The funding source is resolved server-side under lock — the client
1137
- * can request `"balance"` or `"card"`, but the backend verifies the real balance before
1138
- * value moves.
1139
- *
1140
- * - `fundingSource: "balance"` → settles synchronously; result `status:"success"` with
1141
- * `newBalance`/`financialBreakdown`. `totalPrice` is the tenant's network-currency amount.
1142
- * - `fundingSource: "card"` → result `status:"requires_payment"` + `checkoutUrl`/`sessionId`.
1143
- * Send the buyer to `checkoutUrl` — INVO's hosted page owns the card form, wallets,
1144
- * billing address, and 3-D Secure (there is NO billing address in this request, and no
1145
- * client payment code to write; optionally embed via
1146
- * `InvoClient.platformCommerce.mountCheckout`). `totalPrice` is USD, at least $0.50;
1147
- * the maximum is an INVO setting ($100,000.00 by default) and is enforced on the
1148
- * request, not here, so read the live figure off `ABOVE_CARD_MAXIMUM` rather than
1149
- * pinning one.
1150
- * The sale is real only on the `platform_commerce.purchased` webhook — never on the
1151
- * client return.
1152
- *
1153
- * Idempotency on `clientRequestId`: the balance leg throws a 409
1154
- * (`err.isDuplicateRequest`) on a duplicate; the card leg REPLAYS the same checkout
1155
- * session (`idempotentReplay: true`) — a lost response is safely recovered by retrying
1156
- * with the SAME `clientRequestId`. A non-platform tenant throws
1157
- * `err.isNotPlatformTenant` (403).
1158
- */
1159
- purchase(input: PlatformPurchaseInput, opts?: CallOptions): Promise<PlatformPurchaseResult>;
1160
- /** Poll an order's status: `completed` (balance immediately; card after the webhook),
1161
- * `pending_payment` (card awaiting confirmation), or `refunded`. */
1162
- getStatus(orderId: string | number, opts?: CallOptions): Promise<PlatformOrderStatusResult>;
1163
- /**
1164
- * One player's Platform Commerce purchases in your app, newest first, one page at a time
1165
- * (`GET /api/platform-commerce/purchase-history`). Each entry carries exactly the fields
1166
- * `getStatus` returns for that order (including `receiptNumber` / `receiptUrl` on a
1167
- * Merchant of Record card sale once issued). Pass `nextCursor` back as `cursor` for the
1168
- * next page; it is `null` on the last one. `iteratePurchaseHistory` walks every page.
1169
- *
1170
- * Refusals (`InvoError`; this route reports its code in `error_code`, surfaced as
1171
- * `err.code`): a blank `playerEmail` or a bad `limit` / `cursor` throws `INVALID_INPUT`
1172
- * before the network; `400 INVALID_INPUT`, `400 INVALID_CURSOR` (a cursor from another
1173
- * player), `404 PLAYER_NOT_FOUND` (`err.isPlayerNotFound`), `403` for a non-platform
1174
- * tenant (`err.isNotPlatformTenant`), `429` (back off; `err.retryAfter`). A GET, so
1175
- * transient failures are retried automatically.
1176
- */
1177
- getPurchaseHistory(query: PlatformPurchaseHistoryQuery, opts?: CallOptions): Promise<PlatformPurchaseHistoryResult>;
1178
- /**
1179
- * Async iterator over ALL of a player's Platform Commerce purchases, newest first: pages
1180
- * through `getPurchaseHistory` by `nextCursor`, yielding one order at a time.
1181
- *
1182
- * ```ts
1183
- * for await (const order of invo.platformCommerce.iteratePurchaseHistory({ playerEmail })) { … }
1184
- * ```
1185
- */
1186
- iteratePurchaseHistory(query: {
1187
- playerEmail: string;
1188
- pageSize?: number;
1189
- }, opts?: CallOptions): AsyncGenerator<PlatformOrderStatusResult, void, unknown>;
1190
- /**
1191
- * Refund a completed purchase. Provide EXACTLY ONE of `orderId` or `clientRequestId`.
1192
- * INVO retains its fee — the customer is made whole (balance re-credit or card refund)
1193
- * minus that fee. Idempotent on the order: a second refund throws a 409
1194
- * (`err.isAlreadyRefunded`) — treat that as "already done", not a failure.
1195
- */
1196
- refund(input: PlatformRefundInput, opts?: CallOptions): Promise<PlatformRefundResult>;
1197
- }
1198
- /**
1199
- * Subscriptions: INVO bills a member a fixed USD price on a fixed interval and grants
1200
- * your game's currency each period. You keep the entitlement; INVO keeps the clock, the
1201
- * charges, the retries, the events and the revenue split. Reached as
1202
- * `invo.subscriptions.*`. Two rails, fixed at creation: `card` (`create`) and `steam`
1203
- * (`steamInit` + `steamFinalize`).
1204
- *
1205
- * TWO CLOCKS. `currentPeriodEnd` is the billing window, a projection; `paidThrough` is
1206
- * what the member has actually paid for. Grant access from `paidThrough`. Renewals are
1207
- * reported by the `subscription.renewed` webhook (the source of truth for entitlement);
1208
- * only `subscription.expired` and `subscription.canceled` revoke it.
1209
- */
1210
- declare class SubscriptionsServer {
1211
- private readonly http;
1212
- private readonly auth;
1213
- constructor(http: Http, auth: AuthHeader);
1214
- /**
1215
- * Create a CARD-rail subscription. **Charges the first period before responding**
1216
- * (unless it is a trial), so expect the call to take as long as a card charge.
1217
- *
1218
- * Branch on `result.firstCharge.status`: `paid` (grant until `paidThrough`),
1219
- * `requires_action` (NOTHING charged; send the member to `confirmationUrl`),
1220
- * `skipped_trial` (grant trial access until `subscription.trialEnd`), `failed` (in
1221
- * dunning; INVO retries at `nextRetryAt`), `pending` (wait for the event).
1222
- *
1223
- * Idempotent on `clientRequestId`: a repeat returns HTTP 200 with the identical shape
1224
- * and `idempotentReplay: true`, and NOTHING is charged again. **On any timeout or 5xx,
1225
- * replay the same key before you do anything else**; a fresh key inside a retry loop
1226
- * lands on `409 ACTIVE_SUBSCRIPTION_EXISTS` (`err.isActiveSubscriptionExists`,
1227
- * `err.existingSubscriptionId`) at best and a second subscription at worst. Same key
1228
- * with different terms is `err.isIdempotentReplayMismatch` (`err.mismatchedFields`).
1229
- *
1230
- * Card only (since 2026-09-17): the card is charged the full price every period and the
1231
- * member's coin wallet never pays and never moves. Card selection: `playerCardId` names one
1232
- * (from `cards.list`); omitted, INVO attaches the member's newest unexpired saved card. With
1233
- * no saved card the subscription is still created (201) but `firstCharge` is `failed` with
1234
- * `failureCode: "no_payment_method"`, whatever the member's balance: save a card first.
1235
- * `walletOnly: true` is deprecated: it never charges a card, so such a subscription can never
1236
- * be paid (`failureCode: "wallet_only"`).
1237
- *
1238
- * PAID TRIAL: send `trialAmountUsd` with `trialDays` or `trialEnd` (for example $1.00 for 7
1239
- * days, then `amountUsd` monthly). Period 1 is charged the trial price inside this call, so a
1240
- * usable saved card is required (`400 PAYMENT_METHOD_REQUIRED`, `err.isPaymentMethodRequired`),
1241
- * `firstCharge` reports the trial charge (never `skipped_trial`), and a refused trial charge
1242
- * ends the subscription at once (`expired`, no retry). Other refusals:
1243
- * `err.isTrialAmountRequiresTrial`, `err.isTrialAmountNotSupportedForFunding`,
1244
- * `err.isTrialAmountInvalid` (below $0.50, or not less than `amountUsd`),
1245
- * `err.isConsentDisclosedTrialInvalid`.
1246
- * Requires the game to be `live` (`err.isGameNotLive`).
1247
- */
1248
- create(input: CreateSubscriptionInput, opts?: CallOptions): Promise<SubscriptionResult>;
1249
- /** Read one subscription. `404 SUBSCRIPTION_NOT_FOUND` for an id that is not your game's. */
1250
- get(subscriptionId: string, options?: GetSubscriptionOptions, opts?: CallOptions): Promise<GetSubscriptionResult>;
1251
- /**
1252
- * List a member's subscriptions, newest first, paged (`limit` 1..100, `offset`
1253
- * 0..100000). `status` filters; `"live"` expands to the four live statuses and may be
1254
- * mixed in (`["live", "canceled"]`). A player who does not exist yet is an empty list
1255
- * with `totalCount: 0`, not a 404.
1256
- */
1257
- listForPlayer(playerEmail: string, options?: ListSubscriptionsOptions, opts?: CallOptions): Promise<SubscriptionListResult>;
1258
- /**
1259
- * Cancel. `atPeriodEnd` defaults to `true`: the subscription stays live with
1260
- * `cancelAtPeriodEnd: true` and is retired at `paidThrough` without another charge.
1261
- * If nothing has been paid (or the paid window has elapsed) an at-period-end cancel is
1262
- * **downgraded to immediate**: read `terminatedImmediately`. `atPeriodEnd: false` ends
1263
- * it now. Revoke access at `accessUntil`.
1264
- *
1265
- * Cancelling an already-terminal subscription is a 200 with `alreadyCanceled: true`
1266
- * (never thrown), so a batch reconciler needs no special case; that is also what makes
1267
- * a lost-response retry safe. One `subscription.canceled` event fires at request time.
1268
- * Never blocked by a maintenance pause.
1269
- */
1270
- cancel(subscriptionId: string, options?: CancelSubscriptionOptions, opts?: CallOptions): Promise<CancelResult>;
1271
- /**
1272
- * Stage a price change. Applied on the NEXT successful renewal (the current window is
1273
- * billed at the old price first; no proration). Sending the current price clears a
1274
- * staged change (`changeQueued: false`). The billed price appears on that period's
1275
- * `subscription.renewed`; there is no `amount_changed` event.
1276
- *
1277
- * Steam: an increase is refused (`err.isSteamReauthorizationRequired`; start a new
1278
- * Steam subscription at the new price), a decrease stages. An increase to more than
1279
- * double the last agreed price, or above 25000.00, is staged but never applied: raise
1280
- * prices in steps. `err.isSubscriptionTerminal` on a canceled/expired row.
1281
- */
1282
- changeAmount(subscriptionId: string, amountUsd: string | number, opts?: CallOptions): Promise<ChangeAmountResult>;
1283
- /**
1284
- * Card subscriptions only. Attach a card (`{ playerCardId }`, an `id` from
1285
- * `cards.list` belonging to this player, unexpired) or make the subscription wallet-only
1286
- * (`{ walletOnly: true }`, deprecated: a wallet-only card subscription can never be paid).
1287
- * On a wallet-only subscription pass `walletOnly: false` beside the card to convert it
1288
- * back. The new card is used from the next charge, including a pending retry in dunning.
1289
- *
1290
- * `err.isNotACardSubscription` on Steam; `err.isSubscriptionTerminal` on a terminal row.
1291
- */
1292
- setPaymentMethod(subscriptionId: string, input: SetPaymentMethodInput, opts?: CallOptions): Promise<SetPaymentMethodResult>;
1293
- /**
1294
- * Refund a billed period (card rail). Idempotent on `clientRequestId`: a repeat returns
1295
- * the stored receipt with `idempotentReplay: true` and moves nothing.
1296
- *
1297
- * **Branch on `status`.** `"refunded"` (HTTP 200): the refund ran. `"pending_approval"`
1298
- * (HTTP 202): the refund would exceed the game's daily self-serve limit per UTC day (by
1299
- * default never lower than the largest single subscription charge, so a single period
1300
- * always runs unless INVO set a lower limit for the game), NOTHING moved, and INVO reviews it as a refund request (`requestId`); the
1301
- * outcome arrives as `subscription.refund_approved` (sent together with
1302
- * `subscription.refunded`, and `subscription.canceled` on a full refund, in any order) or
1303
- * `subscription.refund_rejected`. The 202 carries every receipt field with nothing moved
1304
- * (`refundedAmountUsd` is `"0.00"`; `totalRefundedAmountUsd` and `remainingRefundableUsd`
1305
- * carry the period's real values). Check it with {@link isRefundPendingApproval}.
1306
- *
1307
- * A card-only period (every card period charged since 2026-09-17) is refunded in cash, full
1308
- * or partial: `cardRefundedUsd` equals the amount and `balanceDeltaCoins` is `"0.00"`. A
1309
- * period charged before that keeps the earlier rule: a full refund returns the card charge
1310
- * and reclaims the coins it minted (`balanceDeltaCoins` is signed), a partial refund
1311
- * credits coins. Your revenue is reversed for the refunded portion
1312
- * (`partnerRevenueReversedUsd`), INVO's fee is retained, and on a card refund you bear the
1313
- * whole refunded amount, INVO's card fee included (`cardFeeChargedToPartnerUsd`;
1314
- * `partnerDebitedUsd` is the sum; since 2026-09-28, with no separate processor fee:
1315
- * `processingFeeUsd` reads `"0.00"`). **A full refund
1316
- * cancels the subscription** (`subscriptionCanceled`, and a `subscription.canceled` event
1317
- * with `cancel_cause: "full_refund"`, sent together with `subscription.refunded` in any
1318
- * order); a partial one does not. INVO emails the member.
1319
- * Refunds run within 30 days of the period's charge. Send a `reason`: it is recommended now
1320
- * and will be required later (`warnings` says so when it is missing).
1321
- *
1322
- * Refusals: `err.isRefundsNotEnabled` (403), `err.isRefundWindowClosed` (409),
1323
- * `err.isRefundRequestPending` (409, `err.refundRequestId`), `err.isRefundRequestRejected`
1324
- * (409, use a new key), `err.isConcurrentRequest` (409, retry with the same key),
1325
- * `err.isRefundMismatch` (502, contact INVO), `NO_PAID_PERIOD` (409, nothing collected yet),
1326
- * `PERIOD_NOT_REFUNDABLE`, `ALREADY_REFUNDED` (`err.isAlreadyRefunded`),
1327
- * `AMOUNT_EXCEEDS_REMAINING` (body carries `remaining_refundable_usd`),
1328
- * `err.isSteamRefundNotSupported`, `err.isFlowPaused`.
1329
- */
1330
- refund(subscriptionId: string, input: RefundSubscriptionInput, opts?: CallOptions): Promise<RefundResult>;
1331
- /**
1332
- * Start a STEAM-rail subscription: creates it in `pending_steam_authorization`, opens
1333
- * period 1 for the full price and starts the Steam authorisation. Nothing is charged
1334
- * until the member authorises and you call {@link steamFinalize}. Idempotent on
1335
- * `clientRequestId`; a replay answers with the row's CURRENT status (which may already
1336
- * be `active`, `canceled` or `expired`).
1337
- *
1338
- * `userSession: "client"` (default): the Steam overlay presents the authorisation inside
1339
- * the game; match the Steam client callback's `order_id` against `steamOrderId` (never
1340
- * `steamTransid`). `"web"`: open `steamCheckoutUrl` as a TOP-LEVEL window (it cannot be
1341
- * framed); requires `playerIp`, the MEMBER's address. Show `amountCoins`: what one
1342
- * period is worth for THIS member depends on their country and is fixed at init.
1343
- *
1344
- * A pending authorisation for the same player and item with the SAME terms is handed
1345
- * back (`pendingReuse: true`, no new agreement): finalize that one. With DIFFERENT
1346
- * terms the call throws `409 STEAM_AUTHORIZATION_PENDING` (`err.isSteamAuthorizationPending`,
1347
- * `err.existingSubscriptionId`): finalize or cancel the pending one first.
1348
- *
1349
- * Not available on Steam, refused before the network: trials, `walletOnly`, card
1350
- * fields, `intervalCount` other than 1. Backend refusals worth branching on:
1351
- * `err.isSteamChannelRequired` (409, wrong channel key), `err.isActiveSubscriptionExists`,
1352
- * `err.isSteamRailNotEntitled` (403), `err.isSteamNotConfigured` (503),
1353
- * `err.isPartnerBillingNotSetUp` / `isPartnerSettlementUnavailable` (409),
1354
- * `AMOUNT_TOO_SMALL_FOR_STEAM` (400). When a Steam-side failure abandons the row after
1355
- * creation the body carries the abandoned `subscription_id`; retry with a NEW key.
1356
- */
1357
- steamInit(input: SteamSubscriptionInitInput, opts?: CallOptions): Promise<SteamInitResult>;
1358
- /**
1359
- * Finalize a Steam subscription after the member has authorised: INVO verifies with
1360
- * Steam, captures period 1, records the agreement and settles period 1 exactly as a
1361
- * renewal. Idempotent: a repeat returns `alreadyProcessed: true` with
1362
- * `idempotentReplay: true` (treat as success; never thrown).
1363
- *
1364
- * **Finalize is your call.** Steam does not tell INVO the member authorised; call this
1365
- * after the overlay or checkout closes, and again if it threw `err.isNotAuthorized`
1366
- * (409 `status: "not_authorized"`: the normal wait state). The member has 24 hours.
1367
- * A 200 with `warning` means Steam charged but period 1 could not settle in one step:
1368
- * the money is taken, do not retry the charge, watch for `subscription.renewed`.
1369
- * In sandbox this does not call Steam (`sandboxAutoApproved: true`).
1370
- *
1371
- * Other refusals: `err.isSubscriptionTerminal`, `NOT_A_STEAM_SUBSCRIPTION`,
1372
- * `NO_STEAM_AUTHORIZATION`, `err.isSteamAppChanged` (409); 502/503 are transient.
1373
- */
1374
- steamFinalize(subscriptionId: string, opts?: CallOptions): Promise<SteamFinalizeSubscriptionResult>;
1375
- }
1376
- /**
1377
- * Saved cards for off-session (recurring) use: the card capture a card subscription
1378
- * needs. Reached as `invo.cards.*`. The subscription endpoints never receive card data
1379
- * and neither does this SDK.
1380
- *
1381
- * THE RECOMMENDED CAPTURE IS {@link createSetupSession}: INVO hosts the card page, you
1382
- * mint a link server-side and send the member to it, and nothing in your integration
1383
- * references a card processor or loads its script. {@link beginSetup} /
1384
- * {@link confirmSetup} are the processor-bound alternative for a partner who already
1385
- * runs a card form in their own client against INVO's current processor.
1386
- *
1387
- * A card saved through the hosted CHECKOUT page, or through a `savedCardId` purchase,
1388
- * does NOT carry the off-session consent a subscription needs; capture it here (or with
1389
- * a `purchaseCurrency` that sets `save_card: true`).
1390
- */
1391
- declare class CardsServer {
1392
- private readonly http;
1393
- private readonly auth;
1394
- constructor(http: Http, auth: AuthHeader);
1395
- /**
1396
- * Mint a short-lived session for the INVO-hosted card page and return its URL. THE
1397
- * RECOMMENDED WAY TO SAVE A CARD FOR A SUBSCRIPTION: two server-to-server calls (this
1398
- * one, then `cards.list`) and one redirect. No browser code, no processor script, no
1399
- * client secret; INVO can change card processor without you changing anything.
1400
- *
1401
- * A member this game already knows needs only `playerEmail`. A BRAND-NEW member (a
1402
- * first-time signup, for example before a paid trial) is created here when you also
1403
- * send `playerName` (and optionally `playerPhone`), exactly as `subscriptions.create`
1404
- * creates one: same phone-share gate, same wallet binding. Without `playerName` an
1405
- * unknown member is `err.isPlayerNotFound` (404) and nothing is created. A known member
1406
- * is never re-created or renamed by this call; `playerName` / `playerPhone` are used
1407
- * only when the member is new. Send the member to `result.cardSetupUrl` top-level (do
1408
- * not frame it). The page says in words that no money moves, saves the card, and then
1409
- * redirects to `successUrl` (or shows "Card saved" when you gave none). The saved card
1410
- * appears in {@link list} immediately, carries the off-session consent a subscription
1411
- * needs, and is indistinguishable from one saved any other way. There is no event for
1412
- * a saved card; `cards.list` is the signal.
1413
- *
1414
- * The session lives 10 minutes (entering a card is one sitting); mint it when the
1415
- * member is about to use it. The link may be reloaded freely before the save; once the
1416
- * card is saved the link is spent and reopening it returns the same card again.
1417
- * `successUrl` is redirected to verbatim (nothing appended) and `metadata` is stored on
1418
- * the session and not returned anywhere today, so put your own correlation id in
1419
- * `successUrl`.
1420
- *
1421
- * Refusals: `err.isInvalidPlayerEmail` (400, a non-email string; a missing or blank
1422
- * `playerEmail` is refused here first with `status: 0`), `err.isPlayerNotFound` (404),
1423
- * `err.isInvalidInput` (400: a script-scheme `successUrl` / `cancelUrl`, or, when the
1424
- * member is new, a `playerName` over 255 characters or a `playerPhone` over 30; the SDK
1425
- * refuses script schemes, a blank or over-long `playerName` and a non-E.164
1426
- * `playerPhone` first with `status: 0`), `err.isPhoneShareApprovalRequired` (409, creating the member needs the
1427
- * existing phone owner's approval; same body as `subscriptions.create`),
1428
- * `err.isPlayerCreateFailed` (503, the member could not be created; call again),
1429
- * 401 / 403 on the key or the game (body `{ message }`, no code), 503 when card setup
1430
- * is not available right now. Never auto-retried: each call mints a fresh link, so on a
1431
- * timeout call it again.
1432
- */
1433
- createSetupSession(input: CardSetupSessionInput, opts?: CallOptions): Promise<CardSetupSessionResult>;
1434
- /**
1435
- * THE PROCESSOR-BOUND ALTERNATIVE to {@link createSetupSession}. Use it only if you
1436
- * already run a card form in your own client against INVO's current card processor:
1437
- * the `clientSecret` it hands back can only be consumed by that processor's client
1438
- * library, so the browser code you write for it will need rework when INVO changes
1439
- * processor. `createSetupSession` does not have that problem.
1440
- *
1441
- * Begin saving a card (charges nothing). The player must already exist in this game
1442
- * (`404 PLAYER_NOT_FOUND`). Idempotent on `setupReference`: resend the same value on a
1443
- * retry and you get the same setup back (`409 SETUP_REFERENCE_REUSED` if you reuse it
1444
- * with different parameters).
1445
- *
1446
- * With `paymentMethodId` (a card tokenised on the client) INVO confirms server-side
1447
- * and answers `succeeded` with the `card`, or `requires_action` with a `clientSecret`
1448
- * for the card form to run the cardholder authentication. Without it, INVO answers
1449
- * `requires_confirmation` / `requires_payment_method` with a `clientSecret`: confirm on
1450
- * the client, then call {@link confirmSetup}. Send tokens only, never raw card numbers
1451
- * (`RAW_CARD_NOT_SUPPORTED`).
1452
- */
1453
- beginSetup(input: CardSetupInput, opts?: CallOptions): Promise<CardSetupResult>;
1454
- /**
1455
- * The second half of the processor-bound alternative (see {@link beginSetup}); not
1456
- * needed on the {@link createSetupSession} path, where INVO's page completes the save.
1457
- *
1458
- * Finish a client-confirmed setup and save the card. Idempotent on `setupIntentId`.
1459
- * While the client has not finished, this throws a 400 with body
1460
- * `status: "still_requires_action"`. On `500 CARD_PERSIST_FAILED` (authorised but not
1461
- * recorded) retry this call with the same `setupIntentId`.
1462
- */
1463
- confirmSetup(input: CardSetupConfirmInput, opts?: CallOptions): Promise<CardSetupConfirmResult>;
1464
- /**
1465
- * A member's unexpired saved cards, newest first. An unknown player is `{ cards: [] }`.
1466
- * The `id` is the value you pass as `playerCardId`; INVO never returns processor
1467
- * identifiers for a card. Served from a short cache (about 60 s); a card saved through
1468
- * the hosted card page (`createSetupSession`) or through `beginSetup` / `confirmSetup`
1469
- * appears immediately. This read is the signal that the hosted page saved a card.
1470
- */
1471
- list(playerEmail: string, opts?: CallOptions): Promise<PlayerCardsResult>;
1472
- }
1473
- /**
1474
- * Sandbox-only clock tools for subscriptions. Reached as `invo.sandbox.subscriptions.*`.
1475
- *
1476
- * **Path note.** These four endpoints live DIRECTLY under the sandbox base, not under
1477
- * `/api`: the full URL is `https://sandbox.invo.network/sandbox/subscriptions/<id>/advance-clock`.
1478
- * Because `baseUrl` already ends in `/sandbox`, this class posts to
1479
- * `/subscriptions/<id>/...` relative to it. They do not exist in production (404).
1480
- *
1481
- * **Second credential.** Every call sends `X-Game-Secret-Key` AND `X-Sandbox-Clock-Key`
1482
- * (`new InvoServer({ ..., sandboxClockKey })`, from the sandbox console: open the game,
1483
- * Game Settings, "Sandbox clock key"). A missing key throws `INVALID_INPUT` before the
1484
- * network; a wrong one is `401 SANDBOX_CLOCK_UNAUTHORIZED` (`err.isSandboxClockUnauthorized`).
1485
- * None of these calls is auto-retried: each one moves the clock or runs the engine.
1486
- */
1487
- declare class SandboxSubscriptionsServer {
1488
- private readonly http;
1489
- private readonly auth;
1490
- private readonly clockKey;
1491
- constructor(http: Http, auth: AuthHeader, clockKey: string | undefined);
1492
- private call;
1493
- /**
1494
- * Make the next period due now. `intervals` 0..60, default 1. `0` makes it due without
1495
- * moving the window (use it to trigger a retry). `N` on a never-paid subscription
1496
- * (a trial, a fresh row) also moves the window back by up to N intervals; once anything
1497
- * has been paid the window stays put (`intervalsAppliedToWindow: 0`). No window is ever
1498
- * billed twice. Then `forceRenewal`, or wait for the next sweep (within a minute or two).
1499
- * `409 SUBSCRIPTION_NOT_LIVE` on a terminal or pending row.
1500
- */
1501
- advanceClock(subscriptionId: string, intervals?: number, opts?: CallOptions): Promise<SandboxClockResult>;
1502
- /**
1503
- * Run the renewal immediately. **Charges the test card** (or the Steam stand-in): the
1504
- * real money path (card: the full price; Steam: wallet first, then the shortfall), mint,
1505
- * spend, split, `subscription.renewed`,
1506
- * and on failure the real dunning. Read `engineStats` (`renewed: 1` on success). A
1507
- * cancel-at-period-end row answers `action: "retired-at-period-end"`, `retired: true`.
1508
- * `409 PERIOD_TOO_FAR_AHEAD` means you forced twice without advancing the clock.
1509
- */
1510
- forceRenewal(subscriptionId: string, opts?: CallOptions): Promise<SandboxClockResult>;
1511
- /**
1512
- * Synthesise a failed attempt and run real dunning. No charge. `outcome` defaults to
1513
- * `card_declined`. Returns `retryBudgetUsed`, `retryScheduleDays` (e.g. `[2, 3, 2]`),
1514
- * `retriesRemaining`. Call it four times to walk `active` through `past_due` to `expired`
1515
- * and watch the events. Does not model a Steam refusal.
1516
- */
1517
- forceFailure(subscriptionId: string, outcome?: SandboxFailureOutcome, options?: SandboxForceFailureOptions, opts?: CallOptions): Promise<SandboxClockResult>;
1518
- /**
1519
- * Synthesise a cardholder authentication challenge: moves the subscription to
1520
- * `awaiting_authentication` (no charge). Returns `authChallengesUsed`,
1521
- * `maxAuthChallenges` (2) and `downgradedToDecline`. It does NOT mint a confirmation
1522
- * link; to exercise the link and the `subscription.authentication_required` event use a
1523
- * test card that requires authentication, then `forceRenewal`.
1524
- */
1525
- forceAuthChallenge(subscriptionId: string, options?: SandboxForceAuthChallengeOptions, opts?: CallOptions): Promise<SandboxClockResult>;
1526
- }
1527
- /** Sandbox-only tooling. Reached as `invo.sandbox.*`. Nothing here exists in production. */
1528
- declare class SandboxServer {
1529
- /** The four subscription clock tools. See {@link SandboxSubscriptionsServer}. */
1530
- readonly subscriptions: SandboxSubscriptionsServer;
1531
- constructor(http: Http, auth: AuthHeader, clockKey: string | undefined);
1532
- }
1533
- /**
1534
- * ## Storefront keys — one client per storefront
1535
- *
1536
- * A game that ships on more than one storefront (Steam, iOS, Android, web,
1537
- * console) has one SDK key per storefront. Construct one `InvoServer` per key
1538
- * and use whichever matches where the player is buying:
1539
- *
1540
- * ```ts
1541
- * const invo = {
1542
- * ios: new InvoServer({ gameSecret: process.env.INVO_KEY_IOS! }),
1543
- * android: new InvoServer({ gameSecret: process.env.INVO_KEY_ANDROID! }),
1544
- * web: new InvoServer({ gameSecret: process.env.INVO_KEY_WEB! }),
1545
- * };
1546
- * await invo[player.storefront].purchaseCurrency({ ... });
1547
- * ```
1548
- *
1549
- * **Do not pass `rail` when using a storefront key.** The key already
1550
- * determines it, and a conflicting `rail` is refused with
1551
- * `RAIL_CHANNEL_MISMATCH` rather than silently overridden — see
1552
- * {@link InvoError.isRailChannelMismatch}. A single legacy key with no
1553
- * storefront keeps working exactly as before, `rail` included.
1554
- *
1555
- * These are still **server-side** keys. A storefront key names where the
1556
- * purchase came from, not where the key lives; it never belongs in a game
1557
- * client, an app bundle, or browser code.
1558
- */
1559
- declare class InvoServer {
1560
- private readonly http;
1561
- private readonly auth;
1562
- /**
1563
- * Platform Commerce (ecommerce) — a PLATFORM tenant selling items funded by balance or
1564
- * card, with refunds. DISTINCT from `purchaseItem` (a game tenant spending existing game
1565
- * currency on an in-game item). See {@link PlatformCommerceServer}.
1566
- */
1567
- readonly platformCommerce: PlatformCommerceServer;
1568
- /**
1569
- * Subscriptions (recurring billing on the card rail or the Steam rail):
1570
- * `create` / `get` / `listForPlayer` / `cancel` / `changeAmount` / `setPaymentMethod` /
1571
- * `refund` / `steamInit` / `steamFinalize`. See {@link SubscriptionsServer}.
1572
- */
1573
- readonly subscriptions: SubscriptionsServer;
1574
- /** Saved-card capture for subscriptions: `beginSetup` / `confirmSetup` / `list`. See {@link CardsServer}. */
1575
- readonly cards: CardsServer;
1576
- /**
1577
- * Sandbox-only tooling: `sandbox.subscriptions.advanceClock` / `forceRenewal` /
1578
- * `forceFailure` / `forceAuthChallenge`. Needs `sandboxClockKey`. See {@link SandboxSubscriptionsServer}.
1579
- */
1580
- readonly sandbox: SandboxServer;
1581
- /**
1582
- * Partner payouts and creator payouts (3.25.0): `registerPayee` / `listPayees` /
1583
- * `getPayee` / `resendPayeeInvite` / `requestPayout` / `getPayout` / `listPayouts` /
1584
- * `cancelPayout`. See {@link PayoutsServer}.
1585
- */
1586
- readonly payouts: PayoutsServer;
1587
- constructor(config: ServerConfig);
1588
- /**
1589
- * Mint a short-lived, game-scoped player token to hand to the browser InvoClient.
1590
- *
1591
- * For a player who already exists in your game, this is a session mint: INVO looks the
1592
- * player up by `playerEmail` and returns a token for their identity. `playerPhone` and
1593
- * `playerName` do not change an existing player.
1594
- *
1595
- * For a player who is NOT in your game yet: without `playerPhone` INVO answers 404
1596
- * (`err.isPlayerNotFound`); with `playerPhone` INVO creates the player and the result
1597
- * carries `created: true`, so a first-time receiver can collect without buying first.
1598
- * Use `registerPlayer` when you want creation to be explicit.
1599
- *
1600
- * `phoneMismatch: true` means the existing player has a different phone than the one
1601
- * you passed; the token is still for that player and their phone is unchanged
1602
- * (`updatePlayerPhone` changes it). A phone already held by another email is a 409
1603
- * (`err.isPhoneShareRefused`).
1604
- */
1605
- mintPlayerToken(input: MintPlayerTokenInput, opts?: CallOptions): Promise<PlayerToken>;
1606
- /**
1607
- * Create a player in your game without moving money (`POST /api/sdk/players`), so a
1608
- * first-time receiver can collect in-game. Sends no message to the player.
1609
- *
1610
- * Returns `status: "created"` (new) or `"exists"` (already in your game with that
1611
- * phone), with a player token when INVO can issue one. Refusals: 409
1612
- * `err.isPhoneMismatch` (already in your game with a different phone; use
1613
- * `updatePlayerPhone`), 409 `err.isPhoneShareRefused` (the phone belongs to another
1614
- * email), 400 `INVALID_INPUT` / `INVALID_PHONE`, 429 (`err.retryAfter`).
1615
- */
1616
- registerPlayer(input: RegisterPlayerInput, opts?: CallOptions): Promise<RegisterPlayerResult>;
1617
- /**
1618
- * Set a player's phone from your server (`POST /api/sdk/players/phone`). A phone change
1619
- * can give the player a new INVO identity: `identityRekeyed: true`, and the result
1620
- * carries a fresh `playerToken` for it (tokens minted before the change are then out
1621
- * of date).
1622
- *
1623
- * Refusals: 409 `err.isPhoneChangeRequiresVerification` (the player has secured this
1624
- * account, so the change needs the player's own confirmation: call `requestPhoneChange`;
1625
- * `err.changeRequestEndpoint` names the route), 409 `err.isPhoneShareRefused` (the
1626
- * number belongs to another email), 409 `err.isPendingTransfersToOldPhone` /
1627
- * `err.isPendingTransfersToNewPhone` (transfers to the current or the new number are still
1628
- * waiting to be collected), 404 `err.isPlayerNotFound`, 400 `INVALID_INPUT` / `INVALID_PHONE`, 429
1629
- * (`err.retryAfter`), 503 (could not be checked right now; try again shortly).
1630
- *
1631
- * Never auto-retried: a retry after a change that landed would answer `"unchanged"` and
1632
- * hide `identityRekeyed`.
1633
- */
1634
- updatePlayerPhone(input: UpdatePlayerPhoneInput, opts?: CallOptions): Promise<UpdatePlayerPhoneResult>;
1635
- /**
1636
- * Ask the player to confirm a new phone number
1637
- * (`POST /api/sdk/players/phone/change-requests`, HTTP 202). Use it when `updatePlayerPhone`
1638
- * answers 409 `err.isPhoneChangeRequiresVerification`.
1639
- *
1640
- * Nothing about the player changes here. INVO emails the player a code and a link to a
1641
- * page on INVO's site, and the player confirms there (plus their passkey on that page, or
1642
- * an approval on their enrolled device, when they have one: see `confirmation`). Your game
1643
- * never collects the code and never receives the link: do not ask the player for it.
1644
- * Follow up with `getPhoneChange`, or wait for the `player.phone_changed` webhook.
1645
- *
1646
- * Refusals carry `err.code`, for example 409 `PHONE_SAME`, `PHONE_IN_USE_BY_ANOTHER_PLAYER`,
1647
- * `PENDING_TRANSFERS_TO_NEW_PHONE` (`err.isPendingTransfersToNewPhone`),
1648
- * `PENDING_TRANSFERS_TO_OLD_PHONE` (`err.isPendingTransfersToOldPhone`),
1649
- * `CHANGE_REQUEST_IN_PROGRESS` (`err.isChangeRequestInProgress`), `PHONE_CHANGE_LOCKED`
1650
- * (`err.isPhoneChangeLocked`), `PHONE_CHANGE_RECOVERY_COOLDOWN`
1651
- * (`err.isPhoneChangeRecoveryCooldown`), `STEP_UP_UNAVAILABLE`, `WALLET_SECURED`,
1652
- * `PHONE_NOT_SET`;
1653
- * 429 `err.isTooManyChangeRequests`; 404 `err.isPlayerNotFound`; 503
1654
- * `err.isPhoneChangeUnavailable`.
1655
- *
1656
- * Never auto-retried: a new request replaces your earlier pending one and sends the player
1657
- * another email.
1658
- */
1659
- requestPhoneChange(input: RequestPhoneChangeInput, opts?: CallOptions): Promise<RequestPhoneChangeResult>;
1660
- /**
1661
- * Read a change request your game created
1662
- * (`GET /api/sdk/players/phone/change-requests/{changeRequestId}`). `status` is `pending`,
1663
- * `confirmed`, `expired`, `cancelled`, `refused` or `denied`. A request another game
1664
- * created, or an unknown id, is 404 `err.isChangeRequestNotFound`. Poll sparingly, or wait
1665
- * for the `player.phone_changed` webhook.
1666
- */
1667
- getPhoneChange(changeRequestId: string, opts?: CallOptions): Promise<PhoneChangeRequest>;
1668
- /**
1669
- * Initiate a cross-game currency SEND. Inspect result.verificationMethod.
1670
- *
1671
- * Steam titles: can throw a 409 `err.isSteamValueNonTransferable` (moving more than the
1672
- * player's non-Steam balance to a non-Steam destination — cap at `err.steamTransferableMax`)
1673
- * or `err.isNonSteamValueIntoSteamBlocked` (non-Steam value into a Steam title). Prevent both
1674
- * up front with `DestinationGame.acceptsSteamOriginValue`.
1675
- */
1676
- initiateSend(input: InitiateSendInput, opts?: CallOptions): Promise<InitiateResult>;
1677
- /** Initiate a cross-game TRANSFER. Inspect result.verificationMethod. Can throw the same
1678
- * Steam-policy 409s as {@link initiateSend} (`isSteamValueNonTransferable` /
1679
- * `isNonSteamValueIntoSteamBlocked`). */
1680
- initiateTransfer(input: InitiateTransferInput, opts?: CallOptions): Promise<InitiateResult>;
1681
- /** Create a hosted checkout session (the recommended purchase path). Open the
1682
- * returned checkoutUrl in a WebView/redirect or an iframe; the INVO-hosted page
1683
- * handles cards, saved cards, and 3-D Secure. Crediting is server-side via the
1684
- * purchase.completed webhook. */
1685
- createCheckout(input: CreateCheckoutInput, opts?: CallOptions): Promise<CreateCheckoutResult>;
1686
- /**
1687
- * Direct purchase via the rail selector. Use when you need a specific rail.
1688
- * - rail "platform" (default): standard card. May return status "requires_action"
1689
- * (run client-side 3-D Secure with clientSecret, then call confirmPayment).
1690
- * - rail "game": returns status "pending_payment" + paymentUrl (redirect the browser).
1691
- * - rail "steam": NOT a browser flow — the backend returns WRONG_RAIL_ENDPOINT.
1692
- *
1693
- * INVO's card fee (3.5% + $0.30 on Open, 5.5% + $0.50 on Merchant of Record, plus 1.5% of
1694
- * the listed price (before tax) on a card issued outside the US) is charged to you, the partner. The player
1695
- * pays the listed price (plus any tax) and receives the listed coins. Card purchases only;
1696
- * purchases through a third-party storefront or payment rail are unaffected. Two shapes,
1697
- * chosen by what you send:
1698
- * - with `acknowledgedTotalUsd` (the `totalUsd` from {@link quoteCurrencyPurchase}): the
1699
- * card is never charged more than that total, and the coins are priced off `usdAmount`.
1700
- * An older, higher fee-inclusive total is accepted and the true, lower total charged. A
1701
- * total below what INVO would charge now throws `409 QUOTE_STALE` (`err.isQuoteStale`);
1702
- * nothing was charged.
1703
- * - without it: the card is charged exactly `usdAmount`, never more.
1704
- *
1705
- * From 2026-10-27 a card purchase under INVO's minimum card purchase ($2.99) throws
1706
- * `400 BELOW_CARD_MINIMUM` (`err.isBelowCardMinimum`, `err.minUsd`, `err.enforcedFrom`);
1707
- * until then it is accepted with `minPurchaseWarning`. `AMOUNT_BELOW_FEE` is no longer
1708
- * returned.
1709
- *
1710
- * A `success` result reports `processingFeeUsd` (`"0.00"`), `feeTakenFrom` (`"partner"`),
1711
- * `partnerFeeUsd`, `internationalCardFeeUsd` (`"0.00"` on a US card or one whose country
1712
- * is unknown; both `null` if the fee could not be booked yet, which INVO does shortly after),
1713
- * `coinsCredited` and `chargeTotalUsd`, each as INVO sent it.
1714
- */
1715
- purchaseCurrency(input: PurchaseInput, opts?: CallOptions): Promise<PurchaseResult>;
1716
- /**
1717
- * What a card purchase of coins will cost, BEFORE charging for it. Moves no money and
1718
- * creates nothing, so it is safe to call on every price render (`POST
1719
- * /api/currency-purchases/quote`, authenticated by your game secret like the purchase).
1720
- *
1721
- * The player pays the listed price plus any tax (when you pass `country`) and receives the
1722
- * listed coins: `totalUsd` carries no card fee, and `processingFeeUsd` is `"0.00"`. INVO's
1723
- * card fee (3.5% + $0.30 on Open, 5.5% + $0.50 on Merchant of Record) is charged to you;
1724
- * `partnerFeeUsd` carries it when INVO sends it. $10.00 quotes a $10.00 total, 100.00 coins
1725
- * at the default 10 per USD, and a $0.65 partner fee on Open. Show the player `totalUsd`,
1726
- * then send the same figure back as `acknowledgedTotalUsd` on {@link purchaseCurrency}; the
1727
- * card is never charged more than that. `ifUnacknowledged` shows the purchase without the
1728
- * acknowledgement (the card charged exactly `usdAmount`), or `null` when INVO sends none.
1729
- * `minPurchaseWarning` is set while an amount under INVO's minimum card purchase is still
1730
- * accepted. Card purchases only; purchases through a third-party storefront or payment
1731
- * rail are unaffected.
1732
- *
1733
- * Refusals: `400 INVALID_INPUT` (amount missing, not above zero, or above INVO's card
1734
- * maximum), `400 CURRENCY_NOT_CONFIGURED`, `503 RATE_UNAVAILABLE`.
1735
- */
1736
- quoteCurrencyPurchase(input: CurrencyPurchaseQuoteInput, opts?: CallOptions): Promise<CurrencyPurchaseQuote>;
1737
- /**
1738
- * Complete the card-rail 3-D Secure step after the client finished card action.
1739
- * `status: "success"` means the payment succeeded; tell the buyer the purchase is complete
1740
- * only when `credited` is `true` (see {@link ConfirmPaymentResult.credited}).
1741
- */
1742
- confirmPayment(input: {
1743
- paymentIntentId: string;
1744
- orderId?: string;
1745
- }, opts?: CallOptions): Promise<ConfirmPaymentResult>;
1746
- /** Fetch purchase status (order + financial summary + timeline). */
1747
- getOrderDetails(query: {
1748
- orderId?: string;
1749
- transactionId?: string;
1750
- }, opts?: CallOptions): Promise<OrderDetailsResult>;
1751
- /**
1752
- * The Steam packs INVO sells, and what each contains for one player.
1753
- *
1754
- * The PRICE is identical for every player and is INVO's to set; the
1755
- * `currencyAmount` varies by country. Render it verbatim — never compute
1756
- * currency from the sticker price (VAT and the storefront's revenue share
1757
- * come out of the sticker before currency is derived), and never cache one
1758
- * answer for all players. Without `steamid` the quote assumes no VAT — the
1759
- * most any pack yields; the purchase itself always re-derives.
1760
- *
1761
- * Refusals: `err.isSteamRailNotEntitled` (403). A missing Steam
1762
- * registration does NOT refuse here — packs deliberately answers with the
1763
- * no-VAT catalogue and lets the PURCHASE be what refuses; the only 503 is
1764
- * the rail being disabled platform-wide, whose body carries no error code.
1765
- */
1766
- steamPacks(query?: SteamPacksQuery, opts?: CallOptions): Promise<SteamPacksResult>;
1767
- /**
1768
- * Start a Steam micro-transaction. The player then authorizes — in the Steam
1769
- * overlay (`usersession: "client"`, the default) or on Steam's hosted
1770
- * checkout page (`usersession: "web"`, returned as `steamCheckoutUrl`; open
1771
- * it as a TOP-LEVEL tab, never an iframe; requires `playerIp`). After
1772
- * authorization, call {@link steamFinalizePurchase} with the returned
1773
- * `orderId`.
1774
- *
1775
- * Idempotent on `purchaseReference`, with one wire subtlety: a resend does
1776
- * not replay the original body — it answers **409 `DUPLICATE_REQUEST`**
1777
- * whose body carries the existing `order_id` (read it from `err.body`).
1778
- * Never double-charges. Retries — including manual retries after a 409 —
1779
- * MUST reuse the reference; a fresh one is a second intended purchase. For
1780
- * WEB sessions, persist `steamCheckoutUrl` from the first success: the 409
1781
- * body does not repeat it.
1782
- *
1783
- * Refusals worth branching on: `err.isPartnerCreditUnavailable` (409, the
1784
- * studio's settlement float cannot cover it — plain failure toast, do NOT
1785
- * hot-poll), `err.isPartnerRailSuspended` (409, terminal from the game's
1786
- * seat), `err.isPartnerBillingNotSetUp` (409), `err.isUnknownSteamPack`
1787
- * (400 — re-fetch `steamPacks()`), `err.isSteamNotConfigured` (503),
1788
- * `err.isSteamRailNotEntitled` (403), `err.isMissingPlayerIp` (400),
1789
- * `err.isDuplicateRequest` (409).
1790
- */
1791
- steamInitPurchase(input: SteamInitPurchaseInput, opts?: CallOptions): Promise<SteamInitPurchaseResult>;
1792
- /**
1793
- * Capture an authorized Steam transaction and credit the player.
1794
- *
1795
- * Idempotent: a retry or duplicate returns `alreadyProcessed: true` and
1796
- * never credits twice. Poller taxonomy — NOT every 409 means "not yet":
1797
- *
1798
- * - `err.isSteamAuthorizationPending` — the player has not approved yet
1799
- * (Steam still reports Init). Wait / poll again. THE NORMAL STATE.
1800
- * - `err.isSteamAuthorizationDead` — Failed / Refunded / Chargedback.
1801
- * STOP polling; no later call can succeed.
1802
- * - `err.isSteamAppChanged` (409) — the title's registration changed under
1803
- * the order. Terminal for this order.
1804
- * - 502 / 503 — transient; retry.
1805
- *
1806
- * A missed finalize is not a lost credit: INVO's reconciler independently
1807
- * detects the authorized transaction and credits, on a delay.
1808
- */
1809
- steamFinalizePurchase(input: SteamFinalizeInput, opts?: CallOptions): Promise<SteamFinalizeResult>;
1810
- /**
1811
- * Buy an in-game item by SPENDING the player's existing game currency (§4.8).
1812
- * No real money, no payment rail, no passkey — it's a balance debit, authenticated
1813
- * server-side by the game secret. Idempotent on clientRequestId (a duplicate throws
1814
- * a 409 InvoError; check err.isDuplicateRequest). Insufficient balance throws a 400
1815
- * (err.isInsufficientBalance; required_amount/current_balance on err.body). Grant the
1816
- * item to your inventory off the `item.purchased` webhook, not just this response.
1817
- */
1818
- purchaseItem(input: PurchaseItemInput, opts?: CallOptions): Promise<PurchaseItemResult>;
1819
- /** Paginated item-purchase history for a player (§4.8 companion read). */
1820
- getItemPurchaseHistory(query: ItemHistoryQuery, opts?: CallOptions): Promise<ItemHistoryResult>;
1821
- /** Look up one item order by EXACTLY ONE of orderId | transactionId | clientRequestId
1822
- * (§4.8). Use clientRequestId for saga/recovery: "did this purchase actually complete?" */
1823
- getItemOrderDetails(query: ItemOrderQuery, opts?: CallOptions): Promise<OrderDetailsResult>;
1824
- /**
1825
- * Async iterator over a player's entire item-purchase history — pages through
1826
- * `getItemPurchaseHistory` (limit/offset) until exhausted, yielding one row at a time.
1827
- *
1828
- * ```ts
1829
- * for await (const row of invo.iterateItemPurchaseHistory({ playerEmail })) { … }
1830
- * ```
1831
- */
1832
- iterateItemPurchaseHistory(query: {
1833
- playerEmail: string;
1834
- pageSize?: number;
1835
- }, opts?: CallOptions): AsyncGenerator<Record<string, unknown>, void, unknown>;
1836
- /**
1837
- * One merged, newest-first list of a player's money activity in your game, one page at a
1838
- * time (`GET /api/sdk/players/activity`): currency purchases, item purchases, Platform
1839
- * Commerce purchases, sends and transfers, in both directions. Only rows where your game
1840
- * is a party through this player are listed; the other side of a cross-game send or
1841
- * transfer is named by game only (`counterpartyGame`).
1842
- *
1843
- * An inbound (`direction: "in"`) send or transfer is listed as soon as it names this
1844
- * player, in ANY status (awaiting collection, completed, expired, refunded): read `status`
1845
- * and `statusDetail` before treating it as credited. `direction` is `"in"` / `"out"` /
1846
- * `"self"`, not the `"incoming"` / `"outgoing"` of the per-type history reads.
1847
- *
1848
- * Pass `nextCursor` back as `cursor` (with the same `types`) for the next page; it is
1849
- * `null` on the last one. `iteratePlayerActivity` walks every page.
1850
- *
1851
- * Refusals (`InvoError`): a blank `playerEmail` or a bad `limit` / `cursor` / `types`
1852
- * throws `INVALID_INPUT` before the network; `400 INVALID_INPUT` (for example an unknown
1853
- * kind in `types`), `400 INVALID_CURSOR` (a cursor from another player or other `types`),
1854
- * `401 INVALID_GAME_SECRET`, `404 PLAYER_NOT_FOUND` (`err.isPlayerNotFound`),
1855
- * `500 PLAYER_ACTIVITY_FAILED` (retry later), `429` (back off; `err.retryAfter`). A GET, so
1856
- * transient failures are retried automatically.
1857
- */
1858
- getPlayerActivity(query: PlayerActivityQuery, opts?: CallOptions): Promise<PlayerActivityResult>;
1859
- /**
1860
- * Async iterator over a player's ENTIRE activity, newest first: pages through
1861
- * `getPlayerActivity` by `nextCursor`, yielding one row at a time.
1862
- *
1863
- * ```ts
1864
- * for await (const row of invo.iteratePlayerActivity({ playerEmail, types: ["send", "transfer"] })) { … }
1865
- * ```
1866
- */
1867
- iteratePlayerActivity(query: {
1868
- playerEmail: string;
1869
- types?: PlayerActivityQuery["types"];
1870
- pageSize?: number;
1871
- }, opts?: CallOptions): AsyncGenerator<PlayerActivityEntry, void, unknown>;
1872
- /**
1873
- * Read a player's currency balances by email (server-side, game-secret).
1874
- *
1875
- * NOTE: lookup is by EMAIL only. There is no by-id balance route on the backend
1876
- * (`playerId` is a per-game internal id), so passing `playerId` throws — use the
1877
- * browser `InvoClient.getBalance()` (token-authed, identity from the token) for a
1878
- * client-side read, or `playerEmail` here server-side.
1879
- */
1880
- getPlayerBalance(query: PlayerBalanceQuery, opts?: CallOptions): Promise<PlayerBalanceResult>;
1881
- /**
1882
- * One player's loyalty cards, read by your SERVER with the game secret: the same cards
1883
- * the player sees through `InvoClient.getMyRewards()`, for the player with this email in
1884
- * your game. Each step carries `state` and `progress` (`{ current, target }`, or `null`
1885
- * when the number could not be read this time: render `state` alone then). Rewards carry
1886
- * their masked code only; a code is never returned here.
1887
- *
1888
- * Refusals (all `InvoError`): a blank email throws `INVALID_INPUT` before the network;
1889
- * `400 INVALID_PLAYER_EMAIL` (`err.isInvalidPlayerEmail`), `401 INVALID_GAME_SECRET` for a missing or wrong key, or
1890
- * a per-channel key (this read takes the game's server secret only), `404 PLAYER_NOT_FOUND`
1891
- * (`err.isPlayerNotFound`: no player with this email in this game), `429` (back off;
1892
- * `err.retryAfter`). Also `409 NO_TENANT` (the game is not set up for loyalty), `503`
1893
- * (temporarily unavailable) and `502` / `504` (the loyalty service could not be reached or
1894
- * timed out): retry later. A GET, so transient failures are retried automatically.
1895
- */
1896
- getPlayerRewards(playerEmail: string, opts?: CallOptions): Promise<LoyaltyCardsResult>;
1897
- /**
1898
- * Report a gameplay event for one player to INVO's loyalty engine from your SERVER
1899
- * (`POST /api/sdk/loyalty/server-events`, game secret). Server-reported events are the
1900
- * ones trusted for rewards. Use it for sessions, level milestones and custom events
1901
- * registered in the console (see {@link GameEventType}); currency steps are tracked by
1902
- * INVO itself and are never reported.
1903
- *
1904
- * Idempotent on `eventId`: pass your own UUID, or let the SDK generate one, and reuse the
1905
- * returned `eventId` if you retry. Transient failures (429, 5xx) are retried with it.
1906
- *
1907
- * Refusals (all `InvoError`): `INVALID_INPUT` before the network for a non-`game.*` type,
1908
- * a malformed `eventId`, an `occurredAt` without a timezone or a non-object payload;
1909
- * `400 RESERVED_EVENT_TYPE` / `EVENT_TYPE_NOT_ALLOWED`; `401 INVALID_GAME_SECRET`;
1910
- * `404 PLAYER_NOT_FOUND` (`err.isPlayerNotFound`); `422 validation_failed` (for example an
1911
- * unregistered `event_name`).
1912
- */
1913
- reportGameEvent(input: ReportServerGameEventInput, opts?: CallOptions): Promise<ReportGameEventResult>;
1914
- /**
1915
- * List LIVE, unclaimed inbound sends/transfers addressed to a player at YOUR game —
1916
- * the source of truth for a "you have X to collect" badge. Pass the player's email
1917
- * or phone. Match `toPhone` to the logged-in player (don't require `toIdentityId`,
1918
- * which is null when the phone maps to more than one of your players). Pairs with the
1919
- * `transfer.claim_pending` webhook (the webhook is the wake-up; this is the list).
1920
- */
1921
- getInboundPending(query: InboundPendingQuery, opts?: CallOptions): Promise<InboundPendingResult>;
1922
- /**
1923
- * Look up a player's linked wallet identities (SERVER-only, game-secret). Game-scoped:
1924
- * returns wallet members that also have a Player row on this game. Provide a `playerEmail`
1925
- * or `playerPhone` (phone wins if both). No in-game match (backend 404) returns
1926
- * `notFound: true` with empty `emails` — not an error.
1927
- *
1928
- * ⚠️ Returns first-party PII (emails/phones) — never expose this to the browser.
1929
- */
1930
- getLinkedIdentities(query: LinkedIdentitiesQuery, opts?: CallOptions): Promise<LinkedIdentitiesResult>;
1931
- /**
1932
- * Complete a TRANSFER's SMS-PIN step — the LAST-RESORT fallback for a sender who has
1933
- * no passkey.
1934
- *
1935
- * @deprecated The SMS-PIN path is being phased out and a future major version will
1936
- * remove this method. **Passkeys are the gold standard for authorizing money movement**
1937
- * — an SMS PIN is a shared secret on a channel exposed to SIM swap and interception,
1938
- * and it is not a peer of a WebAuthn assertion. When `initiate*` returns
1939
- * `verificationMethod: "sms"` it is telling you the sender has no passkey: prompt
1940
- * `InvoClient.enrollPasskey()` and then approve with
1941
- * `InvoClient.approveTransfer(transactionId)`. Reach for this method only when the user
1942
- * cannot enroll (unsupported device) or declines. Still fully functional — this
1943
- * annotation changes documentation only, not behavior.
1944
- *
1945
- * NOT idempotent — each attempt is counted server-side, so this is never auto-retried.
1946
- * A bad PIN throws a 400 InvoError carrying `attempts_remaining` on `err.body`; a
1947
- * blocked recipient throws 429 (`sms_verification_blocked`).
1948
- */
1949
- verifySmsTransfer(transactionId: string, smsPin: string, opts?: CallOptions): Promise<SmsVerifyResult>;
1950
- /**
1951
- * Complete a SEND's SMS-PIN step — the LAST-RESORT fallback for a sender who has no
1952
- * passkey. See {@link verifySmsTransfer}.
1953
- *
1954
- * @deprecated The SMS-PIN path is being phased out and a future major version will
1955
- * remove this method. Prompt `InvoClient.enrollPasskey()` and approve with
1956
- * `InvoClient.approveSend(transactionId)` instead; use this only when the user cannot
1957
- * enroll or declines. Documentation only — behavior is unchanged.
1958
- */
1959
- verifySmsSend(transactionId: string, smsPin: string, opts?: CallOptions): Promise<SmsVerifyResult>;
1960
- /**
1961
- * Claim an inbound TRANSFER by its claim code, crediting one of this game's currencies.
1962
- * NOT idempotent. A 200 may come back as `needsAccountSelection` (the recipient phone
1963
- * maps to >1 of your players) — inspect `result.candidates` and re-submit with
1964
- * `targetPlayerId`. Errors surface via InvoError (404 unknown code, 403 phone mismatch,
1965
- * 400 not-claimable/expired/wrong-value, 409 `err.isPhoneShareApprovalRequired`, …).
1966
- */
1967
- claimTransfer(input: ClaimTransferInput, opts?: CallOptions): Promise<ClaimResult>;
1968
- /**
1969
- * Claim an inbound SEND by its claim code. NOT idempotent. May return
1970
- * `needsAccountSelection` (multi-account phone) — re-submit with `receiverPlayerId`.
1971
- * See claimTransfer for the error surface.
1972
- */
1973
- claimCurrency(input: ClaimCurrencyInput, opts?: CallOptions): Promise<ClaimResult>;
1974
- /** Read a TRANSFER's status (verification_state + amounts + destination). */
1975
- getTransferStatus(transactionId: string, opts?: CallOptions): Promise<TransactionStatusResult>;
1976
- /** Read a SEND's status (adds fees, game names, claim_info, … on `raw`). */
1977
- getSendStatus(transactionId: string, opts?: CallOptions): Promise<TransactionStatusResult>;
1978
- /**
1979
- * Poll a transaction's guardian approval status (minor/guardian flow). The retry
1980
- * layer already retries the 503 (`{status:"unavailable"}`) for this idempotent GET;
1981
- * a missing approval throws a 404 InvoError (`{status:"not_found"}`).
1982
- */
1983
- getGuardianApprovalStatus(transactionId: string, opts?: CallOptions): Promise<GuardianApprovalStatusResult>;
1984
- /**
1985
- * List the games/tenants a player can send/transfer to FROM `sourceGameId`, with
1986
- * display metadata inline (name, icon, currency, min/max limits) — one call, no
1987
- * per-game lookup. SERVER variant (game-secret) of the browser `InvoClient.getDestinations`;
1988
- * the source game is passed explicitly rather than inferred from a player token. Rows
1989
- * share the browser shape. Idempotent (a POST read — safe to retry).
1990
- */
1991
- getDestinations(query: ServerDestinationsQuery, opts?: CallOptions): Promise<DestinationsResult>;
1992
- /**
1993
- * Phone-share OTP handshake — resolves a 409 `PHONE_SHARE_APPROVAL_REQUIRED`.
1994
- *
1995
- * These three endpoints are UNAUTHENTICATED (phone-owner-driven: no game secret,
1996
- * no player token) — a partner backend relays the handshake. The triggering 409
1997
- * carries `approval_id, expires_at, code_sent, existing_account_hints[], next_endpoint`.
1998
- *
1999
- * `phoneShareInitiate` is the fallback OTP send (use when the 409 didn't already
2000
- * dispatch a code). NOT idempotent — never auto-retried. OTP TTL ~10 min.
2001
- */
2002
- phoneShareInitiate(input: PhoneShareContact, opts?: CallOptions): Promise<PhoneShareInitiateResult>;
2003
- /**
2004
- * Approve a phone-share with the OTP the phone owner received. On success the grant
2005
- * is stored server-side, keyed by (phone, requesting_email) and auto-consumed — the
2006
- * caller simply RE-ISSUES the identical original request. UNAUTHENTICATED. NOT
2007
- * idempotent (attempts are counted) — never auto-retried.
2008
- */
2009
- phoneShareApprove(input: PhoneShareApproveInput, opts?: CallOptions): Promise<PhoneShareApproveResult>;
2010
- /**
2011
- * Poll whether a phone-share (phone, requesting_email) pair is approved yet.
2012
- * UNAUTHENTICATED, idempotent GET. `approved:true` means the original request can
2013
- * be re-issued.
2014
- */
2015
- phoneShareStatus(input: PhoneShareContact, opts?: CallOptions): Promise<PhoneShareStatusResult>;
2016
- /**
2017
- * Stage 1 — start a device approval for ONE transaction (RFC 8628 §3.1/§3.2).
2018
- *
2019
- * Returns the grant: render `verificationUriComplete` as the QR (print `userCode`
2020
- * under it for a TV with no camera), keep `deviceCode` on your server, then poll.
2021
- * A repeat `begin` while an earlier grant is merely PENDING supersedes it (fresh code;
2022
- * a page still open on the old one is told to scan again). A grant the player already
2023
- * APPROVED blocks a new `begin` for its window with `409 DEVICE_APPROVAL_ALREADY_PENDING`
2024
- * (`err.isDeviceApprovalAlreadyPending`, `err.deviceApprovalExpiresAt`) — the missing
2025
- * step there is `approveWithDeviceCode`, not a new code.
2026
- *
2027
- * For `transfer` / `send` the backend also pushes the transaction's own approval
2028
- * window past the grant's expiry, so an approval at minute nine cannot land on a
2029
- * transfer that has already been refunded. Auth: the player token. `channel: "popup"`
2030
- * is browser-only (`InvoClient.approveHosted`) and is refused before the network.
2031
- */
2032
- beginDeviceApproval(input: BeginDeviceApprovalInput, opts?: CallOptions): Promise<DeviceApprovalGrant>;
2033
- /**
2034
- * Stage 3 — one poll (RFC 8628 §3.4/§3.5). Call it no faster than `interval` seconds.
2035
- *
2036
- * Returns `status`:
2037
- * - `authorization_pending` — keep polling. While a first-time phone waits on your
2038
- * screen, `enrollment` is present: show "Set up INVO on <deviceLabel>? Code
2039
- * <matchCode>" and answer with `confirmDeviceEnrollment`.
2040
- * - `slow_down` — add 5 s to your interval, then resume.
2041
- * - `approved` — **now call `approveWithDeviceCode`**. Nothing has moved yet.
2042
- * - `access_denied` — the player declined; do not retry silently.
2043
- * - `expired_token` — the grant lapsed; `beginDeviceApproval` again.
2044
- * Throws `InvoError` for `invalid_grant` (`err.code === "invalid_grant"`: unknown code,
2045
- * or not this player's — one answer for both, deliberately) and for transport failures
2046
- * after the retry budget (429 / 5xx are retried: this is an idempotent read).
2047
- */
2048
- pollDeviceApproval(input: PollDeviceApprovalInput, opts?: CallOptions): Promise<DeviceApprovalPollResult>;
2049
- /**
2050
- * Stage 3b — answer the on-screen match-code prompt for a first-time phone.
2051
- *
2052
- * `approve` = "yes, the phone I just scanned with shows this code" (the phone then
2053
- * creates its INVO passkey and approves); `deny` ends the whole grant — the next poll
2054
- * answers `access_denied`. Answered once: `409 DEVICE_APPROVAL_ENROLLMENT_ALREADY_DECIDED`
2055
- * means the backup email got there first — take the prompt down quietly.
2056
- * `409 DEVICE_APPROVAL_NO_ENROLLMENT_PENDING`: no phone has asked. Not auto-retried.
2057
- */
2058
- confirmDeviceEnrollment(input: ConfirmDeviceEnrollmentInput, opts?: CallOptions): Promise<ConfirmDeviceEnrollmentResult>;
2059
- /**
2060
- * Stage 4 — THE MONEY STEP. Once the poll says `approved`, call this with the same
2061
- * player token and the grant's `deviceCode`. Routes by `flow`:
2062
- *
2063
- * transfer → POST /api/sdk/transfers/{id}/approve
2064
- * send → POST /api/sdk/send/{id}/approve
2065
- * send_receipt → POST /api/sdk/send/{id}/confirm-receipt
2066
- * transfer_receipt → POST /api/sdk/transfers/{id}/confirm-receipt
2067
- *
2068
- * The grant proves WHO approved; this call runs every gate the in-app passkey approve
2069
- * runs (guardian, risk, recovery cooldown) and moves the money. A grant that is never
2070
- * followed by this call moves nothing, and is consumed by nothing.
2071
- *
2072
- * Result: `status: "approved"` + `next: "pending_claim"` (transfer/send; `claimCode`
2073
- * on a transfer) or `status: "completed"` + `amountReceived` (receipt flows). A 202
2074
- * hold returns `holdReason` (money held, not refused). A repeat call after the code was
2075
- * consumed returns `status: "not_pending"` with `currentStatus` and `alreadySettled`
2076
- * — the backend's `TRANSACTION_NOT_PENDING` mapped into a result rather than thrown,
2077
- * because for this call it is the normal answer to "did my earlier attempt land?".
2078
- *
2079
- * Throws `InvoError`: `err.isDeviceApprovalNotApproved` (400 — wrong/foreign code,
2080
- * wrong flow, or the poll never said approved), `err.isPasskeyRecoveryCooldown` (403,
2081
- * money-out after a passkey recovery — `err.retryAfterAt`), `err.isPlayerTokenStale`
2082
- * (403, the player token predates the sender's phone being added: re-mint, or use the
2083
- * initiate's `playerToken`, and retry once), guardian terminal states (410). Never
2084
- * auto-retried: the device_code is a single-use factor.
2085
- *
2086
- * **A FAILURE HERE IS AMBIGUOUS ABOUT THE MONEY.** The backend commits the transfer and
2087
- * *then* builds its 200 by reading the transaction back, so a fault raised after that
2088
- * commit answers `SEND_APPROVE_FAILED` / `TRANSFER_APPROVE_FAILED` /
2089
- * `CONFIRM_RECEIPT_FAILED` (`err.isSettleFault`, `err.errorRef`) for money that already
2090
- * moved. A `status === 0` (timeout, connection dropped) is ambiguous for the same
2091
- * reason, and this call is deliberately not auto-retried. So on either: read
2092
- * `getTransferStatus` / `getSendStatus`, or wait for the `transfer.claim_pending`
2093
- * webhook, BEFORE you tell the player it failed — and never auto-start a replacement
2094
- * transaction.
2095
- */
2096
- approveWithDeviceCode(input: ApproveWithDeviceCodeInput, opts?: CallOptions): Promise<DeviceApprovalSettleResult>;
2097
- /**
2098
- * Convenience only — stages 3 and 4 in one call, for a server that can hold the loop
2099
- * open (a per-request worker, a job). Polls `pollDeviceApproval` on `interval`, adds
2100
- * 5 s on `slow_down`, forwards the poll's `enrollment` to `onEnrollment` (answer with
2101
- * `respond`), and on `approved` calls `approveWithDeviceCode` — THEN resolves.
2102
- * `respond` is best-effort: a prompt the grant has outlived (`expired_token`,
2103
- * `invalid_grant`) or that was already answered elsewhere resolves quietly rather than
2104
- * rejecting, because callers fire it from UI code without awaiting it.
2105
- * You still call `beginDeviceApproval` yourself first, because your game has to draw
2106
- * the QR between begin and the first poll.
2107
- *
2108
- * Resolves `{ status: "approved", settlement }` | `denied` | `expired` | `aborted`.
2109
- * Rejects on `invalid_grant`, on a refused approve (e.g. `PASSKEY_RECOVERY_COOLDOWN`),
2110
- * and after 5 consecutive transport failures on the poll.
2111
- *
2112
- * **Record the attempt in your own store BEFORE you call this.** It blocks for as long
2113
- * as the player takes and then moves money from inside the loop, so if your process
2114
- * dies between the approve call and its response, a row you wrote first — plus
2115
- * `getTransferStatus` / `getSendStatus` — is the only way to learn whether the money
2116
- * moved. Servers that must not block a request use the three calls directly and keep
2117
- * `deviceCode` in their own store.
2118
- *
2119
- * `respond` (handed to `onEnrollment`) is best-effort: a prompt the grant has outlived
2120
- * resolves quietly rather than rejecting. Any other confirm-enrollment refusal
2121
- * propagates, so `await` it if you want to see one.
2122
- */
2123
- completeDeviceApproval(input: CompleteDeviceApprovalInput, opts?: CallOptions): Promise<CompleteDeviceApprovalResult>;
2124
- private toInitiateResult;
2125
- }
2126
-
2127
- 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, type IdentityPasskeyResetData, InboundPendingQuery, InboundPendingResult, InitiateResult, InitiateSendInput, InitiateTransferInput, InvoError, InvoServer, type InvoWebhookEvent, ItemHistoryQuery, ItemHistoryResult, ItemOrderQuery, type ItemPurchasedData, LinkedIdentitiesQuery, LinkedIdentitiesResult, type ListPayeesQuery, type ListPayeesResult, type ListPayoutsQuery, type ListPayoutsResult, ListSubscriptionsOptions, LoyaltyCardsResult, MintPlayerTokenInput, OrderDetailsResult, type PayableBlocker, type Payee, type PayeeInvite, type PayeeStatus, type PayeeStatusChangedData, type Payout, type PayoutStatus, type PayoutStatusChangedData, PayoutsServer, PhoneChangeRequest, PhoneShareApproveInput, PhoneShareApproveResult, PhoneShareContact, PhoneShareInitiateResult, PhoneShareStatusResult, type PlatformCommercePurchasedData, type PlatformCommerceRefundedData, PlatformCommerceServer, PlatformOrderStatusResult, PlatformPurchaseHistoryQuery, PlatformPurchaseHistoryResult, PlatformPurchaseInput, PlatformPurchaseResult, PlatformRefundInput, PlatformRefundResult, PlayerActivityEntry, PlayerActivityQuery, PlayerActivityResult, PlayerBalanceQuery, PlayerBalanceResult, PlayerCardsResult, type PlayerPhoneChangedData, PlayerToken, PollDeviceApprovalInput, type PurchaseCompletedData, type PurchaseEventData, PurchaseInput, PurchaseItemInput, PurchaseItemResult, PurchaseResult, RefundResult, RefundSubscriptionInput, type RegisterPayeeInput, type RegisterPayeeResult, RegisterPlayerInput, RegisterPlayerResult, ReportGameEventResult, ReportServerGameEventInput, type RequestPayoutInput, type RequestPayoutResult, RequestPhoneChangeInput, RequestPhoneChangeResult, type ReturnReasonCode, 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, UpdatePlayerPhoneInput, UpdatePlayerPhoneResult, type VerifyWebhookOptions, type WebhookHandlerOptions, createWebhookHandler, verifyWebhook, verifyWebhookAsync };
1
+ export { bx as ApproveWithDeviceCodeInput, br as BeginDeviceApprovalInput, g as CallOptions, ah as CancelResult, ag as CancelSubscriptionOptions, au as CardSetupConfirmInput, av as CardSetupConfirmResult, as as CardSetupInput, at as CardSetupResult, aq as CardSetupSessionInput, ar as CardSetupSessionResult, bB as CardSetupStatus, ai as ChangeAmountResult, bC as CheckoutWarning, bi as ClaimCurrencyInput, y as ClaimDelivery, bh as ClaimResult, bg as ClaimTransferInput, bz as CompleteDeviceApprovalInput, bA as CompleteDeviceApprovalResult, bv as ConfirmDeviceEnrollmentInput, bw as ConfirmDeviceEnrollmentResult, aU as ConfirmPaymentResult, aO as CreateCheckoutInput, aP as CreateCheckoutResult, aa as CreateSubscriptionInput, bD as CurrencyBalance, aT as CurrencyPurchaseQuote, bE as CurrencyPurchaseQuoteBreakdown, aS as CurrencyPurchaseQuoteInput, z as DestinationGame, n as DestinationsResult, bF as DeviceApprovalChannel, bG as DeviceApprovalEnrollment, bH as DeviceApprovalFlow, bs as DeviceApprovalGrant, bu as DeviceApprovalPollResult, bI as DeviceApprovalPollStatus, by as DeviceApprovalSettleResult, bJ as DeviceEnrollmentDecision, bK as DeviceEnrollmentRespond, bL as ExpiryReason, bM as FeeTakenFrom, bN as FirstCharge, bO as FirstChargeStatus, bP as FundingSource, G as GameEventType, ac as GetSubscriptionOptions, ad as GetSubscriptionResult, bk as GuardianApprovalStatusResult, bQ as InboundPendingItem, bb as InboundPendingQuery, bc as InboundPendingResult, aM as InitiateResult, aL as InitiateSendInput, aN as InitiateTransferInput, I as InvoError, F as InvoErrorInfo, J as InvoHooks, K as InvoRequestInfo, N as InvoResponseInfo, b2 as ItemHistoryQuery, b3 as ItemHistoryResult, b4 as ItemOrderQuery, bd as LinkedIdentitiesQuery, be as LinkedIdentitiesResult, bR as LinkedIdentityEmail, ae as ListSubscriptionsOptions, O as LoyaltyCard, Q as LoyaltyCardReward, S as LoyaltyCardStep, o as LoyaltyCardsResult, T as LoyaltyRewardState, U as LoyaltyStepProgress, V as LoyaltyStepState, bS as MinPurchaseWarning, aC as MintPlayerTokenInput, aV as OrderDetailsResult, bT as PhoneChangeConfirmation, aK as PhoneChangeRequest, bU as PhoneChangeRequestStatus, bo as PhoneShareApproveInput, bp as PhoneShareApproveResult, bm as PhoneShareContact, bn as PhoneShareInitiateResult, bq as PhoneShareStatusResult, a5 as PlatformOrderStatusResult, a6 as PlatformPurchaseHistoryQuery, a7 as PlatformPurchaseHistoryResult, a3 as PlatformPurchaseInput, a4 as PlatformPurchaseResult, bV as PlatformPurchaseStatus, a8 as PlatformRefundInput, a9 as PlatformRefundResult, b7 as PlayerActivityEntry, b5 as PlayerActivityQuery, b6 as PlayerActivityResult, bW as PlayerActivityType, b8 as PlayerBalanceQuery, b9 as PlayerBalanceResult, aw as PlayerCardsResult, aD as PlayerToken, bt as PollDeviceApprovalInput, aQ as PurchaseInput, b0 as PurchaseItemInput, b1 as PurchaseItemResult, aR as PurchaseResult, a0 as Rail, bX as RefundInitiation, bY as RefundPendingApproval, bZ as RefundProcessingFeeBasis, b_ as RefundReceipt, am as RefundResult, b$ as RefundRevenueShareAttribution, al as RefundSubscriptionInput, c0 as RefundWarning, aE as RegisterPlayerInput, aF as RegisterPlayerResult, r as ReportGameEventInput, s as ReportGameEventResult, ba as ReportServerGameEventInput, aI as RequestPhoneChangeInput, aJ as RequestPhoneChangeResult, ax as SandboxClockResult, c1 as SandboxClockState, ay as SandboxFailureOutcome, aA as SandboxForceAuthChallengeOptions, az as SandboxForceFailureOptions, c2 as SavedCard, aB as ServerConfig, bl as ServerDestinationsQuery, aj as SetPaymentMethodInput, ak as SetPaymentMethodResult, bf as SmsVerifyResult, a_ as SteamFinalizeInput, a$ as SteamFinalizeResult, ap as SteamFinalizeSubscriptionResult, aY as SteamInitPurchaseInput, aZ as SteamInitPurchaseResult, ao as SteamInitResult, c3 as SteamPack, aW as SteamPacksQuery, aX as SteamPacksResult, an as SteamSubscriptionInitInput, c4 as SteamUserSession, c5 as Subscription, c6 as SubscriptionBaseInput, c7 as SubscriptionConsent, c8 as SubscriptionConsentInput, c9 as SubscriptionFundingRail, ca as SubscriptionInterval, af as SubscriptionListResult, ab as SubscriptionResult, cb as SubscriptionRevenueShare, cc as SubscriptionRevenueShareInput, cd as SubscriptionStatus, bj as TransactionStatusResult, ce as UnacknowledgedPurchaseOutcome, aG as UpdatePlayerPhoneInput, aH as UpdatePlayerPhoneResult, a1 as VerificationMethod, cf as isRefundPendingApproval } from './types-_lIm74kd.js';
2
+ export { C as CardsServer, D as DEMO_KEY_PREFIX, E as EnvironmentUnknownError, c as IdentityPasskeyResetData, a as InvoEnvironment, I as InvoServer, d as InvoWebhookEvent, e as ItemPurchasedData, L as ListPayeesQuery, f as ListPayeesResult, g as ListPayoutsQuery, h as ListPayoutsResult, P as PRODUCTION_BASE_URL, j as PayableBlocker, k as Payee, l as PayeeInvite, m as PayeeStatus, n as PayeeStatusChangedData, o as Payout, p as PayoutStatus, q as PayoutStatusChangedData, s as PayoutsServer, t as PlatformCommercePurchasedData, u as PlatformCommerceRefundedData, w as PlatformCommerceServer, x as PlayerPhoneChangedData, y as PurchaseCompletedData, z as PurchaseEventData, R as RegisterPayeeInput, A as RegisterPayeeResult, B as RequestPayoutInput, F as RequestPayoutResult, G as ReturnReasonCode, S as SANDBOX_BASE_URL, H as SandboxServer, J as SandboxSubscriptionsServer, K as SubscriptionAuthenticationRequiredData, M as SubscriptionCanceledData, N as SubscriptionEventCommon, O as SubscriptionExpiredData, Q as SubscriptionPastDueData, T as SubscriptionPaymentFailedData, U as SubscriptionRefundApprovedData, V as SubscriptionRefundDetail, W as SubscriptionRefundRejectedData, X as SubscriptionRefundRequestData, Y as SubscriptionRefundedData, Z as SubscriptionRenewalFunding, _ as SubscriptionRenewalSplit, $ as SubscriptionRenewedData, a0 as SubscriptionRevenueShareAttribution, a1 as SubscriptionTrialEventFields, a2 as SubscriptionsServer, a3 as TransferEventData, a4 as VerifyWebhookOptions, a5 as WebhookHandlerOptions, b as baseUrlForKey, a6 as createWebhookHandler, i as isDemoKey, r as resolveEnvironment, a7 as verifyWebhook, a8 as verifyWebhookAsync } from './server-Dnx5jxS4.js';
3
+ export { S as SDK_VERSION } from './version-xyYQO5hp.js';