@invonetwork/web-sdk 3.10.0 → 3.11.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
@@ -1,5 +1,31 @@
1
1
  # Changelog
2
2
 
3
+ ## 3.11.0
4
+
5
+ ### Minor Changes
6
+
7
+ - The purchase status read, and the subscription fee is 7%.
8
+
9
+ **A buyer can always be told what happened to the money they paid.** `invo.checkout` (and the standalone `CheckoutClient`, for a page with no player token) reads `GET /api/checkout/sessions/<id>`, authenticated by the SESSION token; the id in the path is a label, not a credential. `getPurchaseStatus({ sessionId, sessionToken })` reads once; `waitForPurchase({ ..., intervalMs, timeoutMs, maxAttempts, signal, onUpdate })` polls until INVO says it is finished and returns that result. Six statuses, four of them terminal, plus `orderId`, `coinsCredited` / `transactionId` / `newBalance` on a credit, `reasonCode` + a player-safe `message` on a refusal, and both money figures (`amountChargedUsd`, `listedUsd`) so a buyer billed 206.29 for a 200 pack can be shown where the 6.29 went.
10
+
11
+ `terminal` is read off the response and is NEVER recomputed from `status`, so a status a later backend introduces cannot make this build decide a purchase finished, or finished well. A status it does not recognise is not terminal and is never a success. `paid_pending_credit` is deliberately not terminal at any age: INVO's reconciler recovers a stalled credit. A failed poll is not a failed purchase: network, timeout, 429 and 5xx are polled through; 401, 403 and 410 are raised at once (`isWrongSessionPurpose`, `isCheckoutSessionMismatch`, `isCheckoutSessionExpired`). On the cap `waitForPurchase` returns the last result it read rather than throwing, so the page keeps showing something true.
12
+
13
+ `CheckoutPurchaseStatus` is a widened union (`… | (string & {})`), not a literal one, and a tsc test pins that partner code storing or comparing an unknown status still compiles, which is the fix 3.10.0 had to make to `RefundResult` after the fact. It is named `Checkout…` because `PurchaseStatus` is already the direct `purchaseCurrency` result and is unchanged. New: `CheckoutClient`, `InvoClient.checkout`, `isPurchaseCredited` / `isPurchaseRefused` / `isPurchaseRefunded` / `isPurchaseExpired`, `nothingWasCharged` (true only where INVO said no money was taken; everything else, an unknown code included, happened after the card was charged, so never put a Try again on it), and the types `PurchaseStatusResult`, `PurchaseStatusInput`, `WaitForPurchaseInput`, `PurchaseRefusalReason`, `PurchaseCredited` / `PurchaseRefused` / `PurchaseRefunded` / `PurchaseExpired`, `CheckoutClientConfig`.
14
+
15
+ `createCheckout()` now also returns `sessionToken`, read from INVO's `session_token` field (backend commit `856fa266`) and falling back to the `checkout_url` query string only for a server that predates it, so nothing has to parse a URL to use the read. The two cannot disagree, and if a response ever carried both and they differed the field wins, because a query-key spelling is not a contract.
16
+
17
+ **Doc fix: INVO's subscription fee is 7% plus $0.30, not 10%** ($9.99 pays INVO $1.00 and you $8.99). Subscriptions became their own rate on 2026-09-17; item purchases stay at 10/90. No code change.
18
+
19
+ **Not included: withdrawals.** INVO's withdrawal request and history reads gained additive `kyc_hold`, `kyc_hold_reason` and `next_steps` fields on 2026-09-17. This package exposes no withdrawal surface at all, so there is nowhere for them to go, and adding one is a separate decision rather than part of a documentation pass.
20
+
21
+ **Fixed: the User-Agent version had drifted.** `SDK_VERSION` was left at `3.10.0` when 3.10.1 published, so every server call from 3.10.1 reported a version that was not the one running, and the test pinning it to `package.json` was failing on `main`. Back in step, and the pin is green.
22
+
23
+ ## 3.10.1
24
+
25
+ ### Patch Changes
26
+
27
+ - `linkDevice()` takes no arguments. The server mints the link id, so requiring one was wrong: callers had to invent a placeholder. The parameter stays optional and any value passed is still sent and ignored by the server, so code written against 3.10 keeps working unchanged. The README now also states that a tenant whose players enrol a passkey on the tenant's own domain MUST offer `linkDevice()`, because that credential can only be asserted on that tenant's origin, and that recovery is never the answer to `ENROLLMENT_REQUIRES_PROOF`.
28
+
3
29
  ## 3.10.0
4
30
 
5
31
  ### Minor Changes
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:** `v3.10.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.10.0** documents **card-only subscriptions** (the card pays the full price every period, the coin wallet never pays; `walletOnly` deprecated; new `failure_code` `wallet_negative`; a renewal's `purchase.completed` is not a purchase) and the **[subscription refund limits](#refunds)**: `subscriptions.refund` can now return a 202 `pending_approval` refund request (`isRefundPendingApproval`), with `warnings`, the processor fee you bear, `subscriptionCanceled` (a full refund cancels), new classifiers (`isRefundsNotEnabled`, `isRefundWindowClosed`, `isRefundRequestPending`, `isRefundRequestRejected`, `isConcurrentRequest`, `isRefundMismatch`) and typed `subscription.refund_requested` / `refund_approved` / `refund_rejected` events, all additive; **3.9.0** adds the **[INVO-hosted card page for subscriptions](#cards-for-subscriptions)**, `invo.cards.createSetupSession`: mint a 10-minute link server-side, send the member to it, read the card back from `cards.list`, with no browser code and no card processor named anywhere (`beginSetup`/`confirmSetup` remain as the processor-bound alternative), plus the `isPlayerNotFound`, `isInvalidPlayerEmail` and `isInvalidInput` classifiers and a fix that makes `includePlayer` reads actually surface `playerEmail`/`playerName`; **3.8.0** adds **[Subscriptions](#subscriptions-recurring-billing)** as a first-class server surface on both rails — `invo.subscriptions.create/get/listForPlayer/cancel/changeAmount/setPaymentMethod/refund/steamInit/steamFinalize`, the off-session card capture (`invo.cards.beginSetup/confirmSetup/list`), the sandbox clock tools (`invo.sandbox.subscriptions.*`, which post to `/subscriptions/<id>/...` **relative to the sandbox base, not under `/api`**, with the new `sandboxClockKey`), typed `data` for all seven `subscription.*` webhook events, and eleven new error classifiers; **3.7.0** makes the **device approval grant a first-class SDK surface** — `beginDeviceApproval`, `pollDeviceApproval`, `confirmDeviceEnrollment` and, the step that actually moves the money, **`approveWithDeviceCode`** (plus the optional `completeDeviceApproval` loop); a grant that is polled to `approved` and left there settles **nothing**, which is the failure this release exists to make impossible, and `TRANSACTION_NOT_PENDING` now comes back as a typed `status: "not_pending"` result with `alreadySettled` rather than a thrown error you would have to string-match; **3.4.0** documents that a Steam title now bills through **its own Steam application** — the studio registers their appid + publisher Web API key and keeps a payment method on file, because Valve pays the studio and INVO settles afterwards (new `isSteamNotConfigured`, `isPartnerBillingNotSetUp`, `isPartnerSettlementUnavailable`, `isSteamAppChanged` error helpers); **3.2.3** corrects the base path and auth header in the Steam snippets (`/api/currency-purchases`, `X-Game-Secret-Key`) — 3.2.2 published both wrong, and copying them returned a 404; **3.2.x** documents **Steam currency purchases on a pack model** — INVO owns the catalogue, you pass a `pack_id` and never a price, and the currency inside a pack varies by country because Steam prices are VAT-inclusive; **3.1.0** makes the authentication guidance explicit — **[passkeys are the gold standard](#passkeys-are-the-gold-standard-dont-build-on-sms)** and the SMS-PIN completion (`verifySmsTransfer`/`verifySmsSend`) is **deprecated and being phased out** (documentation only — no behavior change, no runtime warnings); **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).
5
+ > **Status:** `v3.11.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.11.0** adds the **[purchase status read](#did-the-purchase-go-through-the-status-read)**, where `invo.checkout.getPurchaseStatus()` / `waitForPurchase()` (and the standalone `CheckoutClient`) answer what happened to a hosted-checkout purchase in six words, four of them terminal, so a buyer is never shown a page that closes on nothing; stopping is decided by INVO's `terminal` and never re-derived from `status`, `nothingWasCharged()` says when a **Try again** is safe, `createCheckout()` now also returns `sessionToken`, and the subscription fee is corrected to **7% + $0.30** (it is its own rate; item purchases stay at 10/90); **3.10.0** documents **card-only subscriptions** (the card pays the full price every period, the coin wallet never pays; `walletOnly` deprecated; new `failure_code` `wallet_negative`; a renewal's `purchase.completed` is not a purchase) and the **[subscription refund limits](#refunds)**: `subscriptions.refund` can now return a 202 `pending_approval` refund request (`isRefundPendingApproval`), with `warnings`, the processor fee you bear, `subscriptionCanceled` (a full refund cancels), new classifiers (`isRefundsNotEnabled`, `isRefundWindowClosed`, `isRefundRequestPending`, `isRefundRequestRejected`, `isConcurrentRequest`, `isRefundMismatch`) and typed `subscription.refund_requested` / `refund_approved` / `refund_rejected` events, all additive; **3.9.0** adds the **[INVO-hosted card page for subscriptions](#cards-for-subscriptions)**, `invo.cards.createSetupSession`: mint a 10-minute link server-side, send the member to it, read the card back from `cards.list`, with no browser code and no card processor named anywhere (`beginSetup`/`confirmSetup` remain as the processor-bound alternative), plus the `isPlayerNotFound`, `isInvalidPlayerEmail` and `isInvalidInput` classifiers and a fix that makes `includePlayer` reads actually surface `playerEmail`/`playerName`; **3.8.0** adds **[Subscriptions](#subscriptions-recurring-billing)** as a first-class server surface on both rails — `invo.subscriptions.create/get/listForPlayer/cancel/changeAmount/setPaymentMethod/refund/steamInit/steamFinalize`, the off-session card capture (`invo.cards.beginSetup/confirmSetup/list`), the sandbox clock tools (`invo.sandbox.subscriptions.*`, which post to `/subscriptions/<id>/...` **relative to the sandbox base, not under `/api`**, with the new `sandboxClockKey`), typed `data` for all seven `subscription.*` webhook events, and eleven new error classifiers; **3.7.0** makes the **device approval grant a first-class SDK surface** — `beginDeviceApproval`, `pollDeviceApproval`, `confirmDeviceEnrollment` and, the step that actually moves the money, **`approveWithDeviceCode`** (plus the optional `completeDeviceApproval` loop); a grant that is polled to `approved` and left there settles **nothing**, which is the failure this release exists to make impossible, and `TRANSACTION_NOT_PENDING` now comes back as a typed `status: "not_pending"` result with `alreadySettled` rather than a thrown error you would have to string-match; **3.4.0** documents that a Steam title now bills through **its own Steam application** — the studio registers their appid + publisher Web API key and keeps a payment method on file, because Valve pays the studio and INVO settles afterwards (new `isSteamNotConfigured`, `isPartnerBillingNotSetUp`, `isPartnerSettlementUnavailable`, `isSteamAppChanged` error helpers); **3.2.3** corrects the base path and auth header in the Steam snippets (`/api/currency-purchases`, `X-Game-Secret-Key`) — 3.2.2 published both wrong, and copying them returned a 404; **3.2.x** documents **Steam currency purchases on a pack model** — INVO owns the catalogue, you pass a `pack_id` and never a price, and the currency inside a pack varies by country because Steam prices are VAT-inclusive; **3.1.0** makes the authentication guidance explicit — **[passkeys are the gold standard](#passkeys-are-the-gold-standard-dont-build-on-sms)** and the SMS-PIN completion (`verifySmsTransfer`/`verifySmsSend`) is **deprecated and being phased out** (documentation only — no behavior change, no runtime warnings); **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
@@ -96,6 +96,7 @@ The right approval method is a property of the **client the player is sitting in
96
96
  - [Before you go live](#before-you-go-live)
97
97
  - [Configuration](#configuration)
98
98
  - [Currency purchase (real money in)](#currency-purchase-real-money-in)
99
+ - [Did the purchase go through? (the status read)](#did-the-purchase-go-through-the-status-read)
99
100
  - [Item purchase (spend game currency)](#item-purchase-spend-game-currency)
100
101
  - [Platform Commerce (ecommerce)](#platform-commerce-ecommerce)
101
102
  - [Subscriptions (recurring billing)](#subscriptions-recurring-billing)
@@ -287,7 +288,7 @@ Buy game currency with real money. Authenticated by the **payment rail**, not a
287
288
 
288
289
  ```ts
289
290
  // SERVER
290
- const { checkoutUrl, sessionId, expiresAt, expiresInSeconds } = await server.createCheckout({
291
+ const { checkoutUrl, sessionId, sessionToken, expiresAt, expiresInSeconds } = await server.createCheckout({
291
292
  playerEmail: "p@example.com",
292
293
  usdAmount: "20.00", // USD, 0 < x ≤ 999.99
293
294
  rail: "platform", // optional: "platform" (default) | "game" | "steam"
@@ -296,6 +297,7 @@ const { checkoutUrl, sessionId, expiresAt, expiresInSeconds } = await server.cre
296
297
  metadata: { yourOrderId: "ord_42" }, // echoed on the purchase.completed webhook (all rails); order_id also reconciles
297
298
  });
298
299
  // → send the browser to checkoutUrl. Token TTL is expiresInSeconds (~900s / 15 min).
300
+ // sessionToken is the credential for the status read below (INVO's own session_token field).
299
301
  // Reloading the URL after a completed payment is idempotent — it shows an already-complete
300
302
  // success screen (no error), so you don't have to guard against a refresh.
301
303
  ```
@@ -321,7 +323,59 @@ window.addEventListener("message", (e) => {
321
323
  });
322
324
  ```
323
325
 
324
- The hosted page handles card entry, saved cards, and 3-D Secure (with a top-level break-out when framed). **Grant currency off the `purchase.completed` webhook**, not the postMessage hint. Currency purchase has **no browser SDK method** — the browser only opens the URL.
326
+ The hosted page handles card entry, saved cards, and 3-D Secure (with a top-level break-out when framed). **Grant currency off the `purchase.completed` webhook**, not the postMessage hint. No browser SDK method *charges* (the browser only opens the URL), but it can now **read what happened**, below.
327
+
328
+ ### Did the purchase go through? (the status read)
329
+
330
+ `invo.checkout` answers, in six words, what a checkout purchase is doing. Poll it until INVO says it is finished and the buyer always has something true on screen, **including the case where INVO has their money and they do not have their coins**. That case used to close the page on nothing: no coins, no error, no receipt.
331
+
332
+ ```ts
333
+ // BROWSER (or Node: it needs no DOM)
334
+ import { CheckoutClient, isPurchaseCredited, nothingWasCharged } from "@invonetwork/web-sdk";
335
+
336
+ // `sessionId` and `sessionToken` come from the server's createCheckout(); the hosted page
337
+ // reads the token out of its own ?session= parameter. The token is the credential; the id
338
+ // in the path is only a label.
339
+ const checkout = new CheckoutClient({ baseUrl: "https://invo.network" });
340
+
341
+ const r = await checkout.waitForPurchase({
342
+ sessionId, sessionToken,
343
+ intervalMs: 1500, // every 1 to 2 seconds; the limit is 600 reads/min per IP
344
+ timeoutMs: 300_000, // the cap; on it you get the last result, never a throw
345
+ signal: controller.signal, // optional
346
+ onUpdate: (u) => render(u), // every read, terminal or not; keep the modal open
347
+ });
348
+
349
+ if (isPurchaseCredited(r)) {
350
+ show(`${r.coinsCredited} ${r.currencyName} added`, r.newBalance);
351
+ } else if (r.message) {
352
+ showVerbatim(r.message, r.orderId); // never paraphrase it
353
+ if (nothingWasCharged(r)) offerTryAgain(); // ONLY when INVO says nothing was taken
354
+ else offerContactSupport();
355
+ }
356
+ ```
357
+
358
+ `invo.checkout` is the same object on an `InvoClient` you already built, if the page has a player token. Read once instead with `checkout.getPurchaseStatus({ sessionId, sessionToken })`.
359
+
360
+ | `status` | `terminal` | What it means | What to show |
361
+ |---|---|---|---|
362
+ | `pending` | no | No payment seen for this checkout yet | keep the spinner |
363
+ | `paid_pending_credit` | no | A charge is open, the coins are not in the balance yet, normally seconds | keep the modal open ("Finishing your payment and adding your coins"); after ~60s add the order id and a **Contact support** link, and **keep polling** |
364
+ | `credited` | yes | Charged and credited | `coinsCredited`, `currencyName`, `newBalance` when not null; close on the buyer's action |
365
+ | `refused` | yes | This purchase will not credit; `reasonCode` says why | `message` verbatim + `orderId` + **Contact support** |
366
+ | `refunded` | yes | The money went back | `message` verbatim + `orderId` |
367
+ | `expired` | yes | Never paid, can no longer be paid | `message` verbatim; offer a new checkout |
368
+
369
+ Rules worth taking literally:
370
+
371
+ - **Stop on `result.terminal`, never on `status`.** `terminal` is INVO's answer and the SDK never recomputes it, so a status a later release adds cannot make this build decide a purchase finished, or finished *well*. An unknown status is never read as a success.
372
+ - **`paid_pending_credit` is not a failure, however long it takes.** INVO's reconciler recovers a stalled credit. Telling a buyer they lost money they are about to receive is worse than the silence.
373
+ - **A failed poll is not a failed purchase.** `waitForPurchase` polls through a dropped connection, a timeout, a 429 and a 5xx; it raises a `401`, `403` or `410` at once (`err.isWrongSessionPurpose`, `err.isCheckoutSessionMismatch`, `err.isCheckoutSessionExpired`).
374
+ - **Render `message` verbatim and never show `reasonCode` on its own.** The six post-charge refusal codes all read the same to a buyer (they paid and the coins are not there), and the code exists for support to quote. Offer a **Try again** only where `nothingWasCharged(r)` is true (`PAYMENT_DECLINED`, `PAYMENT_CANCELLED`, `expired`); every other refusal happened *after* the card was charged.
375
+ - **`expired` is not declared the second the link lapses.** A payment made in the last minutes of a checkout can leave no order row until a recovery sweep finds it, so an unpaid checkout reads `pending` for about 30 minutes past expiry. Poll through it.
376
+ - **`amountChargedUsd` minus `listedUsd`** is the processing fee the buyer pays on the card rail. A buyer billed 206.29 for a 200 pack will ask; both numbers are here.
377
+ - **Storefront (in-client) purchases do not reach this read.** Those orders are keyed on your own purchase reference rather than on a checkout session, so a lookup by session id finds nothing and answers `pending`. Do not conclude the purchase never happened.
378
+ - `newBalance` is `null` once the session is past its expiry: the token rides in the checkout URL, so a stale link must not serve a live wallet. `coinsCredited` and `transactionId`, which are about *this* purchase, still come back.
325
379
 
326
380
  ### Payment rails (neutral names)
327
381
 
@@ -616,7 +670,7 @@ A subscription is a standing agreement, created by **your server**, under which
616
670
 
617
671
  Each period INVO works out what the period is worth in coins (card: price × the currency's coins-per-USD rate, 10 per USD by default; Steam: what the price buys through Steam for the member's country) and splits it between INVO's platform fee and your revenue. Every figure is reported on the `subscription.renewed` event.
618
672
 
619
- - **Card rail: card only (since 2026-09-17).** The card is charged the full price every period, whatever the member's coin wallet holds. The coins that charge buys are minted and spent in the same step, so **the wallet never pays for a card subscription and never moves**. There is no shortfall, no rounding and no minimum top-up. INVO's fee is 10% by default plus $0.30, on the full price ($9.99 pays INVO $1.30 and you $8.69).
673
+ - **Card rail: card only (since 2026-09-17).** The card is charged the full price every period, whatever the member's coin wallet holds. The coins that charge buys are minted and spent in the same step, so **the wallet never pays for a card subscription and never moves**. There is no shortfall, no rounding and no minimum top-up. INVO's fee is 7% by default plus $0.30, on the full price ($9.99 pays INVO $1.00 and you $8.99). Subscriptions are their own rate: item purchases stay at 10/90.
620
674
  - **Steam rail: unchanged.** INVO spends the member's wallet first and tops up from Steam for the shortfall only.
621
675
  - **Save a card before `subscriptions.create`.** A member with coins but no saved card is still subscribed (the create succeeds), but the first charge fails with `failureCode: "no_payment_method"` and the subscription enters dunning. Coins never pay it.
622
676
  - **`walletOnly` is deprecated.** It is still accepted and returned, but a `walletOnly: true` card subscription never charges a card and so can never be paid: every charge fails with `failure_code: "wallet_only"` and it lapses to `expired`. Do not send it on new integrations.
@@ -1376,7 +1430,7 @@ await client.enrollPasskey();
1376
1430
  // Interchangeable methods (optional): prove an already-enrolled method (e.g. the INVO app
1377
1431
  // device key) to authorize adding THIS passkey, then enroll. Without this, enrolling a second
1378
1432
  // method is blocked with ENROLLMENT_REQUIRES_PROOF.
1379
- await client.linkDevice(linkId); // → { status: "authorized" }
1433
+ await client.linkDevice(); // → { status: "authorized" } (the server mints the link id)
1380
1434
  await client.enrollPasskey();
1381
1435
  ```
1382
1436
 
@@ -1394,7 +1448,7 @@ try {
1394
1448
  await client.enrollmentVerify(codeFromUser); // 6-digit OTP
1395
1449
  await client.enrollPasskey(); // retry — grant auto-consumed
1396
1450
  } else if (e instanceof InvoError && e.isEnrollmentProofRequired) {
1397
- await client.linkDevice(linkId); // a different method already exists
1451
+ await client.linkDevice(); // a different method already exists
1398
1452
  await client.enrollPasskey();
1399
1453
  } else throw e;
1400
1454
  }
@@ -1412,7 +1466,9 @@ try {
1412
1466
  await client.enrollPasskey();
1413
1467
  } catch (e) {
1414
1468
  if (e instanceof InvoError && e.isEnrollmentProofRequired) {
1415
- // Player still HAS the other method → linkDevice (above). Lost/deleted it → recover:
1469
+ // Player still HAS the other method → linkDevice (above). Lost/deleted it → recover.
1470
+ // READ `e.next` FIRST: "link" means the method still exists, so linkDevice, never recovery.
1471
+ // Recovery deactivates the working credential and starts a 24h money-out cooldown.
1416
1472
  await client.recoveryBegin(); // → { status:"sent", channels:["email"] } — email first; { channel: "sms" } to text instead
1417
1473
  await client.recoveryComplete(codeFromUser); // → { status:"recovered", deactivatedCount }
1418
1474
  await client.enrollPasskey(); // same call — now succeeds
@@ -1785,6 +1841,16 @@ const done = await server.completeDeviceApproval({
1785
1841
  the page refuses to enrol beside it with `409 ENROLLMENT_REQUIRES_PROOF` and tells the
1786
1842
  player to add this phone from where that method lives (`linkDevice`), then scan again. An
1787
1843
  identity with no method enrols freely.
1844
+ > **Partner-passkey tenants must implement `linkDevice`, or this is a dead end.** A passkey
1845
+ > is bound to the site that created it, so a credential on your domain cannot be asserted on
1846
+ > INVO's hosted page: only YOUR site can prove it. If your players enrol a passkey on your
1847
+ > domain (the usual web flow) and then use the hosted approval page, they WILL hit
1848
+ > `ENROLLMENT_REQUIRES_PROOF`, and the only way forward is your site calling `linkDevice()`.
1849
+ > Offer it as a plain "Link this phone" action on the same screen. Branch on the server's
1850
+ > verdict, not on guesswork: `ENROLLMENT_REQUIRES_PROOF` (`next: "link"`) means the player
1851
+ > still holds a working method, so link it. Recovery is for `PASSKEY_ALREADY_ENROLLED` or a
1852
+ > player who says the credential is gone, and it deactivates that credential and imposes a
1853
+ > 24 hour hold on moving money out, so never run it automatically.
1788
1854
  - **The code box on the page is the RFC 8628 `user_code`,** there for a TV with no camera.
1789
1855
  When the QR pre-fills it, the box isn't shown. It is not an SMS field.
1790
1856
  - **Currency purchases on a console go through that console's store**, as the platform
@@ -1976,7 +2042,7 @@ try {
1976
2042
  | `mintPlayerToken({ playerEmail, playerPhone? })` | `{ token, expiresAt, identityId }` — session mint for an **existing** player (404 if unknown); `playerPhone` optional/validated-if-present (see [Player token](#player-token-session-mint-for-an-existing-player)) |
1977
2043
  | `initiateSend(input)` | `{ transactionId, verificationMethod, guardianApproval?, raw }` |
1978
2044
  | `initiateTransfer(input)` | `{ transactionId, verificationMethod, guardianApproval?, raw }` |
1979
- | `createCheckout(input)` | `{ sessionId, checkoutUrl, expiresAt, expiresInSeconds, raw }` |
2045
+ | `createCheckout(input)` | `{ sessionId, checkoutUrl, sessionToken?, expiresAt, expiresInSeconds, raw }`, where `sessionToken` is INVO's own `session_token` field (falling back to the `checkoutUrl` query string on a backend that predates it) and is the credential for the [status read](#did-the-purchase-go-through-the-status-read) |
1980
2046
  | `purchaseCurrency(input)` | `{ status, clientSecret?, paymentIntentId?, paymentUrl?, transactionId?, orderId?, newBalance?, raw }` |
1981
2047
  | `confirmPayment({ paymentIntentId, orderId? })` | `{ status, transactionId?, newBalance?, raw }` |
1982
2048
  | `getOrderDetails({ orderId? \| transactionId? })` | `{ order, financialSummary, statusTimeline, raw }` |
@@ -2030,11 +2096,13 @@ Every method also accepts an optional final `{ signal }` (`AbortSignal`) for can
2030
2096
  | `recoveryBegin()` / `recoveryComplete(code)` | passkey recovery for `ENROLLMENT_REQUIRES_PROOF` when the passkey was lost/deleted (then retry `enrollPasskey`) — recovered keys can't move money OUT for 24h (`PASSKEY_RECOVERY_COOLDOWN`) |
2031
2097
  | `approveSend(txnId)` / `approveTransfer(txnId)` | `{ status, next, transactionId, claimCode?, claimCodeExpiresAt?, holdReason?, risk?, guardianApproval?, pollEndpoint?, raw }` |
2032
2098
  | `confirmReceiptSend(txnId)` / `confirmReceiptTransfer(txnId)` | `{ status, holdReason?, raw }` |
2033
- | `linkDevice(linkId)` | `{ status, raw }` |
2099
+ | `linkDevice()` | `{ status, raw }` — call with no arguments; the server mints the link id (a value passed by 3.10-era code is still accepted and ignored) |
2034
2100
  | `getPendingCollect()` | `{ pending, raw }` — the player's own pending-to-collect list (player-token) |
2035
2101
  | `getDestinations({ direction? })` | `{ availableGames, sourceGameName, transferMode, … }` — where the player can send/transfer, metadata inline |
2036
2102
  | `getBalance()` | `{ gameId, gameName, balances, totalValue, currencyCount, hasFunds, raw }` — the player's balances for this game |
2037
2103
  | `approveHosted({ transactionId, flow, platformOrigin?, onEnrollment?, renderPrompt?, popupBlocked?, popup?, signal? })` | `{ status: "approved" \| "denied" \| "expired" \| "closed" \| "blocked" \| "redirected", popupBlocked, message?, approval? }` — runs the whole RFC 8628 device-approval grant from the browser on INVO's hosted page (begin `channel:"popup"` → popup → poll → match-code prompt → confirm-enrollment → approve with the `device_code`, which the SDK holds and never exposes); `approval` is the `ApproveResult` / `ConfirmReceiptResult` of the flow's approve endpoint |
2104
+ | `checkout.getPurchaseStatus({ sessionId, sessionToken })` | `{ status, terminal, orderId, sessionId, coinsCredited, transactionId, newBalance, reasonCode, message, amountChargedUsd, listedUsd, currencyName, raw }`: what happened to a hosted-checkout purchase. Authenticated by the SESSION token, not the player token |
2105
+ | `checkout.waitForPurchase({ sessionId, sessionToken, intervalMs?, timeoutMs?, maxAttempts?, signal?, onUpdate? })` | the same result, polled until INVO's `terminal` is true (never re-derived from `status`); on the cap it returns the last result rather than throwing. Also available standalone: `new CheckoutClient({ baseUrl })` |
2038
2106
  | `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 |
2039
2107
 
2040
2108
  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.
@@ -667,6 +667,33 @@ var InvoError = class _InvoError extends Error {
667
667
  get isInvalidInput() {
668
668
  return this.code === "INVALID_INPUT";
669
669
  }
670
+ // ---- Checkout session reads (the purchase status read) ----
671
+ /**
672
+ * True when a session token was refused because it belongs to a DIFFERENT checkout
673
+ * session than the id in the path (`SESSION_MISMATCH`, 403). The token is the
674
+ * credential and the id is only a label, so the two have to agree; pair a `sessionId`
675
+ * with the `sessionToken` minted for it.
676
+ */
677
+ get isCheckoutSessionMismatch() {
678
+ return this.code === "SESSION_MISMATCH";
679
+ }
680
+ /**
681
+ * True when a token minted to SAVE A CARD was used where a purchase token belongs
682
+ * (`WRONG_SESSION_PURPOSE`, 401). A card setup session settles nothing and has no
683
+ * purchase to report on.
684
+ */
685
+ get isWrongSessionPurpose() {
686
+ return this.code === "WRONG_SESSION_PURPOSE";
687
+ }
688
+ /**
689
+ * True when a checkout session token is too far past its expiry to answer with
690
+ * (`SESSION_EXPIRED`, 410). A lapsed token still reads its own purchase for a bounded
691
+ * window, because a charge outlives a 15 minute link; past that, show the buyer the
692
+ * order id you already hold and a Contact support link rather than a blank screen.
693
+ */
694
+ get isCheckoutSessionExpired() {
695
+ return this.code === "SESSION_EXPIRED";
696
+ }
670
697
  /** Seconds to wait before retrying, when the backend throttled the call (429 `retry_after`). */
671
698
  get retryAfter() {
672
699
  const v = this.bodyObject()["retry_after"];
@@ -950,5 +977,5 @@ function toDestinationsResult(raw, direction) {
950
977
  }
951
978
 
952
979
  export { Http, InvoError, assertSecureBaseUrl, toDestinationsResult };
953
- //# sourceMappingURL=chunk-L4A6OV54.js.map
954
- //# sourceMappingURL=chunk-L4A6OV54.js.map
980
+ //# sourceMappingURL=chunk-ZDBU3L4T.js.map
981
+ //# sourceMappingURL=chunk-ZDBU3L4T.js.map
package/dist/index.cjs CHANGED
@@ -669,6 +669,33 @@ var InvoError = class _InvoError extends Error {
669
669
  get isInvalidInput() {
670
670
  return this.code === "INVALID_INPUT";
671
671
  }
672
+ // ---- Checkout session reads (the purchase status read) ----
673
+ /**
674
+ * True when a session token was refused because it belongs to a DIFFERENT checkout
675
+ * session than the id in the path (`SESSION_MISMATCH`, 403). The token is the
676
+ * credential and the id is only a label, so the two have to agree; pair a `sessionId`
677
+ * with the `sessionToken` minted for it.
678
+ */
679
+ get isCheckoutSessionMismatch() {
680
+ return this.code === "SESSION_MISMATCH";
681
+ }
682
+ /**
683
+ * True when a token minted to SAVE A CARD was used where a purchase token belongs
684
+ * (`WRONG_SESSION_PURPOSE`, 401). A card setup session settles nothing and has no
685
+ * purchase to report on.
686
+ */
687
+ get isWrongSessionPurpose() {
688
+ return this.code === "WRONG_SESSION_PURPOSE";
689
+ }
690
+ /**
691
+ * True when a checkout session token is too far past its expiry to answer with
692
+ * (`SESSION_EXPIRED`, 410). A lapsed token still reads its own purchase for a bounded
693
+ * window, because a charge outlives a 15 minute link; past that, show the buyer the
694
+ * order id you already hold and a Contact support link rather than a blank screen.
695
+ */
696
+ get isCheckoutSessionExpired() {
697
+ return this.code === "SESSION_EXPIRED";
698
+ }
672
699
  /** Seconds to wait before retrying, when the backend throttled the call (429 `retry_after`). */
673
700
  get retryAfter() {
674
701
  const v = this.bodyObject()["retry_after"];
@@ -1635,6 +1662,49 @@ async function runHostedApproval(opts, api, deps = {}) {
1635
1662
  });
1636
1663
  }
1637
1664
 
1665
+ // src/shared/purchase-status.ts
1666
+ function str(v) {
1667
+ return typeof v === "string" ? v : v === null || v === void 0 ? null : String(v);
1668
+ }
1669
+ function toPurchaseStatusResult(raw, sessionId) {
1670
+ return {
1671
+ status: String(raw["status"] ?? ""),
1672
+ // INVO SAYS, AND ONLY AN EXPLICIT `true` SAYS IT. A missing or malformed field reads
1673
+ // false, which keeps a poll running; the alternative, guessing terminality from
1674
+ // `status`, is how an old SDK declares a future status finished.
1675
+ terminal: raw["terminal"] === true,
1676
+ orderId: str(raw["order_id"]),
1677
+ sessionId: String(raw["session_id"] ?? sessionId),
1678
+ coinsCredited: str(raw["coins_credited"]),
1679
+ transactionId: str(raw["transaction_id"]),
1680
+ newBalance: str(raw["new_balance"]),
1681
+ reasonCode: str(raw["reason_code"]),
1682
+ message: str(raw["message"]),
1683
+ amountChargedUsd: str(raw["amount_charged_usd"]),
1684
+ listedUsd: str(raw["listed_usd"]),
1685
+ currencyName: str(raw["currency_name"]),
1686
+ raw
1687
+ };
1688
+ }
1689
+ function isPurchaseCredited(r) {
1690
+ return r.status === "credited";
1691
+ }
1692
+ function isPurchaseRefused(r) {
1693
+ return r.status === "refused";
1694
+ }
1695
+ function isPurchaseRefunded(r) {
1696
+ return r.status === "refunded";
1697
+ }
1698
+ function isPurchaseExpired(r) {
1699
+ return r.status === "expired";
1700
+ }
1701
+ var NOTHING_CHARGED_REASONS = /* @__PURE__ */ new Set(["PAYMENT_DECLINED", "PAYMENT_CANCELLED"]);
1702
+ function nothingWasCharged(r) {
1703
+ if (r.status === "expired") return true;
1704
+ if (r.status !== "refused") return false;
1705
+ return r.reasonCode !== null && NOTHING_CHARGED_REASONS.has(r.reasonCode);
1706
+ }
1707
+
1638
1708
  // src/index.ts
1639
1709
  function toPendingCollectItem(row) {
1640
1710
  return {
@@ -1766,6 +1836,163 @@ var PlatformCommerceClient = class {
1766
1836
  };
1767
1837
  }
1768
1838
  };
1839
+ var DEFAULT_PURCHASE_POLL_INTERVAL_MS = 1500;
1840
+ var DEFAULT_PURCHASE_POLL_TIMEOUT_MS = 18e4;
1841
+ function pollSleep(ms, signal) {
1842
+ return new Promise((resolve) => {
1843
+ if (signal?.aborted) return resolve();
1844
+ const timer = setTimeout(done, ms);
1845
+ const onAbort = () => done();
1846
+ function done() {
1847
+ clearTimeout(timer);
1848
+ signal?.removeEventListener("abort", onAbort);
1849
+ resolve();
1850
+ }
1851
+ signal?.addEventListener("abort", onAbort, { once: true });
1852
+ });
1853
+ }
1854
+ function isTransientPollFailure(err) {
1855
+ if (!(err instanceof InvoError)) return false;
1856
+ if (err.code === "ABORTED") return false;
1857
+ return err.status === 0 || err.status === 429 || err.status >= 500;
1858
+ }
1859
+ var CheckoutClient = class _CheckoutClient {
1860
+ constructor(config) {
1861
+ if (!config?.baseUrl) throw new Error("CheckoutClient requires a `baseUrl`.");
1862
+ assertSecureBaseUrl(config.baseUrl);
1863
+ this.http = new Http({
1864
+ baseUrl: config.baseUrl,
1865
+ timeoutMs: config.timeoutMs,
1866
+ fetchImpl: config.fetch,
1867
+ maxRetries: config.maxRetries,
1868
+ retryBaseDelayMs: config.retryBaseDelayMs,
1869
+ hooks: config.hooks
1870
+ });
1871
+ }
1872
+ /**
1873
+ * Wrap an `Http` the owning client already built, so `invo.checkout` shares that
1874
+ * client's baseUrl, timeout, retry budget and observability hooks.
1875
+ *
1876
+ * @internal Not part of the public API; it takes an internal type and may change.
1877
+ */
1878
+ static _withHttp(http) {
1879
+ const client = Object.create(_CheckoutClient.prototype);
1880
+ client.http = http;
1881
+ return client;
1882
+ }
1883
+ /**
1884
+ * Read a purchase's status once.
1885
+ *
1886
+ * Answers `200` with a {@link PurchaseStatusResult} for every state of the purchase,
1887
+ * including "we have your money and your coins are not there". There is no tenant gate
1888
+ * on it: a partner suspended after a buyer's card was charged is exactly the case it
1889
+ * exists for.
1890
+ *
1891
+ * Throws an {@link InvoError} on `401` (no token, bad signature, or a card-setup token:
1892
+ * `err.isWrongSessionPurpose`), `403` (a valid token for a DIFFERENT session:
1893
+ * `err.isCheckoutSessionMismatch`) and `410` (the token is more than 24 hours past its
1894
+ * expiry: `err.isCheckoutSessionExpired`; show the buyer the order id you already have
1895
+ * and a Contact support link).
1896
+ *
1897
+ * Storefront (in-client) purchases are keyed on the partner's own purchase reference
1898
+ * rather than on a checkout session, so a read by session id finds nothing and answers
1899
+ * `pending`. Do not conclude from that that such a purchase never happened.
1900
+ */
1901
+ async getPurchaseStatus(input, opts) {
1902
+ const sessionId = String(input?.sessionId ?? "").trim();
1903
+ const sessionToken = String(input?.sessionToken ?? "").trim();
1904
+ if (!sessionId) {
1905
+ throw new InvoError({
1906
+ message: "getPurchaseStatus requires `sessionId` (from createCheckout).",
1907
+ code: "INVALID_INPUT",
1908
+ status: 0
1909
+ });
1910
+ }
1911
+ if (!sessionToken) {
1912
+ throw new InvoError({
1913
+ message: "getPurchaseStatus requires `sessionToken`. The session token is the credential; the id in the path is not.",
1914
+ code: "INVALID_INPUT",
1915
+ status: 0
1916
+ });
1917
+ }
1918
+ const raw = await this.http.get(
1919
+ `/api/checkout/sessions/${encodeURIComponent(sessionId)}`,
1920
+ { kind: "bearer", token: sessionToken },
1921
+ { signal: opts?.signal }
1922
+ );
1923
+ return toPurchaseStatusResult(raw, sessionId);
1924
+ }
1925
+ /**
1926
+ * Poll {@link getPurchaseStatus} until INVO says the purchase is finished, and return
1927
+ * that final result.
1928
+ *
1929
+ * ```ts
1930
+ * const result = await invo.checkout.waitForPurchase({
1931
+ * sessionId, sessionToken,
1932
+ * intervalMs: 1500,
1933
+ * timeoutMs: 300_000,
1934
+ * signal: controller.signal,
1935
+ * onUpdate: (r) => render(r), // keep the modal open on every non-terminal read
1936
+ * });
1937
+ * if (isPurchaseCredited(result)) showCoins(result.coinsCredited, result.currencyName);
1938
+ * else if (result.message) showMessage(result.message, result.orderId); // verbatim
1939
+ * ```
1940
+ *
1941
+ * IT STOPS ON `result.terminal` AND ON NOTHING ELSE. `terminal` is INVO's word, read off
1942
+ * the response; this loop never recomputes it from `status`, so a status a later backend
1943
+ * introduces cannot end a wait here as a success. `paid_pending_credit` is deliberately
1944
+ * not terminal and is never promoted to a failure by age: INVO's reconciler recovers a
1945
+ * stalled credit, and telling a buyer they lost money they are about to receive would
1946
+ * be a fresh lie in place of the old silence.
1947
+ *
1948
+ * A transient failure (network, timeout, 429, 5xx) is polled through rather than raised;
1949
+ * a `401`, `403` or `410` is raised at once. On the cap it returns the LAST result it
1950
+ * read, whose `terminal` is false. Nothing is guessed and nothing is thrown, so the page
1951
+ * keeps showing the buyer what INVO last said. If it never got a single answer, the last
1952
+ * transport failure is thrown.
1953
+ */
1954
+ async waitForPurchase(input) {
1955
+ const intervalMs = Math.max(0, input?.intervalMs ?? DEFAULT_PURCHASE_POLL_INTERVAL_MS);
1956
+ const timeoutMs = Math.max(0, input?.timeoutMs ?? DEFAULT_PURCHASE_POLL_TIMEOUT_MS);
1957
+ const maxAttempts = input?.maxAttempts === void 0 ? Number.POSITIVE_INFINITY : Math.max(1, input.maxAttempts);
1958
+ const deadline = Date.now() + timeoutMs;
1959
+ const signal = input?.signal;
1960
+ let last;
1961
+ let lastFailure;
1962
+ for (let attempts = 0; ; ) {
1963
+ if (signal?.aborted) {
1964
+ throw new InvoError({
1965
+ message: "waitForPurchase was aborted",
1966
+ code: "ABORTED",
1967
+ status: 0
1968
+ });
1969
+ }
1970
+ attempts += 1;
1971
+ try {
1972
+ const result = await this.getPurchaseStatus(input, { signal });
1973
+ last = result;
1974
+ lastFailure = void 0;
1975
+ try {
1976
+ input?.onUpdate?.(result);
1977
+ } catch {
1978
+ }
1979
+ if (result.terminal) return result;
1980
+ } catch (err) {
1981
+ if (!isTransientPollFailure(err)) throw err;
1982
+ lastFailure = err;
1983
+ }
1984
+ if (attempts >= maxAttempts) break;
1985
+ if (Date.now() + intervalMs >= deadline) break;
1986
+ await pollSleep(intervalMs, signal);
1987
+ }
1988
+ if (last) return last;
1989
+ throw lastFailure instanceof Error ? lastFailure : new InvoError({
1990
+ message: "waitForPurchase could not read the purchase status before the cap.",
1991
+ code: "PURCHASE_STATUS_UNAVAILABLE",
1992
+ status: 0
1993
+ });
1994
+ }
1995
+ };
1769
1996
  var InvoClient = class {
1770
1997
  constructor(config) {
1771
1998
  /**
@@ -1790,6 +2017,7 @@ var InvoClient = class {
1790
2017
  });
1791
2018
  this.auth = { kind: "bearer", token: config.token };
1792
2019
  this.refreshToken = config.refreshToken;
2020
+ this.checkout = CheckoutClient._withHttp(this.http);
1793
2021
  }
1794
2022
  assertWebAuthn() {
1795
2023
  if (typeof navigator === "undefined" || !navigator.credentials) {
@@ -1911,15 +2139,22 @@ var InvoClient = class {
1911
2139
  * blocked with ENROLLMENT_REQUIRES_PROOF.
1912
2140
  *
1913
2141
  * begin -> navigator.credentials.get() -> complete with { link_id, webauthn_assertion }.
2142
+ *
2143
+ * Call it with no arguments: `await invo.linkDevice()`. THE SERVER MINTS THE
2144
+ * LINK ID, so there is nothing for the caller to supply. The parameter is kept
2145
+ * (optional, and sent but ignored by the server) so that code written against
2146
+ * 3.10 and earlier, which had to pass a placeholder, keeps compiling and
2147
+ * working unchanged.
1914
2148
  */
1915
2149
  async linkDevice(linkId, opts) {
1916
- if (!linkId) throw new Error("linkDevice requires a `linkId`.");
1917
2150
  this.assertWebAuthn();
1918
2151
  const signal = opts?.signal;
1919
2152
  return this.withTokenRetry(async () => {
1920
2153
  const begin = await this.post(
1921
2154
  "/api/sdk/device/link/webauthn/begin",
1922
- { link_id: linkId },
2155
+ // The server ignores the body and mints its own id; `linkId` travels only
2156
+ // for callers who still pass one.
2157
+ linkId ? { link_id: linkId } : {},
1923
2158
  signal
1924
2159
  );
1925
2160
  const cred = await navigator.credentials.get({
@@ -2167,8 +2402,14 @@ var InvoClient = class {
2167
2402
  }
2168
2403
  };
2169
2404
 
2405
+ exports.CheckoutClient = CheckoutClient;
2170
2406
  exports.InvoClient = InvoClient;
2171
2407
  exports.InvoError = InvoError;
2172
2408
  exports.PlatformCommerceClient = PlatformCommerceClient;
2409
+ exports.isPurchaseCredited = isPurchaseCredited;
2410
+ exports.isPurchaseExpired = isPurchaseExpired;
2411
+ exports.isPurchaseRefunded = isPurchaseRefunded;
2412
+ exports.isPurchaseRefused = isPurchaseRefused;
2413
+ exports.nothingWasCharged = nothingWasCharged;
2173
2414
  //# sourceMappingURL=index.cjs.map
2174
2415
  //# sourceMappingURL=index.cjs.map