@invonetwork/web-sdk 2.5.0 → 2.5.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -4,6 +4,42 @@ 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.5.1] — 2026-07-20
8
+
9
+ Hardening patch from a second, independent post-release audit (correctness vs the backend
10
+ blueprint + security red-team) of the 2.5.0 Platform Commerce feature. No API breaks.
11
+
12
+ ### Fixed
13
+ - **Card-confirm script loader could hang forever on retry.** After a transient CDN failure
14
+ (or a pre-existing processor `<script>` tag whose events already fired), the next
15
+ `mountCardPayment`/`confirmCardPayment` attached listeners to a dead tag and never settled —
16
+ checkout silently dead until page reload. The loader now removes failed tags and polls
17
+ (bounded, 10s) when a tag pre-exists.
18
+ - **Orphaned card element on submit-lookup failure.** `confirmCardPayment` now destroys the
19
+ mounted Payment Element before rethrowing when the `submit` selector can't be resolved
20
+ (previously a retry stacked a second live card iframe).
21
+ - **Billing-address validation errors no longer echo the submitted values** (cardholder PII
22
+ could otherwise land in logs/Sentry); optional billing fields (`name`/`line2`/`state`) are
23
+ now type-checked.
24
+ - **`playerPhone` on `platformCommerce.purchase` is now E.164-validated** — this endpoint can
25
+ create the player identity, so a national-format phone must never reach the wire.
26
+ - **`err.isInsufficientBalance` now also classifies the zero-balance 400** ("Player has no
27
+ balance in this tenant", which carries only `current_balance`).
28
+ - **Breaker-open 503 keeps its human message** (`err.code === "service_unavailable"`, message
29
+ no longer collapses to the bare token).
30
+ - **Webhook types:** `platform_commerce.refunded` `player_email` is nullable + `identity_id`
31
+ added; (2.5.0 already made card-leg `total_price` optional on `purchased`).
32
+ - **Refund result surfaces `newBalance`** (balance leg) **and `processorRefundId`** (card leg)
33
+ instead of leaving them `raw`-only.
34
+ - Platform-commerce error tests now assert the REAL backend envelopes
35
+ (`{status,error_code,message}` / bare `{message}`), not idealized shapes.
36
+
37
+ ### Docs
38
+ - Card-leg lost-response caveat on `purchase` (duplicate 409 can strand a `clientSecret`-less
39
+ pending order — reconcile via webhook/`getStatus`, retry with a NEW `clientRequestId`).
40
+ - `confirmCardPayment`: bank-redirect return-leg guidance + remount-after-decline note;
41
+ `CardPaymentResult.raw` log-redaction note.
42
+
7
43
  ## [2.5.0] — 2026-07-20
8
44
 
9
45
  **Platform Commerce (ecommerce).** A new flow for **platform** tenants (non-game apps: vertical
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.5.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.5.0** adds **Platform Commerce** (ecommerce) — a platform tenant selling items funded by balance **or** card, with `invo.platformCommerce.purchase/getStatus/refund` (server), `invo.platformCommerce.confirmCardPayment` (browser), and the `platform_commerce.*` webhooks; **2.4.0** adds Steam transfer-policy handling (`isSteamValueNonTransferable`/`isNonSteamValueIntoSteamBlocked` + `DestinationGame.acceptsSteamOriginValue`); **2.3.0** surfaces the claim-time phone-share `409` on `confirmReceipt*`/`claim*` (+ `err.phoneShareLast4`). Full history in the [CHANGELOG](CHANGELOG.md).
5
+ > **Status:** `v2.5.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. Recent highlights: **2.5.1** hardens 2.5.0 from a second independent audit (card-confirm loader retry fix, PII-free validation errors, E.164 on `platformCommerce` phone, refund `newBalance`/`processorRefundId`); **2.5.0** adds **Platform Commerce** (ecommerce) — a platform tenant selling items funded by balance **or** card, with `invo.platformCommerce.purchase/getStatus/refund` (server), `invo.platformCommerce.confirmCardPayment` (browser), and the `platform_commerce.*` webhooks; **2.4.0** adds Steam transfer-policy handling (`isSteamValueNonTransferable`/`isNonSteamValueIntoSteamBlocked` + `DestinationGame.acceptsSteamOriginValue`); **2.3.0** surfaces the claim-time phone-share `409` on `confirmReceipt*`/`claim*` (+ `err.phoneShareLast4`). 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
@@ -67,7 +67,9 @@ var InvoError = class _InvoError extends Error {
67
67
  get isInsufficientBalance() {
68
68
  if (this.status !== 400) return false;
69
69
  const b = this.bodyObject();
70
- return this.code === "INSUFFICIENT_BALANCE" || "required_amount" in b || /insufficient[_ ]balance/i.test(this.message);
70
+ return this.code === "INSUFFICIENT_BALANCE" || "required_amount" in b || // Zero-balance variant ("Player has no balance in this tenant") carries only
71
+ // `current_balance` — same top-up condition, so classify it the same way.
72
+ "current_balance" in b || /insufficient[_ ]balance/i.test(this.message);
71
73
  }
72
74
  /**
73
75
  * True if the call needs phone-share approval before it can complete (409) — the
@@ -182,10 +184,11 @@ function errorFromResponse(status, body, requestId) {
182
184
  else if (typeof b["error_code"] === "string") code = b["error_code"];
183
185
  if (typeof b["error"] === "string") message = b["error"];
184
186
  else if (typeof b["message"] === "string") message = b["message"];
185
- if (!code && typeof b["error"] === "string" && /^(flow_paused|spending_limit_exceeded|receiver_not_enrolled_use_claim_code|no_channel_on_file|rate_limited)$/.test(
187
+ if (!code && typeof b["error"] === "string" && /^(flow_paused|spending_limit_exceeded|receiver_not_enrolled_use_claim_code|no_channel_on_file|rate_limited|service_unavailable)$/.test(
186
188
  b["error"]
187
189
  )) {
188
190
  code = b["error"];
191
+ if (typeof b["message"] === "string" && b["message"]) message = b["message"];
189
192
  }
190
193
  } else if (typeof body === "string" && body.trim()) {
191
194
  message = body;
@@ -438,5 +441,5 @@ function toDestinationsResult(raw, direction) {
438
441
  }
439
442
 
440
443
  export { Http, InvoError, assertSecureBaseUrl, toDestinationsResult };
441
- //# sourceMappingURL=chunk-ZKYUSYK5.js.map
442
- //# sourceMappingURL=chunk-ZKYUSYK5.js.map
444
+ //# sourceMappingURL=chunk-5X3ESHJR.js.map
445
+ //# sourceMappingURL=chunk-5X3ESHJR.js.map
package/dist/index.cjs CHANGED
@@ -69,7 +69,9 @@ var InvoError = class _InvoError extends Error {
69
69
  get isInsufficientBalance() {
70
70
  if (this.status !== 400) return false;
71
71
  const b = this.bodyObject();
72
- return this.code === "INSUFFICIENT_BALANCE" || "required_amount" in b || /insufficient[_ ]balance/i.test(this.message);
72
+ return this.code === "INSUFFICIENT_BALANCE" || "required_amount" in b || // Zero-balance variant ("Player has no balance in this tenant") carries only
73
+ // `current_balance` — same top-up condition, so classify it the same way.
74
+ "current_balance" in b || /insufficient[_ ]balance/i.test(this.message);
73
75
  }
74
76
  /**
75
77
  * True if the call needs phone-share approval before it can complete (409) — the
@@ -184,10 +186,11 @@ function errorFromResponse(status, body, requestId) {
184
186
  else if (typeof b["error_code"] === "string") code = b["error_code"];
185
187
  if (typeof b["error"] === "string") message = b["error"];
186
188
  else if (typeof b["message"] === "string") message = b["message"];
187
- if (!code && typeof b["error"] === "string" && /^(flow_paused|spending_limit_exceeded|receiver_not_enrolled_use_claim_code|no_channel_on_file|rate_limited)$/.test(
189
+ if (!code && typeof b["error"] === "string" && /^(flow_paused|spending_limit_exceeded|receiver_not_enrolled_use_claim_code|no_channel_on_file|rate_limited|service_unavailable)$/.test(
188
190
  b["error"]
189
191
  )) {
190
192
  code = b["error"];
193
+ if (typeof b["message"] === "string" && b["message"]) message = b["message"];
191
194
  }
192
195
  } else if (typeof body === "string" && body.trim()) {
193
196
  message = body;
@@ -559,6 +562,7 @@ function toBalanceRow(row) {
559
562
  };
560
563
  }
561
564
  var PROCESSOR_SRC = "https://js.stripe.com/v3";
565
+ var PROCESSOR_LOAD_TIMEOUT_MS = 1e4;
562
566
  var processorScriptLoad;
563
567
  function loadProcessorScript() {
564
568
  if (typeof document === "undefined" || typeof window === "undefined") {
@@ -573,17 +577,7 @@ function loadProcessorScript() {
573
577
  if (window.Stripe) return Promise.resolve();
574
578
  if (processorScriptLoad) return processorScriptLoad;
575
579
  processorScriptLoad = new Promise((resolve, reject) => {
576
- const existing = document.querySelector(
577
- `script[src="${PROCESSOR_SRC}"]`
578
- );
579
- const script = existing ?? document.createElement("script");
580
- if (!existing) {
581
- script.src = PROCESSOR_SRC;
582
- script.async = true;
583
- document.head.appendChild(script);
584
- }
585
- script.addEventListener("load", () => resolve());
586
- script.addEventListener("error", () => {
580
+ const fail = () => {
587
581
  processorScriptLoad = void 0;
588
582
  reject(
589
583
  new InvoError({
@@ -592,7 +586,33 @@ function loadProcessorScript() {
592
586
  status: 0
593
587
  })
594
588
  );
589
+ };
590
+ const existing = document.querySelector(
591
+ `script[src="${PROCESSOR_SRC}"]`
592
+ );
593
+ if (existing) {
594
+ const started = Date.now();
595
+ const poll = setInterval(() => {
596
+ if (window.Stripe) {
597
+ clearInterval(poll);
598
+ resolve();
599
+ } else if (Date.now() - started > PROCESSOR_LOAD_TIMEOUT_MS) {
600
+ clearInterval(poll);
601
+ existing.remove();
602
+ fail();
603
+ }
604
+ }, 100);
605
+ return;
606
+ }
607
+ const script = document.createElement("script");
608
+ script.src = PROCESSOR_SRC;
609
+ script.async = true;
610
+ script.addEventListener("load", () => resolve());
611
+ script.addEventListener("error", () => {
612
+ script.remove();
613
+ fail();
595
614
  });
615
+ document.head.appendChild(script);
596
616
  });
597
617
  return processorScriptLoad;
598
618
  }
@@ -712,10 +732,25 @@ var PlatformCommerceClient = class {
712
732
  * when the payment is confirmed via a submit trigger — either `opts.submit` (your Pay
713
733
  * button, selector or element) or a minimal button the SDK renders inside `mount`. For
714
734
  * full control over the button, prefer {@link mountCardPayment}.
735
+ *
736
+ * Two flow notes:
737
+ * - **Bank redirect:** with `redirect: "if_required"` most cards confirm in-page, but a
738
+ * bank can force a full redirect — the browser then navigates away (this promise never
739
+ * settles) and returns to `returnUrl`. On that return page, reconcile via your server's
740
+ * `platformCommerce.getStatus(orderId)` / the `platform_commerce.purchased` webhook.
741
+ * - **Decline / "failed":** the element is torn down when this resolves — to let the user
742
+ * retry after a decline, call `confirmCardPayment` (or `mountCardPayment`) again to
743
+ * remount.
715
744
  */
716
745
  async confirmCardPayment(clientSecret, opts) {
717
746
  const session = await this.mountCardPayment(clientSecret, opts);
718
- const trigger = resolveSubmit(opts);
747
+ let trigger;
748
+ try {
749
+ trigger = resolveSubmit(opts);
750
+ } catch (e) {
751
+ session.destroy();
752
+ throw e;
753
+ }
719
754
  return new Promise((resolve, reject) => {
720
755
  const finish = (settle) => {
721
756
  if (trigger.created) trigger.el.remove();
package/dist/index.d.cts CHANGED
@@ -1,5 +1,5 @@
1
- import { M as MountCardPaymentOptions, C as CardPaymentSession, a as ConfirmCardPaymentOptions, b as CardPaymentResult, c as ClientConfig, d as CallOptions, A as ApproveResult, e as ConfirmReceiptResult, L as LinkDeviceResult, P as PendingCollectResult, D as DestinationsQuery, f as DestinationsResult, B as BalanceResult, E as EnrollmentBeginResult, g as EnrollmentVerifyResult, R as RecoveryBeginResult, h as RecoveryCompleteResult } from './types-g1xz5GDk.cjs';
2
- export { i as BalanceRow, j as CardPaymentStatus, k as DestinationGame, I as InvoCardConfirmResponse, l as InvoCardElement, m as InvoCardElements, n as InvoCardProcessor, o as InvoError, p as InvoErrorInfo, q as InvoHooks, r as InvoRequestInfo, s as InvoResponseInfo, t as PendingCollectItem, u as Rail, V as VerificationMethod } from './types-g1xz5GDk.cjs';
1
+ import { M as MountCardPaymentOptions, C as CardPaymentSession, a as ConfirmCardPaymentOptions, b as CardPaymentResult, c as ClientConfig, d as CallOptions, A as ApproveResult, e as ConfirmReceiptResult, L as LinkDeviceResult, P as PendingCollectResult, D as DestinationsQuery, f as DestinationsResult, B as BalanceResult, E as EnrollmentBeginResult, g as EnrollmentVerifyResult, R as RecoveryBeginResult, h as RecoveryCompleteResult } from './types-BHvVjdMV.cjs';
2
+ export { i as BalanceRow, j as CardPaymentStatus, k as DestinationGame, I as InvoCardConfirmResponse, l as InvoCardElement, m as InvoCardElements, n as InvoCardProcessor, o as InvoError, p as InvoErrorInfo, q as InvoHooks, r as InvoRequestInfo, s as InvoResponseInfo, t as PendingCollectItem, u as Rail, V as VerificationMethod } from './types-BHvVjdMV.cjs';
3
3
 
4
4
  /**
5
5
  * Platform Commerce card confirmation (browser side). The server (`InvoServer.
@@ -31,6 +31,15 @@ declare class PlatformCommerceClient {
31
31
  * when the payment is confirmed via a submit trigger — either `opts.submit` (your Pay
32
32
  * button, selector or element) or a minimal button the SDK renders inside `mount`. For
33
33
  * full control over the button, prefer {@link mountCardPayment}.
34
+ *
35
+ * Two flow notes:
36
+ * - **Bank redirect:** with `redirect: "if_required"` most cards confirm in-page, but a
37
+ * bank can force a full redirect — the browser then navigates away (this promise never
38
+ * settles) and returns to `returnUrl`. On that return page, reconcile via your server's
39
+ * `platformCommerce.getStatus(orderId)` / the `platform_commerce.purchased` webhook.
40
+ * - **Decline / "failed":** the element is torn down when this resolves — to let the user
41
+ * retry after a decline, call `confirmCardPayment` (or `mountCardPayment`) again to
42
+ * remount.
34
43
  */
35
44
  confirmCardPayment(clientSecret: string, opts: ConfirmCardPaymentOptions): Promise<CardPaymentResult>;
36
45
  }
package/dist/index.d.ts CHANGED
@@ -1,5 +1,5 @@
1
- import { M as MountCardPaymentOptions, C as CardPaymentSession, a as ConfirmCardPaymentOptions, b as CardPaymentResult, c as ClientConfig, d as CallOptions, A as ApproveResult, e as ConfirmReceiptResult, L as LinkDeviceResult, P as PendingCollectResult, D as DestinationsQuery, f as DestinationsResult, B as BalanceResult, E as EnrollmentBeginResult, g as EnrollmentVerifyResult, R as RecoveryBeginResult, h as RecoveryCompleteResult } from './types-g1xz5GDk.js';
2
- export { i as BalanceRow, j as CardPaymentStatus, k as DestinationGame, I as InvoCardConfirmResponse, l as InvoCardElement, m as InvoCardElements, n as InvoCardProcessor, o as InvoError, p as InvoErrorInfo, q as InvoHooks, r as InvoRequestInfo, s as InvoResponseInfo, t as PendingCollectItem, u as Rail, V as VerificationMethod } from './types-g1xz5GDk.js';
1
+ import { M as MountCardPaymentOptions, C as CardPaymentSession, a as ConfirmCardPaymentOptions, b as CardPaymentResult, c as ClientConfig, d as CallOptions, A as ApproveResult, e as ConfirmReceiptResult, L as LinkDeviceResult, P as PendingCollectResult, D as DestinationsQuery, f as DestinationsResult, B as BalanceResult, E as EnrollmentBeginResult, g as EnrollmentVerifyResult, R as RecoveryBeginResult, h as RecoveryCompleteResult } from './types-BHvVjdMV.js';
2
+ export { i as BalanceRow, j as CardPaymentStatus, k as DestinationGame, I as InvoCardConfirmResponse, l as InvoCardElement, m as InvoCardElements, n as InvoCardProcessor, o as InvoError, p as InvoErrorInfo, q as InvoHooks, r as InvoRequestInfo, s as InvoResponseInfo, t as PendingCollectItem, u as Rail, V as VerificationMethod } from './types-BHvVjdMV.js';
3
3
 
4
4
  /**
5
5
  * Platform Commerce card confirmation (browser side). The server (`InvoServer.
@@ -31,6 +31,15 @@ declare class PlatformCommerceClient {
31
31
  * when the payment is confirmed via a submit trigger — either `opts.submit` (your Pay
32
32
  * button, selector or element) or a minimal button the SDK renders inside `mount`. For
33
33
  * full control over the button, prefer {@link mountCardPayment}.
34
+ *
35
+ * Two flow notes:
36
+ * - **Bank redirect:** with `redirect: "if_required"` most cards confirm in-page, but a
37
+ * bank can force a full redirect — the browser then navigates away (this promise never
38
+ * settles) and returns to `returnUrl`. On that return page, reconcile via your server's
39
+ * `platformCommerce.getStatus(orderId)` / the `platform_commerce.purchased` webhook.
40
+ * - **Decline / "failed":** the element is torn down when this resolves — to let the user
41
+ * retry after a decline, call `confirmCardPayment` (or `mountCardPayment`) again to
42
+ * remount.
34
43
  */
35
44
  confirmCardPayment(clientSecret: string, opts: ConfirmCardPaymentOptions): Promise<CardPaymentResult>;
36
45
  }
package/dist/index.js CHANGED
@@ -1,5 +1,5 @@
1
- import { InvoError, assertSecureBaseUrl, Http, toDestinationsResult } from './chunk-ZKYUSYK5.js';
2
- export { InvoError } from './chunk-ZKYUSYK5.js';
1
+ import { InvoError, assertSecureBaseUrl, Http, toDestinationsResult } from './chunk-5X3ESHJR.js';
2
+ export { InvoError } from './chunk-5X3ESHJR.js';
3
3
 
4
4
  // src/shared/webauthn.ts
5
5
  function malformedOptions(field) {
@@ -121,6 +121,7 @@ function toBalanceRow(row) {
121
121
  };
122
122
  }
123
123
  var PROCESSOR_SRC = "https://js.stripe.com/v3";
124
+ var PROCESSOR_LOAD_TIMEOUT_MS = 1e4;
124
125
  var processorScriptLoad;
125
126
  function loadProcessorScript() {
126
127
  if (typeof document === "undefined" || typeof window === "undefined") {
@@ -135,17 +136,7 @@ function loadProcessorScript() {
135
136
  if (window.Stripe) return Promise.resolve();
136
137
  if (processorScriptLoad) return processorScriptLoad;
137
138
  processorScriptLoad = new Promise((resolve, reject) => {
138
- const existing = document.querySelector(
139
- `script[src="${PROCESSOR_SRC}"]`
140
- );
141
- const script = existing ?? document.createElement("script");
142
- if (!existing) {
143
- script.src = PROCESSOR_SRC;
144
- script.async = true;
145
- document.head.appendChild(script);
146
- }
147
- script.addEventListener("load", () => resolve());
148
- script.addEventListener("error", () => {
139
+ const fail = () => {
149
140
  processorScriptLoad = void 0;
150
141
  reject(
151
142
  new InvoError({
@@ -154,7 +145,33 @@ function loadProcessorScript() {
154
145
  status: 0
155
146
  })
156
147
  );
148
+ };
149
+ const existing = document.querySelector(
150
+ `script[src="${PROCESSOR_SRC}"]`
151
+ );
152
+ if (existing) {
153
+ const started = Date.now();
154
+ const poll = setInterval(() => {
155
+ if (window.Stripe) {
156
+ clearInterval(poll);
157
+ resolve();
158
+ } else if (Date.now() - started > PROCESSOR_LOAD_TIMEOUT_MS) {
159
+ clearInterval(poll);
160
+ existing.remove();
161
+ fail();
162
+ }
163
+ }, 100);
164
+ return;
165
+ }
166
+ const script = document.createElement("script");
167
+ script.src = PROCESSOR_SRC;
168
+ script.async = true;
169
+ script.addEventListener("load", () => resolve());
170
+ script.addEventListener("error", () => {
171
+ script.remove();
172
+ fail();
157
173
  });
174
+ document.head.appendChild(script);
158
175
  });
159
176
  return processorScriptLoad;
160
177
  }
@@ -274,10 +291,25 @@ var PlatformCommerceClient = class {
274
291
  * when the payment is confirmed via a submit trigger — either `opts.submit` (your Pay
275
292
  * button, selector or element) or a minimal button the SDK renders inside `mount`. For
276
293
  * full control over the button, prefer {@link mountCardPayment}.
294
+ *
295
+ * Two flow notes:
296
+ * - **Bank redirect:** with `redirect: "if_required"` most cards confirm in-page, but a
297
+ * bank can force a full redirect — the browser then navigates away (this promise never
298
+ * settles) and returns to `returnUrl`. On that return page, reconcile via your server's
299
+ * `platformCommerce.getStatus(orderId)` / the `platform_commerce.purchased` webhook.
300
+ * - **Decline / "failed":** the element is torn down when this resolves — to let the user
301
+ * retry after a decline, call `confirmCardPayment` (or `mountCardPayment`) again to
302
+ * remount.
277
303
  */
278
304
  async confirmCardPayment(clientSecret, opts) {
279
305
  const session = await this.mountCardPayment(clientSecret, opts);
280
- const trigger = resolveSubmit(opts);
306
+ let trigger;
307
+ try {
308
+ trigger = resolveSubmit(opts);
309
+ } catch (e) {
310
+ session.destroy();
311
+ throw e;
312
+ }
281
313
  return new Promise((resolve, reject) => {
282
314
  const finish = (settle) => {
283
315
  if (trigger.created) trigger.el.remove();
package/dist/server.cjs CHANGED
@@ -71,7 +71,9 @@ var InvoError = class _InvoError extends Error {
71
71
  get isInsufficientBalance() {
72
72
  if (this.status !== 400) return false;
73
73
  const b = this.bodyObject();
74
- return this.code === "INSUFFICIENT_BALANCE" || "required_amount" in b || /insufficient[_ ]balance/i.test(this.message);
74
+ return this.code === "INSUFFICIENT_BALANCE" || "required_amount" in b || // Zero-balance variant ("Player has no balance in this tenant") carries only
75
+ // `current_balance` — same top-up condition, so classify it the same way.
76
+ "current_balance" in b || /insufficient[_ ]balance/i.test(this.message);
75
77
  }
76
78
  /**
77
79
  * True if the call needs phone-share approval before it can complete (409) — the
@@ -186,10 +188,11 @@ function errorFromResponse(status, body, requestId) {
186
188
  else if (typeof b["error_code"] === "string") code = b["error_code"];
187
189
  if (typeof b["error"] === "string") message = b["error"];
188
190
  else if (typeof b["message"] === "string") message = b["message"];
189
- if (!code && typeof b["error"] === "string" && /^(flow_paused|spending_limit_exceeded|receiver_not_enrolled_use_claim_code|no_channel_on_file|rate_limited)$/.test(
191
+ if (!code && typeof b["error"] === "string" && /^(flow_paused|spending_limit_exceeded|receiver_not_enrolled_use_claim_code|no_channel_on_file|rate_limited|service_unavailable)$/.test(
190
192
  b["error"]
191
193
  )) {
192
194
  code = b["error"];
195
+ if (typeof b["message"] === "string" && b["message"]) message = b["message"];
193
196
  }
194
197
  } else if (typeof body === "string" && body.trim()) {
195
198
  message = body;
@@ -605,7 +608,7 @@ async function hmacHexSubtle(secret, message) {
605
608
  }
606
609
 
607
610
  // src/server.ts
608
- var DEFAULT_UA = "invonetwork-web-sdk/2.5.0 (+https://invo.network)";
611
+ var DEFAULT_UA = "invonetwork-web-sdk/2.5.1 (+https://invo.network)";
609
612
  var MAX_USD_AMOUNT = 999.99;
610
613
  var MAX_ITEM_PRICE = 999999.99;
611
614
  function invalidInput(label, value, why) {
@@ -767,9 +770,12 @@ function requireField(value, field, raw) {
767
770
  return s;
768
771
  }
769
772
  var FUNDING_SOURCES = /* @__PURE__ */ new Set(["balance", "card"]);
773
+ function invalidInputNoEcho(label, why) {
774
+ return new InvoError({ message: `${label} ${why}.`, code: "INVALID_INPUT", status: 0 });
775
+ }
770
776
  function assertBillingAddress(addr, label) {
771
777
  if (!addr || typeof addr !== "object") {
772
- throw invalidInput(label, addr, 'is required for the "card" funding source');
778
+ throw invalidInputNoEcho(label, 'is required for the "card" funding source and must be an object');
773
779
  }
774
780
  const required = [
775
781
  [`${label}.line1`, addr.line1],
@@ -778,10 +784,20 @@ function assertBillingAddress(addr, label) {
778
784
  [`${label}.country`, addr.country]
779
785
  ];
780
786
  for (const [k, v] of required) {
781
- if (typeof v !== "string" || !v.trim()) throw invalidInput(k, v, "is required");
787
+ if (typeof v !== "string" || !v.trim()) throw invalidInputNoEcho(k, "is required");
782
788
  }
783
789
  if (!/^[A-Za-z]{2}$/.test(addr.country)) {
784
- throw invalidInput(`${label}.country`, addr.country, "must be a 2-letter ISO country code");
790
+ throw invalidInputNoEcho(`${label}.country`, "must be a 2-letter ISO country code");
791
+ }
792
+ const optional = [
793
+ [`${label}.name`, addr.name],
794
+ [`${label}.line2`, addr.line2],
795
+ [`${label}.state`, addr.state]
796
+ ];
797
+ for (const [k, v] of optional) {
798
+ if (v !== void 0 && typeof v !== "string") {
799
+ throw invalidInputNoEcho(k, "must be a string when provided");
800
+ }
785
801
  }
786
802
  }
787
803
  function toBillingAddressBody(addr) {
@@ -815,6 +831,12 @@ var PlatformCommerceServer = class {
815
831
  *
816
832
  * Idempotent on `clientRequestId` (a duplicate throws a 409 `err.isDuplicateRequest`).
817
833
  * A non-platform tenant throws `err.isNotPlatformTenant` (403).
834
+ *
835
+ * ⚠ Card-leg caveat: if the RESPONSE to a card purchase is lost (timeout after the
836
+ * backend created the order), re-sending the same `clientRequestId` returns the duplicate
837
+ * 409 and the `clientSecret` cannot be re-fetched — reconcile that order via the
838
+ * `platform_commerce.purchased` webhook / `getStatus`, and use a NEW `clientRequestId`
839
+ * for a fresh attempt. The balance leg has no such gap.
818
840
  */
819
841
  async purchase(input, opts) {
820
842
  const required = [
@@ -847,6 +869,7 @@ var PlatformCommerceServer = class {
847
869
  if (input.fundingSource === "card") {
848
870
  assertBillingAddress(input.billingAddress, "billingAddress");
849
871
  }
872
+ if (input.playerPhone !== void 0) assertE164(input.playerPhone, "playerPhone");
850
873
  const body = {
851
874
  client_request_id: input.clientRequestId,
852
875
  funding_source: input.fundingSource,
@@ -949,6 +972,9 @@ var PlatformCommerceServer = class {
949
972
  // The refund HTTP response carries no unit; derive it (card → USD). The balance leg's
950
973
  // unit is the tenant's network currency, not present here — left undefined.
951
974
  amountUnit: raw["amount_unit"] ?? (fundingSource === "card" ? "usd" : void 0),
975
+ // Balance leg: the canonical post-refund balance. Card leg: the processor's refund id.
976
+ newBalance: raw["new_balance"] ?? null,
977
+ processorRefundId: raw["stripe_refund_id"],
952
978
  feeRetained: raw["fee_retained"] === true,
953
979
  raw
954
980
  };
package/dist/server.d.cts CHANGED
@@ -1,5 +1,5 @@
1
- import { o as InvoError, H as Http, v as AuthHeader, w as PlatformPurchaseInput, d as CallOptions, x as PlatformPurchaseResult, y as PlatformOrderStatusResult, z as PlatformRefundInput, F as PlatformRefundResult, S as ServerConfig, G as PlayerToken, J as InitiateSendInput, K as InitiateResult, N as InitiateTransferInput, O as CreateCheckoutInput, Q as CreateCheckoutResult, T as PurchaseInput, U as PurchaseResult, W as ConfirmPaymentResult, X as OrderDetailsResult, Y as PurchaseItemInput, Z as PurchaseItemResult, _ as ItemHistoryQuery, $ as ItemHistoryResult, a0 as ItemOrderQuery, a1 as PlayerBalanceQuery, a2 as PlayerBalanceResult, a3 as InboundPendingQuery, a4 as InboundPendingResult, a5 as LinkedIdentitiesQuery, a6 as LinkedIdentitiesResult, a7 as SmsVerifyResult, a8 as ClaimTransferInput, a9 as ClaimResult, aa as ClaimCurrencyInput, ab as TransactionStatusResult, ac as GuardianApprovalStatusResult, ad as ServerDestinationsQuery, f as DestinationsResult, ae as PhoneShareContact, af as PhoneShareInitiateResult, ag as PhoneShareApproveInput, ah as PhoneShareApproveResult, ai as PhoneShareStatusResult } from './types-g1xz5GDk.cjs';
2
- export { aj as BillingAddress, ak as CurrencyBalance, k as DestinationGame, al as FundingSource, am as InboundPendingItem, p as InvoErrorInfo, q as InvoHooks, r as InvoRequestInfo, s as InvoResponseInfo, an as LinkedIdentityEmail, ao as PlatformPurchaseStatus, u as Rail, V as VerificationMethod } from './types-g1xz5GDk.cjs';
1
+ import { o as InvoError, H as Http, v as AuthHeader, w as PlatformPurchaseInput, d as CallOptions, x as PlatformPurchaseResult, y as PlatformOrderStatusResult, z as PlatformRefundInput, F as PlatformRefundResult, S as ServerConfig, G as PlayerToken, J as InitiateSendInput, K as InitiateResult, N as InitiateTransferInput, O as CreateCheckoutInput, Q as CreateCheckoutResult, T as PurchaseInput, U as PurchaseResult, W as ConfirmPaymentResult, X as OrderDetailsResult, Y as PurchaseItemInput, Z as PurchaseItemResult, _ as ItemHistoryQuery, $ as ItemHistoryResult, a0 as ItemOrderQuery, a1 as PlayerBalanceQuery, a2 as PlayerBalanceResult, a3 as InboundPendingQuery, a4 as InboundPendingResult, a5 as LinkedIdentitiesQuery, a6 as LinkedIdentitiesResult, a7 as SmsVerifyResult, a8 as ClaimTransferInput, a9 as ClaimResult, aa as ClaimCurrencyInput, ab as TransactionStatusResult, ac as GuardianApprovalStatusResult, ad as ServerDestinationsQuery, f as DestinationsResult, ae as PhoneShareContact, af as PhoneShareInitiateResult, ag as PhoneShareApproveInput, ah as PhoneShareApproveResult, ai as PhoneShareStatusResult } from './types-BHvVjdMV.cjs';
2
+ export { aj as BillingAddress, ak as CurrencyBalance, k as DestinationGame, al as FundingSource, am as InboundPendingItem, p as InvoErrorInfo, q as InvoHooks, r as InvoRequestInfo, s as InvoResponseInfo, an as LinkedIdentityEmail, ao as PlatformPurchaseStatus, u as Rail, V as VerificationMethod } from './types-BHvVjdMV.cjs';
3
3
 
4
4
  interface VerifyWebhookOptions {
5
5
  /** Max age of the signed timestamp, in seconds. Default 300 (5 min). */
@@ -84,7 +84,10 @@ interface PlatformCommerceRefundedData {
84
84
  order_id: string | number;
85
85
  /** "balance" | "card". */
86
86
  funding_source: string;
87
- player_email: string;
87
+ /** Null when the player row no longer exists at refund time. */
88
+ player_email: string | null;
89
+ /** Nullable for the same reason. */
90
+ identity_id?: string | null;
88
91
  refunded_amount: string;
89
92
  /** `"usd"` (card) or the literal `"currency"` (balance). */
90
93
  amount_unit: string;
@@ -226,6 +229,12 @@ declare class PlatformCommerceServer {
226
229
  *
227
230
  * Idempotent on `clientRequestId` (a duplicate throws a 409 `err.isDuplicateRequest`).
228
231
  * A non-platform tenant throws `err.isNotPlatformTenant` (403).
232
+ *
233
+ * ⚠ Card-leg caveat: if the RESPONSE to a card purchase is lost (timeout after the
234
+ * backend created the order), re-sending the same `clientRequestId` returns the duplicate
235
+ * 409 and the `clientSecret` cannot be re-fetched — reconcile that order via the
236
+ * `platform_commerce.purchased` webhook / `getStatus`, and use a NEW `clientRequestId`
237
+ * for a fresh attempt. The balance leg has no such gap.
229
238
  */
230
239
  purchase(input: PlatformPurchaseInput, opts?: CallOptions): Promise<PlatformPurchaseResult>;
231
240
  /** Poll an order's status: `completed` (balance immediately; card after the webhook),
package/dist/server.d.ts CHANGED
@@ -1,5 +1,5 @@
1
- import { o as InvoError, H as Http, v as AuthHeader, w as PlatformPurchaseInput, d as CallOptions, x as PlatformPurchaseResult, y as PlatformOrderStatusResult, z as PlatformRefundInput, F as PlatformRefundResult, S as ServerConfig, G as PlayerToken, J as InitiateSendInput, K as InitiateResult, N as InitiateTransferInput, O as CreateCheckoutInput, Q as CreateCheckoutResult, T as PurchaseInput, U as PurchaseResult, W as ConfirmPaymentResult, X as OrderDetailsResult, Y as PurchaseItemInput, Z as PurchaseItemResult, _ as ItemHistoryQuery, $ as ItemHistoryResult, a0 as ItemOrderQuery, a1 as PlayerBalanceQuery, a2 as PlayerBalanceResult, a3 as InboundPendingQuery, a4 as InboundPendingResult, a5 as LinkedIdentitiesQuery, a6 as LinkedIdentitiesResult, a7 as SmsVerifyResult, a8 as ClaimTransferInput, a9 as ClaimResult, aa as ClaimCurrencyInput, ab as TransactionStatusResult, ac as GuardianApprovalStatusResult, ad as ServerDestinationsQuery, f as DestinationsResult, ae as PhoneShareContact, af as PhoneShareInitiateResult, ag as PhoneShareApproveInput, ah as PhoneShareApproveResult, ai as PhoneShareStatusResult } from './types-g1xz5GDk.js';
2
- export { aj as BillingAddress, ak as CurrencyBalance, k as DestinationGame, al as FundingSource, am as InboundPendingItem, p as InvoErrorInfo, q as InvoHooks, r as InvoRequestInfo, s as InvoResponseInfo, an as LinkedIdentityEmail, ao as PlatformPurchaseStatus, u as Rail, V as VerificationMethod } from './types-g1xz5GDk.js';
1
+ import { o as InvoError, H as Http, v as AuthHeader, w as PlatformPurchaseInput, d as CallOptions, x as PlatformPurchaseResult, y as PlatformOrderStatusResult, z as PlatformRefundInput, F as PlatformRefundResult, S as ServerConfig, G as PlayerToken, J as InitiateSendInput, K as InitiateResult, N as InitiateTransferInput, O as CreateCheckoutInput, Q as CreateCheckoutResult, T as PurchaseInput, U as PurchaseResult, W as ConfirmPaymentResult, X as OrderDetailsResult, Y as PurchaseItemInput, Z as PurchaseItemResult, _ as ItemHistoryQuery, $ as ItemHistoryResult, a0 as ItemOrderQuery, a1 as PlayerBalanceQuery, a2 as PlayerBalanceResult, a3 as InboundPendingQuery, a4 as InboundPendingResult, a5 as LinkedIdentitiesQuery, a6 as LinkedIdentitiesResult, a7 as SmsVerifyResult, a8 as ClaimTransferInput, a9 as ClaimResult, aa as ClaimCurrencyInput, ab as TransactionStatusResult, ac as GuardianApprovalStatusResult, ad as ServerDestinationsQuery, f as DestinationsResult, ae as PhoneShareContact, af as PhoneShareInitiateResult, ag as PhoneShareApproveInput, ah as PhoneShareApproveResult, ai as PhoneShareStatusResult } from './types-BHvVjdMV.js';
2
+ export { aj as BillingAddress, ak as CurrencyBalance, k as DestinationGame, al as FundingSource, am as InboundPendingItem, p as InvoErrorInfo, q as InvoHooks, r as InvoRequestInfo, s as InvoResponseInfo, an as LinkedIdentityEmail, ao as PlatformPurchaseStatus, u as Rail, V as VerificationMethod } from './types-BHvVjdMV.js';
3
3
 
4
4
  interface VerifyWebhookOptions {
5
5
  /** Max age of the signed timestamp, in seconds. Default 300 (5 min). */
@@ -84,7 +84,10 @@ interface PlatformCommerceRefundedData {
84
84
  order_id: string | number;
85
85
  /** "balance" | "card". */
86
86
  funding_source: string;
87
- player_email: string;
87
+ /** Null when the player row no longer exists at refund time. */
88
+ player_email: string | null;
89
+ /** Nullable for the same reason. */
90
+ identity_id?: string | null;
88
91
  refunded_amount: string;
89
92
  /** `"usd"` (card) or the literal `"currency"` (balance). */
90
93
  amount_unit: string;
@@ -226,6 +229,12 @@ declare class PlatformCommerceServer {
226
229
  *
227
230
  * Idempotent on `clientRequestId` (a duplicate throws a 409 `err.isDuplicateRequest`).
228
231
  * A non-platform tenant throws `err.isNotPlatformTenant` (403).
232
+ *
233
+ * ⚠ Card-leg caveat: if the RESPONSE to a card purchase is lost (timeout after the
234
+ * backend created the order), re-sending the same `clientRequestId` returns the duplicate
235
+ * 409 and the `clientSecret` cannot be re-fetched — reconcile that order via the
236
+ * `platform_commerce.purchased` webhook / `getStatus`, and use a NEW `clientRequestId`
237
+ * for a fresh attempt. The balance leg has no such gap.
229
238
  */
230
239
  purchase(input: PlatformPurchaseInput, opts?: CallOptions): Promise<PlatformPurchaseResult>;
231
240
  /** Poll an order's status: `completed` (balance immediately; card after the webhook),
package/dist/server.js CHANGED
@@ -1,5 +1,5 @@
1
- import { InvoError, assertSecureBaseUrl, Http, toDestinationsResult } from './chunk-ZKYUSYK5.js';
2
- export { InvoError } from './chunk-ZKYUSYK5.js';
1
+ import { InvoError, assertSecureBaseUrl, Http, toDestinationsResult } from './chunk-5X3ESHJR.js';
2
+ export { InvoError } from './chunk-5X3ESHJR.js';
3
3
  import { createHmac, timingSafeEqual } from 'crypto';
4
4
 
5
5
  var DEFAULT_TOLERANCE_SEC = 300;
@@ -167,7 +167,7 @@ async function hmacHexSubtle(secret, message) {
167
167
  }
168
168
 
169
169
  // src/server.ts
170
- var DEFAULT_UA = "invonetwork-web-sdk/2.5.0 (+https://invo.network)";
170
+ var DEFAULT_UA = "invonetwork-web-sdk/2.5.1 (+https://invo.network)";
171
171
  var MAX_USD_AMOUNT = 999.99;
172
172
  var MAX_ITEM_PRICE = 999999.99;
173
173
  function invalidInput(label, value, why) {
@@ -329,9 +329,12 @@ function requireField(value, field, raw) {
329
329
  return s;
330
330
  }
331
331
  var FUNDING_SOURCES = /* @__PURE__ */ new Set(["balance", "card"]);
332
+ function invalidInputNoEcho(label, why) {
333
+ return new InvoError({ message: `${label} ${why}.`, code: "INVALID_INPUT", status: 0 });
334
+ }
332
335
  function assertBillingAddress(addr, label) {
333
336
  if (!addr || typeof addr !== "object") {
334
- throw invalidInput(label, addr, 'is required for the "card" funding source');
337
+ throw invalidInputNoEcho(label, 'is required for the "card" funding source and must be an object');
335
338
  }
336
339
  const required = [
337
340
  [`${label}.line1`, addr.line1],
@@ -340,10 +343,20 @@ function assertBillingAddress(addr, label) {
340
343
  [`${label}.country`, addr.country]
341
344
  ];
342
345
  for (const [k, v] of required) {
343
- if (typeof v !== "string" || !v.trim()) throw invalidInput(k, v, "is required");
346
+ if (typeof v !== "string" || !v.trim()) throw invalidInputNoEcho(k, "is required");
344
347
  }
345
348
  if (!/^[A-Za-z]{2}$/.test(addr.country)) {
346
- throw invalidInput(`${label}.country`, addr.country, "must be a 2-letter ISO country code");
349
+ throw invalidInputNoEcho(`${label}.country`, "must be a 2-letter ISO country code");
350
+ }
351
+ const optional = [
352
+ [`${label}.name`, addr.name],
353
+ [`${label}.line2`, addr.line2],
354
+ [`${label}.state`, addr.state]
355
+ ];
356
+ for (const [k, v] of optional) {
357
+ if (v !== void 0 && typeof v !== "string") {
358
+ throw invalidInputNoEcho(k, "must be a string when provided");
359
+ }
347
360
  }
348
361
  }
349
362
  function toBillingAddressBody(addr) {
@@ -377,6 +390,12 @@ var PlatformCommerceServer = class {
377
390
  *
378
391
  * Idempotent on `clientRequestId` (a duplicate throws a 409 `err.isDuplicateRequest`).
379
392
  * A non-platform tenant throws `err.isNotPlatformTenant` (403).
393
+ *
394
+ * ⚠ Card-leg caveat: if the RESPONSE to a card purchase is lost (timeout after the
395
+ * backend created the order), re-sending the same `clientRequestId` returns the duplicate
396
+ * 409 and the `clientSecret` cannot be re-fetched — reconcile that order via the
397
+ * `platform_commerce.purchased` webhook / `getStatus`, and use a NEW `clientRequestId`
398
+ * for a fresh attempt. The balance leg has no such gap.
380
399
  */
381
400
  async purchase(input, opts) {
382
401
  const required = [
@@ -409,6 +428,7 @@ var PlatformCommerceServer = class {
409
428
  if (input.fundingSource === "card") {
410
429
  assertBillingAddress(input.billingAddress, "billingAddress");
411
430
  }
431
+ if (input.playerPhone !== void 0) assertE164(input.playerPhone, "playerPhone");
412
432
  const body = {
413
433
  client_request_id: input.clientRequestId,
414
434
  funding_source: input.fundingSource,
@@ -511,6 +531,9 @@ var PlatformCommerceServer = class {
511
531
  // The refund HTTP response carries no unit; derive it (card → USD). The balance leg's
512
532
  // unit is the tenant's network currency, not present here — left undefined.
513
533
  amountUnit: raw["amount_unit"] ?? (fundingSource === "card" ? "usd" : void 0),
534
+ // Balance leg: the canonical post-refund balance. Card leg: the processor's refund id.
535
+ newBalance: raw["new_balance"] ?? null,
536
+ processorRefundId: raw["stripe_refund_id"],
514
537
  feeRetained: raw["fee_retained"] === true,
515
538
  raw
516
539
  };
@@ -497,6 +497,10 @@ interface PlatformRefundResult {
497
497
  * currency; the refund response carries no unit, so this is `undefined` there
498
498
  * (the `platform_commerce.refunded` webhook is authoritative for the unit). */
499
499
  amountUnit?: string;
500
+ /** Balance leg only: the canonical balance AFTER the re-credit. */
501
+ newBalance?: string | number | null;
502
+ /** Card leg only: the card processor's refund id (for support/reconciliation). */
503
+ processorRefundId?: string;
500
504
  /** Always true — INVO retains its fee; the customer is made whole minus that fee. */
501
505
  feeRetained?: boolean;
502
506
  raw: Record<string, unknown>;
@@ -573,6 +577,9 @@ interface CardPaymentResult {
573
577
  paymentIntentId?: string;
574
578
  /** Present on "failed": the processor's error message. */
575
579
  error?: string;
580
+ /** The processor's full confirm response. NOTE: includes the PaymentIntent, whose
581
+ * `client_secret` is semi-public but still shouldn't be written to logs — redact
582
+ * `raw` if you log these results. */
576
583
  raw: Record<string, unknown>;
577
584
  }
578
585
  /** Handle returned by `mountCardPayment`: confirm on your own button, then tear down. */
@@ -497,6 +497,10 @@ interface PlatformRefundResult {
497
497
  * currency; the refund response carries no unit, so this is `undefined` there
498
498
  * (the `platform_commerce.refunded` webhook is authoritative for the unit). */
499
499
  amountUnit?: string;
500
+ /** Balance leg only: the canonical balance AFTER the re-credit. */
501
+ newBalance?: string | number | null;
502
+ /** Card leg only: the card processor's refund id (for support/reconciliation). */
503
+ processorRefundId?: string;
500
504
  /** Always true — INVO retains its fee; the customer is made whole minus that fee. */
501
505
  feeRetained?: boolean;
502
506
  raw: Record<string, unknown>;
@@ -573,6 +577,9 @@ interface CardPaymentResult {
573
577
  paymentIntentId?: string;
574
578
  /** Present on "failed": the processor's error message. */
575
579
  error?: string;
580
+ /** The processor's full confirm response. NOTE: includes the PaymentIntent, whose
581
+ * `client_secret` is semi-public but still shouldn't be written to logs — redact
582
+ * `raw` if you log these results. */
576
583
  raw: Record<string, unknown>;
577
584
  }
578
585
  /** Handle returned by `mountCardPayment`: confirm on your own button, then tear down. */
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@invonetwork/web-sdk",
3
- "version": "2.5.0",
3
+ "version": "2.5.1",
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,