@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.
- package/CHANGELOG.md +31 -0
- package/README.md +108 -6
- package/dist/{chunk-SSTZKXPC.js → chunk-ZKYUSYK5.js} +30 -3
- package/dist/index.cjs +207 -1
- package/dist/index.d.cts +44 -3
- package/dist/index.d.ts +44 -3
- package/dist/index.js +181 -3
- package/dist/server.cjs +219 -2
- package/dist/server.d.cts +103 -3
- package/dist/server.d.ts +103 -3
- package/dist/server.js +193 -4
- package/dist/{types-7Hl0Z1Ta.d.cts → types-g1xz5GDk.d.cts} +264 -2
- package/dist/{types-7Hl0Z1Ta.d.ts → types-g1xz5GDk.d.ts} +264 -2
- package/package.json +1 -1
|
@@ -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
|
|
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
|
|
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