@invonetwork/web-sdk 2.5.1 → 3.1.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/CHANGELOG.md +110 -0
- package/README.md +125 -39
- package/dist/{chunk-5X3ESHJR.js → chunk-BPZJ63RM.js} +68 -2
- package/dist/index.cjs +133 -189
- package/dist/index.d.cts +18 -39
- package/dist/index.d.ts +18 -39
- package/dist/index.js +69 -191
- package/dist/server.cjs +134 -69
- package/dist/server.d.cts +39 -19
- package/dist/server.d.ts +39 -19
- package/dist/server.js +70 -71
- package/dist/{types-BHvVjdMV.d.cts → types-DjY-50jn.d.cts} +115 -118
- package/dist/{types-BHvVjdMV.d.ts → types-DjY-50jn.d.ts} +115 -118
- package/package.json +1 -1
|
@@ -100,6 +100,58 @@ declare class InvoError extends Error {
|
|
|
100
100
|
* pick a non-Steam destination (surfaced via `DestinationGame.acceptsSteamOriginValue`).
|
|
101
101
|
*/
|
|
102
102
|
get isNonSteamValueIntoSteamBlocked(): boolean;
|
|
103
|
+
/**
|
|
104
|
+
* True if the initiate was refused because **the caller's OWN game is in testing**
|
|
105
|
+
* (`SOURCE_GAME_NOT_LIVE`, 403). Reaches this SDK via `initiateSend` / `initiateTransfer`;
|
|
106
|
+
* the backend uses the same code on its Amazon rewards-send path too (not wrapped here),
|
|
107
|
+
* so one branch keeps working if that flow is ever added.
|
|
108
|
+
*
|
|
109
|
+
* **The caller can self-serve this**: switch the game to Live in the developer console
|
|
110
|
+
* (Game Settings → Status). Show `err.message` — it names the game and the exact control.
|
|
111
|
+
* `err.gameStatus` carries the current state if you want to render it.
|
|
112
|
+
*
|
|
113
|
+
* Deliberately distinct from {@link isTargetGameNotLive} — do NOT collapse the two into
|
|
114
|
+
* one "not live" case. The remediation differs: this one the developer can fix, the
|
|
115
|
+
* other one they cannot.
|
|
116
|
+
*/
|
|
117
|
+
get isSourceGameNotLive(): boolean;
|
|
118
|
+
/**
|
|
119
|
+
* True if the initiate was refused because **the DESTINATION game is in testing**
|
|
120
|
+
* (`TARGET_GAME_NOT_LIVE`, 403). Reaches this SDK via `initiateSend` / `initiateTransfer`;
|
|
121
|
+
* same backend vocabulary on the Amazon rewards-send path (not wrapped here).
|
|
122
|
+
*
|
|
123
|
+
* **The caller usually CANNOT fix this** — the destination is another developer's game
|
|
124
|
+
* and only its owner can switch it to Live. Don't offer a "go fix it" action; show
|
|
125
|
+
* `err.message` and, ideally, steer the player to a different destination
|
|
126
|
+
* (`getDestinations`). `err.gameStatus` carries the current state.
|
|
127
|
+
*
|
|
128
|
+
* Deliberately distinct from {@link isSourceGameNotLive} — see the note there.
|
|
129
|
+
*/
|
|
130
|
+
get isTargetGameNotLive(): boolean;
|
|
131
|
+
/**
|
|
132
|
+
* The game's current status from a `*_GAME_NOT_LIVE` refusal (`game_status`, e.g.
|
|
133
|
+
* `"testing"`) — for rendering the actual state. Present on both the source and target
|
|
134
|
+
* refusals.
|
|
135
|
+
*/
|
|
136
|
+
get gameStatus(): string | undefined;
|
|
137
|
+
/**
|
|
138
|
+
* True if the tenant has **no verified WebAuthn RP ID**, so passkey endpoints are dark
|
|
139
|
+
* (`WEBAUTHN_NOT_ENABLED_FOR_TENANT`, 403).
|
|
140
|
+
*
|
|
141
|
+
* **This is a configuration state, not a failure.** Passkey step-up is per-tenant and
|
|
142
|
+
* stays dark until the developer verifies a domain in the console. Treat it as
|
|
143
|
+
* "this tenant hasn't enabled passkeys yet" and fall back to the SMS/in-app path rather
|
|
144
|
+
* than surfacing an error to the player — the ceremony was never available to fail.
|
|
145
|
+
*
|
|
146
|
+
* This is currently the COMMON case, not an edge case: as of 2026-08-05 only 4 of 23
|
|
147
|
+
* sandbox tenants and **0 of 3 production tenants** have a verified RP ID. Every
|
|
148
|
+
* integration needs this branch until domain verification is widespread.
|
|
149
|
+
*
|
|
150
|
+
* The fix (for the developer's own tenant) is to verify a domain — see the passkey
|
|
151
|
+
* prerequisites in the README. Note this refusal carries the code on `code`, not
|
|
152
|
+
* `error_code`; the SDK reads both, so `err.code` is populated either way.
|
|
153
|
+
*/
|
|
154
|
+
get isWebauthnNotEnabledForTenant(): boolean;
|
|
103
155
|
/** True if the phone-share (phone, requesting_email) pair was already approved. */
|
|
104
156
|
get isPhoneShareAlreadyApproved(): boolean;
|
|
105
157
|
/** True if an idempotency-keyed request was a duplicate (item / platform purchase → 409). */
|
|
@@ -117,6 +169,9 @@ declare class InvoError extends Error {
|
|
|
117
169
|
/** True if a Platform Commerce CARD purchase was below the processor's floor of $0.50
|
|
118
170
|
* (backend code `BELOW_STRIPE_MINIMUM`, 400). Neutral name; matches the wire code. */
|
|
119
171
|
get isBelowCardMinimum(): boolean;
|
|
172
|
+
/** True if a Platform Commerce CARD purchase exceeded the hosted checkout's single-charge
|
|
173
|
+
* cap of $999.99 (`ABOVE_CARD_MAXIMUM`, 400) — split the sale or lower the amount. */
|
|
174
|
+
get isAboveCardMaximum(): boolean;
|
|
120
175
|
/**
|
|
121
176
|
* True if a Platform Commerce refund targeted an order that was already refunded
|
|
122
177
|
* (409). Idempotent outcome — the original refund did happen, so treat this as
|
|
@@ -220,7 +275,14 @@ interface CallOptions {
|
|
|
220
275
|
/** Public, neutral payment-rail names. Provider/processor names are an internal
|
|
221
276
|
* backend routing detail and are deliberately NOT exposed here. */
|
|
222
277
|
type Rail = "platform" | "game" | "steam";
|
|
223
|
-
/**
|
|
278
|
+
/**
|
|
279
|
+
* Verification method returned by initiate-send / initiate-transfer.
|
|
280
|
+
*
|
|
281
|
+
* These are NOT two equivalent options. `"in_app"` is the passkey (WebAuthn) approve —
|
|
282
|
+
* the gold standard and the path to build for. `"sms"` means the sender has **no passkey
|
|
283
|
+
* enrolled** and the backend fell back to a PIN; treat it as a prompt to enroll, not as a
|
|
284
|
+
* destination. The SMS-PIN path is being phased out.
|
|
285
|
+
*/
|
|
224
286
|
type VerificationMethod = "in_app" | "sms";
|
|
225
287
|
interface InvoConfig {
|
|
226
288
|
/** API base URL. Prod: "https://invo.network". Sandbox: "https://sandbox.invo.network/sandbox". */
|
|
@@ -254,13 +316,6 @@ interface ClientConfig extends InvoConfig {
|
|
|
254
316
|
* is retried once with the new token, and the client keeps using it thereafter.
|
|
255
317
|
*/
|
|
256
318
|
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;
|
|
264
319
|
}
|
|
265
320
|
interface PlayerToken {
|
|
266
321
|
token: string;
|
|
@@ -292,7 +347,11 @@ interface InitiateTransferInput {
|
|
|
292
347
|
interface InitiateResult {
|
|
293
348
|
transactionId: string;
|
|
294
349
|
/**
|
|
295
|
-
* "in_app" → proceed to the
|
|
350
|
+
* `"in_app"` → the sender has a passkey; proceed to the approve flow (the recommended
|
|
351
|
+
* and only non-deprecated path). `"sms"` → the sender has **no passkey**, so a PIN was
|
|
352
|
+
* sent as a last-resort fallback — the best response is to offer `enrollPasskey()` and
|
|
353
|
+
* then `approveSend`/`approveTransfer`, falling back to the PIN pad only if they can't
|
|
354
|
+
* or won't enroll. The SMS-PIN completion is being phased out.
|
|
296
355
|
* `undefined` when the backend returned the minor/guardian path (HTTP 202) and
|
|
297
356
|
* no verification method applies yet — check `guardianApproval` and do NOT route
|
|
298
357
|
* the user into the SMS-PIN UI in that case (§4.3 / §8).
|
|
@@ -411,19 +470,9 @@ interface ItemOrderQuery {
|
|
|
411
470
|
/** How a Platform Commerce purchase is funded. Server-resolved under lock — the client
|
|
412
471
|
* can request it, but the backend verifies the actual balance before value moves. */
|
|
413
472
|
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
473
|
interface PlatformPurchaseInput {
|
|
426
|
-
/** Idempotency key, unique per tenant. Required.
|
|
474
|
+
/** Idempotency key, unique per tenant. Required. Balance leg: a duplicate returns 409.
|
|
475
|
+
* Card leg: a duplicate REPLAYS the same checkout session (`idempotentReplay: true`). */
|
|
427
476
|
clientRequestId: string;
|
|
428
477
|
/** "balance" (spend held INVO currency) or "card" (pay by card — new money). Required;
|
|
429
478
|
* server-validated. */
|
|
@@ -437,23 +486,29 @@ interface PlatformPurchaseInput {
|
|
|
437
486
|
/** Price PER UNIT. > 0. On the CARD leg this is USD; on the BALANCE leg it is the
|
|
438
487
|
* tenant's network-currency amount. */
|
|
439
488
|
unitPrice: string | number;
|
|
440
|
-
/** Must equal unitPrice × itemQuantity (±0.01). USD on the card leg
|
|
441
|
-
* on the balance leg. */
|
|
489
|
+
/** Must equal unitPrice × itemQuantity (±0.01). USD on the card leg (min $0.50,
|
|
490
|
+
* max $999.99); network currency on the balance leg. */
|
|
442
491
|
totalPrice: string | number;
|
|
443
492
|
playerPhone?: string;
|
|
444
493
|
itemDescription?: string;
|
|
445
494
|
itemCategory?: string;
|
|
446
|
-
/**
|
|
447
|
-
|
|
495
|
+
/** Card leg only: where INVO's hosted checkout sends the buyer after payment. */
|
|
496
|
+
successUrl?: string;
|
|
497
|
+
/** Card leg only: where the hosted checkout sends the buyer on cancel. */
|
|
498
|
+
cancelUrl?: string;
|
|
499
|
+
/** Card leg only: your correlation object, echoed back on the webhook. */
|
|
500
|
+
metadata?: Record<string, unknown>;
|
|
448
501
|
}
|
|
449
|
-
/** "success" → BALANCE leg settled synchronously. "requires_payment" → CARD leg:
|
|
450
|
-
* `
|
|
502
|
+
/** "success" → BALANCE leg settled synchronously. "requires_payment" → CARD leg: send
|
|
503
|
+
* the buyer to `checkoutUrl` (INVO's hosted checkout page). */
|
|
451
504
|
type PlatformPurchaseStatus = "success" | "requires_payment";
|
|
452
505
|
interface PlatformPurchaseResult {
|
|
453
|
-
/** "success" (balance settled) | "requires_payment" (card —
|
|
506
|
+
/** "success" (balance settled) | "requires_payment" (card — send the buyer to `checkoutUrl`). */
|
|
454
507
|
status: string;
|
|
455
508
|
fundingSource: string;
|
|
456
|
-
|
|
509
|
+
/** Balance leg only — the card leg creates the order lazily on the verified payment,
|
|
510
|
+
* so `requires_payment` responses carry a `sessionId` instead. */
|
|
511
|
+
orderId?: string | number;
|
|
457
512
|
transactionId?: string;
|
|
458
513
|
/** Canonical balance AFTER the debit (balance leg). */
|
|
459
514
|
newBalance?: string | number | null;
|
|
@@ -461,9 +516,17 @@ interface PlatformPurchaseResult {
|
|
|
461
516
|
currencyName?: string;
|
|
462
517
|
/** { total_paid, developer_revenue, platform_fee } when present. */
|
|
463
518
|
financialBreakdown?: Record<string, unknown>;
|
|
464
|
-
/**
|
|
465
|
-
|
|
519
|
+
/** The hosted-checkout session id. Present on the card leg. */
|
|
520
|
+
sessionId?: string;
|
|
521
|
+
/** Send the buyer here (redirect, or `InvoClient.platformCommerce.mountCheckout`).
|
|
522
|
+
* INVO's hosted page owns the card form, wallets, billing address, and 3-D Secure. */
|
|
523
|
+
checkoutUrl?: string;
|
|
524
|
+
/** Unix seconds when the checkout session expires. Present on the card leg. */
|
|
525
|
+
expiresAt?: number;
|
|
466
526
|
amountUsd?: string | number | null;
|
|
527
|
+
/** True when this response REPLAYED an existing session for the same
|
|
528
|
+
* `clientRequestId` (safe retry — same URL, never a second charge). */
|
|
529
|
+
idempotentReplay?: boolean;
|
|
467
530
|
raw: Record<string, unknown>;
|
|
468
531
|
}
|
|
469
532
|
interface PlatformOrderStatusResult {
|
|
@@ -505,92 +568,21 @@ interface PlatformRefundResult {
|
|
|
505
568
|
feeRetained?: boolean;
|
|
506
569
|
raw: Record<string, unknown>;
|
|
507
570
|
}
|
|
508
|
-
|
|
509
|
-
|
|
510
|
-
|
|
511
|
-
|
|
512
|
-
|
|
513
|
-
|
|
514
|
-
|
|
515
|
-
|
|
516
|
-
|
|
517
|
-
|
|
518
|
-
|
|
519
|
-
|
|
520
|
-
|
|
521
|
-
|
|
522
|
-
|
|
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. */
|
|
571
|
+
interface MountCheckoutOptions {
|
|
572
|
+
/** Called when INVO's page posts `INVO_CHECKOUT_COMPLETE` (payment finished in-frame).
|
|
573
|
+
* Show "processing" and reconcile server-side — the sale is REAL only on the
|
|
574
|
+
* `platform_commerce.purchased` webhook, never on this client signal. */
|
|
575
|
+
onComplete?: (data: Record<string, unknown>) => void;
|
|
576
|
+
/** Extra CSS class for the iframe. The SDK sets width:100%/border:0 by default. */
|
|
577
|
+
className?: string;
|
|
578
|
+
/** iframe `title` for accessibility. Default "INVO checkout". */
|
|
579
|
+
title?: string;
|
|
580
|
+
}
|
|
581
|
+
/** Handle returned by `mountCheckout`. */
|
|
582
|
+
interface CheckoutMountHandle {
|
|
583
|
+
/** The mounted iframe element. */
|
|
584
|
+
iframe: HTMLIFrameElement;
|
|
585
|
+
/** Remove the iframe and stop listening for checkout messages. */
|
|
594
586
|
destroy(): void;
|
|
595
587
|
}
|
|
596
588
|
interface PlayerBalanceQuery {
|
|
@@ -823,6 +815,11 @@ interface LinkDeviceResult {
|
|
|
823
815
|
status: string;
|
|
824
816
|
raw: Record<string, unknown>;
|
|
825
817
|
}
|
|
818
|
+
/**
|
|
819
|
+
* Result of `verifySmsTransfer` / `verifySmsSend` — the last-resort path for senders with
|
|
820
|
+
* no passkey. The SMS-PIN completion is being phased out; passkey approve
|
|
821
|
+
* (`InvoClient.approveSend` / `approveTransfer`) is the gold standard.
|
|
822
|
+
*/
|
|
826
823
|
interface SmsVerifyResult {
|
|
827
824
|
/** "success" on a completed verification. */
|
|
828
825
|
status: string;
|
|
@@ -946,4 +943,4 @@ interface PhoneShareStatusResult {
|
|
|
946
943
|
raw: Record<string, unknown>;
|
|
947
944
|
}
|
|
948
945
|
|
|
949
|
-
export { type
|
|
946
|
+
export { type LinkedIdentitiesResult as $, type ApproveResult as A, type BalanceResult as B, type CheckoutMountHandle as C, type DestinationsQuery as D, type EnrollmentBeginResult as E, type PurchaseInput as F, type PurchaseResult as G, Http as H, InvoError as I, type ConfirmPaymentResult as J, type PurchaseItemInput as K, type LinkDeviceResult as L, type MountCheckoutOptions as M, type PurchaseItemResult as N, type OrderDetailsResult as O, type PendingCollectResult as P, type ItemHistoryQuery as Q, type RecoveryBeginResult as R, type ServerConfig as S, type ItemHistoryResult as T, type ItemOrderQuery as U, type VerificationMethod as V, type PlayerBalanceQuery as W, type PlayerBalanceResult as X, type InboundPendingQuery as Y, type InboundPendingResult as Z, type LinkedIdentitiesQuery as _, type ClientConfig as a, type SmsVerifyResult as a0, type ClaimTransferInput as a1, type ClaimResult as a2, type ClaimCurrencyInput as a3, type TransactionStatusResult as a4, type GuardianApprovalStatusResult as a5, type ServerDestinationsQuery as a6, type PhoneShareContact as a7, type PhoneShareInitiateResult as a8, type PhoneShareApproveInput as a9, type PhoneShareApproveResult as aa, type PhoneShareStatusResult as ab, type CurrencyBalance as ac, type FundingSource as ad, type InboundPendingItem as ae, type LinkedIdentityEmail as af, type PlatformPurchaseStatus as ag, type CallOptions as b, type ConfirmReceiptResult as c, type DestinationsResult as d, type EnrollmentVerifyResult as e, type RecoveryCompleteResult as f, type BalanceRow as g, type DestinationGame as h, type InvoErrorInfo as i, type InvoHooks as j, type InvoRequestInfo as k, type InvoResponseInfo as l, type PendingCollectItem as m, type Rail as n, type AuthHeader as o, type PlatformPurchaseInput as p, type PlatformPurchaseResult as q, type PlatformOrderStatusResult as r, type PlatformRefundInput as s, type PlatformRefundResult as t, type PlayerToken as u, type InitiateSendInput as v, type InitiateResult as w, type InitiateTransferInput as x, type CreateCheckoutInput as y, type CreateCheckoutResult as z };
|
|
@@ -100,6 +100,58 @@ declare class InvoError extends Error {
|
|
|
100
100
|
* pick a non-Steam destination (surfaced via `DestinationGame.acceptsSteamOriginValue`).
|
|
101
101
|
*/
|
|
102
102
|
get isNonSteamValueIntoSteamBlocked(): boolean;
|
|
103
|
+
/**
|
|
104
|
+
* True if the initiate was refused because **the caller's OWN game is in testing**
|
|
105
|
+
* (`SOURCE_GAME_NOT_LIVE`, 403). Reaches this SDK via `initiateSend` / `initiateTransfer`;
|
|
106
|
+
* the backend uses the same code on its Amazon rewards-send path too (not wrapped here),
|
|
107
|
+
* so one branch keeps working if that flow is ever added.
|
|
108
|
+
*
|
|
109
|
+
* **The caller can self-serve this**: switch the game to Live in the developer console
|
|
110
|
+
* (Game Settings → Status). Show `err.message` — it names the game and the exact control.
|
|
111
|
+
* `err.gameStatus` carries the current state if you want to render it.
|
|
112
|
+
*
|
|
113
|
+
* Deliberately distinct from {@link isTargetGameNotLive} — do NOT collapse the two into
|
|
114
|
+
* one "not live" case. The remediation differs: this one the developer can fix, the
|
|
115
|
+
* other one they cannot.
|
|
116
|
+
*/
|
|
117
|
+
get isSourceGameNotLive(): boolean;
|
|
118
|
+
/**
|
|
119
|
+
* True if the initiate was refused because **the DESTINATION game is in testing**
|
|
120
|
+
* (`TARGET_GAME_NOT_LIVE`, 403). Reaches this SDK via `initiateSend` / `initiateTransfer`;
|
|
121
|
+
* same backend vocabulary on the Amazon rewards-send path (not wrapped here).
|
|
122
|
+
*
|
|
123
|
+
* **The caller usually CANNOT fix this** — the destination is another developer's game
|
|
124
|
+
* and only its owner can switch it to Live. Don't offer a "go fix it" action; show
|
|
125
|
+
* `err.message` and, ideally, steer the player to a different destination
|
|
126
|
+
* (`getDestinations`). `err.gameStatus` carries the current state.
|
|
127
|
+
*
|
|
128
|
+
* Deliberately distinct from {@link isSourceGameNotLive} — see the note there.
|
|
129
|
+
*/
|
|
130
|
+
get isTargetGameNotLive(): boolean;
|
|
131
|
+
/**
|
|
132
|
+
* The game's current status from a `*_GAME_NOT_LIVE` refusal (`game_status`, e.g.
|
|
133
|
+
* `"testing"`) — for rendering the actual state. Present on both the source and target
|
|
134
|
+
* refusals.
|
|
135
|
+
*/
|
|
136
|
+
get gameStatus(): string | undefined;
|
|
137
|
+
/**
|
|
138
|
+
* True if the tenant has **no verified WebAuthn RP ID**, so passkey endpoints are dark
|
|
139
|
+
* (`WEBAUTHN_NOT_ENABLED_FOR_TENANT`, 403).
|
|
140
|
+
*
|
|
141
|
+
* **This is a configuration state, not a failure.** Passkey step-up is per-tenant and
|
|
142
|
+
* stays dark until the developer verifies a domain in the console. Treat it as
|
|
143
|
+
* "this tenant hasn't enabled passkeys yet" and fall back to the SMS/in-app path rather
|
|
144
|
+
* than surfacing an error to the player — the ceremony was never available to fail.
|
|
145
|
+
*
|
|
146
|
+
* This is currently the COMMON case, not an edge case: as of 2026-08-05 only 4 of 23
|
|
147
|
+
* sandbox tenants and **0 of 3 production tenants** have a verified RP ID. Every
|
|
148
|
+
* integration needs this branch until domain verification is widespread.
|
|
149
|
+
*
|
|
150
|
+
* The fix (for the developer's own tenant) is to verify a domain — see the passkey
|
|
151
|
+
* prerequisites in the README. Note this refusal carries the code on `code`, not
|
|
152
|
+
* `error_code`; the SDK reads both, so `err.code` is populated either way.
|
|
153
|
+
*/
|
|
154
|
+
get isWebauthnNotEnabledForTenant(): boolean;
|
|
103
155
|
/** True if the phone-share (phone, requesting_email) pair was already approved. */
|
|
104
156
|
get isPhoneShareAlreadyApproved(): boolean;
|
|
105
157
|
/** True if an idempotency-keyed request was a duplicate (item / platform purchase → 409). */
|
|
@@ -117,6 +169,9 @@ declare class InvoError extends Error {
|
|
|
117
169
|
/** True if a Platform Commerce CARD purchase was below the processor's floor of $0.50
|
|
118
170
|
* (backend code `BELOW_STRIPE_MINIMUM`, 400). Neutral name; matches the wire code. */
|
|
119
171
|
get isBelowCardMinimum(): boolean;
|
|
172
|
+
/** True if a Platform Commerce CARD purchase exceeded the hosted checkout's single-charge
|
|
173
|
+
* cap of $999.99 (`ABOVE_CARD_MAXIMUM`, 400) — split the sale or lower the amount. */
|
|
174
|
+
get isAboveCardMaximum(): boolean;
|
|
120
175
|
/**
|
|
121
176
|
* True if a Platform Commerce refund targeted an order that was already refunded
|
|
122
177
|
* (409). Idempotent outcome — the original refund did happen, so treat this as
|
|
@@ -220,7 +275,14 @@ interface CallOptions {
|
|
|
220
275
|
/** Public, neutral payment-rail names. Provider/processor names are an internal
|
|
221
276
|
* backend routing detail and are deliberately NOT exposed here. */
|
|
222
277
|
type Rail = "platform" | "game" | "steam";
|
|
223
|
-
/**
|
|
278
|
+
/**
|
|
279
|
+
* Verification method returned by initiate-send / initiate-transfer.
|
|
280
|
+
*
|
|
281
|
+
* These are NOT two equivalent options. `"in_app"` is the passkey (WebAuthn) approve —
|
|
282
|
+
* the gold standard and the path to build for. `"sms"` means the sender has **no passkey
|
|
283
|
+
* enrolled** and the backend fell back to a PIN; treat it as a prompt to enroll, not as a
|
|
284
|
+
* destination. The SMS-PIN path is being phased out.
|
|
285
|
+
*/
|
|
224
286
|
type VerificationMethod = "in_app" | "sms";
|
|
225
287
|
interface InvoConfig {
|
|
226
288
|
/** API base URL. Prod: "https://invo.network". Sandbox: "https://sandbox.invo.network/sandbox". */
|
|
@@ -254,13 +316,6 @@ interface ClientConfig extends InvoConfig {
|
|
|
254
316
|
* is retried once with the new token, and the client keeps using it thereafter.
|
|
255
317
|
*/
|
|
256
318
|
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;
|
|
264
319
|
}
|
|
265
320
|
interface PlayerToken {
|
|
266
321
|
token: string;
|
|
@@ -292,7 +347,11 @@ interface InitiateTransferInput {
|
|
|
292
347
|
interface InitiateResult {
|
|
293
348
|
transactionId: string;
|
|
294
349
|
/**
|
|
295
|
-
* "in_app" → proceed to the
|
|
350
|
+
* `"in_app"` → the sender has a passkey; proceed to the approve flow (the recommended
|
|
351
|
+
* and only non-deprecated path). `"sms"` → the sender has **no passkey**, so a PIN was
|
|
352
|
+
* sent as a last-resort fallback — the best response is to offer `enrollPasskey()` and
|
|
353
|
+
* then `approveSend`/`approveTransfer`, falling back to the PIN pad only if they can't
|
|
354
|
+
* or won't enroll. The SMS-PIN completion is being phased out.
|
|
296
355
|
* `undefined` when the backend returned the minor/guardian path (HTTP 202) and
|
|
297
356
|
* no verification method applies yet — check `guardianApproval` and do NOT route
|
|
298
357
|
* the user into the SMS-PIN UI in that case (§4.3 / §8).
|
|
@@ -411,19 +470,9 @@ interface ItemOrderQuery {
|
|
|
411
470
|
/** How a Platform Commerce purchase is funded. Server-resolved under lock — the client
|
|
412
471
|
* can request it, but the backend verifies the actual balance before value moves. */
|
|
413
472
|
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
473
|
interface PlatformPurchaseInput {
|
|
426
|
-
/** Idempotency key, unique per tenant. Required.
|
|
474
|
+
/** Idempotency key, unique per tenant. Required. Balance leg: a duplicate returns 409.
|
|
475
|
+
* Card leg: a duplicate REPLAYS the same checkout session (`idempotentReplay: true`). */
|
|
427
476
|
clientRequestId: string;
|
|
428
477
|
/** "balance" (spend held INVO currency) or "card" (pay by card — new money). Required;
|
|
429
478
|
* server-validated. */
|
|
@@ -437,23 +486,29 @@ interface PlatformPurchaseInput {
|
|
|
437
486
|
/** Price PER UNIT. > 0. On the CARD leg this is USD; on the BALANCE leg it is the
|
|
438
487
|
* tenant's network-currency amount. */
|
|
439
488
|
unitPrice: string | number;
|
|
440
|
-
/** Must equal unitPrice × itemQuantity (±0.01). USD on the card leg
|
|
441
|
-
* on the balance leg. */
|
|
489
|
+
/** Must equal unitPrice × itemQuantity (±0.01). USD on the card leg (min $0.50,
|
|
490
|
+
* max $999.99); network currency on the balance leg. */
|
|
442
491
|
totalPrice: string | number;
|
|
443
492
|
playerPhone?: string;
|
|
444
493
|
itemDescription?: string;
|
|
445
494
|
itemCategory?: string;
|
|
446
|
-
/**
|
|
447
|
-
|
|
495
|
+
/** Card leg only: where INVO's hosted checkout sends the buyer after payment. */
|
|
496
|
+
successUrl?: string;
|
|
497
|
+
/** Card leg only: where the hosted checkout sends the buyer on cancel. */
|
|
498
|
+
cancelUrl?: string;
|
|
499
|
+
/** Card leg only: your correlation object, echoed back on the webhook. */
|
|
500
|
+
metadata?: Record<string, unknown>;
|
|
448
501
|
}
|
|
449
|
-
/** "success" → BALANCE leg settled synchronously. "requires_payment" → CARD leg:
|
|
450
|
-
* `
|
|
502
|
+
/** "success" → BALANCE leg settled synchronously. "requires_payment" → CARD leg: send
|
|
503
|
+
* the buyer to `checkoutUrl` (INVO's hosted checkout page). */
|
|
451
504
|
type PlatformPurchaseStatus = "success" | "requires_payment";
|
|
452
505
|
interface PlatformPurchaseResult {
|
|
453
|
-
/** "success" (balance settled) | "requires_payment" (card —
|
|
506
|
+
/** "success" (balance settled) | "requires_payment" (card — send the buyer to `checkoutUrl`). */
|
|
454
507
|
status: string;
|
|
455
508
|
fundingSource: string;
|
|
456
|
-
|
|
509
|
+
/** Balance leg only — the card leg creates the order lazily on the verified payment,
|
|
510
|
+
* so `requires_payment` responses carry a `sessionId` instead. */
|
|
511
|
+
orderId?: string | number;
|
|
457
512
|
transactionId?: string;
|
|
458
513
|
/** Canonical balance AFTER the debit (balance leg). */
|
|
459
514
|
newBalance?: string | number | null;
|
|
@@ -461,9 +516,17 @@ interface PlatformPurchaseResult {
|
|
|
461
516
|
currencyName?: string;
|
|
462
517
|
/** { total_paid, developer_revenue, platform_fee } when present. */
|
|
463
518
|
financialBreakdown?: Record<string, unknown>;
|
|
464
|
-
/**
|
|
465
|
-
|
|
519
|
+
/** The hosted-checkout session id. Present on the card leg. */
|
|
520
|
+
sessionId?: string;
|
|
521
|
+
/** Send the buyer here (redirect, or `InvoClient.platformCommerce.mountCheckout`).
|
|
522
|
+
* INVO's hosted page owns the card form, wallets, billing address, and 3-D Secure. */
|
|
523
|
+
checkoutUrl?: string;
|
|
524
|
+
/** Unix seconds when the checkout session expires. Present on the card leg. */
|
|
525
|
+
expiresAt?: number;
|
|
466
526
|
amountUsd?: string | number | null;
|
|
527
|
+
/** True when this response REPLAYED an existing session for the same
|
|
528
|
+
* `clientRequestId` (safe retry — same URL, never a second charge). */
|
|
529
|
+
idempotentReplay?: boolean;
|
|
467
530
|
raw: Record<string, unknown>;
|
|
468
531
|
}
|
|
469
532
|
interface PlatformOrderStatusResult {
|
|
@@ -505,92 +568,21 @@ interface PlatformRefundResult {
|
|
|
505
568
|
feeRetained?: boolean;
|
|
506
569
|
raw: Record<string, unknown>;
|
|
507
570
|
}
|
|
508
|
-
|
|
509
|
-
|
|
510
|
-
|
|
511
|
-
|
|
512
|
-
|
|
513
|
-
|
|
514
|
-
|
|
515
|
-
|
|
516
|
-
|
|
517
|
-
|
|
518
|
-
|
|
519
|
-
|
|
520
|
-
|
|
521
|
-
|
|
522
|
-
|
|
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. */
|
|
571
|
+
interface MountCheckoutOptions {
|
|
572
|
+
/** Called when INVO's page posts `INVO_CHECKOUT_COMPLETE` (payment finished in-frame).
|
|
573
|
+
* Show "processing" and reconcile server-side — the sale is REAL only on the
|
|
574
|
+
* `platform_commerce.purchased` webhook, never on this client signal. */
|
|
575
|
+
onComplete?: (data: Record<string, unknown>) => void;
|
|
576
|
+
/** Extra CSS class for the iframe. The SDK sets width:100%/border:0 by default. */
|
|
577
|
+
className?: string;
|
|
578
|
+
/** iframe `title` for accessibility. Default "INVO checkout". */
|
|
579
|
+
title?: string;
|
|
580
|
+
}
|
|
581
|
+
/** Handle returned by `mountCheckout`. */
|
|
582
|
+
interface CheckoutMountHandle {
|
|
583
|
+
/** The mounted iframe element. */
|
|
584
|
+
iframe: HTMLIFrameElement;
|
|
585
|
+
/** Remove the iframe and stop listening for checkout messages. */
|
|
594
586
|
destroy(): void;
|
|
595
587
|
}
|
|
596
588
|
interface PlayerBalanceQuery {
|
|
@@ -823,6 +815,11 @@ interface LinkDeviceResult {
|
|
|
823
815
|
status: string;
|
|
824
816
|
raw: Record<string, unknown>;
|
|
825
817
|
}
|
|
818
|
+
/**
|
|
819
|
+
* Result of `verifySmsTransfer` / `verifySmsSend` — the last-resort path for senders with
|
|
820
|
+
* no passkey. The SMS-PIN completion is being phased out; passkey approve
|
|
821
|
+
* (`InvoClient.approveSend` / `approveTransfer`) is the gold standard.
|
|
822
|
+
*/
|
|
826
823
|
interface SmsVerifyResult {
|
|
827
824
|
/** "success" on a completed verification. */
|
|
828
825
|
status: string;
|
|
@@ -946,4 +943,4 @@ interface PhoneShareStatusResult {
|
|
|
946
943
|
raw: Record<string, unknown>;
|
|
947
944
|
}
|
|
948
945
|
|
|
949
|
-
export { type
|
|
946
|
+
export { type LinkedIdentitiesResult as $, type ApproveResult as A, type BalanceResult as B, type CheckoutMountHandle as C, type DestinationsQuery as D, type EnrollmentBeginResult as E, type PurchaseInput as F, type PurchaseResult as G, Http as H, InvoError as I, type ConfirmPaymentResult as J, type PurchaseItemInput as K, type LinkDeviceResult as L, type MountCheckoutOptions as M, type PurchaseItemResult as N, type OrderDetailsResult as O, type PendingCollectResult as P, type ItemHistoryQuery as Q, type RecoveryBeginResult as R, type ServerConfig as S, type ItemHistoryResult as T, type ItemOrderQuery as U, type VerificationMethod as V, type PlayerBalanceQuery as W, type PlayerBalanceResult as X, type InboundPendingQuery as Y, type InboundPendingResult as Z, type LinkedIdentitiesQuery as _, type ClientConfig as a, type SmsVerifyResult as a0, type ClaimTransferInput as a1, type ClaimResult as a2, type ClaimCurrencyInput as a3, type TransactionStatusResult as a4, type GuardianApprovalStatusResult as a5, type ServerDestinationsQuery as a6, type PhoneShareContact as a7, type PhoneShareInitiateResult as a8, type PhoneShareApproveInput as a9, type PhoneShareApproveResult as aa, type PhoneShareStatusResult as ab, type CurrencyBalance as ac, type FundingSource as ad, type InboundPendingItem as ae, type LinkedIdentityEmail as af, type PlatformPurchaseStatus as ag, type CallOptions as b, type ConfirmReceiptResult as c, type DestinationsResult as d, type EnrollmentVerifyResult as e, type RecoveryCompleteResult as f, type BalanceRow as g, type DestinationGame as h, type InvoErrorInfo as i, type InvoHooks as j, type InvoRequestInfo as k, type InvoResponseInfo as l, type PendingCollectItem as m, type Rail as n, type AuthHeader as o, type PlatformPurchaseInput as p, type PlatformPurchaseResult as q, type PlatformOrderStatusResult as r, type PlatformRefundInput as s, type PlatformRefundResult as t, type PlayerToken as u, type InitiateSendInput as v, type InitiateResult as w, type InitiateTransferInput as x, type CreateCheckoutInput as y, type CreateCheckoutResult as z };
|