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