@invonetwork/web-sdk 2.4.1 → 2.5.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.
@@ -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,184 @@ 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
+ /** Always true — INVO retains its fee; the customer is made whole minus that fee. */
501
+ feeRetained?: boolean;
502
+ raw: Record<string, unknown>;
503
+ }
504
+ /**
505
+ * Minimal structural shape of the card processor's browser object (Stripe.js `Stripe`),
506
+ * kept neutral so the public surface never names the processor. The default loader wraps
507
+ * `window.Stripe(publishableKey)` — which already satisfies this shape.
508
+ */
509
+ interface InvoCardProcessor {
510
+ elements(opts: {
511
+ clientSecret: string;
512
+ appearance?: Record<string, unknown>;
513
+ }): InvoCardElements;
514
+ confirmPayment(args: {
515
+ elements: InvoCardElements;
516
+ clientSecret?: string;
517
+ confirmParams?: {
518
+ return_url?: string;
519
+ };
520
+ /** "if_required" keeps the flow in-page unless the bank forces a redirect. */
521
+ redirect?: "if_required" | "always";
522
+ }): Promise<InvoCardConfirmResponse>;
523
+ }
524
+ interface InvoCardElements {
525
+ create(type: string, opts?: Record<string, unknown>): InvoCardElement;
526
+ }
527
+ interface InvoCardElement {
528
+ mount(target: string | HTMLElement): void;
529
+ unmount?(): void;
530
+ }
531
+ interface InvoCardConfirmResponse {
532
+ error?: {
533
+ message?: string;
534
+ code?: string;
535
+ [k: string]: unknown;
536
+ };
537
+ paymentIntent?: {
538
+ id?: string;
539
+ status?: string;
540
+ [k: string]: unknown;
541
+ };
542
+ [k: string]: unknown;
543
+ }
544
+ interface MountCardPaymentOptions {
545
+ /** Where the Payment Element renders: a CSS selector or an HTMLElement. */
546
+ mount: string | HTMLElement;
547
+ /** The card processor PUBLISHABLE key (public). Falls back to
548
+ * `ClientConfig.commercePublishableKey`. */
549
+ publishableKey?: string;
550
+ /** URL the processor returns to after any off-site step (e.g. 3-D Secure). */
551
+ returnUrl?: string;
552
+ /** Payment Element appearance/config, passed straight to the processor. */
553
+ appearance?: Record<string, unknown>;
554
+ /** Advanced/testing: inject the processor instead of loading it from the CDN. */
555
+ loadProcessor?: (publishableKey: string) => Promise<InvoCardProcessor>;
556
+ }
557
+ interface ConfirmCardPaymentOptions extends MountCardPaymentOptions {
558
+ /** Your existing "Pay" button (selector or element). If omitted, the SDK renders a
559
+ * minimal button inside `mount` (requires a DOM `document`). */
560
+ submit?: string | HTMLElement;
561
+ /** Label for the auto-rendered button when `submit` is omitted. Default "Pay". */
562
+ submitLabel?: string;
563
+ }
564
+ type CardPaymentStatus = "succeeded" | "requires_action" | "processing" | "failed";
565
+ interface CardPaymentResult {
566
+ /**
567
+ * "succeeded" — the processor captured/authorized (still fulfill on the
568
+ * `platform_commerce.purchased` webhook, never on this alone). "requires_action" — the
569
+ * bank needs a step (e.g. redirect). "processing" — async settlement in flight.
570
+ * "failed" — declined/errored (`error` carries the message).
571
+ */
572
+ status: CardPaymentStatus;
573
+ paymentIntentId?: string;
574
+ /** Present on "failed": the processor's error message. */
575
+ error?: string;
576
+ raw: Record<string, unknown>;
577
+ }
578
+ /** Handle returned by `mountCardPayment`: confirm on your own button, then tear down. */
579
+ interface CardPaymentSession {
580
+ /** The mounted Payment Element (processor-native object). */
581
+ element: InvoCardElement;
582
+ /** Confirm the payment (call from your Pay button's click handler). */
583
+ confirm(opts?: {
584
+ returnUrl?: string;
585
+ }): Promise<CardPaymentResult>;
586
+ /** Unmount the Payment Element. */
587
+ destroy(): void;
588
+ }
327
589
  interface PlayerBalanceQuery {
328
590
  /** Look up by email, or by playerId — provide one. */
329
591
  playerEmail?: string;
@@ -677,4 +939,4 @@ interface PhoneShareStatusResult {
677
939
  raw: Record<string, unknown>;
678
940
  }
679
941
 
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 };
942
+ 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 };
@@ -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,184 @@ 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
+ /** Always true — INVO retains its fee; the customer is made whole minus that fee. */
501
+ feeRetained?: boolean;
502
+ raw: Record<string, unknown>;
503
+ }
504
+ /**
505
+ * Minimal structural shape of the card processor's browser object (Stripe.js `Stripe`),
506
+ * kept neutral so the public surface never names the processor. The default loader wraps
507
+ * `window.Stripe(publishableKey)` — which already satisfies this shape.
508
+ */
509
+ interface InvoCardProcessor {
510
+ elements(opts: {
511
+ clientSecret: string;
512
+ appearance?: Record<string, unknown>;
513
+ }): InvoCardElements;
514
+ confirmPayment(args: {
515
+ elements: InvoCardElements;
516
+ clientSecret?: string;
517
+ confirmParams?: {
518
+ return_url?: string;
519
+ };
520
+ /** "if_required" keeps the flow in-page unless the bank forces a redirect. */
521
+ redirect?: "if_required" | "always";
522
+ }): Promise<InvoCardConfirmResponse>;
523
+ }
524
+ interface InvoCardElements {
525
+ create(type: string, opts?: Record<string, unknown>): InvoCardElement;
526
+ }
527
+ interface InvoCardElement {
528
+ mount(target: string | HTMLElement): void;
529
+ unmount?(): void;
530
+ }
531
+ interface InvoCardConfirmResponse {
532
+ error?: {
533
+ message?: string;
534
+ code?: string;
535
+ [k: string]: unknown;
536
+ };
537
+ paymentIntent?: {
538
+ id?: string;
539
+ status?: string;
540
+ [k: string]: unknown;
541
+ };
542
+ [k: string]: unknown;
543
+ }
544
+ interface MountCardPaymentOptions {
545
+ /** Where the Payment Element renders: a CSS selector or an HTMLElement. */
546
+ mount: string | HTMLElement;
547
+ /** The card processor PUBLISHABLE key (public). Falls back to
548
+ * `ClientConfig.commercePublishableKey`. */
549
+ publishableKey?: string;
550
+ /** URL the processor returns to after any off-site step (e.g. 3-D Secure). */
551
+ returnUrl?: string;
552
+ /** Payment Element appearance/config, passed straight to the processor. */
553
+ appearance?: Record<string, unknown>;
554
+ /** Advanced/testing: inject the processor instead of loading it from the CDN. */
555
+ loadProcessor?: (publishableKey: string) => Promise<InvoCardProcessor>;
556
+ }
557
+ interface ConfirmCardPaymentOptions extends MountCardPaymentOptions {
558
+ /** Your existing "Pay" button (selector or element). If omitted, the SDK renders a
559
+ * minimal button inside `mount` (requires a DOM `document`). */
560
+ submit?: string | HTMLElement;
561
+ /** Label for the auto-rendered button when `submit` is omitted. Default "Pay". */
562
+ submitLabel?: string;
563
+ }
564
+ type CardPaymentStatus = "succeeded" | "requires_action" | "processing" | "failed";
565
+ interface CardPaymentResult {
566
+ /**
567
+ * "succeeded" — the processor captured/authorized (still fulfill on the
568
+ * `platform_commerce.purchased` webhook, never on this alone). "requires_action" — the
569
+ * bank needs a step (e.g. redirect). "processing" — async settlement in flight.
570
+ * "failed" — declined/errored (`error` carries the message).
571
+ */
572
+ status: CardPaymentStatus;
573
+ paymentIntentId?: string;
574
+ /** Present on "failed": the processor's error message. */
575
+ error?: string;
576
+ raw: Record<string, unknown>;
577
+ }
578
+ /** Handle returned by `mountCardPayment`: confirm on your own button, then tear down. */
579
+ interface CardPaymentSession {
580
+ /** The mounted Payment Element (processor-native object). */
581
+ element: InvoCardElement;
582
+ /** Confirm the payment (call from your Pay button's click handler). */
583
+ confirm(opts?: {
584
+ returnUrl?: string;
585
+ }): Promise<CardPaymentResult>;
586
+ /** Unmount the Payment Element. */
587
+ destroy(): void;
588
+ }
327
589
  interface PlayerBalanceQuery {
328
590
  /** Look up by email, or by playerId — provide one. */
329
591
  playerEmail?: string;
@@ -677,4 +939,4 @@ interface PhoneShareStatusResult {
677
939
  raw: Record<string, unknown>;
678
940
  }
679
941
 
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 };
942
+ 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 };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@invonetwork/web-sdk",
3
- "version": "2.4.1",
3
+ "version": "2.5.0",
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,