@invonetwork/web-sdk 2.4.1 → 2.5.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/server.js CHANGED
@@ -1,5 +1,5 @@
1
- import { InvoError, assertSecureBaseUrl, Http, toDestinationsResult } from './chunk-SSTZKXPC.js';
2
- export { InvoError } from './chunk-SSTZKXPC.js';
1
+ import { InvoError, assertSecureBaseUrl, Http, toDestinationsResult } from './chunk-5X3ESHJR.js';
2
+ export { InvoError } from './chunk-5X3ESHJR.js';
3
3
  import { createHmac, timingSafeEqual } from 'crypto';
4
4
 
5
5
  var DEFAULT_TOLERANCE_SEC = 300;
@@ -167,7 +167,7 @@ async function hmacHexSubtle(secret, message) {
167
167
  }
168
168
 
169
169
  // src/server.ts
170
- var DEFAULT_UA = "invonetwork-web-sdk/2.4.1 (+https://invo.network)";
170
+ var DEFAULT_UA = "invonetwork-web-sdk/2.5.1 (+https://invo.network)";
171
171
  var MAX_USD_AMOUNT = 999.99;
172
172
  var MAX_ITEM_PRICE = 999999.99;
173
173
  function invalidInput(label, value, why) {
@@ -328,6 +328,217 @@ function requireField(value, field, raw) {
328
328
  }
329
329
  return s;
330
330
  }
331
+ var FUNDING_SOURCES = /* @__PURE__ */ new Set(["balance", "card"]);
332
+ function invalidInputNoEcho(label, why) {
333
+ return new InvoError({ message: `${label} ${why}.`, code: "INVALID_INPUT", status: 0 });
334
+ }
335
+ function assertBillingAddress(addr, label) {
336
+ if (!addr || typeof addr !== "object") {
337
+ throw invalidInputNoEcho(label, 'is required for the "card" funding source and must be an object');
338
+ }
339
+ const required = [
340
+ [`${label}.line1`, addr.line1],
341
+ [`${label}.city`, addr.city],
342
+ [`${label}.postalCode`, addr.postalCode],
343
+ [`${label}.country`, addr.country]
344
+ ];
345
+ for (const [k, v] of required) {
346
+ if (typeof v !== "string" || !v.trim()) throw invalidInputNoEcho(k, "is required");
347
+ }
348
+ if (!/^[A-Za-z]{2}$/.test(addr.country)) {
349
+ throw invalidInputNoEcho(`${label}.country`, "must be a 2-letter ISO country code");
350
+ }
351
+ const optional = [
352
+ [`${label}.name`, addr.name],
353
+ [`${label}.line2`, addr.line2],
354
+ [`${label}.state`, addr.state]
355
+ ];
356
+ for (const [k, v] of optional) {
357
+ if (v !== void 0 && typeof v !== "string") {
358
+ throw invalidInputNoEcho(k, "must be a string when provided");
359
+ }
360
+ }
361
+ }
362
+ function toBillingAddressBody(addr) {
363
+ const body = {
364
+ line1: addr.line1,
365
+ city: addr.city,
366
+ postal_code: addr.postalCode,
367
+ country: addr.country
368
+ };
369
+ if (addr.name) body["name"] = addr.name;
370
+ if (addr.line2) body["line2"] = addr.line2;
371
+ if (addr.state) body["state"] = addr.state;
372
+ return body;
373
+ }
374
+ var PlatformCommerceServer = class {
375
+ constructor(http, auth) {
376
+ this.http = http;
377
+ this.auth = auth;
378
+ }
379
+ /**
380
+ * Create a purchase. The funding source is resolved server-side under lock — the client
381
+ * can request `"balance"` or `"card"`, but the backend verifies the real balance before
382
+ * value moves.
383
+ *
384
+ * - `fundingSource: "balance"` → settles synchronously; result `status:"success"` with
385
+ * `newBalance`/`financialBreakdown`. `totalPrice` is the tenant's network-currency amount.
386
+ * - `fundingSource: "card"` → result `status:"requires_payment"` + `clientSecret`; hand
387
+ * that to the browser `platformCommerce.confirmCardPayment`. `totalPrice` is USD and a
388
+ * `billingAddress` is REQUIRED. The sale is real only on the `platform_commerce.purchased`
389
+ * webhook — never on the client confirmation.
390
+ *
391
+ * Idempotent on `clientRequestId` (a duplicate throws a 409 `err.isDuplicateRequest`).
392
+ * A non-platform tenant throws `err.isNotPlatformTenant` (403).
393
+ *
394
+ * ⚠ Card-leg caveat: if the RESPONSE to a card purchase is lost (timeout after the
395
+ * backend created the order), re-sending the same `clientRequestId` returns the duplicate
396
+ * 409 and the `clientSecret` cannot be re-fetched — reconcile that order via the
397
+ * `platform_commerce.purchased` webhook / `getStatus`, and use a NEW `clientRequestId`
398
+ * for a fresh attempt. The balance leg has no such gap.
399
+ */
400
+ async purchase(input, opts) {
401
+ const required = [
402
+ ["clientRequestId", input.clientRequestId],
403
+ ["playerEmail", input.playerEmail],
404
+ ["playerName", input.playerName],
405
+ ["itemId", input.itemId],
406
+ ["itemName", input.itemName]
407
+ ];
408
+ for (const [k, v] of required) {
409
+ if (typeof v !== "string" || !v.trim()) throw invalidInput(k, v, "is required");
410
+ }
411
+ if (!FUNDING_SOURCES.has(input.fundingSource)) {
412
+ throw invalidInput("fundingSource", input.fundingSource, 'must be "balance" or "card"');
413
+ }
414
+ if (!Number.isInteger(input.itemQuantity) || input.itemQuantity < 1 || input.itemQuantity > 1e3) {
415
+ throw invalidInput("itemQuantity", input.itemQuantity, "must be an integer 1..1000");
416
+ }
417
+ const unit = parseMoney(input.unitPrice, MAX_ITEM_PRICE, "unitPrice");
418
+ const total = parseMoney(input.totalPrice, MAX_ITEM_PRICE, "totalPrice");
419
+ const expectedCents = Math.round(unit * input.itemQuantity * 100);
420
+ const totalCents = Math.round(total * 100);
421
+ if (Math.abs(totalCents - expectedCents) > 1) {
422
+ throw invalidInput(
423
+ "totalPrice",
424
+ input.totalPrice,
425
+ `must equal unitPrice \xD7 itemQuantity (\xB10.01): ${unit} \xD7 ${input.itemQuantity}`
426
+ );
427
+ }
428
+ if (input.fundingSource === "card") {
429
+ assertBillingAddress(input.billingAddress, "billingAddress");
430
+ }
431
+ if (input.playerPhone !== void 0) assertE164(input.playerPhone, "playerPhone");
432
+ const body = {
433
+ client_request_id: input.clientRequestId,
434
+ funding_source: input.fundingSource,
435
+ player_email: input.playerEmail,
436
+ player_name: input.playerName,
437
+ item_id: input.itemId,
438
+ item_name: input.itemName,
439
+ item_quantity: input.itemQuantity,
440
+ unit_price: input.unitPrice,
441
+ total_price: input.totalPrice
442
+ };
443
+ if (input.playerPhone) body["player_phone"] = input.playerPhone;
444
+ if (input.itemDescription) body["item_description"] = input.itemDescription;
445
+ if (input.itemCategory) body["item_category"] = input.itemCategory;
446
+ if (input.billingAddress) body["billing_address"] = toBillingAddressBody(input.billingAddress);
447
+ const raw = await this.http.post(
448
+ "/api/platform-commerce/purchase",
449
+ body,
450
+ this.auth,
451
+ { idempotent: true, signal: opts?.signal }
452
+ // client_request_id makes this safe to retry (dup → 409)
453
+ );
454
+ const orderIdRaw = raw["order_id"];
455
+ requireField(orderIdRaw, "order_id", raw);
456
+ const status = String(raw["status"] ?? "");
457
+ if (status === "requires_payment" && !raw["client_secret"]) {
458
+ requireField(raw["client_secret"], "client_secret", raw);
459
+ }
460
+ return {
461
+ status,
462
+ fundingSource: String(raw["funding_source"] ?? input.fundingSource),
463
+ orderId: orderIdRaw,
464
+ transactionId: raw["transaction_id"],
465
+ newBalance: raw["new_balance"] ?? null,
466
+ previousBalance: raw["previous_balance"] ?? null,
467
+ currencyName: raw["currency_name"],
468
+ financialBreakdown: raw["financial_breakdown"],
469
+ clientSecret: raw["client_secret"],
470
+ amountUsd: raw["amount_usd"] ?? null,
471
+ raw
472
+ };
473
+ }
474
+ /** Poll an order's status: `completed` (balance immediately; card after the webhook),
475
+ * `pending_payment` (card awaiting confirmation), or `refunded`. */
476
+ async getStatus(orderId, opts) {
477
+ if (orderId == null || String(orderId).trim() === "") {
478
+ throw invalidInput("orderId", orderId, "is required");
479
+ }
480
+ const raw = await this.http.get(
481
+ `/api/platform-commerce/purchase-status/${encodeURIComponent(String(orderId))}`,
482
+ this.auth,
483
+ { signal: opts?.signal }
484
+ );
485
+ return {
486
+ orderId: raw["order_id"] ?? orderId,
487
+ status: String(raw["status"] ?? ""),
488
+ gameCurrencyAmount: raw["game_currency_amount"] ?? null,
489
+ usdAmount: raw["usd_amount"] ?? null,
490
+ paymentMethod: raw["payment_method"],
491
+ createdAt: raw["created_at"],
492
+ raw
493
+ };
494
+ }
495
+ /**
496
+ * Refund a completed purchase. Provide EXACTLY ONE of `orderId` or `clientRequestId`.
497
+ * INVO retains its fee — the customer is made whole (balance re-credit or card refund)
498
+ * minus that fee. Idempotent on the order: a second refund throws a 409
499
+ * (`err.isAlreadyRefunded`) — treat that as "already done", not a failure.
500
+ */
501
+ async refund(input, opts) {
502
+ const hasOrder = input.orderId != null && String(input.orderId).trim() !== "";
503
+ const hasReq = typeof input.clientRequestId === "string" && input.clientRequestId.trim() !== "";
504
+ if (hasOrder === hasReq) {
505
+ throw new InvoError({
506
+ message: "refund requires EXACTLY ONE of orderId or clientRequestId.",
507
+ code: "INVALID_INPUT",
508
+ status: 0
509
+ });
510
+ }
511
+ const body = {};
512
+ if (hasOrder) body["order_id"] = input.orderId;
513
+ else body["client_request_id"] = input.clientRequestId;
514
+ if (input.reason) body["reason"] = input.reason;
515
+ const raw = await this.http.post(
516
+ "/api/platform-commerce/refund",
517
+ body,
518
+ this.auth,
519
+ // Idempotent on the order: a lost-response retry re-refunds nothing (backend 409s
520
+ // "already refunded"), so a transient 5xx/network retry is safe.
521
+ { idempotent: true, signal: opts?.signal }
522
+ );
523
+ const fundingSource = raw["funding_source"];
524
+ return {
525
+ status: String(raw["status"] ?? ""),
526
+ orderId: raw["order_id"] ?? void 0,
527
+ fundingSource,
528
+ transactionId: raw["transaction_id"],
529
+ // Backend key differs per leg: `refunded_amount` (balance) / `refunded_amount_usd` (card).
530
+ refundedAmount: raw["refunded_amount"] ?? raw["refunded_amount_usd"] ?? null,
531
+ // The refund HTTP response carries no unit; derive it (card → USD). The balance leg's
532
+ // unit is the tenant's network currency, not present here — left undefined.
533
+ amountUnit: raw["amount_unit"] ?? (fundingSource === "card" ? "usd" : void 0),
534
+ // Balance leg: the canonical post-refund balance. Card leg: the processor's refund id.
535
+ newBalance: raw["new_balance"] ?? null,
536
+ processorRefundId: raw["stripe_refund_id"],
537
+ feeRetained: raw["fee_retained"] === true,
538
+ raw
539
+ };
540
+ }
541
+ };
331
542
  var InvoServer = class {
332
543
  constructor(config) {
333
544
  if (!config.gameSecret) throw new Error("InvoServer requires a `gameSecret`.");
@@ -344,6 +555,7 @@ var InvoServer = class {
344
555
  hooks: config.hooks
345
556
  });
346
557
  this.auth = { kind: "game-secret", secret: config.gameSecret };
558
+ this.platformCommerce = new PlatformCommerceServer(this.http, this.auth);
347
559
  }
348
560
  /**
349
561
  * Mint a short-lived, game-scoped player token to hand to the browser InvoClient.
@@ -1023,6 +1235,6 @@ var InvoServer = class {
1023
1235
  }
1024
1236
  };
1025
1237
 
1026
- export { InvoServer, createWebhookHandler, verifyWebhook, verifyWebhookAsync };
1238
+ export { InvoServer, PlatformCommerceServer, createWebhookHandler, verifyWebhook, verifyWebhookAsync };
1027
1239
  //# sourceMappingURL=server.js.map
1028
1240
  //# sourceMappingURL=server.js.map
@@ -102,8 +102,27 @@ declare class InvoError extends Error {
102
102
  get isNonSteamValueIntoSteamBlocked(): boolean;
103
103
  /** True if the phone-share (phone, requesting_email) pair was already approved. */
104
104
  get isPhoneShareAlreadyApproved(): boolean;
105
- /** True if an idempotency-keyed request was a duplicate (item purchase → 409). */
105
+ /** True if an idempotency-keyed request was a duplicate (item / platform purchase → 409). */
106
106
  get isDuplicateRequest(): boolean;
107
+ /**
108
+ * True if a Platform Commerce call was rejected because the tenant isn't a platform
109
+ * tenant (`NOT_A_PLATFORM_TENANT`, 403). Platform Commerce (`invo.platformCommerce.*`)
110
+ * is only for non-game platform tenants — a game tenant should use `purchaseItem`
111
+ * (spend game currency) or `createCheckout`/`purchaseCurrency` (buy currency) instead.
112
+ */
113
+ get isNotPlatformTenant(): boolean;
114
+ /** True if a Platform Commerce purchase was too small for the fee to round above zero
115
+ * (`AMOUNT_BELOW_MINIMUM`, 400) — raise the amount. */
116
+ get isAmountBelowMinimum(): boolean;
117
+ /** True if a Platform Commerce CARD purchase was below the processor's floor of $0.50
118
+ * (backend code `BELOW_STRIPE_MINIMUM`, 400). Neutral name; matches the wire code. */
119
+ get isBelowCardMinimum(): boolean;
120
+ /**
121
+ * True if a Platform Commerce refund targeted an order that was already refunded
122
+ * (409). Idempotent outcome — the original refund did happen, so treat this as
123
+ * success, not a failure to retry-loop.
124
+ */
125
+ get isAlreadyRefunded(): boolean;
107
126
  /** Seconds to wait before retrying, when the backend throttled the call (429 `retry_after`). */
108
127
  get retryAfter(): number | undefined;
109
128
  /** `body` as a plain object, or `{}` if it's a string/number/null (non-JSON responses).
@@ -111,6 +130,15 @@ declare class InvoError extends Error {
111
130
  private bodyObject;
112
131
  }
113
132
 
133
+ type AuthHeader = {
134
+ kind: "game-secret";
135
+ secret: string;
136
+ } | {
137
+ kind: "bearer";
138
+ token: string;
139
+ } | {
140
+ kind: "none";
141
+ };
114
142
  interface InvoRequestInfo {
115
143
  method: string;
116
144
  url: string;
@@ -134,6 +162,55 @@ interface InvoHooks {
134
162
  onResponse?: (info: InvoResponseInfo) => void;
135
163
  onError?: (info: InvoErrorInfo) => void;
136
164
  }
165
+ interface HttpOptions {
166
+ baseUrl: string;
167
+ timeoutMs?: number;
168
+ fetchImpl?: typeof fetch;
169
+ /**
170
+ * Server-side callers MUST send a normal User-Agent. The backend security
171
+ * middleware 403-blocks UAs matching nikto|sqlmap|python-urllib|scanner|bot|^$
172
+ * (case-insensitive). Node's default fetch UA is fine, but be explicit so a
173
+ * stray empty/`node-fetch`/`bot` UA can't get the partner blocked. In the
174
+ * browser this header is forbidden and silently ignored — leave it undefined.
175
+ */
176
+ userAgent?: string;
177
+ /** Max automatic retries on transient failures (network error, 429, 5xx). Default 2. */
178
+ maxRetries?: number;
179
+ /** Base backoff delay in ms (exponential + jitter). Default 250. */
180
+ retryBaseDelayMs?: number;
181
+ /** Optional observability callbacks (onRequest/onResponse/onError). */
182
+ hooks?: InvoHooks;
183
+ }
184
+ declare class Http {
185
+ private readonly baseUrl;
186
+ private readonly timeoutMs;
187
+ private readonly fetchImpl;
188
+ private readonly userAgent;
189
+ private readonly maxRetries;
190
+ private readonly retryBaseDelayMs;
191
+ private readonly hooks;
192
+ /** HTTP statuses worth retrying — rate limit + transient gateway/server errors. */
193
+ private static readonly RETRIABLE_STATUS;
194
+ constructor(opts: HttpOptions);
195
+ /**
196
+ * @param opts.idempotent - mark this POST safe to auto-retry (it carries an
197
+ * idempotency key, or has no side effect). Default false: non-idempotent POSTs
198
+ * (e.g. single-use WebAuthn assertions) are NEVER auto-retried.
199
+ */
200
+ post<T = Record<string, unknown>>(path: string, body: Record<string, unknown> | undefined, auth: AuthHeader, opts?: {
201
+ idempotent?: boolean;
202
+ signal?: AbortSignal;
203
+ }): Promise<T>;
204
+ get<T = Record<string, unknown>>(path: string, auth: AuthHeader, opts?: {
205
+ signal?: AbortSignal;
206
+ }): Promise<T>;
207
+ private authHeaders;
208
+ private request;
209
+ /** Invoke an observability hook, swallowing any error it throws (best-effort). */
210
+ private fire;
211
+ /** Exponential backoff with full jitter: base * 2^attempt, randomized. */
212
+ private backoff;
213
+ }
137
214
 
138
215
  /** Per-call options (e.g. cancellation). Accepted as an optional last arg on SDK methods. */
139
216
  interface CallOptions {
@@ -177,6 +254,13 @@ interface ClientConfig extends InvoConfig {
177
254
  * is retried once with the new token, and the client keeps using it thereafter.
178
255
  */
179
256
  refreshToken?: () => Promise<string> | string;
257
+ /**
258
+ * Optional. The card processor's PUBLISHABLE key (public — safe in the browser),
259
+ * used as the default for `platformCommerce.confirmCardPayment` /
260
+ * `mountCardPayment` when a per-call `publishableKey` isn't given. This is the
261
+ * Platform Commerce CARD leg only; the passkey/token flows never use it.
262
+ */
263
+ commercePublishableKey?: string;
180
264
  }
181
265
  interface PlayerToken {
182
266
  token: string;
@@ -324,6 +408,191 @@ interface ItemOrderQuery {
324
408
  transactionId?: string;
325
409
  clientRequestId?: string;
326
410
  }
411
+ /** How a Platform Commerce purchase is funded. Server-resolved under lock — the client
412
+ * can request it, but the backend verifies the actual balance before value moves. */
413
+ type FundingSource = "balance" | "card";
414
+ /** Billing address — REQUIRED on the card leg (AVS / fraud / merchant-of-record records). */
415
+ interface BillingAddress {
416
+ line1: string;
417
+ city: string;
418
+ postalCode: string;
419
+ /** 2-letter ISO country code, e.g. "US". */
420
+ country: string;
421
+ name?: string;
422
+ line2?: string;
423
+ state?: string;
424
+ }
425
+ interface PlatformPurchaseInput {
426
+ /** Idempotency key, unique per tenant. Required. A duplicate returns 409. */
427
+ clientRequestId: string;
428
+ /** "balance" (spend held INVO currency) or "card" (pay by card — new money). Required;
429
+ * server-validated. */
430
+ fundingSource: FundingSource;
431
+ playerEmail: string;
432
+ playerName: string;
433
+ itemId: string;
434
+ itemName: string;
435
+ /** Integer quantity, 1..1000. */
436
+ itemQuantity: number;
437
+ /** Price PER UNIT. > 0. On the CARD leg this is USD; on the BALANCE leg it is the
438
+ * tenant's network-currency amount. */
439
+ unitPrice: string | number;
440
+ /** Must equal unitPrice × itemQuantity (±0.01). USD on the card leg; network currency
441
+ * on the balance leg. */
442
+ totalPrice: string | number;
443
+ playerPhone?: string;
444
+ itemDescription?: string;
445
+ itemCategory?: string;
446
+ /** REQUIRED when `fundingSource` is "card"; ignored on the balance leg. */
447
+ billingAddress?: BillingAddress;
448
+ }
449
+ /** "success" → BALANCE leg settled synchronously. "requires_payment" → CARD leg: hand
450
+ * `clientSecret` to the browser `platformCommerce.confirmCardPayment`. */
451
+ type PlatformPurchaseStatus = "success" | "requires_payment";
452
+ interface PlatformPurchaseResult {
453
+ /** "success" (balance settled) | "requires_payment" (card — confirm in the browser). */
454
+ status: string;
455
+ fundingSource: string;
456
+ orderId: string | number;
457
+ transactionId?: string;
458
+ /** Canonical balance AFTER the debit (balance leg). */
459
+ newBalance?: string | number | null;
460
+ previousBalance?: string | number | null;
461
+ currencyName?: string;
462
+ /** { total_paid, developer_revenue, platform_fee } when present. */
463
+ financialBreakdown?: Record<string, unknown>;
464
+ /** Hand to the browser `platformCommerce.confirmCardPayment`. Present on the card leg. */
465
+ clientSecret?: string;
466
+ amountUsd?: string | number | null;
467
+ raw: Record<string, unknown>;
468
+ }
469
+ interface PlatformOrderStatusResult {
470
+ orderId: string | number;
471
+ /** "completed" (balance immediately; card after the webhook) | "pending_payment"
472
+ * (card awaiting confirmation) | "refunded". */
473
+ status: string;
474
+ gameCurrencyAmount?: string | number | null;
475
+ usdAmount?: string | number | null;
476
+ paymentMethod?: string;
477
+ createdAt?: string;
478
+ raw: Record<string, unknown>;
479
+ }
480
+ interface PlatformRefundInput {
481
+ /** Provide EXACTLY ONE of orderId or clientRequestId. */
482
+ orderId?: string | number;
483
+ clientRequestId?: string;
484
+ reason?: string;
485
+ }
486
+ interface PlatformRefundResult {
487
+ /** "refunded" on success. A second refund of the same order throws a 409
488
+ * (`err.isAlreadyRefunded`). */
489
+ status: string;
490
+ orderId?: string | number;
491
+ fundingSource?: string;
492
+ transactionId?: string;
493
+ /** The refunded value. The backend sends `refunded_amount` (balance) or
494
+ * `refunded_amount_usd` (card) — both are surfaced here. */
495
+ refundedAmount?: string | number | null;
496
+ /** `"usd"` on the card leg. The balance leg's amount is in the tenant's network
497
+ * currency; the refund response carries no unit, so this is `undefined` there
498
+ * (the `platform_commerce.refunded` webhook is authoritative for the unit). */
499
+ amountUnit?: string;
500
+ /** Balance leg only: the canonical balance AFTER the re-credit. */
501
+ newBalance?: string | number | null;
502
+ /** Card leg only: the card processor's refund id (for support/reconciliation). */
503
+ processorRefundId?: string;
504
+ /** Always true — INVO retains its fee; the customer is made whole minus that fee. */
505
+ feeRetained?: boolean;
506
+ raw: Record<string, unknown>;
507
+ }
508
+ /**
509
+ * Minimal structural shape of the card processor's browser object (Stripe.js `Stripe`),
510
+ * kept neutral so the public surface never names the processor. The default loader wraps
511
+ * `window.Stripe(publishableKey)` — which already satisfies this shape.
512
+ */
513
+ interface InvoCardProcessor {
514
+ elements(opts: {
515
+ clientSecret: string;
516
+ appearance?: Record<string, unknown>;
517
+ }): InvoCardElements;
518
+ confirmPayment(args: {
519
+ elements: InvoCardElements;
520
+ clientSecret?: string;
521
+ confirmParams?: {
522
+ return_url?: string;
523
+ };
524
+ /** "if_required" keeps the flow in-page unless the bank forces a redirect. */
525
+ redirect?: "if_required" | "always";
526
+ }): Promise<InvoCardConfirmResponse>;
527
+ }
528
+ interface InvoCardElements {
529
+ create(type: string, opts?: Record<string, unknown>): InvoCardElement;
530
+ }
531
+ interface InvoCardElement {
532
+ mount(target: string | HTMLElement): void;
533
+ unmount?(): void;
534
+ }
535
+ interface InvoCardConfirmResponse {
536
+ error?: {
537
+ message?: string;
538
+ code?: string;
539
+ [k: string]: unknown;
540
+ };
541
+ paymentIntent?: {
542
+ id?: string;
543
+ status?: string;
544
+ [k: string]: unknown;
545
+ };
546
+ [k: string]: unknown;
547
+ }
548
+ interface MountCardPaymentOptions {
549
+ /** Where the Payment Element renders: a CSS selector or an HTMLElement. */
550
+ mount: string | HTMLElement;
551
+ /** The card processor PUBLISHABLE key (public). Falls back to
552
+ * `ClientConfig.commercePublishableKey`. */
553
+ publishableKey?: string;
554
+ /** URL the processor returns to after any off-site step (e.g. 3-D Secure). */
555
+ returnUrl?: string;
556
+ /** Payment Element appearance/config, passed straight to the processor. */
557
+ appearance?: Record<string, unknown>;
558
+ /** Advanced/testing: inject the processor instead of loading it from the CDN. */
559
+ loadProcessor?: (publishableKey: string) => Promise<InvoCardProcessor>;
560
+ }
561
+ interface ConfirmCardPaymentOptions extends MountCardPaymentOptions {
562
+ /** Your existing "Pay" button (selector or element). If omitted, the SDK renders a
563
+ * minimal button inside `mount` (requires a DOM `document`). */
564
+ submit?: string | HTMLElement;
565
+ /** Label for the auto-rendered button when `submit` is omitted. Default "Pay". */
566
+ submitLabel?: string;
567
+ }
568
+ type CardPaymentStatus = "succeeded" | "requires_action" | "processing" | "failed";
569
+ interface CardPaymentResult {
570
+ /**
571
+ * "succeeded" — the processor captured/authorized (still fulfill on the
572
+ * `platform_commerce.purchased` webhook, never on this alone). "requires_action" — the
573
+ * bank needs a step (e.g. redirect). "processing" — async settlement in flight.
574
+ * "failed" — declined/errored (`error` carries the message).
575
+ */
576
+ status: CardPaymentStatus;
577
+ paymentIntentId?: string;
578
+ /** Present on "failed": the processor's error message. */
579
+ error?: string;
580
+ /** The processor's full confirm response. NOTE: includes the PaymentIntent, whose
581
+ * `client_secret` is semi-public but still shouldn't be written to logs — redact
582
+ * `raw` if you log these results. */
583
+ raw: Record<string, unknown>;
584
+ }
585
+ /** Handle returned by `mountCardPayment`: confirm on your own button, then tear down. */
586
+ interface CardPaymentSession {
587
+ /** The mounted Payment Element (processor-native object). */
588
+ element: InvoCardElement;
589
+ /** Confirm the payment (call from your Pay button's click handler). */
590
+ confirm(opts?: {
591
+ returnUrl?: string;
592
+ }): Promise<CardPaymentResult>;
593
+ /** Unmount the Payment Element. */
594
+ destroy(): void;
595
+ }
327
596
  interface PlayerBalanceQuery {
328
597
  /** Look up by email, or by playerId — provide one. */
329
598
  playerEmail?: string;
@@ -677,4 +946,4 @@ interface PhoneShareStatusResult {
677
946
  raw: Record<string, unknown>;
678
947
  }
679
948
 
680
- export { type PhoneShareInitiateResult as $, type ApproveResult as A, type BalanceResult as B, type ClientConfig as C, type DestinationsQuery as D, type EnrollmentBeginResult as E, type ItemOrderQuery as F, type PlayerBalanceQuery as G, type PlayerBalanceResult as H, InvoError as I, type InboundPendingQuery as J, type InboundPendingResult as K, type LinkDeviceResult as L, type LinkedIdentitiesQuery as M, type LinkedIdentitiesResult as N, type OrderDetailsResult as O, type PendingCollectResult as P, type SmsVerifyResult as Q, type RecoveryBeginResult as R, type ServerConfig as S, type ClaimTransferInput as T, type ClaimResult as U, type VerificationMethod as V, type ClaimCurrencyInput as W, type TransactionStatusResult as X, type GuardianApprovalStatusResult as Y, type ServerDestinationsQuery as Z, type PhoneShareContact as _, type CallOptions as a, type PhoneShareApproveInput as a0, type PhoneShareApproveResult as a1, type PhoneShareStatusResult as a2, type CurrencyBalance as a3, type InboundPendingItem as a4, type LinkedIdentityEmail as a5, type ConfirmReceiptResult as b, type DestinationsResult as c, type EnrollmentVerifyResult as d, type RecoveryCompleteResult as e, type BalanceRow as f, type DestinationGame as g, type InvoErrorInfo as h, type InvoHooks as i, type InvoRequestInfo as j, type InvoResponseInfo as k, type PendingCollectItem as l, type Rail as m, type PlayerToken as n, type InitiateSendInput as o, type InitiateResult as p, type InitiateTransferInput as q, type CreateCheckoutInput as r, type CreateCheckoutResult as s, type PurchaseInput as t, type PurchaseResult as u, type ConfirmPaymentResult as v, type PurchaseItemInput as w, type PurchaseItemResult as x, type ItemHistoryQuery as y, type ItemHistoryResult as z };
949
+ export { type ItemHistoryResult as $, type ApproveResult as A, type BalanceResult as B, type CardPaymentSession as C, type DestinationsQuery as D, type EnrollmentBeginResult as E, type PlatformRefundResult as F, type PlayerToken as G, Http as H, type InvoCardConfirmResponse as I, type InitiateSendInput as J, type InitiateResult as K, type LinkDeviceResult as L, type MountCardPaymentOptions as M, type InitiateTransferInput as N, type CreateCheckoutInput as O, type PendingCollectResult as P, type CreateCheckoutResult as Q, type RecoveryBeginResult as R, type ServerConfig as S, type PurchaseInput as T, type PurchaseResult as U, type VerificationMethod as V, type ConfirmPaymentResult as W, type OrderDetailsResult as X, type PurchaseItemInput as Y, type PurchaseItemResult as Z, type ItemHistoryQuery as _, type ConfirmCardPaymentOptions as a, type ItemOrderQuery as a0, type PlayerBalanceQuery as a1, type PlayerBalanceResult as a2, type InboundPendingQuery as a3, type InboundPendingResult as a4, type LinkedIdentitiesQuery as a5, type LinkedIdentitiesResult as a6, type SmsVerifyResult as a7, type ClaimTransferInput as a8, type ClaimResult as a9, type ClaimCurrencyInput as aa, type TransactionStatusResult as ab, type GuardianApprovalStatusResult as ac, type ServerDestinationsQuery as ad, type PhoneShareContact as ae, type PhoneShareInitiateResult as af, type PhoneShareApproveInput as ag, type PhoneShareApproveResult as ah, type PhoneShareStatusResult as ai, type BillingAddress as aj, type CurrencyBalance as ak, type FundingSource as al, type InboundPendingItem as am, type LinkedIdentityEmail as an, type PlatformPurchaseStatus as ao, type CardPaymentResult as b, type ClientConfig as c, type CallOptions as d, type ConfirmReceiptResult as e, type DestinationsResult as f, type EnrollmentVerifyResult as g, type RecoveryCompleteResult as h, type BalanceRow as i, type CardPaymentStatus as j, type DestinationGame as k, type InvoCardElement as l, type InvoCardElements as m, type InvoCardProcessor as n, InvoError as o, type InvoErrorInfo as p, type InvoHooks as q, type InvoRequestInfo as r, type InvoResponseInfo as s, type PendingCollectItem as t, type Rail as u, type AuthHeader as v, type PlatformPurchaseInput as w, type PlatformPurchaseResult as x, type PlatformOrderStatusResult as y, type PlatformRefundInput as z };