@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.
@@ -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 ItemOrderQuery as $, type ApproveResult as A, type BalanceResult as B, type ConfirmReceiptResult as C, type DestinationsQuery as D, type EnrollmentBeginResult as E, type PurchaseInput as F, type PurchaseResult as G, Http as H, InvoError as I, type ConfirmPaymentResult as J, type SteamPacksQuery as K, type LinkDeviceResult as L, type MountCheckoutOptions as M, type SteamPacksResult as N, type OrderDetailsResult as O, type PendingCollectResult as P, type SteamInitPurchaseInput as Q, type RecoveryBeginResult as R, type ServerConfig as S, type SteamInitPurchaseResult as T, type SteamFinalizeInput as U, type VerificationMethod as V, type SteamFinalizeResult as W, type PurchaseItemInput as X, type PurchaseItemResult as Y, type ItemHistoryQuery as Z, type ItemHistoryResult as _, type CheckoutMountHandle as a, type PlayerBalanceQuery as a0, type PlayerBalanceResult as a1, type InboundPendingQuery as a2, type InboundPendingResult as a3, type LinkedIdentitiesQuery as a4, type LinkedIdentitiesResult as a5, type SmsVerifyResult as a6, type ClaimTransferInput as a7, type ClaimResult as a8, type ClaimCurrencyInput as a9, type InboundPendingItem as aA, type LinkedIdentityEmail as aB, type PlatformPurchaseStatus as aC, type SteamPack as aD, type SteamUserSession as aE, type TransactionStatusResult as aa, type GuardianApprovalStatusResult as ab, type ServerDestinationsQuery as ac, type PhoneShareContact as ad, type PhoneShareInitiateResult as ae, type PhoneShareApproveInput as af, type PhoneShareApproveResult as ag, type PhoneShareStatusResult as ah, type BeginDeviceApprovalInput as ai, type DeviceApprovalGrant as aj, type PollDeviceApprovalInput as ak, type DeviceApprovalPollResult as al, type ConfirmDeviceEnrollmentInput as am, type ConfirmDeviceEnrollmentResult as an, type ApproveWithDeviceCodeInput as ao, type DeviceApprovalSettleResult as ap, type CompleteDeviceApprovalInput as aq, type CompleteDeviceApprovalResult 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 FundingSource as az, type ClientConfig as b, 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 PlatformPurchaseInput as p, type PlatformPurchaseResult as q, type PlatformOrderStatusResult as r, type PlatformRefundInput as s, type PlatformRefundResult as t, type PlayerToken as u, type InitiateSendInput as v, type InitiateResult as w, type InitiateTransferInput as x, type CreateCheckoutInput as y, type CreateCheckoutResult as z };
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 };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@invonetwork/web-sdk",
3
- "version": "3.7.0",
3
+ "version": "3.8.1",
4
4
  "description": "INVO Web SDK — currency purchase + passkey (WebAuthn) verification for partner web platforms.",
5
5
  "license": "SEE LICENSE IN LICENSE",
6
6
  "private": false,