@invonetwork/web-sdk 3.8.0 → 3.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/server.cjs CHANGED
@@ -567,6 +567,34 @@ var InvoError = class _InvoError extends Error {
567
567
  get isGameNotLive() {
568
568
  return this.code === "GAME_NOT_LIVE";
569
569
  }
570
+ // ---- Card setup session (the INVO-hosted card page) ----
571
+ /**
572
+ * True when `cards.createSetupSession` was refused because the member does not exist
573
+ * in this game yet (`PLAYER_NOT_FOUND`, 404). The card page never creates players;
574
+ * create the member first (any endpoint that creates players, for example a currency
575
+ * purchase), then mint the session again. The same code comes back from
576
+ * `cards.beginSetup` and from `mintPlayerToken` for the same reason.
577
+ */
578
+ get isPlayerNotFound() {
579
+ return this.code === "PLAYER_NOT_FOUND";
580
+ }
581
+ /**
582
+ * True when `cards.createSetupSession` was refused because `playerEmail` was missing or
583
+ * is not an email address (`INVALID_PLAYER_EMAIL`, 400).
584
+ */
585
+ get isInvalidPlayerEmail() {
586
+ return this.code === "INVALID_PLAYER_EMAIL";
587
+ }
588
+ /**
589
+ * True on an `INVALID_INPUT` refusal. Two sources, told apart by `status`:
590
+ * `status === 0` is this SDK refusing a value before the network (every client-side
591
+ * guard uses this code); `status === 400` is INVO refusing one, on
592
+ * `cards.createSetupSession` a `successUrl` / `cancelUrl` that uses a script scheme
593
+ * (`javascript:`, `data:`, `vbscript:`). http(s) and app deep-link schemes are fine.
594
+ */
595
+ get isInvalidInput() {
596
+ return this.code === "INVALID_INPUT";
597
+ }
570
598
  /** Seconds to wait before retrying, when the backend throttled the call (429 `retry_after`). */
571
599
  get retryAfter() {
572
600
  const v = this.bodyObject()["retry_after"];
@@ -850,7 +878,7 @@ function toDestinationsResult(raw, direction) {
850
878
  }
851
879
 
852
880
  // src/version.ts
853
- var SDK_VERSION = "3.8.0";
881
+ var SDK_VERSION = "3.9.0";
854
882
  var DEFAULT_TOLERANCE_SEC = 300;
855
883
  var ENCODER = new TextEncoder();
856
884
  function toBytes(body) {
@@ -1580,6 +1608,9 @@ function toSubscription(row) {
1580
1608
  } : null,
1581
1609
  paidThrough: nullableString(r["paid_through"]),
1582
1610
  amountCoinsEstimate: r["amount_coins_estimate"] == null ? void 0 : String(r["amount_coins_estimate"]),
1611
+ // `include_player` puts these two ON the object (there is no separate block).
1612
+ ..."player_email" in r ? { playerEmail: nullableString(r["player_email"]) } : {},
1613
+ ..."player_name" in r ? { playerName: nullableString(r["player_name"]) } : {},
1583
1614
  raw: r
1584
1615
  };
1585
1616
  }
@@ -1795,11 +1826,10 @@ var SubscriptionsServer = class {
1795
1826
  this.auth,
1796
1827
  { signal: opts?.signal }
1797
1828
  );
1798
- return {
1799
- subscription: toSubscription(raw["subscription"]),
1800
- player: raw["player"] && typeof raw["player"] === "object" ? raw["player"] : void 0,
1801
- raw
1802
- };
1829
+ const subscription = toSubscription(raw["subscription"]);
1830
+ const row = subscription.raw;
1831
+ const player = "player_email" in row || "player_name" in row ? { player_email: row["player_email"] ?? null, player_name: row["player_name"] ?? null } : void 0;
1832
+ return { subscription, player, raw };
1803
1833
  }
1804
1834
  /**
1805
1835
  * List a member's subscriptions, newest first, paged (`limit` 1..100, `offset`
@@ -1909,7 +1939,7 @@ var SubscriptionsServer = class {
1909
1939
  *
1910
1940
  * Steam: an increase is refused (`err.isSteamReauthorizationRequired`; start a new
1911
1941
  * Steam subscription at the new price), a decrease stages. An increase to more than
1912
- * double the last agreed price, or above 500.00, is staged but never applied: raise
1942
+ * double the last agreed price, or above 25000.00, is staged but never applied: raise
1913
1943
  * prices in steps. `err.isSubscriptionTerminal` on a canceled/expired row.
1914
1944
  */
1915
1945
  async changeAmount(subscriptionId, amountUsd, opts) {
@@ -2168,12 +2198,81 @@ var SubscriptionsServer = class {
2168
2198
  };
2169
2199
  }
2170
2200
  };
2201
+ var SCRIPT_SCHEME = /^\s*(javascript|data|vbscript):/i;
2171
2202
  var CardsServer = class {
2172
2203
  constructor(http, auth) {
2173
2204
  this.http = http;
2174
2205
  this.auth = auth;
2175
2206
  }
2176
2207
  /**
2208
+ * Mint a short-lived session for the INVO-hosted card page and return its URL. THE
2209
+ * RECOMMENDED WAY TO SAVE A CARD FOR A SUBSCRIPTION: two server-to-server calls (this
2210
+ * one, then `cards.list`) and one redirect. No browser code, no processor script, no
2211
+ * client secret; INVO can change card processor without you changing anything.
2212
+ *
2213
+ * The member must already exist in this game (`err.isPlayerNotFound`, 404); the page
2214
+ * never creates players. Send the member to `result.cardSetupUrl` top-level (do not
2215
+ * frame it). The page says in words that no money moves, saves the card, and then
2216
+ * redirects to `successUrl` (or shows "Card saved" when you gave none). The saved card
2217
+ * appears in {@link list} immediately, carries the off-session consent a subscription
2218
+ * needs, and is indistinguishable from one saved any other way. There is no event for
2219
+ * a saved card; `cards.list` is the signal.
2220
+ *
2221
+ * The session lives 10 minutes (entering a card is one sitting); mint it when the
2222
+ * member is about to use it. The link may be reloaded freely before the save; once the
2223
+ * card is saved the link is spent and reopening it returns the same card again.
2224
+ * `successUrl` is redirected to verbatim (nothing appended) and `metadata` is stored on
2225
+ * the session and not returned anywhere today, so put your own correlation id in
2226
+ * `successUrl`.
2227
+ *
2228
+ * Refusals: `err.isInvalidPlayerEmail` (400, a non-email string; a missing or blank
2229
+ * `playerEmail` is refused here first with `status: 0`), `err.isPlayerNotFound` (404),
2230
+ * `err.isInvalidInput` (400: a script-scheme `successUrl` / `cancelUrl`; the SDK
2231
+ * refuses the same values first with `status: 0`), 401 / 403 on the key or the game
2232
+ * (body `{ message }`, no code), 503 when card setup is not available right now.
2233
+ * Never auto-retried: each call mints a fresh link, so on a timeout call it again.
2234
+ */
2235
+ async createSetupSession(input, opts) {
2236
+ if (typeof input.playerEmail !== "string" || !input.playerEmail.trim()) {
2237
+ throw invalidInput("playerEmail", input.playerEmail, "is required");
2238
+ }
2239
+ for (const [label, value] of [
2240
+ ["successUrl", input.successUrl],
2241
+ ["cancelUrl", input.cancelUrl]
2242
+ ]) {
2243
+ if (value === void 0) continue;
2244
+ if (typeof value !== "string" || !value.trim()) throw invalidInput(label, value, "must be a non-empty URL");
2245
+ if (SCRIPT_SCHEME.test(value)) throw invalidInput(label, value, "must not use a script scheme");
2246
+ }
2247
+ if (input.metadata !== void 0 && (input.metadata === null || typeof input.metadata !== "object" || Array.isArray(input.metadata))) {
2248
+ throw invalidInput("metadata", input.metadata, "must be a plain object");
2249
+ }
2250
+ const body = { player_email: input.playerEmail };
2251
+ if (input.successUrl) body["success_url"] = input.successUrl;
2252
+ if (input.cancelUrl) body["cancel_url"] = input.cancelUrl;
2253
+ if (input.metadata) body["metadata"] = input.metadata;
2254
+ const raw = await this.http.post(
2255
+ "/api/checkout/card-setup-sessions",
2256
+ body,
2257
+ this.auth,
2258
+ { signal: opts?.signal }
2259
+ // not idempotent: every call mints a new session (same rule as createCheckout)
2260
+ );
2261
+ return {
2262
+ sessionId: String(raw["session_id"] ?? ""),
2263
+ // Load-bearing: the member must be sent here. A 2xx without it is a broken response.
2264
+ cardSetupUrl: requireField(raw["card_setup_url"], "card_setup_url", raw),
2265
+ expiresAt: String(raw["expires_at"] ?? ""),
2266
+ raw
2267
+ };
2268
+ }
2269
+ /**
2270
+ * THE PROCESSOR-BOUND ALTERNATIVE to {@link createSetupSession}. Use it only if you
2271
+ * already run a card form in your own client against INVO's current card processor:
2272
+ * the `clientSecret` it hands back can only be consumed by that processor's client
2273
+ * library, so the browser code you write for it will need rework when INVO changes
2274
+ * processor. `createSetupSession` does not have that problem.
2275
+ *
2177
2276
  * Begin saving a card (charges nothing). The player must already exist in this game
2178
2277
  * (`404 PLAYER_NOT_FOUND`). Idempotent on `setupReference`: resend the same value on a
2179
2278
  * retry and you get the same setup back (`409 SETUP_REFERENCE_REUSED` if you reuse it
@@ -2217,6 +2316,9 @@ var CardsServer = class {
2217
2316
  };
2218
2317
  }
2219
2318
  /**
2319
+ * The second half of the processor-bound alternative (see {@link beginSetup}); not
2320
+ * needed on the {@link createSetupSession} path, where INVO's page completes the save.
2321
+ *
2220
2322
  * Finish a client-confirmed setup and save the card. Idempotent on `setupIntentId`.
2221
2323
  * While the client has not finished, this throws a 400 with body
2222
2324
  * `status: "still_requires_action"`. On `500 CARD_PERSIST_FAILED` (authorised but not
@@ -2245,7 +2347,8 @@ var CardsServer = class {
2245
2347
  * A member's unexpired saved cards, newest first. An unknown player is `{ cards: [] }`.
2246
2348
  * The `id` is the value you pass as `playerCardId`; INVO never returns processor
2247
2349
  * identifiers for a card. Served from a short cache (about 60 s); a card saved through
2248
- * `beginSetup` / `confirmSetup` appears immediately.
2350
+ * the hosted card page (`createSetupSession`) or through `beginSetup` / `confirmSetup`
2351
+ * appears immediately. This read is the signal that the hosted page saved a card.
2249
2352
  */
2250
2353
  async list(playerEmail, opts) {
2251
2354
  if (typeof playerEmail !== "string" || !playerEmail.trim()) {
package/dist/server.d.cts CHANGED
@@ -1,12 +1,12 @@
1
- import { I as InvoError, H as Http, o as AuthHeader, p as CardSetupInput, c as CallOptions, q as CardSetupResult, r as CardSetupConfirmInput, s as CardSetupConfirmResult, t as PlayerCardsResult, u as PlatformPurchaseInput, v as PlatformPurchaseResult, w as PlatformOrderStatusResult, x as PlatformRefundInput, y as PlatformRefundResult, z as CreateSubscriptionInput, S as SubscriptionResult, G as GetSubscriptionOptions, F as GetSubscriptionResult, J as ListSubscriptionsOptions, K as SubscriptionListResult, N as CancelSubscriptionOptions, O as CancelResult, Q as ChangeAmountResult, T as SetPaymentMethodInput, U as SetPaymentMethodResult, W as RefundSubscriptionInput, X as RefundResult, Y as SteamSubscriptionInitInput, Z as SteamInitResult, _ as SteamFinalizeSubscriptionResult, $ as SandboxClockResult, a0 as SandboxFailureOutcome, a1 as SandboxForceFailureOptions, a2 as SandboxForceAuthChallengeOptions, a3 as ServerConfig, a4 as PlayerToken, a5 as InitiateSendInput, a6 as InitiateResult, a7 as InitiateTransferInput, a8 as CreateCheckoutInput, a9 as CreateCheckoutResult, aa as PurchaseInput, ab as PurchaseResult, ac as ConfirmPaymentResult, ad as OrderDetailsResult, ae as SteamPacksQuery, af as SteamPacksResult, ag as SteamInitPurchaseInput, ah as SteamInitPurchaseResult, ai as SteamFinalizeInput, aj as SteamFinalizeResult, ak as PurchaseItemInput, al as PurchaseItemResult, am as ItemHistoryQuery, an as ItemHistoryResult, ao as ItemOrderQuery, ap as PlayerBalanceQuery, aq as PlayerBalanceResult, ar as InboundPendingQuery, as as InboundPendingResult, at as LinkedIdentitiesQuery, au as LinkedIdentitiesResult, av as SmsVerifyResult, aw as ClaimTransferInput, ax as ClaimResult, ay as ClaimCurrencyInput, az as TransactionStatusResult, aA as GuardianApprovalStatusResult, aB as ServerDestinationsQuery, d as DestinationsResult, aC as PhoneShareContact, aD as PhoneShareInitiateResult, aE as PhoneShareApproveInput, aF as PhoneShareApproveResult, aG as PhoneShareStatusResult, aH as BeginDeviceApprovalInput, aI as DeviceApprovalGrant, aJ as PollDeviceApprovalInput, aK as DeviceApprovalPollResult, aL as ConfirmDeviceEnrollmentInput, aM as ConfirmDeviceEnrollmentResult, aN as ApproveWithDeviceCodeInput, aO as DeviceApprovalSettleResult, aP as CompleteDeviceApprovalInput, aQ as CompleteDeviceApprovalResult } from './types-DqRuqbqI.cjs';
2
- export { aR as CardSetupStatus, aS as CurrencyBalance, h as DestinationGame, aT as DeviceApprovalChannel, aU as DeviceApprovalEnrollment, aV as DeviceApprovalFlow, aW as DeviceApprovalPollStatus, aX as DeviceEnrollmentDecision, aY as DeviceEnrollmentRespond, aZ as FirstCharge, a_ as FirstChargeStatus, a$ as FundingSource, b0 as InboundPendingItem, i as InvoErrorInfo, j as InvoHooks, k as InvoRequestInfo, l as InvoResponseInfo, b1 as LinkedIdentityEmail, b2 as PlatformPurchaseStatus, n as Rail, b3 as RefundRevenueShareAttribution, b4 as SandboxClockState, b5 as SavedCard, b6 as SteamPack, b7 as SteamUserSession, b8 as Subscription, b9 as SubscriptionBaseInput, ba as SubscriptionConsent, bb as SubscriptionConsentInput, bc as SubscriptionFundingRail, bd as SubscriptionInterval, be as SubscriptionRevenueShare, bf as SubscriptionRevenueShareInput, bg as SubscriptionStatus, V as VerificationMethod } from './types-DqRuqbqI.cjs';
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-CUzSzV8-.cjs';
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 RefundRevenueShareAttribution, b6 as SandboxClockState, b7 as SavedCard, b8 as SteamPack, b9 as SteamUserSession, ba as Subscription, bb as SubscriptionBaseInput, bc as SubscriptionConsent, bd as SubscriptionConsentInput, be as SubscriptionFundingRail, bf as SubscriptionInterval, bg as SubscriptionRevenueShare, bh as SubscriptionRevenueShareInput, bi as SubscriptionStatus, V as VerificationMethod } from './types-CUzSzV8-.cjs';
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.8.0";
9
+ declare const SDK_VERSION = "3.9.0";
10
10
 
11
11
  interface VerifyWebhookOptions {
12
12
  /** Max age of the signed timestamp, in seconds. Default 300 (5 min). */
@@ -565,7 +565,7 @@ declare class SubscriptionsServer {
565
565
  *
566
566
  * Steam: an increase is refused (`err.isSteamReauthorizationRequired`; start a new
567
567
  * Steam subscription at the new price), a decrease stages. An increase to more than
568
- * double the last agreed price, or above 500.00, is staged but never applied: raise
568
+ * double the last agreed price, or above 25000.00, is staged but never applied: raise
569
569
  * prices in steps. `err.isSubscriptionTerminal` on a canceled/expired row.
570
570
  */
571
571
  changeAmount(subscriptionId: string, amountUsd: string | number, opts?: CallOptions): Promise<ChangeAmountResult>;
@@ -643,16 +643,58 @@ declare class SubscriptionsServer {
643
643
  /**
644
644
  * Saved cards for off-session (recurring) use: the card capture a card subscription
645
645
  * needs. Reached as `invo.cards.*`. The subscription endpoints never receive card data
646
- * and neither does this SDK: the card form on the client tokenises it. A card saved
647
- * through the hosted checkout, or through a `savedCardId` purchase, does NOT carry the
648
- * off-session consent a subscription needs; capture it here (or with a
649
- * `purchaseCurrency` that sets `save_card: true`).
646
+ * and neither does this SDK.
647
+ *
648
+ * THE RECOMMENDED CAPTURE IS {@link createSetupSession}: INVO hosts the card page, you
649
+ * mint a link server-side and send the member to it, and nothing in your integration
650
+ * references a card processor or loads its script. {@link beginSetup} /
651
+ * {@link confirmSetup} are the processor-bound alternative for a partner who already
652
+ * runs a card form in their own client against INVO's current processor.
653
+ *
654
+ * A card saved through the hosted CHECKOUT page, or through a `savedCardId` purchase,
655
+ * does NOT carry the off-session consent a subscription needs; capture it here (or with
656
+ * a `purchaseCurrency` that sets `save_card: true`).
650
657
  */
651
658
  declare class CardsServer {
652
659
  private readonly http;
653
660
  private readonly auth;
654
661
  constructor(http: Http, auth: AuthHeader);
655
662
  /**
663
+ * Mint a short-lived session for the INVO-hosted card page and return its URL. THE
664
+ * RECOMMENDED WAY TO SAVE A CARD FOR A SUBSCRIPTION: two server-to-server calls (this
665
+ * one, then `cards.list`) and one redirect. No browser code, no processor script, no
666
+ * client secret; INVO can change card processor without you changing anything.
667
+ *
668
+ * The member must already exist in this game (`err.isPlayerNotFound`, 404); the page
669
+ * never creates players. Send the member to `result.cardSetupUrl` top-level (do not
670
+ * frame it). The page says in words that no money moves, saves the card, and then
671
+ * redirects to `successUrl` (or shows "Card saved" when you gave none). The saved card
672
+ * appears in {@link list} immediately, carries the off-session consent a subscription
673
+ * needs, and is indistinguishable from one saved any other way. There is no event for
674
+ * a saved card; `cards.list` is the signal.
675
+ *
676
+ * The session lives 10 minutes (entering a card is one sitting); mint it when the
677
+ * member is about to use it. The link may be reloaded freely before the save; once the
678
+ * card is saved the link is spent and reopening it returns the same card again.
679
+ * `successUrl` is redirected to verbatim (nothing appended) and `metadata` is stored on
680
+ * the session and not returned anywhere today, so put your own correlation id in
681
+ * `successUrl`.
682
+ *
683
+ * Refusals: `err.isInvalidPlayerEmail` (400, a non-email string; a missing or blank
684
+ * `playerEmail` is refused here first with `status: 0`), `err.isPlayerNotFound` (404),
685
+ * `err.isInvalidInput` (400: a script-scheme `successUrl` / `cancelUrl`; the SDK
686
+ * refuses the same values first with `status: 0`), 401 / 403 on the key or the game
687
+ * (body `{ message }`, no code), 503 when card setup is not available right now.
688
+ * Never auto-retried: each call mints a fresh link, so on a timeout call it again.
689
+ */
690
+ createSetupSession(input: CardSetupSessionInput, opts?: CallOptions): Promise<CardSetupSessionResult>;
691
+ /**
692
+ * THE PROCESSOR-BOUND ALTERNATIVE to {@link createSetupSession}. Use it only if you
693
+ * already run a card form in your own client against INVO's current card processor:
694
+ * the `clientSecret` it hands back can only be consumed by that processor's client
695
+ * library, so the browser code you write for it will need rework when INVO changes
696
+ * processor. `createSetupSession` does not have that problem.
697
+ *
656
698
  * Begin saving a card (charges nothing). The player must already exist in this game
657
699
  * (`404 PLAYER_NOT_FOUND`). Idempotent on `setupReference`: resend the same value on a
658
700
  * retry and you get the same setup back (`409 SETUP_REFERENCE_REUSED` if you reuse it
@@ -667,6 +709,9 @@ declare class CardsServer {
667
709
  */
668
710
  beginSetup(input: CardSetupInput, opts?: CallOptions): Promise<CardSetupResult>;
669
711
  /**
712
+ * The second half of the processor-bound alternative (see {@link beginSetup}); not
713
+ * needed on the {@link createSetupSession} path, where INVO's page completes the save.
714
+ *
670
715
  * Finish a client-confirmed setup and save the card. Idempotent on `setupIntentId`.
671
716
  * While the client has not finished, this throws a 400 with body
672
717
  * `status: "still_requires_action"`. On `500 CARD_PERSIST_FAILED` (authorised but not
@@ -677,7 +722,8 @@ declare class CardsServer {
677
722
  * A member's unexpired saved cards, newest first. An unknown player is `{ cards: [] }`.
678
723
  * The `id` is the value you pass as `playerCardId`; INVO never returns processor
679
724
  * identifiers for a card. Served from a short cache (about 60 s); a card saved through
680
- * `beginSetup` / `confirmSetup` appears immediately.
725
+ * the hosted card page (`createSetupSession`) or through `beginSetup` / `confirmSetup`
726
+ * appears immediately. This read is the signal that the hosted page saved a card.
681
727
  */
682
728
  list(playerEmail: string, opts?: CallOptions): Promise<PlayerCardsResult>;
683
729
  }
@@ -1148,4 +1194,4 @@ declare class InvoServer {
1148
1194
  private toInitiateResult;
1149
1195
  }
1150
1196
 
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 };
1197
+ 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 SubscriptionRefundDetail, type SubscriptionRefundedData, type SubscriptionRenewalFunding, type SubscriptionRenewalSplit, type SubscriptionRenewedData, SubscriptionResult, type SubscriptionRevenueShareAttribution, SubscriptionsServer, TransactionStatusResult, type TransferEventData, type VerifyWebhookOptions, type WebhookHandlerOptions, createWebhookHandler, verifyWebhook, verifyWebhookAsync };
package/dist/server.d.ts CHANGED
@@ -1,12 +1,12 @@
1
- import { I as InvoError, H as Http, o as AuthHeader, p as CardSetupInput, c as CallOptions, q as CardSetupResult, r as CardSetupConfirmInput, s as CardSetupConfirmResult, t as PlayerCardsResult, u as PlatformPurchaseInput, v as PlatformPurchaseResult, w as PlatformOrderStatusResult, x as PlatformRefundInput, y as PlatformRefundResult, z as CreateSubscriptionInput, S as SubscriptionResult, G as GetSubscriptionOptions, F as GetSubscriptionResult, J as ListSubscriptionsOptions, K as SubscriptionListResult, N as CancelSubscriptionOptions, O as CancelResult, Q as ChangeAmountResult, T as SetPaymentMethodInput, U as SetPaymentMethodResult, W as RefundSubscriptionInput, X as RefundResult, Y as SteamSubscriptionInitInput, Z as SteamInitResult, _ as SteamFinalizeSubscriptionResult, $ as SandboxClockResult, a0 as SandboxFailureOutcome, a1 as SandboxForceFailureOptions, a2 as SandboxForceAuthChallengeOptions, a3 as ServerConfig, a4 as PlayerToken, a5 as InitiateSendInput, a6 as InitiateResult, a7 as InitiateTransferInput, a8 as CreateCheckoutInput, a9 as CreateCheckoutResult, aa as PurchaseInput, ab as PurchaseResult, ac as ConfirmPaymentResult, ad as OrderDetailsResult, ae as SteamPacksQuery, af as SteamPacksResult, ag as SteamInitPurchaseInput, ah as SteamInitPurchaseResult, ai as SteamFinalizeInput, aj as SteamFinalizeResult, ak as PurchaseItemInput, al as PurchaseItemResult, am as ItemHistoryQuery, an as ItemHistoryResult, ao as ItemOrderQuery, ap as PlayerBalanceQuery, aq as PlayerBalanceResult, ar as InboundPendingQuery, as as InboundPendingResult, at as LinkedIdentitiesQuery, au as LinkedIdentitiesResult, av as SmsVerifyResult, aw as ClaimTransferInput, ax as ClaimResult, ay as ClaimCurrencyInput, az as TransactionStatusResult, aA as GuardianApprovalStatusResult, aB as ServerDestinationsQuery, d as DestinationsResult, aC as PhoneShareContact, aD as PhoneShareInitiateResult, aE as PhoneShareApproveInput, aF as PhoneShareApproveResult, aG as PhoneShareStatusResult, aH as BeginDeviceApprovalInput, aI as DeviceApprovalGrant, aJ as PollDeviceApprovalInput, aK as DeviceApprovalPollResult, aL as ConfirmDeviceEnrollmentInput, aM as ConfirmDeviceEnrollmentResult, aN as ApproveWithDeviceCodeInput, aO as DeviceApprovalSettleResult, aP as CompleteDeviceApprovalInput, aQ as CompleteDeviceApprovalResult } from './types-DqRuqbqI.js';
2
- export { aR as CardSetupStatus, aS as CurrencyBalance, h as DestinationGame, aT as DeviceApprovalChannel, aU as DeviceApprovalEnrollment, aV as DeviceApprovalFlow, aW as DeviceApprovalPollStatus, aX as DeviceEnrollmentDecision, aY as DeviceEnrollmentRespond, aZ as FirstCharge, a_ as FirstChargeStatus, a$ as FundingSource, b0 as InboundPendingItem, i as InvoErrorInfo, j as InvoHooks, k as InvoRequestInfo, l as InvoResponseInfo, b1 as LinkedIdentityEmail, b2 as PlatformPurchaseStatus, n as Rail, b3 as RefundRevenueShareAttribution, b4 as SandboxClockState, b5 as SavedCard, b6 as SteamPack, b7 as SteamUserSession, b8 as Subscription, b9 as SubscriptionBaseInput, ba as SubscriptionConsent, bb as SubscriptionConsentInput, bc as SubscriptionFundingRail, bd as SubscriptionInterval, be as SubscriptionRevenueShare, bf as SubscriptionRevenueShareInput, bg as SubscriptionStatus, V as VerificationMethod } from './types-DqRuqbqI.js';
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-CUzSzV8-.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 RefundRevenueShareAttribution, b6 as SandboxClockState, b7 as SavedCard, b8 as SteamPack, b9 as SteamUserSession, ba as Subscription, bb as SubscriptionBaseInput, bc as SubscriptionConsent, bd as SubscriptionConsentInput, be as SubscriptionFundingRail, bf as SubscriptionInterval, bg as SubscriptionRevenueShare, bh as SubscriptionRevenueShareInput, bi as SubscriptionStatus, V as VerificationMethod } from './types-CUzSzV8-.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.8.0";
9
+ declare const SDK_VERSION = "3.9.0";
10
10
 
11
11
  interface VerifyWebhookOptions {
12
12
  /** Max age of the signed timestamp, in seconds. Default 300 (5 min). */
@@ -565,7 +565,7 @@ declare class SubscriptionsServer {
565
565
  *
566
566
  * Steam: an increase is refused (`err.isSteamReauthorizationRequired`; start a new
567
567
  * Steam subscription at the new price), a decrease stages. An increase to more than
568
- * double the last agreed price, or above 500.00, is staged but never applied: raise
568
+ * double the last agreed price, or above 25000.00, is staged but never applied: raise
569
569
  * prices in steps. `err.isSubscriptionTerminal` on a canceled/expired row.
570
570
  */
571
571
  changeAmount(subscriptionId: string, amountUsd: string | number, opts?: CallOptions): Promise<ChangeAmountResult>;
@@ -643,16 +643,58 @@ declare class SubscriptionsServer {
643
643
  /**
644
644
  * Saved cards for off-session (recurring) use: the card capture a card subscription
645
645
  * needs. Reached as `invo.cards.*`. The subscription endpoints never receive card data
646
- * and neither does this SDK: the card form on the client tokenises it. A card saved
647
- * through the hosted checkout, or through a `savedCardId` purchase, does NOT carry the
648
- * off-session consent a subscription needs; capture it here (or with a
649
- * `purchaseCurrency` that sets `save_card: true`).
646
+ * and neither does this SDK.
647
+ *
648
+ * THE RECOMMENDED CAPTURE IS {@link createSetupSession}: INVO hosts the card page, you
649
+ * mint a link server-side and send the member to it, and nothing in your integration
650
+ * references a card processor or loads its script. {@link beginSetup} /
651
+ * {@link confirmSetup} are the processor-bound alternative for a partner who already
652
+ * runs a card form in their own client against INVO's current processor.
653
+ *
654
+ * A card saved through the hosted CHECKOUT page, or through a `savedCardId` purchase,
655
+ * does NOT carry the off-session consent a subscription needs; capture it here (or with
656
+ * a `purchaseCurrency` that sets `save_card: true`).
650
657
  */
651
658
  declare class CardsServer {
652
659
  private readonly http;
653
660
  private readonly auth;
654
661
  constructor(http: Http, auth: AuthHeader);
655
662
  /**
663
+ * Mint a short-lived session for the INVO-hosted card page and return its URL. THE
664
+ * RECOMMENDED WAY TO SAVE A CARD FOR A SUBSCRIPTION: two server-to-server calls (this
665
+ * one, then `cards.list`) and one redirect. No browser code, no processor script, no
666
+ * client secret; INVO can change card processor without you changing anything.
667
+ *
668
+ * The member must already exist in this game (`err.isPlayerNotFound`, 404); the page
669
+ * never creates players. Send the member to `result.cardSetupUrl` top-level (do not
670
+ * frame it). The page says in words that no money moves, saves the card, and then
671
+ * redirects to `successUrl` (or shows "Card saved" when you gave none). The saved card
672
+ * appears in {@link list} immediately, carries the off-session consent a subscription
673
+ * needs, and is indistinguishable from one saved any other way. There is no event for
674
+ * a saved card; `cards.list` is the signal.
675
+ *
676
+ * The session lives 10 minutes (entering a card is one sitting); mint it when the
677
+ * member is about to use it. The link may be reloaded freely before the save; once the
678
+ * card is saved the link is spent and reopening it returns the same card again.
679
+ * `successUrl` is redirected to verbatim (nothing appended) and `metadata` is stored on
680
+ * the session and not returned anywhere today, so put your own correlation id in
681
+ * `successUrl`.
682
+ *
683
+ * Refusals: `err.isInvalidPlayerEmail` (400, a non-email string; a missing or blank
684
+ * `playerEmail` is refused here first with `status: 0`), `err.isPlayerNotFound` (404),
685
+ * `err.isInvalidInput` (400: a script-scheme `successUrl` / `cancelUrl`; the SDK
686
+ * refuses the same values first with `status: 0`), 401 / 403 on the key or the game
687
+ * (body `{ message }`, no code), 503 when card setup is not available right now.
688
+ * Never auto-retried: each call mints a fresh link, so on a timeout call it again.
689
+ */
690
+ createSetupSession(input: CardSetupSessionInput, opts?: CallOptions): Promise<CardSetupSessionResult>;
691
+ /**
692
+ * THE PROCESSOR-BOUND ALTERNATIVE to {@link createSetupSession}. Use it only if you
693
+ * already run a card form in your own client against INVO's current card processor:
694
+ * the `clientSecret` it hands back can only be consumed by that processor's client
695
+ * library, so the browser code you write for it will need rework when INVO changes
696
+ * processor. `createSetupSession` does not have that problem.
697
+ *
656
698
  * Begin saving a card (charges nothing). The player must already exist in this game
657
699
  * (`404 PLAYER_NOT_FOUND`). Idempotent on `setupReference`: resend the same value on a
658
700
  * retry and you get the same setup back (`409 SETUP_REFERENCE_REUSED` if you reuse it
@@ -667,6 +709,9 @@ declare class CardsServer {
667
709
  */
668
710
  beginSetup(input: CardSetupInput, opts?: CallOptions): Promise<CardSetupResult>;
669
711
  /**
712
+ * The second half of the processor-bound alternative (see {@link beginSetup}); not
713
+ * needed on the {@link createSetupSession} path, where INVO's page completes the save.
714
+ *
670
715
  * Finish a client-confirmed setup and save the card. Idempotent on `setupIntentId`.
671
716
  * While the client has not finished, this throws a 400 with body
672
717
  * `status: "still_requires_action"`. On `500 CARD_PERSIST_FAILED` (authorised but not
@@ -677,7 +722,8 @@ declare class CardsServer {
677
722
  * A member's unexpired saved cards, newest first. An unknown player is `{ cards: [] }`.
678
723
  * The `id` is the value you pass as `playerCardId`; INVO never returns processor
679
724
  * identifiers for a card. Served from a short cache (about 60 s); a card saved through
680
- * `beginSetup` / `confirmSetup` appears immediately.
725
+ * the hosted card page (`createSetupSession`) or through `beginSetup` / `confirmSetup`
726
+ * appears immediately. This read is the signal that the hosted page saved a card.
681
727
  */
682
728
  list(playerEmail: string, opts?: CallOptions): Promise<PlayerCardsResult>;
683
729
  }
@@ -1148,4 +1194,4 @@ declare class InvoServer {
1148
1194
  private toInitiateResult;
1149
1195
  }
1150
1196
 
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 };
1197
+ 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 SubscriptionRefundDetail, type SubscriptionRefundedData, type SubscriptionRenewalFunding, type SubscriptionRenewalSplit, type SubscriptionRenewedData, SubscriptionResult, type SubscriptionRevenueShareAttribution, SubscriptionsServer, TransactionStatusResult, type TransferEventData, type VerifyWebhookOptions, type WebhookHandlerOptions, createWebhookHandler, verifyWebhook, verifyWebhookAsync };
package/dist/server.js CHANGED
@@ -1,9 +1,9 @@
1
- import { InvoError, assertSecureBaseUrl, Http, toDestinationsResult } from './chunk-HYGBTUEJ.js';
2
- export { InvoError } from './chunk-HYGBTUEJ.js';
1
+ import { InvoError, assertSecureBaseUrl, Http, toDestinationsResult } from './chunk-NB6UF657.js';
2
+ export { InvoError } from './chunk-NB6UF657.js';
3
3
  import { createHmac, timingSafeEqual } from 'crypto';
4
4
 
5
5
  // src/version.ts
6
- var SDK_VERSION = "3.8.0";
6
+ var SDK_VERSION = "3.9.0";
7
7
  var DEFAULT_TOLERANCE_SEC = 300;
8
8
  var ENCODER = new TextEncoder();
9
9
  function toBytes(body) {
@@ -733,6 +733,9 @@ function toSubscription(row) {
733
733
  } : null,
734
734
  paidThrough: nullableString(r["paid_through"]),
735
735
  amountCoinsEstimate: r["amount_coins_estimate"] == null ? void 0 : String(r["amount_coins_estimate"]),
736
+ // `include_player` puts these two ON the object (there is no separate block).
737
+ ..."player_email" in r ? { playerEmail: nullableString(r["player_email"]) } : {},
738
+ ..."player_name" in r ? { playerName: nullableString(r["player_name"]) } : {},
736
739
  raw: r
737
740
  };
738
741
  }
@@ -948,11 +951,10 @@ var SubscriptionsServer = class {
948
951
  this.auth,
949
952
  { signal: opts?.signal }
950
953
  );
951
- return {
952
- subscription: toSubscription(raw["subscription"]),
953
- player: raw["player"] && typeof raw["player"] === "object" ? raw["player"] : void 0,
954
- raw
955
- };
954
+ const subscription = toSubscription(raw["subscription"]);
955
+ const row = subscription.raw;
956
+ const player = "player_email" in row || "player_name" in row ? { player_email: row["player_email"] ?? null, player_name: row["player_name"] ?? null } : void 0;
957
+ return { subscription, player, raw };
956
958
  }
957
959
  /**
958
960
  * List a member's subscriptions, newest first, paged (`limit` 1..100, `offset`
@@ -1062,7 +1064,7 @@ var SubscriptionsServer = class {
1062
1064
  *
1063
1065
  * Steam: an increase is refused (`err.isSteamReauthorizationRequired`; start a new
1064
1066
  * Steam subscription at the new price), a decrease stages. An increase to more than
1065
- * double the last agreed price, or above 500.00, is staged but never applied: raise
1067
+ * double the last agreed price, or above 25000.00, is staged but never applied: raise
1066
1068
  * prices in steps. `err.isSubscriptionTerminal` on a canceled/expired row.
1067
1069
  */
1068
1070
  async changeAmount(subscriptionId, amountUsd, opts) {
@@ -1321,12 +1323,81 @@ var SubscriptionsServer = class {
1321
1323
  };
1322
1324
  }
1323
1325
  };
1326
+ var SCRIPT_SCHEME = /^\s*(javascript|data|vbscript):/i;
1324
1327
  var CardsServer = class {
1325
1328
  constructor(http, auth) {
1326
1329
  this.http = http;
1327
1330
  this.auth = auth;
1328
1331
  }
1329
1332
  /**
1333
+ * Mint a short-lived session for the INVO-hosted card page and return its URL. THE
1334
+ * RECOMMENDED WAY TO SAVE A CARD FOR A SUBSCRIPTION: two server-to-server calls (this
1335
+ * one, then `cards.list`) and one redirect. No browser code, no processor script, no
1336
+ * client secret; INVO can change card processor without you changing anything.
1337
+ *
1338
+ * The member must already exist in this game (`err.isPlayerNotFound`, 404); the page
1339
+ * never creates players. Send the member to `result.cardSetupUrl` top-level (do not
1340
+ * frame it). The page says in words that no money moves, saves the card, and then
1341
+ * redirects to `successUrl` (or shows "Card saved" when you gave none). The saved card
1342
+ * appears in {@link list} immediately, carries the off-session consent a subscription
1343
+ * needs, and is indistinguishable from one saved any other way. There is no event for
1344
+ * a saved card; `cards.list` is the signal.
1345
+ *
1346
+ * The session lives 10 minutes (entering a card is one sitting); mint it when the
1347
+ * member is about to use it. The link may be reloaded freely before the save; once the
1348
+ * card is saved the link is spent and reopening it returns the same card again.
1349
+ * `successUrl` is redirected to verbatim (nothing appended) and `metadata` is stored on
1350
+ * the session and not returned anywhere today, so put your own correlation id in
1351
+ * `successUrl`.
1352
+ *
1353
+ * Refusals: `err.isInvalidPlayerEmail` (400, a non-email string; a missing or blank
1354
+ * `playerEmail` is refused here first with `status: 0`), `err.isPlayerNotFound` (404),
1355
+ * `err.isInvalidInput` (400: a script-scheme `successUrl` / `cancelUrl`; the SDK
1356
+ * refuses the same values first with `status: 0`), 401 / 403 on the key or the game
1357
+ * (body `{ message }`, no code), 503 when card setup is not available right now.
1358
+ * Never auto-retried: each call mints a fresh link, so on a timeout call it again.
1359
+ */
1360
+ async createSetupSession(input, opts) {
1361
+ if (typeof input.playerEmail !== "string" || !input.playerEmail.trim()) {
1362
+ throw invalidInput("playerEmail", input.playerEmail, "is required");
1363
+ }
1364
+ for (const [label, value] of [
1365
+ ["successUrl", input.successUrl],
1366
+ ["cancelUrl", input.cancelUrl]
1367
+ ]) {
1368
+ if (value === void 0) continue;
1369
+ if (typeof value !== "string" || !value.trim()) throw invalidInput(label, value, "must be a non-empty URL");
1370
+ if (SCRIPT_SCHEME.test(value)) throw invalidInput(label, value, "must not use a script scheme");
1371
+ }
1372
+ if (input.metadata !== void 0 && (input.metadata === null || typeof input.metadata !== "object" || Array.isArray(input.metadata))) {
1373
+ throw invalidInput("metadata", input.metadata, "must be a plain object");
1374
+ }
1375
+ const body = { player_email: input.playerEmail };
1376
+ if (input.successUrl) body["success_url"] = input.successUrl;
1377
+ if (input.cancelUrl) body["cancel_url"] = input.cancelUrl;
1378
+ if (input.metadata) body["metadata"] = input.metadata;
1379
+ const raw = await this.http.post(
1380
+ "/api/checkout/card-setup-sessions",
1381
+ body,
1382
+ this.auth,
1383
+ { signal: opts?.signal }
1384
+ // not idempotent: every call mints a new session (same rule as createCheckout)
1385
+ );
1386
+ return {
1387
+ sessionId: String(raw["session_id"] ?? ""),
1388
+ // Load-bearing: the member must be sent here. A 2xx without it is a broken response.
1389
+ cardSetupUrl: requireField(raw["card_setup_url"], "card_setup_url", raw),
1390
+ expiresAt: String(raw["expires_at"] ?? ""),
1391
+ raw
1392
+ };
1393
+ }
1394
+ /**
1395
+ * THE PROCESSOR-BOUND ALTERNATIVE to {@link createSetupSession}. Use it only if you
1396
+ * already run a card form in your own client against INVO's current card processor:
1397
+ * the `clientSecret` it hands back can only be consumed by that processor's client
1398
+ * library, so the browser code you write for it will need rework when INVO changes
1399
+ * processor. `createSetupSession` does not have that problem.
1400
+ *
1330
1401
  * Begin saving a card (charges nothing). The player must already exist in this game
1331
1402
  * (`404 PLAYER_NOT_FOUND`). Idempotent on `setupReference`: resend the same value on a
1332
1403
  * retry and you get the same setup back (`409 SETUP_REFERENCE_REUSED` if you reuse it
@@ -1370,6 +1441,9 @@ var CardsServer = class {
1370
1441
  };
1371
1442
  }
1372
1443
  /**
1444
+ * The second half of the processor-bound alternative (see {@link beginSetup}); not
1445
+ * needed on the {@link createSetupSession} path, where INVO's page completes the save.
1446
+ *
1373
1447
  * Finish a client-confirmed setup and save the card. Idempotent on `setupIntentId`.
1374
1448
  * While the client has not finished, this throws a 400 with body
1375
1449
  * `status: "still_requires_action"`. On `500 CARD_PERSIST_FAILED` (authorised but not
@@ -1398,7 +1472,8 @@ var CardsServer = class {
1398
1472
  * A member's unexpired saved cards, newest first. An unknown player is `{ cards: [] }`.
1399
1473
  * The `id` is the value you pass as `playerCardId`; INVO never returns processor
1400
1474
  * identifiers for a card. Served from a short cache (about 60 s); a card saved through
1401
- * `beginSetup` / `confirmSetup` appears immediately.
1475
+ * the hosted card page (`createSetupSession`) or through `beginSetup` / `confirmSetup`
1476
+ * appears immediately. This read is the signal that the hosted page saved a card.
1402
1477
  */
1403
1478
  async list(playerEmail, opts) {
1404
1479
  if (typeof playerEmail !== "string" || !playerEmail.trim()) {