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