@invonetwork/web-sdk 3.7.0 → 3.8.1
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 +48 -0
- package/README.md +334 -2
- package/dist/{chunk-23TGMTII.js → chunk-HYGBTUEJ.js} +105 -5
- package/dist/index.cjs +103 -3
- package/dist/index.d.cts +2 -2
- package/dist/index.d.ts +2 -2
- package/dist/index.js +2 -2
- package/dist/server.cjs +964 -4
- package/dist/server.d.cts +500 -3
- package/dist/server.d.ts +500 -3
- package/dist/server.js +858 -4
- package/dist/{types-CspPkmK9.d.cts → types-DqRuqbqI.d.cts} +593 -1
- package/dist/{types-CspPkmK9.d.ts → types-DqRuqbqI.d.ts} +593 -1
- package/package.json +1 -1
|
@@ -369,6 +369,73 @@ declare class InvoError extends Error {
|
|
|
369
369
|
* it to INVO support gets the cause in one message instead of a description of symptoms.
|
|
370
370
|
*/
|
|
371
371
|
get errorRef(): string | undefined;
|
|
372
|
+
/**
|
|
373
|
+
* True when a create (`subscriptions.create` / `steamInit`) was refused because the
|
|
374
|
+
* player already has a LIVE subscription to this `itemId` (`ACTIVE_SUBSCRIPTION_EXISTS`,
|
|
375
|
+
* 409). Use `existingSubscriptionId`. This is what you hit if you regenerate
|
|
376
|
+
* `clientRequestId` inside a retry loop: replay the same key instead.
|
|
377
|
+
*/
|
|
378
|
+
get isActiveSubscriptionExists(): boolean;
|
|
379
|
+
/**
|
|
380
|
+
* The `subscription_id` a create refusal names: the LIVE subscription on
|
|
381
|
+
* `ACTIVE_SUBSCRIPTION_EXISTS`, the PENDING Steam row on `STEAM_AUTHORIZATION_PENDING`,
|
|
382
|
+
* or the abandoned (now `expired`) row when a Steam-side failure abandoned it after creation.
|
|
383
|
+
*/
|
|
384
|
+
get existingSubscriptionId(): string | undefined;
|
|
385
|
+
/**
|
|
386
|
+
* True when the same `clientRequestId` was replayed for the same player and item but
|
|
387
|
+
* with DIFFERENT material terms (`IDEMPOTENT_REPLAY_MISMATCH`, 409). See
|
|
388
|
+
* `mismatchedFields` (any of `amount_usd`, `interval`, `interval_count`, `wallet_only`,
|
|
389
|
+
* `funding_rail`). To change terms use `changeAmount` / `setPaymentMethod`; to create a
|
|
390
|
+
* new subscription use a new key.
|
|
391
|
+
*/
|
|
392
|
+
get isIdempotentReplayMismatch(): boolean;
|
|
393
|
+
/** The `mismatched_fields` on an `IDEMPOTENT_REPLAY_MISMATCH` 409. */
|
|
394
|
+
get mismatchedFields(): string[];
|
|
395
|
+
/**
|
|
396
|
+
* True when `changeAmount` tried to RAISE the price of a Steam subscription
|
|
397
|
+
* (`STEAM_REAUTHORIZATION_REQUIRED`, 409). The member consented to a ceiling; start a
|
|
398
|
+
* new Steam subscription at the new price and cancel this one. Decreases stage normally.
|
|
399
|
+
* The body carries `current_amount_usd` and `requested_amount_usd`.
|
|
400
|
+
*/
|
|
401
|
+
get isSteamReauthorizationRequired(): boolean;
|
|
402
|
+
/** True when `setPaymentMethod` was called on a Steam subscription (`NOT_A_CARD_SUBSCRIPTION`, 409). A rail is fixed at creation. */
|
|
403
|
+
get isNotACardSubscription(): boolean;
|
|
404
|
+
/**
|
|
405
|
+
* True when a Steam subscription was started with a key for a non-Steam channel
|
|
406
|
+
* (`STEAM_CHANNEL_REQUIRED`, 409). Use the primary game key or the `steam` channel key.
|
|
407
|
+
*/
|
|
408
|
+
get isSteamChannelRequired(): boolean;
|
|
409
|
+
/**
|
|
410
|
+
* True when `subscriptions.refund` targeted a period that was charged through Steam
|
|
411
|
+
* (`STEAM_REFUND_NOT_SUPPORTED`, 409). Refunds of Steam-charged periods are not
|
|
412
|
+
* supported yet; periods of a Steam subscription that the wallet covered entirely
|
|
413
|
+
* remain refundable in coins.
|
|
414
|
+
*/
|
|
415
|
+
get isSteamRefundNotSupported(): boolean;
|
|
416
|
+
/** True when the subscription is `canceled` or `expired` and the call cannot apply (`SUBSCRIPTION_TERMINAL`, 409). Start a new one. */
|
|
417
|
+
get isSubscriptionTerminal(): boolean;
|
|
418
|
+
/**
|
|
419
|
+
* True when `subscriptions.steamFinalize` was called before the member completed the
|
|
420
|
+
* Steam authorisation (409, body `status: "not_authorized"`, with `steam_status`).
|
|
421
|
+
* THE NORMAL WAIT STATE: call finalize again after the overlay or checkout closes.
|
|
422
|
+
* The member has 24 hours; after that the row expires.
|
|
423
|
+
*/
|
|
424
|
+
get isNotAuthorized(): boolean;
|
|
425
|
+
/**
|
|
426
|
+
* True when a sandbox clock call was refused for a missing, wrong or never-issued
|
|
427
|
+
* `X-Sandbox-Clock-Key` (`SANDBOX_CLOCK_UNAUTHORIZED`, 401). Reveal or rotate the key on
|
|
428
|
+
* the game's Game Settings page in the sandbox console.
|
|
429
|
+
*/
|
|
430
|
+
get isSandboxClockUnauthorized(): boolean;
|
|
431
|
+
/**
|
|
432
|
+
* True when INVO has paused this flow for maintenance (503): `flow_paused` on create /
|
|
433
|
+
* amount / payment-method / Steam init / card setup, `FLOW_PAUSED` on refund and the
|
|
434
|
+
* sandbox clock. Retry later WITH THE SAME idempotency key.
|
|
435
|
+
*/
|
|
436
|
+
get isFlowPaused(): boolean;
|
|
437
|
+
/** True when a create was refused because the game is not `live` (`GAME_NOT_LIVE`, 403). Make it live in the console. */
|
|
438
|
+
get isGameNotLive(): boolean;
|
|
372
439
|
/** Seconds to wait before retrying, when the backend throttled the call (429 `retry_after`). */
|
|
373
440
|
get retryAfter(): number | undefined;
|
|
374
441
|
/** `body` as a plain object, or `{}` if it's a string/number/null (non-JSON responses).
|
|
@@ -446,9 +513,11 @@ declare class Http {
|
|
|
446
513
|
post<T = Record<string, unknown>>(path: string, body: Record<string, unknown> | undefined, auth: AuthHeader, opts?: {
|
|
447
514
|
idempotent?: boolean;
|
|
448
515
|
signal?: AbortSignal;
|
|
516
|
+
headers?: Record<string, string>;
|
|
449
517
|
}): Promise<T>;
|
|
450
518
|
get<T = Record<string, unknown>>(path: string, auth: AuthHeader, opts?: {
|
|
451
519
|
signal?: AbortSignal;
|
|
520
|
+
headers?: Record<string, string>;
|
|
452
521
|
}): Promise<T>;
|
|
453
522
|
private authHeaders;
|
|
454
523
|
private request;
|
|
@@ -496,6 +565,14 @@ interface InvoConfig {
|
|
|
496
565
|
interface ServerConfig extends InvoConfig {
|
|
497
566
|
/** The game secret. Server-side ONLY — never ship this to a browser. */
|
|
498
567
|
gameSecret: string;
|
|
568
|
+
/**
|
|
569
|
+
* The per-game **sandbox clock key** (`ivclk_...`) from the sandbox console (Game
|
|
570
|
+
* Settings → "Sandbox clock key"). Sent as `X-Sandbox-Clock-Key` by
|
|
571
|
+
* `invo.sandbox.subscriptions.*` only. Optional; those methods throw `INVALID_INPUT`
|
|
572
|
+
* before the network when it is missing. Has no effect outside sandbox. Server-side
|
|
573
|
+
* only — keep it out of game clients and source control.
|
|
574
|
+
*/
|
|
575
|
+
sandboxClockKey?: string;
|
|
499
576
|
}
|
|
500
577
|
interface ClientConfig extends InvoConfig {
|
|
501
578
|
/** Short-lived, game-scoped player token minted server-side via mintPlayerToken(). */
|
|
@@ -1438,5 +1515,520 @@ interface CompleteDeviceApprovalResult {
|
|
|
1438
1515
|
/** The last poll seen, for diagnostics. */
|
|
1439
1516
|
lastPoll?: DeviceApprovalPollResult;
|
|
1440
1517
|
}
|
|
1518
|
+
/** Which rail funds the wallet shortfall. Fixed at creation. */
|
|
1519
|
+
type SubscriptionFundingRail = "card" | "steam";
|
|
1520
|
+
/** `month` (default) or `year`. */
|
|
1521
|
+
type SubscriptionInterval = "month" | "year";
|
|
1522
|
+
/**
|
|
1523
|
+
* Subscription lifecycle. "Live" (`trialing`, `active`, `past_due`,
|
|
1524
|
+
* `awaiting_authentication`) occupies the one-live-per-item slot and is touched by the
|
|
1525
|
+
* renewal engine. `pending_steam_authorization` is Steam-only and not yet billable.
|
|
1526
|
+
* `canceled` and `expired` are terminal.
|
|
1527
|
+
*/
|
|
1528
|
+
type SubscriptionStatus = "trialing" | "active" | "past_due" | "awaiting_authentication" | "pending_steam_authorization" | "canceled" | "expired";
|
|
1529
|
+
/** Evidence the member agreed to the recurring charge. Stored verbatim, returned on every read. */
|
|
1530
|
+
interface SubscriptionConsentInput {
|
|
1531
|
+
/** ISO 8601. Not more than 5 minutes in the future. */
|
|
1532
|
+
consentAt?: string;
|
|
1533
|
+
/** The MEMBER's IP as your server saw it (INVO sees your server's). Max 45 chars. */
|
|
1534
|
+
consentIp?: string;
|
|
1535
|
+
/** Truncated to 500. */
|
|
1536
|
+
consentUserAgent?: string;
|
|
1537
|
+
/** The price you showed the member; should equal `amountUsd`. Decimal string. */
|
|
1538
|
+
disclosedAmountUsd?: string;
|
|
1539
|
+
/** The interval you showed the member. */
|
|
1540
|
+
disclosedInterval?: SubscriptionInterval;
|
|
1541
|
+
/** Your terms version, max 50. */
|
|
1542
|
+
termsVersion?: string;
|
|
1543
|
+
}
|
|
1544
|
+
/** The `consent` block as INVO returns it: six fields, all `null` until supplied. */
|
|
1545
|
+
interface SubscriptionConsent {
|
|
1546
|
+
consent_at: string | null;
|
|
1547
|
+
consent_ip: string | null;
|
|
1548
|
+
consent_user_agent: string | null;
|
|
1549
|
+
disclosed_amount_usd: string | null;
|
|
1550
|
+
disclosed_interval: string | null;
|
|
1551
|
+
terms_version: string | null;
|
|
1552
|
+
}
|
|
1553
|
+
/**
|
|
1554
|
+
* Attribution to a second player in your game, and ATTRIBUTION ONLY. INVO records the
|
|
1555
|
+
* share and reports it on every `subscription.renewed`; INVO pays the recipient nothing
|
|
1556
|
+
* (`settledByInvo` is always `false`). Provide EXACTLY ONE of `recipientPlayerEmail` /
|
|
1557
|
+
* `recipientPlayerId`. `percent` is `0` to `100`, two decimals.
|
|
1558
|
+
*/
|
|
1559
|
+
interface SubscriptionRevenueShareInput {
|
|
1560
|
+
recipientPlayerEmail?: string;
|
|
1561
|
+
recipientPlayerId?: number;
|
|
1562
|
+
percent: string | number;
|
|
1563
|
+
}
|
|
1564
|
+
interface SubscriptionRevenueShare {
|
|
1565
|
+
recipientPlayerId: number;
|
|
1566
|
+
percent: string;
|
|
1567
|
+
/** Always `false`: you pay the recipient yourself, out of your own revenue. */
|
|
1568
|
+
settledByInvo: boolean;
|
|
1569
|
+
}
|
|
1570
|
+
/**
|
|
1571
|
+
* The subscription object, as every read and every mutation returns it.
|
|
1572
|
+
*
|
|
1573
|
+
* TWO CLOCKS, not one: `currentPeriodStart`/`currentPeriodEnd` is the billing WINDOW (a
|
|
1574
|
+
* projection that exists from the instant of creation); `paidThrough` is the ENTITLEMENT
|
|
1575
|
+
* boundary (the furthest date the member has actually paid for; `null` until a period
|
|
1576
|
+
* has charged). Grant access from `paidThrough`, never from `currentPeriodEnd`.
|
|
1577
|
+
*/
|
|
1578
|
+
interface Subscription {
|
|
1579
|
+
/** `SUB_<epoch>_<8 chars>`. Not a secret; every call is still scoped by your key. */
|
|
1580
|
+
subscriptionId: string;
|
|
1581
|
+
gameId: string;
|
|
1582
|
+
playerId: number;
|
|
1583
|
+
/** Your idempotency key. */
|
|
1584
|
+
clientRequestId: string;
|
|
1585
|
+
status: SubscriptionStatus;
|
|
1586
|
+
/** The current price, decimal string. */
|
|
1587
|
+
amountUsd: string;
|
|
1588
|
+
/** A staged price change not yet applied, or `null`. */
|
|
1589
|
+
pendingAmountUsd: string | null;
|
|
1590
|
+
interval: SubscriptionInterval;
|
|
1591
|
+
intervalCount: number;
|
|
1592
|
+
itemId: string;
|
|
1593
|
+
itemName: string | null;
|
|
1594
|
+
/** The billing window. NOT entitlement. */
|
|
1595
|
+
currentPeriodStart: string;
|
|
1596
|
+
currentPeriodEnd: string;
|
|
1597
|
+
/** 1-based counter of billing periods; advances on every successful charge. */
|
|
1598
|
+
periodSeq: number;
|
|
1599
|
+
/** When INVO next touches the subscription (also the retry time in dunning and the
|
|
1600
|
+
* challenge deadline in `awaiting_authentication`). `null` on terminal rows and on
|
|
1601
|
+
* `pending_steam_authorization`. */
|
|
1602
|
+
nextChargeAt: string | null;
|
|
1603
|
+
cancelAtPeriodEnd: boolean;
|
|
1604
|
+
trialEnd: string | null;
|
|
1605
|
+
canceledAt: string | null;
|
|
1606
|
+
endedAt: string | null;
|
|
1607
|
+
walletOnly: boolean;
|
|
1608
|
+
/** A card is attached. Never the card's identifiers. */
|
|
1609
|
+
hasPaymentMethod: boolean;
|
|
1610
|
+
fundingRail: SubscriptionFundingRail;
|
|
1611
|
+
/** `pending` | `active` | `canceled`, or `null` on card subscriptions. */
|
|
1612
|
+
steamAgreementStatus: string | null;
|
|
1613
|
+
metadata: Record<string, unknown> | null;
|
|
1614
|
+
consent: SubscriptionConsent;
|
|
1615
|
+
createdAt: string;
|
|
1616
|
+
updatedAt: string;
|
|
1617
|
+
revenueShare: SubscriptionRevenueShare | null;
|
|
1618
|
+
/** THE ENTITLEMENT BOUNDARY. `null` until a period has been charged. */
|
|
1619
|
+
paidThrough: string | null;
|
|
1620
|
+
/** Create/finalize responses only: what one period is worth in coins on this rail. */
|
|
1621
|
+
amountCoinsEstimate?: string;
|
|
1622
|
+
raw: Record<string, unknown>;
|
|
1623
|
+
}
|
|
1624
|
+
/** A saved card as INVO describes it. `id` is the only handle; never a processor id. */
|
|
1625
|
+
interface SavedCard {
|
|
1626
|
+
id: number;
|
|
1627
|
+
lastFour: string;
|
|
1628
|
+
brand: string;
|
|
1629
|
+
expMonth: number;
|
|
1630
|
+
expYear: number;
|
|
1631
|
+
createdAt: string;
|
|
1632
|
+
raw: Record<string, unknown>;
|
|
1633
|
+
}
|
|
1634
|
+
/**
|
|
1635
|
+
* What happened to the money on the first period.
|
|
1636
|
+
* - `paid`: money moved, currency granted; grant access until `paidThrough`.
|
|
1637
|
+
* - `requires_action`: the card issuer wants the cardholder to authenticate. NOTHING
|
|
1638
|
+
* has been charged; send the member to `confirmationUrl` before `expiresAt`.
|
|
1639
|
+
* - `skipped_trial`: deliberately not charged; the subscription is `trialing`.
|
|
1640
|
+
* - `failed`: the charge did not succeed; the subscription is `past_due` and in dunning.
|
|
1641
|
+
* - `pending`: not resolved yet; wait for `subscription.renewed` / `payment_failed`.
|
|
1642
|
+
* - `pending_authorization`: Steam; nothing charged until the member authorises and
|
|
1643
|
+
* you call `steamFinalize`.
|
|
1644
|
+
*/
|
|
1645
|
+
type FirstChargeStatus = "paid" | "requires_action" | "skipped_trial" | "failed" | "pending" | "pending_authorization";
|
|
1646
|
+
/**
|
|
1647
|
+
* Always carries the same keys, on every outcome. Branch on `status`.
|
|
1648
|
+
*
|
|
1649
|
+
* PERIOD NUMBERING. After a successful first charge `subscription.periodSeq` already
|
|
1650
|
+
* points at the NEXT window (it reads `2`), and the `subscription.renewed` webhook for
|
|
1651
|
+
* the period just paid reports `period_seq: 1`. Key entitlement on `paidPeriodSeq` here
|
|
1652
|
+
* (or the webhook's `period_seq`), never on `subscription.periodSeq`: the two roads
|
|
1653
|
+
* count differently by design.
|
|
1654
|
+
*/
|
|
1655
|
+
interface FirstCharge {
|
|
1656
|
+
status: FirstChargeStatus;
|
|
1657
|
+
/** On `paid`: the amount actually charged for period 1. */
|
|
1658
|
+
amountUsd: string | null;
|
|
1659
|
+
/** The period that was just paid (`1` for the first period). `null` unless `status` is `paid`. */
|
|
1660
|
+
paidPeriodSeq: number | null;
|
|
1661
|
+
/** Same value as `subscription.paidThrough`, repeated so one object answers "what happened". */
|
|
1662
|
+
paidThrough: string | null;
|
|
1663
|
+
failureCode: string | null;
|
|
1664
|
+
nextRetryAt: string | null;
|
|
1665
|
+
/** On `requires_action`: a single-use bearer link. Do not log it beside identifiers you publish. */
|
|
1666
|
+
confirmationUrl: string | null;
|
|
1667
|
+
expiresAt: string | null;
|
|
1668
|
+
message: string | null;
|
|
1669
|
+
raw: Record<string, unknown>;
|
|
1670
|
+
}
|
|
1671
|
+
/** Fields shared by `subscriptions.create` and `subscriptions.steamInit`. */
|
|
1672
|
+
interface SubscriptionBaseInput {
|
|
1673
|
+
/**
|
|
1674
|
+
* Idempotency key: unique per subscription and per player within your game, max 255
|
|
1675
|
+
* chars, must not begin with `sub_`. Generate it ONCE per subscription, persist it, and
|
|
1676
|
+
* reuse it on every retry: a repeat returns the same subscription (`idempotentReplay`).
|
|
1677
|
+
*/
|
|
1678
|
+
clientRequestId: string;
|
|
1679
|
+
/** Identifies the member. Lower-cased server-side. */
|
|
1680
|
+
playerEmail: string;
|
|
1681
|
+
/** Used only if the player does not exist yet. Max 255. */
|
|
1682
|
+
playerName: string;
|
|
1683
|
+
/** Optional; E.164 when supplied (this call can create the player identity). */
|
|
1684
|
+
playerPhone?: string;
|
|
1685
|
+
/** Your entitlement handle. One live subscription per (player, item). */
|
|
1686
|
+
itemId: string;
|
|
1687
|
+
/** Echoed on events. Max 255. */
|
|
1688
|
+
itemName?: string;
|
|
1689
|
+
/** `0.01` to `999999.99`, two decimals. Prices above `500.00` are accepted but never charged. */
|
|
1690
|
+
amountUsd: string | number;
|
|
1691
|
+
/** Default `month`. */
|
|
1692
|
+
interval?: SubscriptionInterval;
|
|
1693
|
+
/** Up to 8192 bytes serialised. Echoed on every read and event. `_invo` is reserved. */
|
|
1694
|
+
metadata?: Record<string, unknown>;
|
|
1695
|
+
/** Supply it: INVO is merchant of record on the card rail and a dispute is argued from this. */
|
|
1696
|
+
consent?: SubscriptionConsentInput;
|
|
1697
|
+
/** Attribution only; INVO pays nothing to the recipient. Set once at create. */
|
|
1698
|
+
revenueShare?: SubscriptionRevenueShareInput;
|
|
1699
|
+
}
|
|
1700
|
+
/** Input for `subscriptions.create` (the CARD rail). */
|
|
1701
|
+
interface CreateSubscriptionInput extends SubscriptionBaseInput {
|
|
1702
|
+
/** 1 (default) to 36. `3` with `month` bills quarterly. */
|
|
1703
|
+
intervalCount?: number;
|
|
1704
|
+
/** 1 to 365. INVO adds up to one hour of jitter to the derived end. */
|
|
1705
|
+
trialDays?: number;
|
|
1706
|
+
/** Explicit ISO 8601 trial end (future, within 365 days). Takes precedence over `trialDays`. */
|
|
1707
|
+
trialEnd?: string;
|
|
1708
|
+
/** Default `false`. `true` opts out of the card backstop; cannot be combined with `playerCardId`. */
|
|
1709
|
+
walletOnly?: boolean;
|
|
1710
|
+
/** The `id` of a card from `cards.list`. Omitted: INVO picks the newest unexpired saved card. */
|
|
1711
|
+
playerCardId?: number;
|
|
1712
|
+
}
|
|
1713
|
+
/** Result of `subscriptions.create` (201, or a 200 replay). */
|
|
1714
|
+
interface SubscriptionResult {
|
|
1715
|
+
/** `success` on the card rail. */
|
|
1716
|
+
status: string;
|
|
1717
|
+
/** `true` when this `clientRequestId` was seen before; nothing was charged again. */
|
|
1718
|
+
idempotentReplay: boolean;
|
|
1719
|
+
subscription: Subscription;
|
|
1720
|
+
/** The card backing the subscription (named or auto-picked), or `null` when none. */
|
|
1721
|
+
card: SavedCard | null;
|
|
1722
|
+
firstCharge: FirstCharge;
|
|
1723
|
+
/** Present on a reduced 201 (INVO created the row but could not render the full body): read it with `get`. */
|
|
1724
|
+
warning?: string;
|
|
1725
|
+
raw: Record<string, unknown>;
|
|
1726
|
+
}
|
|
1727
|
+
/** Input for `subscriptions.steamInit`: the `create` input minus card/trial fields, plus Steam. */
|
|
1728
|
+
interface SteamSubscriptionInitInput extends SubscriptionBaseInput {
|
|
1729
|
+
/** The member's 64-bit Steam id (digits). */
|
|
1730
|
+
steamId: string;
|
|
1731
|
+
/** `client` (default; the member authorises in the Steam overlay) or `web` (a hosted checkout URL). */
|
|
1732
|
+
userSession?: SteamUserSession;
|
|
1733
|
+
/** Required for `web`: the MEMBER's IP as your server sees it, never your server's own. */
|
|
1734
|
+
playerIp?: string;
|
|
1735
|
+
/** Must be `1` on Steam (monthly and yearly only). */
|
|
1736
|
+
intervalCount?: 1;
|
|
1737
|
+
}
|
|
1738
|
+
/** Result of `subscriptions.steamInit` (201, or a 200 replay carrying the row's CURRENT status). */
|
|
1739
|
+
interface SteamInitResult {
|
|
1740
|
+
/** `pending_steam_authorization` on first creation; on a replay, the row's current status. */
|
|
1741
|
+
status: string;
|
|
1742
|
+
subscriptionStatus: string;
|
|
1743
|
+
idempotentReplay: boolean;
|
|
1744
|
+
/**
|
|
1745
|
+
* `true` when a PENDING authorisation for the same player and item with the same terms
|
|
1746
|
+
* was handed back instead of a new agreement being created. Finalize that one. (Same
|
|
1747
|
+
* player and item with DIFFERENT terms throws `409 STEAM_AUTHORIZATION_PENDING`,
|
|
1748
|
+
* `err.isSteamAuthorizationPending`, with the pending `subscription_id` on the body.)
|
|
1749
|
+
*/
|
|
1750
|
+
pendingReuse: boolean;
|
|
1751
|
+
subscription: Subscription;
|
|
1752
|
+
subscriptionId: string;
|
|
1753
|
+
orderId: string;
|
|
1754
|
+
/**
|
|
1755
|
+
* The uint64 order id the Steam client callback's `order_id` echoes. **Match the
|
|
1756
|
+
* callback with this**, then call `steamFinalize`. (It is not `steamTransid`.)
|
|
1757
|
+
*/
|
|
1758
|
+
steamOrderId: string;
|
|
1759
|
+
/** Steam's transaction reference for period 1, for your support tooling only. */
|
|
1760
|
+
steamTransid: string;
|
|
1761
|
+
/** Present only for `userSession: "web"`. Open it as a TOP-LEVEL window; it cannot be framed. */
|
|
1762
|
+
steamCheckoutUrl: string | null;
|
|
1763
|
+
amountUsd: string;
|
|
1764
|
+
/** What one period is worth for THIS member (country-derived). Show it; never price x 10. */
|
|
1765
|
+
amountCoins: string;
|
|
1766
|
+
/** What period 1 will charge (the full price). */
|
|
1767
|
+
steamChargeUsd: string;
|
|
1768
|
+
/** The ceiling the member consents to (the price). */
|
|
1769
|
+
recurringAmountUsd: string;
|
|
1770
|
+
firstCharge: FirstCharge;
|
|
1771
|
+
message: string;
|
|
1772
|
+
raw: Record<string, unknown>;
|
|
1773
|
+
}
|
|
1774
|
+
/** Result of `subscriptions.steamFinalize`: the `SubscriptionResult` plus the finalize flags. */
|
|
1775
|
+
interface SteamFinalizeSubscriptionResult extends SubscriptionResult {
|
|
1776
|
+
/** `true` when already finalised (or a concurrent finalize won). Treat as success. */
|
|
1777
|
+
alreadyProcessed: boolean;
|
|
1778
|
+
/** Normally `active`; `pending` if Steam captured the charge but the agreement is not located yet. */
|
|
1779
|
+
steamAgreementStatus: string | null;
|
|
1780
|
+
/** Sandbox only: the authorisation was simulated, not Valve's. Do one real Steam sandbox run before launch. */
|
|
1781
|
+
sandboxAutoApproved: boolean;
|
|
1782
|
+
}
|
|
1783
|
+
interface GetSubscriptionOptions {
|
|
1784
|
+
/** Adds a `player` block. Default `false`. */
|
|
1785
|
+
includePlayer?: boolean;
|
|
1786
|
+
}
|
|
1787
|
+
interface GetSubscriptionResult {
|
|
1788
|
+
subscription: Subscription;
|
|
1789
|
+
player?: Record<string, unknown>;
|
|
1790
|
+
raw: Record<string, unknown>;
|
|
1791
|
+
}
|
|
1792
|
+
interface ListSubscriptionsOptions {
|
|
1793
|
+
/** One or more statuses; `live` expands to the four live statuses and may be mixed in. */
|
|
1794
|
+
status?: SubscriptionStatus | "live" | Array<SubscriptionStatus | "live">;
|
|
1795
|
+
includePlayer?: boolean;
|
|
1796
|
+
/** 1 to 100, default 50. */
|
|
1797
|
+
limit?: number;
|
|
1798
|
+
/** 0 to 100000, default 0. */
|
|
1799
|
+
offset?: number;
|
|
1800
|
+
}
|
|
1801
|
+
interface SubscriptionListResult {
|
|
1802
|
+
playerEmail: string;
|
|
1803
|
+
/** Newest first with a stable tiebreaker. An unknown player is an empty list, not a 404. */
|
|
1804
|
+
subscriptions: Subscription[];
|
|
1805
|
+
pagination: {
|
|
1806
|
+
totalCount: number;
|
|
1807
|
+
limit: number;
|
|
1808
|
+
offset: number;
|
|
1809
|
+
hasMore: boolean;
|
|
1810
|
+
};
|
|
1811
|
+
raw: Record<string, unknown>;
|
|
1812
|
+
}
|
|
1813
|
+
interface CancelSubscriptionOptions {
|
|
1814
|
+
/** Default `true`. `false` ends the subscription now. */
|
|
1815
|
+
atPeriodEnd?: boolean;
|
|
1816
|
+
/** Stored (max 500) and carried on the `subscription.canceled` event. */
|
|
1817
|
+
reason?: string;
|
|
1818
|
+
}
|
|
1819
|
+
interface CancelResult {
|
|
1820
|
+
status: string;
|
|
1821
|
+
/** `true` when the subscription was already `canceled`/`expired` (a 200, not an error). */
|
|
1822
|
+
alreadyCanceled: boolean;
|
|
1823
|
+
/** On an already-terminal row: its status. */
|
|
1824
|
+
finalStatus?: string;
|
|
1825
|
+
cancelAtPeriodEnd: boolean;
|
|
1826
|
+
effectiveAt: string | null;
|
|
1827
|
+
currentPeriodEnd: string | null;
|
|
1828
|
+
/** Revoke access here. */
|
|
1829
|
+
accessUntil: string | null;
|
|
1830
|
+
paidThrough: string | null;
|
|
1831
|
+
/** `true` when an at-period-end cancel was DOWNGRADED to immediate (nothing paid to preserve). */
|
|
1832
|
+
terminatedImmediately: boolean;
|
|
1833
|
+
/** `NO_PAID_PERIOD` on a downgrade. */
|
|
1834
|
+
downgradeReason?: string;
|
|
1835
|
+
message?: string;
|
|
1836
|
+
/** Steam only. */
|
|
1837
|
+
steamAgreementStatus?: string | null;
|
|
1838
|
+
/** Steam only: whether the agreement was ended at Steam in this call (INVO retries on its own if not). */
|
|
1839
|
+
steamAgreementCanceled?: boolean;
|
|
1840
|
+
subscription: Subscription | null;
|
|
1841
|
+
raw: Record<string, unknown>;
|
|
1842
|
+
}
|
|
1843
|
+
interface ChangeAmountResult {
|
|
1844
|
+
status: string;
|
|
1845
|
+
oldAmountUsd: string;
|
|
1846
|
+
newAmountUsd: string;
|
|
1847
|
+
/** The staged price, or `null` when the change was cleared. */
|
|
1848
|
+
pendingAmountUsd: string | null;
|
|
1849
|
+
changeQueued: boolean;
|
|
1850
|
+
/** `null` until something has been paid. */
|
|
1851
|
+
appliesFrom: string | null;
|
|
1852
|
+
appliesFromPeriodSeq: number;
|
|
1853
|
+
paidThrough: string | null;
|
|
1854
|
+
currentPeriodEnd: string | null;
|
|
1855
|
+
/** Always `false`: no proration. */
|
|
1856
|
+
prorated: boolean;
|
|
1857
|
+
subscription: Subscription | null;
|
|
1858
|
+
raw: Record<string, unknown>;
|
|
1859
|
+
}
|
|
1860
|
+
/** Attach a card (optionally converting a wallet-only subscription), or make it wallet-only. */
|
|
1861
|
+
type SetPaymentMethodInput = {
|
|
1862
|
+
playerCardId: number;
|
|
1863
|
+
walletOnly?: false;
|
|
1864
|
+
} | {
|
|
1865
|
+
walletOnly: true;
|
|
1866
|
+
};
|
|
1867
|
+
interface SetPaymentMethodResult {
|
|
1868
|
+
status: string;
|
|
1869
|
+
replaced: boolean;
|
|
1870
|
+
walletOnly: boolean;
|
|
1871
|
+
card: SavedCard | null;
|
|
1872
|
+
subscription: Subscription | null;
|
|
1873
|
+
raw: Record<string, unknown>;
|
|
1874
|
+
}
|
|
1875
|
+
interface RefundSubscriptionInput {
|
|
1876
|
+
/** One per refund, max 255, not `sub_`-prefixed. Reuse it on retries. */
|
|
1877
|
+
clientRequestId: string;
|
|
1878
|
+
/** Defaults to the most recent billed period. */
|
|
1879
|
+
periodSeq?: number;
|
|
1880
|
+
/** Defaults to the full remaining refundable amount. A partial refund is allowed. */
|
|
1881
|
+
amountUsd?: string | number;
|
|
1882
|
+
/** Max 500. Carried on the receipt and the event. */
|
|
1883
|
+
reason?: string;
|
|
1884
|
+
}
|
|
1885
|
+
interface RefundRevenueShareAttribution {
|
|
1886
|
+
recipientPlayerId: number;
|
|
1887
|
+
percent: string;
|
|
1888
|
+
originalAttributedAmountUsd: string;
|
|
1889
|
+
refundedAttributedAmountUsd: string;
|
|
1890
|
+
/** The corrected figure to pay your recipient for that renewal. Nothing moves. */
|
|
1891
|
+
netAttributedAmountUsd: string;
|
|
1892
|
+
settledByInvo: boolean;
|
|
1893
|
+
raw: Record<string, unknown>;
|
|
1894
|
+
}
|
|
1895
|
+
/** The refund receipt. A repeated `clientRequestId` returns the stored receipt with `idempotentReplay: true`. */
|
|
1896
|
+
interface RefundResult {
|
|
1897
|
+
/** `refunded`. */
|
|
1898
|
+
status: string;
|
|
1899
|
+
idempotentReplay: boolean;
|
|
1900
|
+
refundKey: string | null;
|
|
1901
|
+
clientRequestId: string | null;
|
|
1902
|
+
subscriptionId: string;
|
|
1903
|
+
periodSeq: number | null;
|
|
1904
|
+
transactionId: string | null;
|
|
1905
|
+
refundedAmountUsd: string | null;
|
|
1906
|
+
totalRefundedAmountUsd: string | null;
|
|
1907
|
+
remainingRefundableUsd: string | null;
|
|
1908
|
+
isFullRefund: boolean;
|
|
1909
|
+
/** `wallet` | `card` | `mixed`. */
|
|
1910
|
+
fundingShape: string | null;
|
|
1911
|
+
/** Signed; can be negative (coins the card charge minted are taken back). */
|
|
1912
|
+
balanceDeltaCoins: string | null;
|
|
1913
|
+
cardRefundedUsd: string | null;
|
|
1914
|
+
processorRefundReference: string | null;
|
|
1915
|
+
/** `true` when the card refund had already been issued by an earlier attempt and this call recorded it. */
|
|
1916
|
+
processorRefundAdopted: boolean;
|
|
1917
|
+
invoFeeRetained: boolean;
|
|
1918
|
+
partnerRevenueReversedUsd: string | null;
|
|
1919
|
+
/** `full` | `prorata`. */
|
|
1920
|
+
partnerRevenueReversalMode: string | null;
|
|
1921
|
+
reason: string | null;
|
|
1922
|
+
refundedAt: string | null;
|
|
1923
|
+
newBalance: string | null;
|
|
1924
|
+
revenueShareAttribution: RefundRevenueShareAttribution | null;
|
|
1925
|
+
/** On a reduced replay (receipt lost): "This refund was already processed." */
|
|
1926
|
+
note?: string;
|
|
1927
|
+
raw: Record<string, unknown>;
|
|
1928
|
+
}
|
|
1929
|
+
interface CardSetupInput {
|
|
1930
|
+
/** Must already exist in this game (this endpoint does not create players). */
|
|
1931
|
+
playerEmail: string;
|
|
1932
|
+
/** Idempotency anchor, 1-200 chars of `A-Z a-z 0-9 . _ : -`. Resend the same value on a retry. */
|
|
1933
|
+
setupReference: string;
|
|
1934
|
+
/** A card tokenised on the client by the card form. When present INVO saves the card immediately. */
|
|
1935
|
+
paymentMethodId?: string;
|
|
1936
|
+
}
|
|
1937
|
+
/**
|
|
1938
|
+
* - `succeeded`: card saved (`card` set).
|
|
1939
|
+
* - `requires_action`: hand `clientSecret` to the card form, then call `confirmSetup`.
|
|
1940
|
+
* - `requires_confirmation` / `requires_payment_method`: the normal hand-off when you sent
|
|
1941
|
+
* no `paymentMethodId`. Confirm on the client, then call `confirmSetup`.
|
|
1942
|
+
*/
|
|
1943
|
+
type CardSetupStatus = "succeeded" | "requires_action" | "requires_confirmation" | "requires_payment_method";
|
|
1944
|
+
interface CardSetupResult {
|
|
1945
|
+
status: CardSetupStatus | string;
|
|
1946
|
+
setupIntentId: string;
|
|
1947
|
+
/** Present when the client must finish the setup. */
|
|
1948
|
+
clientSecret?: string;
|
|
1949
|
+
publishableKey?: string;
|
|
1950
|
+
card: SavedCard | null;
|
|
1951
|
+
alreadySaved: boolean;
|
|
1952
|
+
message?: string;
|
|
1953
|
+
raw: Record<string, unknown>;
|
|
1954
|
+
}
|
|
1955
|
+
interface CardSetupConfirmInput {
|
|
1956
|
+
/** From `beginSetup`. */
|
|
1957
|
+
setupIntentId: string;
|
|
1958
|
+
}
|
|
1959
|
+
interface CardSetupConfirmResult {
|
|
1960
|
+
/** `success`. */
|
|
1961
|
+
status: string;
|
|
1962
|
+
setupIntentId: string;
|
|
1963
|
+
card: SavedCard | null;
|
|
1964
|
+
alreadySaved: boolean;
|
|
1965
|
+
raw: Record<string, unknown>;
|
|
1966
|
+
}
|
|
1967
|
+
interface PlayerCardsResult {
|
|
1968
|
+
/** Unexpired cards, newest first. An unknown player is an empty list. */
|
|
1969
|
+
cards: SavedCard[];
|
|
1970
|
+
raw: Record<string, unknown>;
|
|
1971
|
+
}
|
|
1972
|
+
/** `card_declined` (default) | `insufficient_funds` | `error`. */
|
|
1973
|
+
type SandboxFailureOutcome = "card_declined" | "insufficient_funds" | "error";
|
|
1974
|
+
interface SandboxForceFailureOptions {
|
|
1975
|
+
/** Up to 100 chars. */
|
|
1976
|
+
failureCode?: string;
|
|
1977
|
+
failureMessage?: string;
|
|
1978
|
+
}
|
|
1979
|
+
interface SandboxForceAuthChallengeOptions {
|
|
1980
|
+
failureMessage?: string;
|
|
1981
|
+
}
|
|
1982
|
+
/** The clock fields every sandbox clock response reports (a subset of the subscription). */
|
|
1983
|
+
interface SandboxClockState {
|
|
1984
|
+
status: string;
|
|
1985
|
+
periodSeq: number;
|
|
1986
|
+
currentPeriodStart: string | null;
|
|
1987
|
+
currentPeriodEnd: string | null;
|
|
1988
|
+
nextChargeAt: string | null;
|
|
1989
|
+
trialEnd: string | null;
|
|
1990
|
+
cancelAtPeriodEnd: boolean;
|
|
1991
|
+
walletOnly: boolean;
|
|
1992
|
+
hasPaymentMethod: boolean;
|
|
1993
|
+
amountUsd: string;
|
|
1994
|
+
raw: Record<string, unknown>;
|
|
1995
|
+
}
|
|
1996
|
+
/**
|
|
1997
|
+
* Result of the four sandbox clock tools. `action` says which; the tool-specific fields
|
|
1998
|
+
* are optional and populated per tool (see the JSDoc on each method).
|
|
1999
|
+
*/
|
|
2000
|
+
interface SandboxClockResult {
|
|
2001
|
+
/** `ok`. */
|
|
2002
|
+
status: string;
|
|
2003
|
+
/** `advance-clock` | `force-renewal` | `retired-at-period-end` | `force-failure` | `force-auth-challenge`. */
|
|
2004
|
+
action: string;
|
|
2005
|
+
subscription: SandboxClockState | null;
|
|
2006
|
+
/** advance-clock: the state before the move. */
|
|
2007
|
+
before?: SandboxClockState;
|
|
2008
|
+
/** advance-clock: the state after the move. */
|
|
2009
|
+
after?: SandboxClockState;
|
|
2010
|
+
intervals?: number;
|
|
2011
|
+
intervalsAppliedToWindow?: number;
|
|
2012
|
+
windowMoved?: boolean;
|
|
2013
|
+
windowAlreadyElapsed?: boolean;
|
|
2014
|
+
/** force-renewal: the engine's counters (`renewed`, `declined`, `insufficient`, `auth_required`, ...; on Steam also `steam_charged`, `sandbox_synthetic`, ...). */
|
|
2015
|
+
engineStats?: Record<string, number>;
|
|
2016
|
+
periodSeq?: number;
|
|
2017
|
+
attemptNo?: number;
|
|
2018
|
+
amountUsd?: string;
|
|
2019
|
+
amountCoins?: string;
|
|
2020
|
+
/** force-renewal on a cancel-at-period-end row: nothing billed, the subscription was retired. */
|
|
2021
|
+
retired?: boolean;
|
|
2022
|
+
/** force-failure. */
|
|
2023
|
+
retryBudgetUsed?: number;
|
|
2024
|
+
retryScheduleDays?: number[];
|
|
2025
|
+
retriesRemaining?: number;
|
|
2026
|
+
/** force-auth-challenge. */
|
|
2027
|
+
authChallengesUsed?: number;
|
|
2028
|
+
maxAuthChallenges?: number;
|
|
2029
|
+
downgradedToDecline?: boolean;
|
|
2030
|
+
note?: string;
|
|
2031
|
+
raw: Record<string, unknown>;
|
|
2032
|
+
}
|
|
1441
2033
|
|
|
1442
|
-
export { type
|
|
2034
|
+
export { type SandboxClockResult as $, type ApproveResult as A, type BalanceResult as B, type ConfirmReceiptResult as C, type DestinationsQuery as D, type EnrollmentBeginResult as E, type GetSubscriptionResult as F, type GetSubscriptionOptions as G, Http as H, InvoError as I, type ListSubscriptionsOptions as J, type SubscriptionListResult as K, type LinkDeviceResult as L, type MountCheckoutOptions as M, type CancelSubscriptionOptions as N, type CancelResult as O, type PendingCollectResult as P, type ChangeAmountResult as Q, type RecoveryBeginResult as R, type SubscriptionResult as S, type SetPaymentMethodInput as T, type SetPaymentMethodResult as U, type VerificationMethod as V, type RefundSubscriptionInput as W, type RefundResult as X, type SteamSubscriptionInitInput as Y, type SteamInitResult as Z, type SteamFinalizeSubscriptionResult as _, type CheckoutMountHandle as a, type FundingSource as a$, type SandboxFailureOutcome as a0, type SandboxForceFailureOptions as a1, type SandboxForceAuthChallengeOptions as a2, type ServerConfig as a3, type PlayerToken as a4, type InitiateSendInput as a5, type InitiateResult as a6, type InitiateTransferInput as a7, type CreateCheckoutInput as a8, type CreateCheckoutResult as a9, type GuardianApprovalStatusResult as aA, type ServerDestinationsQuery as aB, type PhoneShareContact as aC, type PhoneShareInitiateResult as aD, type PhoneShareApproveInput as aE, type PhoneShareApproveResult as aF, type PhoneShareStatusResult as aG, type BeginDeviceApprovalInput as aH, type DeviceApprovalGrant as aI, type PollDeviceApprovalInput as aJ, type DeviceApprovalPollResult as aK, type ConfirmDeviceEnrollmentInput as aL, type ConfirmDeviceEnrollmentResult as aM, type ApproveWithDeviceCodeInput as aN, type DeviceApprovalSettleResult as aO, type CompleteDeviceApprovalInput as aP, type CompleteDeviceApprovalResult as aQ, type CardSetupStatus as aR, type CurrencyBalance as aS, type DeviceApprovalChannel as aT, type DeviceApprovalEnrollment as aU, type DeviceApprovalFlow as aV, type DeviceApprovalPollStatus as aW, type DeviceEnrollmentDecision as aX, type DeviceEnrollmentRespond as aY, type FirstCharge as aZ, type FirstChargeStatus as a_, type PurchaseInput as aa, type PurchaseResult as ab, type ConfirmPaymentResult as ac, type OrderDetailsResult as ad, type SteamPacksQuery as ae, type SteamPacksResult as af, type SteamInitPurchaseInput as ag, type SteamInitPurchaseResult as ah, type SteamFinalizeInput as ai, type SteamFinalizeResult as aj, type PurchaseItemInput as ak, type PurchaseItemResult as al, type ItemHistoryQuery as am, type ItemHistoryResult as an, type ItemOrderQuery as ao, type PlayerBalanceQuery as ap, type PlayerBalanceResult as aq, type InboundPendingQuery as ar, type InboundPendingResult as as, type LinkedIdentitiesQuery as at, type LinkedIdentitiesResult as au, type SmsVerifyResult as av, type ClaimTransferInput as aw, type ClaimResult as ax, type ClaimCurrencyInput as ay, type TransactionStatusResult as az, type ClientConfig as b, type InboundPendingItem as b0, type LinkedIdentityEmail as b1, type PlatformPurchaseStatus as b2, type RefundRevenueShareAttribution as b3, type SandboxClockState as b4, type SavedCard as b5, type SteamPack as b6, type SteamUserSession as b7, type Subscription as b8, type SubscriptionBaseInput as b9, type SubscriptionConsent as ba, type SubscriptionConsentInput as bb, type SubscriptionFundingRail as bc, type SubscriptionInterval as bd, type SubscriptionRevenueShare as be, type SubscriptionRevenueShareInput as bf, type SubscriptionStatus as bg, type CallOptions as c, type DestinationsResult as d, type EnrollmentVerifyResult as e, type RecoveryCompleteResult as f, type BalanceRow as g, type DestinationGame as h, type InvoErrorInfo as i, type InvoHooks as j, type InvoRequestInfo as k, type InvoResponseInfo as l, type PendingCollectItem as m, type Rail as n, type AuthHeader as o, type CardSetupInput as p, type CardSetupResult as q, type CardSetupConfirmInput as r, type CardSetupConfirmResult as s, type PlayerCardsResult as t, type PlatformPurchaseInput as u, type PlatformPurchaseResult as v, type PlatformOrderStatusResult as w, type PlatformRefundInput as x, type PlatformRefundResult as y, type CreateSubscriptionInput as z };
|