@invonetwork/web-sdk 3.8.1 → 3.10.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +70 -0
- package/LICENSE +18 -18
- package/README.md +176 -51
- package/dist/{chunk-HYGBTUEJ.js → chunk-L4A6OV54.js} +106 -2
- package/dist/index.cjs +104 -0
- package/dist/index.d.cts +2 -2
- package/dist/index.d.ts +2 -2
- package/dist/index.js +2 -2
- package/dist/server.cjs +307 -61
- package/dist/server.d.cts +216 -37
- package/dist/server.d.ts +216 -37
- package/dist/server.js +204 -63
- package/dist/{types-DqRuqbqI.d.cts → types-CBxpXgAM.d.cts} +273 -15
- package/dist/{types-DqRuqbqI.d.ts → types-CBxpXgAM.d.ts} +273 -15
- package/package.json +1 -1
package/dist/server.d.ts
CHANGED
|
@@ -1,12 +1,12 @@
|
|
|
1
|
-
import { I as InvoError, H as Http, o as AuthHeader, p as
|
|
2
|
-
export {
|
|
1
|
+
import { I as InvoError, H as Http, o as AuthHeader, p as CardSetupSessionInput, c as CallOptions, q as CardSetupSessionResult, r as CardSetupInput, s as CardSetupResult, t as CardSetupConfirmInput, u as CardSetupConfirmResult, v as PlayerCardsResult, w as PlatformPurchaseInput, x as PlatformPurchaseResult, y as PlatformOrderStatusResult, z as PlatformRefundInput, F as PlatformRefundResult, G as CreateSubscriptionInput, S as SubscriptionResult, J as GetSubscriptionOptions, K as GetSubscriptionResult, N as ListSubscriptionsOptions, O as SubscriptionListResult, Q as CancelSubscriptionOptions, T as CancelResult, U as ChangeAmountResult, W as SetPaymentMethodInput, X as SetPaymentMethodResult, Y as RefundSubscriptionInput, Z as RefundResult, _ as SteamSubscriptionInitInput, $ as SteamInitResult, a0 as SteamFinalizeSubscriptionResult, a1 as SandboxClockResult, a2 as SandboxFailureOutcome, a3 as SandboxForceFailureOptions, a4 as SandboxForceAuthChallengeOptions, a5 as ServerConfig, a6 as PlayerToken, a7 as InitiateSendInput, a8 as InitiateResult, a9 as InitiateTransferInput, aa as CreateCheckoutInput, ab as CreateCheckoutResult, ac as PurchaseInput, ad as PurchaseResult, ae as ConfirmPaymentResult, af as OrderDetailsResult, ag as SteamPacksQuery, ah as SteamPacksResult, ai as SteamInitPurchaseInput, aj as SteamInitPurchaseResult, ak as SteamFinalizeInput, al as SteamFinalizeResult, am as PurchaseItemInput, an as PurchaseItemResult, ao as ItemHistoryQuery, ap as ItemHistoryResult, aq as ItemOrderQuery, ar as PlayerBalanceQuery, as as PlayerBalanceResult, at as InboundPendingQuery, au as InboundPendingResult, av as LinkedIdentitiesQuery, aw as LinkedIdentitiesResult, ax as SmsVerifyResult, ay as ClaimTransferInput, az as ClaimResult, aA as ClaimCurrencyInput, aB as TransactionStatusResult, aC as GuardianApprovalStatusResult, aD as ServerDestinationsQuery, d as DestinationsResult, aE as PhoneShareContact, aF as PhoneShareInitiateResult, aG as PhoneShareApproveInput, aH as PhoneShareApproveResult, aI as PhoneShareStatusResult, aJ as BeginDeviceApprovalInput, aK as DeviceApprovalGrant, aL as PollDeviceApprovalInput, aM as DeviceApprovalPollResult, aN as ConfirmDeviceEnrollmentInput, aO as ConfirmDeviceEnrollmentResult, aP as ApproveWithDeviceCodeInput, aQ as DeviceApprovalSettleResult, aR as CompleteDeviceApprovalInput, aS as CompleteDeviceApprovalResult } from './types-CBxpXgAM.js';
|
|
2
|
+
export { aT as CardSetupStatus, aU as CurrencyBalance, h as DestinationGame, aV as DeviceApprovalChannel, aW as DeviceApprovalEnrollment, aX as DeviceApprovalFlow, aY as DeviceApprovalPollStatus, aZ as DeviceEnrollmentDecision, a_ as DeviceEnrollmentRespond, a$ as FirstCharge, b0 as FirstChargeStatus, b1 as FundingSource, b2 as InboundPendingItem, i as InvoErrorInfo, j as InvoHooks, k as InvoRequestInfo, l as InvoResponseInfo, b3 as LinkedIdentityEmail, b4 as PlatformPurchaseStatus, n as Rail, b5 as RefundInitiation, b6 as RefundPendingApproval, b7 as RefundProcessingFeeBasis, b8 as RefundReceipt, b9 as RefundRevenueShareAttribution, ba as RefundWarning, bb as SandboxClockState, bc as SavedCard, bd as SteamPack, be as SteamUserSession, bf as Subscription, bg as SubscriptionBaseInput, bh as SubscriptionConsent, bi as SubscriptionConsentInput, bj as SubscriptionFundingRail, bk as SubscriptionInterval, bl as SubscriptionRevenueShare, bm as SubscriptionRevenueShareInput, bn as SubscriptionStatus, V as VerificationMethod, bo as isRefundPendingApproval } from './types-CBxpXgAM.js';
|
|
3
3
|
|
|
4
4
|
/**
|
|
5
5
|
* The package version, as sent in the server User-Agent. A test pins this to
|
|
6
6
|
* `package.json` so it cannot drift silently (it did: the UA read 3.0.0 through 3.7.0).
|
|
7
7
|
* Bump it with the changeset flow.
|
|
8
8
|
*/
|
|
9
|
-
declare const SDK_VERSION = "3.
|
|
9
|
+
declare const SDK_VERSION = "3.10.0";
|
|
10
10
|
|
|
11
11
|
interface VerifyWebhookOptions {
|
|
12
12
|
/** Max age of the signed timestamp, in seconds. Default 300 (5 min). */
|
|
@@ -40,7 +40,17 @@ interface PurchaseCompletedData {
|
|
|
40
40
|
* real answer ("unattributed"), read it as one.
|
|
41
41
|
*/
|
|
42
42
|
channel?: string | null;
|
|
43
|
-
/**
|
|
43
|
+
/**
|
|
44
|
+
* The metadata you passed to createCheckout/purchaseCurrency/steamInitPurchase, echoed back
|
|
45
|
+
* (all rails).
|
|
46
|
+
*
|
|
47
|
+
* **Subscription renewals also emit `purchase.completed`** (every paid card renewal, for the
|
|
48
|
+
* coins its charge minted). Those carry `metadata.source === "subscription_renewal"` and
|
|
49
|
+
* `metadata.subscription_id` (plus `period_seq`, `attempt_no`, `item_id`, `funding_rail`,
|
|
50
|
+
* and `funding_model: "card_only"` on the card rail). **Do not grant currency or access from
|
|
51
|
+
* them**: the renewal spends those coins in the same step. Act on `subscription.renewed`;
|
|
52
|
+
* its `mint_order_id` equals this event's `order_id`.
|
|
53
|
+
*/
|
|
44
54
|
metadata?: Record<string, unknown>;
|
|
45
55
|
[key: string]: unknown;
|
|
46
56
|
}
|
|
@@ -150,10 +160,18 @@ interface SubscriptionEventCommon {
|
|
|
150
160
|
metadata: Record<string, unknown> | null;
|
|
151
161
|
[key: string]: unknown;
|
|
152
162
|
}
|
|
153
|
-
/**
|
|
163
|
+
/**
|
|
164
|
+
* How a renewal was funded.
|
|
165
|
+
*
|
|
166
|
+
* Card rail (card only since 2026-09-17): the card pays the full price, so
|
|
167
|
+
* `balance_applied_coins` is always `"0.00"`, `card_charged_usd` is the price, `minted_coins`
|
|
168
|
+
* equals the event's `amount_coins`, and `new_balance` is the member's unchanged balance.
|
|
169
|
+
* Steam rail: the wallet is spent first and Steam tops up the shortfall only.
|
|
170
|
+
*/
|
|
154
171
|
interface SubscriptionRenewalFunding {
|
|
155
|
-
/** The pre-existing wallet portion, in coins. */
|
|
172
|
+
/** The pre-existing wallet portion, in coins. Always `"0.00"` on the card rail. */
|
|
156
173
|
balance_applied_coins: string;
|
|
174
|
+
/** On the card rail, the full period price. */
|
|
157
175
|
card_charged_usd: string;
|
|
158
176
|
/** "card" | "steam". */
|
|
159
177
|
rail: string;
|
|
@@ -163,7 +181,8 @@ interface SubscriptionRenewalFunding {
|
|
|
163
181
|
[key: string]: unknown;
|
|
164
182
|
}
|
|
165
183
|
/**
|
|
166
|
-
* The fee split for one renewal. On
|
|
184
|
+
* The fee split for one renewal. On the card rail INVO's fee is its percentage plus $0.30 on
|
|
185
|
+
* the full price. On Steam, `basis` is `"steam_net"` and `total_usd` is
|
|
167
186
|
* what the coins are worth after Valve's share and VAT, NOT the price (the price is the
|
|
168
187
|
* event's top-level `amount_usd`).
|
|
169
188
|
*/
|
|
@@ -191,7 +210,12 @@ interface SubscriptionRevenueShareAttribution {
|
|
|
191
210
|
* `subscription.renewed`: THE SOURCE OF TRUTH FOR ENTITLEMENT. Fires once per successfully
|
|
192
211
|
* charged period, including period 1. Extend access to `period_end` (the new `paid_through`).
|
|
193
212
|
* `period_start`/`period_end` are the period JUST PAID; `current_period_*` and
|
|
194
|
-
* `next_charge_at` are the NEW window. `mint_order_id` is `null`
|
|
213
|
+
* `next_charge_at` are the NEW window. `mint_order_id` is never `null` on a card renewal; on
|
|
214
|
+
* Steam it is `null` when the wallet covered the period.
|
|
215
|
+
*
|
|
216
|
+
* Every paid card renewal also emits `purchase.completed` (with
|
|
217
|
+
* `data.metadata.source === "subscription_renewal"`) for the coins its charge minted. Do not
|
|
218
|
+
* grant anything from that event; its `order_id` is this event's `mint_order_id`.
|
|
195
219
|
*/
|
|
196
220
|
interface SubscriptionRenewedData {
|
|
197
221
|
subscription_id: string;
|
|
@@ -230,6 +254,14 @@ interface SubscriptionPaymentFailedData extends SubscriptionEventCommon {
|
|
|
230
254
|
/** "card_declined" | "insufficient_funds" | "error". */
|
|
231
255
|
outcome: string;
|
|
232
256
|
reason: string;
|
|
257
|
+
/**
|
|
258
|
+
* Why the attempt failed. Card rail: `card_declined`, `no_payment_method` (no saved card;
|
|
259
|
+
* the coin wallet never pays a card subscription), `wallet_only` (a deprecated wallet-only
|
|
260
|
+
* subscription, which can never be paid), `wallet_negative` (the member's coin balance is
|
|
261
|
+
* below zero; nothing was charged), `card_expired`, `card_detached`, `card_mismatch`,
|
|
262
|
+
* `no_customer_snapshot`, `processing_error`, `settlement_error`. Steam: `steam_*` codes.
|
|
263
|
+
* Treat unknown values as a generic failure.
|
|
264
|
+
*/
|
|
233
265
|
failure_code: string;
|
|
234
266
|
failure_message: string | null;
|
|
235
267
|
first_failure: boolean;
|
|
@@ -249,8 +281,9 @@ interface SubscriptionPastDueData extends SubscriptionEventCommon {
|
|
|
249
281
|
/**
|
|
250
282
|
* `subscription.authentication_required`: NOT a failure. Card rail only. Nothing was
|
|
251
283
|
* charged and no retry was consumed. Relay `confirmation_url` (a single-use bearer link)
|
|
252
|
-
* to the member before `expires_at`. `card_amount_usd` is what the card is asked for
|
|
253
|
-
*
|
|
284
|
+
* to the member before `expires_at`. `card_amount_usd` is what the card is asked for: since
|
|
285
|
+
* 2026-09-17 the full period price, the same figure as `amount_due_usd` (a challenge opened
|
|
286
|
+
* before that date can still show the older wallet-shortfall figure).
|
|
254
287
|
*/
|
|
255
288
|
interface SubscriptionAuthenticationRequiredData extends SubscriptionEventCommon {
|
|
256
289
|
attempt_no: number;
|
|
@@ -267,7 +300,9 @@ interface SubscriptionAuthenticationRequiredData extends SubscriptionEventCommon
|
|
|
267
300
|
/**
|
|
268
301
|
* `subscription.canceled`: fires once, at the moment cancellation is requested, in both
|
|
269
302
|
* modes. Revoke at `access_until`. `canceled_by` is `"partner"` for your API call and
|
|
270
|
-
* `"steam"` when the member cancelled the agreement from their Steam account.
|
|
303
|
+
* `"steam"` when the member cancelled the agreement from their Steam account. A full refund
|
|
304
|
+
* also cancels the subscription immediately: that event carries `canceled_by: "partner"` and
|
|
305
|
+
* `cancel_cause: "full_refund"`; it and `subscription.refunded` are sent together and may arrive in any order.
|
|
271
306
|
*/
|
|
272
307
|
interface SubscriptionCanceledData extends SubscriptionEventCommon {
|
|
273
308
|
effective_at: string;
|
|
@@ -278,13 +313,15 @@ interface SubscriptionCanceledData extends SubscriptionEventCommon {
|
|
|
278
313
|
reason: string | null;
|
|
279
314
|
/** "partner" | "steam". */
|
|
280
315
|
canceled_by: string;
|
|
316
|
+
/** Present only when the cancellation was a side effect: `"full_refund"`. Absent on an ordinary cancel. */
|
|
317
|
+
cancel_cause?: string;
|
|
281
318
|
}
|
|
282
319
|
/**
|
|
283
320
|
* `subscription.expired`: THE EVENT THAT REVOKES ENTITLEMENT. Revoke at `final_period_end`
|
|
284
321
|
* (the last instant the member paid for; `null` if nothing was ever collected), not at
|
|
285
|
-
* `ended_at`. A never-authorised Steam row carries `failure_code: "steam_authorization_abandoned"
|
|
286
|
-
*
|
|
287
|
-
*
|
|
322
|
+
* `ended_at`. A never-authorised Steam row carries `failure_code: "steam_authorization_abandoned"`.
|
|
323
|
+
* `failure_code: "steam_containment"` is no longer sent (spending is not restricted by which
|
|
324
|
+
* rail bought the currency).
|
|
288
325
|
*/
|
|
289
326
|
interface SubscriptionExpiredData extends SubscriptionEventCommon {
|
|
290
327
|
failed_period_start: string | null;
|
|
@@ -310,12 +347,24 @@ interface SubscriptionRefundDetail {
|
|
|
310
347
|
partner_revenue_reversed_usd: string;
|
|
311
348
|
/** "full" | "prorata". */
|
|
312
349
|
partner_revenue_reversal_mode: string;
|
|
350
|
+
/** Additive (2026-09-17). The card processor fee you bear on a card refund; `"0.00"` on a coin refund. */
|
|
351
|
+
processing_fee_usd?: string;
|
|
352
|
+
/** Additive (2026-09-17). "actual" | "estimated" | "none". */
|
|
353
|
+
processing_fee_basis?: string;
|
|
354
|
+
/** Additive (2026-09-17). Always "partner". */
|
|
355
|
+
processing_fee_borne_by?: string;
|
|
356
|
+
/** Additive (2026-09-17). Revenue reversed plus the processor fee: everything this refund took from your revenue. */
|
|
357
|
+
partner_total_reversed_usd?: string;
|
|
313
358
|
[key: string]: unknown;
|
|
314
359
|
}
|
|
315
360
|
/**
|
|
316
361
|
* `subscription.refunded`: its own shape. Your revenue for the refunded portion is
|
|
317
|
-
* reversed (`refund.partner_revenue_reversed_usd`); INVO's fee is retained
|
|
318
|
-
*
|
|
362
|
+
* reversed (`refund.partner_revenue_reversed_usd`); INVO's fee is retained; on a card refund
|
|
363
|
+
* you also bear the processor fee (`refund.processing_fee_usd`). "What did I earn" subtracts
|
|
364
|
+
* `refund.partner_total_reversed_usd` (older events without it: `partner_revenue_reversed_usd`).
|
|
365
|
+
* A FULL refund cancels the subscription (`subscription_canceled: true`), and a
|
|
366
|
+
* `subscription.canceled` with `cancel_cause: "full_refund"` is sent with it (sent together and may arrive in any order).
|
|
367
|
+
* A partial one does not.
|
|
319
368
|
*/
|
|
320
369
|
interface SubscriptionRefundedData {
|
|
321
370
|
subscription_id: string;
|
|
@@ -335,8 +384,58 @@ interface SubscriptionRefundedData {
|
|
|
335
384
|
refund: SubscriptionRefundDetail;
|
|
336
385
|
revenue_share_attribution: Record<string, unknown> | null;
|
|
337
386
|
metadata: Record<string, unknown> | null;
|
|
387
|
+
/** Additive (2026-09-17). "self_serve" | "approved_request". */
|
|
388
|
+
initiation?: string;
|
|
389
|
+
/** Additive (2026-09-17). The refund request INVO approved, or `null`. */
|
|
390
|
+
refund_request_id?: string | null;
|
|
391
|
+
/** Additive (2026-09-17). `true` when this refund cancelled the subscription. */
|
|
392
|
+
subscription_canceled?: boolean;
|
|
393
|
+
[key: string]: unknown;
|
|
394
|
+
}
|
|
395
|
+
/**
|
|
396
|
+
* `subscription.refund_requested`: a refund over your game's daily self-serve limit became a
|
|
397
|
+
* refund request (your `/refund` call answered 202 `pending_approval`). Nothing has moved.
|
|
398
|
+
* Not the common subscription block: it describes the request.
|
|
399
|
+
*/
|
|
400
|
+
interface SubscriptionRefundRequestData {
|
|
401
|
+
/** `SRR...`. */
|
|
402
|
+
request_id: string;
|
|
403
|
+
/** "pending" | "approved" | "rejected". */
|
|
404
|
+
status: string;
|
|
405
|
+
subscription_id: string;
|
|
406
|
+
item_id: string;
|
|
407
|
+
period_seq: number;
|
|
408
|
+
client_request_id: string;
|
|
409
|
+
/** The amount asked for. */
|
|
410
|
+
amount_usd: string;
|
|
411
|
+
/** Your reason, or `null` when you sent none. */
|
|
412
|
+
reason: string | null;
|
|
413
|
+
requested_at: string;
|
|
414
|
+
daily_cap_usd: string;
|
|
415
|
+
executed_today_usd: string;
|
|
416
|
+
player_email: string | null;
|
|
417
|
+
identity_id: string | null;
|
|
418
|
+
metadata: Record<string, unknown> | null;
|
|
338
419
|
[key: string]: unknown;
|
|
339
420
|
}
|
|
421
|
+
/**
|
|
422
|
+
* `subscription.refund_approved`: INVO approved the request and the refund ran;
|
|
423
|
+
* `subscription.refunded` (and `subscription.canceled` on a full refund) are sent in the same
|
|
424
|
+
* step and may arrive before or after this event. A retry of your `clientRequestId` now returns the receipt.
|
|
425
|
+
*/
|
|
426
|
+
interface SubscriptionRefundApprovedData extends SubscriptionRefundRequestData {
|
|
427
|
+
decided_at: string;
|
|
428
|
+
/** The refund transaction. */
|
|
429
|
+
transaction_id: string;
|
|
430
|
+
}
|
|
431
|
+
/**
|
|
432
|
+
* `subscription.refund_rejected`: INVO rejected the request; nothing moved. Your
|
|
433
|
+
* `clientRequestId` now answers `409 REFUND_REQUEST_REJECTED`; use a new one to try again.
|
|
434
|
+
*/
|
|
435
|
+
interface SubscriptionRefundRejectedData extends SubscriptionRefundRequestData {
|
|
436
|
+
decided_at: string;
|
|
437
|
+
decision_reason: string | null;
|
|
438
|
+
}
|
|
340
439
|
type PurchaseEventType = "purchase.failed" | "purchase.refunded" | "purchase.disputed" | "purchase.fraud_warning";
|
|
341
440
|
type TransferEventType = "transfer.sent" | "transfer.received" | "transfer.claim_pending" | "transfer.claim_expired" | "transfer.refunded";
|
|
342
441
|
/**
|
|
@@ -382,6 +481,15 @@ type InvoWebhookEvent = (WebhookBase & {
|
|
|
382
481
|
}) | (WebhookBase & {
|
|
383
482
|
event_type: "subscription.refunded";
|
|
384
483
|
data: SubscriptionRefundedData;
|
|
484
|
+
}) | (WebhookBase & {
|
|
485
|
+
event_type: "subscription.refund_requested";
|
|
486
|
+
data: SubscriptionRefundRequestData;
|
|
487
|
+
}) | (WebhookBase & {
|
|
488
|
+
event_type: "subscription.refund_approved";
|
|
489
|
+
data: SubscriptionRefundApprovedData;
|
|
490
|
+
}) | (WebhookBase & {
|
|
491
|
+
event_type: "subscription.refund_rejected";
|
|
492
|
+
data: SubscriptionRefundRejectedData;
|
|
385
493
|
}) | (WebhookBase & {
|
|
386
494
|
event_type: "payout.status_changed";
|
|
387
495
|
data: Record<string, unknown>;
|
|
@@ -530,8 +638,13 @@ declare class SubscriptionsServer {
|
|
|
530
638
|
* `err.existingSubscriptionId`) at best and a second subscription at worst. Same key
|
|
531
639
|
* with different terms is `err.isIdempotentReplayMismatch` (`err.mismatchedFields`).
|
|
532
640
|
*
|
|
533
|
-
* Card
|
|
534
|
-
*
|
|
641
|
+
* Card only (since 2026-09-17): the card is charged the full price every period and the
|
|
642
|
+
* member's coin wallet never pays and never moves. Card selection: `playerCardId` names one
|
|
643
|
+
* (from `cards.list`); omitted, INVO attaches the member's newest unexpired saved card. With
|
|
644
|
+
* no saved card the subscription is still created (201) but `firstCharge` is `failed` with
|
|
645
|
+
* `failureCode: "no_payment_method"`, whatever the member's balance: save a card first.
|
|
646
|
+
* `walletOnly: true` is deprecated: it never charges a card, so such a subscription can never
|
|
647
|
+
* be paid (`failureCode: "wallet_only"`).
|
|
535
648
|
* Requires the game to be `live` (`err.isGameNotLive`).
|
|
536
649
|
*/
|
|
537
650
|
create(input: CreateSubscriptionInput, opts?: CallOptions): Promise<SubscriptionResult>;
|
|
@@ -572,9 +685,9 @@ declare class SubscriptionsServer {
|
|
|
572
685
|
/**
|
|
573
686
|
* Card subscriptions only. Attach a card (`{ playerCardId }`, an `id` from
|
|
574
687
|
* `cards.list` belonging to this player, unexpired) or make the subscription wallet-only
|
|
575
|
-
* (`{ walletOnly: true }
|
|
576
|
-
*
|
|
577
|
-
* including a pending retry in dunning.
|
|
688
|
+
* (`{ walletOnly: true }`, deprecated: a wallet-only card subscription can never be paid).
|
|
689
|
+
* On a wallet-only subscription pass `walletOnly: false` beside the card to convert it
|
|
690
|
+
* back. The new card is used from the next charge, including a pending retry in dunning.
|
|
578
691
|
*
|
|
579
692
|
* `err.isNotACardSubscription` on Steam; `err.isSubscriptionTerminal` on a terminal row.
|
|
580
693
|
*/
|
|
@@ -583,16 +696,35 @@ declare class SubscriptionsServer {
|
|
|
583
696
|
* Refund a billed period (card rail). Idempotent on `clientRequestId`: a repeat returns
|
|
584
697
|
* the stored receipt with `idempotentReplay: true` and moves nothing.
|
|
585
698
|
*
|
|
586
|
-
*
|
|
587
|
-
* (
|
|
588
|
-
*
|
|
589
|
-
*
|
|
590
|
-
*
|
|
591
|
-
*
|
|
699
|
+
* **Branch on `status`.** `"refunded"` (HTTP 200): the refund ran. `"pending_approval"`
|
|
700
|
+
* (HTTP 202): the refund would exceed the game's daily self-serve limit ($500 per UTC day
|
|
701
|
+
* by default), NOTHING moved, and INVO reviews it as a refund request (`requestId`); the
|
|
702
|
+
* outcome arrives as `subscription.refund_approved` (sent together with
|
|
703
|
+
* `subscription.refunded`, and `subscription.canceled` on a full refund, in any order) or
|
|
704
|
+
* `subscription.refund_rejected`. The 202 carries every receipt field with nothing moved
|
|
705
|
+
* (`refundedAmountUsd` is `"0.00"`; `totalRefundedAmountUsd` and `remainingRefundableUsd`
|
|
706
|
+
* carry the period's real values). Check it with {@link isRefundPendingApproval}.
|
|
592
707
|
*
|
|
593
|
-
*
|
|
594
|
-
* `
|
|
595
|
-
*
|
|
708
|
+
* A card-only period (every card period charged since 2026-09-17) is refunded in cash, full
|
|
709
|
+
* or partial: `cardRefundedUsd` equals the amount and `balanceDeltaCoins` is `"0.00"`. A
|
|
710
|
+
* period charged before that keeps the earlier rule: a full refund returns the card charge
|
|
711
|
+
* and reclaims the coins it minted (`balanceDeltaCoins` is signed), a partial refund
|
|
712
|
+
* credits coins. Your revenue is reversed for the refunded portion
|
|
713
|
+
* (`partnerRevenueReversedUsd`), INVO's fee is retained, and on a card refund you bear the
|
|
714
|
+
* processor fee (`processingFeeUsd`; `partnerTotalReversedUsd` is the sum). **A full refund
|
|
715
|
+
* cancels the subscription** (`subscriptionCanceled`, and a `subscription.canceled` event
|
|
716
|
+
* with `cancel_cause: "full_refund"`, sent together with `subscription.refunded` in any
|
|
717
|
+
* order); a partial one does not. INVO emails the member.
|
|
718
|
+
* Refunds run within 30 days of the period's charge. Send a `reason`: it is recommended now
|
|
719
|
+
* and will be required later (`warnings` says so when it is missing).
|
|
720
|
+
*
|
|
721
|
+
* Refusals: `err.isRefundsNotEnabled` (403), `err.isRefundWindowClosed` (409),
|
|
722
|
+
* `err.isRefundRequestPending` (409, `err.refundRequestId`), `err.isRefundRequestRejected`
|
|
723
|
+
* (409, use a new key), `err.isConcurrentRequest` (409, retry with the same key),
|
|
724
|
+
* `err.isRefundMismatch` (502, contact INVO), `NO_PAID_PERIOD` (409, nothing collected yet),
|
|
725
|
+
* `PERIOD_NOT_REFUNDABLE`, `ALREADY_REFUNDED` (`err.isAlreadyRefunded`),
|
|
726
|
+
* `AMOUNT_EXCEEDS_REMAINING` (body carries `remaining_refundable_usd`),
|
|
727
|
+
* `err.isSteamRefundNotSupported`, `err.isFlowPaused`.
|
|
596
728
|
*/
|
|
597
729
|
refund(subscriptionId: string, input: RefundSubscriptionInput, opts?: CallOptions): Promise<RefundResult>;
|
|
598
730
|
/**
|
|
@@ -643,16 +775,58 @@ declare class SubscriptionsServer {
|
|
|
643
775
|
/**
|
|
644
776
|
* Saved cards for off-session (recurring) use: the card capture a card subscription
|
|
645
777
|
* needs. Reached as `invo.cards.*`. The subscription endpoints never receive card data
|
|
646
|
-
* and neither does this SDK
|
|
647
|
-
*
|
|
648
|
-
*
|
|
649
|
-
*
|
|
778
|
+
* and neither does this SDK.
|
|
779
|
+
*
|
|
780
|
+
* THE RECOMMENDED CAPTURE IS {@link createSetupSession}: INVO hosts the card page, you
|
|
781
|
+
* mint a link server-side and send the member to it, and nothing in your integration
|
|
782
|
+
* references a card processor or loads its script. {@link beginSetup} /
|
|
783
|
+
* {@link confirmSetup} are the processor-bound alternative for a partner who already
|
|
784
|
+
* runs a card form in their own client against INVO's current processor.
|
|
785
|
+
*
|
|
786
|
+
* A card saved through the hosted CHECKOUT page, or through a `savedCardId` purchase,
|
|
787
|
+
* does NOT carry the off-session consent a subscription needs; capture it here (or with
|
|
788
|
+
* a `purchaseCurrency` that sets `save_card: true`).
|
|
650
789
|
*/
|
|
651
790
|
declare class CardsServer {
|
|
652
791
|
private readonly http;
|
|
653
792
|
private readonly auth;
|
|
654
793
|
constructor(http: Http, auth: AuthHeader);
|
|
655
794
|
/**
|
|
795
|
+
* Mint a short-lived session for the INVO-hosted card page and return its URL. THE
|
|
796
|
+
* RECOMMENDED WAY TO SAVE A CARD FOR A SUBSCRIPTION: two server-to-server calls (this
|
|
797
|
+
* one, then `cards.list`) and one redirect. No browser code, no processor script, no
|
|
798
|
+
* client secret; INVO can change card processor without you changing anything.
|
|
799
|
+
*
|
|
800
|
+
* The member must already exist in this game (`err.isPlayerNotFound`, 404); the page
|
|
801
|
+
* never creates players. Send the member to `result.cardSetupUrl` top-level (do not
|
|
802
|
+
* frame it). The page says in words that no money moves, saves the card, and then
|
|
803
|
+
* redirects to `successUrl` (or shows "Card saved" when you gave none). The saved card
|
|
804
|
+
* appears in {@link list} immediately, carries the off-session consent a subscription
|
|
805
|
+
* needs, and is indistinguishable from one saved any other way. There is no event for
|
|
806
|
+
* a saved card; `cards.list` is the signal.
|
|
807
|
+
*
|
|
808
|
+
* The session lives 10 minutes (entering a card is one sitting); mint it when the
|
|
809
|
+
* member is about to use it. The link may be reloaded freely before the save; once the
|
|
810
|
+
* card is saved the link is spent and reopening it returns the same card again.
|
|
811
|
+
* `successUrl` is redirected to verbatim (nothing appended) and `metadata` is stored on
|
|
812
|
+
* the session and not returned anywhere today, so put your own correlation id in
|
|
813
|
+
* `successUrl`.
|
|
814
|
+
*
|
|
815
|
+
* Refusals: `err.isInvalidPlayerEmail` (400, a non-email string; a missing or blank
|
|
816
|
+
* `playerEmail` is refused here first with `status: 0`), `err.isPlayerNotFound` (404),
|
|
817
|
+
* `err.isInvalidInput` (400: a script-scheme `successUrl` / `cancelUrl`; the SDK
|
|
818
|
+
* refuses the same values first with `status: 0`), 401 / 403 on the key or the game
|
|
819
|
+
* (body `{ message }`, no code), 503 when card setup is not available right now.
|
|
820
|
+
* Never auto-retried: each call mints a fresh link, so on a timeout call it again.
|
|
821
|
+
*/
|
|
822
|
+
createSetupSession(input: CardSetupSessionInput, opts?: CallOptions): Promise<CardSetupSessionResult>;
|
|
823
|
+
/**
|
|
824
|
+
* THE PROCESSOR-BOUND ALTERNATIVE to {@link createSetupSession}. Use it only if you
|
|
825
|
+
* already run a card form in your own client against INVO's current card processor:
|
|
826
|
+
* the `clientSecret` it hands back can only be consumed by that processor's client
|
|
827
|
+
* library, so the browser code you write for it will need rework when INVO changes
|
|
828
|
+
* processor. `createSetupSession` does not have that problem.
|
|
829
|
+
*
|
|
656
830
|
* Begin saving a card (charges nothing). The player must already exist in this game
|
|
657
831
|
* (`404 PLAYER_NOT_FOUND`). Idempotent on `setupReference`: resend the same value on a
|
|
658
832
|
* retry and you get the same setup back (`409 SETUP_REFERENCE_REUSED` if you reuse it
|
|
@@ -667,6 +841,9 @@ declare class CardsServer {
|
|
|
667
841
|
*/
|
|
668
842
|
beginSetup(input: CardSetupInput, opts?: CallOptions): Promise<CardSetupResult>;
|
|
669
843
|
/**
|
|
844
|
+
* The second half of the processor-bound alternative (see {@link beginSetup}); not
|
|
845
|
+
* needed on the {@link createSetupSession} path, where INVO's page completes the save.
|
|
846
|
+
*
|
|
670
847
|
* Finish a client-confirmed setup and save the card. Idempotent on `setupIntentId`.
|
|
671
848
|
* While the client has not finished, this throws a 400 with body
|
|
672
849
|
* `status: "still_requires_action"`. On `500 CARD_PERSIST_FAILED` (authorised but not
|
|
@@ -677,7 +854,8 @@ declare class CardsServer {
|
|
|
677
854
|
* A member's unexpired saved cards, newest first. An unknown player is `{ cards: [] }`.
|
|
678
855
|
* The `id` is the value you pass as `playerCardId`; INVO never returns processor
|
|
679
856
|
* identifiers for a card. Served from a short cache (about 60 s); a card saved through
|
|
680
|
-
* `beginSetup` / `confirmSetup`
|
|
857
|
+
* the hosted card page (`createSetupSession`) or through `beginSetup` / `confirmSetup`
|
|
858
|
+
* appears immediately. This read is the signal that the hosted page saved a card.
|
|
681
859
|
*/
|
|
682
860
|
list(playerEmail: string, opts?: CallOptions): Promise<PlayerCardsResult>;
|
|
683
861
|
}
|
|
@@ -712,7 +890,8 @@ declare class SandboxSubscriptionsServer {
|
|
|
712
890
|
advanceClock(subscriptionId: string, intervals?: number, opts?: CallOptions): Promise<SandboxClockResult>;
|
|
713
891
|
/**
|
|
714
892
|
* Run the renewal immediately. **Charges the test card** (or the Steam stand-in): the
|
|
715
|
-
* real money path
|
|
893
|
+
* real money path (card: the full price; Steam: wallet first, then the shortfall), mint,
|
|
894
|
+
* spend, split, `subscription.renewed`,
|
|
716
895
|
* and on failure the real dunning. Read `engineStats` (`renewed: 1` on success). A
|
|
717
896
|
* cancel-at-period-end row answers `action: "retired-at-period-end"`, `retired: true`.
|
|
718
897
|
* `409 PERIOD_TOO_FAR_AHEAD` means you forced twice without advancing the clock.
|
|
@@ -1148,4 +1327,4 @@ declare class InvoServer {
|
|
|
1148
1327
|
private toInitiateResult;
|
|
1149
1328
|
}
|
|
1150
1329
|
|
|
1151
|
-
export { ApproveWithDeviceCodeInput, BeginDeviceApprovalInput, CallOptions, CancelResult, CancelSubscriptionOptions, CardSetupConfirmInput, CardSetupConfirmResult, CardSetupInput, CardSetupResult, CardsServer, ChangeAmountResult, ClaimCurrencyInput, ClaimResult, ClaimTransferInput, CompleteDeviceApprovalInput, CompleteDeviceApprovalResult, ConfirmDeviceEnrollmentInput, ConfirmDeviceEnrollmentResult, ConfirmPaymentResult, CreateCheckoutInput, CreateCheckoutResult, CreateSubscriptionInput, DestinationsResult, DeviceApprovalGrant, DeviceApprovalPollResult, DeviceApprovalSettleResult, GetSubscriptionOptions, GetSubscriptionResult, GuardianApprovalStatusResult, InboundPendingQuery, InboundPendingResult, InitiateResult, InitiateSendInput, InitiateTransferInput, InvoError, InvoServer, type InvoWebhookEvent, ItemHistoryQuery, ItemHistoryResult, ItemOrderQuery, type ItemPurchasedData, LinkedIdentitiesQuery, LinkedIdentitiesResult, ListSubscriptionsOptions, OrderDetailsResult, PhoneShareApproveInput, PhoneShareApproveResult, PhoneShareContact, PhoneShareInitiateResult, PhoneShareStatusResult, type PlatformCommercePurchasedData, type PlatformCommerceRefundedData, PlatformCommerceServer, PlatformOrderStatusResult, PlatformPurchaseInput, PlatformPurchaseResult, PlatformRefundInput, PlatformRefundResult, PlayerBalanceQuery, PlayerBalanceResult, PlayerCardsResult, PlayerToken, PollDeviceApprovalInput, type PurchaseCompletedData, type PurchaseEventData, PurchaseInput, PurchaseItemInput, PurchaseItemResult, PurchaseResult, RefundResult, RefundSubscriptionInput, SDK_VERSION, SandboxClockResult, SandboxFailureOutcome, SandboxForceAuthChallengeOptions, SandboxForceFailureOptions, SandboxServer, SandboxSubscriptionsServer, ServerConfig, ServerDestinationsQuery, SetPaymentMethodInput, SetPaymentMethodResult, SmsVerifyResult, SteamFinalizeInput, SteamFinalizeResult, SteamFinalizeSubscriptionResult, SteamInitPurchaseInput, SteamInitPurchaseResult, SteamInitResult, SteamPacksQuery, SteamPacksResult, SteamSubscriptionInitInput, type SubscriptionAuthenticationRequiredData, type SubscriptionCanceledData, type SubscriptionEventCommon, type SubscriptionExpiredData, SubscriptionListResult, type SubscriptionPastDueData, type SubscriptionPaymentFailedData, type SubscriptionRefundDetail, type SubscriptionRefundedData, type SubscriptionRenewalFunding, type SubscriptionRenewalSplit, type SubscriptionRenewedData, SubscriptionResult, type SubscriptionRevenueShareAttribution, SubscriptionsServer, TransactionStatusResult, type TransferEventData, type VerifyWebhookOptions, type WebhookHandlerOptions, createWebhookHandler, verifyWebhook, verifyWebhookAsync };
|
|
1330
|
+
export { ApproveWithDeviceCodeInput, BeginDeviceApprovalInput, CallOptions, CancelResult, CancelSubscriptionOptions, CardSetupConfirmInput, CardSetupConfirmResult, CardSetupInput, CardSetupResult, CardSetupSessionInput, CardSetupSessionResult, CardsServer, ChangeAmountResult, ClaimCurrencyInput, ClaimResult, ClaimTransferInput, CompleteDeviceApprovalInput, CompleteDeviceApprovalResult, ConfirmDeviceEnrollmentInput, ConfirmDeviceEnrollmentResult, ConfirmPaymentResult, CreateCheckoutInput, CreateCheckoutResult, CreateSubscriptionInput, DestinationsResult, DeviceApprovalGrant, DeviceApprovalPollResult, DeviceApprovalSettleResult, GetSubscriptionOptions, GetSubscriptionResult, GuardianApprovalStatusResult, InboundPendingQuery, InboundPendingResult, InitiateResult, InitiateSendInput, InitiateTransferInput, InvoError, InvoServer, type InvoWebhookEvent, ItemHistoryQuery, ItemHistoryResult, ItemOrderQuery, type ItemPurchasedData, LinkedIdentitiesQuery, LinkedIdentitiesResult, ListSubscriptionsOptions, OrderDetailsResult, PhoneShareApproveInput, PhoneShareApproveResult, PhoneShareContact, PhoneShareInitiateResult, PhoneShareStatusResult, type PlatformCommercePurchasedData, type PlatformCommerceRefundedData, PlatformCommerceServer, PlatformOrderStatusResult, PlatformPurchaseInput, PlatformPurchaseResult, PlatformRefundInput, PlatformRefundResult, PlayerBalanceQuery, PlayerBalanceResult, PlayerCardsResult, PlayerToken, PollDeviceApprovalInput, type PurchaseCompletedData, type PurchaseEventData, PurchaseInput, PurchaseItemInput, PurchaseItemResult, PurchaseResult, RefundResult, RefundSubscriptionInput, SDK_VERSION, SandboxClockResult, SandboxFailureOutcome, SandboxForceAuthChallengeOptions, SandboxForceFailureOptions, SandboxServer, SandboxSubscriptionsServer, ServerConfig, ServerDestinationsQuery, SetPaymentMethodInput, SetPaymentMethodResult, SmsVerifyResult, SteamFinalizeInput, SteamFinalizeResult, SteamFinalizeSubscriptionResult, SteamInitPurchaseInput, SteamInitPurchaseResult, SteamInitResult, SteamPacksQuery, SteamPacksResult, SteamSubscriptionInitInput, type SubscriptionAuthenticationRequiredData, type SubscriptionCanceledData, type SubscriptionEventCommon, type SubscriptionExpiredData, SubscriptionListResult, type SubscriptionPastDueData, type SubscriptionPaymentFailedData, type SubscriptionRefundApprovedData, type SubscriptionRefundDetail, type SubscriptionRefundRejectedData, type SubscriptionRefundRequestData, type SubscriptionRefundedData, type SubscriptionRenewalFunding, type SubscriptionRenewalSplit, type SubscriptionRenewedData, SubscriptionResult, type SubscriptionRevenueShareAttribution, SubscriptionsServer, TransactionStatusResult, type TransferEventData, type VerifyWebhookOptions, type WebhookHandlerOptions, createWebhookHandler, verifyWebhook, verifyWebhookAsync };
|