@invonetwork/web-sdk 2.5.1 → 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,41 @@ 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
+
7
42
  ## [2.5.1] — 2026-07-20
8
43
 
9
44
  Hardening patch from a second, independent post-release audit (correctness vs the backend
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.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).
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
 
@@ -155,6 +155,11 @@ var InvoError = class _InvoError extends Error {
155
155
  get isBelowCardMinimum() {
156
156
  return this.code === "BELOW_STRIPE_MINIMUM";
157
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
+ }
158
163
  /**
159
164
  * True if a Platform Commerce refund targeted an order that was already refunded
160
165
  * (409). Idempotent outcome — the original refund did happen, so treat this as
@@ -441,5 +446,5 @@ function toDestinationsResult(raw, direction) {
441
446
  }
442
447
 
443
448
  export { Http, InvoError, assertSecureBaseUrl, toDestinationsResult };
444
- //# sourceMappingURL=chunk-5X3ESHJR.js.map
445
- //# sourceMappingURL=chunk-5X3ESHJR.js.map
449
+ //# sourceMappingURL=chunk-SPTYWJDN.js.map
450
+ //# sourceMappingURL=chunk-SPTYWJDN.js.map
package/dist/index.cjs CHANGED
@@ -157,6 +157,11 @@ var InvoError = class _InvoError extends Error {
157
157
  get isBelowCardMinimum() {
158
158
  return this.code === "BELOW_STRIPE_MINIMUM";
159
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
+ }
160
165
  /**
161
166
  * True if a Platform Commerce refund targeted an order that was already refunded
162
167
  * (409). Idempotent outcome — the original refund did happen, so treat this as
@@ -561,216 +566,96 @@ function toBalanceRow(row) {
561
566
  raw: row
562
567
  };
563
568
  }
564
- var PROCESSOR_SRC = "https://js.stripe.com/v3";
565
- var PROCESSOR_LOAD_TIMEOUT_MS = 1e4;
566
- var processorScriptLoad;
567
- function loadProcessorScript() {
568
- if (typeof document === "undefined" || typeof window === "undefined") {
569
- return Promise.reject(
570
- new InvoError({
571
- message: "confirmCardPayment requires a browser DOM (window/document).",
572
- code: "DOM_UNAVAILABLE",
573
- status: 0
574
- })
575
- );
576
- }
577
- if (window.Stripe) return Promise.resolve();
578
- if (processorScriptLoad) return processorScriptLoad;
579
- processorScriptLoad = new Promise((resolve, reject) => {
580
- const fail = () => {
581
- processorScriptLoad = void 0;
582
- reject(
583
- new InvoError({
584
- message: "Failed to load the card processor script.",
585
- code: "PROCESSOR_LOAD_FAILED",
586
- status: 0
587
- })
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();
614
- });
615
- document.head.appendChild(script);
616
- });
617
- return processorScriptLoad;
618
- }
619
- async function defaultLoadProcessor(publishableKey) {
620
- await loadProcessorScript();
621
- const factory = window.Stripe;
622
- if (typeof factory !== "function") {
623
- throw new InvoError({
624
- message: "The card processor was unavailable after loading.",
625
- code: "PROCESSOR_UNAVAILABLE",
626
- status: 0
627
- });
628
- }
629
- return factory(publishableKey);
630
- }
631
- function mapCardConfirm(res) {
632
- const raw = res;
633
- if (res.error) {
634
- return { status: "failed", error: res.error.message ?? "Card payment failed.", raw };
635
- }
636
- const pi = res.paymentIntent;
637
- const s = pi?.status;
638
- let status;
639
- if (s === "succeeded") status = "succeeded";
640
- else if (s === "processing") status = "processing";
641
- else if (s === "requires_action" || s === "requires_confirmation") status = "requires_action";
642
- else status = "failed";
643
- return { status, paymentIntentId: pi?.id, raw };
644
- }
645
- function resolveSubmit(opts) {
646
- if (opts.submit) {
647
- const el = typeof opts.submit === "string" ? typeof document !== "undefined" ? document.querySelector(opts.submit) : null : opts.submit;
648
- if (!el) {
649
- throw new InvoError({
650
- message: `confirmCardPayment could not find the submit element "${String(opts.submit)}".`,
651
- code: "SUBMIT_NOT_FOUND",
652
- status: 0
653
- });
654
- }
655
- return { el, created: false };
656
- }
657
- if (typeof document === "undefined") {
658
- throw new InvoError({
659
- message: "confirmCardPayment needs a submit button: pass `submit`, or use `mountCardPayment(...).confirm()` from your own button.",
660
- code: "SUBMIT_REQUIRED",
661
- status: 0
662
- });
663
- }
664
- const container = typeof opts.mount === "string" ? document.querySelector(opts.mount) : opts.mount;
665
- const btn = document.createElement("button");
666
- btn.type = "button";
667
- btn.textContent = opts.submitLabel ?? "Pay";
668
- (container ?? document.body).appendChild(btn);
669
- return { el: btn, created: true };
670
- }
671
569
  var PlatformCommerceClient = class {
672
- constructor(defaultPublishableKey) {
673
- this.defaultPublishableKey = defaultPublishableKey;
674
- }
675
570
  /**
676
- * Mount the Payment Element and get a session you confirm from your OWN Pay button.
677
- * This is the fully-controllable primitive (`confirmCardPayment` builds on it).
571
+ * Embed INVO's hosted checkout in an iframe and listen for completion.
678
572
  *
679
573
  * ```ts
680
- * const session = await invo.platformCommerce.mountCardPayment(clientSecret, {
681
- * mount: "#pay", publishableKey: "pk_live_…",
574
+ * const handle = invo.platformCommerce.mountCheckout("#checkout", checkoutUrl, {
575
+ * onComplete: () => showProcessing(), // then reconcile server-side
682
576
  * });
683
- * // on your Pay button click:
684
- * const r = await session.confirm({ returnUrl: location.href });
685
- * if (r.status === "succeeded") showProcessing();
686
- * session.destroy();
577
+ * // later: handle.destroy();
687
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.
688
587
  */
689
- async mountCardPayment(clientSecret, opts) {
690
- if (!clientSecret || !clientSecret.trim()) {
691
- 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
+ });
692
595
  }
693
- if (opts?.mount == null || typeof opts.mount === "string" && !opts.mount.trim()) {
694
- 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`.");
695
598
  }
696
- const pk = opts.publishableKey ?? this.defaultPublishableKey();
697
- 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 {
698
608
  throw new InvoError({
699
- message: "A card processor publishableKey is required \u2014 pass it in options, or set `commercePublishableKey` on the InvoClient config.",
700
- code: "MISSING_PUBLISHABLE_KEY",
609
+ message: "mountCheckout requires an absolute https checkoutUrl.",
610
+ code: "INVALID_INPUT",
701
611
  status: 0
702
612
  });
703
613
  }
704
- const load = opts.loadProcessor ?? defaultLoadProcessor;
705
- const processor = await load(pk);
706
- const elements = processor.elements({ clientSecret, appearance: opts.appearance });
707
- const element = elements.create("payment");
708
- element.mount(opts.mount);
709
- const confirm = async (confirmOpts) => {
710
- const returnUrl = confirmOpts?.returnUrl ?? opts.returnUrl;
711
- const res = await processor.confirmPayment({
712
- elements,
713
- confirmParams: returnUrl ? { return_url: returnUrl } : void 0,
714
- // Stay in-page unless the bank forces a redirect (then return_url completes it).
715
- 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
716
620
  });
717
- 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
+ );
718
637
  };
638
+ window.addEventListener("message", onMessage);
639
+ container.appendChild(iframe);
719
640
  return {
720
- element,
721
- confirm,
641
+ iframe,
722
642
  destroy() {
723
- try {
724
- element.unmount?.();
725
- } catch {
726
- }
643
+ window.removeEventListener("message", onMessage);
644
+ iframe.remove();
727
645
  }
728
646
  };
729
647
  }
730
- /**
731
- * One-call mount + confirm. Mounts the Payment Element into `opts.mount` and resolves
732
- * when the payment is confirmed via a submit trigger — either `opts.submit` (your Pay
733
- * button, selector or element) or a minimal button the SDK renders inside `mount`. For
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.
744
- */
745
- async confirmCardPayment(clientSecret, opts) {
746
- const session = await this.mountCardPayment(clientSecret, opts);
747
- let trigger;
748
- try {
749
- trigger = resolveSubmit(opts);
750
- } catch (e) {
751
- session.destroy();
752
- throw e;
753
- }
754
- return new Promise((resolve, reject) => {
755
- const finish = (settle) => {
756
- if (trigger.created) trigger.el.remove();
757
- session.destroy();
758
- settle();
759
- };
760
- const onClick = () => {
761
- trigger.el.removeEventListener("click", onClick);
762
- if ("disabled" in trigger.el) trigger.el.disabled = true;
763
- session.confirm().then(
764
- (r) => finish(() => resolve(r)),
765
- (e) => finish(() => reject(e))
766
- );
767
- };
768
- trigger.el.addEventListener("click", onClick);
769
- });
770
- }
771
648
  };
772
649
  var InvoClient = class {
773
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();
774
659
  if (!config.token) throw new Error("InvoClient requires a player `token`.");
775
660
  if (!config.baseUrl) throw new Error("InvoClient requires a `baseUrl`.");
776
661
  assertSecureBaseUrl(config.baseUrl);
@@ -785,8 +670,6 @@ var InvoClient = class {
785
670
  });
786
671
  this.auth = { kind: "bearer", token: config.token };
787
672
  this.refreshToken = config.refreshToken;
788
- this.commercePublishableKey = config.commercePublishableKey;
789
- this.platformCommerce = new PlatformCommerceClient(() => this.commercePublishableKey);
790
673
  }
791
674
  assertWebAuthn() {
792
675
  if (typeof navigator === "undefined" || !navigator.credentials) {
package/dist/index.d.cts CHANGED
@@ -1,47 +1,26 @@
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';
1
+ import { M as MountCheckoutOptions, C as CheckoutMountHandle, a as ClientConfig, b as CallOptions, A as ApproveResult, c as ConfirmReceiptResult, L as LinkDeviceResult, P as PendingCollectResult, D as DestinationsQuery, d as DestinationsResult, B as BalanceResult, E as EnrollmentBeginResult, e as EnrollmentVerifyResult, R as RecoveryBeginResult, f as RecoveryCompleteResult } from './types-DMNXAGiw.cjs';
2
+ export { g as BalanceRow, h as DestinationGame, I as InvoError, i as InvoErrorInfo, j as InvoHooks, k as InvoRequestInfo, l as InvoResponseInfo, m as PendingCollectItem, n as Rail, V as VerificationMethod } from './types-DMNXAGiw.cjs';
3
3
 
4
- /**
5
- * Platform Commerce card confirmation (browser side). The server (`InvoServer.
6
- * platformCommerce.purchase` with `fundingSource:"card"`) returns a `clientSecret`; this
7
- * mounts the processor's Payment Element (card / Apple Pay / Google Pay) and confirms it.
8
- * The sale is real only on the `platform_commerce.purchased` webhook — treat a "succeeded"
9
- * here as "show processing", never as fulfilled.
10
- */
11
4
  declare class PlatformCommerceClient {
12
- private readonly defaultPublishableKey;
13
- constructor(defaultPublishableKey: () => string | undefined);
14
5
  /**
15
- * Mount the Payment Element and get a session you confirm from your OWN Pay button.
16
- * This is the fully-controllable primitive (`confirmCardPayment` builds on it).
6
+ * Embed INVO's hosted checkout in an iframe and listen for completion.
17
7
  *
18
8
  * ```ts
19
- * const session = await invo.platformCommerce.mountCardPayment(clientSecret, {
20
- * mount: "#pay", publishableKey: "pk_live_…",
9
+ * const handle = invo.platformCommerce.mountCheckout("#checkout", checkoutUrl, {
10
+ * onComplete: () => showProcessing(), // then reconcile server-side
21
11
  * });
22
- * // on your Pay button click:
23
- * const r = await session.confirm({ returnUrl: location.href });
24
- * if (r.status === "succeeded") showProcessing();
25
- * session.destroy();
12
+ * // later: handle.destroy();
26
13
  * ```
27
- */
28
- mountCardPayment(clientSecret: string, opts: MountCardPaymentOptions): Promise<CardPaymentSession>;
29
- /**
30
- * One-call mount + confirm. Mounts the Payment Element into `opts.mount` and resolves
31
- * when the payment is confirmed via a submit trigger — either `opts.submit` (your Pay
32
- * button, selector or element) or a minimal button the SDK renders inside `mount`. For
33
- * full control over the button, prefer {@link mountCardPayment}.
34
14
  *
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.
15
+ * Or skip the helper and redirect: `location.href = checkoutUrl` (the buyer returns to
16
+ * the `successUrl`/`cancelUrl` you passed to the server `purchase()`).
17
+ *
18
+ * `onComplete` fires on the page's `INVO_CHECKOUT_COMPLETE` postMessage -- accepted ONLY
19
+ * from the checkout URL's own origin (any other window could forge the event). It is a
20
+ * UX signal: the sale is REAL only on the `platform_commerce.purchased` webhook, never
21
+ * on this client event.
43
22
  */
44
- confirmCardPayment(clientSecret: string, opts: ConfirmCardPaymentOptions): Promise<CardPaymentResult>;
23
+ mountCheckout(el: string | HTMLElement, checkoutUrl: string, opts?: MountCheckoutOptions): CheckoutMountHandle;
45
24
  }
46
25
  declare class InvoClient {
47
26
  private readonly http;
@@ -49,11 +28,11 @@ declare class InvoClient {
49
28
  private readonly refreshToken;
50
29
  /** In-flight refresh, shared so concurrent expiries trigger a single re-mint. */
51
30
  private refreshInFlight;
52
- private readonly commercePublishableKey;
53
31
  /**
54
- * Platform Commerce (ecommerce) card confirmation. Use after
32
+ * Platform Commerce (ecommerce) hosted-checkout embed. Use after
55
33
  * `InvoServer.platformCommerce.purchase({ fundingSource: "card" })` returns a
56
- * `clientSecret`. The passkey/token flows never touch this. See
34
+ * `checkoutUrl` — either redirect the buyer there, or embed it with
35
+ * `mountCheckout`. No card element, no processor dependency. See
57
36
  * {@link PlatformCommerceClient}.
58
37
  */
59
38
  readonly platformCommerce: PlatformCommerceClient;
@@ -179,4 +158,4 @@ declare class InvoClient {
179
158
  private confirmReceipt;
180
159
  }
181
160
 
182
- export { ApproveResult, BalanceResult, CallOptions, CardPaymentResult, CardPaymentSession, ClientConfig, ConfirmCardPaymentOptions, ConfirmReceiptResult, DestinationsQuery, DestinationsResult, EnrollmentBeginResult, EnrollmentVerifyResult, InvoClient, LinkDeviceResult, MountCardPaymentOptions, PendingCollectResult, PlatformCommerceClient, RecoveryBeginResult, RecoveryCompleteResult };
161
+ export { ApproveResult, BalanceResult, CallOptions, CheckoutMountHandle, ClientConfig, ConfirmReceiptResult, DestinationsQuery, DestinationsResult, EnrollmentBeginResult, EnrollmentVerifyResult, InvoClient, LinkDeviceResult, MountCheckoutOptions, PendingCollectResult, PlatformCommerceClient, RecoveryBeginResult, RecoveryCompleteResult };