@invonetwork/web-sdk 3.34.1 → 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.
@@ -867,6 +867,65 @@ declare class InvoError extends Error {
867
867
  * and send the same request again. Branch on this, not on the message.
868
868
  */
869
869
  get isRateLimited(): boolean;
870
+ /**
871
+ * The body's boolean `finish` (additive, 3.35.0), sent on every `verifyApplePurchase`
872
+ * answer: `true` when the game should call StoreKit's `Transaction.finish()` for this
873
+ * refusal (nothing can ever be delivered), `false` when it should leave the transaction
874
+ * unfinished and retry. `undefined` when the body carries none (any other endpoint, an
875
+ * older backend, or a network error); `shouldFinishAppleTransaction(err)` then falls back
876
+ * to the error code.
877
+ */
878
+ get finish(): boolean | undefined;
879
+ /** Not a genuine Apple transaction (`APPLE_SIGNATURE_INVALID`, 400). Leave it unfinished. */
880
+ get isAppleSignatureInvalid(): boolean;
881
+ /** Another app's transaction: the bundle id (or Apple ID) is not this game's
882
+ * (`APPLE_BUNDLE_MISMATCH`, 400). */
883
+ get isAppleBundleMismatch(): boolean;
884
+ /** The transaction's environment is not accepted here (`APPLE_ENVIRONMENT_NOT_ALLOWED`, 400).
885
+ * The INVO sandbox takes only Sandbox transactions; Xcode StoreKit-testing transactions are
886
+ * never accepted, because Apple does not sign them. */
887
+ get isAppleEnvironmentNotAllowed(): boolean;
888
+ /** Only consumable products buy currency (`APPLE_PRODUCT_TYPE_UNSUPPORTED`, 400). */
889
+ get isAppleProductTypeUnsupported(): boolean;
890
+ /** The product id is not registered for this game (`APPLE_PRODUCT_UNKNOWN`, 400). Register
891
+ * it in the INVO console and retry; keep the transaction unfinished meanwhile. */
892
+ get isAppleProductUnknown(): boolean;
893
+ /** `metadata` was refused (`INVALID_METADATA`, 400). Fix the request and retry. */
894
+ get isInvalidMetadata(): boolean;
895
+ /** A Sandbox purchase on INVO production by an account not on the game's App Review list
896
+ * (`APPLE_REVIEW_ACCOUNT_REQUIRED`, 403). */
897
+ get isAppleReviewAccountRequired(): boolean;
898
+ /** Apple refunded or revoked the transaction (`APPLE_TRANSACTION_REVOKED`, 409). Nothing can
899
+ * ever be delivered for it: **finish it** (`finish: true`). */
900
+ get isAppleTransactionRevoked(): boolean;
901
+ /** The transaction was already credited in another INVO game
902
+ * (`APPLE_TRANSACTION_ALREADY_USED`, 409). Terminal: **finish it** (`finish: true`). */
903
+ get isAppleTransactionAlreadyUsed(): boolean;
904
+ /** Bought before the game sold through INVO (`APPLE_TRANSACTION_TOO_OLD`, 409). Terminal:
905
+ * **finish it** (`finish: true`). */
906
+ get isAppleTransactionTooOld(): boolean;
907
+ /** The product's coins are out of proportion to its signed price, or over the per-purchase
908
+ * maximum (`APPLE_VALUE_EXCEEDS_PRICE`, 409). Fix the product mapping and retry. */
909
+ get isAppleValueExceedsPrice(): boolean;
910
+ /** The transaction's `appAccountToken` is not the one you sent: it was made for a
911
+ * different player (`APPLE_ACCOUNT_TOKEN_MISMATCH`, 409). */
912
+ get isAppleAccountTokenMismatch(): boolean;
913
+ /** The game's Apple configuration is missing or turned off (`APPLE_NOT_CONFIGURED`, 409).
914
+ * Retry once it is set up. */
915
+ get isAppleNotConfigured(): boolean;
916
+ /** Production has not yet confirmed you own the App Store app (`APPLE_NOT_VERIFIED`, 409).
917
+ * Point App Store Server Notifications at INVO; retry once verified. */
918
+ get isAppleNotVerified(): boolean;
919
+ /** Today's App Review purchase cap on production is reached (`APPLE_REVIEW_PURCHASE_LIMIT`,
920
+ * 429). */
921
+ get isAppleReviewPurchaseLimit(): boolean;
922
+ /** Verified and held, not refused (`APPLE_CREDIT_PENDING`, 503): the coins will credit on a
923
+ * later retry. Keep the transaction unfinished and retry; StoreKit also redelivers it. */
924
+ get isAppleCreditPending(): boolean;
925
+ /** A card purchase (`purchaseCurrency`) was made with a key on the Apple rail
926
+ * (`WRONG_RAIL_ENDPOINT`, 400, `status: "use_apple_endpoint"`). Use
927
+ * `verifyApplePurchase` for that key. */
928
+ get isAppleEndpointRequired(): boolean;
870
929
  /** `body` as a plain object, or `{}` if it's a string/number/null (non-JSON responses).
871
930
  * The `in` operator throws on primitives, so callers must go through this. */
872
931
  private bodyObject;
@@ -1830,6 +1889,92 @@ interface SteamFinalizeResult {
1830
1889
  reasonCode?: string | null;
1831
1890
  raw: Record<string, unknown>;
1832
1891
  }
1892
+ /**
1893
+ * Why INVO will not sell a product through Apple right now (`unavailableReason`).
1894
+ * Open-ended: treat any other value as "not available".
1895
+ *
1896
+ * - `APPLE_NOT_VERIFIED`: production has not yet confirmed you own the App Store app
1897
+ * (it does on the first App Store Server Notification).
1898
+ * - `PARTNER_BILLING_NOT_SET_UP`: the developer account has no INVO billing set up.
1899
+ * - `PARTNER_RAIL_SUSPENDED`: the developer account's settlement is suspended.
1900
+ * - `PARTNER_CREDIT_UNAVAILABLE`: no headroom for this product's coins right now.
1901
+ */
1902
+ type AppleUnavailableReason = "APPLE_NOT_VERIFIED" | "PARTNER_BILLING_NOT_SET_UP" | "PARTNER_RAIL_SUSPENDED" | "PARTNER_CREDIT_UNAVAILABLE" | (string & {});
1903
+ /** One App Store product registered for the game in the INVO console. */
1904
+ interface AppleProduct {
1905
+ /** The App Store Connect product id. Ask StoreKit for exactly these ids. */
1906
+ productId: string;
1907
+ /** Coins the product credits, fixed per product. */
1908
+ coins: number;
1909
+ /** Display label from the console (the product id when none was set). */
1910
+ label: string;
1911
+ /** The US App Store price registered in the console, decimal string, or `null`. */
1912
+ priceUsd: string | null;
1913
+ /** Always `true` here: retired products are not listed. */
1914
+ active: boolean;
1915
+ /** Offer the product only when this is `true`. Apple charges before INVO sees the purchase. */
1916
+ available: boolean;
1917
+ /** Set when `available` is `false`. */
1918
+ unavailableReason: AppleUnavailableReason | null;
1919
+ }
1920
+ interface AppleProductsResult {
1921
+ /** The App Store bundle id registered for the game. */
1922
+ bundleId: string;
1923
+ /** `false` when nothing can be sold right now; `unavailableReason` says why. */
1924
+ canSell: boolean;
1925
+ unavailableReason: AppleUnavailableReason | null;
1926
+ products: AppleProduct[];
1927
+ raw: Record<string, unknown>;
1928
+ }
1929
+ /** The App Store environment of a verified transaction. */
1930
+ type AppleEnvironment = "Production" | "Sandbox" | (string & {});
1931
+ interface VerifyApplePurchaseInput {
1932
+ playerEmail: string;
1933
+ /**
1934
+ * StoreKit 2's `Transaction.jwsRepresentation` (or `VerificationResult.jwsRepresentation`),
1935
+ * sent unchanged. INVO verifies Apple's signature; never decode or trust it yourself first.
1936
+ */
1937
+ signedTransaction: string;
1938
+ /**
1939
+ * The UUID your game set as `appAccountToken` on the purchase, when it set one. INVO
1940
+ * refuses a transaction whose token differs (`APPLE_ACCOUNT_TOKEN_MISMATCH`).
1941
+ */
1942
+ appAccountToken?: string;
1943
+ /** Used only when INVO creates the player on this purchase. */
1944
+ playerName?: string;
1945
+ /** Your own JSON, echoed on `purchase.completed` and `purchase.refunded` (`data.metadata`). */
1946
+ metadata?: Record<string, unknown>;
1947
+ }
1948
+ /** `credited`: added by this call. `already_credited`: a replay of a transaction INVO already credited. */
1949
+ type ApplePurchaseStatus = "credited" | "already_credited";
1950
+ interface ApplePurchaseResult {
1951
+ status: ApplePurchaseStatus;
1952
+ orderId: string;
1953
+ /** Apple's `transactionId`. */
1954
+ transactionId: string;
1955
+ productId: string;
1956
+ /** Coins credited for this transaction. */
1957
+ coins: number;
1958
+ /**
1959
+ * The player's balance after the credit, decimal string. On `already_credited` it is
1960
+ * `null` unless the call names the same player the transaction was credited to.
1961
+ */
1962
+ balance: string | null;
1963
+ environment: AppleEnvironment;
1964
+ /**
1965
+ * `true` only for an App Review (Sandbox) purchase accepted on INVO production. On the INVO
1966
+ * sandbox, where every transaction is a Sandbox one, it is `false`.
1967
+ */
1968
+ testMode: boolean;
1969
+ /**
1970
+ * Whether to call StoreKit's `Transaction.finish()`: INVO's `finish` flag (`true` on both
1971
+ * success statuses). From an older backend that sends none, `true` for `credited` and
1972
+ * `already_credited`. Prefer `shouldFinishAppleTransaction(resultOrError)`, which also
1973
+ * covers the thrown errors.
1974
+ */
1975
+ finish: boolean;
1976
+ raw: Record<string, unknown>;
1977
+ }
1833
1978
  interface PurchaseItemInput {
1834
1979
  /** Idempotency key, unique per game. Required. A duplicate returns 409. */
1835
1980
  clientRequestId: string;
@@ -3802,4 +3947,4 @@ interface RewardsPageLink {
3802
3947
  raw: Record<string, unknown>;
3803
3948
  }
3804
3949
 
3805
- export { type AuthHeader as $, type ApproveResult as A, type BalanceResult as B, type CheckoutClientConfig as C, type DestinationGame as D, type EnrollmentBeginResult as E, type InvoHooks as F, type InvoRequestInfo as G, Http as H, InvoError as I, type InvoResponseInfo as J, type LoyaltyCard as K, type LinkDeviceResult as L, type MountCheckoutOptions as M, type LoyaltyCardReward as N, type LoyaltyCardStep as O, type PendingCollectItem as P, type LoyaltyRewardState as Q, type RedeemRewardResult as R, type LoyaltyStepProgress as S, type LoyaltyStepState as T, type LoyaltyVaultEntry as U, type PhoneChangeApproval as V, type WaitForPurchaseInput as W, type PhoneChangeDeviceSignal as X, type PurchaseRefusalReason as Y, type Rail as Z, type VerificationMethod as _, type PurchaseStatusResult as a, type PurchaseItemResult as a$, type PlatformPurchaseInput as a0, type PlatformPurchaseResult as a1, type PlatformApprovalResult as a2, type PlatformOrderStatusResult as a3, type PlatformPurchaseHistoryQuery as a4, type PlatformPurchaseHistoryResult as a5, type PlatformRefundInput as a6, type PlatformRefundResult as a7, type CreateSubscriptionInput as a8, type SubscriptionResult as a9, type MintPlayerTokenInput as aA, type PlayerToken as aB, type RegisterPlayerInput as aC, type RegisterPlayerResult as aD, type UpdatePlayerPhoneInput as aE, type UpdatePlayerPhoneResult as aF, type RequestPhoneChangeInput as aG, type RequestPhoneChangeResult as aH, type PhoneChangeRequest as aI, type InitiateSendInput as aJ, type InitiateResult as aK, type InitiateTransferInput as aL, type CreateCheckoutInput as aM, type CreateCheckoutResult as aN, type PurchaseInput as aO, type PurchaseResult as aP, type CurrencyPurchaseQuoteInput as aQ, type CurrencyPurchaseQuote as aR, type ConfirmPaymentResult as aS, type OrderDetailsResult as aT, type SteamPacksQuery as aU, type SteamPacksResult as aV, type SteamInitPurchaseInput as aW, type SteamInitPurchaseResult as aX, type SteamFinalizeInput as aY, type SteamFinalizeResult as aZ, type PurchaseItemInput as a_, type GetSubscriptionOptions as aa, type GetSubscriptionResult as ab, type ListSubscriptionsOptions as ac, type SubscriptionListResult as ad, type CancelSubscriptionOptions as ae, type CancelResult as af, type ChangeAmountResult as ag, type SetPaymentMethodInput as ah, type SetPaymentMethodResult as ai, type RefundSubscriptionInput as aj, type RefundResult as ak, type SteamSubscriptionInitInput as al, type SteamInitResult as am, type SteamFinalizeSubscriptionResult as an, type CardSetupSessionInput as ao, type CardSetupSessionResult as ap, type CardSetupInput as aq, type CardSetupResult as ar, type CardSetupConfirmInput as as, type CardSetupConfirmResult as at, type PlayerCardsResult as au, type SandboxClockResult as av, type SandboxFailureOutcome as aw, type SandboxForceFailureOptions as ax, type SandboxForceAuthChallengeOptions as ay, type ServerConfig as az, type PurchaseCredited as b, type SavedCard as b$, type ItemHistoryQuery as b0, type ItemHistoryResult as b1, type ItemOrderQuery as b2, type PlayerActivityQuery as b3, type PlayerActivityResult as b4, type PlayerActivityEntry as b5, type PlayerBalanceQuery as b6, type PlayerBalanceResult as b7, type InboundPendingQuery as b8, type InboundPendingResult as b9, type CurrencyBalance as bA, type CurrencyPurchaseQuoteBreakdown as bB, type DeviceApprovalChannel as bC, type DeviceApprovalEnrollment as bD, type DeviceApprovalFlow as bE, type DeviceApprovalPollStatus as bF, type DeviceEnrollmentDecision as bG, type DeviceEnrollmentRespond as bH, type ExpiryReason as bI, type FeeTakenFrom as bJ, type FirstCharge as bK, type FirstChargeStatus as bL, type FundingSource as bM, type InboundPendingItem as bN, type LinkedIdentityEmail as bO, type MinPurchaseWarning as bP, type PhoneChangeConfirmation as bQ, type PhoneChangeRequestStatus as bR, type PlatformPurchaseStatus as bS, type PlayerActivityType as bT, type RefundInitiation as bU, type RefundPendingApproval as bV, type RefundProcessingFeeBasis as bW, type RefundReceipt as bX, type RefundRevenueShareAttribution as bY, type RefundWarning as bZ, type SandboxClockState as b_, type LinkedIdentitiesQuery as ba, type LinkedIdentitiesResult as bb, type SmsVerifyResult as bc, type ClaimTransferInput as bd, type ClaimResult as be, type ClaimCurrencyInput as bf, type TransactionStatusResult as bg, type GuardianApprovalStatusResult as bh, type ServerDestinationsQuery as bi, type PhoneShareContact as bj, type PhoneShareInitiateResult as bk, type PhoneShareApproveInput as bl, type PhoneShareApproveResult as bm, type PhoneShareStatusResult as bn, type BeginDeviceApprovalInput as bo, type DeviceApprovalGrant as bp, type PollDeviceApprovalInput as bq, type DeviceApprovalPollResult as br, type ConfirmDeviceEnrollmentInput as bs, type ConfirmDeviceEnrollmentResult as bt, type ApproveWithDeviceCodeInput as bu, type DeviceApprovalSettleResult as bv, type CompleteDeviceApprovalInput as bw, type CompleteDeviceApprovalResult as bx, type CardSetupStatus as by, type CheckoutWarning as bz, type PurchaseExpired as c, type SteamPack as c0, type SteamUserSession as c1, type Subscription as c2, type SubscriptionBaseInput as c3, type SubscriptionConsent as c4, type SubscriptionConsentInput as c5, type SubscriptionFundingRail as c6, type SubscriptionInterval as c7, type SubscriptionRevenueShare as c8, type SubscriptionRevenueShareInput as c9, type SubscriptionStatus as ca, type UnacknowledgedPurchaseOutcome as cb, isRefundPendingApproval as cc, type PurchaseRefunded as d, type PurchaseRefused as e, type PurchaseStatusInput as f, type CallOptions as g, type CheckoutMountHandle as h, type ClientConfig as i, type ConfirmReceiptResult as j, type PhoneChangeApprovalsResult as k, type ApprovePhoneChangeInput as l, type ApprovePhoneChangeResult as m, type PendingCollectResult as n, type DestinationsQuery as o, type DestinationsResult as p, type LoyaltyCardsResult as q, type LoyaltyVaultResult as r, type RewardsPageLink as s, type EnrollmentVerifyResult as t, type RecoveryBeginResult as u, type RecoveryCompleteResult as v, type BalanceRow as w, type CheckoutPurchaseStatus as x, type ClaimDelivery as y, type InvoErrorInfo as z };
3950
+ export { type AuthHeader as $, type ApproveResult as A, type BalanceResult as B, type CheckoutClientConfig as C, type DestinationGame as D, type EnrollmentBeginResult as E, type InvoHooks as F, type InvoRequestInfo as G, Http as H, InvoError as I, type InvoResponseInfo as J, type LoyaltyCard as K, type LinkDeviceResult as L, type MountCheckoutOptions as M, type LoyaltyCardReward as N, type LoyaltyCardStep as O, type PendingCollectItem as P, type LoyaltyRewardState as Q, type RedeemRewardResult as R, type LoyaltyStepProgress as S, type LoyaltyStepState as T, type LoyaltyVaultEntry as U, type PhoneChangeApproval as V, type WaitForPurchaseInput as W, type PhoneChangeDeviceSignal as X, type PurchaseRefusalReason as Y, type Rail as Z, type VerificationMethod as _, type PurchaseStatusResult as a, type AppleProductsResult as a$, type ApplePurchaseResult as a0, type PlatformPurchaseInput as a1, type PlatformPurchaseResult as a2, type PlatformApprovalResult as a3, type PlatformOrderStatusResult as a4, type PlatformPurchaseHistoryQuery as a5, type PlatformPurchaseHistoryResult as a6, type PlatformRefundInput as a7, type PlatformRefundResult as a8, type CreateSubscriptionInput as a9, type ServerConfig as aA, type MintPlayerTokenInput as aB, type PlayerToken as aC, type RegisterPlayerInput as aD, type RegisterPlayerResult as aE, type UpdatePlayerPhoneInput as aF, type UpdatePlayerPhoneResult as aG, type RequestPhoneChangeInput as aH, type RequestPhoneChangeResult as aI, type PhoneChangeRequest as aJ, type InitiateSendInput as aK, type InitiateResult as aL, type InitiateTransferInput as aM, type CreateCheckoutInput as aN, type CreateCheckoutResult as aO, type PurchaseInput as aP, type PurchaseResult as aQ, type CurrencyPurchaseQuoteInput as aR, type CurrencyPurchaseQuote as aS, type ConfirmPaymentResult as aT, type OrderDetailsResult as aU, type SteamPacksQuery as aV, type SteamPacksResult as aW, type SteamInitPurchaseInput as aX, type SteamInitPurchaseResult as aY, type SteamFinalizeInput as aZ, type SteamFinalizeResult as a_, type SubscriptionResult as aa, type GetSubscriptionOptions as ab, type GetSubscriptionResult as ac, type ListSubscriptionsOptions as ad, type SubscriptionListResult as ae, type CancelSubscriptionOptions as af, type CancelResult as ag, type ChangeAmountResult as ah, type SetPaymentMethodInput as ai, type SetPaymentMethodResult as aj, type RefundSubscriptionInput as ak, type RefundResult as al, type SteamSubscriptionInitInput as am, type SteamInitResult as an, type SteamFinalizeSubscriptionResult as ao, type CardSetupSessionInput as ap, type CardSetupSessionResult as aq, type CardSetupInput as ar, type CardSetupResult as as, type CardSetupConfirmInput as at, type CardSetupConfirmResult as au, type PlayerCardsResult as av, type SandboxClockResult as aw, type SandboxFailureOutcome as ax, type SandboxForceFailureOptions as ay, type SandboxForceAuthChallengeOptions as az, type PurchaseCredited as b, type RefundInitiation as b$, type VerifyApplePurchaseInput as b0, type PurchaseItemInput as b1, type PurchaseItemResult as b2, type ItemHistoryQuery as b3, type ItemHistoryResult as b4, type ItemOrderQuery as b5, type PlayerActivityQuery as b6, type PlayerActivityResult as b7, type PlayerActivityEntry as b8, type PlayerBalanceQuery as b9, type CompleteDeviceApprovalResult as bA, type AppleEnvironment as bB, type AppleProduct as bC, type ApplePurchaseStatus as bD, type AppleUnavailableReason as bE, type CardSetupStatus as bF, type CheckoutWarning as bG, type CurrencyBalance as bH, type CurrencyPurchaseQuoteBreakdown as bI, type DeviceApprovalChannel as bJ, type DeviceApprovalEnrollment as bK, type DeviceApprovalFlow as bL, type DeviceApprovalPollStatus as bM, type DeviceEnrollmentDecision as bN, type DeviceEnrollmentRespond as bO, type ExpiryReason as bP, type FeeTakenFrom as bQ, type FirstCharge as bR, type FirstChargeStatus as bS, type FundingSource as bT, type InboundPendingItem as bU, type LinkedIdentityEmail as bV, type MinPurchaseWarning as bW, type PhoneChangeConfirmation as bX, type PhoneChangeRequestStatus as bY, type PlatformPurchaseStatus as bZ, type PlayerActivityType as b_, type PlayerBalanceResult as ba, type InboundPendingQuery as bb, type InboundPendingResult as bc, type LinkedIdentitiesQuery as bd, type LinkedIdentitiesResult as be, type SmsVerifyResult as bf, type ClaimTransferInput as bg, type ClaimResult as bh, type ClaimCurrencyInput as bi, type TransactionStatusResult as bj, type GuardianApprovalStatusResult as bk, type ServerDestinationsQuery as bl, type PhoneShareContact as bm, type PhoneShareInitiateResult as bn, type PhoneShareApproveInput as bo, type PhoneShareApproveResult as bp, type PhoneShareStatusResult as bq, type BeginDeviceApprovalInput as br, type DeviceApprovalGrant as bs, type PollDeviceApprovalInput as bt, type DeviceApprovalPollResult as bu, type ConfirmDeviceEnrollmentInput as bv, type ConfirmDeviceEnrollmentResult as bw, type ApproveWithDeviceCodeInput as bx, type DeviceApprovalSettleResult as by, type CompleteDeviceApprovalInput as bz, type PurchaseExpired as c, type RefundPendingApproval as c0, type RefundProcessingFeeBasis as c1, type RefundReceipt as c2, type RefundRevenueShareAttribution as c3, type RefundWarning as c4, type SandboxClockState as c5, type SavedCard as c6, type SteamPack as c7, type SteamUserSession as c8, type Subscription as c9, type SubscriptionBaseInput as ca, type SubscriptionConsent as cb, type SubscriptionConsentInput as cc, type SubscriptionFundingRail as cd, type SubscriptionInterval as ce, type SubscriptionRevenueShare as cf, type SubscriptionRevenueShareInput as cg, type SubscriptionStatus as ch, type UnacknowledgedPurchaseOutcome as ci, isRefundPendingApproval as cj, type PurchaseRefunded as d, type PurchaseRefused as e, type PurchaseStatusInput as f, type CallOptions as g, type CheckoutMountHandle as h, type ClientConfig as i, type ConfirmReceiptResult as j, type PhoneChangeApprovalsResult as k, type ApprovePhoneChangeInput as l, type ApprovePhoneChangeResult as m, type PendingCollectResult as n, type DestinationsQuery as o, type DestinationsResult as p, type LoyaltyCardsResult as q, type LoyaltyVaultResult as r, type RewardsPageLink as s, type EnrollmentVerifyResult as t, type RecoveryBeginResult as u, type RecoveryCompleteResult as v, type BalanceRow as w, type CheckoutPurchaseStatus as x, type ClaimDelivery as y, type InvoErrorInfo as z };
@@ -867,6 +867,65 @@ declare class InvoError extends Error {
867
867
  * and send the same request again. Branch on this, not on the message.
868
868
  */
869
869
  get isRateLimited(): boolean;
870
+ /**
871
+ * The body's boolean `finish` (additive, 3.35.0), sent on every `verifyApplePurchase`
872
+ * answer: `true` when the game should call StoreKit's `Transaction.finish()` for this
873
+ * refusal (nothing can ever be delivered), `false` when it should leave the transaction
874
+ * unfinished and retry. `undefined` when the body carries none (any other endpoint, an
875
+ * older backend, or a network error); `shouldFinishAppleTransaction(err)` then falls back
876
+ * to the error code.
877
+ */
878
+ get finish(): boolean | undefined;
879
+ /** Not a genuine Apple transaction (`APPLE_SIGNATURE_INVALID`, 400). Leave it unfinished. */
880
+ get isAppleSignatureInvalid(): boolean;
881
+ /** Another app's transaction: the bundle id (or Apple ID) is not this game's
882
+ * (`APPLE_BUNDLE_MISMATCH`, 400). */
883
+ get isAppleBundleMismatch(): boolean;
884
+ /** The transaction's environment is not accepted here (`APPLE_ENVIRONMENT_NOT_ALLOWED`, 400).
885
+ * The INVO sandbox takes only Sandbox transactions; Xcode StoreKit-testing transactions are
886
+ * never accepted, because Apple does not sign them. */
887
+ get isAppleEnvironmentNotAllowed(): boolean;
888
+ /** Only consumable products buy currency (`APPLE_PRODUCT_TYPE_UNSUPPORTED`, 400). */
889
+ get isAppleProductTypeUnsupported(): boolean;
890
+ /** The product id is not registered for this game (`APPLE_PRODUCT_UNKNOWN`, 400). Register
891
+ * it in the INVO console and retry; keep the transaction unfinished meanwhile. */
892
+ get isAppleProductUnknown(): boolean;
893
+ /** `metadata` was refused (`INVALID_METADATA`, 400). Fix the request and retry. */
894
+ get isInvalidMetadata(): boolean;
895
+ /** A Sandbox purchase on INVO production by an account not on the game's App Review list
896
+ * (`APPLE_REVIEW_ACCOUNT_REQUIRED`, 403). */
897
+ get isAppleReviewAccountRequired(): boolean;
898
+ /** Apple refunded or revoked the transaction (`APPLE_TRANSACTION_REVOKED`, 409). Nothing can
899
+ * ever be delivered for it: **finish it** (`finish: true`). */
900
+ get isAppleTransactionRevoked(): boolean;
901
+ /** The transaction was already credited in another INVO game
902
+ * (`APPLE_TRANSACTION_ALREADY_USED`, 409). Terminal: **finish it** (`finish: true`). */
903
+ get isAppleTransactionAlreadyUsed(): boolean;
904
+ /** Bought before the game sold through INVO (`APPLE_TRANSACTION_TOO_OLD`, 409). Terminal:
905
+ * **finish it** (`finish: true`). */
906
+ get isAppleTransactionTooOld(): boolean;
907
+ /** The product's coins are out of proportion to its signed price, or over the per-purchase
908
+ * maximum (`APPLE_VALUE_EXCEEDS_PRICE`, 409). Fix the product mapping and retry. */
909
+ get isAppleValueExceedsPrice(): boolean;
910
+ /** The transaction's `appAccountToken` is not the one you sent: it was made for a
911
+ * different player (`APPLE_ACCOUNT_TOKEN_MISMATCH`, 409). */
912
+ get isAppleAccountTokenMismatch(): boolean;
913
+ /** The game's Apple configuration is missing or turned off (`APPLE_NOT_CONFIGURED`, 409).
914
+ * Retry once it is set up. */
915
+ get isAppleNotConfigured(): boolean;
916
+ /** Production has not yet confirmed you own the App Store app (`APPLE_NOT_VERIFIED`, 409).
917
+ * Point App Store Server Notifications at INVO; retry once verified. */
918
+ get isAppleNotVerified(): boolean;
919
+ /** Today's App Review purchase cap on production is reached (`APPLE_REVIEW_PURCHASE_LIMIT`,
920
+ * 429). */
921
+ get isAppleReviewPurchaseLimit(): boolean;
922
+ /** Verified and held, not refused (`APPLE_CREDIT_PENDING`, 503): the coins will credit on a
923
+ * later retry. Keep the transaction unfinished and retry; StoreKit also redelivers it. */
924
+ get isAppleCreditPending(): boolean;
925
+ /** A card purchase (`purchaseCurrency`) was made with a key on the Apple rail
926
+ * (`WRONG_RAIL_ENDPOINT`, 400, `status: "use_apple_endpoint"`). Use
927
+ * `verifyApplePurchase` for that key. */
928
+ get isAppleEndpointRequired(): boolean;
870
929
  /** `body` as a plain object, or `{}` if it's a string/number/null (non-JSON responses).
871
930
  * The `in` operator throws on primitives, so callers must go through this. */
872
931
  private bodyObject;
@@ -1830,6 +1889,92 @@ interface SteamFinalizeResult {
1830
1889
  reasonCode?: string | null;
1831
1890
  raw: Record<string, unknown>;
1832
1891
  }
1892
+ /**
1893
+ * Why INVO will not sell a product through Apple right now (`unavailableReason`).
1894
+ * Open-ended: treat any other value as "not available".
1895
+ *
1896
+ * - `APPLE_NOT_VERIFIED`: production has not yet confirmed you own the App Store app
1897
+ * (it does on the first App Store Server Notification).
1898
+ * - `PARTNER_BILLING_NOT_SET_UP`: the developer account has no INVO billing set up.
1899
+ * - `PARTNER_RAIL_SUSPENDED`: the developer account's settlement is suspended.
1900
+ * - `PARTNER_CREDIT_UNAVAILABLE`: no headroom for this product's coins right now.
1901
+ */
1902
+ type AppleUnavailableReason = "APPLE_NOT_VERIFIED" | "PARTNER_BILLING_NOT_SET_UP" | "PARTNER_RAIL_SUSPENDED" | "PARTNER_CREDIT_UNAVAILABLE" | (string & {});
1903
+ /** One App Store product registered for the game in the INVO console. */
1904
+ interface AppleProduct {
1905
+ /** The App Store Connect product id. Ask StoreKit for exactly these ids. */
1906
+ productId: string;
1907
+ /** Coins the product credits, fixed per product. */
1908
+ coins: number;
1909
+ /** Display label from the console (the product id when none was set). */
1910
+ label: string;
1911
+ /** The US App Store price registered in the console, decimal string, or `null`. */
1912
+ priceUsd: string | null;
1913
+ /** Always `true` here: retired products are not listed. */
1914
+ active: boolean;
1915
+ /** Offer the product only when this is `true`. Apple charges before INVO sees the purchase. */
1916
+ available: boolean;
1917
+ /** Set when `available` is `false`. */
1918
+ unavailableReason: AppleUnavailableReason | null;
1919
+ }
1920
+ interface AppleProductsResult {
1921
+ /** The App Store bundle id registered for the game. */
1922
+ bundleId: string;
1923
+ /** `false` when nothing can be sold right now; `unavailableReason` says why. */
1924
+ canSell: boolean;
1925
+ unavailableReason: AppleUnavailableReason | null;
1926
+ products: AppleProduct[];
1927
+ raw: Record<string, unknown>;
1928
+ }
1929
+ /** The App Store environment of a verified transaction. */
1930
+ type AppleEnvironment = "Production" | "Sandbox" | (string & {});
1931
+ interface VerifyApplePurchaseInput {
1932
+ playerEmail: string;
1933
+ /**
1934
+ * StoreKit 2's `Transaction.jwsRepresentation` (or `VerificationResult.jwsRepresentation`),
1935
+ * sent unchanged. INVO verifies Apple's signature; never decode or trust it yourself first.
1936
+ */
1937
+ signedTransaction: string;
1938
+ /**
1939
+ * The UUID your game set as `appAccountToken` on the purchase, when it set one. INVO
1940
+ * refuses a transaction whose token differs (`APPLE_ACCOUNT_TOKEN_MISMATCH`).
1941
+ */
1942
+ appAccountToken?: string;
1943
+ /** Used only when INVO creates the player on this purchase. */
1944
+ playerName?: string;
1945
+ /** Your own JSON, echoed on `purchase.completed` and `purchase.refunded` (`data.metadata`). */
1946
+ metadata?: Record<string, unknown>;
1947
+ }
1948
+ /** `credited`: added by this call. `already_credited`: a replay of a transaction INVO already credited. */
1949
+ type ApplePurchaseStatus = "credited" | "already_credited";
1950
+ interface ApplePurchaseResult {
1951
+ status: ApplePurchaseStatus;
1952
+ orderId: string;
1953
+ /** Apple's `transactionId`. */
1954
+ transactionId: string;
1955
+ productId: string;
1956
+ /** Coins credited for this transaction. */
1957
+ coins: number;
1958
+ /**
1959
+ * The player's balance after the credit, decimal string. On `already_credited` it is
1960
+ * `null` unless the call names the same player the transaction was credited to.
1961
+ */
1962
+ balance: string | null;
1963
+ environment: AppleEnvironment;
1964
+ /**
1965
+ * `true` only for an App Review (Sandbox) purchase accepted on INVO production. On the INVO
1966
+ * sandbox, where every transaction is a Sandbox one, it is `false`.
1967
+ */
1968
+ testMode: boolean;
1969
+ /**
1970
+ * Whether to call StoreKit's `Transaction.finish()`: INVO's `finish` flag (`true` on both
1971
+ * success statuses). From an older backend that sends none, `true` for `credited` and
1972
+ * `already_credited`. Prefer `shouldFinishAppleTransaction(resultOrError)`, which also
1973
+ * covers the thrown errors.
1974
+ */
1975
+ finish: boolean;
1976
+ raw: Record<string, unknown>;
1977
+ }
1833
1978
  interface PurchaseItemInput {
1834
1979
  /** Idempotency key, unique per game. Required. A duplicate returns 409. */
1835
1980
  clientRequestId: string;
@@ -3802,4 +3947,4 @@ interface RewardsPageLink {
3802
3947
  raw: Record<string, unknown>;
3803
3948
  }
3804
3949
 
3805
- export { type AuthHeader as $, type ApproveResult as A, type BalanceResult as B, type CheckoutClientConfig as C, type DestinationGame as D, type EnrollmentBeginResult as E, type InvoHooks as F, type InvoRequestInfo as G, Http as H, InvoError as I, type InvoResponseInfo as J, type LoyaltyCard as K, type LinkDeviceResult as L, type MountCheckoutOptions as M, type LoyaltyCardReward as N, type LoyaltyCardStep as O, type PendingCollectItem as P, type LoyaltyRewardState as Q, type RedeemRewardResult as R, type LoyaltyStepProgress as S, type LoyaltyStepState as T, type LoyaltyVaultEntry as U, type PhoneChangeApproval as V, type WaitForPurchaseInput as W, type PhoneChangeDeviceSignal as X, type PurchaseRefusalReason as Y, type Rail as Z, type VerificationMethod as _, type PurchaseStatusResult as a, type PurchaseItemResult as a$, type PlatformPurchaseInput as a0, type PlatformPurchaseResult as a1, type PlatformApprovalResult as a2, type PlatformOrderStatusResult as a3, type PlatformPurchaseHistoryQuery as a4, type PlatformPurchaseHistoryResult as a5, type PlatformRefundInput as a6, type PlatformRefundResult as a7, type CreateSubscriptionInput as a8, type SubscriptionResult as a9, type MintPlayerTokenInput as aA, type PlayerToken as aB, type RegisterPlayerInput as aC, type RegisterPlayerResult as aD, type UpdatePlayerPhoneInput as aE, type UpdatePlayerPhoneResult as aF, type RequestPhoneChangeInput as aG, type RequestPhoneChangeResult as aH, type PhoneChangeRequest as aI, type InitiateSendInput as aJ, type InitiateResult as aK, type InitiateTransferInput as aL, type CreateCheckoutInput as aM, type CreateCheckoutResult as aN, type PurchaseInput as aO, type PurchaseResult as aP, type CurrencyPurchaseQuoteInput as aQ, type CurrencyPurchaseQuote as aR, type ConfirmPaymentResult as aS, type OrderDetailsResult as aT, type SteamPacksQuery as aU, type SteamPacksResult as aV, type SteamInitPurchaseInput as aW, type SteamInitPurchaseResult as aX, type SteamFinalizeInput as aY, type SteamFinalizeResult as aZ, type PurchaseItemInput as a_, type GetSubscriptionOptions as aa, type GetSubscriptionResult as ab, type ListSubscriptionsOptions as ac, type SubscriptionListResult as ad, type CancelSubscriptionOptions as ae, type CancelResult as af, type ChangeAmountResult as ag, type SetPaymentMethodInput as ah, type SetPaymentMethodResult as ai, type RefundSubscriptionInput as aj, type RefundResult as ak, type SteamSubscriptionInitInput as al, type SteamInitResult as am, type SteamFinalizeSubscriptionResult as an, type CardSetupSessionInput as ao, type CardSetupSessionResult as ap, type CardSetupInput as aq, type CardSetupResult as ar, type CardSetupConfirmInput as as, type CardSetupConfirmResult as at, type PlayerCardsResult as au, type SandboxClockResult as av, type SandboxFailureOutcome as aw, type SandboxForceFailureOptions as ax, type SandboxForceAuthChallengeOptions as ay, type ServerConfig as az, type PurchaseCredited as b, type SavedCard as b$, type ItemHistoryQuery as b0, type ItemHistoryResult as b1, type ItemOrderQuery as b2, type PlayerActivityQuery as b3, type PlayerActivityResult as b4, type PlayerActivityEntry as b5, type PlayerBalanceQuery as b6, type PlayerBalanceResult as b7, type InboundPendingQuery as b8, type InboundPendingResult as b9, type CurrencyBalance as bA, type CurrencyPurchaseQuoteBreakdown as bB, type DeviceApprovalChannel as bC, type DeviceApprovalEnrollment as bD, type DeviceApprovalFlow as bE, type DeviceApprovalPollStatus as bF, type DeviceEnrollmentDecision as bG, type DeviceEnrollmentRespond as bH, type ExpiryReason as bI, type FeeTakenFrom as bJ, type FirstCharge as bK, type FirstChargeStatus as bL, type FundingSource as bM, type InboundPendingItem as bN, type LinkedIdentityEmail as bO, type MinPurchaseWarning as bP, type PhoneChangeConfirmation as bQ, type PhoneChangeRequestStatus as bR, type PlatformPurchaseStatus as bS, type PlayerActivityType as bT, type RefundInitiation as bU, type RefundPendingApproval as bV, type RefundProcessingFeeBasis as bW, type RefundReceipt as bX, type RefundRevenueShareAttribution as bY, type RefundWarning as bZ, type SandboxClockState as b_, type LinkedIdentitiesQuery as ba, type LinkedIdentitiesResult as bb, type SmsVerifyResult as bc, type ClaimTransferInput as bd, type ClaimResult as be, type ClaimCurrencyInput as bf, type TransactionStatusResult as bg, type GuardianApprovalStatusResult as bh, type ServerDestinationsQuery as bi, type PhoneShareContact as bj, type PhoneShareInitiateResult as bk, type PhoneShareApproveInput as bl, type PhoneShareApproveResult as bm, type PhoneShareStatusResult as bn, type BeginDeviceApprovalInput as bo, type DeviceApprovalGrant as bp, type PollDeviceApprovalInput as bq, type DeviceApprovalPollResult as br, type ConfirmDeviceEnrollmentInput as bs, type ConfirmDeviceEnrollmentResult as bt, type ApproveWithDeviceCodeInput as bu, type DeviceApprovalSettleResult as bv, type CompleteDeviceApprovalInput as bw, type CompleteDeviceApprovalResult as bx, type CardSetupStatus as by, type CheckoutWarning as bz, type PurchaseExpired as c, type SteamPack as c0, type SteamUserSession as c1, type Subscription as c2, type SubscriptionBaseInput as c3, type SubscriptionConsent as c4, type SubscriptionConsentInput as c5, type SubscriptionFundingRail as c6, type SubscriptionInterval as c7, type SubscriptionRevenueShare as c8, type SubscriptionRevenueShareInput as c9, type SubscriptionStatus as ca, type UnacknowledgedPurchaseOutcome as cb, isRefundPendingApproval as cc, type PurchaseRefunded as d, type PurchaseRefused as e, type PurchaseStatusInput as f, type CallOptions as g, type CheckoutMountHandle as h, type ClientConfig as i, type ConfirmReceiptResult as j, type PhoneChangeApprovalsResult as k, type ApprovePhoneChangeInput as l, type ApprovePhoneChangeResult as m, type PendingCollectResult as n, type DestinationsQuery as o, type DestinationsResult as p, type LoyaltyCardsResult as q, type LoyaltyVaultResult as r, type RewardsPageLink as s, type EnrollmentVerifyResult as t, type RecoveryBeginResult as u, type RecoveryCompleteResult as v, type BalanceRow as w, type CheckoutPurchaseStatus as x, type ClaimDelivery as y, type InvoErrorInfo as z };
3950
+ export { type AuthHeader as $, type ApproveResult as A, type BalanceResult as B, type CheckoutClientConfig as C, type DestinationGame as D, type EnrollmentBeginResult as E, type InvoHooks as F, type InvoRequestInfo as G, Http as H, InvoError as I, type InvoResponseInfo as J, type LoyaltyCard as K, type LinkDeviceResult as L, type MountCheckoutOptions as M, type LoyaltyCardReward as N, type LoyaltyCardStep as O, type PendingCollectItem as P, type LoyaltyRewardState as Q, type RedeemRewardResult as R, type LoyaltyStepProgress as S, type LoyaltyStepState as T, type LoyaltyVaultEntry as U, type PhoneChangeApproval as V, type WaitForPurchaseInput as W, type PhoneChangeDeviceSignal as X, type PurchaseRefusalReason as Y, type Rail as Z, type VerificationMethod as _, type PurchaseStatusResult as a, type AppleProductsResult as a$, type ApplePurchaseResult as a0, type PlatformPurchaseInput as a1, type PlatformPurchaseResult as a2, type PlatformApprovalResult as a3, type PlatformOrderStatusResult as a4, type PlatformPurchaseHistoryQuery as a5, type PlatformPurchaseHistoryResult as a6, type PlatformRefundInput as a7, type PlatformRefundResult as a8, type CreateSubscriptionInput as a9, type ServerConfig as aA, type MintPlayerTokenInput as aB, type PlayerToken as aC, type RegisterPlayerInput as aD, type RegisterPlayerResult as aE, type UpdatePlayerPhoneInput as aF, type UpdatePlayerPhoneResult as aG, type RequestPhoneChangeInput as aH, type RequestPhoneChangeResult as aI, type PhoneChangeRequest as aJ, type InitiateSendInput as aK, type InitiateResult as aL, type InitiateTransferInput as aM, type CreateCheckoutInput as aN, type CreateCheckoutResult as aO, type PurchaseInput as aP, type PurchaseResult as aQ, type CurrencyPurchaseQuoteInput as aR, type CurrencyPurchaseQuote as aS, type ConfirmPaymentResult as aT, type OrderDetailsResult as aU, type SteamPacksQuery as aV, type SteamPacksResult as aW, type SteamInitPurchaseInput as aX, type SteamInitPurchaseResult as aY, type SteamFinalizeInput as aZ, type SteamFinalizeResult as a_, type SubscriptionResult as aa, type GetSubscriptionOptions as ab, type GetSubscriptionResult as ac, type ListSubscriptionsOptions as ad, type SubscriptionListResult as ae, type CancelSubscriptionOptions as af, type CancelResult as ag, type ChangeAmountResult as ah, type SetPaymentMethodInput as ai, type SetPaymentMethodResult as aj, type RefundSubscriptionInput as ak, type RefundResult as al, type SteamSubscriptionInitInput as am, type SteamInitResult as an, type SteamFinalizeSubscriptionResult as ao, type CardSetupSessionInput as ap, type CardSetupSessionResult as aq, type CardSetupInput as ar, type CardSetupResult as as, type CardSetupConfirmInput as at, type CardSetupConfirmResult as au, type PlayerCardsResult as av, type SandboxClockResult as aw, type SandboxFailureOutcome as ax, type SandboxForceFailureOptions as ay, type SandboxForceAuthChallengeOptions as az, type PurchaseCredited as b, type RefundInitiation as b$, type VerifyApplePurchaseInput as b0, type PurchaseItemInput as b1, type PurchaseItemResult as b2, type ItemHistoryQuery as b3, type ItemHistoryResult as b4, type ItemOrderQuery as b5, type PlayerActivityQuery as b6, type PlayerActivityResult as b7, type PlayerActivityEntry as b8, type PlayerBalanceQuery as b9, type CompleteDeviceApprovalResult as bA, type AppleEnvironment as bB, type AppleProduct as bC, type ApplePurchaseStatus as bD, type AppleUnavailableReason as bE, type CardSetupStatus as bF, type CheckoutWarning as bG, type CurrencyBalance as bH, type CurrencyPurchaseQuoteBreakdown as bI, type DeviceApprovalChannel as bJ, type DeviceApprovalEnrollment as bK, type DeviceApprovalFlow as bL, type DeviceApprovalPollStatus as bM, type DeviceEnrollmentDecision as bN, type DeviceEnrollmentRespond as bO, type ExpiryReason as bP, type FeeTakenFrom as bQ, type FirstCharge as bR, type FirstChargeStatus as bS, type FundingSource as bT, type InboundPendingItem as bU, type LinkedIdentityEmail as bV, type MinPurchaseWarning as bW, type PhoneChangeConfirmation as bX, type PhoneChangeRequestStatus as bY, type PlatformPurchaseStatus as bZ, type PlayerActivityType as b_, type PlayerBalanceResult as ba, type InboundPendingQuery as bb, type InboundPendingResult as bc, type LinkedIdentitiesQuery as bd, type LinkedIdentitiesResult as be, type SmsVerifyResult as bf, type ClaimTransferInput as bg, type ClaimResult as bh, type ClaimCurrencyInput as bi, type TransactionStatusResult as bj, type GuardianApprovalStatusResult as bk, type ServerDestinationsQuery as bl, type PhoneShareContact as bm, type PhoneShareInitiateResult as bn, type PhoneShareApproveInput as bo, type PhoneShareApproveResult as bp, type PhoneShareStatusResult as bq, type BeginDeviceApprovalInput as br, type DeviceApprovalGrant as bs, type PollDeviceApprovalInput as bt, type DeviceApprovalPollResult as bu, type ConfirmDeviceEnrollmentInput as bv, type ConfirmDeviceEnrollmentResult as bw, type ApproveWithDeviceCodeInput as bx, type DeviceApprovalSettleResult as by, type CompleteDeviceApprovalInput as bz, type PurchaseExpired as c, type RefundPendingApproval as c0, type RefundProcessingFeeBasis as c1, type RefundReceipt as c2, type RefundRevenueShareAttribution as c3, type RefundWarning as c4, type SandboxClockState as c5, type SavedCard as c6, type SteamPack as c7, type SteamUserSession as c8, type Subscription as c9, type SubscriptionBaseInput as ca, type SubscriptionConsent as cb, type SubscriptionConsentInput as cc, type SubscriptionFundingRail as cd, type SubscriptionInterval as ce, type SubscriptionRevenueShare as cf, type SubscriptionRevenueShareInput as cg, type SubscriptionStatus as ch, type UnacknowledgedPurchaseOutcome as ci, isRefundPendingApproval as cj, type PurchaseRefunded as d, type PurchaseRefused as e, type PurchaseStatusInput as f, type CallOptions as g, type CheckoutMountHandle as h, type ClientConfig as i, type ConfirmReceiptResult as j, type PhoneChangeApprovalsResult as k, type ApprovePhoneChangeInput as l, type ApprovePhoneChangeResult as m, type PendingCollectResult as n, type DestinationsQuery as o, type DestinationsResult as p, type LoyaltyCardsResult as q, type LoyaltyVaultResult as r, type RewardsPageLink as s, type EnrollmentVerifyResult as t, type RecoveryBeginResult as u, type RecoveryCompleteResult as v, type BalanceRow as w, type CheckoutPurchaseStatus as x, type ClaimDelivery as y, type InvoErrorInfo as z };