@invonetwork/web-sdk 2.2.0 → 2.4.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 CHANGED
@@ -4,6 +4,39 @@ All notable changes to `@invonetwork/web-sdk` are documented here. This project
4
4
  [Semantic Versioning](https://semver.org/). Releases are managed with
5
5
  [changesets](https://github.com/changesets/changesets).
6
6
 
7
+ ## [2.4.0] — 2026-07-10
8
+
9
+ **Steam transfer policy.** Steam-purchased currency is locked to Steam titles; the backend now
10
+ enforces this at transfer/send initiate and annotates destinations. Additive, and inert until a
11
+ title is flagged Steam-distributed. (Design doc: `docs/features/steam-transfer-policy.md`.)
12
+
13
+ - New `InvoError` classifiers on `initiateSend`/`initiateTransfer` 409s:
14
+ `isSteamValueNonTransferable` (with `steamTransferableMax` / `steamOriginAmount` — decimal
15
+ strings) and `isNonSteamValueIntoSteamBlocked`. Surface `err.message` verbatim.
16
+ - New `DestinationGame.acceptsSteamOriginValue` (maps `accepts_steam_origin_value`; `false` when
17
+ omitted) — disable non-Steam destinations for a player holding Steam value so they never hit
18
+ the 409.
19
+
20
+ No breaking changes.
21
+
22
+ ## [2.3.0] — 2026-07-07
23
+
24
+ **Claim-time phone-share approval.** The backend closed a security gap: claiming/collecting a
25
+ phone-routed transfer now authorizes the collecting identity against the receiver phone before
26
+ crediting. So `confirmReceiptSend`/`confirmReceiptTransfer` and `claimTransfer`/`claimCurrency`
27
+ can now return the phone-share `409 PHONE_SHARE_APPROVAL_REQUIRED` (previously only
28
+ registration/mint did). The existing `InvoError.isPhoneShareApprovalRequired` already classifies
29
+ it — no consumer code must change — but:
30
+
31
+ - New **`InvoError.phoneShareLast4`** surfaces the `phone_last4` from the 409 body for the UI
32
+ ("we texted the phone ending 1234").
33
+ - `isPhoneShareApprovalRequired` docs + the `confirmReceipt*`/claim method docs + README now
34
+ spell out the claim-time path: it's **not a failure** — the funds are held and the phone owner
35
+ is texted; show `err.message` verbatim, then **retry the same call** once approved (it succeeds
36
+ idempotently); on denial/expiry the sender is refunded.
37
+
38
+ Additive, no breaking changes; affects all rails' claim paths (transfer, currency send, amazon).
39
+
7
40
  ## [2.2.0] — 2026-07-07
8
41
 
9
42
  **Backend reconciliation** — a full audit of the SDK against the live backend surfaced three
package/README.md CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  First-party TypeScript SDK for integrating **INVO** into partner **web** platforms (storefronts, web games, dashboards). It wraps INVO's web money flows behind a typed, versioned API — the web analog of the Unity/Unreal plugins.
4
4
 
5
- > **Status:** `v2.1.1` — stable, published on npm. The backend it wraps is **live** on sandbox + production. The API is covered by a [stability commitment](#stability): no breaking changes without a major bump. **Since 2.0.0 (breaking):** `mintPlayerToken` requires `playerPhone` (E.164) — see the [CHANGELOG](CHANGELOG.md) migration note. **2.1.0 adds** self-serve passkey recovery; **2.1.1** security hardening; **2.1.2** `expiresInSeconds` on `createCheckout`. **2.2.0** reconciles with the backend: `mintPlayerToken` no longer requires `playerPhone` (it's a session mint, not registration), send-by-phone-alone, and `getPlayerBalance` is email-only.
5
+ > **Status:** `v2.3.0` — stable, published on npm. The backend it wraps is **live** on sandbox + production. The API is covered by a [stability commitment](#stability): no breaking changes without a major bump. Recent highlights: **2.2.0** reconciled with the backend (`mintPlayerToken` is a session mint — `playerPhone` optional; send-by-phone-alone; email-only `getPlayerBalance`); **2.3.0** surfaces the claim-time phone-share `409` on `confirmReceipt*`/`claim*` (+ `err.phoneShareLast4`); **2.4.0** adds Steam transfer-policy handling (`isSteamValueNonTransferable`/`isNonSteamValueIntoSteamBlocked` + `DestinationGame.acceptsSteamOriginValue`). Full history in the [CHANGELOG](CHANGELOG.md).
6
6
  > Canonical partner reference: **https://docs.invo.network/docs/currency-purchase** and **https://docs.invo.network/docs/game-developer-integration**.
7
7
 
8
8
  ## What it does
@@ -370,6 +370,10 @@ try {
370
370
  } catch (e) {
371
371
  if (e instanceof InvoError && e.isReceiverNotEnrolled) {
372
372
  // recipient has no passkey here → show claim-code entry using approved.claimCode
373
+ } else if (e instanceof InvoError && e.isPhoneShareApprovalRequired) {
374
+ // receiver phone is contested → funds held, phone owner texted to approve.
375
+ showPending(e.message, e.phoneShareLast4); // show e.message verbatim; last4 names the phone
376
+ // …then RETRY the same confirmReceipt*/claim call once approved (succeeds idempotently).
373
377
  } else throw e;
374
378
  }
375
379
  ```
@@ -377,6 +381,8 @@ try {
377
381
  - **`verificationMethod`** (from initiate): `"in_app"` → passkey approve; `"sms"` → un-enrolled, PIN sent; `undefined` + `guardianApproval` → minor/guardian (HTTP 202), do **not** show the PIN UI. On the guardian path the SDK reports `verificationMethod: undefined` (even though the raw 202 body also carries `"sms"`) so `guardianApproval` wins — but branch on it first to be safe.
378
382
  - **Claim codes** are returned only by `approveTransfer`; they're the out-of-band fallback when the recipient isn't enrolled.
379
383
  - **`err.isReceiverNotEnrolled`** on `confirmReceipt*` is the explicit signal to switch to claim-code entry.
384
+ - **`err.isPhoneShareApprovalRequired` on `confirmReceipt*` / `claimTransfer` / `claimCurrency`** (409): the receiver phone is contested, so INVO **holds the money** and texts the phone owner to approve. Not a failure — show `err.message` verbatim (`err.phoneShareLast4` names the phone), then **retry the same call** once approved (it succeeds idempotently); on denial/expiry the sender is refunded. Same handling as the initiate-time phone-share 409.
385
+ - **Steam titles** (dark until a title is Steam-distributed): `initiateSend`/`initiateTransfer` can throw `err.isSteamValueNonTransferable` (moving more than the non-Steam balance to a non-Steam destination — show `err.message`, cap the amount at `err.steamTransferableMax`; `err.steamOriginAmount` is the Steam-locked portion) or `err.isNonSteamValueIntoSteamBlocked` (non-Steam value into a Steam title). Prevent both up front: `getDestinations` rows carry **`acceptsSteamOriginValue`** — disable non-Steam destinations for a player holding Steam-purchased currency.
380
386
  - Transfer self-claim may be disabled for your tenant; if it is, surface the claim-code path instead.
381
387
  - **Holds:** an approve/claim can return an HTTP 202 hold instead of success — inspect `result.holdReason` (`"RISK_HOLD"`, `"GUARDIAN_APPROVAL_PENDING"`, and on confirm-receipt `"RECIPIENT_IDENTITY_PENDING"`); success has no `holdReason` (and `next: "pending_claim"`). Terminal guardian outcomes throw (`GUARDIAN_APPROVAL_REJECTED`/`_EXPIRED`).
382
388
 
@@ -567,7 +573,9 @@ Helpers:
567
573
  | `.retryAfter` | seconds to back off on a 429 throttle |
568
574
  | `.isEnrollmentAuthorizationRequired` | first-enrollment needs the OTP grant → `enrollmentBegin`/`enrollmentVerify` |
569
575
  | `.isEnrollmentProofRequired` | another method exists → prove it via `linkDevice` |
570
- | `.isPhoneShareApprovalRequired` | a new-account phone needs owner approval → run the `phoneShare*` handshake, then retry |
576
+ | `.isPhoneShareApprovalRequired` | phone needs owner approval — at register/mint **or** at claim/`confirmReceipt*` (contested receiver phone) → show `.message` (+ `.phoneShareLast4`), retry the same call after approval |
577
+ | `.isSteamValueNonTransferable` | initiate blocked (409): would move more than the non-Steam balance to a non-Steam destination → show `.message`, cap input at `.steamTransferableMax` (`.steamOriginAmount` = Steam-locked portion) |
578
+ | `.isNonSteamValueIntoSteamBlocked` | initiate blocked (409): non-Steam value can't move into a Steam title → show `.message`, pick a non-Steam destination |
571
579
  | `.isPhoneShareAlreadyApproved` | phone-share was already approved (e.g. from a `/reject`) |
572
580
 
573
581
  Client-side guards (bad amount, missing idempotency key, `rail:"steam"` on `purchaseCurrency`, item validation) throw `InvoError` with `.status === 0` **before** any network call. Notable backend codes: `SDK_TOKEN_EXPIRED`, `TENANT_NOT_MIGRATED`, `WEBAUTHN_NOT_ENABLED_FOR_TENANT`, `WEBAUTHN_UV_REQUIRED`, `ENROLLMENT_REQUIRES_PROOF`, `ENROLLMENT_CODE_INVALID`, `PASSKEY_RECOVERY_COOLDOWN` (403, `retryAfterAt`), `no_channel_on_file`, `rate_limited`, `WRONG_RAIL_ENDPOINT`, `flow_paused`.
@@ -70,12 +70,19 @@ var InvoError = class _InvoError extends Error {
70
70
  return this.code === "INSUFFICIENT_BALANCE" || "required_amount" in b || /insufficient[_ ]balance/i.test(this.message);
71
71
  }
72
72
  /**
73
- * True if the call needs phone-share approval before it can complete (409). Raised by
74
- * registration/token-mint and by claims when the phone already belongs to another INVO
75
- * account (same person, new email — expected, not a failure). The phone holder gets a
76
- * consent SMS; show "pending approval", then re-issue the identical call once approved
77
- * (poll `phoneShareStatus`, or use `phoneShareInitiate`/`phoneShareApprove` for the OTP
78
- * fallback). `phoneShareApprovalId` carries the id from the 409 body.
73
+ * True if the call needs phone-share approval before it can complete (409) — the
74
+ * collecting/registering identity isn't yet authorized for the phone on file. Raised by:
75
+ * - registration/token-mint (phone already on another INVO account), and
76
+ * - **claim + confirm-receipt** (`claimTransfer`/`claimCurrency`,
77
+ * `confirmReceiptSend`/`confirmReceiptTransfer`) — the receiver phone is contested,
78
+ * so INVO holds the money and texts the phone owner to approve.
79
+ *
80
+ * NOT a failure. Show `err.message` verbatim (the backend supplies the user-facing text;
81
+ * `phoneShareLast4` tells the UI which phone), keep the funds pending, and **retry the same
82
+ * call** once the phone owner approves — an approved consent makes the retry succeed
83
+ * idempotently. On denial/expiry the backend refunds the sender. (`phoneShareApprovalId`
84
+ * carries the id when the 409 came from the OTP-handshake path;
85
+ * `phoneShareInitiate`/`phoneShareApprove`/`phoneShareStatus` drive that fallback.)
79
86
  */
80
87
  get isPhoneShareApprovalRequired() {
81
88
  return this.code === "PHONE_SHARE_APPROVAL_REQUIRED";
@@ -85,6 +92,40 @@ var InvoError = class _InvoError extends Error {
85
92
  const v = this.bodyObject()["approval_id"];
86
93
  return typeof v === "string" && v ? v : void 0;
87
94
  }
95
+ /** Last 4 digits of the phone that must approve (`phone_last4`), for the UI message. */
96
+ get phoneShareLast4() {
97
+ const v = this.bodyObject()["phone_last4"];
98
+ return typeof v === "string" && v ? v : void 0;
99
+ }
100
+ /**
101
+ * True if a transfer/send initiate was blocked because it would move more than the player's
102
+ * NON-Steam balance to a non-Steam destination (`STEAM_VALUE_NON_TRANSFERABLE`, 409).
103
+ * Steam-purchased currency is locked to Steam titles. NOT retryable as-is — show
104
+ * `err.message` and cap the amount at `err.steamTransferableMax` (`err.steamOriginAmount`
105
+ * is the Steam-locked portion). Prevent it up front by hiding non-Steam destinations for a
106
+ * holder of Steam value (`DestinationGame.acceptsSteamOriginValue`).
107
+ */
108
+ get isSteamValueNonTransferable() {
109
+ return this.code === "STEAM_VALUE_NON_TRANSFERABLE";
110
+ }
111
+ /** Max the player can still send to this (non-Steam) destination (`transferable_max`), a decimal string. */
112
+ get steamTransferableMax() {
113
+ const v = this.bodyObject()["transferable_max"];
114
+ return typeof v === "string" && v ? v : void 0;
115
+ }
116
+ /** The Steam-purchased portion locked to Steam titles (`steam_origin_amount`), a decimal string. */
117
+ get steamOriginAmount() {
118
+ const v = this.bodyObject()["steam_origin_amount"];
119
+ return typeof v === "string" && v ? v : void 0;
120
+ }
121
+ /**
122
+ * True if a transfer/send initiate was blocked because it moves NON-Steam value INTO a
123
+ * Steam title (`NON_STEAM_VALUE_INTO_STEAM_BLOCKED`, 409). Show `err.message`; the fix is to
124
+ * pick a non-Steam destination (surfaced via `DestinationGame.acceptsSteamOriginValue`).
125
+ */
126
+ get isNonSteamValueIntoSteamBlocked() {
127
+ return this.code === "NON_STEAM_VALUE_INTO_STEAM_BLOCKED";
128
+ }
88
129
  /** True if the phone-share (phone, requesting_email) pair was already approved. */
89
130
  get isPhoneShareAlreadyApproved() {
90
131
  return this.code === "PHONE_SHARE_ALREADY_APPROVED";
@@ -346,6 +387,7 @@ function toDestinationGame(row) {
346
387
  currencySymbolUrl: s("currency_symbol_url"),
347
388
  minimumTransfer: String(row["minimum_transfer"] ?? ""),
348
389
  maximumTransfer: String(row["maximum_transfer"] ?? ""),
390
+ acceptsSteamOriginValue: row["accepts_steam_origin_value"] === true,
349
391
  raw: row
350
392
  };
351
393
  }
@@ -369,5 +411,5 @@ function toDestinationsResult(raw, direction) {
369
411
  }
370
412
 
371
413
  export { Http, InvoError, assertSecureBaseUrl, toDestinationsResult };
372
- //# sourceMappingURL=chunk-DJADKVYI.js.map
373
- //# sourceMappingURL=chunk-DJADKVYI.js.map
414
+ //# sourceMappingURL=chunk-SSTZKXPC.js.map
415
+ //# sourceMappingURL=chunk-SSTZKXPC.js.map
package/dist/index.cjs CHANGED
@@ -72,12 +72,19 @@ var InvoError = class _InvoError extends Error {
72
72
  return this.code === "INSUFFICIENT_BALANCE" || "required_amount" in b || /insufficient[_ ]balance/i.test(this.message);
73
73
  }
74
74
  /**
75
- * True if the call needs phone-share approval before it can complete (409). Raised by
76
- * registration/token-mint and by claims when the phone already belongs to another INVO
77
- * account (same person, new email — expected, not a failure). The phone holder gets a
78
- * consent SMS; show "pending approval", then re-issue the identical call once approved
79
- * (poll `phoneShareStatus`, or use `phoneShareInitiate`/`phoneShareApprove` for the OTP
80
- * fallback). `phoneShareApprovalId` carries the id from the 409 body.
75
+ * True if the call needs phone-share approval before it can complete (409) — the
76
+ * collecting/registering identity isn't yet authorized for the phone on file. Raised by:
77
+ * - registration/token-mint (phone already on another INVO account), and
78
+ * - **claim + confirm-receipt** (`claimTransfer`/`claimCurrency`,
79
+ * `confirmReceiptSend`/`confirmReceiptTransfer`) — the receiver phone is contested,
80
+ * so INVO holds the money and texts the phone owner to approve.
81
+ *
82
+ * NOT a failure. Show `err.message` verbatim (the backend supplies the user-facing text;
83
+ * `phoneShareLast4` tells the UI which phone), keep the funds pending, and **retry the same
84
+ * call** once the phone owner approves — an approved consent makes the retry succeed
85
+ * idempotently. On denial/expiry the backend refunds the sender. (`phoneShareApprovalId`
86
+ * carries the id when the 409 came from the OTP-handshake path;
87
+ * `phoneShareInitiate`/`phoneShareApprove`/`phoneShareStatus` drive that fallback.)
81
88
  */
82
89
  get isPhoneShareApprovalRequired() {
83
90
  return this.code === "PHONE_SHARE_APPROVAL_REQUIRED";
@@ -87,6 +94,40 @@ var InvoError = class _InvoError extends Error {
87
94
  const v = this.bodyObject()["approval_id"];
88
95
  return typeof v === "string" && v ? v : void 0;
89
96
  }
97
+ /** Last 4 digits of the phone that must approve (`phone_last4`), for the UI message. */
98
+ get phoneShareLast4() {
99
+ const v = this.bodyObject()["phone_last4"];
100
+ return typeof v === "string" && v ? v : void 0;
101
+ }
102
+ /**
103
+ * True if a transfer/send initiate was blocked because it would move more than the player's
104
+ * NON-Steam balance to a non-Steam destination (`STEAM_VALUE_NON_TRANSFERABLE`, 409).
105
+ * Steam-purchased currency is locked to Steam titles. NOT retryable as-is — show
106
+ * `err.message` and cap the amount at `err.steamTransferableMax` (`err.steamOriginAmount`
107
+ * is the Steam-locked portion). Prevent it up front by hiding non-Steam destinations for a
108
+ * holder of Steam value (`DestinationGame.acceptsSteamOriginValue`).
109
+ */
110
+ get isSteamValueNonTransferable() {
111
+ return this.code === "STEAM_VALUE_NON_TRANSFERABLE";
112
+ }
113
+ /** Max the player can still send to this (non-Steam) destination (`transferable_max`), a decimal string. */
114
+ get steamTransferableMax() {
115
+ const v = this.bodyObject()["transferable_max"];
116
+ return typeof v === "string" && v ? v : void 0;
117
+ }
118
+ /** The Steam-purchased portion locked to Steam titles (`steam_origin_amount`), a decimal string. */
119
+ get steamOriginAmount() {
120
+ const v = this.bodyObject()["steam_origin_amount"];
121
+ return typeof v === "string" && v ? v : void 0;
122
+ }
123
+ /**
124
+ * True if a transfer/send initiate was blocked because it moves NON-Steam value INTO a
125
+ * Steam title (`NON_STEAM_VALUE_INTO_STEAM_BLOCKED`, 409). Show `err.message`; the fix is to
126
+ * pick a non-Steam destination (surfaced via `DestinationGame.acceptsSteamOriginValue`).
127
+ */
128
+ get isNonSteamValueIntoSteamBlocked() {
129
+ return this.code === "NON_STEAM_VALUE_INTO_STEAM_BLOCKED";
130
+ }
90
131
  /** True if the phone-share (phone, requesting_email) pair was already approved. */
91
132
  get isPhoneShareAlreadyApproved() {
92
133
  return this.code === "PHONE_SHARE_ALREADY_APPROVED";
@@ -439,6 +480,7 @@ function toDestinationGame(row) {
439
480
  currencySymbolUrl: s("currency_symbol_url"),
440
481
  minimumTransfer: String(row["minimum_transfer"] ?? ""),
441
482
  maximumTransfer: String(row["maximum_transfer"] ?? ""),
483
+ acceptsSteamOriginValue: row["accepts_steam_origin_value"] === true,
442
484
  raw: row
443
485
  };
444
486
  }
@@ -547,11 +589,21 @@ var InvoClient = class {
547
589
  async approveTransfer(transactionId, opts) {
548
590
  return this.approve("transfers", transactionId, opts);
549
591
  }
550
- /** Recipient self-claims a SEND with their passkey. */
592
+ /**
593
+ * Recipient self-claims a SEND with their passkey.
594
+ *
595
+ * May throw a 409 with `err.isPhoneShareApprovalRequired` when the receiver phone is
596
+ * contested (the collecting identity isn't yet authorized for it). NOT a failure — the
597
+ * money is held and the phone owner is texted to approve. Show `err.message`
598
+ * (`err.phoneShareLast4` names the phone), then **retry this same call** once approved
599
+ * (it then succeeds idempotently); on denial/expiry the backend refunds the sender.
600
+ */
551
601
  async confirmReceiptSend(transactionId, opts) {
552
602
  return this.confirmReceipt("send", transactionId, opts);
553
603
  }
554
- /** Recipient self-claims a TRANSFER with their passkey. */
604
+ /** Recipient self-claims a TRANSFER with their passkey. Can throw the same phone-share
605
+ * 409 as {@link confirmReceiptSend} (`err.isPhoneShareApprovalRequired`) — handle it the
606
+ * same way: show `err.message`, retry after the phone owner approves. */
555
607
  async confirmReceiptTransfer(transactionId, opts) {
556
608
  return this.confirmReceipt("transfers", transactionId, opts);
557
609
  }
package/dist/index.d.cts CHANGED
@@ -1,5 +1,5 @@
1
- import { C as ClientConfig, a as CallOptions, A as ApproveResult, b as ConfirmReceiptResult, L as LinkDeviceResult, P as PendingCollectResult, D as DestinationsQuery, c as DestinationsResult, B as BalanceResult, E as EnrollmentBeginResult, d as EnrollmentVerifyResult, R as RecoveryBeginResult, e as RecoveryCompleteResult } from './types-Byp0p1r5.cjs';
2
- export { f as BalanceRow, g as DestinationGame, I as InvoError, h as InvoErrorInfo, i as InvoHooks, j as InvoRequestInfo, k as InvoResponseInfo, l as PendingCollectItem, m as Rail, V as VerificationMethod } from './types-Byp0p1r5.cjs';
1
+ import { C as ClientConfig, a as CallOptions, A as ApproveResult, b as ConfirmReceiptResult, L as LinkDeviceResult, P as PendingCollectResult, D as DestinationsQuery, c as DestinationsResult, B as BalanceResult, E as EnrollmentBeginResult, d as EnrollmentVerifyResult, R as RecoveryBeginResult, e as RecoveryCompleteResult } from './types-7Hl0Z1Ta.cjs';
2
+ export { f as BalanceRow, g as DestinationGame, I as InvoError, h as InvoErrorInfo, i as InvoHooks, j as InvoRequestInfo, k as InvoResponseInfo, l as PendingCollectItem, m as Rail, V as VerificationMethod } from './types-7Hl0Z1Ta.cjs';
3
3
 
4
4
  declare class InvoClient {
5
5
  private readonly http;
@@ -24,9 +24,19 @@ declare class InvoClient {
24
24
  approveSend(transactionId: string, opts?: CallOptions): Promise<ApproveResult>;
25
25
  /** Approve a TRANSFER with the player's passkey (returns the sender's claim code). */
26
26
  approveTransfer(transactionId: string, opts?: CallOptions): Promise<ApproveResult>;
27
- /** Recipient self-claims a SEND with their passkey. */
27
+ /**
28
+ * Recipient self-claims a SEND with their passkey.
29
+ *
30
+ * May throw a 409 with `err.isPhoneShareApprovalRequired` when the receiver phone is
31
+ * contested (the collecting identity isn't yet authorized for it). NOT a failure — the
32
+ * money is held and the phone owner is texted to approve. Show `err.message`
33
+ * (`err.phoneShareLast4` names the phone), then **retry this same call** once approved
34
+ * (it then succeeds idempotently); on denial/expiry the backend refunds the sender.
35
+ */
28
36
  confirmReceiptSend(transactionId: string, opts?: CallOptions): Promise<ConfirmReceiptResult>;
29
- /** Recipient self-claims a TRANSFER with their passkey. */
37
+ /** Recipient self-claims a TRANSFER with their passkey. Can throw the same phone-share
38
+ * 409 as {@link confirmReceiptSend} (`err.isPhoneShareApprovalRequired`) — handle it the
39
+ * same way: show `err.message`, retry after the phone owner approves. */
30
40
  confirmReceiptTransfer(transactionId: string, opts?: CallOptions): Promise<ConfirmReceiptResult>;
31
41
  /**
32
42
  * Interchangeable methods (§4.6): prove an *already-enrolled* method (e.g. the
package/dist/index.d.ts CHANGED
@@ -1,5 +1,5 @@
1
- import { C as ClientConfig, a as CallOptions, A as ApproveResult, b as ConfirmReceiptResult, L as LinkDeviceResult, P as PendingCollectResult, D as DestinationsQuery, c as DestinationsResult, B as BalanceResult, E as EnrollmentBeginResult, d as EnrollmentVerifyResult, R as RecoveryBeginResult, e as RecoveryCompleteResult } from './types-Byp0p1r5.js';
2
- export { f as BalanceRow, g as DestinationGame, I as InvoError, h as InvoErrorInfo, i as InvoHooks, j as InvoRequestInfo, k as InvoResponseInfo, l as PendingCollectItem, m as Rail, V as VerificationMethod } from './types-Byp0p1r5.js';
1
+ import { C as ClientConfig, a as CallOptions, A as ApproveResult, b as ConfirmReceiptResult, L as LinkDeviceResult, P as PendingCollectResult, D as DestinationsQuery, c as DestinationsResult, B as BalanceResult, E as EnrollmentBeginResult, d as EnrollmentVerifyResult, R as RecoveryBeginResult, e as RecoveryCompleteResult } from './types-7Hl0Z1Ta.js';
2
+ export { f as BalanceRow, g as DestinationGame, I as InvoError, h as InvoErrorInfo, i as InvoHooks, j as InvoRequestInfo, k as InvoResponseInfo, l as PendingCollectItem, m as Rail, V as VerificationMethod } from './types-7Hl0Z1Ta.js';
3
3
 
4
4
  declare class InvoClient {
5
5
  private readonly http;
@@ -24,9 +24,19 @@ declare class InvoClient {
24
24
  approveSend(transactionId: string, opts?: CallOptions): Promise<ApproveResult>;
25
25
  /** Approve a TRANSFER with the player's passkey (returns the sender's claim code). */
26
26
  approveTransfer(transactionId: string, opts?: CallOptions): Promise<ApproveResult>;
27
- /** Recipient self-claims a SEND with their passkey. */
27
+ /**
28
+ * Recipient self-claims a SEND with their passkey.
29
+ *
30
+ * May throw a 409 with `err.isPhoneShareApprovalRequired` when the receiver phone is
31
+ * contested (the collecting identity isn't yet authorized for it). NOT a failure — the
32
+ * money is held and the phone owner is texted to approve. Show `err.message`
33
+ * (`err.phoneShareLast4` names the phone), then **retry this same call** once approved
34
+ * (it then succeeds idempotently); on denial/expiry the backend refunds the sender.
35
+ */
28
36
  confirmReceiptSend(transactionId: string, opts?: CallOptions): Promise<ConfirmReceiptResult>;
29
- /** Recipient self-claims a TRANSFER with their passkey. */
37
+ /** Recipient self-claims a TRANSFER with their passkey. Can throw the same phone-share
38
+ * 409 as {@link confirmReceiptSend} (`err.isPhoneShareApprovalRequired`) — handle it the
39
+ * same way: show `err.message`, retry after the phone owner approves. */
30
40
  confirmReceiptTransfer(transactionId: string, opts?: CallOptions): Promise<ConfirmReceiptResult>;
31
41
  /**
32
42
  * Interchangeable methods (§4.6): prove an *already-enrolled* method (e.g. the
package/dist/index.js CHANGED
@@ -1,5 +1,5 @@
1
- import { assertSecureBaseUrl, Http, toDestinationsResult, InvoError } from './chunk-DJADKVYI.js';
2
- export { InvoError } from './chunk-DJADKVYI.js';
1
+ import { assertSecureBaseUrl, Http, toDestinationsResult, InvoError } from './chunk-SSTZKXPC.js';
2
+ export { InvoError } from './chunk-SSTZKXPC.js';
3
3
 
4
4
  // src/shared/webauthn.ts
5
5
  function malformedOptions(field) {
@@ -178,11 +178,21 @@ var InvoClient = class {
178
178
  async approveTransfer(transactionId, opts) {
179
179
  return this.approve("transfers", transactionId, opts);
180
180
  }
181
- /** Recipient self-claims a SEND with their passkey. */
181
+ /**
182
+ * Recipient self-claims a SEND with their passkey.
183
+ *
184
+ * May throw a 409 with `err.isPhoneShareApprovalRequired` when the receiver phone is
185
+ * contested (the collecting identity isn't yet authorized for it). NOT a failure — the
186
+ * money is held and the phone owner is texted to approve. Show `err.message`
187
+ * (`err.phoneShareLast4` names the phone), then **retry this same call** once approved
188
+ * (it then succeeds idempotently); on denial/expiry the backend refunds the sender.
189
+ */
182
190
  async confirmReceiptSend(transactionId, opts) {
183
191
  return this.confirmReceipt("send", transactionId, opts);
184
192
  }
185
- /** Recipient self-claims a TRANSFER with their passkey. */
193
+ /** Recipient self-claims a TRANSFER with their passkey. Can throw the same phone-share
194
+ * 409 as {@link confirmReceiptSend} (`err.isPhoneShareApprovalRequired`) — handle it the
195
+ * same way: show `err.message`, retry after the phone owner approves. */
186
196
  async confirmReceiptTransfer(transactionId, opts) {
187
197
  return this.confirmReceipt("transfers", transactionId, opts);
188
198
  }
package/dist/server.cjs CHANGED
@@ -74,12 +74,19 @@ var InvoError = class _InvoError extends Error {
74
74
  return this.code === "INSUFFICIENT_BALANCE" || "required_amount" in b || /insufficient[_ ]balance/i.test(this.message);
75
75
  }
76
76
  /**
77
- * True if the call needs phone-share approval before it can complete (409). Raised by
78
- * registration/token-mint and by claims when the phone already belongs to another INVO
79
- * account (same person, new email — expected, not a failure). The phone holder gets a
80
- * consent SMS; show "pending approval", then re-issue the identical call once approved
81
- * (poll `phoneShareStatus`, or use `phoneShareInitiate`/`phoneShareApprove` for the OTP
82
- * fallback). `phoneShareApprovalId` carries the id from the 409 body.
77
+ * True if the call needs phone-share approval before it can complete (409) — the
78
+ * collecting/registering identity isn't yet authorized for the phone on file. Raised by:
79
+ * - registration/token-mint (phone already on another INVO account), and
80
+ * - **claim + confirm-receipt** (`claimTransfer`/`claimCurrency`,
81
+ * `confirmReceiptSend`/`confirmReceiptTransfer`) — the receiver phone is contested,
82
+ * so INVO holds the money and texts the phone owner to approve.
83
+ *
84
+ * NOT a failure. Show `err.message` verbatim (the backend supplies the user-facing text;
85
+ * `phoneShareLast4` tells the UI which phone), keep the funds pending, and **retry the same
86
+ * call** once the phone owner approves — an approved consent makes the retry succeed
87
+ * idempotently. On denial/expiry the backend refunds the sender. (`phoneShareApprovalId`
88
+ * carries the id when the 409 came from the OTP-handshake path;
89
+ * `phoneShareInitiate`/`phoneShareApprove`/`phoneShareStatus` drive that fallback.)
83
90
  */
84
91
  get isPhoneShareApprovalRequired() {
85
92
  return this.code === "PHONE_SHARE_APPROVAL_REQUIRED";
@@ -89,6 +96,40 @@ var InvoError = class _InvoError extends Error {
89
96
  const v = this.bodyObject()["approval_id"];
90
97
  return typeof v === "string" && v ? v : void 0;
91
98
  }
99
+ /** Last 4 digits of the phone that must approve (`phone_last4`), for the UI message. */
100
+ get phoneShareLast4() {
101
+ const v = this.bodyObject()["phone_last4"];
102
+ return typeof v === "string" && v ? v : void 0;
103
+ }
104
+ /**
105
+ * True if a transfer/send initiate was blocked because it would move more than the player's
106
+ * NON-Steam balance to a non-Steam destination (`STEAM_VALUE_NON_TRANSFERABLE`, 409).
107
+ * Steam-purchased currency is locked to Steam titles. NOT retryable as-is — show
108
+ * `err.message` and cap the amount at `err.steamTransferableMax` (`err.steamOriginAmount`
109
+ * is the Steam-locked portion). Prevent it up front by hiding non-Steam destinations for a
110
+ * holder of Steam value (`DestinationGame.acceptsSteamOriginValue`).
111
+ */
112
+ get isSteamValueNonTransferable() {
113
+ return this.code === "STEAM_VALUE_NON_TRANSFERABLE";
114
+ }
115
+ /** Max the player can still send to this (non-Steam) destination (`transferable_max`), a decimal string. */
116
+ get steamTransferableMax() {
117
+ const v = this.bodyObject()["transferable_max"];
118
+ return typeof v === "string" && v ? v : void 0;
119
+ }
120
+ /** The Steam-purchased portion locked to Steam titles (`steam_origin_amount`), a decimal string. */
121
+ get steamOriginAmount() {
122
+ const v = this.bodyObject()["steam_origin_amount"];
123
+ return typeof v === "string" && v ? v : void 0;
124
+ }
125
+ /**
126
+ * True if a transfer/send initiate was blocked because it moves NON-Steam value INTO a
127
+ * Steam title (`NON_STEAM_VALUE_INTO_STEAM_BLOCKED`, 409). Show `err.message`; the fix is to
128
+ * pick a non-Steam destination (surfaced via `DestinationGame.acceptsSteamOriginValue`).
129
+ */
130
+ get isNonSteamValueIntoSteamBlocked() {
131
+ return this.code === "NON_STEAM_VALUE_INTO_STEAM_BLOCKED";
132
+ }
92
133
  /** True if the phone-share (phone, requesting_email) pair was already approved. */
93
134
  get isPhoneShareAlreadyApproved() {
94
135
  return this.code === "PHONE_SHARE_ALREADY_APPROVED";
@@ -350,6 +391,7 @@ function toDestinationGame(row) {
350
391
  currencySymbolUrl: s("currency_symbol_url"),
351
392
  minimumTransfer: String(row["minimum_transfer"] ?? ""),
352
393
  maximumTransfer: String(row["maximum_transfer"] ?? ""),
394
+ acceptsSteamOriginValue: row["accepts_steam_origin_value"] === true,
353
395
  raw: row
354
396
  };
355
397
  }
@@ -536,7 +578,7 @@ async function hmacHexSubtle(secret, message) {
536
578
  }
537
579
 
538
580
  // src/server.ts
539
- var DEFAULT_UA = "invonetwork-web-sdk/2.2.0 (+https://invo.network)";
581
+ var DEFAULT_UA = "invonetwork-web-sdk/2.4.0 (+https://invo.network)";
540
582
  var MAX_USD_AMOUNT = 999.99;
541
583
  var MAX_ITEM_PRICE = 999999.99;
542
584
  function invalidInput(label, value, why) {
@@ -750,7 +792,14 @@ var InvoServer = class {
750
792
  identityId: String(raw["identity_id"] ?? "")
751
793
  };
752
794
  }
753
- /** Initiate a cross-game currency SEND. Inspect result.verificationMethod. */
795
+ /**
796
+ * Initiate a cross-game currency SEND. Inspect result.verificationMethod.
797
+ *
798
+ * Steam titles: can throw a 409 `err.isSteamValueNonTransferable` (moving more than the
799
+ * player's non-Steam balance to a non-Steam destination — cap at `err.steamTransferableMax`)
800
+ * or `err.isNonSteamValueIntoSteamBlocked` (non-Steam value into a Steam title). Prevent both
801
+ * up front with `DestinationGame.acceptsSteamOriginValue`.
802
+ */
754
803
  async initiateSend(input, opts) {
755
804
  const raw = await this.http.post(
756
805
  "/api/currency-sends/initiate-send",
@@ -770,7 +819,9 @@ var InvoServer = class {
770
819
  );
771
820
  return this.toInitiateResult(raw);
772
821
  }
773
- /** Initiate a cross-game TRANSFER. Inspect result.verificationMethod. */
822
+ /** Initiate a cross-game TRANSFER. Inspect result.verificationMethod. Can throw the same
823
+ * Steam-policy 409s as {@link initiateSend} (`isSteamValueNonTransferable` /
824
+ * `isNonSteamValueIntoSteamBlocked`). */
774
825
  async initiateTransfer(input, opts) {
775
826
  const raw = await this.http.post(
776
827
  "/api/transfers/initiate-transfer",
package/dist/server.d.cts CHANGED
@@ -1,5 +1,5 @@
1
- import { I as InvoError, S as ServerConfig, a as CallOptions, n as PlayerToken, o as InitiateSendInput, p as InitiateResult, q as InitiateTransferInput, r as CreateCheckoutInput, s as CreateCheckoutResult, t as PurchaseInput, u as PurchaseResult, v as ConfirmPaymentResult, O as OrderDetailsResult, w as PurchaseItemInput, x as PurchaseItemResult, y as ItemHistoryQuery, z as ItemHistoryResult, F as ItemOrderQuery, G as PlayerBalanceQuery, H as PlayerBalanceResult, J as InboundPendingQuery, K as InboundPendingResult, M as LinkedIdentitiesQuery, N as LinkedIdentitiesResult, Q as SmsVerifyResult, T as ClaimTransferInput, U as ClaimResult, W as ClaimCurrencyInput, X as TransactionStatusResult, Y as GuardianApprovalStatusResult, Z as ServerDestinationsQuery, c as DestinationsResult, _ as PhoneShareContact, $ as PhoneShareInitiateResult, a0 as PhoneShareApproveInput, a1 as PhoneShareApproveResult, a2 as PhoneShareStatusResult } from './types-Byp0p1r5.cjs';
2
- export { a3 as CurrencyBalance, g as DestinationGame, a4 as InboundPendingItem, h as InvoErrorInfo, i as InvoHooks, j as InvoRequestInfo, k as InvoResponseInfo, a5 as LinkedIdentityEmail, m as Rail, V as VerificationMethod } from './types-Byp0p1r5.cjs';
1
+ import { I as InvoError, S as ServerConfig, a as CallOptions, n as PlayerToken, o as InitiateSendInput, p as InitiateResult, q as InitiateTransferInput, r as CreateCheckoutInput, s as CreateCheckoutResult, t as PurchaseInput, u as PurchaseResult, v as ConfirmPaymentResult, O as OrderDetailsResult, w as PurchaseItemInput, x as PurchaseItemResult, y as ItemHistoryQuery, z as ItemHistoryResult, F as ItemOrderQuery, G as PlayerBalanceQuery, H as PlayerBalanceResult, J as InboundPendingQuery, K as InboundPendingResult, M as LinkedIdentitiesQuery, N as LinkedIdentitiesResult, Q as SmsVerifyResult, T as ClaimTransferInput, U as ClaimResult, W as ClaimCurrencyInput, X as TransactionStatusResult, Y as GuardianApprovalStatusResult, Z as ServerDestinationsQuery, c as DestinationsResult, _ as PhoneShareContact, $ as PhoneShareInitiateResult, a0 as PhoneShareApproveInput, a1 as PhoneShareApproveResult, a2 as PhoneShareStatusResult } from './types-7Hl0Z1Ta.cjs';
2
+ export { a3 as CurrencyBalance, g as DestinationGame, a4 as InboundPendingItem, h as InvoErrorInfo, i as InvoHooks, j as InvoRequestInfo, k as InvoResponseInfo, a5 as LinkedIdentityEmail, m as Rail, V as VerificationMethod } from './types-7Hl0Z1Ta.cjs';
3
3
 
4
4
  interface VerifyWebhookOptions {
5
5
  /** Max age of the signed timestamp, in seconds. Default 300 (5 min). */
@@ -167,9 +167,18 @@ declare class InvoServer {
167
167
  playerEmail: string;
168
168
  playerPhone?: string;
169
169
  }, opts?: CallOptions): Promise<PlayerToken>;
170
- /** Initiate a cross-game currency SEND. Inspect result.verificationMethod. */
170
+ /**
171
+ * Initiate a cross-game currency SEND. Inspect result.verificationMethod.
172
+ *
173
+ * Steam titles: can throw a 409 `err.isSteamValueNonTransferable` (moving more than the
174
+ * player's non-Steam balance to a non-Steam destination — cap at `err.steamTransferableMax`)
175
+ * or `err.isNonSteamValueIntoSteamBlocked` (non-Steam value into a Steam title). Prevent both
176
+ * up front with `DestinationGame.acceptsSteamOriginValue`.
177
+ */
171
178
  initiateSend(input: InitiateSendInput, opts?: CallOptions): Promise<InitiateResult>;
172
- /** Initiate a cross-game TRANSFER. Inspect result.verificationMethod. */
179
+ /** Initiate a cross-game TRANSFER. Inspect result.verificationMethod. Can throw the same
180
+ * Steam-policy 409s as {@link initiateSend} (`isSteamValueNonTransferable` /
181
+ * `isNonSteamValueIntoSteamBlocked`). */
173
182
  initiateTransfer(input: InitiateTransferInput, opts?: CallOptions): Promise<InitiateResult>;
174
183
  /** Create a hosted checkout session (the recommended purchase path). Open the
175
184
  * returned checkoutUrl in a WebView/redirect or an iframe; the INVO-hosted page
package/dist/server.d.ts CHANGED
@@ -1,5 +1,5 @@
1
- import { I as InvoError, S as ServerConfig, a as CallOptions, n as PlayerToken, o as InitiateSendInput, p as InitiateResult, q as InitiateTransferInput, r as CreateCheckoutInput, s as CreateCheckoutResult, t as PurchaseInput, u as PurchaseResult, v as ConfirmPaymentResult, O as OrderDetailsResult, w as PurchaseItemInput, x as PurchaseItemResult, y as ItemHistoryQuery, z as ItemHistoryResult, F as ItemOrderQuery, G as PlayerBalanceQuery, H as PlayerBalanceResult, J as InboundPendingQuery, K as InboundPendingResult, M as LinkedIdentitiesQuery, N as LinkedIdentitiesResult, Q as SmsVerifyResult, T as ClaimTransferInput, U as ClaimResult, W as ClaimCurrencyInput, X as TransactionStatusResult, Y as GuardianApprovalStatusResult, Z as ServerDestinationsQuery, c as DestinationsResult, _ as PhoneShareContact, $ as PhoneShareInitiateResult, a0 as PhoneShareApproveInput, a1 as PhoneShareApproveResult, a2 as PhoneShareStatusResult } from './types-Byp0p1r5.js';
2
- export { a3 as CurrencyBalance, g as DestinationGame, a4 as InboundPendingItem, h as InvoErrorInfo, i as InvoHooks, j as InvoRequestInfo, k as InvoResponseInfo, a5 as LinkedIdentityEmail, m as Rail, V as VerificationMethod } from './types-Byp0p1r5.js';
1
+ import { I as InvoError, S as ServerConfig, a as CallOptions, n as PlayerToken, o as InitiateSendInput, p as InitiateResult, q as InitiateTransferInput, r as CreateCheckoutInput, s as CreateCheckoutResult, t as PurchaseInput, u as PurchaseResult, v as ConfirmPaymentResult, O as OrderDetailsResult, w as PurchaseItemInput, x as PurchaseItemResult, y as ItemHistoryQuery, z as ItemHistoryResult, F as ItemOrderQuery, G as PlayerBalanceQuery, H as PlayerBalanceResult, J as InboundPendingQuery, K as InboundPendingResult, M as LinkedIdentitiesQuery, N as LinkedIdentitiesResult, Q as SmsVerifyResult, T as ClaimTransferInput, U as ClaimResult, W as ClaimCurrencyInput, X as TransactionStatusResult, Y as GuardianApprovalStatusResult, Z as ServerDestinationsQuery, c as DestinationsResult, _ as PhoneShareContact, $ as PhoneShareInitiateResult, a0 as PhoneShareApproveInput, a1 as PhoneShareApproveResult, a2 as PhoneShareStatusResult } from './types-7Hl0Z1Ta.js';
2
+ export { a3 as CurrencyBalance, g as DestinationGame, a4 as InboundPendingItem, h as InvoErrorInfo, i as InvoHooks, j as InvoRequestInfo, k as InvoResponseInfo, a5 as LinkedIdentityEmail, m as Rail, V as VerificationMethod } from './types-7Hl0Z1Ta.js';
3
3
 
4
4
  interface VerifyWebhookOptions {
5
5
  /** Max age of the signed timestamp, in seconds. Default 300 (5 min). */
@@ -167,9 +167,18 @@ declare class InvoServer {
167
167
  playerEmail: string;
168
168
  playerPhone?: string;
169
169
  }, opts?: CallOptions): Promise<PlayerToken>;
170
- /** Initiate a cross-game currency SEND. Inspect result.verificationMethod. */
170
+ /**
171
+ * Initiate a cross-game currency SEND. Inspect result.verificationMethod.
172
+ *
173
+ * Steam titles: can throw a 409 `err.isSteamValueNonTransferable` (moving more than the
174
+ * player's non-Steam balance to a non-Steam destination — cap at `err.steamTransferableMax`)
175
+ * or `err.isNonSteamValueIntoSteamBlocked` (non-Steam value into a Steam title). Prevent both
176
+ * up front with `DestinationGame.acceptsSteamOriginValue`.
177
+ */
171
178
  initiateSend(input: InitiateSendInput, opts?: CallOptions): Promise<InitiateResult>;
172
- /** Initiate a cross-game TRANSFER. Inspect result.verificationMethod. */
179
+ /** Initiate a cross-game TRANSFER. Inspect result.verificationMethod. Can throw the same
180
+ * Steam-policy 409s as {@link initiateSend} (`isSteamValueNonTransferable` /
181
+ * `isNonSteamValueIntoSteamBlocked`). */
173
182
  initiateTransfer(input: InitiateTransferInput, opts?: CallOptions): Promise<InitiateResult>;
174
183
  /** Create a hosted checkout session (the recommended purchase path). Open the
175
184
  * returned checkoutUrl in a WebView/redirect or an iframe; the INVO-hosted page
package/dist/server.js CHANGED
@@ -1,5 +1,5 @@
1
- import { InvoError, assertSecureBaseUrl, Http, toDestinationsResult } from './chunk-DJADKVYI.js';
2
- export { InvoError } from './chunk-DJADKVYI.js';
1
+ import { InvoError, assertSecureBaseUrl, Http, toDestinationsResult } from './chunk-SSTZKXPC.js';
2
+ export { InvoError } from './chunk-SSTZKXPC.js';
3
3
  import { createHmac, timingSafeEqual } from 'crypto';
4
4
 
5
5
  var DEFAULT_TOLERANCE_SEC = 300;
@@ -167,7 +167,7 @@ async function hmacHexSubtle(secret, message) {
167
167
  }
168
168
 
169
169
  // src/server.ts
170
- var DEFAULT_UA = "invonetwork-web-sdk/2.2.0 (+https://invo.network)";
170
+ var DEFAULT_UA = "invonetwork-web-sdk/2.4.0 (+https://invo.network)";
171
171
  var MAX_USD_AMOUNT = 999.99;
172
172
  var MAX_ITEM_PRICE = 999999.99;
173
173
  function invalidInput(label, value, why) {
@@ -381,7 +381,14 @@ var InvoServer = class {
381
381
  identityId: String(raw["identity_id"] ?? "")
382
382
  };
383
383
  }
384
- /** Initiate a cross-game currency SEND. Inspect result.verificationMethod. */
384
+ /**
385
+ * Initiate a cross-game currency SEND. Inspect result.verificationMethod.
386
+ *
387
+ * Steam titles: can throw a 409 `err.isSteamValueNonTransferable` (moving more than the
388
+ * player's non-Steam balance to a non-Steam destination — cap at `err.steamTransferableMax`)
389
+ * or `err.isNonSteamValueIntoSteamBlocked` (non-Steam value into a Steam title). Prevent both
390
+ * up front with `DestinationGame.acceptsSteamOriginValue`.
391
+ */
385
392
  async initiateSend(input, opts) {
386
393
  const raw = await this.http.post(
387
394
  "/api/currency-sends/initiate-send",
@@ -401,7 +408,9 @@ var InvoServer = class {
401
408
  );
402
409
  return this.toInitiateResult(raw);
403
410
  }
404
- /** Initiate a cross-game TRANSFER. Inspect result.verificationMethod. */
411
+ /** Initiate a cross-game TRANSFER. Inspect result.verificationMethod. Can throw the same
412
+ * Steam-policy 409s as {@link initiateSend} (`isSteamValueNonTransferable` /
413
+ * `isNonSteamValueIntoSteamBlocked`). */
405
414
  async initiateTransfer(input, opts) {
406
415
  const raw = await this.http.post(
407
416
  "/api/transfers/initiate-transfer",
@@ -62,16 +62,44 @@ declare class InvoError extends Error {
62
62
  */
63
63
  get isInsufficientBalance(): boolean;
64
64
  /**
65
- * True if the call needs phone-share approval before it can complete (409). Raised by
66
- * registration/token-mint and by claims when the phone already belongs to another INVO
67
- * account (same person, new email — expected, not a failure). The phone holder gets a
68
- * consent SMS; show "pending approval", then re-issue the identical call once approved
69
- * (poll `phoneShareStatus`, or use `phoneShareInitiate`/`phoneShareApprove` for the OTP
70
- * fallback). `phoneShareApprovalId` carries the id from the 409 body.
65
+ * True if the call needs phone-share approval before it can complete (409) — the
66
+ * collecting/registering identity isn't yet authorized for the phone on file. Raised by:
67
+ * - registration/token-mint (phone already on another INVO account), and
68
+ * - **claim + confirm-receipt** (`claimTransfer`/`claimCurrency`,
69
+ * `confirmReceiptSend`/`confirmReceiptTransfer`) — the receiver phone is contested,
70
+ * so INVO holds the money and texts the phone owner to approve.
71
+ *
72
+ * NOT a failure. Show `err.message` verbatim (the backend supplies the user-facing text;
73
+ * `phoneShareLast4` tells the UI which phone), keep the funds pending, and **retry the same
74
+ * call** once the phone owner approves — an approved consent makes the retry succeed
75
+ * idempotently. On denial/expiry the backend refunds the sender. (`phoneShareApprovalId`
76
+ * carries the id when the 409 came from the OTP-handshake path;
77
+ * `phoneShareInitiate`/`phoneShareApprove`/`phoneShareStatus` drive that fallback.)
71
78
  */
72
79
  get isPhoneShareApprovalRequired(): boolean;
73
80
  /** The `approval_id` from a phone-share 409 body, for `phoneShareApprove`. */
74
81
  get phoneShareApprovalId(): string | undefined;
82
+ /** Last 4 digits of the phone that must approve (`phone_last4`), for the UI message. */
83
+ get phoneShareLast4(): string | undefined;
84
+ /**
85
+ * True if a transfer/send initiate was blocked because it would move more than the player's
86
+ * NON-Steam balance to a non-Steam destination (`STEAM_VALUE_NON_TRANSFERABLE`, 409).
87
+ * Steam-purchased currency is locked to Steam titles. NOT retryable as-is — show
88
+ * `err.message` and cap the amount at `err.steamTransferableMax` (`err.steamOriginAmount`
89
+ * is the Steam-locked portion). Prevent it up front by hiding non-Steam destinations for a
90
+ * holder of Steam value (`DestinationGame.acceptsSteamOriginValue`).
91
+ */
92
+ get isSteamValueNonTransferable(): boolean;
93
+ /** Max the player can still send to this (non-Steam) destination (`transferable_max`), a decimal string. */
94
+ get steamTransferableMax(): string | undefined;
95
+ /** The Steam-purchased portion locked to Steam titles (`steam_origin_amount`), a decimal string. */
96
+ get steamOriginAmount(): string | undefined;
97
+ /**
98
+ * True if a transfer/send initiate was blocked because it moves NON-Steam value INTO a
99
+ * Steam title (`NON_STEAM_VALUE_INTO_STEAM_BLOCKED`, 409). Show `err.message`; the fix is to
100
+ * pick a non-Steam destination (surfaced via `DestinationGame.acceptsSteamOriginValue`).
101
+ */
102
+ get isNonSteamValueIntoSteamBlocked(): boolean;
75
103
  /** True if the phone-share (phone, requesting_email) pair was already approved. */
76
104
  get isPhoneShareAlreadyApproved(): boolean;
77
105
  /** True if an idempotency-keyed request was a duplicate (item purchase → 409). */
@@ -474,6 +502,10 @@ interface DestinationGame {
474
502
  /** Limits are decimal strings. */
475
503
  minimumTransfer: string;
476
504
  maximumTransfer: string;
505
+ /** True for Steam-distributed titles — they accept Steam-purchased (Steam-origin) value.
506
+ * Disable non-Steam destinations for a player holding Steam value so they never hit the
507
+ * `STEAM_VALUE_NON_TRANSFERABLE` 409. Defaults to `false` when the backend omits it. */
508
+ acceptsSteamOriginValue: boolean;
477
509
  raw: Record<string, unknown>;
478
510
  }
479
511
  interface DestinationsResult {
@@ -62,16 +62,44 @@ declare class InvoError extends Error {
62
62
  */
63
63
  get isInsufficientBalance(): boolean;
64
64
  /**
65
- * True if the call needs phone-share approval before it can complete (409). Raised by
66
- * registration/token-mint and by claims when the phone already belongs to another INVO
67
- * account (same person, new email — expected, not a failure). The phone holder gets a
68
- * consent SMS; show "pending approval", then re-issue the identical call once approved
69
- * (poll `phoneShareStatus`, or use `phoneShareInitiate`/`phoneShareApprove` for the OTP
70
- * fallback). `phoneShareApprovalId` carries the id from the 409 body.
65
+ * True if the call needs phone-share approval before it can complete (409) — the
66
+ * collecting/registering identity isn't yet authorized for the phone on file. Raised by:
67
+ * - registration/token-mint (phone already on another INVO account), and
68
+ * - **claim + confirm-receipt** (`claimTransfer`/`claimCurrency`,
69
+ * `confirmReceiptSend`/`confirmReceiptTransfer`) — the receiver phone is contested,
70
+ * so INVO holds the money and texts the phone owner to approve.
71
+ *
72
+ * NOT a failure. Show `err.message` verbatim (the backend supplies the user-facing text;
73
+ * `phoneShareLast4` tells the UI which phone), keep the funds pending, and **retry the same
74
+ * call** once the phone owner approves — an approved consent makes the retry succeed
75
+ * idempotently. On denial/expiry the backend refunds the sender. (`phoneShareApprovalId`
76
+ * carries the id when the 409 came from the OTP-handshake path;
77
+ * `phoneShareInitiate`/`phoneShareApprove`/`phoneShareStatus` drive that fallback.)
71
78
  */
72
79
  get isPhoneShareApprovalRequired(): boolean;
73
80
  /** The `approval_id` from a phone-share 409 body, for `phoneShareApprove`. */
74
81
  get phoneShareApprovalId(): string | undefined;
82
+ /** Last 4 digits of the phone that must approve (`phone_last4`), for the UI message. */
83
+ get phoneShareLast4(): string | undefined;
84
+ /**
85
+ * True if a transfer/send initiate was blocked because it would move more than the player's
86
+ * NON-Steam balance to a non-Steam destination (`STEAM_VALUE_NON_TRANSFERABLE`, 409).
87
+ * Steam-purchased currency is locked to Steam titles. NOT retryable as-is — show
88
+ * `err.message` and cap the amount at `err.steamTransferableMax` (`err.steamOriginAmount`
89
+ * is the Steam-locked portion). Prevent it up front by hiding non-Steam destinations for a
90
+ * holder of Steam value (`DestinationGame.acceptsSteamOriginValue`).
91
+ */
92
+ get isSteamValueNonTransferable(): boolean;
93
+ /** Max the player can still send to this (non-Steam) destination (`transferable_max`), a decimal string. */
94
+ get steamTransferableMax(): string | undefined;
95
+ /** The Steam-purchased portion locked to Steam titles (`steam_origin_amount`), a decimal string. */
96
+ get steamOriginAmount(): string | undefined;
97
+ /**
98
+ * True if a transfer/send initiate was blocked because it moves NON-Steam value INTO a
99
+ * Steam title (`NON_STEAM_VALUE_INTO_STEAM_BLOCKED`, 409). Show `err.message`; the fix is to
100
+ * pick a non-Steam destination (surfaced via `DestinationGame.acceptsSteamOriginValue`).
101
+ */
102
+ get isNonSteamValueIntoSteamBlocked(): boolean;
75
103
  /** True if the phone-share (phone, requesting_email) pair was already approved. */
76
104
  get isPhoneShareAlreadyApproved(): boolean;
77
105
  /** True if an idempotency-keyed request was a duplicate (item purchase → 409). */
@@ -474,6 +502,10 @@ interface DestinationGame {
474
502
  /** Limits are decimal strings. */
475
503
  minimumTransfer: string;
476
504
  maximumTransfer: string;
505
+ /** True for Steam-distributed titles — they accept Steam-purchased (Steam-origin) value.
506
+ * Disable non-Steam destinations for a player holding Steam value so they never hit the
507
+ * `STEAM_VALUE_NON_TRANSFERABLE` 409. Defaults to `false` when the backend omits it. */
508
+ acceptsSteamOriginValue: boolean;
477
509
  raw: Record<string, unknown>;
478
510
  }
479
511
  interface DestinationsResult {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@invonetwork/web-sdk",
3
- "version": "2.2.0",
3
+ "version": "2.4.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,