@invonetwork/web-sdk 3.6.0 → 3.8.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 +119 -0
- package/README.md +711 -62
- package/dist/{chunk-MBKE6ULW.js → chunk-HYGBTUEJ.js} +193 -6
- package/dist/index.cjs +191 -4
- package/dist/index.d.cts +2 -2
- package/dist/index.d.ts +2 -2
- package/dist/index.js +2 -2
- package/dist/server.cjs +1472 -5
- package/dist/server.d.cts +606 -3
- package/dist/server.d.ts +606 -3
- package/dist/server.js +1278 -4
- package/dist/{types-ZNoG09S5.d.cts → types-DqRuqbqI.d.cts} +857 -11
- package/dist/{types-ZNoG09S5.d.ts → types-DqRuqbqI.d.ts} +857 -11
- package/package.json +1 -1
|
@@ -1,11 +1,3 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* Typed error for every INVO backend failure.
|
|
3
|
-
*
|
|
4
|
-
* The backend error envelope is usually `{ "error": <message>, "code": <STABLE_CODE> }`,
|
|
5
|
-
* but a few txn-state/claim errors carry only `error` (no `code`) and some use
|
|
6
|
-
* `{ "status": "error", "message": ... }`. So `code` may be undefined — branch on
|
|
7
|
-
* `code` when present, else fall back to `message`. See the handoff doc §8.
|
|
8
|
-
*/
|
|
9
1
|
declare class InvoError extends Error {
|
|
10
2
|
/**
|
|
11
3
|
* Stable machine code, provider-neutral.
|
|
@@ -313,6 +305,137 @@ declare class InvoError extends Error {
|
|
|
313
305
|
* success, not a failure to retry-loop.
|
|
314
306
|
*/
|
|
315
307
|
get isAlreadyRefunded(): boolean;
|
|
308
|
+
/**
|
|
309
|
+
* True when an approve / confirm-receipt was refused because the transaction is no
|
|
310
|
+
* longer awaiting that step (`TRANSACTION_NOT_PENDING`, 400). `approveWithDeviceCode`
|
|
311
|
+
* maps this into a non-throwing `status: "not_pending"` result; you meet it as a thrown
|
|
312
|
+
* error only from a raw call. Usually "already done" (a repeat call with a device_code
|
|
313
|
+
* that was consumed the first time) — read `currentTransactionStatus`, do not retry-loop.
|
|
314
|
+
*
|
|
315
|
+
* The message fallback is for OLDER BACKEND RELEASES. The stable
|
|
316
|
+
* `TRANSACTION_NOT_PENDING` code was added on 2026-09-04; before that the same four
|
|
317
|
+
* endpoints answered `{"status":"error","message":"Transaction not pending PIN
|
|
318
|
+
* verification (current status: …)"}` — or, on the two receipt flows, "…cannot be
|
|
319
|
+
* confirmed (current status: …)" — with **no machine code at all**. An integrator
|
|
320
|
+
* running against an older deployment must still be able to tell "already done" from a
|
|
321
|
+
* real refusal without string-matching in their own code, so the string-matching lives
|
|
322
|
+
* here, once.
|
|
323
|
+
*
|
|
324
|
+
* That fallback is deliberately narrow, because it is guessing. It requires all three
|
|
325
|
+
* of: HTTP 400, one of those two phrases, AND a readable status clause. "cannot be
|
|
326
|
+
* confirmed" is an ordinary English phrase that some future refusal could reasonably
|
|
327
|
+
* use, so a phrase match ALONE must never be able to tell a caller that money moved —
|
|
328
|
+
* and with the clause required, `currentStatus` is always populated on this path, which
|
|
329
|
+
* is what actually decides `alreadySettled`.
|
|
330
|
+
*/
|
|
331
|
+
get isTransactionNotPending(): boolean;
|
|
332
|
+
/**
|
|
333
|
+
* The `current_status` a `TRANSACTION_NOT_PENDING` refusal reports (e.g. `pending_claim`,
|
|
334
|
+
* `completed`, `expired`).
|
|
335
|
+
*
|
|
336
|
+
* Falls back to the `(current status: …)` clause inside the message, which is where the
|
|
337
|
+
* older releases described above put it — they carried no `current_status` field.
|
|
338
|
+
*/
|
|
339
|
+
get currentTransactionStatus(): string | undefined;
|
|
340
|
+
/**
|
|
341
|
+
* True when the approve endpoint did not accept the `device_code`
|
|
342
|
+
* (`DEVICE_APPROVAL_NOT_APPROVED`, 400): unknown, another player's, bound to a
|
|
343
|
+
* different transaction or FLOW, or not yet approved. Deliberately one answer for all
|
|
344
|
+
* of those (no oracle). Check the `flow` you passed matches the one you began with,
|
|
345
|
+
* and that the poll actually said `approved` before you called approve.
|
|
346
|
+
*/
|
|
347
|
+
get isDeviceApprovalNotApproved(): boolean;
|
|
348
|
+
/**
|
|
349
|
+
* True when `beginDeviceApproval` was refused because an APPROVED grant for this
|
|
350
|
+
* transaction and flow is still inside its window (`DEVICE_APPROVAL_ALREADY_PENDING`,
|
|
351
|
+
* 409). The player already approved — you are missing the approve call, not a new
|
|
352
|
+
* code. If you still hold the `device_code`, call `approveWithDeviceCode`; otherwise
|
|
353
|
+
* `begin` works again after `deviceApprovalExpiresAt`. (A merely PENDING earlier grant
|
|
354
|
+
* does not 409 — `begin` supersedes it with a fresh code.)
|
|
355
|
+
*/
|
|
356
|
+
get isDeviceApprovalAlreadyPending(): boolean;
|
|
357
|
+
/** ISO time the blocking approved grant's window closes (`expires_at` on a `DEVICE_APPROVAL_ALREADY_PENDING` 409). */
|
|
358
|
+
get deviceApprovalExpiresAt(): string | undefined;
|
|
359
|
+
/**
|
|
360
|
+
* True when a settle call failed on INVO's side rather than being refused by a rule
|
|
361
|
+
* (`SEND_APPROVE_FAILED` / `TRANSFER_APPROVE_FAILED` / `CONFIRM_RECEIPT_FAILED`, 400).
|
|
362
|
+
*
|
|
363
|
+
* A fault, never a rule and never retryable. Show a neutral failure and report
|
|
364
|
+
* {@link errorRef} — do not treat it as a decision about the player or the money.
|
|
365
|
+
*/
|
|
366
|
+
get isSettleFault(): boolean;
|
|
367
|
+
/**
|
|
368
|
+
* The `error_ref` a settle fault carries. It names the exact server log line, so quoting
|
|
369
|
+
* it to INVO support gets the cause in one message instead of a description of symptoms.
|
|
370
|
+
*/
|
|
371
|
+
get errorRef(): string | undefined;
|
|
372
|
+
/**
|
|
373
|
+
* True when a create (`subscriptions.create` / `steamInit`) was refused because the
|
|
374
|
+
* player already has a LIVE subscription to this `itemId` (`ACTIVE_SUBSCRIPTION_EXISTS`,
|
|
375
|
+
* 409). Use `existingSubscriptionId`. This is what you hit if you regenerate
|
|
376
|
+
* `clientRequestId` inside a retry loop: replay the same key instead.
|
|
377
|
+
*/
|
|
378
|
+
get isActiveSubscriptionExists(): boolean;
|
|
379
|
+
/**
|
|
380
|
+
* The `subscription_id` a create refusal names: the LIVE subscription on
|
|
381
|
+
* `ACTIVE_SUBSCRIPTION_EXISTS`, the PENDING Steam row on `STEAM_AUTHORIZATION_PENDING`,
|
|
382
|
+
* or the abandoned (now `expired`) row when a Steam-side failure abandoned it after creation.
|
|
383
|
+
*/
|
|
384
|
+
get existingSubscriptionId(): string | undefined;
|
|
385
|
+
/**
|
|
386
|
+
* True when the same `clientRequestId` was replayed for the same player and item but
|
|
387
|
+
* with DIFFERENT material terms (`IDEMPOTENT_REPLAY_MISMATCH`, 409). See
|
|
388
|
+
* `mismatchedFields` (any of `amount_usd`, `interval`, `interval_count`, `wallet_only`,
|
|
389
|
+
* `funding_rail`). To change terms use `changeAmount` / `setPaymentMethod`; to create a
|
|
390
|
+
* new subscription use a new key.
|
|
391
|
+
*/
|
|
392
|
+
get isIdempotentReplayMismatch(): boolean;
|
|
393
|
+
/** The `mismatched_fields` on an `IDEMPOTENT_REPLAY_MISMATCH` 409. */
|
|
394
|
+
get mismatchedFields(): string[];
|
|
395
|
+
/**
|
|
396
|
+
* True when `changeAmount` tried to RAISE the price of a Steam subscription
|
|
397
|
+
* (`STEAM_REAUTHORIZATION_REQUIRED`, 409). The member consented to a ceiling; start a
|
|
398
|
+
* new Steam subscription at the new price and cancel this one. Decreases stage normally.
|
|
399
|
+
* The body carries `current_amount_usd` and `requested_amount_usd`.
|
|
400
|
+
*/
|
|
401
|
+
get isSteamReauthorizationRequired(): boolean;
|
|
402
|
+
/** True when `setPaymentMethod` was called on a Steam subscription (`NOT_A_CARD_SUBSCRIPTION`, 409). A rail is fixed at creation. */
|
|
403
|
+
get isNotACardSubscription(): boolean;
|
|
404
|
+
/**
|
|
405
|
+
* True when a Steam subscription was started with a key for a non-Steam channel
|
|
406
|
+
* (`STEAM_CHANNEL_REQUIRED`, 409). Use the primary game key or the `steam` channel key.
|
|
407
|
+
*/
|
|
408
|
+
get isSteamChannelRequired(): boolean;
|
|
409
|
+
/**
|
|
410
|
+
* True when `subscriptions.refund` targeted a period that was charged through Steam
|
|
411
|
+
* (`STEAM_REFUND_NOT_SUPPORTED`, 409). Refunds of Steam-charged periods are not
|
|
412
|
+
* supported yet; periods of a Steam subscription that the wallet covered entirely
|
|
413
|
+
* remain refundable in coins.
|
|
414
|
+
*/
|
|
415
|
+
get isSteamRefundNotSupported(): boolean;
|
|
416
|
+
/** True when the subscription is `canceled` or `expired` and the call cannot apply (`SUBSCRIPTION_TERMINAL`, 409). Start a new one. */
|
|
417
|
+
get isSubscriptionTerminal(): boolean;
|
|
418
|
+
/**
|
|
419
|
+
* True when `subscriptions.steamFinalize` was called before the member completed the
|
|
420
|
+
* Steam authorisation (409, body `status: "not_authorized"`, with `steam_status`).
|
|
421
|
+
* THE NORMAL WAIT STATE: call finalize again after the overlay or checkout closes.
|
|
422
|
+
* The member has 24 hours; after that the row expires.
|
|
423
|
+
*/
|
|
424
|
+
get isNotAuthorized(): boolean;
|
|
425
|
+
/**
|
|
426
|
+
* True when a sandbox clock call was refused for a missing, wrong or never-issued
|
|
427
|
+
* `X-Sandbox-Clock-Key` (`SANDBOX_CLOCK_UNAUTHORIZED`, 401). Reveal or rotate the key on
|
|
428
|
+
* the game's Game Settings page in the sandbox console.
|
|
429
|
+
*/
|
|
430
|
+
get isSandboxClockUnauthorized(): boolean;
|
|
431
|
+
/**
|
|
432
|
+
* True when INVO has paused this flow for maintenance (503): `flow_paused` on create /
|
|
433
|
+
* amount / payment-method / Steam init / card setup, `FLOW_PAUSED` on refund and the
|
|
434
|
+
* sandbox clock. Retry later WITH THE SAME idempotency key.
|
|
435
|
+
*/
|
|
436
|
+
get isFlowPaused(): boolean;
|
|
437
|
+
/** True when a create was refused because the game is not `live` (`GAME_NOT_LIVE`, 403). Make it live in the console. */
|
|
438
|
+
get isGameNotLive(): boolean;
|
|
316
439
|
/** Seconds to wait before retrying, when the backend throttled the call (429 `retry_after`). */
|
|
317
440
|
get retryAfter(): number | undefined;
|
|
318
441
|
/** `body` as a plain object, or `{}` if it's a string/number/null (non-JSON responses).
|
|
@@ -390,9 +513,11 @@ declare class Http {
|
|
|
390
513
|
post<T = Record<string, unknown>>(path: string, body: Record<string, unknown> | undefined, auth: AuthHeader, opts?: {
|
|
391
514
|
idempotent?: boolean;
|
|
392
515
|
signal?: AbortSignal;
|
|
516
|
+
headers?: Record<string, string>;
|
|
393
517
|
}): Promise<T>;
|
|
394
518
|
get<T = Record<string, unknown>>(path: string, auth: AuthHeader, opts?: {
|
|
395
519
|
signal?: AbortSignal;
|
|
520
|
+
headers?: Record<string, string>;
|
|
396
521
|
}): Promise<T>;
|
|
397
522
|
private authHeaders;
|
|
398
523
|
private request;
|
|
@@ -440,6 +565,14 @@ interface InvoConfig {
|
|
|
440
565
|
interface ServerConfig extends InvoConfig {
|
|
441
566
|
/** The game secret. Server-side ONLY — never ship this to a browser. */
|
|
442
567
|
gameSecret: string;
|
|
568
|
+
/**
|
|
569
|
+
* The per-game **sandbox clock key** (`ivclk_...`) from the sandbox console (Game
|
|
570
|
+
* Settings → "Sandbox clock key"). Sent as `X-Sandbox-Clock-Key` by
|
|
571
|
+
* `invo.sandbox.subscriptions.*` only. Optional; those methods throw `INVALID_INPUT`
|
|
572
|
+
* before the network when it is missing. Has no effect outside sandbox. Server-side
|
|
573
|
+
* only — keep it out of game clients and source control.
|
|
574
|
+
*/
|
|
575
|
+
sandboxClockKey?: string;
|
|
443
576
|
}
|
|
444
577
|
interface ClientConfig extends InvoConfig {
|
|
445
578
|
/** Short-lived, game-scoped player token minted server-side via mintPlayerToken(). */
|
|
@@ -909,9 +1042,22 @@ interface ConfirmReceiptResult {
|
|
|
909
1042
|
interface PendingCollectItem {
|
|
910
1043
|
/** The transaction id — note the backend key is `transfer_id`. */
|
|
911
1044
|
transferId: string;
|
|
912
|
-
/**
|
|
1045
|
+
/**
|
|
1046
|
+
* "identity_gate" — you initiated this, call approve*.
|
|
1047
|
+
* "receiving_confirm" — it is addressed to you, call confirmReceipt*.
|
|
1048
|
+
*
|
|
1049
|
+
* `receiving_confirm` covers BOTH rails, a peer send and a cross-game
|
|
1050
|
+
* transfer. Do not branch on `kind` alone to pick the endpoint: an
|
|
1051
|
+
* integrator who read this as "peer sends only" shipped a collect screen
|
|
1052
|
+
* that dropped every transfer and showed no button (2026-09-04). `flow` is
|
|
1053
|
+
* what selects the call.
|
|
1054
|
+
*/
|
|
913
1055
|
kind: string;
|
|
914
|
-
/**
|
|
1056
|
+
/**
|
|
1057
|
+
* "send" → confirmReceiptSend / the send confirm-receipt endpoint.
|
|
1058
|
+
* "transfer" → confirmReceiptTransfer / the transfer one.
|
|
1059
|
+
* THIS is the field that decides which endpoint settles the item.
|
|
1060
|
+
*/
|
|
915
1061
|
flow: string;
|
|
916
1062
|
amount: string | null;
|
|
917
1063
|
/** Currency name (not id). */
|
|
@@ -1184,5 +1330,705 @@ interface PhoneShareStatusResult {
|
|
|
1184
1330
|
approved: boolean;
|
|
1185
1331
|
raw: Record<string, unknown>;
|
|
1186
1332
|
}
|
|
1333
|
+
/** The four device-approval flows. Sender side: `transfer` | `send`. Recipient side:
|
|
1334
|
+
* `transfer_receipt` | `send_receipt`. The flow picks which endpoint settles the money. */
|
|
1335
|
+
type DeviceApprovalFlow = "transfer" | "send" | "send_receipt" | "transfer_receipt";
|
|
1336
|
+
/**
|
|
1337
|
+
* How the approval page reaches the player. `qr` (default): the game renders
|
|
1338
|
+
* `verificationUriComplete` as a QR. `app_browser`: the Unity / Unreal plugin opens the
|
|
1339
|
+
* system browser (INVO derives the return scheme). `popup` is BROWSER-only — the page's
|
|
1340
|
+
* own https `Origin` becomes the popup's opener, so a server-to-server `begin` with it is
|
|
1341
|
+
* refused (400); the SDK rejects it before the network. Use `InvoClient.approveHosted`.
|
|
1342
|
+
*/
|
|
1343
|
+
type DeviceApprovalChannel = "qr" | "app_browser" | "popup";
|
|
1344
|
+
interface BeginDeviceApprovalInput {
|
|
1345
|
+
/** The PLAYER'S session token (from `mintPlayerToken`) — never the game secret. */
|
|
1346
|
+
playerToken: string;
|
|
1347
|
+
/** The transaction your server initiated (`initiateSend` / `initiateTransfer`). */
|
|
1348
|
+
transactionId: string;
|
|
1349
|
+
flow: DeviceApprovalFlow;
|
|
1350
|
+
/** Default `"qr"`. */
|
|
1351
|
+
channel?: DeviceApprovalChannel;
|
|
1352
|
+
}
|
|
1353
|
+
/** The RFC 8628 §3.2 grant returned by `beginDeviceApproval`. */
|
|
1354
|
+
interface DeviceApprovalGrant {
|
|
1355
|
+
/**
|
|
1356
|
+
* The bearer credential for this grant. Keep it on your server: it goes into `poll`,
|
|
1357
|
+
* `confirmEnrollment` and — the step that moves the money — `approveWithDeviceCode`.
|
|
1358
|
+
* Never render it, never log it. `userCode` is the thing meant to be seen.
|
|
1359
|
+
*/
|
|
1360
|
+
deviceCode: string;
|
|
1361
|
+
/** Short code the player could type on a TV with no camera; the QR already carries it. */
|
|
1362
|
+
userCode: string;
|
|
1363
|
+
verificationUri: string;
|
|
1364
|
+
/** Render THIS as the QR. */
|
|
1365
|
+
verificationUriComplete: string;
|
|
1366
|
+
/** Seconds until the grant expires. A countdown hint only — the poll's `expired_token`
|
|
1367
|
+
* is the truth; do not abandon a grant on your own clock. */
|
|
1368
|
+
expiresIn: number;
|
|
1369
|
+
/** Minimum seconds between polls. Honour it; `slow_down` means you didn't. */
|
|
1370
|
+
interval: number;
|
|
1371
|
+
channel: string;
|
|
1372
|
+
raw: Record<string, unknown>;
|
|
1373
|
+
}
|
|
1374
|
+
interface PollDeviceApprovalInput {
|
|
1375
|
+
playerToken: string;
|
|
1376
|
+
deviceCode: string;
|
|
1377
|
+
}
|
|
1378
|
+
/**
|
|
1379
|
+
* RFC 8628 §3.5 outcomes of one poll. `approved` is the cue to call
|
|
1380
|
+
* `approveWithDeviceCode` — polling to `approved` and stopping moves nothing.
|
|
1381
|
+
* `invalid_grant` (unknown code, or not this player's) is thrown as `InvoError`
|
|
1382
|
+
* (`err.code === "invalid_grant"`) rather than returned — it is a bug or a lost grant,
|
|
1383
|
+
* not an outcome to wait on.
|
|
1384
|
+
*/
|
|
1385
|
+
type DeviceApprovalPollStatus = "approved" | "authorization_pending" | "slow_down" | "expired_token" | "access_denied";
|
|
1386
|
+
/** The poll's `enrollment` object — present only while a first-time phone waits on the
|
|
1387
|
+
* game screen to confirm the match code. */
|
|
1388
|
+
interface DeviceApprovalEnrollment {
|
|
1389
|
+
/** `awaiting_screen` → show the prompt; `confirmed` / `denied` → take it down. */
|
|
1390
|
+
state: string;
|
|
1391
|
+
/** Fixed-list label of the scanning device (iPhone, Android phone, …) — a hint, not an identity. */
|
|
1392
|
+
deviceLabel: string;
|
|
1393
|
+
/** The code the phone is showing. Draw it large: the player confirms a MATCH. */
|
|
1394
|
+
matchCode: string;
|
|
1395
|
+
/** true when the phone declared it is REPLACING a lost INVO passkey — word the prompt accordingly. */
|
|
1396
|
+
recovery: boolean;
|
|
1397
|
+
requestedAt: string | null;
|
|
1398
|
+
raw: Record<string, unknown>;
|
|
1399
|
+
}
|
|
1400
|
+
interface DeviceApprovalPollResult {
|
|
1401
|
+
status: DeviceApprovalPollStatus;
|
|
1402
|
+
/** Server-stated minimum poll spacing (seconds), when the body carries one. On
|
|
1403
|
+
* `slow_down` add 5 s to whatever you were using (RFC 8628 §3.5). */
|
|
1404
|
+
interval?: number;
|
|
1405
|
+
/** Present on `authorization_pending` while a phone waits for the on-screen match-code
|
|
1406
|
+
* confirmation. Answer it with `confirmDeviceEnrollment`. */
|
|
1407
|
+
enrollment?: DeviceApprovalEnrollment;
|
|
1408
|
+
/** On `approved`: the transaction and flow the grant is bound to. */
|
|
1409
|
+
transactionId?: string;
|
|
1410
|
+
flow?: string;
|
|
1411
|
+
approvedAt?: string | null;
|
|
1412
|
+
raw: Record<string, unknown>;
|
|
1413
|
+
}
|
|
1414
|
+
type DeviceEnrollmentDecision = "approve" | "deny";
|
|
1415
|
+
interface ConfirmDeviceEnrollmentInput {
|
|
1416
|
+
playerToken: string;
|
|
1417
|
+
deviceCode: string;
|
|
1418
|
+
/** `approve` = "yes, my phone shows this code"; `deny` ends the whole grant
|
|
1419
|
+
* (the next poll answers `access_denied`). */
|
|
1420
|
+
decision: DeviceEnrollmentDecision;
|
|
1421
|
+
}
|
|
1422
|
+
interface ConfirmDeviceEnrollmentResult {
|
|
1423
|
+
/** `confirmed` | `denied`. */
|
|
1424
|
+
status: string;
|
|
1425
|
+
raw: Record<string, unknown>;
|
|
1426
|
+
}
|
|
1427
|
+
interface ApproveWithDeviceCodeInput {
|
|
1428
|
+
playerToken: string;
|
|
1429
|
+
transactionId: string;
|
|
1430
|
+
/** Must be the flow the grant was begun with — a grant approved for one flow settles
|
|
1431
|
+
* nothing else (`DEVICE_APPROVAL_NOT_APPROVED`). */
|
|
1432
|
+
flow: DeviceApprovalFlow;
|
|
1433
|
+
deviceCode: string;
|
|
1434
|
+
}
|
|
1435
|
+
/**
|
|
1436
|
+
* Result of `approveWithDeviceCode` — the call that actually moves the money.
|
|
1437
|
+
*
|
|
1438
|
+
* - `transfer` / `send` success: `status: "approved"`, `next: "pending_claim"`
|
|
1439
|
+
* (+ `claimCode` on a transfer, for the sender to claim at the destination).
|
|
1440
|
+
* - `send_receipt` / `transfer_receipt` success: `status: "completed"` + `amountReceived`.
|
|
1441
|
+
* - A 202 hold (guardian / risk / recipient-identity): `status` is the hold's status and
|
|
1442
|
+
* `holdReason` names it; the money is held, not refused.
|
|
1443
|
+
* - `status: "not_pending"`: the backend answered `TRANSACTION_NOT_PENDING` — the
|
|
1444
|
+
* transaction is no longer awaiting this step. NOT a failure: a repeat call after a
|
|
1445
|
+
* crash or timeout lands here because the first one already settled it. Read
|
|
1446
|
+
* `currentStatus` (or `getTransferStatus` / `getSendStatus`) for where it is now.
|
|
1447
|
+
*/
|
|
1448
|
+
interface DeviceApprovalSettleResult {
|
|
1449
|
+
status: string;
|
|
1450
|
+
transactionId: string;
|
|
1451
|
+
flow: DeviceApprovalFlow;
|
|
1452
|
+
/**
|
|
1453
|
+
* true ONLY when the backend answered `TRANSACTION_NOT_PENDING` and `currentStatus`
|
|
1454
|
+
* is a state past this step for this flow: the approval already happened, usually on
|
|
1455
|
+
* an earlier attempt whose response you lost. Safe to treat as success.
|
|
1456
|
+
*
|
|
1457
|
+
* false covers THREE different situations, and only one of them means "start again":
|
|
1458
|
+
* 1. success (nothing was "already" done);
|
|
1459
|
+
* 2. a dead state (expired_claim, expired_pin_verification, failed_*, rejected_*,
|
|
1460
|
+
* admin_cancelled) — the value is back with the sender and a fresh transaction
|
|
1461
|
+
* is the right move;
|
|
1462
|
+
* 3. NOT THERE YET, or a status this version does not recognise. On a receipt flow
|
|
1463
|
+
* `pending_pin_verification` / `pending_verification` mean the SENDER has not
|
|
1464
|
+
* approved (their approval may be sitting at a guardian prompt), and the
|
|
1465
|
+
* classification deliberately fails closed on anything unknown.
|
|
1466
|
+
*
|
|
1467
|
+
* So never start a replacement transaction on false alone. Read `currentStatus`, or
|
|
1468
|
+
* fetch the transaction, before telling a player anything.
|
|
1469
|
+
*/
|
|
1470
|
+
alreadySettled: boolean;
|
|
1471
|
+
/** The transaction's current status when the backend said it is not pending. */
|
|
1472
|
+
currentStatus?: string;
|
|
1473
|
+
/** `pending_claim` on a transfer/send success. */
|
|
1474
|
+
next?: string;
|
|
1475
|
+
/** Transfer approve only: the sender's claim code for the destination game. */
|
|
1476
|
+
claimCode?: string;
|
|
1477
|
+
claimCodeExpiresAt?: string;
|
|
1478
|
+
/** Receipt flows: the net amount credited (decimal string). */
|
|
1479
|
+
amountReceived?: string;
|
|
1480
|
+
/** Present on a 202 hold: `GUARDIAN_APPROVAL_PENDING`, `RISK_HOLD`, `RECIPIENT_IDENTITY_PENDING`, … */
|
|
1481
|
+
holdReason?: string;
|
|
1482
|
+
risk?: Record<string, unknown>;
|
|
1483
|
+
guardianApproval?: unknown;
|
|
1484
|
+
pollEndpoint?: string;
|
|
1485
|
+
raw: Record<string, unknown>;
|
|
1486
|
+
}
|
|
1487
|
+
/** Answer the on-screen match-code prompt (forwarded to `confirmDeviceEnrollment`). */
|
|
1488
|
+
type DeviceEnrollmentRespond = (decision: DeviceEnrollmentDecision) => Promise<void>;
|
|
1489
|
+
interface CompleteDeviceApprovalInput {
|
|
1490
|
+
playerToken: string;
|
|
1491
|
+
transactionId: string;
|
|
1492
|
+
flow: DeviceApprovalFlow;
|
|
1493
|
+
/** From `beginDeviceApproval` — you already showed its QR. */
|
|
1494
|
+
deviceCode: string;
|
|
1495
|
+
/** Initial poll spacing in seconds (the grant's `interval`). Default 5. */
|
|
1496
|
+
interval?: number;
|
|
1497
|
+
/**
|
|
1498
|
+
* Called each time the poll's `enrollment` object changes (`null` when it clears).
|
|
1499
|
+
* Show "Set up INVO on <deviceLabel>? Code <matchCode>" while `state` is
|
|
1500
|
+
* `awaiting_screen` and call `respond("approve" | "deny")` with the player's answer.
|
|
1501
|
+
*/
|
|
1502
|
+
onEnrollment?: (enrollment: DeviceApprovalEnrollment | null, respond: DeviceEnrollmentRespond) => void;
|
|
1503
|
+
/** Abort → resolves `{ status: "aborted" }` after the in-flight call returns. */
|
|
1504
|
+
signal?: AbortSignal;
|
|
1505
|
+
}
|
|
1506
|
+
interface CompleteDeviceApprovalResult {
|
|
1507
|
+
/**
|
|
1508
|
+
* `approved`: the poll said approved AND `approveWithDeviceCode` was called — see
|
|
1509
|
+
* `settlement` (which may itself be a hold or `not_pending`). `denied`: the player
|
|
1510
|
+
* declined on the page or the screen prompt. `expired`: the grant lapsed — begin again.
|
|
1511
|
+
* `aborted`: your `signal` fired.
|
|
1512
|
+
*/
|
|
1513
|
+
status: "approved" | "denied" | "expired" | "aborted";
|
|
1514
|
+
settlement?: DeviceApprovalSettleResult;
|
|
1515
|
+
/** The last poll seen, for diagnostics. */
|
|
1516
|
+
lastPoll?: DeviceApprovalPollResult;
|
|
1517
|
+
}
|
|
1518
|
+
/** Which rail funds the wallet shortfall. Fixed at creation. */
|
|
1519
|
+
type SubscriptionFundingRail = "card" | "steam";
|
|
1520
|
+
/** `month` (default) or `year`. */
|
|
1521
|
+
type SubscriptionInterval = "month" | "year";
|
|
1522
|
+
/**
|
|
1523
|
+
* Subscription lifecycle. "Live" (`trialing`, `active`, `past_due`,
|
|
1524
|
+
* `awaiting_authentication`) occupies the one-live-per-item slot and is touched by the
|
|
1525
|
+
* renewal engine. `pending_steam_authorization` is Steam-only and not yet billable.
|
|
1526
|
+
* `canceled` and `expired` are terminal.
|
|
1527
|
+
*/
|
|
1528
|
+
type SubscriptionStatus = "trialing" | "active" | "past_due" | "awaiting_authentication" | "pending_steam_authorization" | "canceled" | "expired";
|
|
1529
|
+
/** Evidence the member agreed to the recurring charge. Stored verbatim, returned on every read. */
|
|
1530
|
+
interface SubscriptionConsentInput {
|
|
1531
|
+
/** ISO 8601. Not more than 5 minutes in the future. */
|
|
1532
|
+
consentAt?: string;
|
|
1533
|
+
/** The MEMBER's IP as your server saw it (INVO sees your server's). Max 45 chars. */
|
|
1534
|
+
consentIp?: string;
|
|
1535
|
+
/** Truncated to 500. */
|
|
1536
|
+
consentUserAgent?: string;
|
|
1537
|
+
/** The price you showed the member; should equal `amountUsd`. Decimal string. */
|
|
1538
|
+
disclosedAmountUsd?: string;
|
|
1539
|
+
/** The interval you showed the member. */
|
|
1540
|
+
disclosedInterval?: SubscriptionInterval;
|
|
1541
|
+
/** Your terms version, max 50. */
|
|
1542
|
+
termsVersion?: string;
|
|
1543
|
+
}
|
|
1544
|
+
/** The `consent` block as INVO returns it: six fields, all `null` until supplied. */
|
|
1545
|
+
interface SubscriptionConsent {
|
|
1546
|
+
consent_at: string | null;
|
|
1547
|
+
consent_ip: string | null;
|
|
1548
|
+
consent_user_agent: string | null;
|
|
1549
|
+
disclosed_amount_usd: string | null;
|
|
1550
|
+
disclosed_interval: string | null;
|
|
1551
|
+
terms_version: string | null;
|
|
1552
|
+
}
|
|
1553
|
+
/**
|
|
1554
|
+
* Attribution to a second player in your game, and ATTRIBUTION ONLY. INVO records the
|
|
1555
|
+
* share and reports it on every `subscription.renewed`; INVO pays the recipient nothing
|
|
1556
|
+
* (`settledByInvo` is always `false`). Provide EXACTLY ONE of `recipientPlayerEmail` /
|
|
1557
|
+
* `recipientPlayerId`. `percent` is `0` to `100`, two decimals.
|
|
1558
|
+
*/
|
|
1559
|
+
interface SubscriptionRevenueShareInput {
|
|
1560
|
+
recipientPlayerEmail?: string;
|
|
1561
|
+
recipientPlayerId?: number;
|
|
1562
|
+
percent: string | number;
|
|
1563
|
+
}
|
|
1564
|
+
interface SubscriptionRevenueShare {
|
|
1565
|
+
recipientPlayerId: number;
|
|
1566
|
+
percent: string;
|
|
1567
|
+
/** Always `false`: you pay the recipient yourself, out of your own revenue. */
|
|
1568
|
+
settledByInvo: boolean;
|
|
1569
|
+
}
|
|
1570
|
+
/**
|
|
1571
|
+
* The subscription object, as every read and every mutation returns it.
|
|
1572
|
+
*
|
|
1573
|
+
* TWO CLOCKS, not one: `currentPeriodStart`/`currentPeriodEnd` is the billing WINDOW (a
|
|
1574
|
+
* projection that exists from the instant of creation); `paidThrough` is the ENTITLEMENT
|
|
1575
|
+
* boundary (the furthest date the member has actually paid for; `null` until a period
|
|
1576
|
+
* has charged). Grant access from `paidThrough`, never from `currentPeriodEnd`.
|
|
1577
|
+
*/
|
|
1578
|
+
interface Subscription {
|
|
1579
|
+
/** `SUB_<epoch>_<8 chars>`. Not a secret; every call is still scoped by your key. */
|
|
1580
|
+
subscriptionId: string;
|
|
1581
|
+
gameId: string;
|
|
1582
|
+
playerId: number;
|
|
1583
|
+
/** Your idempotency key. */
|
|
1584
|
+
clientRequestId: string;
|
|
1585
|
+
status: SubscriptionStatus;
|
|
1586
|
+
/** The current price, decimal string. */
|
|
1587
|
+
amountUsd: string;
|
|
1588
|
+
/** A staged price change not yet applied, or `null`. */
|
|
1589
|
+
pendingAmountUsd: string | null;
|
|
1590
|
+
interval: SubscriptionInterval;
|
|
1591
|
+
intervalCount: number;
|
|
1592
|
+
itemId: string;
|
|
1593
|
+
itemName: string | null;
|
|
1594
|
+
/** The billing window. NOT entitlement. */
|
|
1595
|
+
currentPeriodStart: string;
|
|
1596
|
+
currentPeriodEnd: string;
|
|
1597
|
+
/** 1-based counter of billing periods; advances on every successful charge. */
|
|
1598
|
+
periodSeq: number;
|
|
1599
|
+
/** When INVO next touches the subscription (also the retry time in dunning and the
|
|
1600
|
+
* challenge deadline in `awaiting_authentication`). `null` on terminal rows and on
|
|
1601
|
+
* `pending_steam_authorization`. */
|
|
1602
|
+
nextChargeAt: string | null;
|
|
1603
|
+
cancelAtPeriodEnd: boolean;
|
|
1604
|
+
trialEnd: string | null;
|
|
1605
|
+
canceledAt: string | null;
|
|
1606
|
+
endedAt: string | null;
|
|
1607
|
+
walletOnly: boolean;
|
|
1608
|
+
/** A card is attached. Never the card's identifiers. */
|
|
1609
|
+
hasPaymentMethod: boolean;
|
|
1610
|
+
fundingRail: SubscriptionFundingRail;
|
|
1611
|
+
/** `pending` | `active` | `canceled`, or `null` on card subscriptions. */
|
|
1612
|
+
steamAgreementStatus: string | null;
|
|
1613
|
+
metadata: Record<string, unknown> | null;
|
|
1614
|
+
consent: SubscriptionConsent;
|
|
1615
|
+
createdAt: string;
|
|
1616
|
+
updatedAt: string;
|
|
1617
|
+
revenueShare: SubscriptionRevenueShare | null;
|
|
1618
|
+
/** THE ENTITLEMENT BOUNDARY. `null` until a period has been charged. */
|
|
1619
|
+
paidThrough: string | null;
|
|
1620
|
+
/** Create/finalize responses only: what one period is worth in coins on this rail. */
|
|
1621
|
+
amountCoinsEstimate?: string;
|
|
1622
|
+
raw: Record<string, unknown>;
|
|
1623
|
+
}
|
|
1624
|
+
/** A saved card as INVO describes it. `id` is the only handle; never a processor id. */
|
|
1625
|
+
interface SavedCard {
|
|
1626
|
+
id: number;
|
|
1627
|
+
lastFour: string;
|
|
1628
|
+
brand: string;
|
|
1629
|
+
expMonth: number;
|
|
1630
|
+
expYear: number;
|
|
1631
|
+
createdAt: string;
|
|
1632
|
+
raw: Record<string, unknown>;
|
|
1633
|
+
}
|
|
1634
|
+
/**
|
|
1635
|
+
* What happened to the money on the first period.
|
|
1636
|
+
* - `paid`: money moved, currency granted; grant access until `paidThrough`.
|
|
1637
|
+
* - `requires_action`: the card issuer wants the cardholder to authenticate. NOTHING
|
|
1638
|
+
* has been charged; send the member to `confirmationUrl` before `expiresAt`.
|
|
1639
|
+
* - `skipped_trial`: deliberately not charged; the subscription is `trialing`.
|
|
1640
|
+
* - `failed`: the charge did not succeed; the subscription is `past_due` and in dunning.
|
|
1641
|
+
* - `pending`: not resolved yet; wait for `subscription.renewed` / `payment_failed`.
|
|
1642
|
+
* - `pending_authorization`: Steam; nothing charged until the member authorises and
|
|
1643
|
+
* you call `steamFinalize`.
|
|
1644
|
+
*/
|
|
1645
|
+
type FirstChargeStatus = "paid" | "requires_action" | "skipped_trial" | "failed" | "pending" | "pending_authorization";
|
|
1646
|
+
/**
|
|
1647
|
+
* Always carries the same keys, on every outcome. Branch on `status`.
|
|
1648
|
+
*
|
|
1649
|
+
* PERIOD NUMBERING. After a successful first charge `subscription.periodSeq` already
|
|
1650
|
+
* points at the NEXT window (it reads `2`), and the `subscription.renewed` webhook for
|
|
1651
|
+
* the period just paid reports `period_seq: 1`. Key entitlement on `paidPeriodSeq` here
|
|
1652
|
+
* (or the webhook's `period_seq`), never on `subscription.periodSeq`: the two roads
|
|
1653
|
+
* count differently by design.
|
|
1654
|
+
*/
|
|
1655
|
+
interface FirstCharge {
|
|
1656
|
+
status: FirstChargeStatus;
|
|
1657
|
+
/** On `paid`: the amount actually charged for period 1. */
|
|
1658
|
+
amountUsd: string | null;
|
|
1659
|
+
/** The period that was just paid (`1` for the first period). `null` unless `status` is `paid`. */
|
|
1660
|
+
paidPeriodSeq: number | null;
|
|
1661
|
+
/** Same value as `subscription.paidThrough`, repeated so one object answers "what happened". */
|
|
1662
|
+
paidThrough: string | null;
|
|
1663
|
+
failureCode: string | null;
|
|
1664
|
+
nextRetryAt: string | null;
|
|
1665
|
+
/** On `requires_action`: a single-use bearer link. Do not log it beside identifiers you publish. */
|
|
1666
|
+
confirmationUrl: string | null;
|
|
1667
|
+
expiresAt: string | null;
|
|
1668
|
+
message: string | null;
|
|
1669
|
+
raw: Record<string, unknown>;
|
|
1670
|
+
}
|
|
1671
|
+
/** Fields shared by `subscriptions.create` and `subscriptions.steamInit`. */
|
|
1672
|
+
interface SubscriptionBaseInput {
|
|
1673
|
+
/**
|
|
1674
|
+
* Idempotency key: unique per subscription and per player within your game, max 255
|
|
1675
|
+
* chars, must not begin with `sub_`. Generate it ONCE per subscription, persist it, and
|
|
1676
|
+
* reuse it on every retry: a repeat returns the same subscription (`idempotentReplay`).
|
|
1677
|
+
*/
|
|
1678
|
+
clientRequestId: string;
|
|
1679
|
+
/** Identifies the member. Lower-cased server-side. */
|
|
1680
|
+
playerEmail: string;
|
|
1681
|
+
/** Used only if the player does not exist yet. Max 255. */
|
|
1682
|
+
playerName: string;
|
|
1683
|
+
/** Optional; E.164 when supplied (this call can create the player identity). */
|
|
1684
|
+
playerPhone?: string;
|
|
1685
|
+
/** Your entitlement handle. One live subscription per (player, item). */
|
|
1686
|
+
itemId: string;
|
|
1687
|
+
/** Echoed on events. Max 255. */
|
|
1688
|
+
itemName?: string;
|
|
1689
|
+
/** `0.01` to `999999.99`, two decimals. Prices above `500.00` are accepted but never charged. */
|
|
1690
|
+
amountUsd: string | number;
|
|
1691
|
+
/** Default `month`. */
|
|
1692
|
+
interval?: SubscriptionInterval;
|
|
1693
|
+
/** Up to 8192 bytes serialised. Echoed on every read and event. `_invo` is reserved. */
|
|
1694
|
+
metadata?: Record<string, unknown>;
|
|
1695
|
+
/** Supply it: INVO is merchant of record on the card rail and a dispute is argued from this. */
|
|
1696
|
+
consent?: SubscriptionConsentInput;
|
|
1697
|
+
/** Attribution only; INVO pays nothing to the recipient. Set once at create. */
|
|
1698
|
+
revenueShare?: SubscriptionRevenueShareInput;
|
|
1699
|
+
}
|
|
1700
|
+
/** Input for `subscriptions.create` (the CARD rail). */
|
|
1701
|
+
interface CreateSubscriptionInput extends SubscriptionBaseInput {
|
|
1702
|
+
/** 1 (default) to 36. `3` with `month` bills quarterly. */
|
|
1703
|
+
intervalCount?: number;
|
|
1704
|
+
/** 1 to 365. INVO adds up to one hour of jitter to the derived end. */
|
|
1705
|
+
trialDays?: number;
|
|
1706
|
+
/** Explicit ISO 8601 trial end (future, within 365 days). Takes precedence over `trialDays`. */
|
|
1707
|
+
trialEnd?: string;
|
|
1708
|
+
/** Default `false`. `true` opts out of the card backstop; cannot be combined with `playerCardId`. */
|
|
1709
|
+
walletOnly?: boolean;
|
|
1710
|
+
/** The `id` of a card from `cards.list`. Omitted: INVO picks the newest unexpired saved card. */
|
|
1711
|
+
playerCardId?: number;
|
|
1712
|
+
}
|
|
1713
|
+
/** Result of `subscriptions.create` (201, or a 200 replay). */
|
|
1714
|
+
interface SubscriptionResult {
|
|
1715
|
+
/** `success` on the card rail. */
|
|
1716
|
+
status: string;
|
|
1717
|
+
/** `true` when this `clientRequestId` was seen before; nothing was charged again. */
|
|
1718
|
+
idempotentReplay: boolean;
|
|
1719
|
+
subscription: Subscription;
|
|
1720
|
+
/** The card backing the subscription (named or auto-picked), or `null` when none. */
|
|
1721
|
+
card: SavedCard | null;
|
|
1722
|
+
firstCharge: FirstCharge;
|
|
1723
|
+
/** Present on a reduced 201 (INVO created the row but could not render the full body): read it with `get`. */
|
|
1724
|
+
warning?: string;
|
|
1725
|
+
raw: Record<string, unknown>;
|
|
1726
|
+
}
|
|
1727
|
+
/** Input for `subscriptions.steamInit`: the `create` input minus card/trial fields, plus Steam. */
|
|
1728
|
+
interface SteamSubscriptionInitInput extends SubscriptionBaseInput {
|
|
1729
|
+
/** The member's 64-bit Steam id (digits). */
|
|
1730
|
+
steamId: string;
|
|
1731
|
+
/** `client` (default; the member authorises in the Steam overlay) or `web` (a hosted checkout URL). */
|
|
1732
|
+
userSession?: SteamUserSession;
|
|
1733
|
+
/** Required for `web`: the MEMBER's IP as your server sees it, never your server's own. */
|
|
1734
|
+
playerIp?: string;
|
|
1735
|
+
/** Must be `1` on Steam (monthly and yearly only). */
|
|
1736
|
+
intervalCount?: 1;
|
|
1737
|
+
}
|
|
1738
|
+
/** Result of `subscriptions.steamInit` (201, or a 200 replay carrying the row's CURRENT status). */
|
|
1739
|
+
interface SteamInitResult {
|
|
1740
|
+
/** `pending_steam_authorization` on first creation; on a replay, the row's current status. */
|
|
1741
|
+
status: string;
|
|
1742
|
+
subscriptionStatus: string;
|
|
1743
|
+
idempotentReplay: boolean;
|
|
1744
|
+
/**
|
|
1745
|
+
* `true` when a PENDING authorisation for the same player and item with the same terms
|
|
1746
|
+
* was handed back instead of a new agreement being created. Finalize that one. (Same
|
|
1747
|
+
* player and item with DIFFERENT terms throws `409 STEAM_AUTHORIZATION_PENDING`,
|
|
1748
|
+
* `err.isSteamAuthorizationPending`, with the pending `subscription_id` on the body.)
|
|
1749
|
+
*/
|
|
1750
|
+
pendingReuse: boolean;
|
|
1751
|
+
subscription: Subscription;
|
|
1752
|
+
subscriptionId: string;
|
|
1753
|
+
orderId: string;
|
|
1754
|
+
/**
|
|
1755
|
+
* The uint64 order id the Steam client callback's `order_id` echoes. **Match the
|
|
1756
|
+
* callback with this**, then call `steamFinalize`. (It is not `steamTransid`.)
|
|
1757
|
+
*/
|
|
1758
|
+
steamOrderId: string;
|
|
1759
|
+
/** Steam's transaction reference for period 1, for your support tooling only. */
|
|
1760
|
+
steamTransid: string;
|
|
1761
|
+
/** Present only for `userSession: "web"`. Open it as a TOP-LEVEL window; it cannot be framed. */
|
|
1762
|
+
steamCheckoutUrl: string | null;
|
|
1763
|
+
amountUsd: string;
|
|
1764
|
+
/** What one period is worth for THIS member (country-derived). Show it; never price x 10. */
|
|
1765
|
+
amountCoins: string;
|
|
1766
|
+
/** What period 1 will charge (the full price). */
|
|
1767
|
+
steamChargeUsd: string;
|
|
1768
|
+
/** The ceiling the member consents to (the price). */
|
|
1769
|
+
recurringAmountUsd: string;
|
|
1770
|
+
firstCharge: FirstCharge;
|
|
1771
|
+
message: string;
|
|
1772
|
+
raw: Record<string, unknown>;
|
|
1773
|
+
}
|
|
1774
|
+
/** Result of `subscriptions.steamFinalize`: the `SubscriptionResult` plus the finalize flags. */
|
|
1775
|
+
interface SteamFinalizeSubscriptionResult extends SubscriptionResult {
|
|
1776
|
+
/** `true` when already finalised (or a concurrent finalize won). Treat as success. */
|
|
1777
|
+
alreadyProcessed: boolean;
|
|
1778
|
+
/** Normally `active`; `pending` if Steam captured the charge but the agreement is not located yet. */
|
|
1779
|
+
steamAgreementStatus: string | null;
|
|
1780
|
+
/** Sandbox only: the authorisation was simulated, not Valve's. Do one real Steam sandbox run before launch. */
|
|
1781
|
+
sandboxAutoApproved: boolean;
|
|
1782
|
+
}
|
|
1783
|
+
interface GetSubscriptionOptions {
|
|
1784
|
+
/** Adds a `player` block. Default `false`. */
|
|
1785
|
+
includePlayer?: boolean;
|
|
1786
|
+
}
|
|
1787
|
+
interface GetSubscriptionResult {
|
|
1788
|
+
subscription: Subscription;
|
|
1789
|
+
player?: Record<string, unknown>;
|
|
1790
|
+
raw: Record<string, unknown>;
|
|
1791
|
+
}
|
|
1792
|
+
interface ListSubscriptionsOptions {
|
|
1793
|
+
/** One or more statuses; `live` expands to the four live statuses and may be mixed in. */
|
|
1794
|
+
status?: SubscriptionStatus | "live" | Array<SubscriptionStatus | "live">;
|
|
1795
|
+
includePlayer?: boolean;
|
|
1796
|
+
/** 1 to 100, default 50. */
|
|
1797
|
+
limit?: number;
|
|
1798
|
+
/** 0 to 100000, default 0. */
|
|
1799
|
+
offset?: number;
|
|
1800
|
+
}
|
|
1801
|
+
interface SubscriptionListResult {
|
|
1802
|
+
playerEmail: string;
|
|
1803
|
+
/** Newest first with a stable tiebreaker. An unknown player is an empty list, not a 404. */
|
|
1804
|
+
subscriptions: Subscription[];
|
|
1805
|
+
pagination: {
|
|
1806
|
+
totalCount: number;
|
|
1807
|
+
limit: number;
|
|
1808
|
+
offset: number;
|
|
1809
|
+
hasMore: boolean;
|
|
1810
|
+
};
|
|
1811
|
+
raw: Record<string, unknown>;
|
|
1812
|
+
}
|
|
1813
|
+
interface CancelSubscriptionOptions {
|
|
1814
|
+
/** Default `true`. `false` ends the subscription now. */
|
|
1815
|
+
atPeriodEnd?: boolean;
|
|
1816
|
+
/** Stored (max 500) and carried on the `subscription.canceled` event. */
|
|
1817
|
+
reason?: string;
|
|
1818
|
+
}
|
|
1819
|
+
interface CancelResult {
|
|
1820
|
+
status: string;
|
|
1821
|
+
/** `true` when the subscription was already `canceled`/`expired` (a 200, not an error). */
|
|
1822
|
+
alreadyCanceled: boolean;
|
|
1823
|
+
/** On an already-terminal row: its status. */
|
|
1824
|
+
finalStatus?: string;
|
|
1825
|
+
cancelAtPeriodEnd: boolean;
|
|
1826
|
+
effectiveAt: string | null;
|
|
1827
|
+
currentPeriodEnd: string | null;
|
|
1828
|
+
/** Revoke access here. */
|
|
1829
|
+
accessUntil: string | null;
|
|
1830
|
+
paidThrough: string | null;
|
|
1831
|
+
/** `true` when an at-period-end cancel was DOWNGRADED to immediate (nothing paid to preserve). */
|
|
1832
|
+
terminatedImmediately: boolean;
|
|
1833
|
+
/** `NO_PAID_PERIOD` on a downgrade. */
|
|
1834
|
+
downgradeReason?: string;
|
|
1835
|
+
message?: string;
|
|
1836
|
+
/** Steam only. */
|
|
1837
|
+
steamAgreementStatus?: string | null;
|
|
1838
|
+
/** Steam only: whether the agreement was ended at Steam in this call (INVO retries on its own if not). */
|
|
1839
|
+
steamAgreementCanceled?: boolean;
|
|
1840
|
+
subscription: Subscription | null;
|
|
1841
|
+
raw: Record<string, unknown>;
|
|
1842
|
+
}
|
|
1843
|
+
interface ChangeAmountResult {
|
|
1844
|
+
status: string;
|
|
1845
|
+
oldAmountUsd: string;
|
|
1846
|
+
newAmountUsd: string;
|
|
1847
|
+
/** The staged price, or `null` when the change was cleared. */
|
|
1848
|
+
pendingAmountUsd: string | null;
|
|
1849
|
+
changeQueued: boolean;
|
|
1850
|
+
/** `null` until something has been paid. */
|
|
1851
|
+
appliesFrom: string | null;
|
|
1852
|
+
appliesFromPeriodSeq: number;
|
|
1853
|
+
paidThrough: string | null;
|
|
1854
|
+
currentPeriodEnd: string | null;
|
|
1855
|
+
/** Always `false`: no proration. */
|
|
1856
|
+
prorated: boolean;
|
|
1857
|
+
subscription: Subscription | null;
|
|
1858
|
+
raw: Record<string, unknown>;
|
|
1859
|
+
}
|
|
1860
|
+
/** Attach a card (optionally converting a wallet-only subscription), or make it wallet-only. */
|
|
1861
|
+
type SetPaymentMethodInput = {
|
|
1862
|
+
playerCardId: number;
|
|
1863
|
+
walletOnly?: false;
|
|
1864
|
+
} | {
|
|
1865
|
+
walletOnly: true;
|
|
1866
|
+
};
|
|
1867
|
+
interface SetPaymentMethodResult {
|
|
1868
|
+
status: string;
|
|
1869
|
+
replaced: boolean;
|
|
1870
|
+
walletOnly: boolean;
|
|
1871
|
+
card: SavedCard | null;
|
|
1872
|
+
subscription: Subscription | null;
|
|
1873
|
+
raw: Record<string, unknown>;
|
|
1874
|
+
}
|
|
1875
|
+
interface RefundSubscriptionInput {
|
|
1876
|
+
/** One per refund, max 255, not `sub_`-prefixed. Reuse it on retries. */
|
|
1877
|
+
clientRequestId: string;
|
|
1878
|
+
/** Defaults to the most recent billed period. */
|
|
1879
|
+
periodSeq?: number;
|
|
1880
|
+
/** Defaults to the full remaining refundable amount. A partial refund is allowed. */
|
|
1881
|
+
amountUsd?: string | number;
|
|
1882
|
+
/** Max 500. Carried on the receipt and the event. */
|
|
1883
|
+
reason?: string;
|
|
1884
|
+
}
|
|
1885
|
+
interface RefundRevenueShareAttribution {
|
|
1886
|
+
recipientPlayerId: number;
|
|
1887
|
+
percent: string;
|
|
1888
|
+
originalAttributedAmountUsd: string;
|
|
1889
|
+
refundedAttributedAmountUsd: string;
|
|
1890
|
+
/** The corrected figure to pay your recipient for that renewal. Nothing moves. */
|
|
1891
|
+
netAttributedAmountUsd: string;
|
|
1892
|
+
settledByInvo: boolean;
|
|
1893
|
+
raw: Record<string, unknown>;
|
|
1894
|
+
}
|
|
1895
|
+
/** The refund receipt. A repeated `clientRequestId` returns the stored receipt with `idempotentReplay: true`. */
|
|
1896
|
+
interface RefundResult {
|
|
1897
|
+
/** `refunded`. */
|
|
1898
|
+
status: string;
|
|
1899
|
+
idempotentReplay: boolean;
|
|
1900
|
+
refundKey: string | null;
|
|
1901
|
+
clientRequestId: string | null;
|
|
1902
|
+
subscriptionId: string;
|
|
1903
|
+
periodSeq: number | null;
|
|
1904
|
+
transactionId: string | null;
|
|
1905
|
+
refundedAmountUsd: string | null;
|
|
1906
|
+
totalRefundedAmountUsd: string | null;
|
|
1907
|
+
remainingRefundableUsd: string | null;
|
|
1908
|
+
isFullRefund: boolean;
|
|
1909
|
+
/** `wallet` | `card` | `mixed`. */
|
|
1910
|
+
fundingShape: string | null;
|
|
1911
|
+
/** Signed; can be negative (coins the card charge minted are taken back). */
|
|
1912
|
+
balanceDeltaCoins: string | null;
|
|
1913
|
+
cardRefundedUsd: string | null;
|
|
1914
|
+
processorRefundReference: string | null;
|
|
1915
|
+
/** `true` when the card refund had already been issued by an earlier attempt and this call recorded it. */
|
|
1916
|
+
processorRefundAdopted: boolean;
|
|
1917
|
+
invoFeeRetained: boolean;
|
|
1918
|
+
partnerRevenueReversedUsd: string | null;
|
|
1919
|
+
/** `full` | `prorata`. */
|
|
1920
|
+
partnerRevenueReversalMode: string | null;
|
|
1921
|
+
reason: string | null;
|
|
1922
|
+
refundedAt: string | null;
|
|
1923
|
+
newBalance: string | null;
|
|
1924
|
+
revenueShareAttribution: RefundRevenueShareAttribution | null;
|
|
1925
|
+
/** On a reduced replay (receipt lost): "This refund was already processed." */
|
|
1926
|
+
note?: string;
|
|
1927
|
+
raw: Record<string, unknown>;
|
|
1928
|
+
}
|
|
1929
|
+
interface CardSetupInput {
|
|
1930
|
+
/** Must already exist in this game (this endpoint does not create players). */
|
|
1931
|
+
playerEmail: string;
|
|
1932
|
+
/** Idempotency anchor, 1-200 chars of `A-Z a-z 0-9 . _ : -`. Resend the same value on a retry. */
|
|
1933
|
+
setupReference: string;
|
|
1934
|
+
/** A card tokenised on the client by the card form. When present INVO saves the card immediately. */
|
|
1935
|
+
paymentMethodId?: string;
|
|
1936
|
+
}
|
|
1937
|
+
/**
|
|
1938
|
+
* - `succeeded`: card saved (`card` set).
|
|
1939
|
+
* - `requires_action`: hand `clientSecret` to the card form, then call `confirmSetup`.
|
|
1940
|
+
* - `requires_confirmation` / `requires_payment_method`: the normal hand-off when you sent
|
|
1941
|
+
* no `paymentMethodId`. Confirm on the client, then call `confirmSetup`.
|
|
1942
|
+
*/
|
|
1943
|
+
type CardSetupStatus = "succeeded" | "requires_action" | "requires_confirmation" | "requires_payment_method";
|
|
1944
|
+
interface CardSetupResult {
|
|
1945
|
+
status: CardSetupStatus | string;
|
|
1946
|
+
setupIntentId: string;
|
|
1947
|
+
/** Present when the client must finish the setup. */
|
|
1948
|
+
clientSecret?: string;
|
|
1949
|
+
publishableKey?: string;
|
|
1950
|
+
card: SavedCard | null;
|
|
1951
|
+
alreadySaved: boolean;
|
|
1952
|
+
message?: string;
|
|
1953
|
+
raw: Record<string, unknown>;
|
|
1954
|
+
}
|
|
1955
|
+
interface CardSetupConfirmInput {
|
|
1956
|
+
/** From `beginSetup`. */
|
|
1957
|
+
setupIntentId: string;
|
|
1958
|
+
}
|
|
1959
|
+
interface CardSetupConfirmResult {
|
|
1960
|
+
/** `success`. */
|
|
1961
|
+
status: string;
|
|
1962
|
+
setupIntentId: string;
|
|
1963
|
+
card: SavedCard | null;
|
|
1964
|
+
alreadySaved: boolean;
|
|
1965
|
+
raw: Record<string, unknown>;
|
|
1966
|
+
}
|
|
1967
|
+
interface PlayerCardsResult {
|
|
1968
|
+
/** Unexpired cards, newest first. An unknown player is an empty list. */
|
|
1969
|
+
cards: SavedCard[];
|
|
1970
|
+
raw: Record<string, unknown>;
|
|
1971
|
+
}
|
|
1972
|
+
/** `card_declined` (default) | `insufficient_funds` | `error`. */
|
|
1973
|
+
type SandboxFailureOutcome = "card_declined" | "insufficient_funds" | "error";
|
|
1974
|
+
interface SandboxForceFailureOptions {
|
|
1975
|
+
/** Up to 100 chars. */
|
|
1976
|
+
failureCode?: string;
|
|
1977
|
+
failureMessage?: string;
|
|
1978
|
+
}
|
|
1979
|
+
interface SandboxForceAuthChallengeOptions {
|
|
1980
|
+
failureMessage?: string;
|
|
1981
|
+
}
|
|
1982
|
+
/** The clock fields every sandbox clock response reports (a subset of the subscription). */
|
|
1983
|
+
interface SandboxClockState {
|
|
1984
|
+
status: string;
|
|
1985
|
+
periodSeq: number;
|
|
1986
|
+
currentPeriodStart: string | null;
|
|
1987
|
+
currentPeriodEnd: string | null;
|
|
1988
|
+
nextChargeAt: string | null;
|
|
1989
|
+
trialEnd: string | null;
|
|
1990
|
+
cancelAtPeriodEnd: boolean;
|
|
1991
|
+
walletOnly: boolean;
|
|
1992
|
+
hasPaymentMethod: boolean;
|
|
1993
|
+
amountUsd: string;
|
|
1994
|
+
raw: Record<string, unknown>;
|
|
1995
|
+
}
|
|
1996
|
+
/**
|
|
1997
|
+
* Result of the four sandbox clock tools. `action` says which; the tool-specific fields
|
|
1998
|
+
* are optional and populated per tool (see the JSDoc on each method).
|
|
1999
|
+
*/
|
|
2000
|
+
interface SandboxClockResult {
|
|
2001
|
+
/** `ok`. */
|
|
2002
|
+
status: string;
|
|
2003
|
+
/** `advance-clock` | `force-renewal` | `retired-at-period-end` | `force-failure` | `force-auth-challenge`. */
|
|
2004
|
+
action: string;
|
|
2005
|
+
subscription: SandboxClockState | null;
|
|
2006
|
+
/** advance-clock: the state before the move. */
|
|
2007
|
+
before?: SandboxClockState;
|
|
2008
|
+
/** advance-clock: the state after the move. */
|
|
2009
|
+
after?: SandboxClockState;
|
|
2010
|
+
intervals?: number;
|
|
2011
|
+
intervalsAppliedToWindow?: number;
|
|
2012
|
+
windowMoved?: boolean;
|
|
2013
|
+
windowAlreadyElapsed?: boolean;
|
|
2014
|
+
/** force-renewal: the engine's counters (`renewed`, `declined`, `insufficient`, `auth_required`, ...; on Steam also `steam_charged`, `sandbox_synthetic`, ...). */
|
|
2015
|
+
engineStats?: Record<string, number>;
|
|
2016
|
+
periodSeq?: number;
|
|
2017
|
+
attemptNo?: number;
|
|
2018
|
+
amountUsd?: string;
|
|
2019
|
+
amountCoins?: string;
|
|
2020
|
+
/** force-renewal on a cancel-at-period-end row: nothing billed, the subscription was retired. */
|
|
2021
|
+
retired?: boolean;
|
|
2022
|
+
/** force-failure. */
|
|
2023
|
+
retryBudgetUsed?: number;
|
|
2024
|
+
retryScheduleDays?: number[];
|
|
2025
|
+
retriesRemaining?: number;
|
|
2026
|
+
/** force-auth-challenge. */
|
|
2027
|
+
authChallengesUsed?: number;
|
|
2028
|
+
maxAuthChallenges?: number;
|
|
2029
|
+
downgradedToDecline?: boolean;
|
|
2030
|
+
note?: string;
|
|
2031
|
+
raw: Record<string, unknown>;
|
|
2032
|
+
}
|
|
1187
2033
|
|
|
1188
|
-
export { type
|
|
2034
|
+
export { type SandboxClockResult as $, type ApproveResult as A, type BalanceResult as B, type ConfirmReceiptResult as C, type DestinationsQuery as D, type EnrollmentBeginResult as E, type GetSubscriptionResult as F, type GetSubscriptionOptions as G, Http as H, InvoError as I, type ListSubscriptionsOptions as J, type SubscriptionListResult as K, type LinkDeviceResult as L, type MountCheckoutOptions as M, type CancelSubscriptionOptions as N, type CancelResult as O, type PendingCollectResult as P, type ChangeAmountResult as Q, type RecoveryBeginResult as R, type SubscriptionResult as S, type SetPaymentMethodInput as T, type SetPaymentMethodResult as U, type VerificationMethod as V, type RefundSubscriptionInput as W, type RefundResult as X, type SteamSubscriptionInitInput as Y, type SteamInitResult as Z, type SteamFinalizeSubscriptionResult as _, type CheckoutMountHandle as a, type FundingSource as a$, type SandboxFailureOutcome as a0, type SandboxForceFailureOptions as a1, type SandboxForceAuthChallengeOptions as a2, type ServerConfig as a3, type PlayerToken as a4, type InitiateSendInput as a5, type InitiateResult as a6, type InitiateTransferInput as a7, type CreateCheckoutInput as a8, type CreateCheckoutResult as a9, type GuardianApprovalStatusResult as aA, type ServerDestinationsQuery as aB, type PhoneShareContact as aC, type PhoneShareInitiateResult as aD, type PhoneShareApproveInput as aE, type PhoneShareApproveResult as aF, type PhoneShareStatusResult as aG, type BeginDeviceApprovalInput as aH, type DeviceApprovalGrant as aI, type PollDeviceApprovalInput as aJ, type DeviceApprovalPollResult as aK, type ConfirmDeviceEnrollmentInput as aL, type ConfirmDeviceEnrollmentResult as aM, type ApproveWithDeviceCodeInput as aN, type DeviceApprovalSettleResult as aO, type CompleteDeviceApprovalInput as aP, type CompleteDeviceApprovalResult as aQ, type CardSetupStatus as aR, type CurrencyBalance as aS, type DeviceApprovalChannel as aT, type DeviceApprovalEnrollment as aU, type DeviceApprovalFlow as aV, type DeviceApprovalPollStatus as aW, type DeviceEnrollmentDecision as aX, type DeviceEnrollmentRespond as aY, type FirstCharge as aZ, type FirstChargeStatus as a_, type PurchaseInput as aa, type PurchaseResult as ab, type ConfirmPaymentResult as ac, type OrderDetailsResult as ad, type SteamPacksQuery as ae, type SteamPacksResult as af, type SteamInitPurchaseInput as ag, type SteamInitPurchaseResult as ah, type SteamFinalizeInput as ai, type SteamFinalizeResult as aj, type PurchaseItemInput as ak, type PurchaseItemResult as al, type ItemHistoryQuery as am, type ItemHistoryResult as an, type ItemOrderQuery as ao, type PlayerBalanceQuery as ap, type PlayerBalanceResult as aq, type InboundPendingQuery as ar, type InboundPendingResult as as, type LinkedIdentitiesQuery as at, type LinkedIdentitiesResult as au, type SmsVerifyResult as av, type ClaimTransferInput as aw, type ClaimResult as ax, type ClaimCurrencyInput as ay, type TransactionStatusResult as az, type ClientConfig as b, type InboundPendingItem as b0, type LinkedIdentityEmail as b1, type PlatformPurchaseStatus as b2, type RefundRevenueShareAttribution as b3, type SandboxClockState as b4, type SavedCard as b5, type SteamPack as b6, type SteamUserSession as b7, type Subscription as b8, type SubscriptionBaseInput as b9, type SubscriptionConsent as ba, type SubscriptionConsentInput as bb, type SubscriptionFundingRail as bc, type SubscriptionInterval as bd, type SubscriptionRevenueShare as be, type SubscriptionRevenueShareInput as bf, type SubscriptionStatus as bg, type CallOptions 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 CardSetupInput as p, type CardSetupResult as q, type CardSetupConfirmInput as r, type CardSetupConfirmResult as s, type PlayerCardsResult as t, type PlatformPurchaseInput as u, type PlatformPurchaseResult as v, type PlatformOrderStatusResult as w, type PlatformRefundInput as x, type PlatformRefundResult as y, type CreateSubscriptionInput as z };
|