@invonetwork/web-sdk 3.5.0 → 3.7.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.
@@ -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,70 @@ 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;
316
372
  /** Seconds to wait before retrying, when the backend throttled the call (429 `retry_after`). */
317
373
  get retryAfter(): number | undefined;
318
374
  /** `body` as a plain object, or `{}` if it's a string/number/null (non-JSON responses).
@@ -909,9 +965,22 @@ interface ConfirmReceiptResult {
909
965
  interface PendingCollectItem {
910
966
  /** The transaction id — note the backend key is `transfer_id`. */
911
967
  transferId: string;
912
- /** "identity_gate" (you initiated → call approve*) | "receiving_confirm" (peer send → call confirmReceipt*). */
968
+ /**
969
+ * "identity_gate" — you initiated this, call approve*.
970
+ * "receiving_confirm" — it is addressed to you, call confirmReceipt*.
971
+ *
972
+ * `receiving_confirm` covers BOTH rails, a peer send and a cross-game
973
+ * transfer. Do not branch on `kind` alone to pick the endpoint: an
974
+ * integrator who read this as "peer sends only" shipped a collect screen
975
+ * that dropped every transfer and showed no button (2026-09-04). `flow` is
976
+ * what selects the call.
977
+ */
913
978
  kind: string;
914
- /** "transfer" | "send". */
979
+ /**
980
+ * "send" → confirmReceiptSend / the send confirm-receipt endpoint.
981
+ * "transfer" → confirmReceiptTransfer / the transfer one.
982
+ * THIS is the field that decides which endpoint settles the item.
983
+ */
915
984
  flow: string;
916
985
  amount: string | null;
917
986
  /** Currency name (not id). */
@@ -1184,5 +1253,190 @@ interface PhoneShareStatusResult {
1184
1253
  approved: boolean;
1185
1254
  raw: Record<string, unknown>;
1186
1255
  }
1256
+ /** The four device-approval flows. Sender side: `transfer` | `send`. Recipient side:
1257
+ * `transfer_receipt` | `send_receipt`. The flow picks which endpoint settles the money. */
1258
+ type DeviceApprovalFlow = "transfer" | "send" | "send_receipt" | "transfer_receipt";
1259
+ /**
1260
+ * How the approval page reaches the player. `qr` (default): the game renders
1261
+ * `verificationUriComplete` as a QR. `app_browser`: the Unity / Unreal plugin opens the
1262
+ * system browser (INVO derives the return scheme). `popup` is BROWSER-only — the page's
1263
+ * own https `Origin` becomes the popup's opener, so a server-to-server `begin` with it is
1264
+ * refused (400); the SDK rejects it before the network. Use `InvoClient.approveHosted`.
1265
+ */
1266
+ type DeviceApprovalChannel = "qr" | "app_browser" | "popup";
1267
+ interface BeginDeviceApprovalInput {
1268
+ /** The PLAYER'S session token (from `mintPlayerToken`) — never the game secret. */
1269
+ playerToken: string;
1270
+ /** The transaction your server initiated (`initiateSend` / `initiateTransfer`). */
1271
+ transactionId: string;
1272
+ flow: DeviceApprovalFlow;
1273
+ /** Default `"qr"`. */
1274
+ channel?: DeviceApprovalChannel;
1275
+ }
1276
+ /** The RFC 8628 §3.2 grant returned by `beginDeviceApproval`. */
1277
+ interface DeviceApprovalGrant {
1278
+ /**
1279
+ * The bearer credential for this grant. Keep it on your server: it goes into `poll`,
1280
+ * `confirmEnrollment` and — the step that moves the money — `approveWithDeviceCode`.
1281
+ * Never render it, never log it. `userCode` is the thing meant to be seen.
1282
+ */
1283
+ deviceCode: string;
1284
+ /** Short code the player could type on a TV with no camera; the QR already carries it. */
1285
+ userCode: string;
1286
+ verificationUri: string;
1287
+ /** Render THIS as the QR. */
1288
+ verificationUriComplete: string;
1289
+ /** Seconds until the grant expires. A countdown hint only — the poll's `expired_token`
1290
+ * is the truth; do not abandon a grant on your own clock. */
1291
+ expiresIn: number;
1292
+ /** Minimum seconds between polls. Honour it; `slow_down` means you didn't. */
1293
+ interval: number;
1294
+ channel: string;
1295
+ raw: Record<string, unknown>;
1296
+ }
1297
+ interface PollDeviceApprovalInput {
1298
+ playerToken: string;
1299
+ deviceCode: string;
1300
+ }
1301
+ /**
1302
+ * RFC 8628 §3.5 outcomes of one poll. `approved` is the cue to call
1303
+ * `approveWithDeviceCode` — polling to `approved` and stopping moves nothing.
1304
+ * `invalid_grant` (unknown code, or not this player's) is thrown as `InvoError`
1305
+ * (`err.code === "invalid_grant"`) rather than returned — it is a bug or a lost grant,
1306
+ * not an outcome to wait on.
1307
+ */
1308
+ type DeviceApprovalPollStatus = "approved" | "authorization_pending" | "slow_down" | "expired_token" | "access_denied";
1309
+ /** The poll's `enrollment` object — present only while a first-time phone waits on the
1310
+ * game screen to confirm the match code. */
1311
+ interface DeviceApprovalEnrollment {
1312
+ /** `awaiting_screen` → show the prompt; `confirmed` / `denied` → take it down. */
1313
+ state: string;
1314
+ /** Fixed-list label of the scanning device (iPhone, Android phone, …) — a hint, not an identity. */
1315
+ deviceLabel: string;
1316
+ /** The code the phone is showing. Draw it large: the player confirms a MATCH. */
1317
+ matchCode: string;
1318
+ /** true when the phone declared it is REPLACING a lost INVO passkey — word the prompt accordingly. */
1319
+ recovery: boolean;
1320
+ requestedAt: string | null;
1321
+ raw: Record<string, unknown>;
1322
+ }
1323
+ interface DeviceApprovalPollResult {
1324
+ status: DeviceApprovalPollStatus;
1325
+ /** Server-stated minimum poll spacing (seconds), when the body carries one. On
1326
+ * `slow_down` add 5 s to whatever you were using (RFC 8628 §3.5). */
1327
+ interval?: number;
1328
+ /** Present on `authorization_pending` while a phone waits for the on-screen match-code
1329
+ * confirmation. Answer it with `confirmDeviceEnrollment`. */
1330
+ enrollment?: DeviceApprovalEnrollment;
1331
+ /** On `approved`: the transaction and flow the grant is bound to. */
1332
+ transactionId?: string;
1333
+ flow?: string;
1334
+ approvedAt?: string | null;
1335
+ raw: Record<string, unknown>;
1336
+ }
1337
+ type DeviceEnrollmentDecision = "approve" | "deny";
1338
+ interface ConfirmDeviceEnrollmentInput {
1339
+ playerToken: string;
1340
+ deviceCode: string;
1341
+ /** `approve` = "yes, my phone shows this code"; `deny` ends the whole grant
1342
+ * (the next poll answers `access_denied`). */
1343
+ decision: DeviceEnrollmentDecision;
1344
+ }
1345
+ interface ConfirmDeviceEnrollmentResult {
1346
+ /** `confirmed` | `denied`. */
1347
+ status: string;
1348
+ raw: Record<string, unknown>;
1349
+ }
1350
+ interface ApproveWithDeviceCodeInput {
1351
+ playerToken: string;
1352
+ transactionId: string;
1353
+ /** Must be the flow the grant was begun with — a grant approved for one flow settles
1354
+ * nothing else (`DEVICE_APPROVAL_NOT_APPROVED`). */
1355
+ flow: DeviceApprovalFlow;
1356
+ deviceCode: string;
1357
+ }
1358
+ /**
1359
+ * Result of `approveWithDeviceCode` — the call that actually moves the money.
1360
+ *
1361
+ * - `transfer` / `send` success: `status: "approved"`, `next: "pending_claim"`
1362
+ * (+ `claimCode` on a transfer, for the sender to claim at the destination).
1363
+ * - `send_receipt` / `transfer_receipt` success: `status: "completed"` + `amountReceived`.
1364
+ * - A 202 hold (guardian / risk / recipient-identity): `status` is the hold's status and
1365
+ * `holdReason` names it; the money is held, not refused.
1366
+ * - `status: "not_pending"`: the backend answered `TRANSACTION_NOT_PENDING` — the
1367
+ * transaction is no longer awaiting this step. NOT a failure: a repeat call after a
1368
+ * crash or timeout lands here because the first one already settled it. Read
1369
+ * `currentStatus` (or `getTransferStatus` / `getSendStatus`) for where it is now.
1370
+ */
1371
+ interface DeviceApprovalSettleResult {
1372
+ status: string;
1373
+ transactionId: string;
1374
+ flow: DeviceApprovalFlow;
1375
+ /**
1376
+ * true ONLY when the backend answered `TRANSACTION_NOT_PENDING` and `currentStatus`
1377
+ * is a state past this step for this flow: the approval already happened, usually on
1378
+ * an earlier attempt whose response you lost. Safe to treat as success.
1379
+ *
1380
+ * false covers THREE different situations, and only one of them means "start again":
1381
+ * 1. success (nothing was "already" done);
1382
+ * 2. a dead state (expired_claim, expired_pin_verification, failed_*, rejected_*,
1383
+ * admin_cancelled) — the value is back with the sender and a fresh transaction
1384
+ * is the right move;
1385
+ * 3. NOT THERE YET, or a status this version does not recognise. On a receipt flow
1386
+ * `pending_pin_verification` / `pending_verification` mean the SENDER has not
1387
+ * approved (their approval may be sitting at a guardian prompt), and the
1388
+ * classification deliberately fails closed on anything unknown.
1389
+ *
1390
+ * So never start a replacement transaction on false alone. Read `currentStatus`, or
1391
+ * fetch the transaction, before telling a player anything.
1392
+ */
1393
+ alreadySettled: boolean;
1394
+ /** The transaction's current status when the backend said it is not pending. */
1395
+ currentStatus?: string;
1396
+ /** `pending_claim` on a transfer/send success. */
1397
+ next?: string;
1398
+ /** Transfer approve only: the sender's claim code for the destination game. */
1399
+ claimCode?: string;
1400
+ claimCodeExpiresAt?: string;
1401
+ /** Receipt flows: the net amount credited (decimal string). */
1402
+ amountReceived?: string;
1403
+ /** Present on a 202 hold: `GUARDIAN_APPROVAL_PENDING`, `RISK_HOLD`, `RECIPIENT_IDENTITY_PENDING`, … */
1404
+ holdReason?: string;
1405
+ risk?: Record<string, unknown>;
1406
+ guardianApproval?: unknown;
1407
+ pollEndpoint?: string;
1408
+ raw: Record<string, unknown>;
1409
+ }
1410
+ /** Answer the on-screen match-code prompt (forwarded to `confirmDeviceEnrollment`). */
1411
+ type DeviceEnrollmentRespond = (decision: DeviceEnrollmentDecision) => Promise<void>;
1412
+ interface CompleteDeviceApprovalInput {
1413
+ playerToken: string;
1414
+ transactionId: string;
1415
+ flow: DeviceApprovalFlow;
1416
+ /** From `beginDeviceApproval` — you already showed its QR. */
1417
+ deviceCode: string;
1418
+ /** Initial poll spacing in seconds (the grant's `interval`). Default 5. */
1419
+ interval?: number;
1420
+ /**
1421
+ * Called each time the poll's `enrollment` object changes (`null` when it clears).
1422
+ * Show "Set up INVO on <deviceLabel>? Code <matchCode>" while `state` is
1423
+ * `awaiting_screen` and call `respond("approve" | "deny")` with the player's answer.
1424
+ */
1425
+ onEnrollment?: (enrollment: DeviceApprovalEnrollment | null, respond: DeviceEnrollmentRespond) => void;
1426
+ /** Abort → resolves `{ status: "aborted" }` after the in-flight call returns. */
1427
+ signal?: AbortSignal;
1428
+ }
1429
+ interface CompleteDeviceApprovalResult {
1430
+ /**
1431
+ * `approved`: the poll said approved AND `approveWithDeviceCode` was called — see
1432
+ * `settlement` (which may itself be a hold or `not_pending`). `denied`: the player
1433
+ * declined on the page or the screen prompt. `expired`: the grant lapsed — begin again.
1434
+ * `aborted`: your `signal` fired.
1435
+ */
1436
+ status: "approved" | "denied" | "expired" | "aborted";
1437
+ settlement?: DeviceApprovalSettleResult;
1438
+ /** The last poll seen, for diagnostics. */
1439
+ lastPoll?: DeviceApprovalPollResult;
1440
+ }
1187
1441
 
1188
- export { type ItemOrderQuery as $, type ApproveResult as A, type BalanceResult as B, type CheckoutMountHandle as C, type DestinationsQuery as D, type EnrollmentBeginResult as E, type PurchaseInput as F, type PurchaseResult as G, Http as H, InvoError as I, type ConfirmPaymentResult as J, type SteamPacksQuery as K, type LinkDeviceResult as L, type MountCheckoutOptions as M, type SteamPacksResult as N, type OrderDetailsResult as O, type PendingCollectResult as P, type SteamInitPurchaseInput as Q, type RecoveryBeginResult as R, type ServerConfig as S, type SteamInitPurchaseResult as T, type SteamFinalizeInput as U, type VerificationMethod as V, type SteamFinalizeResult as W, type PurchaseItemInput as X, type PurchaseItemResult as Y, type ItemHistoryQuery as Z, type ItemHistoryResult as _, type ClientConfig as a, type PlayerBalanceQuery as a0, type PlayerBalanceResult as a1, type InboundPendingQuery as a2, type InboundPendingResult as a3, type LinkedIdentitiesQuery as a4, type LinkedIdentitiesResult as a5, type SmsVerifyResult as a6, type ClaimTransferInput as a7, type ClaimResult as a8, type ClaimCurrencyInput as a9, type TransactionStatusResult as aa, type GuardianApprovalStatusResult as ab, type ServerDestinationsQuery as ac, type PhoneShareContact as ad, type PhoneShareInitiateResult as ae, type PhoneShareApproveInput as af, type PhoneShareApproveResult as ag, type PhoneShareStatusResult as ah, type CurrencyBalance as ai, type FundingSource as aj, type InboundPendingItem as ak, type LinkedIdentityEmail as al, type PlatformPurchaseStatus as am, type SteamPack as an, type SteamUserSession as ao, type CallOptions as b, type ConfirmReceiptResult as c, type DestinationsResult as d, type EnrollmentVerifyResult as e, type RecoveryCompleteResult as f, type BalanceRow as g, type DestinationGame as h, type InvoErrorInfo as i, type InvoHooks as j, type InvoRequestInfo as k, type InvoResponseInfo as l, type PendingCollectItem as m, type Rail as n, type AuthHeader as o, type PlatformPurchaseInput as p, type PlatformPurchaseResult as q, type PlatformOrderStatusResult as r, type PlatformRefundInput as s, type PlatformRefundResult as t, type PlayerToken as u, type InitiateSendInput as v, type InitiateResult as w, type InitiateTransferInput as x, type CreateCheckoutInput as y, type CreateCheckoutResult as z };
1442
+ export { type ItemOrderQuery as $, type ApproveResult as A, type BalanceResult as B, type ConfirmReceiptResult as C, type DestinationsQuery as D, type EnrollmentBeginResult as E, type PurchaseInput as F, type PurchaseResult as G, Http as H, InvoError as I, type ConfirmPaymentResult as J, type SteamPacksQuery as K, type LinkDeviceResult as L, type MountCheckoutOptions as M, type SteamPacksResult as N, type OrderDetailsResult as O, type PendingCollectResult as P, type SteamInitPurchaseInput as Q, type RecoveryBeginResult as R, type ServerConfig as S, type SteamInitPurchaseResult as T, type SteamFinalizeInput as U, type VerificationMethod as V, type SteamFinalizeResult as W, type PurchaseItemInput as X, type PurchaseItemResult as Y, type ItemHistoryQuery as Z, type ItemHistoryResult as _, type CheckoutMountHandle as a, type PlayerBalanceQuery as a0, type PlayerBalanceResult as a1, type InboundPendingQuery as a2, type InboundPendingResult as a3, type LinkedIdentitiesQuery as a4, type LinkedIdentitiesResult as a5, type SmsVerifyResult as a6, type ClaimTransferInput as a7, type ClaimResult as a8, type ClaimCurrencyInput as a9, type InboundPendingItem as aA, type LinkedIdentityEmail as aB, type PlatformPurchaseStatus as aC, type SteamPack as aD, type SteamUserSession as aE, type TransactionStatusResult as aa, type GuardianApprovalStatusResult as ab, type ServerDestinationsQuery as ac, type PhoneShareContact as ad, type PhoneShareInitiateResult as ae, type PhoneShareApproveInput as af, type PhoneShareApproveResult as ag, type PhoneShareStatusResult as ah, type BeginDeviceApprovalInput as ai, type DeviceApprovalGrant as aj, type PollDeviceApprovalInput as ak, type DeviceApprovalPollResult as al, type ConfirmDeviceEnrollmentInput as am, type ConfirmDeviceEnrollmentResult as an, type ApproveWithDeviceCodeInput as ao, type DeviceApprovalSettleResult as ap, type CompleteDeviceApprovalInput as aq, type CompleteDeviceApprovalResult 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 FundingSource as az, type ClientConfig as b, 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 PlatformPurchaseInput as p, type PlatformPurchaseResult as q, type PlatformOrderStatusResult as r, type PlatformRefundInput as s, type PlatformRefundResult as t, type PlayerToken as u, type InitiateSendInput as v, type InitiateResult as w, type InitiateTransferInput as x, type CreateCheckoutInput as y, type CreateCheckoutResult as z };
@@ -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,70 @@ 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;
316
372
  /** Seconds to wait before retrying, when the backend throttled the call (429 `retry_after`). */
317
373
  get retryAfter(): number | undefined;
318
374
  /** `body` as a plain object, or `{}` if it's a string/number/null (non-JSON responses).
@@ -909,9 +965,22 @@ interface ConfirmReceiptResult {
909
965
  interface PendingCollectItem {
910
966
  /** The transaction id — note the backend key is `transfer_id`. */
911
967
  transferId: string;
912
- /** "identity_gate" (you initiated → call approve*) | "receiving_confirm" (peer send → call confirmReceipt*). */
968
+ /**
969
+ * "identity_gate" — you initiated this, call approve*.
970
+ * "receiving_confirm" — it is addressed to you, call confirmReceipt*.
971
+ *
972
+ * `receiving_confirm` covers BOTH rails, a peer send and a cross-game
973
+ * transfer. Do not branch on `kind` alone to pick the endpoint: an
974
+ * integrator who read this as "peer sends only" shipped a collect screen
975
+ * that dropped every transfer and showed no button (2026-09-04). `flow` is
976
+ * what selects the call.
977
+ */
913
978
  kind: string;
914
- /** "transfer" | "send". */
979
+ /**
980
+ * "send" → confirmReceiptSend / the send confirm-receipt endpoint.
981
+ * "transfer" → confirmReceiptTransfer / the transfer one.
982
+ * THIS is the field that decides which endpoint settles the item.
983
+ */
915
984
  flow: string;
916
985
  amount: string | null;
917
986
  /** Currency name (not id). */
@@ -1184,5 +1253,190 @@ interface PhoneShareStatusResult {
1184
1253
  approved: boolean;
1185
1254
  raw: Record<string, unknown>;
1186
1255
  }
1256
+ /** The four device-approval flows. Sender side: `transfer` | `send`. Recipient side:
1257
+ * `transfer_receipt` | `send_receipt`. The flow picks which endpoint settles the money. */
1258
+ type DeviceApprovalFlow = "transfer" | "send" | "send_receipt" | "transfer_receipt";
1259
+ /**
1260
+ * How the approval page reaches the player. `qr` (default): the game renders
1261
+ * `verificationUriComplete` as a QR. `app_browser`: the Unity / Unreal plugin opens the
1262
+ * system browser (INVO derives the return scheme). `popup` is BROWSER-only — the page's
1263
+ * own https `Origin` becomes the popup's opener, so a server-to-server `begin` with it is
1264
+ * refused (400); the SDK rejects it before the network. Use `InvoClient.approveHosted`.
1265
+ */
1266
+ type DeviceApprovalChannel = "qr" | "app_browser" | "popup";
1267
+ interface BeginDeviceApprovalInput {
1268
+ /** The PLAYER'S session token (from `mintPlayerToken`) — never the game secret. */
1269
+ playerToken: string;
1270
+ /** The transaction your server initiated (`initiateSend` / `initiateTransfer`). */
1271
+ transactionId: string;
1272
+ flow: DeviceApprovalFlow;
1273
+ /** Default `"qr"`. */
1274
+ channel?: DeviceApprovalChannel;
1275
+ }
1276
+ /** The RFC 8628 §3.2 grant returned by `beginDeviceApproval`. */
1277
+ interface DeviceApprovalGrant {
1278
+ /**
1279
+ * The bearer credential for this grant. Keep it on your server: it goes into `poll`,
1280
+ * `confirmEnrollment` and — the step that moves the money — `approveWithDeviceCode`.
1281
+ * Never render it, never log it. `userCode` is the thing meant to be seen.
1282
+ */
1283
+ deviceCode: string;
1284
+ /** Short code the player could type on a TV with no camera; the QR already carries it. */
1285
+ userCode: string;
1286
+ verificationUri: string;
1287
+ /** Render THIS as the QR. */
1288
+ verificationUriComplete: string;
1289
+ /** Seconds until the grant expires. A countdown hint only — the poll's `expired_token`
1290
+ * is the truth; do not abandon a grant on your own clock. */
1291
+ expiresIn: number;
1292
+ /** Minimum seconds between polls. Honour it; `slow_down` means you didn't. */
1293
+ interval: number;
1294
+ channel: string;
1295
+ raw: Record<string, unknown>;
1296
+ }
1297
+ interface PollDeviceApprovalInput {
1298
+ playerToken: string;
1299
+ deviceCode: string;
1300
+ }
1301
+ /**
1302
+ * RFC 8628 §3.5 outcomes of one poll. `approved` is the cue to call
1303
+ * `approveWithDeviceCode` — polling to `approved` and stopping moves nothing.
1304
+ * `invalid_grant` (unknown code, or not this player's) is thrown as `InvoError`
1305
+ * (`err.code === "invalid_grant"`) rather than returned — it is a bug or a lost grant,
1306
+ * not an outcome to wait on.
1307
+ */
1308
+ type DeviceApprovalPollStatus = "approved" | "authorization_pending" | "slow_down" | "expired_token" | "access_denied";
1309
+ /** The poll's `enrollment` object — present only while a first-time phone waits on the
1310
+ * game screen to confirm the match code. */
1311
+ interface DeviceApprovalEnrollment {
1312
+ /** `awaiting_screen` → show the prompt; `confirmed` / `denied` → take it down. */
1313
+ state: string;
1314
+ /** Fixed-list label of the scanning device (iPhone, Android phone, …) — a hint, not an identity. */
1315
+ deviceLabel: string;
1316
+ /** The code the phone is showing. Draw it large: the player confirms a MATCH. */
1317
+ matchCode: string;
1318
+ /** true when the phone declared it is REPLACING a lost INVO passkey — word the prompt accordingly. */
1319
+ recovery: boolean;
1320
+ requestedAt: string | null;
1321
+ raw: Record<string, unknown>;
1322
+ }
1323
+ interface DeviceApprovalPollResult {
1324
+ status: DeviceApprovalPollStatus;
1325
+ /** Server-stated minimum poll spacing (seconds), when the body carries one. On
1326
+ * `slow_down` add 5 s to whatever you were using (RFC 8628 §3.5). */
1327
+ interval?: number;
1328
+ /** Present on `authorization_pending` while a phone waits for the on-screen match-code
1329
+ * confirmation. Answer it with `confirmDeviceEnrollment`. */
1330
+ enrollment?: DeviceApprovalEnrollment;
1331
+ /** On `approved`: the transaction and flow the grant is bound to. */
1332
+ transactionId?: string;
1333
+ flow?: string;
1334
+ approvedAt?: string | null;
1335
+ raw: Record<string, unknown>;
1336
+ }
1337
+ type DeviceEnrollmentDecision = "approve" | "deny";
1338
+ interface ConfirmDeviceEnrollmentInput {
1339
+ playerToken: string;
1340
+ deviceCode: string;
1341
+ /** `approve` = "yes, my phone shows this code"; `deny` ends the whole grant
1342
+ * (the next poll answers `access_denied`). */
1343
+ decision: DeviceEnrollmentDecision;
1344
+ }
1345
+ interface ConfirmDeviceEnrollmentResult {
1346
+ /** `confirmed` | `denied`. */
1347
+ status: string;
1348
+ raw: Record<string, unknown>;
1349
+ }
1350
+ interface ApproveWithDeviceCodeInput {
1351
+ playerToken: string;
1352
+ transactionId: string;
1353
+ /** Must be the flow the grant was begun with — a grant approved for one flow settles
1354
+ * nothing else (`DEVICE_APPROVAL_NOT_APPROVED`). */
1355
+ flow: DeviceApprovalFlow;
1356
+ deviceCode: string;
1357
+ }
1358
+ /**
1359
+ * Result of `approveWithDeviceCode` — the call that actually moves the money.
1360
+ *
1361
+ * - `transfer` / `send` success: `status: "approved"`, `next: "pending_claim"`
1362
+ * (+ `claimCode` on a transfer, for the sender to claim at the destination).
1363
+ * - `send_receipt` / `transfer_receipt` success: `status: "completed"` + `amountReceived`.
1364
+ * - A 202 hold (guardian / risk / recipient-identity): `status` is the hold's status and
1365
+ * `holdReason` names it; the money is held, not refused.
1366
+ * - `status: "not_pending"`: the backend answered `TRANSACTION_NOT_PENDING` — the
1367
+ * transaction is no longer awaiting this step. NOT a failure: a repeat call after a
1368
+ * crash or timeout lands here because the first one already settled it. Read
1369
+ * `currentStatus` (or `getTransferStatus` / `getSendStatus`) for where it is now.
1370
+ */
1371
+ interface DeviceApprovalSettleResult {
1372
+ status: string;
1373
+ transactionId: string;
1374
+ flow: DeviceApprovalFlow;
1375
+ /**
1376
+ * true ONLY when the backend answered `TRANSACTION_NOT_PENDING` and `currentStatus`
1377
+ * is a state past this step for this flow: the approval already happened, usually on
1378
+ * an earlier attempt whose response you lost. Safe to treat as success.
1379
+ *
1380
+ * false covers THREE different situations, and only one of them means "start again":
1381
+ * 1. success (nothing was "already" done);
1382
+ * 2. a dead state (expired_claim, expired_pin_verification, failed_*, rejected_*,
1383
+ * admin_cancelled) — the value is back with the sender and a fresh transaction
1384
+ * is the right move;
1385
+ * 3. NOT THERE YET, or a status this version does not recognise. On a receipt flow
1386
+ * `pending_pin_verification` / `pending_verification` mean the SENDER has not
1387
+ * approved (their approval may be sitting at a guardian prompt), and the
1388
+ * classification deliberately fails closed on anything unknown.
1389
+ *
1390
+ * So never start a replacement transaction on false alone. Read `currentStatus`, or
1391
+ * fetch the transaction, before telling a player anything.
1392
+ */
1393
+ alreadySettled: boolean;
1394
+ /** The transaction's current status when the backend said it is not pending. */
1395
+ currentStatus?: string;
1396
+ /** `pending_claim` on a transfer/send success. */
1397
+ next?: string;
1398
+ /** Transfer approve only: the sender's claim code for the destination game. */
1399
+ claimCode?: string;
1400
+ claimCodeExpiresAt?: string;
1401
+ /** Receipt flows: the net amount credited (decimal string). */
1402
+ amountReceived?: string;
1403
+ /** Present on a 202 hold: `GUARDIAN_APPROVAL_PENDING`, `RISK_HOLD`, `RECIPIENT_IDENTITY_PENDING`, … */
1404
+ holdReason?: string;
1405
+ risk?: Record<string, unknown>;
1406
+ guardianApproval?: unknown;
1407
+ pollEndpoint?: string;
1408
+ raw: Record<string, unknown>;
1409
+ }
1410
+ /** Answer the on-screen match-code prompt (forwarded to `confirmDeviceEnrollment`). */
1411
+ type DeviceEnrollmentRespond = (decision: DeviceEnrollmentDecision) => Promise<void>;
1412
+ interface CompleteDeviceApprovalInput {
1413
+ playerToken: string;
1414
+ transactionId: string;
1415
+ flow: DeviceApprovalFlow;
1416
+ /** From `beginDeviceApproval` — you already showed its QR. */
1417
+ deviceCode: string;
1418
+ /** Initial poll spacing in seconds (the grant's `interval`). Default 5. */
1419
+ interval?: number;
1420
+ /**
1421
+ * Called each time the poll's `enrollment` object changes (`null` when it clears).
1422
+ * Show "Set up INVO on <deviceLabel>? Code <matchCode>" while `state` is
1423
+ * `awaiting_screen` and call `respond("approve" | "deny")` with the player's answer.
1424
+ */
1425
+ onEnrollment?: (enrollment: DeviceApprovalEnrollment | null, respond: DeviceEnrollmentRespond) => void;
1426
+ /** Abort → resolves `{ status: "aborted" }` after the in-flight call returns. */
1427
+ signal?: AbortSignal;
1428
+ }
1429
+ interface CompleteDeviceApprovalResult {
1430
+ /**
1431
+ * `approved`: the poll said approved AND `approveWithDeviceCode` was called — see
1432
+ * `settlement` (which may itself be a hold or `not_pending`). `denied`: the player
1433
+ * declined on the page or the screen prompt. `expired`: the grant lapsed — begin again.
1434
+ * `aborted`: your `signal` fired.
1435
+ */
1436
+ status: "approved" | "denied" | "expired" | "aborted";
1437
+ settlement?: DeviceApprovalSettleResult;
1438
+ /** The last poll seen, for diagnostics. */
1439
+ lastPoll?: DeviceApprovalPollResult;
1440
+ }
1187
1441
 
1188
- export { type ItemOrderQuery as $, type ApproveResult as A, type BalanceResult as B, type CheckoutMountHandle as C, type DestinationsQuery as D, type EnrollmentBeginResult as E, type PurchaseInput as F, type PurchaseResult as G, Http as H, InvoError as I, type ConfirmPaymentResult as J, type SteamPacksQuery as K, type LinkDeviceResult as L, type MountCheckoutOptions as M, type SteamPacksResult as N, type OrderDetailsResult as O, type PendingCollectResult as P, type SteamInitPurchaseInput as Q, type RecoveryBeginResult as R, type ServerConfig as S, type SteamInitPurchaseResult as T, type SteamFinalizeInput as U, type VerificationMethod as V, type SteamFinalizeResult as W, type PurchaseItemInput as X, type PurchaseItemResult as Y, type ItemHistoryQuery as Z, type ItemHistoryResult as _, type ClientConfig as a, type PlayerBalanceQuery as a0, type PlayerBalanceResult as a1, type InboundPendingQuery as a2, type InboundPendingResult as a3, type LinkedIdentitiesQuery as a4, type LinkedIdentitiesResult as a5, type SmsVerifyResult as a6, type ClaimTransferInput as a7, type ClaimResult as a8, type ClaimCurrencyInput as a9, type TransactionStatusResult as aa, type GuardianApprovalStatusResult as ab, type ServerDestinationsQuery as ac, type PhoneShareContact as ad, type PhoneShareInitiateResult as ae, type PhoneShareApproveInput as af, type PhoneShareApproveResult as ag, type PhoneShareStatusResult as ah, type CurrencyBalance as ai, type FundingSource as aj, type InboundPendingItem as ak, type LinkedIdentityEmail as al, type PlatformPurchaseStatus as am, type SteamPack as an, type SteamUserSession as ao, type CallOptions as b, type ConfirmReceiptResult as c, type DestinationsResult as d, type EnrollmentVerifyResult as e, type RecoveryCompleteResult as f, type BalanceRow as g, type DestinationGame as h, type InvoErrorInfo as i, type InvoHooks as j, type InvoRequestInfo as k, type InvoResponseInfo as l, type PendingCollectItem as m, type Rail as n, type AuthHeader as o, type PlatformPurchaseInput as p, type PlatformPurchaseResult as q, type PlatformOrderStatusResult as r, type PlatformRefundInput as s, type PlatformRefundResult as t, type PlayerToken as u, type InitiateSendInput as v, type InitiateResult as w, type InitiateTransferInput as x, type CreateCheckoutInput as y, type CreateCheckoutResult as z };
1442
+ export { type ItemOrderQuery as $, type ApproveResult as A, type BalanceResult as B, type ConfirmReceiptResult as C, type DestinationsQuery as D, type EnrollmentBeginResult as E, type PurchaseInput as F, type PurchaseResult as G, Http as H, InvoError as I, type ConfirmPaymentResult as J, type SteamPacksQuery as K, type LinkDeviceResult as L, type MountCheckoutOptions as M, type SteamPacksResult as N, type OrderDetailsResult as O, type PendingCollectResult as P, type SteamInitPurchaseInput as Q, type RecoveryBeginResult as R, type ServerConfig as S, type SteamInitPurchaseResult as T, type SteamFinalizeInput as U, type VerificationMethod as V, type SteamFinalizeResult as W, type PurchaseItemInput as X, type PurchaseItemResult as Y, type ItemHistoryQuery as Z, type ItemHistoryResult as _, type CheckoutMountHandle as a, type PlayerBalanceQuery as a0, type PlayerBalanceResult as a1, type InboundPendingQuery as a2, type InboundPendingResult as a3, type LinkedIdentitiesQuery as a4, type LinkedIdentitiesResult as a5, type SmsVerifyResult as a6, type ClaimTransferInput as a7, type ClaimResult as a8, type ClaimCurrencyInput as a9, type InboundPendingItem as aA, type LinkedIdentityEmail as aB, type PlatformPurchaseStatus as aC, type SteamPack as aD, type SteamUserSession as aE, type TransactionStatusResult as aa, type GuardianApprovalStatusResult as ab, type ServerDestinationsQuery as ac, type PhoneShareContact as ad, type PhoneShareInitiateResult as ae, type PhoneShareApproveInput as af, type PhoneShareApproveResult as ag, type PhoneShareStatusResult as ah, type BeginDeviceApprovalInput as ai, type DeviceApprovalGrant as aj, type PollDeviceApprovalInput as ak, type DeviceApprovalPollResult as al, type ConfirmDeviceEnrollmentInput as am, type ConfirmDeviceEnrollmentResult as an, type ApproveWithDeviceCodeInput as ao, type DeviceApprovalSettleResult as ap, type CompleteDeviceApprovalInput as aq, type CompleteDeviceApprovalResult 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 FundingSource as az, type ClientConfig as b, 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 PlatformPurchaseInput as p, type PlatformPurchaseResult as q, type PlatformOrderStatusResult as r, type PlatformRefundInput as s, type PlatformRefundResult as t, type PlayerToken as u, type InitiateSendInput as v, type InitiateResult as w, type InitiateTransferInput as x, type CreateCheckoutInput as y, type CreateCheckoutResult as z };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@invonetwork/web-sdk",
3
- "version": "3.5.0",
3
+ "version": "3.7.0",
4
4
  "description": "INVO Web SDK — currency purchase + passkey (WebAuthn) verification for partner web platforms.",
5
5
  "license": "SEE LICENSE IN LICENSE",
6
6
  "private": false,
@@ -67,6 +67,7 @@
67
67
  "@changesets/cli": "^2.31.0",
68
68
  "@eslint/js": "^10.0.1",
69
69
  "eslint": "^10.6.0",
70
+ "happy-dom": "^15.11.7",
70
71
  "rimraf": "^5.0.5",
71
72
  "tsup": "^8.0.1",
72
73
  "typescript": "^5.4.5",