@invonetwork/web-sdk 3.37.0 → 3.38.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.
Files changed (33) hide show
  1. package/CHANGELOG.md +24 -0
  2. package/README.md +49 -8
  3. package/dist/{chunk-AUHRMREF.js → chunk-3HK32FE4.js} +3 -3
  4. package/dist/{chunk-KWAUFFDY.js → chunk-7B7MFAQ3.js} +33 -5
  5. package/dist/chunk-MOHWLDOQ.js +6 -0
  6. package/dist/{chunk-ZHEQAZLW.js → chunk-NS33T5FB.js} +64 -15
  7. package/dist/game-server.cjs +99 -22
  8. package/dist/game-server.d.cts +4 -4
  9. package/dist/game-server.d.ts +4 -4
  10. package/dist/game-server.js +5 -5
  11. package/dist/game.cjs +32 -4
  12. package/dist/game.d.cts +3 -3
  13. package/dist/game.d.ts +3 -3
  14. package/dist/game.js +3 -3
  15. package/dist/{hosted-approval-DS9gcCF5.d.cts → hosted-approval-B-kbdFDL.d.cts} +1 -1
  16. package/dist/{hosted-approval-Dv462L4e.d.ts → hosted-approval-CtAZ1Rzt.d.ts} +1 -1
  17. package/dist/index.cjs +31 -3
  18. package/dist/index.d.cts +4 -4
  19. package/dist/index.d.ts +4 -4
  20. package/dist/index.js +2 -2
  21. package/dist/{server-B9PtYZaM.d.cts → server-BWGl9v5j.d.cts} +93 -13
  22. package/dist/{server-B7Pw1HMp.d.ts → server-CaaP-Nc3.d.ts} +93 -13
  23. package/dist/server.cjs +99 -22
  24. package/dist/server.d.cts +3 -3
  25. package/dist/server.d.ts +3 -3
  26. package/dist/server.js +3 -3
  27. package/dist/{types-BdKpJX93.d.cts → types-DGgWWX1v.d.cts} +89 -9
  28. package/dist/{types-BdKpJX93.d.ts → types-DGgWWX1v.d.ts} +89 -9
  29. package/dist/{version-CuhMO-6s.d.cts → version-D_cJUvMp.d.cts} +1 -1
  30. package/dist/{version-CuhMO-6s.d.ts → version-D_cJUvMp.d.ts} +1 -1
  31. package/docs/merchant-of-record-tax.md +176 -0
  32. package/package.json +2 -1
  33. package/dist/chunk-MENRG67H.js +0 -6
package/CHANGELOG.md CHANGED
@@ -1,5 +1,29 @@
1
1
  # Changelog
2
2
 
3
+ ## 3.38.0
4
+
5
+ ### Minor Changes
6
+
7
+ - Tax on Merchant of Record sales. On the Merchant of Record tier INVO is the seller on card sales and handles the consumption tax: added on top in the US, included in the price everywhere else (the developer bears it and INVO's fee is worked out on the net). All additive; nothing changes for an integration that does not read the new fields.
8
+
9
+ - `CurrencyPurchaseQuoteBreakdown` gains `taxIncluded`, `taxIncludedUsd`, `taxAddedUsd`, `taxLabel`, `taxLine` ("Includes VAT 20% ($1.67)") and `taxPriceDisplay`, present only on a tax-inclusive sale. When `taxIncluded` is `true` the tax is inside `subtotalUsd` and `totalUsd = subtotalUsd + processingFeeUsd`.
10
+ - `PurchaseResult` (`purchaseCurrency()`) gains `taxIncluded`, `taxUsd`, `taxIncludedUsd`, `taxPriceDisplay`, `taxJurisdiction`, `taxRatePct`, `taxLabel` and `taxLine`, on a tax-inclusive sale only.
11
+ - New `TaxPriceDisplay` type (`"inclusive" | "exclusive" | string`).
12
+ - `InvoError.isSaleNotAvailableInCountry` (`SALE_NOT_AVAILABLE_IN_COUNTRY`, 409: the buyer is in a country where INVO does not yet sell as Merchant of Record; nothing was charged; not retryable) and `err.unavailableCountry`.
13
+ - Webhook types: the tax keys on `purchase.completed` (`charge_total_usd`, `subtotal_usd`, `tax_usd`, `tax_jurisdiction`, `tax_rate_pct`, `tax_price_display`, `tax_included`), `purchase.refunded` and `platform_commerce.refunded` (`tax_refunded_usd`, `tax_jurisdiction`, `tax_included`, `tax_price_display`), `platform_commerce.purchased` (`item_price_usd`, `tax_usd`, `tax_jurisdiction`, `tax_price_display`, `tax_included`, `tax_rate_pct`; `fee_breakdown.tax_set_aside_usd` documented) and `subscription.renewed` `funding` (`tax_usd`, `card_authorised_usd`, `tax_jurisdiction`, `tax_included_usd`, `tax_included`, `tax_price_display`, `tax_rate_pct`).
14
+ - New guide, docs/merchant-of-record-tax.md (shipped in the package and linked from the README): the worked $10 UK example, tax set aside while a registration is pending, refunds, the error and what to show buyers, and the console tax rows.
15
+
16
+ ## 3.37.1
17
+
18
+ ### Patch Changes
19
+
20
+ - Documentation only; no code or behavior change. Phone-share, player registration and guardian approval now match the server:
21
+
22
+ - `registerPlayer`: `"created"` means new to your title and can mean joining the person's existing INVO wallet (same email and phone), so `identityId` is the same one other games see; the token fields are omitted when INVO cannot issue a token; `503 sdk_verification_disabled` is listed.
23
+ - `err.isPhoneShareRefused` / `err.isPhoneShareApprovalRequired`: the refusal is not a dead end. INVO creates an approval request and asks the phone's existing owner (by email when INVO has verified their address, otherwise by a text code); retry the same call once they approve. An INVO wallet created in the INVO app counts as an owner of its phone. `err.phoneShareLast4` is the last 4 digits as a string, absent on older servers.
24
+ - `PhoneShareApproveResult`: describes what the approve endpoint returns (`status`, `approved`, `approval_id`, `phone`, `approved_email`, `approved_at`); `alreadyApproved` and `expiresAt` are not sent by it. Approval is permanent; there is no revoke.
25
+ - README: who is a minor (INVO sets no minimum age; INVO support marks a wallet as a minor on request; `isMinor` reads it), what the guardian gates (cross-game transfers, sends, wallet-app moves; not coin or item purchases, not receiving) and the 15-minute window.
26
+
3
27
  ## 3.37.0
4
28
 
5
29
  ### Minor Changes
package/README.md CHANGED
@@ -6,6 +6,8 @@ First-party TypeScript SDK for integrating **INVO** into partner **web** platfor
6
6
  > Canonical partner reference: **https://docs.invo.network/docs/currency-purchase** and **https://docs.invo.network/docs/game-developer-integration**.
7
7
  > **Selling on iOS?** Read the full guide: [Apple In-App Purchases (StoreKit 2)](https://github.com/Invo-Technologies/invo-web-sdk/blob/main/docs/apple-in-app-purchases.md).
8
8
 
9
+ > **On the Merchant of Record tier?** Read the full guide: [Tax on Merchant of Record sales](https://github.com/Invo-Technologies/invo-web-sdk/blob/main/docs/merchant-of-record-tax.md) (3.38.0): tax-inclusive prices outside the US (`taxIncluded`, `taxLine`), who bears the VAT, tax set aside while a registration is pending, and `err.isSaleNotAvailableInCountry`.
10
+
9
11
  ## What it does
10
12
 
11
13
  Six money flows plus passkey (WebAuthn) authentication, split across a trusted server entry and an untrusted browser entry:
@@ -99,6 +101,7 @@ The right approval method is a property of the **client the player is sitting in
99
101
  - [Before you go live](#before-you-go-live)
100
102
  - [Configuration](#configuration)
101
103
  - [Tiers](#tiers)
104
+ - [Tax on Merchant of Record sales](#tax-on-merchant-of-record-sales): full guide in [docs/merchant-of-record-tax.md](https://github.com/Invo-Technologies/invo-web-sdk/blob/main/docs/merchant-of-record-tax.md)
102
105
  - [Currency purchase (real money in)](#currency-purchase-real-money-in)
103
106
  - [The card maximum is INVO's, not the SDK's](#the-card-maximum-is-invos-not-the-sdks)
104
107
  - [INVO's card fee: quote, show, acknowledge](#invos-card-fee-quote-show-acknowledge)
@@ -211,7 +214,9 @@ An existing player's phone is **never changed** by this call. When it differs fr
211
214
  `phoneMismatch: true`. When the new phone is genuine, call
212
215
  `updatePlayerPhone({ playerEmail, newPhone })` to change it (see
213
216
  [Registering players and changing their phone](#registering-players-and-changing-their-phone)).
214
- A phone that already belongs to another email is a `409` (`err.isPhoneShareRefused`).
217
+ A phone that already belongs to another email is a `409` (`err.isPhoneShareRefused`): INVO asks the
218
+ phone's owner to approve, and the same call succeeds once they have (see
219
+ [Registering players and changing their phone](#registering-players-and-changing-their-phone)).
215
220
 
216
221
  If the player changed their number with INVO (a `player.phone_changed` webhook, or a
217
222
  `phoneMismatch` you did not cause), INVO's number is the current one: **never push the number
@@ -230,12 +235,29 @@ money routing keys off it:
230
235
  ### Registering players and changing their phone
231
236
 
232
237
  Two server calls, both authenticated with your game secret, neither moves money nor sends the
233
- player a message.
238
+ player a message. The one exception is a phone-share refusal (below): it contacts the phone's
239
+ **existing owner**, never the player you are registering.
234
240
 
235
241
  **`registerPlayer({ playerEmail, playerPhone, playerName? })`** creates the player in your
236
242
  title. It returns `status: "created"` (new) or `status: "exists"` (already in your title with
237
243
  that phone), the `identityId`, and a `playerToken` / `playerTokenExpiresAt` when INVO can issue
238
- one for your title, so you can hand the browser a token straight away.
244
+ one for your title, so you can hand the browser a token straight away. Both token fields are
245
+ omitted when INVO cannot issue a token, so check for them.
246
+
247
+ `"created"` means new to **your** title, not new to INVO. When the email and phone match an
248
+ existing INVO wallet (the person already uses INVO in another game, or in the INVO app), the
249
+ player joins that wallet: the `identityId` is derived from the email and phone, so it is the
250
+ same `identityId` other games see for that person. `registerPlayer` answers `503` with
251
+ `error: "sdk_verification_disabled"` while the SDK player routes are switched off.
252
+
253
+ **When the phone is held under a different email** (by a player in any game, or by an INVO
254
+ wallet, including one created in the INVO app that has no player in any game), the call is
255
+ refused with `409` `err.isPhoneShareRefused`. The refusal is not a dead end: INVO creates an
256
+ approval request and asks the phone's owner to approve (by email when INVO has verified their
257
+ address, otherwise by a text code; in the INVO app too when app notifications are on). Show
258
+ `err.message` (`err.phoneShareLast4` is the last 4 digits of the phone, when the server sends
259
+ it), then retry the same call once the owner approves: it succeeds. `phoneShareStatus` tells
260
+ you when. The approval is permanent and applies across the network.
239
261
 
240
262
  ```ts
241
263
  const reg = await invo.registerPlayer({
@@ -260,7 +282,7 @@ if (upd.identityRekeyed && upd.playerToken) handTokenToBrowser(upd.playerToken);
260
282
  | Refusal | HTTP | Means | Do |
261
283
  |---|---|---|---|
262
284
  | `err.isPhoneMismatch` (`PHONE_MISMATCH`) | 409 | `registerPlayer`: the player is already in your title with a **different** phone. Nothing changed. | Call `updatePlayerPhone` if the change is genuine. |
263
- | `err.isPhoneShareRefused` (`PHONE_SHARE_APPROVAL_REQUIRED`) | 409 | The phone belongs to another email. Nothing was created or changed. Same code as `err.isPhoneShareApprovalRequired`. | Show `err.message`; ask the player to check the number. |
285
+ | `err.isPhoneShareRefused` (`PHONE_SHARE_APPROVAL_REQUIRED`) | 409 | The phone is held under another email (a player or an INVO wallet). No player was created or changed, but INVO created an approval request and asked the phone's owner to approve. Same code as `err.isPhoneShareApprovalRequired`. | Show `err.message` (`err.phoneShareLast4` names the number); retry the same call once the owner approves (poll `phoneShareStatus`). |
264
286
  | `err.isPhoneChangeRequiresVerification` (`PHONE_CHANGE_REQUIRES_VERIFICATION`) | 409 | `updatePlayerPhone`: the player has secured this account, so the change needs the player's own confirmation. Nothing changed. `err.changeRequestEndpoint` names the route to use instead. | Call `requestPhoneChange` (see [Player-confirmed phone change](#player-confirmed-phone-change)). |
265
287
  | `err.isPlayerNotFound` | 404 | `updatePlayerPhone` (or `mintPlayerToken` without `playerPhone`): no player with that email in your title. | Create the player first (`registerPlayer`). |
266
288
  | `INVALID_INPUT` / `INVALID_PHONE` | 400 | A missing email or phone, or a phone INVO does not accept. | Fix the input. The SDK also refuses a non-E.164 phone before the network (`status === 0`). |
@@ -268,6 +290,7 @@ if (upd.identityRekeyed && upd.playerToken) handTokenToBrowser(upd.playerToken);
268
290
  | `err.isPendingTransfersToOldPhone` (`PENDING_TRANSFERS_TO_OLD_PHONE`) | 409 | `updatePlayerPhone`: sends or transfers to the player's current number are still waiting to be collected; changing the number now would strand them. Nothing changed. | Ask the player to collect them first (or wait until they expire), then retry. |
269
291
  | `err.isPendingTransfersToNewPhone` (`PENDING_TRANSFERS_TO_NEW_PHONE`) | 409 | `updatePlayerPhone`: sends or transfers to the new number are still waiting to be collected. Nothing changed. | Retry after they are collected or expire. |
270
292
  | `PHONE_UPDATE_UNAVAILABLE` | 503 | `updatePlayerPhone` could not be checked right now. Nothing changed. | Try again shortly. |
293
+ | `sdk_verification_disabled` (in `error`) | 503 | The SDK player routes are switched off in this environment. Nothing changed. | Retry later. |
271
294
 
272
295
  ### Player-confirmed phone change
273
296
 
@@ -528,6 +551,14 @@ The card terms above (card fee, international fee, minimum and chargeback guaran
528
551
  - **Receipts (Merchant of Record only).** INVO issues a receipt for every card sale and a refund receipt for every card refund, and emails it to the buyer when the buyer's email is known; the number is always issued (a pending refund's number follows once it settles) and always reaches you. The number and link reach you as `receiptNumber` / `receiptUrl` on `purchaseCurrency()`, `getOrderDetails()` (from `GET /order-details`, which returns `receipt_number` / `receipt_url`), `CheckoutClient.getPurchaseStatus()` (once `credited`), `platformCommerce.getStatus()` and a paid `firstCharge`, and as `receipt_number` / `receipt_url` on the `purchase.completed`, `platform_commerce.purchased` and `subscription.renewed` webhooks. The refund webhooks (`purchase.refunded`, `platform_commerce.refunded`, `subscription.refunded`) carry the refund receipt's. On Open, and on storefront rails, the fields are absent. Anyone with a `receiptUrl` can read the receipt.
529
552
  - **Chargeback reserve (Merchant of Record only).** Part of your share of each card-funded sale (Platform Commerce card sales, card subscription charges) is held, by default 10% for 90 days (terms may differ per account), then released automatically. It affects your withdrawable balance, not anything this SDK returns: see https://docs.invo.network/docs/tiers/ for the balance fields.
530
553
 
554
+ ### Tax on Merchant of Record sales
555
+
556
+ On Merchant of Record INVO is the seller on your card sales and handles the consumption tax. In the US tax is added on top of your price. **Outside the US your price includes the tax**: the buyer pays $10.00 and sees "Includes VAT 20% ($1.67)", the tax comes out of the price, and INVO's fee and your share are worked out on the net ($10.00 UK sale: $1.67 VAT, $8.33 net, $0.57 fee, $7.76 to you). Where INVO's registration is still pending the buyer sees no tax line but the tax is still set aside from your share. A buyer in a country not yet open to Merchant of Record sales (today the EU, until January 1, 2027) is refused before any charge with `409 SALE_NOT_AVAILABLE_IN_COUNTRY` (`err.isSaleNotAvailableInCountry`, `err.unavailableCountry`).
557
+
558
+ New in 3.38.0, all additive and present only on a tax-inclusive sale: `taxIncluded`, `taxIncludedUsd`, `taxAddedUsd`, `taxLabel`, `taxLine` and `taxPriceDisplay` on `quoteCurrencyPurchase().breakdown`; `taxIncluded`, `taxUsd`, `taxIncludedUsd`, `taxPriceDisplay`, `taxJurisdiction`, `taxRatePct`, `taxLabel` and `taxLine` on `purchaseCurrency()`; and the tax keys on `purchase.completed`, `purchase.refunded`, `platform_commerce.*` and `subscription.renewed` (`funding.tax_included_usd`). When `taxIncluded` is `true`, never add the tax to the price: show `totalUsd` and `taxLine` under it.
559
+
560
+ **Full guide: [Tax on Merchant of Record sales](https://github.com/Invo-Technologies/invo-web-sdk/blob/main/docs/merchant-of-record-tax.md)**, with the worked example, every field, the error and the console tax rows. Public docs: https://docs.invo.network/docs/merchant-of-record-tax
561
+
531
562
  ## Currency purchase (real money in)
532
563
 
533
564
  Buy game currency with real money. Authenticated by the **payment rail**, not a passkey — there's no WebAuthn step. Two paths:
@@ -1004,6 +1035,7 @@ const purchase = await server.purchaseCurrency({
1004
1035
  | `409 QUOTE_STALE` (`err.isQuoteStale`) | the acknowledged total is below the total INVO would charge now | nothing was charged; quote again, show `err.expectedTotalUsd`, retry with the new total and a new `purchaseReference` |
1005
1036
  | `400 BELOW_CARD_MINIMUM` (`err.isBelowCardMinimum`) | from 2026-10-27, a card purchase under the minimum card purchase (`err.minUsd`, `err.enforcedFrom`) | nothing was charged; raise the amount to at least `err.minUsd` |
1006
1037
  | `409 TAX_PLACE_UNAVAILABLE` (`err.isTaxPlaceUnavailable`) | Merchant of Record only: you acknowledged a taxed total, INVO could not read the buyer's tax location from the card, and the request carried no `country` | nothing was charged; retry (a new attempt usually reads the card), or send the `country` / `subdivision` you quoted with. `err.untaxedTotalUsd` is the total without tax |
1038
+ | `409 SALE_NOT_AVAILABLE_IN_COUNTRY` (`err.isSaleNotAvailableInCountry`) | Merchant of Record only: the buyer is in a country where INVO does not yet sell as Merchant of Record (`err.unavailableCountry`); also thrown by `quoteCurrencyPurchase()` | nothing was charged; show `err.message`, do not retry and do not ask for another card. See [Tax on Merchant of Record sales](#tax-on-merchant-of-record-sales) |
1007
1039
  | `400 AMOUNT_BELOW_FEE` (`err.isAmountBelowFee`, deprecated) | no longer returned: the card fee is not in the player's charge | keep the branch if you have one; it will not fire |
1008
1040
 
1009
1041
  Only a `success` response carries the fee fields (`processingFeeUsd`, `feeTakenFrom`, `partnerFeeUsd`, `internationalCardFeeUsd`); `requires_action` and `pending_payment` do not. `internationalCardFeeUsd` is `"0.00"` on a US card and on a card whose country cannot be determined (it counts as domestic). `partnerFeeUsd` and `internationalCardFeeUsd` are `null` only if the fee could not be booked when the purchase completed: the purchase succeeded and INVO books the fee shortly after. On a quote `internationalCardFeeUsd` is always `null`, since no card is known yet. Each field is exactly what INVO sent, or `undefined`: the SDK never fills one in. A purchase settled under the earlier pricing may read `feeTakenFrom: "charge"` or `"coins"`. Storefront rails bill no INVO card fee: the storefront takes its own cut.
@@ -1868,12 +1900,19 @@ try {
1868
1900
  sender is as before; what's new is that the sender gets an email and the recipient a single
1869
1901
  text saying the currency was returned, instead of silence. `transfer.claim_expired` +
1870
1902
  `transfer.refunded` remain the source of truth — reconcile off those, not the messages.
1871
- - **`err.isPhoneShareApprovalRequired` on `confirmReceipt*` / `claimTransfer` / `claimCurrency`** (409): the receiver phone is contested, so INVO **holds the money** and texts the phone owner to approve. Not a failure — show `err.message` verbatim (`err.phoneShareLast4` names the phone), then **retry the same call** once approved (it succeeds idempotently); on denial/expiry the sender is refunded. Same handling as the initiate-time phone-share 409.
1903
+ - **`err.isPhoneShareApprovalRequired` on `confirmReceipt*` / `claimTransfer` / `claimCurrency`** (409): the receiver phone is contested, so INVO **holds the money** and asks the phone owner to approve (by email when INVO has verified their address, otherwise by text). Not a failure — show `err.message` verbatim (`err.phoneShareLast4` names the phone), then **retry the same call** once approved (it succeeds idempotently); on denial/expiry the sender is refunded. Same handling as the initiate-time phone-share 409.
1872
1904
  - **`err.isIdentityCheckUnavailable` on `confirmReceipt*` / `claimTransfer` / `claimCurrency`** (503, retryable): INVO could not check the claim just now. Nothing was moved; retry the same call after a few seconds.
1873
1905
  - **Both games must be Live.** `initiateSend`/`initiateTransfer` throw `403` if either side is still in testing, and the two cases are **deliberately separate** because the fix differs: `err.isSourceGameNotLive` is **your** game (self-serve — switch it to Live in the console under Game Settings → Status), `err.isTargetGameNotLive` is the **destination** game, usually owned by another developer, so you can't flip it — show `err.message` and steer the player elsewhere via `getDestinations`. `err.gameStatus` carries the current state. Don't merge these into one "not live" branch; it produces a "go fix it" button that leads nowhere half the time.
1874
1906
  - **Steam titles** (dark until a title is Steam-distributed): `initiateSend`/`initiateTransfer` can throw `err.isSteamValueNonTransferable` (moving more than the non-Steam balance to a non-Steam destination — show `err.message`, cap the amount at `err.steamTransferableMax`; `err.steamOriginAmount` is the Steam-locked portion) or `err.isNonSteamValueIntoSteamBlocked` (non-Steam value into a Steam title). Prevent both up front: `getDestinations` rows carry **`acceptsSteamOriginValue`** — disable non-Steam destinations for a player holding Steam-purchased currency. **This is a rule about currency moving between titles, not about spending.** A player can spend any balance on items in any title, Steam-distributed or not, including currency bought through Steam, so an item purchase never fails on origin and there is nothing to branch on there.
1875
1907
  - Transfer self-claim may be disabled for your tenant; if it is, surface the claim-code path instead.
1876
1908
  - **Holds:** an approve/claim can return an HTTP 202 hold instead of success — inspect `result.holdReason` (`"RISK_HOLD"`, `"GUARDIAN_APPROVAL_PENDING"`, and on confirm-receipt `"RECIPIENT_IDENTITY_PENDING"`); success has no `holdReason` (and `next: "pending_claim"`). Terminal guardian outcomes throw (`GUARDIAN_APPROVAL_REJECTED`/`_EXPIRED`).
1909
+ - **Who is a minor.** INVO sets no minimum age for a wallet; your game's own age policy applies. A wallet
1910
+ is marked as a minor, and linked to a guardian's wallet, only by INVO support on request; it is not
1911
+ inferred from other signals. `getLinkedIdentities().isMinor` reads the flag (server-only), but it can
1912
+ change at any time, so handle the 202 everywhere. A minor's cross-game transfers, sends and INVO
1913
+ wallet-app moves need the guardian; buying coins, buying items and receiving money do not. The
1914
+ guardian has 15 minutes: with no answer the request expires and the money does not move. A minor with
1915
+ no usable guardian is refused with `403` `GUARDIAN_REQUIRED`.
1877
1916
  - **Guardian approval goes by email first.** When a minor's initiate returns the 202, the guardian gets a
1878
1917
  signed, single-use link to a hosted INVO page with Approve / Decline — not a text. A reply-YES text goes
1879
1918
  out only when the guardian has no verified email or the email could not be delivered. The raw 202
@@ -1890,7 +1929,9 @@ try {
1890
1929
  - **Phone-share and recipient-identity consents use the same hosted page.** On `err.isPhoneShareApprovalRequired`
1891
1930
  the phone's existing owner gets an emailed link (Allow / Decline) when INVO has itself proven an address for
1892
1931
  them — at most three holders, one email per request — and the 409 body carries `consent_channel: "email"`;
1893
- the OTP text goes out instead only when no proven holder exists (`consent_channel: "sms"`). The
1932
+ the OTP text goes out instead only when no proven holder exists (`consent_channel: "sms"`). An INVO wallet
1933
+ created in the INVO app counts as a holder of its phone, so registering a different email with that phone
1934
+ needs the wallet owner's approval. The
1894
1935
  `RECIPIENT_IDENTITY_PENDING` hold emails the phone owner's oldest verified address the same way. **Nothing
1895
1936
  changes for you:** same 409 / 202 codes, same poll-and-retry, and the typed-code and in-app approves still work.
1896
1937
 
@@ -2915,7 +2956,7 @@ export const POST = createWebhookHandler({
2915
2956
  | `player.phone_changed` | a player's phone changed (confirmed by the player, or by INVO support); sent to every game the player is in | store the new `identity_id` and re-mint the token (`player_email, previous_phone_masked, new_phone_masked, new_phone_included, changed_at, source, identity_id, previous_identity_id`; `new_phone` only for the game that requested the change). Never push your stored number back; ask the player. See [Player-confirmed phone change](#player-confirmed-phone-change) |
2916
2957
  | `payout.status_changed` | a payout of your balance to your bank | track the payout (`payout_id, status, previous_status, requested_amount_usd`, plus the payout fee: `offboarding_fee_pct, offboarding_fee_usd, offboarding_fee_cap_usd, net_payout_usd`, `null` on a payout recorded before the fee existed) |
2917
2958
 
2918
- On a Merchant of Record account, `purchase.completed`, `platform_commerce.purchased` and `subscription.renewed` for a card sale also carry `receipt_number` and `receipt_url` (the receipt INVO issued to the buyer), and `purchase.refunded`, `platform_commerce.refunded` and `subscription.refunded` carry the refund receipt's. Absent on Open. `purchase.completed` also carries `tax_treatment` (`"partner_responsible"` on Open).
2959
+ On a Merchant of Record account, `purchase.completed`, `platform_commerce.purchased` and `subscription.renewed` for a card sale also carry `receipt_number` and `receipt_url` (the receipt INVO issued to the buyer), and `purchase.refunded`, `platform_commerce.refunded` and `subscription.refunded` carry the refund receipt's. Absent on Open. `purchase.completed` also carries `tax_treatment` (`"partner_responsible"` on Open). On a Merchant of Record sale whose price includes the tax (outside the US), the purchase, refund and `platform_commerce.*` events add `tax_included` and `tax_price_display`, and `subscription.renewed` adds `funding.tax_included_usd`: see [Tax on Merchant of Record sales](#tax-on-merchant-of-record-sales).
2919
2960
 
2920
2961
  Don't block waiting on `purchase.failed` for the `game`/`steam` rails — they only emit `completed`/`refunded`. Reconcile off `*.completed` + the status endpoints. For Platform Commerce **card** orders, fulfill on `platform_commerce.purchased`, not the browser confirmation.
2921
2962
 
@@ -3048,7 +3089,7 @@ try {
3048
3089
  | `initiateTransfer(input)` | same as `initiateSend` |
3049
3090
  | `createCheckout(input)` | `{ sessionId, checkoutUrl, sessionToken?, expiresAt, expiresInSeconds, warnings?, minPurchaseWarning?, raw }` (`minPurchaseWarning` while an amount under INVO's minimum card purchase is still accepted), 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) |
3050
3091
  | `quoteCurrencyPurchase({ playerEmail, usdAmount, country?, subdivision? })` | `CurrencyPurchaseQuote`: `{ totalUsd, amountCents, subtotalUsd, processingFeeUsd, partnerFeeUsd?, internationalCardFeeUsd?, feeTakenFrom?, minPurchaseWarning?, coins, currencyName, breakdown, ifUnacknowledged, raw }`; moves no money; send `totalUsd` back as `acknowledgedTotalUsd` (see [INVO's card fee](#invos-card-fee-quote-show-acknowledge)) |
3051
- | `purchaseCurrency(input)` | `{ status, clientSecret?, paymentIntentId?, paymentUrl?, transactionId?, orderId?, newBalance?, processingFeeUsd?, feeTakenFrom?, partnerFeeUsd?, internationalCardFeeUsd?, minPurchaseWarning?, coinsCredited?, chargeTotalUsd?, receiptNumber?, receiptUrl?, raw }`; optional `acknowledgedTotalUsd`, `country` and `subdivision` inputs; `receiptNumber` / `receiptUrl` on Merchant of Record only |
3092
+ | `purchaseCurrency(input)` | `{ status, clientSecret?, paymentIntentId?, paymentUrl?, transactionId?, orderId?, newBalance?, processingFeeUsd?, feeTakenFrom?, partnerFeeUsd?, internationalCardFeeUsd?, minPurchaseWarning?, coinsCredited?, chargeTotalUsd?, receiptNumber?, receiptUrl?, taxIncluded?, taxUsd?, taxIncludedUsd?, taxPriceDisplay?, taxJurisdiction?, taxRatePct?, taxLabel?, taxLine?, raw }`; optional `acknowledgedTotalUsd`, `country` and `subdivision` inputs; `receiptNumber` / `receiptUrl` on Merchant of Record only; the `tax*` fields on a Merchant of Record tax-inclusive sale only |
3052
3093
  | `confirmPayment({ paymentIntentId, orderId? })` | `{ status, transactionId?, newBalance?, credited?, reasonCode?, raw }`; report success only on `credited: true` |
3053
3094
  | `getOrderDetails({ orderId? \| transactionId? })` | `{ order, financialSummary, statusTimeline, receiptNumber?, receiptUrl?, raw }`; the receipt fields on a Merchant of Record currency purchase only |
3054
3095
  | `appleProducts()` | `{ bundleId, canSell, unavailableReason, products: [{ productId, coins, label, priceUsd, active, available, unavailableReason }], raw }`; call before every Apple purchase and offer only `available` products. See [Apple In-App Purchases](#apple-in-app-purchases-storekit-2) |
@@ -1,4 +1,4 @@
1
- import { InvoError, assertSecureBaseUrl, Http, toPurchaseStatusResult, toPhoneChangeApprovalsResult, phoneChangeSignalMessage, toApprovePhoneChangeResult, toDestinationsResult, toLoyaltyCardsResult, toLoyaltyVaultResult, toRedeemRewardResult, toRewardsPageLink, buildGameEventBody, toReportGameEventResult } from './chunk-KWAUFFDY.js';
1
+ import { InvoError, assertSecureBaseUrl, Http, toPurchaseStatusResult, toPhoneChangeApprovalsResult, phoneChangeSignalMessage, toApprovePhoneChangeResult, toDestinationsResult, toLoyaltyCardsResult, toLoyaltyVaultResult, toRedeemRewardResult, toRewardsPageLink, buildGameEventBody, toReportGameEventResult } from './chunk-7B7MFAQ3.js';
2
2
 
3
3
  // src/shared/webauthn.ts
4
4
  function malformedOptions(field) {
@@ -1586,5 +1586,5 @@ var InvoClient = class {
1586
1586
  };
1587
1587
 
1588
1588
  export { CheckoutClient, InvoClient, PlatformCommerceClient };
1589
- //# sourceMappingURL=chunk-AUHRMREF.js.map
1590
- //# sourceMappingURL=chunk-AUHRMREF.js.map
1589
+ //# sourceMappingURL=chunk-3HK32FE4.js.map
1590
+ //# sourceMappingURL=chunk-3HK32FE4.js.map
@@ -82,7 +82,11 @@ var InvoError = class _InvoError extends Error {
82
82
  * - registration/token-mint (phone already on another INVO account), and
83
83
  * - **claim + confirm-receipt** (`claimTransfer`/`claimCurrency`,
84
84
  * `confirmReceiptSend`/`confirmReceiptTransfer`) — the receiver phone is contested,
85
- * so INVO holds the money and texts the phone owner to approve.
85
+ * so INVO holds the money and asks the phone owner to approve.
86
+ *
87
+ * Either way the 409 has already created an approval request and contacted the phone's
88
+ * existing owner: by email when INVO has verified their address, otherwise by a text code
89
+ * (the body's `consent_channel` says which).
86
90
  *
87
91
  * NOT a failure. Show `err.message` verbatim (the backend supplies the user-facing text;
88
92
  * `phoneShareLast4` tells the UI which phone), keep the funds pending, and **retry the same
@@ -99,7 +103,8 @@ var InvoError = class _InvoError extends Error {
99
103
  const v = this.bodyObject()["approval_id"];
100
104
  return typeof v === "string" && v ? v : void 0;
101
105
  }
102
- /** Last 4 digits of the phone that must approve (`phone_last4`), for the UI message. */
106
+ /** Last 4 digits of the phone that must approve (`phone_last4`, a string such as `"4567"`),
107
+ * for the UI message. `undefined` when the body has none (an older server). */
103
108
  get phoneShareLast4() {
104
109
  const v = this.bodyObject()["phone_last4"];
105
110
  return typeof v === "string" && v ? v : void 0;
@@ -538,6 +543,26 @@ var InvoError = class _InvoError extends Error {
538
543
  const v = this.bodyObject()["untaxed_total_usd"];
539
544
  return typeof v === "string" && v ? v : void 0;
540
545
  }
546
+ /**
547
+ * Additive (3.38.0). True when a Merchant of Record card sale was refused because the buyer is in
548
+ * a country where INVO does not yet sell as Merchant of Record (`SALE_NOT_AVAILABLE_IN_COUNTRY`,
549
+ * 409; today the EU member states until January 1, 2027). NOTHING WAS CHARGED. The body carries
550
+ * `retryable: false`: do not retry, and do not ask for another card (the refusal follows where
551
+ * the buyer is). Show the message (`err.message`), for example "Purchases aren't available in
552
+ * your country yet. Nothing was charged." Returned by the quote, the purchase, hosted checkout
553
+ * and Platform Commerce card purchases. Branch on this, never on a country list.
554
+ * See https://docs.invo.network/docs/merchant-of-record-tax#sale-not-available
555
+ */
556
+ get isSaleNotAvailableInCountry() {
557
+ return this.code === "SALE_NOT_AVAILABLE_IN_COUNTRY";
558
+ }
559
+ /** On `SALE_NOT_AVAILABLE_IN_COUNTRY`: the buyer's country, ISO 3166-1 alpha-2 (`country`), or
560
+ * `undefined` when INVO did not know it. */
561
+ get unavailableCountry() {
562
+ if (!this.isSaleNotAvailableInCountry) return void 0;
563
+ const v = this.bodyObject()["country"];
564
+ return typeof v === "string" && v ? v : void 0;
565
+ }
541
566
  /**
542
567
  * True if a Platform Commerce refund targeted an order that was already refunded
543
568
  * (409). Idempotent outcome — the original refund did happen, so treat this as
@@ -1072,7 +1097,10 @@ var InvoError = class _InvoError extends Error {
1072
1097
  /**
1073
1098
  * True when the phone you supplied belongs to another email
1074
1099
  * (`PHONE_SHARE_APPROVAL_REQUIRED`, 409) on `mintPlayerToken`, `registerPlayer` or
1075
- * `updatePlayerPhone`. Nothing was created or changed. The same condition as
1100
+ * `updatePlayerPhone`. The phone may be held by a player in any game or by an INVO wallet
1101
+ * (including one created in the INVO app). No player was created or changed, but INVO has
1102
+ * created an approval request and asked the phone's owner to approve; retry the same call
1103
+ * once they have and it succeeds. The same condition as
1076
1104
  * {@link isPhoneShareApprovalRequired}, named for these registration calls.
1077
1105
  */
1078
1106
  get isPhoneShareRefused() {
@@ -1897,5 +1925,5 @@ function toApprovePhoneChangeResult(raw, changeRequestId) {
1897
1925
  }
1898
1926
 
1899
1927
  export { Http, InvoError, assertSecureBaseUrl, buildGameEventBody, creditFields, isPurchaseCredited, isPurchaseExpired, isPurchaseRefunded, isPurchaseRefused, newEventId, nothingWasCharged, phoneChangeSignalMessage, receiptFields, toApprovePhoneChangeResult, toDestinationsResult, toLoyaltyCardsResult, toLoyaltyVaultResult, toPhoneChangeApprovalsResult, toPhoneChangeRequest, toPurchaseStatusResult, toRedeemRewardResult, toReportGameEventResult, toRequestPhoneChangeResult, toRewardsPageLink };
1900
- //# sourceMappingURL=chunk-KWAUFFDY.js.map
1901
- //# sourceMappingURL=chunk-KWAUFFDY.js.map
1928
+ //# sourceMappingURL=chunk-7B7MFAQ3.js.map
1929
+ //# sourceMappingURL=chunk-7B7MFAQ3.js.map
@@ -0,0 +1,6 @@
1
+ // src/version.ts
2
+ var SDK_VERSION = "3.38.0";
3
+
4
+ export { SDK_VERSION };
5
+ //# sourceMappingURL=chunk-MOHWLDOQ.js.map
6
+ //# sourceMappingURL=chunk-MOHWLDOQ.js.map
@@ -1,5 +1,5 @@
1
- import { SDK_VERSION } from './chunk-MENRG67H.js';
2
- import { InvoError, assertSecureBaseUrl, Http, toRequestPhoneChangeResult, toPhoneChangeRequest, toPurchaseStatusResult, receiptFields, creditFields, toLoyaltyCardsResult, buildGameEventBody, toReportGameEventResult, toDestinationsResult } from './chunk-KWAUFFDY.js';
1
+ import { SDK_VERSION } from './chunk-MOHWLDOQ.js';
2
+ import { InvoError, assertSecureBaseUrl, Http, toRequestPhoneChangeResult, toPhoneChangeRequest, toPurchaseStatusResult, receiptFields, creditFields, toLoyaltyCardsResult, buildGameEventBody, toReportGameEventResult, toDestinationsResult } from './chunk-7B7MFAQ3.js';
3
3
  import { createHmac, timingSafeEqual } from 'crypto';
4
4
 
5
5
  // src/shared/apple.ts
@@ -88,6 +88,39 @@ function toApplePurchaseResult(raw) {
88
88
  };
89
89
  }
90
90
 
91
+ // src/shared/tax-fields.ts
92
+ function str(v) {
93
+ return v == null ? void 0 : String(v);
94
+ }
95
+ function includedTaxFields(raw) {
96
+ const out = {};
97
+ if (typeof raw["tax_included"] === "boolean") out.taxIncluded = raw["tax_included"];
98
+ const inc = str(raw["tax_included_usd"]);
99
+ if (inc !== void 0) out.taxIncludedUsd = inc;
100
+ const display = str(raw["tax_price_display"]);
101
+ if (display !== void 0) out.taxPriceDisplay = display;
102
+ const label = str(raw["tax_label"]);
103
+ if (label !== void 0) out.taxLabel = label;
104
+ const line = str(raw["tax_line"]);
105
+ if (line !== void 0) out.taxLine = line;
106
+ return out;
107
+ }
108
+ function includedTaxBreakdownFields(raw) {
109
+ const out = includedTaxFields(raw);
110
+ const added = str(raw["tax_added_usd"]);
111
+ if (added !== void 0) out.taxAddedUsd = added;
112
+ return out;
113
+ }
114
+ function includedTaxPurchaseFields(raw) {
115
+ const out = includedTaxFields(raw);
116
+ if (out.taxIncluded !== true) return out;
117
+ const tax = str(raw["tax_usd"]);
118
+ if (tax !== void 0) out.taxUsd = tax;
119
+ if (Object.prototype.hasOwnProperty.call(raw, "tax_jurisdiction")) out.taxJurisdiction = str(raw["tax_jurisdiction"]) ?? null;
120
+ if (Object.prototype.hasOwnProperty.call(raw, "tax_rate_pct")) out.taxRatePct = str(raw["tax_rate_pct"]) ?? null;
121
+ return out;
122
+ }
123
+
91
124
  // src/payouts.ts
92
125
  var AMOUNT = /^\d+(\.\d{1,2})?$/;
93
126
  function invalidInput(label, value, why) {
@@ -663,6 +696,7 @@ function toQuoteBreakdown(row) {
663
696
  totalUsd: String(r["total_usd"] ?? ""),
664
697
  coins: String(r["coins"] ?? ""),
665
698
  currencyName: String(r["currency_name"] ?? ""),
699
+ ...includedTaxBreakdownFields(r),
666
700
  raw: r
667
701
  };
668
702
  }
@@ -2558,11 +2592,16 @@ var InvoServer = class {
2558
2592
  * Create a player in your game without moving money (`POST /api/sdk/players`), so a
2559
2593
  * first-time receiver can collect in-game. Sends no message to the player.
2560
2594
  *
2561
- * Returns `status: "created"` (new) or `"exists"` (already in your game with that
2562
- * phone), with a player token when INVO can issue one. Refusals: 409
2563
- * `err.isPhoneMismatch` (already in your game with a different phone; use
2564
- * `updatePlayerPhone`), 409 `err.isPhoneShareRefused` (the phone belongs to another
2565
- * email), 400 `INVALID_INPUT` / `INVALID_PHONE`, 429 (`err.retryAfter`).
2595
+ * Returns `status: "created"` (201, new to your game) or `"exists"` (200, already in
2596
+ * your game with that phone), with a player token when INVO can issue one (the token
2597
+ * fields are omitted otherwise). "created" can mean joining an existing INVO wallet:
2598
+ * the same email and phone as a wallet the person already has, so `identityId` is the
2599
+ * same one other games see. Refusals: 409 `err.isPhoneMismatch` (already in your game
2600
+ * with a different phone; use `updatePlayerPhone`), 409 `err.isPhoneShareRefused` (the
2601
+ * phone is held under another email, by a player or an INVO wallet: INVO asks the
2602
+ * phone's owner to approve, and the same call succeeds once they have), 400
2603
+ * `INVALID_INPUT` / `INVALID_PHONE`, 429 (`err.retryAfter`), 503
2604
+ * `sdk_verification_disabled` (the SDK player routes are switched off).
2566
2605
  */
2567
2606
  async registerPlayer(input, opts) {
2568
2607
  if (typeof input.playerEmail !== "string" || !input.playerEmail.trim()) {
@@ -2881,6 +2920,7 @@ var InvoServer = class {
2881
2920
  chargeTotalUsd: optionalDecimalString(raw["charge_total_usd"]),
2882
2921
  ...pricingFields(raw),
2883
2922
  ...receiptFields(raw),
2923
+ ...includedTaxPurchaseFields(raw),
2884
2924
  raw
2885
2925
  };
2886
2926
  }
@@ -2901,8 +2941,14 @@ var InvoServer = class {
2901
2941
  * accepted. Card purchases only; purchases through a third-party storefront or payment
2902
2942
  * rail are unaffected.
2903
2943
  *
2944
+ * Merchant of Record: in the US tax is added on top (`totalUsd` above the price); outside the
2945
+ * US the price includes the tax, and `breakdown.taxIncluded` is `true` with
2946
+ * `breakdown.taxLine` ("Includes VAT 20% ($1.67)") to show under `totalUsd`.
2947
+ *
2904
2948
  * Refusals: `400 INVALID_INPUT` (amount missing, not above zero, or above INVO's card
2905
- * maximum), `400 CURRENCY_NOT_CONFIGURED`, `503 RATE_UNAVAILABLE`.
2949
+ * maximum), `400 CURRENCY_NOT_CONFIGURED`, `503 RATE_UNAVAILABLE`, and on Merchant of Record
2950
+ * `409 SALE_NOT_AVAILABLE_IN_COUNTRY` (`err.isSaleNotAvailableInCountry`) for a buyer in a
2951
+ * country where INVO does not yet sell as Merchant of Record.
2906
2952
  */
2907
2953
  async quoteCurrencyPurchase(input, opts) {
2908
2954
  assertUsdAmount(input.usdAmount);
@@ -3738,7 +3784,9 @@ var InvoServer = class {
3738
3784
  *
3739
3785
  * These three endpoints are UNAUTHENTICATED (phone-owner-driven: no game secret,
3740
3786
  * no player token) — a partner backend relays the handshake. The triggering 409
3741
- * carries `approval_id, expires_at, code_sent, existing_account_hints[], next_endpoint`.
3787
+ * carries `approval_id, expires_at, code_sent, existing_account_hints[], next_endpoint`,
3788
+ * `phone_last4` and `consent_channel` (`"email"` when the owner was emailed a link,
3789
+ * so there is no code to collect; `"sms"` when a text code went out).
3742
3790
  *
3743
3791
  * `phoneShareInitiate` is the fallback OTP send (use when the 409 didn't already
3744
3792
  * dispatch a code). NOT idempotent — never auto-retried. OTP TTL ~10 min.
@@ -3761,10 +3809,11 @@ var InvoServer = class {
3761
3809
  return toPhoneShareInitiateResult(raw);
3762
3810
  }
3763
3811
  /**
3764
- * Approve a phone-share with the OTP the phone owner received. On success the grant
3765
- * is stored server-side, keyed by (phone, requesting_email) and auto-consumed — the
3766
- * caller simply RE-ISSUES the identical original request. UNAUTHENTICATED. NOT
3767
- * idempotent (attempts are counted) — never auto-retried.
3812
+ * Approve a phone-share with the OTP the phone owner received. On success the approval
3813
+ * is stored server-side, keyed by (phone, requesting_email), permanently and
3814
+ * network-wide (there is no revoke) — the caller simply RE-ISSUES the identical
3815
+ * original request. UNAUTHENTICATED. NOT idempotent (attempts are counted) — never
3816
+ * auto-retried.
3768
3817
  */
3769
3818
  async phoneShareApprove(input, opts) {
3770
3819
  if (typeof input.approvalId !== "string" || !input.approvalId.trim()) {
@@ -4118,5 +4167,5 @@ var InvoServer = class {
4118
4167
  };
4119
4168
 
4120
4169
  export { APPLE_FINISH_ERROR_CODES, CardsServer, DEMO_KEY_PREFIX, EnvironmentUnknownError, InvoServer, KeyEnvironmentMismatchError, LIVE_KEY_PREFIX, PRODUCTION_BASE_URL, PayoutsServer, PlatformCommerceServer, SANDBOX_BASE_URL, SandboxServer, SandboxSubscriptionsServer, SubscriptionsServer, TEST_KEY_PREFIX, assertKeyMatchesBaseUrl, assertKeyMatchesEnvironment, baseUrlForKey, createWebhookHandler, environmentForBaseUrl, environmentFromKeyPrefix, isAppleCreditPending, isDemoKey, isRefundPendingApproval, resolveEnvironment, shouldFinishAppleTransaction, verifyInvoSignature, verifyWebhook, verifyWebhookAsync };
4121
- //# sourceMappingURL=chunk-ZHEQAZLW.js.map
4122
- //# sourceMappingURL=chunk-ZHEQAZLW.js.map
4170
+ //# sourceMappingURL=chunk-NS33T5FB.js.map
4171
+ //# sourceMappingURL=chunk-NS33T5FB.js.map