@virex-tech/paywallo-sdk 1.1.3 → 1.3.0

package/dist/index.d.mts

@@ -116,6 +116,7 @@ interface ServerProductInfo {
 }
 interface CampaignResponse {
     campaignId: string;
+    placement?: string;
     variantKey: string;
     paywall: {
         id: string;
@@ -183,6 +184,31 @@ interface EmergencyPaywallResponse {
     paywall?: PaywallConfig;
 }
 
+declare class PaywalloError extends Error {
+    readonly code: string;
+    readonly domain: string;
+    constructor(domain: string, code: string, message: string);
+}
+
+declare class PurchaseError extends PaywalloError {
+    readonly userCancelled: boolean;
+    constructor(code: string, message: string, userCancelled?: boolean);
+}
+declare const PURCHASE_ERROR_CODES: {
+    readonly NOT_INITIALIZED: "PURCHASE_NOT_INITIALIZED";
+    readonly PRODUCT_NOT_FOUND: "PRODUCT_NOT_FOUND";
+    readonly PURCHASE_FAILED: "PURCHASE_FAILED";
+    readonly RESTORE_FAILED: "RESTORE_FAILED";
+    readonly VALIDATION_FAILED: "VALIDATION_FAILED";
+    readonly USER_CANCELLED: "USER_CANCELLED";
+    readonly NETWORK_ERROR: "PURCHASE_NETWORK_ERROR";
+    readonly STORE_ERROR: "PURCHASE_STORE_ERROR";
+    readonly PENDING_PURCHASE: "PURCHASE_PENDING";
+    readonly DEFERRED_PURCHASE: "PURCHASE_DEFERRED";
+    readonly STORE_NOT_AVAILABLE: "PURCHASE_STORE_NOT_AVAILABLE";
+};
+declare function createPurchaseError(code: keyof typeof PURCHASE_ERROR_CODES, message?: string): PurchaseError;
+
 interface Product {
     productId: string;
     title: string;
@@ -196,6 +222,7 @@ interface Product {
     introductoryPrice?: string;
     introductoryPriceValue?: number;
     freeTrialPeriod?: string;
+    trialDays?: number;
     pricePerMonth?: string;
     pricePerWeek?: string;
     pricePerDay?: string;
@@ -212,7 +239,7 @@ interface Purchase {
 interface PurchaseResult {
     success: boolean;
     purchase?: Purchase;
-    error?: Error;
+    error?: PurchaseError;
 }
 interface ValidatePurchaseResponse {
     success: boolean;
@@ -252,10 +279,16 @@ interface ApiClientConfig {
     offlineQueueEnabled?: boolean;
     timeout?: number;
 }
+interface PaywallErrorStrings$1 {
+    title?: string;
+    retry?: string;
+    close?: string;
+}
 interface PaywalloConfig {
     appKey: string;
     debug?: boolean;
     environment?: Environment;
+    errorStrings?: PaywallErrorStrings$1;
 }
 interface UserProperties {
     [key: string]: string | number | boolean | null;
@@ -367,6 +400,7 @@ interface PreloadResult {
 interface PaywalloContextValue {
     config: PaywalloConfig | null;
     isInitialized: boolean;
+    isReady: boolean;
     initError: Error | null;
     distinctId: string | null;
     subscription: Subscription | null;
@@ -386,12 +420,6 @@ interface PaywalloContextValue {
 }
 declare const PaywalloContext: React.Context<PaywalloContextValue | null>;
 
-declare class PaywalloError extends Error {
-    readonly code: string;
-    readonly domain: string;
-    constructor(domain: string, code: string, message: string);
-}
-
 declare class PaywallError extends PaywalloError {
     constructor(code: string, message: string);
 }
@@ -459,8 +487,8 @@ declare class ApiClient {
     private httpClient;
     private readonly cache;
     constructor(appKey: string, debug?: boolean, environment?: Environment, offlineQueueEnabled?: boolean, timeout?: number);
-    /** Exposed only for QueueProcessor initialization. Prefer get()/post() for requests. */
     getHttpClient(): HttpClient;
+    getBaseUrl(): string;
     getWebUrl(): string;
     getEnvironment(): Environment;
     getQueueSize(): number;
@@ -473,7 +501,7 @@ declare class ApiClient {
     post<T>(path: string, body: unknown, skipRetry?: boolean): Promise<HttpResponse<T>>;
     reportError(errorType: string, message: string, context?: Record<string, unknown>): Promise<void>;
     trackEvent(eventName: string, distinctId: string, properties?: UserProperties, timestamp?: number): Promise<void>;
-    identify(distinctId: string, properties?: UserProperties, email?: string): Promise<void>;
+    identify(distinctId: string, properties?: UserProperties, email?: string, deviceId?: string): Promise<void>;
     startSession(distinctId: string, sessionId: string, platform?: string): Promise<{
         success: boolean;
     }>;
@@ -484,23 +512,15 @@ declare class ApiClient {
     getPaywall(placement: string): Promise<PaywallConfig | null>;
     getEmergencyPaywall(): Promise<EmergencyPaywallResponse>;
     getCampaign(placement: string, distinctId: string, context?: Record<string, unknown>): Promise<CampaignResponse | null>;
+    getPrimaryCampaign(distinctId: string): Promise<CampaignResponse | null>;
     validatePurchase(platform: "ios" | "android", receipt: string, productId: string, transactionId: string, priceLocal: number, currency: string, country: string, distinctId?: string, paywallPlacement?: string, variantKey?: string): Promise<ValidatePurchaseResponse>;
     getSubscriptionStatus(distinctId: string): Promise<SubscriptionStatusResponse$1>;
     evaluateFlags(keys: string[], distinctId: string): Promise<Record<string, string | null>>;
     getConditionalFlag(flagKey: string, context: ConditionalFlagContext): Promise<ConditionalFlagResult>;
-    /**
-     * Reads a flag variant from cache layers only — no network call.
-     * Checks in-memory cache first, then SecureStorage.
-     * Returns null when both layers miss.
-     */
     getVariantFromCache(flagKey: string, distinctId: string): Promise<FlagVariant | null>;
     private static readonly FLAG_MAX_AGE_MS;
     private readFlagFromStorage;
     private writeFlagToStorage;
-    /**
-     * POST with offline queue fallback. Enqueues when offline or on network failure.
-     * Throws only when offlineQueueEnabled is false and the request fails.
-     */
     private postWithQueue;
     private log;
 }
@@ -594,11 +614,13 @@ declare class IAPService {
     loadProducts(productIds: string[]): Promise<Product[]>;
     getProduct(productId: string): Product | undefined;
     getCachedProducts(): Map<string, Product>;
+    private validateWithRetry;
     private validateWithServer;
     private finishTransaction;
     purchase(productId: string, options?: {
         paywallPlacement?: string;
         variantKey?: string;
+        onValidating?: () => void;
     }): Promise<PurchaseResult>;
     restore(): Promise<Purchase[]>;
 }
@@ -613,7 +635,7 @@ declare const nativeStoreKit: {
     getActiveTransactions(): Promise<Purchase[]>;
 };
 
-type PurchaseState = "idle" | "loading" | "purchasing" | "restoring" | "error";
+type PurchaseState = "idle" | "loading" | "purchasing" | "validating" | "restoring" | "error";
 interface IAPProduct {
     productId: string;
     price: string;
@@ -630,6 +652,7 @@ interface IAPProduct {
     introductoryPriceNumberOfPeriodsIOS?: string;
     introductoryPriceSubscriptionPeriodIOS?: string;
     freeTrialPeriodAndroid?: string;
+    trialDays: number;
 }
 interface IAPPurchase {
     productId: string;
@@ -653,25 +676,6 @@ interface ProductPriceInfo {
     pricePerDay?: string;
 }
 
-declare class PurchaseError extends PaywalloError {
-    readonly userCancelled: boolean;
-    constructor(code: string, message: string, userCancelled?: boolean);
-}
-declare const PURCHASE_ERROR_CODES: {
-    readonly NOT_INITIALIZED: "PURCHASE_NOT_INITIALIZED";
-    readonly PRODUCT_NOT_FOUND: "PRODUCT_NOT_FOUND";
-    readonly PURCHASE_FAILED: "PURCHASE_FAILED";
-    readonly RESTORE_FAILED: "RESTORE_FAILED";
-    readonly VALIDATION_FAILED: "VALIDATION_FAILED";
-    readonly USER_CANCELLED: "USER_CANCELLED";
-    readonly NETWORK_ERROR: "PURCHASE_NETWORK_ERROR";
-    readonly STORE_ERROR: "PURCHASE_STORE_ERROR";
-    readonly PENDING_PURCHASE: "PURCHASE_PENDING";
-    readonly DEFERRED_PURCHASE: "PURCHASE_DEFERRED";
-    readonly STORE_NOT_AVAILABLE: "PURCHASE_STORE_NOT_AVAILABLE";
-};
-declare function createPurchaseError(code: keyof typeof PURCHASE_ERROR_CODES, message?: string): PurchaseError;
-
 interface IdentityState {
     deviceId: string;
     email: string | null;
@@ -679,6 +683,7 @@ interface IdentityState {
 }
 declare class IdentityManager {
     private deviceId;
+    private anonId;
     private email;
     private properties;
     private apiClient;
@@ -697,7 +702,6 @@ declare class IdentityManager {
     isSecureStorageAvailable(): boolean;
     private loadPersistedState;
     private ensureInitialized;
-    private log;
 }
 declare const identityManager: IdentityManager;
 
@@ -812,16 +816,26 @@ interface PreloadCampaignResult {
     success: boolean;
     error?: Error;
 }
+interface PaywallErrorStrings {
+    title?: string;
+    retry?: string;
+    close?: string;
+}
 interface PaywalloInitConfig extends PaywalloConfig {
     sessionConfig?: SessionConfig;
     autoStartSession?: boolean;
     offlineQueueEnabled?: boolean;
     timeout?: number;
-    /** Request ATT permission during init (iOS only). Default: false. */
     requestATT?: boolean;
+    errorStrings?: PaywallErrorStrings;
+    sessionFlags?: string[];
+    subscriptionCacheTTL?: number;
+    autoPreloadCampaign?: string;
 }
 interface IPaywalloClient {
     init(config: PaywalloInitConfig): Promise<void>;
+    isReady(): boolean;
+    waitUntilReady(): Promise<void>;
     identify(options?: IdentifyOptions | UserProperties): Promise<void>;
     track(eventName: string, options?: TrackEventOptions): Promise<void>;
     getVariantCached(flagKey: string, defaultValue?: string): Promise<FlagVariant>;
@@ -862,6 +876,7 @@ interface IPaywalloClient {
     registerActiveChecker(checker: () => Promise<boolean>): void;
     registerRestoreHandler(handler: () => Promise<RestoreResult>): void;
     registerEmergencyPaywallHandler(handler: EmergencyPaywallHandler): void;
+    getSessionFlag(key: string): string | null;
     isOnline(): boolean;
     getOfflineQueueSize(): number;
     clearOfflineQueue(): Promise<void>;
@@ -871,6 +886,9 @@ interface IPaywalloClient {
     }>;
     onboardingStep(index: number, name: string): Promise<void>;
     coreAction(actionName: string): Promise<void>;
+    isPreloaded(placement: string): boolean;
+    getAutoPreloadedPlacement(): string | null;
+    waitForAutoPreloadedPlacement(): Promise<string | null>;
 }
 
 declare const PaywalloClient: IPaywalloClient;
@@ -913,7 +931,7 @@ declare class OfflineQueueClass {
     private loadFromStorage;
     private saveToStorage;
     private cleanupExpired;
-    enqueue(method: "POST" | "PUT", url: string, body: unknown, headers?: Record<string, string>): Promise<QueueItem>;
+    enqueue(method: "POST" | "PUT", url: string, body: unknown, headers?: Record<string, string>, id?: string): Promise<QueueItem>;
     private findDuplicateIndex;
     dequeue(): Promise<QueueItem | null>;
     removeItem(id: string): Promise<boolean>;
@@ -926,7 +944,6 @@ declare class OfflineQueueClass {
         processed: number;
         failed: number;
     }>;
-    /** Returns true if the item was permanently removed (counted as failed). */
     private handleItemFailure;
     private sleep;
     getQueue(): ReadonlyArray<QueueItem>;
@@ -1003,6 +1020,7 @@ interface FormattedProduct extends ProductPriceInfo {
     subscriptionPeriod?: string;
     introductoryPrice?: string;
     freeTrialPeriod?: string;
+    trialDays: number;
 }
 
 interface UseProductsResult {
@@ -1017,13 +1035,19 @@ interface UseProductsResult {
 }
 declare function useProducts(initialProductIds?: string[]): UseProductsResult;
 
+interface PurchaseOutcome {
+    status: "success" | "cancelled" | "failed";
+    purchase?: IAPPurchase;
+    error?: PurchaseError;
+}
 interface UsePurchaseResult {
     state: PurchaseState;
-    purchase: (productId: string) => Promise<IAPPurchase>;
+    purchase: (productId: string) => Promise<PurchaseOutcome>;
     restore: () => Promise<IAPPurchase[]>;
     error: PurchaseError | null;
     isLoading: boolean;
     isPurchasing: boolean;
+    isValidating: boolean;
     isRestoring: boolean;
 }
 declare function usePurchase(): UsePurchaseResult;
@@ -1082,10 +1106,13 @@ declare class SubscriptionCache {
     private ttl;
     private memoryCache;
     private storage;
+    private legacyCleanupDone;
     constructor(ttl?: number);
-    get(): Promise<CachedSubscription | null>;
-    set(data: SubscriptionStatusResponse): Promise<void>;
-    invalidate(): Promise<void>;
+    private cleanupLegacyCache;
+    get(distinctId: string): Promise<CachedSubscription | null>;
+    set(distinctId: string, data: SubscriptionStatusResponse): Promise<void>;
+    invalidate(distinctId: string): Promise<void>;
+    invalidateAll(): Promise<void>;
     private isExpired;
     setTTL(ttl: number): void;
 }
@@ -1097,6 +1124,7 @@ declare class SubscriptionManagerClass {
     private listeners;
     private userId;
     constructor();
+    private cacheKey;
     init(config: SubscriptionManagerConfig): void;
     setUserId(userId: string | null): void;
     hasActiveSubscription(forceRefresh?: boolean): Promise<boolean>;
@@ -1149,4 +1177,4 @@ declare function hasVariables(text: string): boolean;
 
 declare const Paywallo: IPaywalloClient;
 
-export { AFFILIATE_ERROR_CODES, ANALYTICS_ERROR_CODES, type AffiliateBalance, type AffiliateCommission, type AffiliateCoupon, AffiliateError, AffiliateManager, AnalyticsError, ApiClient, type ApiClientConfig, type BlockType, type BoxSpacing, CAMPAIGN_ERROR_CODES, type CachedSubscription, CampaignError, type CampaignPresentOptions, type CampaignResponse, type CampaignResult, type ConditionalFlagContext, type ConditionalFlagResult, PURCHASE_ERROR_CODES as ERROR_CODES, type Environment, type FlagVariant, HttpClient, type HttpClientConfig, type HttpResponse, type IAPProduct, type IAPPurchase, IAPService, IDENTITY_ERROR_CODES, type IPaywalloClient, type IdentifyOptions, IdentityError, IdentityManager, type IdentityState, type LocalizedText, type NetworkListener, type NetworkMonitorConfig, type NetworkState, type OfflineQueueConfig, PAYWALL_ERROR_CODES, PURCHASE_ERROR_CODES, type PaywallBlockConfig, type PaywallConfig, PaywallContext, PaywallError, PaywallModal, type PaywallNode, type PaywallPresentOptions, type PaywallResult, type PaywallState, Paywallo, PaywalloAffiliate, PaywalloClient, type PaywalloConfig, PaywalloContext, PaywalloError, type PaywalloInitConfig, PaywalloProvider, type PreloadCampaignResult, type PreloadResult, type Product, type ProductPriceInfo, type Purchase, type PurchaseControllerConfig, PurchaseError, type PurchaseResult, type PurchaseState, type QueueEvent, type QueueItem, type QueueListener, type QueueProcessorConfig, type RequestOptions, type RestoreResult, type RetryConfig, SESSION_ERROR_CODES, type SessionConfig, SessionError, SessionManager, type SessionState, type Subscription, SubscriptionCache, type SubscriptionInfo, type SubscriptionManagerConfig, type SubscriptionPlatform, type SubscriptionStatus$1 as SubscriptionStatus, type SubscriptionStatusResponse$1 as SubscriptionStatusResponse, type TapBehavior, type TrackEventOptions, type UserProperties, type ValidatePurchaseResponse, type VariableContext, type WithdrawalRequest, affiliateManager, createPurchaseError, Paywallo as default, detectDeviceLanguage, getCurrentLanguage, getDefaultLanguage, getIAPService, getLocalizedString, hasVariables, identityManager, initLocalization, nativeStoreKit, networkMonitor, offlineQueue, parseVariables, queueProcessor, resolveText, sessionManager, setCurrentLanguage, setDefaultLanguage, subscriptionManager, usePaywallContext, usePaywallo, useProducts, usePurchase, useSubscription };
+export { AFFILIATE_ERROR_CODES, ANALYTICS_ERROR_CODES, type AffiliateBalance, type AffiliateCommission, type AffiliateCoupon, AffiliateError, AffiliateManager, AnalyticsError, ApiClient, type ApiClientConfig, type BlockType, type BoxSpacing, CAMPAIGN_ERROR_CODES, type CachedSubscription, CampaignError, type CampaignPresentOptions, type CampaignResponse, type CampaignResult, type ConditionalFlagContext, type ConditionalFlagResult, PURCHASE_ERROR_CODES as ERROR_CODES, type Environment, type FlagVariant, HttpClient, type HttpClientConfig, type HttpResponse, type IAPProduct, type IAPPurchase, IAPService, IDENTITY_ERROR_CODES, type IPaywalloClient, type IdentifyOptions, IdentityError, IdentityManager, type IdentityState, type LocalizedText, type NetworkListener, type NetworkMonitorConfig, type NetworkState, type OfflineQueueConfig, PAYWALL_ERROR_CODES, PURCHASE_ERROR_CODES, type PaywallBlockConfig, type PaywallConfig, PaywallContext, PaywallError, type PaywallErrorStrings$1 as PaywallErrorStrings, PaywallModal, type PaywallNode, type PaywallPresentOptions, type PaywallResult, type PaywallState, Paywallo, PaywalloAffiliate, PaywalloClient, type PaywalloConfig, PaywalloContext, PaywalloError, type PaywalloInitConfig, PaywalloProvider, type PaywalloProviderProps, type PreloadCampaignResult, type PreloadResult, type Product, type ProductPriceInfo, type Purchase, type PurchaseControllerConfig, PurchaseError, type PurchaseResult, type PurchaseState, type QueueEvent, type QueueItem, type QueueListener, type QueueProcessorConfig, type RequestOptions, type RestoreResult, type RetryConfig, SESSION_ERROR_CODES, type SessionConfig, SessionError, SessionManager, type SessionState, type Subscription, SubscriptionCache, type SubscriptionInfo, type SubscriptionManagerConfig, type SubscriptionPlatform, type SubscriptionStatus$1 as SubscriptionStatus, type SubscriptionStatusResponse$1 as SubscriptionStatusResponse, type TapBehavior, type TrackEventOptions, type UserProperties, type ValidatePurchaseResponse, type VariableContext, type WithdrawalRequest, affiliateManager, createPurchaseError, Paywallo as default, detectDeviceLanguage, getCurrentLanguage, getDefaultLanguage, getIAPService, getLocalizedString, hasVariables, identityManager, initLocalization, nativeStoreKit, networkMonitor, offlineQueue, parseVariables, queueProcessor, resolveText, sessionManager, setCurrentLanguage, setDefaultLanguage, subscriptionManager, usePaywallContext, usePaywallo, useProducts, usePurchase, useSubscription };

package/dist/index.d.ts

@@ -116,6 +116,7 @@ interface ServerProductInfo {
 }
 interface CampaignResponse {
     campaignId: string;
+    placement?: string;
     variantKey: string;
     paywall: {
         id: string;
@@ -183,6 +184,31 @@ interface EmergencyPaywallResponse {
     paywall?: PaywallConfig;
 }
 
+declare class PaywalloError extends Error {
+    readonly code: string;
+    readonly domain: string;
+    constructor(domain: string, code: string, message: string);
+}
+
+declare class PurchaseError extends PaywalloError {
+    readonly userCancelled: boolean;
+    constructor(code: string, message: string, userCancelled?: boolean);
+}
+declare const PURCHASE_ERROR_CODES: {
+    readonly NOT_INITIALIZED: "PURCHASE_NOT_INITIALIZED";
+    readonly PRODUCT_NOT_FOUND: "PRODUCT_NOT_FOUND";
+    readonly PURCHASE_FAILED: "PURCHASE_FAILED";
+    readonly RESTORE_FAILED: "RESTORE_FAILED";
+    readonly VALIDATION_FAILED: "VALIDATION_FAILED";
+    readonly USER_CANCELLED: "USER_CANCELLED";
+    readonly NETWORK_ERROR: "PURCHASE_NETWORK_ERROR";
+    readonly STORE_ERROR: "PURCHASE_STORE_ERROR";
+    readonly PENDING_PURCHASE: "PURCHASE_PENDING";
+    readonly DEFERRED_PURCHASE: "PURCHASE_DEFERRED";
+    readonly STORE_NOT_AVAILABLE: "PURCHASE_STORE_NOT_AVAILABLE";
+};
+declare function createPurchaseError(code: keyof typeof PURCHASE_ERROR_CODES, message?: string): PurchaseError;
+
 interface Product {
     productId: string;
     title: string;
@@ -196,6 +222,7 @@ interface Product {
     introductoryPrice?: string;
     introductoryPriceValue?: number;
     freeTrialPeriod?: string;
+    trialDays?: number;
     pricePerMonth?: string;
     pricePerWeek?: string;
     pricePerDay?: string;
@@ -212,7 +239,7 @@ interface Purchase {
 interface PurchaseResult {
     success: boolean;
     purchase?: Purchase;
-    error?: Error;
+    error?: PurchaseError;
 }
 interface ValidatePurchaseResponse {
     success: boolean;
@@ -252,10 +279,16 @@ interface ApiClientConfig {
     offlineQueueEnabled?: boolean;
     timeout?: number;
 }
+interface PaywallErrorStrings$1 {
+    title?: string;
+    retry?: string;
+    close?: string;
+}
 interface PaywalloConfig {
     appKey: string;
     debug?: boolean;
     environment?: Environment;
+    errorStrings?: PaywallErrorStrings$1;
 }
 interface UserProperties {
     [key: string]: string | number | boolean | null;
@@ -367,6 +400,7 @@ interface PreloadResult {
 interface PaywalloContextValue {
     config: PaywalloConfig | null;
     isInitialized: boolean;
+    isReady: boolean;
     initError: Error | null;
     distinctId: string | null;
     subscription: Subscription | null;
@@ -386,12 +420,6 @@ interface PaywalloContextValue {
 }
 declare const PaywalloContext: React.Context<PaywalloContextValue | null>;
 
-declare class PaywalloError extends Error {
-    readonly code: string;
-    readonly domain: string;
-    constructor(domain: string, code: string, message: string);
-}
-
 declare class PaywallError extends PaywalloError {
     constructor(code: string, message: string);
 }
@@ -459,8 +487,8 @@ declare class ApiClient {
     private httpClient;
     private readonly cache;
     constructor(appKey: string, debug?: boolean, environment?: Environment, offlineQueueEnabled?: boolean, timeout?: number);
-    /** Exposed only for QueueProcessor initialization. Prefer get()/post() for requests. */
     getHttpClient(): HttpClient;
+    getBaseUrl(): string;
     getWebUrl(): string;
     getEnvironment(): Environment;
     getQueueSize(): number;
@@ -473,7 +501,7 @@ declare class ApiClient {
     post<T>(path: string, body: unknown, skipRetry?: boolean): Promise<HttpResponse<T>>;
     reportError(errorType: string, message: string, context?: Record<string, unknown>): Promise<void>;
     trackEvent(eventName: string, distinctId: string, properties?: UserProperties, timestamp?: number): Promise<void>;
-    identify(distinctId: string, properties?: UserProperties, email?: string): Promise<void>;
+    identify(distinctId: string, properties?: UserProperties, email?: string, deviceId?: string): Promise<void>;
     startSession(distinctId: string, sessionId: string, platform?: string): Promise<{
         success: boolean;
     }>;
@@ -484,23 +512,15 @@ declare class ApiClient {
     getPaywall(placement: string): Promise<PaywallConfig | null>;
     getEmergencyPaywall(): Promise<EmergencyPaywallResponse>;
     getCampaign(placement: string, distinctId: string, context?: Record<string, unknown>): Promise<CampaignResponse | null>;
+    getPrimaryCampaign(distinctId: string): Promise<CampaignResponse | null>;
     validatePurchase(platform: "ios" | "android", receipt: string, productId: string, transactionId: string, priceLocal: number, currency: string, country: string, distinctId?: string, paywallPlacement?: string, variantKey?: string): Promise<ValidatePurchaseResponse>;
     getSubscriptionStatus(distinctId: string): Promise<SubscriptionStatusResponse$1>;
     evaluateFlags(keys: string[], distinctId: string): Promise<Record<string, string | null>>;
     getConditionalFlag(flagKey: string, context: ConditionalFlagContext): Promise<ConditionalFlagResult>;
-    /**
-     * Reads a flag variant from cache layers only — no network call.
-     * Checks in-memory cache first, then SecureStorage.
-     * Returns null when both layers miss.
-     */
     getVariantFromCache(flagKey: string, distinctId: string): Promise<FlagVariant | null>;
     private static readonly FLAG_MAX_AGE_MS;
     private readFlagFromStorage;
     private writeFlagToStorage;
-    /**
-     * POST with offline queue fallback. Enqueues when offline or on network failure.
-     * Throws only when offlineQueueEnabled is false and the request fails.
-     */
     private postWithQueue;
     private log;
 }
@@ -594,11 +614,13 @@ declare class IAPService {
     loadProducts(productIds: string[]): Promise<Product[]>;
     getProduct(productId: string): Product | undefined;
     getCachedProducts(): Map<string, Product>;
+    private validateWithRetry;
     private validateWithServer;
     private finishTransaction;
     purchase(productId: string, options?: {
         paywallPlacement?: string;
         variantKey?: string;
+        onValidating?: () => void;
     }): Promise<PurchaseResult>;
     restore(): Promise<Purchase[]>;
 }
@@ -613,7 +635,7 @@ declare const nativeStoreKit: {
     getActiveTransactions(): Promise<Purchase[]>;
 };
 
-type PurchaseState = "idle" | "loading" | "purchasing" | "restoring" | "error";
+type PurchaseState = "idle" | "loading" | "purchasing" | "validating" | "restoring" | "error";
 interface IAPProduct {
     productId: string;
     price: string;
@@ -630,6 +652,7 @@ interface IAPProduct {
     introductoryPriceNumberOfPeriodsIOS?: string;
     introductoryPriceSubscriptionPeriodIOS?: string;
     freeTrialPeriodAndroid?: string;
+    trialDays: number;
 }
 interface IAPPurchase {
     productId: string;
@@ -653,25 +676,6 @@ interface ProductPriceInfo {
     pricePerDay?: string;
 }
 
-declare class PurchaseError extends PaywalloError {
-    readonly userCancelled: boolean;
-    constructor(code: string, message: string, userCancelled?: boolean);
-}
-declare const PURCHASE_ERROR_CODES: {
-    readonly NOT_INITIALIZED: "PURCHASE_NOT_INITIALIZED";
-    readonly PRODUCT_NOT_FOUND: "PRODUCT_NOT_FOUND";
-    readonly PURCHASE_FAILED: "PURCHASE_FAILED";
-    readonly RESTORE_FAILED: "RESTORE_FAILED";
-    readonly VALIDATION_FAILED: "VALIDATION_FAILED";
-    readonly USER_CANCELLED: "USER_CANCELLED";
-    readonly NETWORK_ERROR: "PURCHASE_NETWORK_ERROR";
-    readonly STORE_ERROR: "PURCHASE_STORE_ERROR";
-    readonly PENDING_PURCHASE: "PURCHASE_PENDING";
-    readonly DEFERRED_PURCHASE: "PURCHASE_DEFERRED";
-    readonly STORE_NOT_AVAILABLE: "PURCHASE_STORE_NOT_AVAILABLE";
-};
-declare function createPurchaseError(code: keyof typeof PURCHASE_ERROR_CODES, message?: string): PurchaseError;
-
 interface IdentityState {
     deviceId: string;
     email: string | null;
@@ -679,6 +683,7 @@ interface IdentityState {
 }
 declare class IdentityManager {
     private deviceId;
+    private anonId;
     private email;
     private properties;
     private apiClient;
@@ -697,7 +702,6 @@ declare class IdentityManager {
     isSecureStorageAvailable(): boolean;
     private loadPersistedState;
     private ensureInitialized;
-    private log;
 }
 declare const identityManager: IdentityManager;
 
@@ -812,16 +816,26 @@ interface PreloadCampaignResult {
     success: boolean;
     error?: Error;
 }
+interface PaywallErrorStrings {
+    title?: string;
+    retry?: string;
+    close?: string;
+}
 interface PaywalloInitConfig extends PaywalloConfig {
     sessionConfig?: SessionConfig;
     autoStartSession?: boolean;
     offlineQueueEnabled?: boolean;
     timeout?: number;
-    /** Request ATT permission during init (iOS only). Default: false. */
     requestATT?: boolean;
+    errorStrings?: PaywallErrorStrings;
+    sessionFlags?: string[];
+    subscriptionCacheTTL?: number;
+    autoPreloadCampaign?: string;
 }
 interface IPaywalloClient {
     init(config: PaywalloInitConfig): Promise<void>;
+    isReady(): boolean;
+    waitUntilReady(): Promise<void>;
     identify(options?: IdentifyOptions | UserProperties): Promise<void>;
     track(eventName: string, options?: TrackEventOptions): Promise<void>;
     getVariantCached(flagKey: string, defaultValue?: string): Promise<FlagVariant>;
@@ -862,6 +876,7 @@ interface IPaywalloClient {
     registerActiveChecker(checker: () => Promise<boolean>): void;
     registerRestoreHandler(handler: () => Promise<RestoreResult>): void;
     registerEmergencyPaywallHandler(handler: EmergencyPaywallHandler): void;
+    getSessionFlag(key: string): string | null;
     isOnline(): boolean;
     getOfflineQueueSize(): number;
     clearOfflineQueue(): Promise<void>;
@@ -871,6 +886,9 @@ interface IPaywalloClient {
     }>;
     onboardingStep(index: number, name: string): Promise<void>;
     coreAction(actionName: string): Promise<void>;
+    isPreloaded(placement: string): boolean;
+    getAutoPreloadedPlacement(): string | null;
+    waitForAutoPreloadedPlacement(): Promise<string | null>;
 }
 
 declare const PaywalloClient: IPaywalloClient;
@@ -913,7 +931,7 @@ declare class OfflineQueueClass {
     private loadFromStorage;
     private saveToStorage;
     private cleanupExpired;
-    enqueue(method: "POST" | "PUT", url: string, body: unknown, headers?: Record<string, string>): Promise<QueueItem>;
+    enqueue(method: "POST" | "PUT", url: string, body: unknown, headers?: Record<string, string>, id?: string): Promise<QueueItem>;
     private findDuplicateIndex;
     dequeue(): Promise<QueueItem | null>;
     removeItem(id: string): Promise<boolean>;
@@ -926,7 +944,6 @@ declare class OfflineQueueClass {
         processed: number;
         failed: number;
     }>;
-    /** Returns true if the item was permanently removed (counted as failed). */
     private handleItemFailure;
     private sleep;
     getQueue(): ReadonlyArray<QueueItem>;
@@ -1003,6 +1020,7 @@ interface FormattedProduct extends ProductPriceInfo {
     subscriptionPeriod?: string;
     introductoryPrice?: string;
     freeTrialPeriod?: string;
+    trialDays: number;
 }
 
 interface UseProductsResult {
@@ -1017,13 +1035,19 @@ interface UseProductsResult {
 }
 declare function useProducts(initialProductIds?: string[]): UseProductsResult;
 
+interface PurchaseOutcome {
+    status: "success" | "cancelled" | "failed";
+    purchase?: IAPPurchase;
+    error?: PurchaseError;
+}
 interface UsePurchaseResult {
     state: PurchaseState;
-    purchase: (productId: string) => Promise<IAPPurchase>;
+    purchase: (productId: string) => Promise<PurchaseOutcome>;
     restore: () => Promise<IAPPurchase[]>;
     error: PurchaseError | null;
     isLoading: boolean;
     isPurchasing: boolean;
+    isValidating: boolean;
     isRestoring: boolean;
 }
 declare function usePurchase(): UsePurchaseResult;
@@ -1082,10 +1106,13 @@ declare class SubscriptionCache {
     private ttl;
     private memoryCache;
     private storage;
+    private legacyCleanupDone;
     constructor(ttl?: number);
-    get(): Promise<CachedSubscription | null>;
-    set(data: SubscriptionStatusResponse): Promise<void>;
-    invalidate(): Promise<void>;
+    private cleanupLegacyCache;
+    get(distinctId: string): Promise<CachedSubscription | null>;
+    set(distinctId: string, data: SubscriptionStatusResponse): Promise<void>;
+    invalidate(distinctId: string): Promise<void>;
+    invalidateAll(): Promise<void>;
     private isExpired;
     setTTL(ttl: number): void;
 }
@@ -1097,6 +1124,7 @@ declare class SubscriptionManagerClass {
     private listeners;
     private userId;
     constructor();
+    private cacheKey;
     init(config: SubscriptionManagerConfig): void;
     setUserId(userId: string | null): void;
     hasActiveSubscription(forceRefresh?: boolean): Promise<boolean>;
@@ -1149,4 +1177,4 @@ declare function hasVariables(text: string): boolean;
 
 declare const Paywallo: IPaywalloClient;
 
-export { AFFILIATE_ERROR_CODES, ANALYTICS_ERROR_CODES, type AffiliateBalance, type AffiliateCommission, type AffiliateCoupon, AffiliateError, AffiliateManager, AnalyticsError, ApiClient, type ApiClientConfig, type BlockType, type BoxSpacing, CAMPAIGN_ERROR_CODES, type CachedSubscription, CampaignError, type CampaignPresentOptions, type CampaignResponse, type CampaignResult, type ConditionalFlagContext, type ConditionalFlagResult, PURCHASE_ERROR_CODES as ERROR_CODES, type Environment, type FlagVariant, HttpClient, type HttpClientConfig, type HttpResponse, type IAPProduct, type IAPPurchase, IAPService, IDENTITY_ERROR_CODES, type IPaywalloClient, type IdentifyOptions, IdentityError, IdentityManager, type IdentityState, type LocalizedText, type NetworkListener, type NetworkMonitorConfig, type NetworkState, type OfflineQueueConfig, PAYWALL_ERROR_CODES, PURCHASE_ERROR_CODES, type PaywallBlockConfig, type PaywallConfig, PaywallContext, PaywallError, PaywallModal, type PaywallNode, type PaywallPresentOptions, type PaywallResult, type PaywallState, Paywallo, PaywalloAffiliate, PaywalloClient, type PaywalloConfig, PaywalloContext, PaywalloError, type PaywalloInitConfig, PaywalloProvider, type PreloadCampaignResult, type PreloadResult, type Product, type ProductPriceInfo, type Purchase, type PurchaseControllerConfig, PurchaseError, type PurchaseResult, type PurchaseState, type QueueEvent, type QueueItem, type QueueListener, type QueueProcessorConfig, type RequestOptions, type RestoreResult, type RetryConfig, SESSION_ERROR_CODES, type SessionConfig, SessionError, SessionManager, type SessionState, type Subscription, SubscriptionCache, type SubscriptionInfo, type SubscriptionManagerConfig, type SubscriptionPlatform, type SubscriptionStatus$1 as SubscriptionStatus, type SubscriptionStatusResponse$1 as SubscriptionStatusResponse, type TapBehavior, type TrackEventOptions, type UserProperties, type ValidatePurchaseResponse, type VariableContext, type WithdrawalRequest, affiliateManager, createPurchaseError, Paywallo as default, detectDeviceLanguage, getCurrentLanguage, getDefaultLanguage, getIAPService, getLocalizedString, hasVariables, identityManager, initLocalization, nativeStoreKit, networkMonitor, offlineQueue, parseVariables, queueProcessor, resolveText, sessionManager, setCurrentLanguage, setDefaultLanguage, subscriptionManager, usePaywallContext, usePaywallo, useProducts, usePurchase, useSubscription };
+export { AFFILIATE_ERROR_CODES, ANALYTICS_ERROR_CODES, type AffiliateBalance, type AffiliateCommission, type AffiliateCoupon, AffiliateError, AffiliateManager, AnalyticsError, ApiClient, type ApiClientConfig, type BlockType, type BoxSpacing, CAMPAIGN_ERROR_CODES, type CachedSubscription, CampaignError, type CampaignPresentOptions, type CampaignResponse, type CampaignResult, type ConditionalFlagContext, type ConditionalFlagResult, PURCHASE_ERROR_CODES as ERROR_CODES, type Environment, type FlagVariant, HttpClient, type HttpClientConfig, type HttpResponse, type IAPProduct, type IAPPurchase, IAPService, IDENTITY_ERROR_CODES, type IPaywalloClient, type IdentifyOptions, IdentityError, IdentityManager, type IdentityState, type LocalizedText, type NetworkListener, type NetworkMonitorConfig, type NetworkState, type OfflineQueueConfig, PAYWALL_ERROR_CODES, PURCHASE_ERROR_CODES, type PaywallBlockConfig, type PaywallConfig, PaywallContext, PaywallError, type PaywallErrorStrings$1 as PaywallErrorStrings, PaywallModal, type PaywallNode, type PaywallPresentOptions, type PaywallResult, type PaywallState, Paywallo, PaywalloAffiliate, PaywalloClient, type PaywalloConfig, PaywalloContext, PaywalloError, type PaywalloInitConfig, PaywalloProvider, type PaywalloProviderProps, type PreloadCampaignResult, type PreloadResult, type Product, type ProductPriceInfo, type Purchase, type PurchaseControllerConfig, PurchaseError, type PurchaseResult, type PurchaseState, type QueueEvent, type QueueItem, type QueueListener, type QueueProcessorConfig, type RequestOptions, type RestoreResult, type RetryConfig, SESSION_ERROR_CODES, type SessionConfig, SessionError, SessionManager, type SessionState, type Subscription, SubscriptionCache, type SubscriptionInfo, type SubscriptionManagerConfig, type SubscriptionPlatform, type SubscriptionStatus$1 as SubscriptionStatus, type SubscriptionStatusResponse$1 as SubscriptionStatusResponse, type TapBehavior, type TrackEventOptions, type UserProperties, type ValidatePurchaseResponse, type VariableContext, type WithdrawalRequest, affiliateManager, createPurchaseError, Paywallo as default, detectDeviceLanguage, getCurrentLanguage, getDefaultLanguage, getIAPService, getLocalizedString, hasVariables, identityManager, initLocalization, nativeStoreKit, networkMonitor, offlineQueue, parseVariables, queueProcessor, resolveText, sessionManager, setCurrentLanguage, setDefaultLanguage, subscriptionManager, usePaywallContext, usePaywallo, useProducts, usePurchase, useSubscription };