@invonetwork/web-sdk 3.34.0 → 3.35.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 +20 -0
- package/README.md +104 -11
- package/dist/chunk-6763YM7P.js +6 -0
- package/dist/{chunk-R65CANFG.js → chunk-BGCSSWVL.js} +105 -3
- package/dist/{chunk-DMTNU5PM.js → chunk-SCFK6IVH.js} +3 -3
- package/dist/{chunk-D2AUZRYS.js → chunk-XN6MCLQV.js} +231 -70
- package/dist/game-server.cjs +294 -74
- package/dist/game-server.d.cts +4 -4
- package/dist/game-server.d.ts +4 -4
- package/dist/game-server.js +5 -5
- package/dist/game.cjs +105 -3
- package/dist/game.d.cts +3 -3
- package/dist/game.d.ts +3 -3
- package/dist/game.js +4 -4
- package/dist/{hosted-approval-CFlj4UQE.d.ts → hosted-approval-DIYUGgHi.d.ts} +1 -1
- package/dist/{hosted-approval-C1hQvbu6.d.cts → hosted-approval-VQ3uyeDh.d.cts} +1 -1
- package/dist/index.cjs +103 -1
- package/dist/index.d.cts +4 -4
- package/dist/index.d.ts +4 -4
- package/dist/index.js +2 -2
- package/dist/{server-CtXpytKt.d.ts → server-CMJHOmYL.d.ts} +120 -9
- package/dist/{server-ZnCyLWA2.d.cts → server-DF-BZU0B.d.cts} +120 -9
- package/dist/server.cjs +333 -67
- package/dist/server.d.cts +3 -3
- package/dist/server.d.ts +3 -3
- package/dist/server.js +3 -3
- package/dist/{types-Ctn8N2_l.d.ts → types-Dv0UavA9.d.cts} +149 -4
- package/dist/{types-Ctn8N2_l.d.cts → types-Dv0UavA9.d.ts} +149 -4
- package/dist/{version-Ce_pLpJf.d.cts → version-DB2wgiPY.d.cts} +1 -1
- package/dist/{version-Ce_pLpJf.d.ts → version-DB2wgiPY.d.ts} +1 -1
- package/docs/apple-in-app-purchases.md +382 -0
- package/package.json +2 -1
- package/dist/chunk-73ZVDQZV.js +0 -6
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,25 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 3.35.0
|
|
4
|
+
|
|
5
|
+
### Minor Changes
|
|
6
|
+
|
|
7
|
+
- Apple In-App Purchases (StoreKit 2) on `InvoServer`. All additive.
|
|
8
|
+
|
|
9
|
+
- `appleProducts()` (`GET /api/currency-purchases/apple/products`): the App Store products registered for the game and whether INVO will sell each one right now (`available`, `unavailableReason`). Call it before every purchase and offer only available products: Apple charges the player before INVO sees the purchase.
|
|
10
|
+
- `verifyApplePurchase({ playerEmail, signedTransaction, appAccountToken?, playerName?, metadata? })` (`POST /api/currency-purchases/apple/verify-purchase`): call it from your server with StoreKit's `Transaction.jwsRepresentation`. INVO verifies it and credits the coins once. Returns `status` (`"credited"` or `"already_credited"`), `orderId`, `transactionId`, `productId`, `coins`, `balance`, `environment`, `testMode` and `finish`. Safe to retry: a replay never credits twice.
|
|
11
|
+
- `shouldFinishAppleTransaction(resultOrError)`: whether to call StoreKit's `Transaction.finish()`. It reads INVO's `finish` flag, which every verify-purchase answer carries, and falls back to the same rule when a body has none: `true` for `credited`, `already_credited` and the errors `APPLE_TRANSACTION_REVOKED`, `APPLE_TRANSACTION_ALREADY_USED` and `APPLE_TRANSACTION_TOO_OLD` (exported as `APPLE_FINISH_ERROR_CODES`); `false` for everything else, including network errors. `InvoError.finish` exposes the flag on a refusal (`undefined` when the body has none). Also `isAppleCreditPending(err)` for `APPLE_CREDIT_PENDING` (503, verified and held: retry).
|
|
12
|
+
- `InvoError` predicates: `isAppleSignatureInvalid`, `isAppleBundleMismatch`, `isAppleEnvironmentNotAllowed`, `isAppleProductTypeUnsupported`, `isAppleProductUnknown`, `isInvalidMetadata`, `isAppleReviewAccountRequired`, `isAppleTransactionRevoked`, `isAppleTransactionAlreadyUsed`, `isAppleTransactionTooOld`, `isAppleValueExceedsPrice`, `isAppleAccountTokenMismatch`, `isAppleNotConfigured`, `isAppleNotVerified`, `isAppleReviewPurchaseLimit`, `isAppleCreditPending`, and `isAppleEndpointRequired` (a card purchase with a key on the Apple rail).
|
|
13
|
+
- Types: `AppleProduct`, `AppleProductsResult`, `AppleUnavailableReason`, `AppleEnvironment`, `VerifyApplePurchaseInput`, `ApplePurchaseStatus`, `ApplePurchaseResult`.
|
|
14
|
+
- Webhooks: `rail: "apple"` on `purchase.completed` and `purchase.refunded`, with the new `apple` block (`AppleWebhookDetails`: `transaction_id`, `original_transaction_id`, `product_id`, `environment`, `storefront`, `price`, `currency`, `charged_usd_estimated`, `test_mode`) and `metadata` on an Apple `purchase.refunded`.
|
|
15
|
+
- Docs: a full guide, [Apple In-App Purchases](https://github.com/Invo-Technologies/invo-web-sdk/blob/main/docs/apple-in-app-purchases.md) (`docs/apple-in-app-purchases.md`, shipped in the package), linked from the top of the README, plus a README summary section.
|
|
16
|
+
|
|
17
|
+
## 3.34.1
|
|
18
|
+
|
|
19
|
+
### Patch Changes
|
|
20
|
+
|
|
21
|
+
- Console links now point at the one INVO console: live mode at `https://console.invo.network`, test mode at `https://console.invo.network/test`. The game UI's "Open the INVO console" link for a sandbox game, the README console table, and the sandbox clock key guidance (README, `sandboxClockKey` and `isSandboxClockUnauthorized` docs, and the `INVALID_INPUT` message) now name the console in test mode. The old `https://dev.console.invo.network` address still redirects there. API hosts are unchanged. No code or type changes beyond the link and the message text.
|
|
22
|
+
|
|
3
23
|
## 3.34.0
|
|
4
24
|
|
|
5
25
|
### Minor Changes
|
package/README.md
CHANGED
|
@@ -2,8 +2,9 @@
|
|
|
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.34.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.34.0** reads the environment from the [key prefix](#key-prefixes) (`ivsdk_live_` is production, `ivsdk_test_` is the sandbox), throws `KeyEnvironmentMismatchError` when a key is pointed at the other INVO host, and adds `err.isKeyForOtherEnvironment`; **3.33.0** adds **[buyer-approved balance purchases](#buyer-approved-balance-purchases)** on Platform Commerce (`requirePlayerApproval`, `getApproval`, `cancelApproval`, the opt-in `platform_commerce.declined` webhook) and `metadata` on the `platform_commerce.*` webhooks; **3.32.0** adds `err.isPaymentsPaused`; **3.31.0** adds `invoFeeUsd` / `partnerShareUsd` on `platformCommerce.getStatus()` and `getPurchaseHistory()`, `spent_coins_charged_usd` on the coin `purchase.disputed` close (coins already spent are charged to you on a lost dispute), `err.isRateLimited` (every rate-limit 429 now carries `RATE_LIMITED`) and a `Retry-After` header fallback for `err.retryAfter`, and documents dispute holds on both tiers and the $10 payout minimum; **3.23.0** types two optional fields on the `purchase.disputed` close: `dispute_fee_usd` and `dispute_fee_charged_to_partner` (from November 8, 2026 the card dispute fee on Open-tier card sales is passed through to you at cost); **3.22.0** follows INVO's 2026-10 pricing: the Open card fee is **3.5% + $0.30** (was 4.5%), Merchant of Record stays **5.5% + $0.50**; the **chargeback guarantee** is a Merchant of Record term (Open-tier card payments made before November 8, 2026 keep it); payouts to your bank carry a **1% fee, capped at $500 per payout**. New reads: `getPlayerActivity()` / `iteratePlayerActivity()` (one merged list of a player's purchases, sends and transfers) and `platformCommerce.getPurchaseHistory()` / `iteratePurchaseHistory()`; `expiryReason` on `getTransferStatus()` / `getSendStatus()`; typed `transfer.*` and `payout.status_changed` webhook fields; new additive `err.publicCode` (the neutral twin of a code), set to `"BELOW_CARD_MINIMUM"` on the local card-floor refusal, whose `err.code` is unchanged (see [Tiers](#tiers) for the pricing); and the **[player-confirmed phone change](#player-confirmed-phone-change)**: `requestPhoneChange()` / `getPhoneChange()` on the server, `listPhoneChangeApprovals()` / `approvePhoneChange()` on the player's enrolled device, the typed `player.phone_changed` webhook, `err.changeRequestEndpoint` and new phone change error helpers; **3.18.0** follows INVO's 2026-09 card pricing: on card purchases **you pay INVO's card fee** (**4.5% + $0.30** on Open, **5.5% + $0.50** on Merchant of Record, plus **1.5%** on a card issued outside the US) and the player pays the listed price and gets the listed coins; fraud screening and a **chargeback guarantee** are included; minimum card purchase **$2.99** from 2026-10-27. New `partnerFeeUsd`, `internationalCardFeeUsd`, `minPurchaseWarning`, `feeTakenFrom: "partner"`, `err.minUsd` / `err.enforcedFrom` on `err.isBelowCardMinimum`, `minPurchaseWarning` on `createCheckout()`, `country` / `subdivision` on `purchaseCurrency()` with `err.isTaxPlaceUnavailable`, `cardFeeChargedToPartnerUsd` / `partnerDebitedUsd` on Platform Commerce card refunds, and the `partner_fee_usd` / `international_card_fee_usd` / `guarantee_covered` / `card_fee_charged_to_partner_usd` / `partner_debited_usd` webhook fields, all additive; an unacknowledged $10.00 coin purchase now credits 100.00 coins, not 93.70 (see **[Tiers](#tiers)**); **3.17.0** types the Steam fields on `purchase.refunded` / `purchase.disputed` (`rail`, `steam_transid`, nullable card-only ids): Steam chargebacks now arrive as `purchase.disputed`; **3.16.0** adds `warnings` on `createCheckout()` (item metadata on a coin session), `err.isDuplicateClientRequestId`, `err.isTrialAmountBelowFeeFloor` and `err.isIdentityCheckUnavailable`; **3.14.0** adds `credited` / `reasonCode` on `confirmPayment()` and `steamFinalizePurchase()`, Merchant of Record receipt fields, Platform Commerce card refunds in parts, and updates the **[tiers](#tiers)**: subscription card rates and chargeback handling by tier (the rates are superseded by 3.18.0), and Merchant of Record is applied for from the console; **3.13.0** documents the two **[tiers](#tiers)** (Open by default, Merchant of Record by application), adds **[INVO's card fee on coin purchases](#invos-card-fee-quote-show-acknowledge)** (rates superseded by 3.18.0): `quoteCurrencyPurchase()`, `acknowledgedTotalUsd` on `purchaseCurrency()`, the new `processingFeeUsd` / `feeTakenFrom` / `coinsCredited` / `chargeTotalUsd` fields and `err.isAmountBelowFee` / `err.isQuoteStale`, states the coin refund rule (only unspent coins), and adds **[paid trials](#paid-trials)** on card subscriptions (`trialAmountUsd`, the disclosed trial consent fields, `is_trial` / `expire_cause` on the events, `err.isPaymentMethodRequired` and the `isTrialAmount*` helpers); **3.12.0** removes the SDK's own card maximum (INVO's is a runtime setting, $100,000.00 by default); **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 (it is its own rate; item purchases stay at 10/90; see [Tiers](#tiers) for the current rate); **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.34.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: **3.34.1** points every console link at the one INVO console (live at console.invo.network, test mode at console.invo.network/test); **3.34.0** reads the environment from the [key prefix](#key-prefixes) (`ivsdk_live_` is production, `ivsdk_test_` is the sandbox), throws `KeyEnvironmentMismatchError` when a key is pointed at the other INVO host, and adds `err.isKeyForOtherEnvironment`; **3.33.0** adds **[buyer-approved balance purchases](#buyer-approved-balance-purchases)** on Platform Commerce (`requirePlayerApproval`, `getApproval`, `cancelApproval`, the opt-in `platform_commerce.declined` webhook) and `metadata` on the `platform_commerce.*` webhooks; **3.32.0** adds `err.isPaymentsPaused`; **3.31.0** adds `invoFeeUsd` / `partnerShareUsd` on `platformCommerce.getStatus()` and `getPurchaseHistory()`, `spent_coins_charged_usd` on the coin `purchase.disputed` close (coins already spent are charged to you on a lost dispute), `err.isRateLimited` (every rate-limit 429 now carries `RATE_LIMITED`) and a `Retry-After` header fallback for `err.retryAfter`, and documents dispute holds on both tiers and the $10 payout minimum; **3.23.0** types two optional fields on the `purchase.disputed` close: `dispute_fee_usd` and `dispute_fee_charged_to_partner` (from November 8, 2026 the card dispute fee on Open-tier card sales is passed through to you at cost); **3.22.0** follows INVO's 2026-10 pricing: the Open card fee is **3.5% + $0.30** (was 4.5%), Merchant of Record stays **5.5% + $0.50**; the **chargeback guarantee** is a Merchant of Record term (Open-tier card payments made before November 8, 2026 keep it); payouts to your bank carry a **1% fee, capped at $500 per payout**. New reads: `getPlayerActivity()` / `iteratePlayerActivity()` (one merged list of a player's purchases, sends and transfers) and `platformCommerce.getPurchaseHistory()` / `iteratePurchaseHistory()`; `expiryReason` on `getTransferStatus()` / `getSendStatus()`; typed `transfer.*` and `payout.status_changed` webhook fields; new additive `err.publicCode` (the neutral twin of a code), set to `"BELOW_CARD_MINIMUM"` on the local card-floor refusal, whose `err.code` is unchanged (see [Tiers](#tiers) for the pricing); and the **[player-confirmed phone change](#player-confirmed-phone-change)**: `requestPhoneChange()` / `getPhoneChange()` on the server, `listPhoneChangeApprovals()` / `approvePhoneChange()` on the player's enrolled device, the typed `player.phone_changed` webhook, `err.changeRequestEndpoint` and new phone change error helpers; **3.18.0** follows INVO's 2026-09 card pricing: on card purchases **you pay INVO's card fee** (**4.5% + $0.30** on Open, **5.5% + $0.50** on Merchant of Record, plus **1.5%** on a card issued outside the US) and the player pays the listed price and gets the listed coins; fraud screening and a **chargeback guarantee** are included; minimum card purchase **$2.99** from 2026-10-27. New `partnerFeeUsd`, `internationalCardFeeUsd`, `minPurchaseWarning`, `feeTakenFrom: "partner"`, `err.minUsd` / `err.enforcedFrom` on `err.isBelowCardMinimum`, `minPurchaseWarning` on `createCheckout()`, `country` / `subdivision` on `purchaseCurrency()` with `err.isTaxPlaceUnavailable`, `cardFeeChargedToPartnerUsd` / `partnerDebitedUsd` on Platform Commerce card refunds, and the `partner_fee_usd` / `international_card_fee_usd` / `guarantee_covered` / `card_fee_charged_to_partner_usd` / `partner_debited_usd` webhook fields, all additive; an unacknowledged $10.00 coin purchase now credits 100.00 coins, not 93.70 (see **[Tiers](#tiers)**); **3.17.0** types the Steam fields on `purchase.refunded` / `purchase.disputed` (`rail`, `steam_transid`, nullable card-only ids): Steam chargebacks now arrive as `purchase.disputed`; **3.16.0** adds `warnings` on `createCheckout()` (item metadata on a coin session), `err.isDuplicateClientRequestId`, `err.isTrialAmountBelowFeeFloor` and `err.isIdentityCheckUnavailable`; **3.14.0** adds `credited` / `reasonCode` on `confirmPayment()` and `steamFinalizePurchase()`, Merchant of Record receipt fields, Platform Commerce card refunds in parts, and updates the **[tiers](#tiers)**: subscription card rates and chargeback handling by tier (the rates are superseded by 3.18.0), and Merchant of Record is applied for from the console; **3.13.0** documents the two **[tiers](#tiers)** (Open by default, Merchant of Record by application), adds **[INVO's card fee on coin purchases](#invos-card-fee-quote-show-acknowledge)** (rates superseded by 3.18.0): `quoteCurrencyPurchase()`, `acknowledgedTotalUsd` on `purchaseCurrency()`, the new `processingFeeUsd` / `feeTakenFrom` / `coinsCredited` / `chargeTotalUsd` fields and `err.isAmountBelowFee` / `err.isQuoteStale`, states the coin refund rule (only unspent coins), and adds **[paid trials](#paid-trials)** on card subscriptions (`trialAmountUsd`, the disclosed trial consent fields, `is_trial` / `expire_cause` on the events, `err.isPaymentMethodRequired` and the `isTrialAmount*` helpers); **3.12.0** removes the SDK's own card maximum (INVO's is a runtime setting, $100,000.00 by default); **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 (it is its own rate; item purchases stay at 10/90; see [Tiers](#tiers) for the current rate); **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
|
+
> **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).
|
|
7
8
|
|
|
8
9
|
## What it does
|
|
9
10
|
|
|
@@ -103,6 +104,7 @@ The right approval method is a property of the **client the player is sitting in
|
|
|
103
104
|
- [INVO's card fee: quote, show, acknowledge](#invos-card-fee-quote-show-acknowledge)
|
|
104
105
|
- [Refunds of coin purchases](#refunds-of-coin-purchases)
|
|
105
106
|
- [Did the purchase go through? (the status read)](#did-the-purchase-go-through-the-status-read)
|
|
107
|
+
- [Apple In-App Purchases (StoreKit 2)](#apple-in-app-purchases-storekit-2): full guide in [docs/apple-in-app-purchases.md](https://github.com/Invo-Technologies/invo-web-sdk/blob/main/docs/apple-in-app-purchases.md)
|
|
106
108
|
- [Item purchase (spend game currency)](#item-purchase-spend-game-currency)
|
|
107
109
|
- [Platform Commerce (ecommerce)](#platform-commerce-ecommerce)
|
|
108
110
|
- [Subscriptions (recurring billing)](#subscriptions-recurring-billing)
|
|
@@ -139,14 +141,14 @@ Node ≥ 18 on the server (uses the global `fetch`). The browser build ships ESM
|
|
|
139
141
|
|
|
140
142
|
## Get your account & game secret (INVO console)
|
|
141
143
|
|
|
142
|
-
Sign up, create your title, and copy its credentials (the **game secret**, plus your WebAuthn **RP ID / origins**) in the INVO console.
|
|
144
|
+
Sign up, create your title, and copy its credentials (the **game secret**, plus your WebAuthn **RP ID / origins**) in the INVO console. There is one console with a test mode; use the mode that matches the environment you're building against:
|
|
143
145
|
|
|
144
146
|
| Environment | Console: sign up, manage titles, copy your game secret | API `baseUrl` |
|
|
145
147
|
|---|---|---|
|
|
146
|
-
| **Testing / sandbox** | **https://
|
|
147
|
-
| **Production** | **https://console.invo.network** | `https://invo.network` |
|
|
148
|
+
| **Testing / sandbox** | **https://console.invo.network/test** (the console in test mode) | `https://sandbox.invo.network/sandbox` |
|
|
149
|
+
| **Production (live)** | **https://console.invo.network** | `https://invo.network` |
|
|
148
150
|
|
|
149
|
-
Build and test against the
|
|
151
|
+
Build and test against the INVO console in test mode (console.invo.network/test) and the sandbox API first, then switch the console to live mode and use **`https://invo.network`** for launch. The old address `https://dev.console.invo.network` redirects to the test mode. **Each environment has its own game secret; never mix them**, and keep the secret server-side only.
|
|
150
152
|
|
|
151
153
|
## Architecture & the two entry points
|
|
152
154
|
|
|
@@ -464,8 +466,8 @@ const client = new InvoClient({
|
|
|
464
466
|
```
|
|
465
467
|
|
|
466
468
|
**Base URLs** (manage each environment in its [console](#get-your-account--game-secret-invo-console))
|
|
467
|
-
- Production: `https://invo.network
|
|
468
|
-
- Sandbox / testing: `https://sandbox.invo.network/sandbox
|
|
469
|
+
- Production: `https://invo.network`, console: `https://console.invo.network` (live mode)
|
|
470
|
+
- Sandbox / testing: `https://sandbox.invo.network/sandbox`, console: `https://console.invo.network/test`, the console in test mode (sandbox prepends the `/sandbox` prefix; the SDK absorbs it via `baseUrl`)
|
|
469
471
|
|
|
470
472
|
`baseUrl` must be `https://` — the game secret and player token travel in request headers, so plaintext is rejected. `http://localhost` is allowed for local dev only.
|
|
471
473
|
|
|
@@ -804,6 +806,95 @@ be issued:
|
|
|
804
806
|
names in yours
|
|
805
807
|
(`data.channel` is the channel of the KEY you presented — `"steam"` when you call with your Steam channel key; `null` on a legacy game key).
|
|
806
808
|
|
|
809
|
+
### Apple In-App Purchases (StoreKit 2)
|
|
810
|
+
|
|
811
|
+
> **Full guide: [Apple In-App Purchases](https://github.com/Invo-Technologies/invo-web-sdk/blob/main/docs/apple-in-app-purchases.md)** (prerequisites in App Store Connect and the
|
|
812
|
+
> INVO console, the flow, every error with its retry and finish rule, held purchases, refunds
|
|
813
|
+
> and webhooks, App Review on production, verification, and a complete server example). This
|
|
814
|
+
> section is the summary.
|
|
815
|
+
|
|
816
|
+
An iOS game sells coins with Apple In-App Purchase: the player pays Apple through StoreKit 2,
|
|
817
|
+
and your server sends Apple's signed transaction to INVO, which verifies it and credits the
|
|
818
|
+
coins once. Both methods are on `InvoServer` and take the game's **iOS key**, with Apple
|
|
819
|
+
In-App Purchases set up for the game in the INVO console (bundle id and products). A card
|
|
820
|
+
purchase with that key throws `WRONG_RAIL_ENDPOINT` (`err.isAppleEndpointRequired`).
|
|
821
|
+
|
|
822
|
+
**Apple charges the player before INVO sees the purchase.** So the order of calls matters:
|
|
823
|
+
|
|
824
|
+
1. **Before every purchase, call `appleProducts()`** and offer only products with
|
|
825
|
+
`available: true`. Ask StoreKit for exactly the `productId`s listed. This is the only point
|
|
826
|
+
where INVO can say no (`unavailableReason`: `APPLE_NOT_VERIFIED`,
|
|
827
|
+
`PARTNER_BILLING_NOT_SET_UP`, `PARTNER_RAIL_SUSPENDED`, `PARTNER_CREDIT_UNAVAILABLE`).
|
|
828
|
+
2. **Verify from your server, never the device.** Your app sends
|
|
829
|
+
`Transaction.jwsRepresentation` to your server, and your server calls
|
|
830
|
+
`verifyApplePurchase()`.
|
|
831
|
+
3. **Call `Transaction.finish()` only when INVO says to.** Every answer, success or error,
|
|
832
|
+
carries a boolean `finish` (`result.finish`, `err.finish`), and
|
|
833
|
+
`shouldFinishAppleTransaction()` reads it for you. It is `true` for `credited`,
|
|
834
|
+
`already_credited`, and the errors `APPLE_TRANSACTION_REVOKED`,
|
|
835
|
+
`APPLE_TRANSACTION_ALREADY_USED` and `APPLE_TRANSACTION_TOO_OLD`, after which nothing can
|
|
836
|
+
ever be delivered. On anything else, leave the transaction unfinished: StoreKit
|
|
837
|
+
redelivers it and your server retries. A retry never credits twice.
|
|
838
|
+
|
|
839
|
+
```ts
|
|
840
|
+
import { InvoServer, shouldFinishAppleTransaction } from "@invonetwork/web-sdk/server";
|
|
841
|
+
|
|
842
|
+
const server = new InvoServer({
|
|
843
|
+
gameSecret: process.env.INVO_IOS_KEY!, // the game's iOS key, server-side only
|
|
844
|
+
baseUrl: "https://sandbox.invo.network/sandbox", // prod: "https://invo.network"
|
|
845
|
+
});
|
|
846
|
+
|
|
847
|
+
// 1. Before every purchase: what may be offered right now.
|
|
848
|
+
const { canSell, products } = await server.appleProducts();
|
|
849
|
+
const offer = canSell ? products.filter((p) => p.available) : [];
|
|
850
|
+
// -> [{ productId, coins, label, priceUsd, available, unavailableReason }, ...]
|
|
851
|
+
|
|
852
|
+
// 2. After StoreKit returns a verified transaction, on your server:
|
|
853
|
+
let outcome: unknown;
|
|
854
|
+
try {
|
|
855
|
+
outcome = await server.verifyApplePurchase({
|
|
856
|
+
playerEmail: "player@example.com",
|
|
857
|
+
signedTransaction: jwsFromTheApp, // Transaction.jwsRepresentation, unchanged
|
|
858
|
+
appAccountToken: playerUuid, // optional: the appAccountToken you set
|
|
859
|
+
metadata: { playerId: myPlayerId }, // optional: echoed on the webhooks
|
|
860
|
+
});
|
|
861
|
+
// -> { status: "credited" | "already_credited", orderId, transactionId, productId,
|
|
862
|
+
// coins, balance, environment, testMode, finish }
|
|
863
|
+
} catch (err) {
|
|
864
|
+
outcome = err; // err.isAppleCreditPending: held, retry later
|
|
865
|
+
}
|
|
866
|
+
|
|
867
|
+
// 3. Tell the app whether to finish the transaction.
|
|
868
|
+
return { finish: shouldFinishAppleTransaction(outcome) };
|
|
869
|
+
```
|
|
870
|
+
|
|
871
|
+
| Outcome | HTTP | Finish? | Do |
|
|
872
|
+
|---|---|---|---|
|
|
873
|
+
| `status: "credited"` | 200 | yes | grant the coins |
|
|
874
|
+
| `status: "already_credited"` | 200 | yes | a replay; the coins were granted before (`balance` is `null` unless you name the same player) |
|
|
875
|
+
| `err.isAppleTransactionRevoked` | 409 | yes | Apple refunded or revoked it; grant nothing |
|
|
876
|
+
| `err.isAppleTransactionAlreadyUsed` | 409 | yes | credited in another INVO game; grant nothing here |
|
|
877
|
+
| `err.isAppleTransactionTooOld` | 409 | yes | bought before the game sold through INVO; grant nothing |
|
|
878
|
+
| `err.isAppleCreditPending` | 503 | no | verified and held; retry later, never ask the player to pay again |
|
|
879
|
+
| `err.isAppleProductUnknown`, `err.isAppleValueExceedsPrice` | 400, 409 | no | fix the product in the INVO console, then retry |
|
|
880
|
+
| `err.isAppleNotConfigured`, `err.isAppleNotVerified`, `err.isRailChannelMismatch` | 409 | no | finish the setup, then retry |
|
|
881
|
+
| `err.isAppleReviewPurchaseLimit` | 429 | no | today's App Review cap (per UTC day); retry the next day |
|
|
882
|
+
| `err.isAppleSignatureInvalid`, `err.isAppleBundleMismatch`, `err.isAppleEnvironmentNotAllowed`, `err.isAppleProductTypeUnsupported`, `err.isInvalidMetadata`, `err.isInvalidInput` | 400 | no | not a purchase INVO can credit as sent |
|
|
883
|
+
| `err.isAppleReviewAccountRequired` | 403 | no | a Sandbox purchase on production by an account not on the game's App Review list |
|
|
884
|
+
| `err.isAppleAccountTokenMismatch` | 409 | no | made for a different player |
|
|
885
|
+
| anything else, a network error or a timeout | | no | retry |
|
|
886
|
+
|
|
887
|
+
- **The INVO sandbox takes Sandbox transactions only.** Production takes Production ones,
|
|
888
|
+
and Sandbox ones only for the App Review accounts listed in the console (`testMode: true`,
|
|
889
|
+
capped per day). Xcode StoreKit-testing transactions are never accepted: Apple does not
|
|
890
|
+
sign them.
|
|
891
|
+
- **Webhooks:** `purchase.completed` and `purchase.refunded` carry `rail: "apple"`, your
|
|
892
|
+
`metadata` and an `apple` block (`transaction_id`,
|
|
893
|
+
`original_transaction_id`, `product_id`, `environment`, `storefront`, `price`, `currency`,
|
|
894
|
+
`charged_usd_estimated`, `test_mode`); `purchase.completed` also carries `channel: "ios"`.
|
|
895
|
+
A refund takes back only the coins the player still
|
|
896
|
+
holds from the purchase, never below zero.
|
|
897
|
+
|
|
807
898
|
### Direct rail (advanced — you tokenize the card yourself)
|
|
808
899
|
|
|
809
900
|
```ts
|
|
@@ -1510,7 +1601,7 @@ await sb.forceAuthChallenge(id); // moves it to awaiting_authenticati
|
|
|
1510
1601
|
|
|
1511
1602
|
> **Path note, loudly.** These four endpoints live **directly under the sandbox base, not under `/api`**: the full URL is `https://sandbox.invo.network/sandbox/subscriptions/<id>/advance-clock`. Because `baseUrl` already ends in `/sandbox`, the SDK posts to `/subscriptions/<id>/advance-clock` relative to it. They do not exist in production at all (404).
|
|
1512
1603
|
>
|
|
1513
|
-
> **Second credential.** Every clock call sends `X-Game-Secret-Key` *and* `X-Sandbox-Clock-Key`, a separate per-game key (`ivclk_...`). Get it from the
|
|
1604
|
+
> **Second credential.** Every clock call sends `X-Game-Secret-Key` *and* `X-Sandbox-Clock-Key`, a separate per-game key (`ivclk_...`). Get it from the INVO console in test mode (console.invo.network/test): open the game, **Game Settings**, the **"Sandbox clock key"** card (generated the first time you reveal it; the same card rotates it, with a 7-day grace). Pass it as `sandboxClockKey`; a missing key throws `INVALID_INPUT` before the network, a wrong one is `401 SANDBOX_CLOCK_UNAUTHORIZED` (`err.isSandboxClockUnauthorized`). Keep it out of game clients and source control. None of these calls is auto-retried: each one moves the clock or runs the engine.
|
|
1514
1605
|
|
|
1515
1606
|
**Card recipe.** Make the sandbox game live and register a webhook. Save a card with `cards.createSetupSession` (open `cardSetupUrl` in a browser; the sandbox page runs against the test-mode card processor, so enter a test card there, never a real one; the sandbox recipe on the public docs site is at https://docs.invo.network/docs/subscriptions-sandbox), or, on the processor-bound path, with `cards.beginSetup` using `paymentMethodId: "pm_card_visa"` (immediate) or `"pm_card_threeDSecure2Required"` (returns `requires_action`; finish on the client, then `confirmSetup`). `subscriptions.create` with that `playerCardId`: expect `firstCharge.status: "paid"`, `subscription.periodSeq: 2`, and a `subscription.renewed` delivery with `period_seq: 1`. Replay the same input: expect `idempotentReplay: true`. Then `advanceClock` + `forceRenewal` for as many periods as you like (`engineStats.renewed: 1`, `period_seq` advancing on each `subscription.renewed`); `forceFailure` four times (or swap in `"pm_card_chargeDeclined"` through `setPaymentMethod`, then advance + force four times) to walk `past_due` to `expired` with `final_period_end`; `changeAmount` then advance + force to see the old price on that renewal and the new one on the next; `cancel({ atPeriodEnd: true })` then advance + force to get `action: "retired-at-period-end"`; `refund` a paid period (a full refund cancels the subscription, so refund a partial amount first if you want to keep testing it; the daily limit applies in sandbox too, and a refund over it answers `pending_approval`; at the default limit a single period always runs, so to see a `pending_approval` ask INVO to set a low limit for your sandbox game); and create one with `trialDays: 7` to see `skipped_trial` convert.
|
|
1516
1607
|
|
|
@@ -1544,7 +1635,7 @@ Match on `err.code` (and on `body.status` where the body carries one), never on
|
|
|
1544
1635
|
| `.isRefundRequestRejected` + `.refundRequestId` / `.decisionReason` | (409) this key was a refund request INVO rejected; use a new key to try again |
|
|
1545
1636
|
| `.isConcurrentRequest` | (409) two requests collided (two creates for a new player, or two refund requests for one period); retry with the **same** key |
|
|
1546
1637
|
| `.isRefundMismatch` | (502) a card refund needs manual reconciliation; contact INVO, do not retry-loop |
|
|
1547
|
-
| `.isSandboxClockUnauthorized` | (401) missing/wrong `X-Sandbox-Clock-Key`; reveal it in the
|
|
1638
|
+
| `.isSandboxClockUnauthorized` | (401) missing/wrong `X-Sandbox-Clock-Key`; reveal it in the INVO console in test mode (console.invo.network/test) |
|
|
1548
1639
|
| `.isPhoneShareApprovalRequired` | (409) the supplied `playerPhone` belongs to another identity; run the phone-share flow, then retry |
|
|
1549
1640
|
| `PAYMENT_METHOD_NOT_FOUND` / `PAYMENT_METHOD_EXPIRED` / `PAYMENT_METHOD_INVALID` | the card is not this player's in this game, is expired, or the id is malformed |
|
|
1550
1641
|
| `WALLET_ONLY_SUBSCRIPTION` / `WALLET_ONLY_CONFLICT` | `walletOnly: true` with a card; or a wallet-only subscription needs `walletOnly: false` beside the new card (`walletOnly` is deprecated: such a subscription can never be paid) |
|
|
@@ -2758,10 +2849,10 @@ export const POST = createWebhookHandler({
|
|
|
2758
2849
|
|
|
2759
2850
|
| Event | Fires for | Use it to |
|
|
2760
2851
|
|---|---|---|
|
|
2761
|
-
| `purchase.completed` | every currency-purchase rail, **and every paid card subscription renewal** | grant currency (payload: `transaction_id, order_id, player_email, identity_id, usd_amount, currency_amount, currency_name, new_balance, rail`, `metadata`). `metadata` echoes what you passed to `createCheckout`/`purchaseCurrency` (all rails); `order_id` is also on every webhook as a secondary reconciliation key (`getOrderDetails`). Card purchases also carry `partner_fee_usd` and `international_card_fee_usd`, the card fees charged to you (the player paid the listed price). **Skip it when `metadata.source` is `"subscription_renewal"`**: those coins are spent by the renewal itself; grant on `subscription.renewed`. |
|
|
2852
|
+
| `purchase.completed` | every currency-purchase rail, **and every paid card subscription renewal** | grant currency (payload: `transaction_id, order_id, player_email, identity_id, usd_amount, currency_amount, currency_name, new_balance, rail`, `metadata`). `metadata` echoes what you passed to `createCheckout`/`purchaseCurrency` (all rails); `order_id` is also on every webhook as a secondary reconciliation key (`getOrderDetails`). Card purchases also carry `partner_fee_usd` and `international_card_fee_usd`, the card fees charged to you (the player paid the listed price). Apple purchases carry `rail: "apple"` and an `apple` block (see [Apple In-App Purchases](#apple-in-app-purchases-storekit-2)). **Skip it when `metadata.source` is `"subscription_renewal"`**: those coins are spent by the renewal itself; grant on `subscription.renewed`. |
|
|
2762
2853
|
| `purchase.failed` | `platform` rail only | handle failures |
|
|
2763
2854
|
| `purchase.disputed` | `platform` rail, and `steam` chargebacks | handle disputes. A lost chargeback takes back up to the purchase's coins from the available balance, never below zero. On a lost Platform Commerce card sale or subscription charge dispute (`order_type`), `guarantee_covered: true` means INVO's chargeback guarantee covers it (a fraud chargeback): your share is not reversed or held and no dispute fee is passed to you. Otherwise a lost dispute costs you what a refund would: your share is reversed and INVO's card fee stays charged to you, on a Platform Commerce sale and on every subscription charge (`card_fee_charged_to_partner_usd`, and `partner_debited_usd` = share reversed plus that fee, since 2026-09-28). A subscription dispute also carries `processing_fee_usd`, which reads `"0.00"`. Coin purchase disputes carry none of these keys: a lost one takes back the coins the player still holds and, since 2026-10-20, charges you for coins already spent at the price paid (`spent_coins_charged_usd` on the close, `"0.00"` when none). A Steam chargeback carries the same keys as a lost card dispute with `payment_intent_id`, `charge_id` and `dispute_id` `null`, plus `rail: "steam"` and `steam_transid`. A card dispute close also carries `dispute_fee_usd` (string decimal, `"0.00"` when INVO bears the fee, `null` when undecided) and `dispute_fee_charged_to_partner` (boolean or `null`); from November 8, 2026 the dispute fee on an Open-tier card sale is passed through to you at cost. **If you revoke on `purchase.refunded`, handle this too:** a Steam chargeback no longer arrives as `purchase.refunded` |
|
|
2764
|
-
| `purchase.refunded` | `game` / `steam` rails | handle refunds. Only coins the player still has from that purchase are taken back, never below zero. A Steam partial refund carries `fully_refunded: false` |
|
|
2855
|
+
| `purchase.refunded` | `game` / `steam` / `apple` rails | handle refunds. Only coins the player still has from that purchase are taken back, never below zero. A Steam partial refund carries `fully_refunded: false`. An Apple refund or revocation carries `rail: "apple"`, `metadata` and the `apple` block |
|
|
2765
2856
|
| `item.purchased` | every item purchase | **grant the in-game item** (payload includes `transaction_id, order_id, player_email, identity_id, item_id, item_name, item_quantity, unit_price, total_price, currency_name, new_balance, fee_breakdown`) |
|
|
2766
2857
|
| `platform_commerce.purchased` | every Platform Commerce purchase (balance immediately; **card after payment settles**) | **fulfill the ecommerce order** — never on the browser confirm (payload: `transaction_id, order_id, funding_source, player_email, identity_id, item_id, item_name, item_quantity, total_price`; + `unit_price, currency_name, new_balance` on balance; `total_price_usd` on card; `fee_breakdown`) |
|
|
2767
2858
|
| `platform_commerce.refunded` | a Platform Commerce refund | handle the reversal (payload: `order_id, funding_source, player_email, refunded_amount, amount_unit, fee_retained`) |
|
|
@@ -2913,6 +3004,8 @@ try {
|
|
|
2913
3004
|
| `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 |
|
|
2914
3005
|
| `confirmPayment({ paymentIntentId, orderId? })` | `{ status, transactionId?, newBalance?, credited?, reasonCode?, raw }`; report success only on `credited: true` |
|
|
2915
3006
|
| `getOrderDetails({ orderId? \| transactionId? })` | `{ order, financialSummary, statusTimeline, receiptNumber?, receiptUrl?, raw }`; the receipt fields on a Merchant of Record currency purchase only |
|
|
3007
|
+
| `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) |
|
|
3008
|
+
| `verifyApplePurchase({ playerEmail, signedTransaction, appAccountToken?, playerName?, metadata? })` | `{ status: "credited" | "already_credited", orderId, transactionId, productId, coins, balance, environment, testMode, finish, raw }`; finish the StoreKit transaction only when\| "already_credited", orderId, transactionId, productId, coins, balance, environment, testMode, raw }`; finish the StoreKit transaction only when `shouldFinishAppleTransaction(resultOrError)` is `true` |
|
|
2916
3009
|
| `purchaseItem(input)` | `{ status, transactionId, orderId, newBalance, previousBalance, currencyName, financialBreakdown?, raw }` — **game** tenant spending game currency on an in-game item |
|
|
2917
3010
|
| `getItemPurchaseHistory({ playerEmail, limit?, offset? })` | `{ history, pagination, raw }` |
|
|
2918
3011
|
| `getPlayerActivity({ playerEmail, limit?, cursor?, types? })` | `PlayerActivityResult`: `{ playerEmail, gameId, types, activity, limit, hasMore, nextCursor, raw }`, one merged, newest-first page of purchases, sends and transfers. See [Player activity](#player-activity-one-list-of-everything) |
|
|
@@ -841,7 +841,7 @@ var InvoError = class _InvoError extends Error {
|
|
|
841
841
|
/**
|
|
842
842
|
* True when a sandbox clock call was refused for a missing, wrong or never-issued
|
|
843
843
|
* `X-Sandbox-Clock-Key` (`SANDBOX_CLOCK_UNAUTHORIZED`, 401). Reveal or rotate the key on
|
|
844
|
-
* the game's Game Settings page in the
|
|
844
|
+
* the game's Game Settings page in the INVO console in test mode (console.invo.network/test).
|
|
845
845
|
*/
|
|
846
846
|
get isSandboxClockUnauthorized() {
|
|
847
847
|
return this.code === "SANDBOX_CLOCK_UNAUTHORIZED";
|
|
@@ -1161,6 +1161,108 @@ var InvoError = class _InvoError extends Error {
|
|
|
1161
1161
|
get isRateLimited() {
|
|
1162
1162
|
return this.code === "RATE_LIMITED" || this.code === "rate_limited" || this.status === 429;
|
|
1163
1163
|
}
|
|
1164
|
+
// ---- Apple In-App Purchase (verifyApplePurchase / appleProducts, 3.35.0) ----
|
|
1165
|
+
//
|
|
1166
|
+
// Apple has already charged the player when verifyApplePurchase runs. Decide whether to
|
|
1167
|
+
// call StoreKit's Transaction.finish() with shouldFinishAppleTransaction() (or `finish`),
|
|
1168
|
+
// not with these: among the errors only APPLE_TRANSACTION_REVOKED,
|
|
1169
|
+
// APPLE_TRANSACTION_ALREADY_USED and APPLE_TRANSACTION_TOO_OLD are finished.
|
|
1170
|
+
/**
|
|
1171
|
+
* The body's boolean `finish` (additive, 3.35.0), sent on every `verifyApplePurchase`
|
|
1172
|
+
* answer: `true` when the game should call StoreKit's `Transaction.finish()` for this
|
|
1173
|
+
* refusal (nothing can ever be delivered), `false` when it should leave the transaction
|
|
1174
|
+
* unfinished and retry. `undefined` when the body carries none (any other endpoint, an
|
|
1175
|
+
* older backend, or a network error); `shouldFinishAppleTransaction(err)` then falls back
|
|
1176
|
+
* to the error code.
|
|
1177
|
+
*/
|
|
1178
|
+
get finish() {
|
|
1179
|
+
const f = this.bodyObject()["finish"];
|
|
1180
|
+
return typeof f === "boolean" ? f : void 0;
|
|
1181
|
+
}
|
|
1182
|
+
/** Not a genuine Apple transaction (`APPLE_SIGNATURE_INVALID`, 400). Leave it unfinished. */
|
|
1183
|
+
get isAppleSignatureInvalid() {
|
|
1184
|
+
return this.code === "APPLE_SIGNATURE_INVALID";
|
|
1185
|
+
}
|
|
1186
|
+
/** Another app's transaction: the bundle id (or Apple ID) is not this game's
|
|
1187
|
+
* (`APPLE_BUNDLE_MISMATCH`, 400). */
|
|
1188
|
+
get isAppleBundleMismatch() {
|
|
1189
|
+
return this.code === "APPLE_BUNDLE_MISMATCH";
|
|
1190
|
+
}
|
|
1191
|
+
/** The transaction's environment is not accepted here (`APPLE_ENVIRONMENT_NOT_ALLOWED`, 400).
|
|
1192
|
+
* The INVO sandbox takes only Sandbox transactions; Xcode StoreKit-testing transactions are
|
|
1193
|
+
* never accepted, because Apple does not sign them. */
|
|
1194
|
+
get isAppleEnvironmentNotAllowed() {
|
|
1195
|
+
return this.code === "APPLE_ENVIRONMENT_NOT_ALLOWED";
|
|
1196
|
+
}
|
|
1197
|
+
/** Only consumable products buy currency (`APPLE_PRODUCT_TYPE_UNSUPPORTED`, 400). */
|
|
1198
|
+
get isAppleProductTypeUnsupported() {
|
|
1199
|
+
return this.code === "APPLE_PRODUCT_TYPE_UNSUPPORTED";
|
|
1200
|
+
}
|
|
1201
|
+
/** The product id is not registered for this game (`APPLE_PRODUCT_UNKNOWN`, 400). Register
|
|
1202
|
+
* it in the INVO console and retry; keep the transaction unfinished meanwhile. */
|
|
1203
|
+
get isAppleProductUnknown() {
|
|
1204
|
+
return this.code === "APPLE_PRODUCT_UNKNOWN";
|
|
1205
|
+
}
|
|
1206
|
+
/** `metadata` was refused (`INVALID_METADATA`, 400). Fix the request and retry. */
|
|
1207
|
+
get isInvalidMetadata() {
|
|
1208
|
+
return this.code === "INVALID_METADATA";
|
|
1209
|
+
}
|
|
1210
|
+
/** A Sandbox purchase on INVO production by an account not on the game's App Review list
|
|
1211
|
+
* (`APPLE_REVIEW_ACCOUNT_REQUIRED`, 403). */
|
|
1212
|
+
get isAppleReviewAccountRequired() {
|
|
1213
|
+
return this.code === "APPLE_REVIEW_ACCOUNT_REQUIRED";
|
|
1214
|
+
}
|
|
1215
|
+
/** Apple refunded or revoked the transaction (`APPLE_TRANSACTION_REVOKED`, 409). Nothing can
|
|
1216
|
+
* ever be delivered for it: **finish it** (`finish: true`). */
|
|
1217
|
+
get isAppleTransactionRevoked() {
|
|
1218
|
+
return this.code === "APPLE_TRANSACTION_REVOKED";
|
|
1219
|
+
}
|
|
1220
|
+
/** The transaction was already credited in another INVO game
|
|
1221
|
+
* (`APPLE_TRANSACTION_ALREADY_USED`, 409). Terminal: **finish it** (`finish: true`). */
|
|
1222
|
+
get isAppleTransactionAlreadyUsed() {
|
|
1223
|
+
return this.code === "APPLE_TRANSACTION_ALREADY_USED";
|
|
1224
|
+
}
|
|
1225
|
+
/** Bought before the game sold through INVO (`APPLE_TRANSACTION_TOO_OLD`, 409). Terminal:
|
|
1226
|
+
* **finish it** (`finish: true`). */
|
|
1227
|
+
get isAppleTransactionTooOld() {
|
|
1228
|
+
return this.code === "APPLE_TRANSACTION_TOO_OLD";
|
|
1229
|
+
}
|
|
1230
|
+
/** The product's coins are out of proportion to its signed price, or over the per-purchase
|
|
1231
|
+
* maximum (`APPLE_VALUE_EXCEEDS_PRICE`, 409). Fix the product mapping and retry. */
|
|
1232
|
+
get isAppleValueExceedsPrice() {
|
|
1233
|
+
return this.code === "APPLE_VALUE_EXCEEDS_PRICE";
|
|
1234
|
+
}
|
|
1235
|
+
/** The transaction's `appAccountToken` is not the one you sent: it was made for a
|
|
1236
|
+
* different player (`APPLE_ACCOUNT_TOKEN_MISMATCH`, 409). */
|
|
1237
|
+
get isAppleAccountTokenMismatch() {
|
|
1238
|
+
return this.code === "APPLE_ACCOUNT_TOKEN_MISMATCH";
|
|
1239
|
+
}
|
|
1240
|
+
/** The game's Apple configuration is missing or turned off (`APPLE_NOT_CONFIGURED`, 409).
|
|
1241
|
+
* Retry once it is set up. */
|
|
1242
|
+
get isAppleNotConfigured() {
|
|
1243
|
+
return this.code === "APPLE_NOT_CONFIGURED";
|
|
1244
|
+
}
|
|
1245
|
+
/** Production has not yet confirmed you own the App Store app (`APPLE_NOT_VERIFIED`, 409).
|
|
1246
|
+
* Point App Store Server Notifications at INVO; retry once verified. */
|
|
1247
|
+
get isAppleNotVerified() {
|
|
1248
|
+
return this.code === "APPLE_NOT_VERIFIED";
|
|
1249
|
+
}
|
|
1250
|
+
/** Today's App Review purchase cap on production is reached (`APPLE_REVIEW_PURCHASE_LIMIT`,
|
|
1251
|
+
* 429). */
|
|
1252
|
+
get isAppleReviewPurchaseLimit() {
|
|
1253
|
+
return this.code === "APPLE_REVIEW_PURCHASE_LIMIT";
|
|
1254
|
+
}
|
|
1255
|
+
/** Verified and held, not refused (`APPLE_CREDIT_PENDING`, 503): the coins will credit on a
|
|
1256
|
+
* later retry. Keep the transaction unfinished and retry; StoreKit also redelivers it. */
|
|
1257
|
+
get isAppleCreditPending() {
|
|
1258
|
+
return this.code === "APPLE_CREDIT_PENDING";
|
|
1259
|
+
}
|
|
1260
|
+
/** A card purchase (`purchaseCurrency`) was made with a key on the Apple rail
|
|
1261
|
+
* (`WRONG_RAIL_ENDPOINT`, 400, `status: "use_apple_endpoint"`). Use
|
|
1262
|
+
* `verifyApplePurchase` for that key. */
|
|
1263
|
+
get isAppleEndpointRequired() {
|
|
1264
|
+
return this.code === "WRONG_RAIL_ENDPOINT" && this.bodyObject()["status"] === "use_apple_endpoint";
|
|
1265
|
+
}
|
|
1164
1266
|
/** `body` as a plain object, or `{}` if it's a string/number/null (non-JSON responses).
|
|
1165
1267
|
* The `in` operator throws on primitives, so callers must go through this. */
|
|
1166
1268
|
bodyObject() {
|
|
@@ -1774,5 +1876,5 @@ function toApprovePhoneChangeResult(raw, changeRequestId) {
|
|
|
1774
1876
|
}
|
|
1775
1877
|
|
|
1776
1878
|
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 };
|
|
1777
|
-
//# sourceMappingURL=chunk-
|
|
1778
|
-
//# sourceMappingURL=chunk-
|
|
1879
|
+
//# sourceMappingURL=chunk-BGCSSWVL.js.map
|
|
1880
|
+
//# sourceMappingURL=chunk-BGCSSWVL.js.map
|
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { InvoError, assertSecureBaseUrl, Http, toPurchaseStatusResult, toPhoneChangeApprovalsResult, phoneChangeSignalMessage, toApprovePhoneChangeResult, toDestinationsResult, toLoyaltyCardsResult, toLoyaltyVaultResult, toRedeemRewardResult, toRewardsPageLink, buildGameEventBody, toReportGameEventResult } from './chunk-
|
|
1
|
+
import { InvoError, assertSecureBaseUrl, Http, toPurchaseStatusResult, toPhoneChangeApprovalsResult, phoneChangeSignalMessage, toApprovePhoneChangeResult, toDestinationsResult, toLoyaltyCardsResult, toLoyaltyVaultResult, toRedeemRewardResult, toRewardsPageLink, buildGameEventBody, toReportGameEventResult } from './chunk-BGCSSWVL.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-
|
|
1590
|
-
//# sourceMappingURL=chunk-
|
|
1589
|
+
//# sourceMappingURL=chunk-SCFK6IVH.js.map
|
|
1590
|
+
//# sourceMappingURL=chunk-SCFK6IVH.js.map
|