@invonetwork/web-sdk 2.5.0 → 3.0.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,77 @@ 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
+ ## [3.0.0] — 2026-07-20
8
+
9
+ **BREAKING — the Platform Commerce card leg moved to INVO's hosted checkout.** The backend now
10
+ hosts the entire card flow (card fields, Apple Pay / Google Pay, billing-address collection,
11
+ 3-D Secure) on its own checkout page, so the browser card-element surface shipped in 2.5.x is
12
+ gone. Card sales are simpler AND safer: server creates → buyer pays on `checkoutUrl` → fulfill
13
+ on the `platform_commerce.purchased` webhook. Note: the card leg is pending final enablement on
14
+ the backend (sandbox payment test) — the balance leg is fully live.
15
+
16
+ ### Migration from 2.5.x (card leg only — balance/status/refund/webhooks unchanged)
17
+ - `platformCommerce.purchase({ fundingSource: "card" })`: **remove `billingAddress`** (the type
18
+ is gone; the hosted page collects it) and optionally pass `successUrl` / `cancelUrl` /
19
+ `metadata`. The result now carries `checkoutUrl` / `sessionId` / `expiresAt` (unix seconds) /
20
+ `idempotentReplay` — **`clientSecret` no longer exists.**
21
+ - Browser: **`confirmCardPayment` and `mountCardPayment` are removed** (with all card-element
22
+ types and the `commercePublishableKey` config). Replace with a redirect
23
+ (`location.href = checkoutUrl`) or the new optional embed:
24
+ `invo.platformCommerce.mountCheckout(el, checkoutUrl, { onComplete })` — an iframe plus an
25
+ origin-checked listener for the page's `INVO_CHECKOUT_COMPLETE` message.
26
+ - Card duplicates no longer 409: retrying `purchase` with the same `clientRequestId` **replays
27
+ the same checkout session** (`idempotentReplay: true`), so a lost response is recoverable.
28
+
29
+ ### Added
30
+ - `PlatformPurchaseInput.successUrl/cancelUrl/metadata`; result fields
31
+ `sessionId/checkoutUrl/expiresAt/idempotentReplay`.
32
+ - `InvoClient.platformCommerce.mountCheckout(el, checkoutUrl, opts)` → `{ iframe, destroy() }`.
33
+ - `err.isAboveCardMaximum` (`ABOVE_CARD_MAXIMUM`, card > $999.99) + client-side card USD
34
+ bounds fail-fast ($0.50–$999.99).
35
+ - Card `requires_payment` responses without a `checkout_url` fail closed (`INVALID_RESPONSE`).
36
+
37
+ ### Removed
38
+ - `confirmCardPayment`, `mountCardPayment`, `commercePublishableKey`, `BillingAddress`, and the
39
+ card-element/processor types + the runtime CDN script loader (no more processor touchpoints
40
+ in this SDK at all).
41
+
42
+ ## [2.5.1] — 2026-07-20
43
+
44
+ Hardening patch from a second, independent post-release audit (correctness vs the backend
45
+ blueprint + security red-team) of the 2.5.0 Platform Commerce feature. No API breaks.
46
+
47
+ ### Fixed
48
+ - **Card-confirm script loader could hang forever on retry.** After a transient CDN failure
49
+ (or a pre-existing processor `<script>` tag whose events already fired), the next
50
+ `mountCardPayment`/`confirmCardPayment` attached listeners to a dead tag and never settled —
51
+ checkout silently dead until page reload. The loader now removes failed tags and polls
52
+ (bounded, 10s) when a tag pre-exists.
53
+ - **Orphaned card element on submit-lookup failure.** `confirmCardPayment` now destroys the
54
+ mounted Payment Element before rethrowing when the `submit` selector can't be resolved
55
+ (previously a retry stacked a second live card iframe).
56
+ - **Billing-address validation errors no longer echo the submitted values** (cardholder PII
57
+ could otherwise land in logs/Sentry); optional billing fields (`name`/`line2`/`state`) are
58
+ now type-checked.
59
+ - **`playerPhone` on `platformCommerce.purchase` is now E.164-validated** — this endpoint can
60
+ create the player identity, so a national-format phone must never reach the wire.
61
+ - **`err.isInsufficientBalance` now also classifies the zero-balance 400** ("Player has no
62
+ balance in this tenant", which carries only `current_balance`).
63
+ - **Breaker-open 503 keeps its human message** (`err.code === "service_unavailable"`, message
64
+ no longer collapses to the bare token).
65
+ - **Webhook types:** `platform_commerce.refunded` `player_email` is nullable + `identity_id`
66
+ added; (2.5.0 already made card-leg `total_price` optional on `purchased`).
67
+ - **Refund result surfaces `newBalance`** (balance leg) **and `processorRefundId`** (card leg)
68
+ instead of leaving them `raw`-only.
69
+ - Platform-commerce error tests now assert the REAL backend envelopes
70
+ (`{status,error_code,message}` / bare `{message}`), not idealized shapes.
71
+
72
+ ### Docs
73
+ - Card-leg lost-response caveat on `purchase` (duplicate 409 can strand a `clientSecret`-less
74
+ pending order — reconcile via webhook/`getStatus`, retry with a NEW `clientRequestId`).
75
+ - `confirmCardPayment`: bank-redirect return-leg guidance + remount-after-decline note;
76
+ `CardPaymentResult.raw` log-redaction note.
77
+
7
78
  ## [2.5.0] — 2026-07-20
8
79
 
9
80
  **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:** `v3.0.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: **3.0.0** moves the Platform Commerce card leg to **INVO's hosted checkout** — the server `purchase()` now returns a `checkoutUrl` and the browser just sends the buyer there (redirect or `mountCheckout` iframe); the 2.5.x card-element surface (`confirmCardPayment`/`mountCardPayment`, `billingAddress`, `commercePublishableKey`) is **removed** — see the [CHANGELOG](CHANGELOG.md) migration note; **2.5.0** added **Platform Commerce** (ecommerce) — a platform tenant selling items funded by balance **or** card, with `invo.platformCommerce.purchase/getStatus/refund` (server) 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
@@ -13,7 +13,7 @@ Five money flows plus passkey (WebAuthn) authentication, split across a trusted
13
13
  |---|---|---|---|---|
14
14
  | **Currency purchase** | real money **→** game currency | yes (card/rails) | no | server initiates, browser opens hosted checkout |
15
15
  | **Item purchase** | game currency **→** in-game item | no (balance debit) | no | server only |
16
- | **Platform Commerce** (ecommerce) | balance **or** card **→** a storefront item | card leg only | no | server creates, browser confirms the card |
16
+ | **Platform Commerce** (ecommerce) | balance **or** card **→** a storefront item | card leg only | no | server creates; buyer pays on INVO's **hosted checkout** |
17
17
  | **Send** | currency **→** another player (cross-game) | no | yes (sender approves) | server initiates, browser approves/claims |
18
18
  | **Transfer** | currency **→** another player (transfer rail) | no | yes (sender approves) | server initiates, browser approves/claims |
19
19
 
@@ -21,7 +21,7 @@ Five money flows plus passkey (WebAuthn) authentication, split across a trusted
21
21
  > - **[Item purchase](#item-purchase-spend-game-currency)** — a **game** tenant. A player spends **game currency they already hold** on an **in-game** item (a sword, a skin). Always a balance debit — **never a card, never new money, no refunds**. `server.purchaseItem(...)` → `/api/item-purchases`.
22
22
  > - **[Platform Commerce](#platform-commerce-ecommerce)** — a **platform** tenant (a non-game app: vertical video, creator merch, marketplace). A **storefront** sale funded by **INVO balance or a real card** (new money), with **INVO as merchant of record** and **refunds**. `server.platformCommerce.purchase(...)` → `/api/platform-commerce`. A game tenant calling it gets `403 NOT_A_PLATFORM_TENANT`.
23
23
 
24
- The **game secret stays on your server**; the browser only ever holds a short-lived, game-scoped **player token** (and, for the card leg, a per-purchase `clientSecret`).
24
+ The **game secret stays on your server**; the browser only ever holds a short-lived, game-scoped **player token** (and, for the card leg, a per-purchase `checkoutUrl`).
25
25
 
26
26
  ## Contents
27
27
 
@@ -313,7 +313,7 @@ const item = await server.purchaseItem({
313
313
 
314
314
  > **This is not [item purchase](#item-purchase-spend-game-currency).** Item purchase is a *game* tenant spending a player's *existing game currency* on an *in-game* item — always a balance debit, never a card, no refunds. **Platform Commerce is a _platform_ tenant (a non-game app: vertical video, creator merch, marketplace) running a storefront.** The buyer pays with **INVO balance** *or* a **real card** (new money), INVO is **merchant of record**, and **refunds** exist. Only platform tenants may call it — a game tenant gets `403` (`err.isNotPlatformTenant`).
315
315
 
316
- The funding source is resolved **server-side under lock** — the client can *request* `balance` or `card`, but the backend verifies the real balance before any value moves. That's why there's a server call (holds the secret, creates the purchase/refund) **and** a browser call (confirms the card). Reached via the `platformCommerce` namespace on each entry point.
316
+ The funding source is resolved **server-side under lock** — the client can *request* `balance` or `card`, but the backend verifies the real balance before any value moves. Everything money-shaped is a server call (holds the secret, creates the purchase/refund); the browser's only job on the card leg is to **send the buyer to INVO's hosted checkout page**. Reached via the `platformCommerce` namespace on each entry point.
317
317
 
318
318
  ### Balance leg — one server call, settles now
319
319
 
@@ -335,12 +335,12 @@ const r = await server.platformCommerce.purchase({
335
335
  // r.financialBreakdown { total_paid, developer_revenue, platform_fee } // INVO fee: 3.5% flat
336
336
  ```
337
337
 
338
- ### Card leg — server creates, browser confirms
338
+ ### Card leg — server creates, INVO hosts the checkout
339
339
 
340
- The card leg is the SDK's only browser **payment** step. `totalPrice` is **USD**, and a **`billingAddress`** is required (AVS / fraud / merchant-of-record).
340
+ **INVO hosts the entire card checkout** — card fields, Apple Pay / Google Pay, the international billing-address collector, and 3-D Secure all live on INVO's page. There is **no billing address in the request, no card element, no processor dependency, and no client payment code to write**: the server call returns a `checkoutUrl` and you send the buyer there. `totalPrice` is **USD** ($0.50–$999.99).
341
341
 
342
342
  ```ts
343
- // 1) server — returns a clientSecret, NOT yet paid
343
+ // 1) server — returns a hosted-checkout session, NOT yet paid
344
344
  const r = await server.platformCommerce.purchase({
345
345
  clientRequestId: crypto.randomUUID(),
346
346
  fundingSource: "card",
@@ -351,29 +351,28 @@ const r = await server.platformCommerce.purchase({
351
351
  itemQuantity: 1,
352
352
  unitPrice: "5.00", // CARD leg: USD
353
353
  totalPrice: "5.00",
354
- billingAddress: { // REQUIRED on the card leg
355
- line1: "1 Main St", city: "Austin", postalCode: "78701", country: "US",
356
- // optional: name, line2, state
357
- },
354
+ successUrl: "https://app.example/thanks", // optional: where the buyer lands after paying
355
+ cancelUrl: "https://app.example/cart", // optional: where the buyer lands on cancel
356
+ metadata: { cartId: "c_9" }, // optional: echoed back on the webhook
358
357
  });
359
- // r.status === "requires_payment"; hand r.clientSecret to the browser
358
+ // r.status === "requires_payment"
359
+ // r.checkoutUrl → send the buyer here r.sessionId / r.expiresAt (unix seconds)
360
360
  ```
361
361
 
362
362
  ```ts
363
- // 2) browser — mount the card element and confirm. The SDK lazy-loads the card
364
- // processor's JS from its CDN (no bundled dependency); pass its PUBLISHABLE key.
365
- const result = await invo.platformCommerce.confirmCardPayment(clientSecret, {
366
- mount: "#pay", // a CSS selector or an HTMLElement
367
- publishableKey: "pk_live_…", // or set commercePublishableKey on the InvoClient config
368
- returnUrl: location.href, // where the bank returns after any 3-D Secure step
369
- // optional: submit (your own Pay button, selector or element), submitLabel, appearance
363
+ // 2) browser — EITHER just redirect…
364
+ location.href = r.checkoutUrl;
365
+
366
+ // …OR embed the hosted page with the optional helper (iframe + completion listener):
367
+ const handle = invo.platformCommerce.mountCheckout("#checkout", checkoutUrl, {
368
+ onComplete: () => showProcessing(), // fires on the page's INVO_CHECKOUT_COMPLETE message
370
369
  });
371
- // result.status: "succeeded" | "requires_action" | "processing" | "failed"
370
+ // later: handle.destroy();
372
371
  ```
373
372
 
374
- For full control over your own Pay button, use the primitive: `const session = await invo.platformCommerce.mountCardPayment(clientSecret, { mount, publishableKey })`, then call `await session.confirm({ returnUrl })` from your button and `session.destroy()` when done.
373
+ `mountCheckout` accepts completion messages **only from the checkout page's own origin**, and `onComplete` is a UX signal — show "processing", then reconcile server-side.
375
374
 
376
- > ⚠️ **The card sale is real only on the `platform_commerce.purchased` webhook — never on the browser confirmation** (a client can be tampered with). Treat `"succeeded"` as "show processing" and fulfill on the webhook.
375
+ > ⚠️ **The card sale is real only on the `platform_commerce.purchased` webhook — never on the client return or the in-frame completion event** (a client can be tampered with). Fulfill on the webhook.
377
376
 
378
377
  ### Status & refunds
379
378
 
@@ -387,10 +386,9 @@ const ref = await server.platformCommerce.refund({ orderId: r.orderId, reason: "
387
386
  // A second refund of the same order throws 409 (err.isAlreadyRefunded) — treat as already done.
388
387
  ```
389
388
 
390
- - **Idempotent** on `clientRequestId` — a duplicate purchase throws `409` (`err.isDuplicateRequest`).
391
- - **Lost card-purchase response?** If the network drops the card-leg response, you won't have the `clientSecret` or `orderId`, and retrying the same `clientRequestId` returns `409` (the order already exists). Reconcile via your **`platform_commerce.purchased`** webhook — don't retry to recover the `clientSecret`. (The balance leg is fully retry-safe.)
392
- - INVO fee: **3.5% flat** (balance) · **3.5% + $0.30** (card). Below-minimum amounts throw `err.isAmountBelowMinimum`; a card charge under $0.50 throws `err.isBelowCardMinimum`.
393
- - Client-side validation (missing fields, bad funding source, quantity outside `1..1000`, total ≠ unit×qty, missing/short billing address on the card leg) throws `INVALID_INPUT` **before** any network call.
389
+ - **Idempotency on `clientRequestId`:** a duplicate BALANCE purchase throws `409` (`err.isDuplicateRequest`); a duplicate CARD purchase **replays the same checkout session** (`r.idempotentReplay === true`, same URL — never a second charge), so a lost card-leg response is safely recovered by retrying with the *same* `clientRequestId`.
390
+ - INVO fee: **3.5% flat** (balance) · **3.5% + $0.30** (card). Too-small amounts throw `err.isAmountBelowMinimum` / `err.isBelowCardMinimum` (card < $0.50); a card total over $999.99 throws `err.isAboveCardMaximum`.
391
+ - Client-side validation (missing fields, bad funding source, quantity outside `1..1000`, total ≠ unit×qty, card USD bounds, non-E.164 `playerPhone`) throws **before** any network call.
394
392
  - Fulfill on the **`platform_commerce.purchased`** webhook; handle **`platform_commerce.refunded`** for reversals.
395
393
 
396
394
  ---
@@ -665,7 +663,7 @@ Helpers:
665
663
  | `.isInsufficientBalance` | item purchase failed (400); `required_amount` + `current_balance` on `.body` |
666
664
  | `.isDuplicateRequest` | idempotency-keyed request was a duplicate (409) |
667
665
  | `.isNotPlatformTenant` | Platform Commerce called by a non-platform tenant (403) — use `purchaseItem`/`createCheckout` instead |
668
- | `.isAmountBelowMinimum` / `.isBelowCardMinimum` | Platform Commerce amount too small for the fee to round up / card charge under $0.50 (400) |
666
+ | `.isAmountBelowMinimum` / `.isBelowCardMinimum` / `.isAboveCardMaximum` | Platform Commerce amount too small for the fee to round up / card charge under $0.50 / card charge over $999.99 (400) |
669
667
  | `.isAlreadyRefunded` | Platform Commerce refund of an already-refunded order (409) — treat as already done |
670
668
  | `.retryAfter` | seconds to back off on a 429 throttle |
671
669
  | `.isEnrollmentAuthorizationRequired` | first-enrollment needs the OTP grant → `enrollmentBegin`/`enrollmentVerify` |
@@ -706,7 +704,7 @@ try {
706
704
  | `purchaseItem(input)` | `{ status, transactionId, orderId, newBalance, previousBalance, currencyName, financialBreakdown?, raw }` — **game** tenant spending game currency on an in-game item |
707
705
  | `getItemPurchaseHistory({ playerEmail, limit?, offset? })` | `{ history, pagination, raw }` |
708
706
  | `getItemOrderDetails({ orderId? \| transactionId? \| clientRequestId? })` | `{ order, financialSummary, statusTimeline, raw }` |
709
- | `platformCommerce.purchase(input)` | `{ status, fundingSource, orderId, transactionId?, newBalance?, financialBreakdown?, clientSecret?, amountUsd?, raw }` — **ecommerce** (platform tenant); `balance` settles now, `card` returns a `clientSecret` |
707
+ | `platformCommerce.purchase(input)` | `{ status, fundingSource, orderId?, transactionId?, newBalance?, financialBreakdown?, sessionId?, checkoutUrl?, expiresAt?, amountUsd?, idempotentReplay?, raw }` — **ecommerce** (platform tenant); `balance` settles now, `card` returns a hosted-checkout `checkoutUrl` |
710
708
  | `platformCommerce.getStatus(orderId)` | `{ orderId, status, gameCurrencyAmount?, usdAmount?, paymentMethod?, createdAt?, raw }` |
711
709
  | `platformCommerce.refund({ orderId? \| clientRequestId?, reason? })` | `{ status, orderId?, fundingSource?, refundedAmount?, amountUnit?, feeRetained?, raw }` — pass **exactly one** id; INVO keeps its fee |
712
710
  | `getPlayerBalance({ playerEmail })` | `{ player, balances, summary, raw }` — **by email only** (no by-id route; use `InvoClient.getBalance()` client-side) |
@@ -738,10 +736,9 @@ Every method also accepts an optional final `{ signal }` (`AbortSignal`) for can
738
736
  | `getPendingCollect()` | `{ pending, raw }` — the player's own pending-to-collect list (player-token) |
739
737
  | `getDestinations({ direction? })` | `{ availableGames, sourceGameName, transferMode, … }` — where the player can send/transfer, metadata inline |
740
738
  | `getBalance()` | `{ gameId, gameName, balances, totalValue, currencyCount, hasFunds, raw }` — the player's balances for this game |
741
- | `platformCommerce.confirmCardPayment(clientSecret, { mount, publishableKey?, returnUrl?, submit?, appearance? })` | `{ status: "succeeded" \| "requires_action" \| "processing" \| "failed", paymentIntentId?, error?, raw }` — mount + confirm the Platform Commerce card leg |
742
- | `platformCommerce.mountCardPayment(clientSecret, { mount, publishableKey? })` | `{ element, confirm({ returnUrl? }), destroy() }` — the primitive: confirm from your own Pay button |
739
+ | `platformCommerce.mountCheckout(el, checkoutUrl, { onComplete? })` | `{ iframe, destroy() }` — optional embed of INVO's hosted checkout (or just `location.href = checkoutUrl`); `onComplete` fires on the page's origin-checked `INVO_CHECKOUT_COMPLETE` message |
743
740
 
744
- Every method throws `InvoError` on failure and takes an optional final `{ signal }`. Full inline types ship with the package. For the Platform Commerce card leg, set `commercePublishableKey` on the `InvoClient` config (or pass `publishableKey` per call); the processor JS is lazy-loaded from its CDN — nothing to bundle.
741
+ Every method throws `InvoError` on failure and takes an optional final `{ signal }`. Full inline types ship with the package. The Platform Commerce card leg needs **no keys and no payment code in the browser** — INVO's hosted page owns the card form.
745
742
 
746
743
  ---
747
744
 
@@ -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
@@ -153,6 +155,11 @@ var InvoError = class _InvoError extends Error {
153
155
  get isBelowCardMinimum() {
154
156
  return this.code === "BELOW_STRIPE_MINIMUM";
155
157
  }
158
+ /** True if a Platform Commerce CARD purchase exceeded the hosted checkout's single-charge
159
+ * cap of $999.99 (`ABOVE_CARD_MAXIMUM`, 400) — split the sale or lower the amount. */
160
+ get isAboveCardMaximum() {
161
+ return this.code === "ABOVE_CARD_MAXIMUM";
162
+ }
156
163
  /**
157
164
  * True if a Platform Commerce refund targeted an order that was already refunded
158
165
  * (409). Idempotent outcome — the original refund did happen, so treat this as
@@ -182,10 +189,11 @@ function errorFromResponse(status, body, requestId) {
182
189
  else if (typeof b["error_code"] === "string") code = b["error_code"];
183
190
  if (typeof b["error"] === "string") message = b["error"];
184
191
  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(
192
+ 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
193
  b["error"]
187
194
  )) {
188
195
  code = b["error"];
196
+ if (typeof b["message"] === "string" && b["message"]) message = b["message"];
189
197
  }
190
198
  } else if (typeof body === "string" && body.trim()) {
191
199
  message = body;
@@ -438,5 +446,5 @@ function toDestinationsResult(raw, direction) {
438
446
  }
439
447
 
440
448
  export { Http, InvoError, assertSecureBaseUrl, toDestinationsResult };
441
- //# sourceMappingURL=chunk-ZKYUSYK5.js.map
442
- //# sourceMappingURL=chunk-ZKYUSYK5.js.map
449
+ //# sourceMappingURL=chunk-SPTYWJDN.js.map
450
+ //# sourceMappingURL=chunk-SPTYWJDN.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
@@ -155,6 +157,11 @@ var InvoError = class _InvoError extends Error {
155
157
  get isBelowCardMinimum() {
156
158
  return this.code === "BELOW_STRIPE_MINIMUM";
157
159
  }
160
+ /** True if a Platform Commerce CARD purchase exceeded the hosted checkout's single-charge
161
+ * cap of $999.99 (`ABOVE_CARD_MAXIMUM`, 400) — split the sale or lower the amount. */
162
+ get isAboveCardMaximum() {
163
+ return this.code === "ABOVE_CARD_MAXIMUM";
164
+ }
158
165
  /**
159
166
  * True if a Platform Commerce refund targeted an order that was already refunded
160
167
  * (409). Idempotent outcome — the original refund did happen, so treat this as
@@ -184,10 +191,11 @@ function errorFromResponse(status, body, requestId) {
184
191
  else if (typeof b["error_code"] === "string") code = b["error_code"];
185
192
  if (typeof b["error"] === "string") message = b["error"];
186
193
  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(
194
+ 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
195
  b["error"]
189
196
  )) {
190
197
  code = b["error"];
198
+ if (typeof b["message"] === "string" && b["message"]) message = b["message"];
191
199
  }
192
200
  } else if (typeof body === "string" && body.trim()) {
193
201
  message = body;
@@ -558,184 +566,96 @@ function toBalanceRow(row) {
558
566
  raw: row
559
567
  };
560
568
  }
561
- var PROCESSOR_SRC = "https://js.stripe.com/v3";
562
- var processorScriptLoad;
563
- function loadProcessorScript() {
564
- if (typeof document === "undefined" || typeof window === "undefined") {
565
- return Promise.reject(
566
- new InvoError({
567
- message: "confirmCardPayment requires a browser DOM (window/document).",
568
- code: "DOM_UNAVAILABLE",
569
- status: 0
570
- })
571
- );
572
- }
573
- if (window.Stripe) return Promise.resolve();
574
- if (processorScriptLoad) return processorScriptLoad;
575
- 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", () => {
587
- processorScriptLoad = void 0;
588
- reject(
589
- new InvoError({
590
- message: "Failed to load the card processor script.",
591
- code: "PROCESSOR_LOAD_FAILED",
592
- status: 0
593
- })
594
- );
595
- });
596
- });
597
- return processorScriptLoad;
598
- }
599
- async function defaultLoadProcessor(publishableKey) {
600
- await loadProcessorScript();
601
- const factory = window.Stripe;
602
- if (typeof factory !== "function") {
603
- throw new InvoError({
604
- message: "The card processor was unavailable after loading.",
605
- code: "PROCESSOR_UNAVAILABLE",
606
- status: 0
607
- });
608
- }
609
- return factory(publishableKey);
610
- }
611
- function mapCardConfirm(res) {
612
- const raw = res;
613
- if (res.error) {
614
- return { status: "failed", error: res.error.message ?? "Card payment failed.", raw };
615
- }
616
- const pi = res.paymentIntent;
617
- const s = pi?.status;
618
- let status;
619
- if (s === "succeeded") status = "succeeded";
620
- else if (s === "processing") status = "processing";
621
- else if (s === "requires_action" || s === "requires_confirmation") status = "requires_action";
622
- else status = "failed";
623
- return { status, paymentIntentId: pi?.id, raw };
624
- }
625
- function resolveSubmit(opts) {
626
- if (opts.submit) {
627
- const el = typeof opts.submit === "string" ? typeof document !== "undefined" ? document.querySelector(opts.submit) : null : opts.submit;
628
- if (!el) {
629
- throw new InvoError({
630
- message: `confirmCardPayment could not find the submit element "${String(opts.submit)}".`,
631
- code: "SUBMIT_NOT_FOUND",
632
- status: 0
633
- });
634
- }
635
- return { el, created: false };
636
- }
637
- if (typeof document === "undefined") {
638
- throw new InvoError({
639
- message: "confirmCardPayment needs a submit button: pass `submit`, or use `mountCardPayment(...).confirm()` from your own button.",
640
- code: "SUBMIT_REQUIRED",
641
- status: 0
642
- });
643
- }
644
- const container = typeof opts.mount === "string" ? document.querySelector(opts.mount) : opts.mount;
645
- const btn = document.createElement("button");
646
- btn.type = "button";
647
- btn.textContent = opts.submitLabel ?? "Pay";
648
- (container ?? document.body).appendChild(btn);
649
- return { el: btn, created: true };
650
- }
651
569
  var PlatformCommerceClient = class {
652
- constructor(defaultPublishableKey) {
653
- this.defaultPublishableKey = defaultPublishableKey;
654
- }
655
570
  /**
656
- * Mount the Payment Element and get a session you confirm from your OWN Pay button.
657
- * This is the fully-controllable primitive (`confirmCardPayment` builds on it).
571
+ * Embed INVO's hosted checkout in an iframe and listen for completion.
658
572
  *
659
573
  * ```ts
660
- * const session = await invo.platformCommerce.mountCardPayment(clientSecret, {
661
- * mount: "#pay", publishableKey: "pk_live_…",
574
+ * const handle = invo.platformCommerce.mountCheckout("#checkout", checkoutUrl, {
575
+ * onComplete: () => showProcessing(), // then reconcile server-side
662
576
  * });
663
- * // on your Pay button click:
664
- * const r = await session.confirm({ returnUrl: location.href });
665
- * if (r.status === "succeeded") showProcessing();
666
- * session.destroy();
577
+ * // later: handle.destroy();
667
578
  * ```
579
+ *
580
+ * Or skip the helper and redirect: `location.href = checkoutUrl` (the buyer returns to
581
+ * the `successUrl`/`cancelUrl` you passed to the server `purchase()`).
582
+ *
583
+ * `onComplete` fires on the page's `INVO_CHECKOUT_COMPLETE` postMessage -- accepted ONLY
584
+ * from the checkout URL's own origin (any other window could forge the event). It is a
585
+ * UX signal: the sale is REAL only on the `platform_commerce.purchased` webhook, never
586
+ * on this client event.
668
587
  */
669
- async mountCardPayment(clientSecret, opts) {
670
- if (!clientSecret || !clientSecret.trim()) {
671
- throw new Error("mountCardPayment requires a `clientSecret`.");
588
+ mountCheckout(el, checkoutUrl, opts) {
589
+ if (typeof document === "undefined" || typeof window === "undefined") {
590
+ throw new InvoError({
591
+ message: "mountCheckout requires a browser DOM (window/document).",
592
+ code: "DOM_UNAVAILABLE",
593
+ status: 0
594
+ });
672
595
  }
673
- if (opts?.mount == null || typeof opts.mount === "string" && !opts.mount.trim()) {
674
- throw new Error("mountCardPayment requires a `mount` target (selector or element).");
596
+ if (!checkoutUrl || !checkoutUrl.trim()) {
597
+ throw new Error("mountCheckout requires the server-returned `checkoutUrl`.");
675
598
  }
676
- const pk = opts.publishableKey ?? this.defaultPublishableKey();
677
- if (!pk) {
599
+ let checkoutOrigin;
600
+ try {
601
+ const u = new URL(checkoutUrl);
602
+ const isLocal = u.hostname === "localhost" || u.hostname === "127.0.0.1";
603
+ if (u.protocol !== "https:" && !(u.protocol === "http:" && isLocal)) {
604
+ throw new Error("not https");
605
+ }
606
+ checkoutOrigin = u.origin;
607
+ } catch {
678
608
  throw new InvoError({
679
- message: "A card processor publishableKey is required \u2014 pass it in options, or set `commercePublishableKey` on the InvoClient config.",
680
- code: "MISSING_PUBLISHABLE_KEY",
609
+ message: "mountCheckout requires an absolute https checkoutUrl.",
610
+ code: "INVALID_INPUT",
681
611
  status: 0
682
612
  });
683
613
  }
684
- const load = opts.loadProcessor ?? defaultLoadProcessor;
685
- const processor = await load(pk);
686
- const elements = processor.elements({ clientSecret, appearance: opts.appearance });
687
- const element = elements.create("payment");
688
- element.mount(opts.mount);
689
- const confirm = async (confirmOpts) => {
690
- const returnUrl = confirmOpts?.returnUrl ?? opts.returnUrl;
691
- const res = await processor.confirmPayment({
692
- elements,
693
- confirmParams: returnUrl ? { return_url: returnUrl } : void 0,
694
- // Stay in-page unless the bank forces a redirect (then return_url completes it).
695
- redirect: "if_required"
614
+ const container = typeof el === "string" ? document.querySelector(el) : el;
615
+ if (!container) {
616
+ throw new InvoError({
617
+ message: `mountCheckout could not find the container "${String(el)}".`,
618
+ code: "MOUNT_NOT_FOUND",
619
+ status: 0
696
620
  });
697
- return mapCardConfirm(res);
621
+ }
622
+ const iframe = document.createElement("iframe");
623
+ iframe.src = checkoutUrl;
624
+ iframe.title = opts?.title ?? "INVO checkout";
625
+ if (opts?.className) iframe.className = opts.className;
626
+ iframe.style.width = "100%";
627
+ iframe.style.border = "0";
628
+ iframe.allow = "payment";
629
+ const onMessage = (event) => {
630
+ if (event.origin !== checkoutOrigin) return;
631
+ if (iframe.contentWindow && event.source !== iframe.contentWindow) return;
632
+ const msg = event.data;
633
+ if (!msg || msg.type !== "INVO_CHECKOUT_COMPLETE") return;
634
+ opts?.onComplete?.(
635
+ msg.data && typeof msg.data === "object" ? msg.data : {}
636
+ );
698
637
  };
638
+ window.addEventListener("message", onMessage);
639
+ container.appendChild(iframe);
699
640
  return {
700
- element,
701
- confirm,
641
+ iframe,
702
642
  destroy() {
703
- try {
704
- element.unmount?.();
705
- } catch {
706
- }
643
+ window.removeEventListener("message", onMessage);
644
+ iframe.remove();
707
645
  }
708
646
  };
709
647
  }
710
- /**
711
- * One-call mount + confirm. Mounts the Payment Element into `opts.mount` and resolves
712
- * when the payment is confirmed via a submit trigger — either `opts.submit` (your Pay
713
- * button, selector or element) or a minimal button the SDK renders inside `mount`. For
714
- * full control over the button, prefer {@link mountCardPayment}.
715
- */
716
- async confirmCardPayment(clientSecret, opts) {
717
- const session = await this.mountCardPayment(clientSecret, opts);
718
- const trigger = resolveSubmit(opts);
719
- return new Promise((resolve, reject) => {
720
- const finish = (settle) => {
721
- if (trigger.created) trigger.el.remove();
722
- session.destroy();
723
- settle();
724
- };
725
- const onClick = () => {
726
- trigger.el.removeEventListener("click", onClick);
727
- if ("disabled" in trigger.el) trigger.el.disabled = true;
728
- session.confirm().then(
729
- (r) => finish(() => resolve(r)),
730
- (e) => finish(() => reject(e))
731
- );
732
- };
733
- trigger.el.addEventListener("click", onClick);
734
- });
735
- }
736
648
  };
737
649
  var InvoClient = class {
738
650
  constructor(config) {
651
+ /**
652
+ * Platform Commerce (ecommerce) hosted-checkout embed. Use after
653
+ * `InvoServer.platformCommerce.purchase({ fundingSource: "card" })` returns a
654
+ * `checkoutUrl` — either redirect the buyer there, or embed it with
655
+ * `mountCheckout`. No card element, no processor dependency. See
656
+ * {@link PlatformCommerceClient}.
657
+ */
658
+ this.platformCommerce = new PlatformCommerceClient();
739
659
  if (!config.token) throw new Error("InvoClient requires a player `token`.");
740
660
  if (!config.baseUrl) throw new Error("InvoClient requires a `baseUrl`.");
741
661
  assertSecureBaseUrl(config.baseUrl);
@@ -750,8 +670,6 @@ var InvoClient = class {
750
670
  });
751
671
  this.auth = { kind: "bearer", token: config.token };
752
672
  this.refreshToken = config.refreshToken;
753
- this.commercePublishableKey = config.commercePublishableKey;
754
- this.platformCommerce = new PlatformCommerceClient(() => this.commercePublishableKey);
755
673
  }
756
674
  assertWebAuthn() {
757
675
  if (typeof navigator === "undefined" || !navigator.credentials) {