@mysuperwall/react-native 0.0.0-stage → 1.1.0

package/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+## 1.1.0
+
+- Add compiled JavaScript and TypeScript declarations to npm packages.
+- Keep native integrations as peer dependencies, without pinning host apps to one major.
+- Persist anonymous installation identity per application and server.
+- Send Android package identifiers as packageName for manifests and analytics.
+- Export initialization option types and include the MIT license.
+

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MySuperWall
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,158 @@
-# Temporary Holding Version
+# MySuperwall React Native SDK
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Official React Native SDK for [MySuperwall](https://mysuperwall.com). Remotely configure, evaluate, and display dynamic paywalls in your React Native apps using cached, on-device rule evaluation.
+
+## Features
+
+- **⚡ Local rule evaluation:** Evaluates audience rules and deterministic A/B variants locally in-memory on the device.
+- **💾 Offline Cache:** Automatically caches active paywall manifests with `@react-native-async-storage/async-storage` for instant cold starts without network wait.
+- **🔄 ETag / 304 Synchronization:** Background sync fetches updates with zero bandwidth waste when rules haven't changed.
+- **🎨 HTML/CSS Dynamic Paywalls:** High-performance `react-native-webview` rendering with two-way JS bridge.
+- **📊 Offline Event Queue:** Fire-and-forget analytics event batching to `POST /paywall/events/batch`.
+
+## Compatibility
+
+The package includes compiled JavaScript and TypeScript declarations. Native WebView
+and AsyncStorage remain peer dependencies so your app controls their versions.
+
+Verified dependency combinations (installation and TypeScript checks):
+
+| React | React Native | WebView | AsyncStorage |
+| --- | --- | --- | --- |
+| 18.2.0 | 0.73.4 | 13.8.1 | 1.21.0 |
+| 19.2.3 | 0.87.1 | 14.0.1 | 3.1.1 |
+
+For modern React Native use your app's `moduleResolution: "bundler"` TypeScript configuration.
+These checks do not replace an iOS/Android device integration test. Versions below
+these combinations are not covered by this audit, even if the peer range permits them.
+Cached manifests are available after initialization; the first installation still
+needs a successful background manifest download before a trigger can resolve.
+For Android pass `platform: 'android'`; `bundleId` is sent as the Android package name.
+
+## Installation
+
+```sh
+npm install @mysuperwall/react-native react-native-webview @react-native-async-storage/async-storage
+```
+
+Choose WebView and AsyncStorage versions compatible with your existing React Native
+or Expo project. For Expo-managed dependencies use `npx expo install`.
+Bare iOS projects also require `pod install` from the `ios` directory.
+Expo requires a native development build.
+
+Existing checksum-pinned source snapshots remain an alternative installation method.
+Do not install both the snapshot and npm package in the same app.
+
+## Quick Start
+
+### 1. Initialize on App Launch
+
+In your root `App.tsx` or `index.js`:
+
+```tsx
+import React, { useEffect } from 'react';
+import { Platform } from 'react-native';
+import { MySuperwall, PaywallModal, usePaywall } from '@mysuperwall/react-native';
+
+export default function App() {
+  const { activePaywall, isVisible, dismiss, callbacks } = usePaywall();
+
+  useEffect(() => {
+    MySuperwall.initialize({
+      appKey: 'YOUR_APP_KEY',
+      platform: Platform.OS === 'android' ? 'android' : 'ios'
+    });
+  }, []);
+
+  return (
+    <>
+      <MainAppScreen />
+      <PaywallModal
+        visible={isVisible}
+        paywall={activePaywall}
+        onClose={dismiss}
+        {...callbacks}
+      />
+    </>
+  );
+}
+```
+
+### 2. Trigger a Paywall
+
+Fires immediately with **no network request for cached rules**:
+
+```tsx
+MySuperwall.shared.handleTrigger('onboarding_finish', {
+  onPurchase: async (productId) => {
+    console.log('User wants to purchase:', productId);
+    // Call your IAP flow (RevenueCat, react-native-iap)
+  },
+  onRestore: () => {
+    console.log('User requested restore');
+  },
+  onDismiss: () => {
+    console.log('Paywall closed');
+  }
+});
+```
+
+### 3. User Attributes & Identification
+
+```tsx
+// Identify authenticated users
+MySuperwall.shared.identify('user_12345');
+
+// Set custom attributes for audience targeting
+MySuperwall.shared.setUserAttributes({
+  tier: 'gold',
+  level: 15,
+  isSubscriber: false
+});
+```
+
+
+### Experiment attribution
+
+Manifest resolution retains optional server-issued experiment, audience, variant and
+published-paywall version identifiers. Older manifests remain usable without this
+context. Fetching or resolving alone does not record an impression. Built-in UI
+records `paywall_shown` after the page loads while displayed; custom presenters
+must call `trackPaywallEvent` when they actually show the paywall.
+
+Purchase and restore button requests record `purchase_started` and
+`restore_started`, not successful transactions. After your billing provider confirms
+a purchase, pass the **original displayed paywall** to the SDK:
+
+```
+await MySuperwall.shared.trackPaywallEvent('purchase_success', displayedPaywall, productId)
+```
+
+Do not resolve the trigger again to attribute a completed purchase. An identity
+change invalidates attribution from the previous user's paywall. Offline retries
+retain the original event ID and context; events are removed by acknowledged ID.
+Verified revenue remains a separate backend/provider concern.
+
+## Locale, targeting and recovery (1.1.0)
+
+Initialize with optional `locale`, `country` (ISO region, e.g. `TR`) and `appVersion`.
+The default language and region come from the device's Intl locale when available.
+React Native does not provide a universal built-in app-version API: pass your real
+version from your existing app-info integration, or call `setAppVersion(version)`.
+`await MySuperwall.shared.setLocale('tr')` switches to the language-specific cache
+and refreshes its manifest; `setCountry('US')` does not change the paywall language.
+Call `setSubscriptionStatus(true/false)` from your billing entitlement state for
+`skipIfPremium` recovery rules.
+
+`handleTrigger` automatically handles configured trigger-based follow-up rules and
+the legacy dismiss second screen. Explicit rules take priority. Session/cooldown,
+chain-depth and repeat checks bound the flow. A purchase tap does not run a success
+rule: the host must call `trackPaywallEvent('purchase_success', displayedPaywall)`
+after its billing provider confirms success. Use the captured presenter payload.
+Identity/configuration/language changes cancel delayed recovery. The stock modal
+calls the dismissal callback once for either a close action or Android Back.
+Programmatic dismissal through the hook clears the modal without starting recovery.
+
+Manifest and offline event storage are isolated by app/server scope. Unscoped legacy
+caches are ignored; source updates need one successful manifest sync before offline use.
+No store billing is replaced by this SDK.

package/lib/MySuperwall.d.ts

@@ -0,0 +1,64 @@
+import { LocalRuleEngine } from './engine/localRuleEngine';
+import { ManifestService } from './services/manifestService';
+import { OfflineEventQueue } from './services/offlineEventQueue';
+import { PaywallResult, PaywallData, PaywallCallbackActions } from './models/paywall';
+export interface MySuperwallInitOptions {
+    appKey?: string;
+    userId?: string;
+    baseUrl?: string;
+    bundleId?: string;
+    platform?: 'ios' | 'android' | 'web';
+    locale?: string;
+    country?: string;
+    appVersion?: string;
+}
+export declare class MySuperwall {
+    private static instance;
+    appKey?: string;
+    userId?: string;
+    baseUrl: string;
+    bundleId?: string;
+    platform: string;
+    locale: string;
+    country: string;
+    appVersion?: string;
+    private premium;
+    private epoch;
+    private presentationSequence;
+    private followUps;
+    private activeFlow?;
+    userAttributes: Record<string, any>;
+    manifestService: ManifestService;
+    ruleEngine: LocalRuleEngine;
+    eventQueue: OfflineEventQueue;
+    private onPresentPaywallListener?;
+    private constructor();
+    static get shared(): MySuperwall;
+    /**
+     * Initializes MySuperwall with cached local rule evaluation.
+     */
+    static initialize(options?: MySuperwallInitOptions): Promise<MySuperwall>;
+    identify(userId: string): void;
+    private resetFlow;
+    private manifestOptions;
+    setLocale(locale: string): Promise<void>;
+    setCountry(country: string): void;
+    setAppVersion(version: string): void;
+    setSubscriptionStatus(premium: boolean): void;
+    setUserAttributes(attributes: Record<string, any>): void;
+    registerPresenter(listener: (paywall: PaywallData, callbacks: PaywallCallbackActions) => void): () => void;
+    /**
+     * Evaluates rules locally in-memory in memory.
+     */
+    resolveTrigger(triggerKey: string, metadata?: Record<string, any>): PaywallResult;
+    /** Attribute actions to the displayed paywall, never a new assignment. */
+    trackPaywallEvent(type: string, paywall: PaywallData, productId?: string): Promise<void>;
+    /**
+     * Fires a trigger, presents the paywall if resolved, and wires up callbacks.
+     */
+    handleTrigger(triggerKey: string, callbacks?: PaywallCallbackActions & {
+        metadata?: Record<string, any>;
+    }): PaywallResult;
+    private present;
+    private scheduleFollowUp;
+}

package/lib/MySuperwall.js

@@ -0,0 +1,249 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MySuperwall = void 0;
+const anonymousIdentity_1 = require("./services/anonymousIdentity");
+const followUpService_1 = require("./services/followUpService");
+const localRuleEngine_1 = require("./engine/localRuleEngine");
+const manifestService_1 = require("./services/manifestService");
+const offlineEventQueue_1 = require("./services/offlineEventQueue");
+class MySuperwall {
+    constructor() {
+        this.baseUrl = 'https://mysuperwall.com/';
+        this.platform = 'ios';
+        this.locale = 'en';
+        this.country = '';
+        this.premium = false;
+        this.epoch = 0;
+        this.presentationSequence = 0;
+        this.followUps = new followUpService_1.FollowUpService();
+        this.userAttributes = {};
+        this.manifestService = new manifestService_1.ManifestService();
+        this.ruleEngine = new localRuleEngine_1.LocalRuleEngine();
+        this.eventQueue = new offlineEventQueue_1.OfflineEventQueue();
+    }
+    static get shared() {
+        if (!MySuperwall.instance) {
+            MySuperwall.instance = new MySuperwall();
+        }
+        return MySuperwall.instance;
+    }
+    /**
+     * Initializes MySuperwall with cached local rule evaluation.
+     */
+    static async initialize(options = {}) {
+        const inst = MySuperwall.shared;
+        inst.resetFlow();
+        inst.userAttributes = {};
+        inst.premium = false;
+        inst.appKey = options.appKey;
+        inst.baseUrl = options.baseUrl
+            ? options.baseUrl.endsWith('/')
+                ? options.baseUrl
+                : `${options.baseUrl}/`
+            : 'https://mysuperwall.com/';
+        inst.bundleId = options.bundleId;
+        inst.platform = options.platform || 'ios';
+        let deviceLocale = 'en';
+        try {
+            deviceLocale = Intl.DateTimeFormat().resolvedOptions().locale;
+        }
+        catch (_) { }
+        inst.locale = (options.locale || deviceLocale).replace(/_/g, '-').toLowerCase();
+        inst.country = (options.country || inst.locale.match(/-([a-z]{2})(?:-|$)/i)?.[1] || '').toUpperCase();
+        inst.appVersion = options.appVersion;
+        inst.manifestService.configure(inst.manifestOptions());
+        inst.eventQueue = new offlineEventQueue_1.OfflineEventQueue(JSON.stringify([inst.baseUrl, inst.appKey, inst.bundleId, inst.platform]));
+        const epoch = inst.epoch;
+        const userId = options.userId?.trim() || await anonymousIdentity_1.AnonymousIdentity.get(JSON.stringify([inst.baseUrl, inst.appKey, inst.bundleId, inst.platform]));
+        if (epoch !== inst.epoch)
+            return inst;
+        inst.userId = userId;
+        // 1. Load this app’s cached manifest into memory
+        await inst.manifestService.loadFromDisk();
+        if (epoch !== inst.epoch)
+            return inst;
+        // 2. Background non-blocking sync with ETag / 304 validation
+        void inst.manifestService.syncInBackground(inst.manifestOptions());
+        return inst;
+    }
+    identify(userId) {
+        if (!userId.trim())
+            throw new Error('User ID cannot be empty');
+        if (this.userId !== userId.trim()) {
+            this.resetFlow();
+            this.userAttributes = {};
+            this.premium = false;
+        }
+        this.userId = userId.trim();
+    }
+    resetFlow() { this.epoch++; this.followUps.reset(); this.activeFlow = undefined; }
+    manifestOptions() {
+        return { baseUrl: this.baseUrl, appKey: this.appKey, bundleId: this.bundleId, platform: this.platform, lang: this.locale };
+    }
+    async setLocale(locale) {
+        const normalized = locale.trim().replace(/_/g, '-').toLowerCase();
+        if (!normalized || normalized === this.locale)
+            return;
+        this.resetFlow();
+        this.locale = normalized;
+        const epoch = this.epoch;
+        this.manifestService.configure(this.manifestOptions());
+        await this.manifestService.loadFromDisk();
+        if (epoch === this.epoch)
+            await this.manifestService.syncInBackground(this.manifestOptions());
+    }
+    setCountry(country) { this.country = country.trim().toUpperCase(); }
+    setAppVersion(version) { this.appVersion = version; }
+    setSubscriptionStatus(premium) { this.premium = premium; }
+    setUserAttributes(attributes) {
+        Object.assign(this.userAttributes, attributes);
+    }
+    registerPresenter(listener) {
+        this.onPresentPaywallListener = listener;
+        return () => {
+            if (this.onPresentPaywallListener === listener) {
+                this.onPresentPaywallListener = undefined;
+            }
+        };
+    }
+    /**
+     * Evaluates rules locally in-memory in memory.
+     */
+    resolveTrigger(triggerKey, metadata) {
+        const manifest = this.manifestService.manifest;
+        if (!manifest) {
+            return { show: false, paywall: null, reason: 'manifest_not_cached' };
+        }
+        const trigger = (manifest.triggers || []).find(t => t.key.trim().toLowerCase() === triggerKey.trim().toLowerCase());
+        if (!trigger) {
+            return { show: false, paywall: null, reason: 'trigger_not_found' };
+        }
+        const evalContext = {
+            platform: this.platform,
+            country: this.country,
+            appVersion: this.appVersion,
+            metadata: metadata || {},
+            userAttributes: this.userAttributes,
+            ...(metadata || {})
+        };
+        const resolution = this.ruleEngine.resolveTrigger(trigger, this.userId, evalContext);
+        if (resolution.isHoldout) {
+            return { show: false, paywall: null, reason: 'holdout' };
+        }
+        if (resolution.show && resolution.paywallId) {
+            const manifestPaywall = manifest.paywalls[resolution.paywallId];
+            if (manifestPaywall) {
+                const paywallData = {
+                    followUpRules: manifestPaywall.contentJson?.followUpRules,
+                    dismissFollowUpPaywallId: trigger.dismissAction?.type === 'follow_up_paywall' ? trigger.dismissAction.followUpPaywallId || undefined : undefined,
+                    id: manifestPaywall.id,
+                    name: manifestPaywall.name,
+                    html: manifestPaywall.html,
+                    productIds: manifestPaywall.productIds,
+                    products: manifestPaywall.products,
+                    triggerKey,
+                    abVariant: resolution.abVariant || 'A',
+                    attributionUserId: this.userId,
+                    attributionScope: manifestService_1.ManifestService.scopeKey(this.manifestOptions()),
+                    experimentContext: (() => {
+                        const rule = trigger.rules.find(rule => rule.id === resolution.matchedRuleId);
+                        const audience = rule || trigger;
+                        const matches = audience.variants.filter(variant => variant.paywallId === manifestPaywall.id && variant.variant === resolution.abVariant);
+                        const variant = matches.length === 1 ? matches[0] : undefined;
+                        if (!variant?.variantId || !audience.experimentId || !audience.experimentVersion ||
+                            !audience.audienceId || manifestPaywall.publishedVersion == null)
+                            return undefined;
+                        return { experimentId: audience.experimentId, experimentVersion: audience.experimentVersion,
+                            audienceId: audience.audienceId, variantId: variant.variantId,
+                            variantLabel: variant.variantLabel || variant.variant,
+                            paywallId: manifestPaywall.id, paywallVersion: manifestPaywall.publishedVersion };
+                    })()
+                };
+                return { show: true, paywall: paywallData, reason: resolution.reason };
+            }
+        }
+        return { show: false, paywall: null, reason: resolution.reason };
+    }
+    /** Attribute actions to the displayed paywall, never a new assignment. */
+    async trackPaywallEvent(type, paywall, productId) {
+        if (paywall.attributionScope !== undefined && paywall.attributionScope !== manifestService_1.ManifestService.scopeKey(this.manifestOptions()))
+            return;
+        if (paywall.attributionUserId !== undefined && paywall.attributionUserId !== this.userId)
+            return;
+        const flow = this.activeFlow;
+        if (flow && flow.paywall.presentationId === paywall.presentationId && flow.epoch === this.epoch) {
+            const keys = { purchase: 'onPurchase', purchase_success: 'onPurchase', purchase_failed: 'onPurchaseFailed', restore: 'onRestore', restore_success: 'onRestore' };
+            if (keys[type]) {
+                flow.outcome = true;
+                this.scheduleFollowUp(flow, keys[type]);
+            }
+        }
+        await this.eventQueue.enqueue({ type, paywallId: paywall.id,
+            triggerKey: paywall.triggerKey, abVariant: paywall.abVariant,
+            experimentContext: paywall.attributionUserId === this.userId ? paywall.experimentContext : undefined, userId: this.userId, productId });
+        await this.eventQueue.flush({ baseUrl: this.baseUrl, appKey: this.appKey,
+            bundleId: this.bundleId, platform: this.platform });
+    }
+    /**
+     * Fires a trigger, presents the paywall if resolved, and wires up callbacks.
+     */
+    handleTrigger(triggerKey, callbacks) {
+        this.epoch++;
+        this.followUps.cancel();
+        this.activeFlow = undefined;
+        const result = this.resolveTrigger(triggerKey, callbacks?.metadata);
+        if (result.show && result.paywall) {
+            const paywall = this.present(result.paywall, callbacks || {}, callbacks?.metadata, 0, []);
+            return { ...result, paywall };
+        }
+        return result;
+    }
+    present(paywall, callbacks, metadata, depth, seen) {
+        paywall = { ...paywall, presentationId: `${this.epoch}:${++this.presentationSequence}` };
+        const flow = { paywall, callbacks, metadata, depth, seen: [...seen, paywall.id], epoch: this.epoch };
+        this.activeFlow = flow;
+        let dismissed = false;
+        this.onPresentPaywallListener?.(paywall, { ...callbacks, onDismiss: () => {
+                if (dismissed)
+                    return;
+                dismissed = true;
+                if (this.activeFlow !== flow || flow.epoch !== this.epoch)
+                    return;
+                if (!flow.outcome)
+                    this.scheduleFollowUp(flow, 'onDismiss');
+                void callbacks.onDismiss?.();
+            } });
+        return paywall;
+    }
+    scheduleFollowUp(flow, event) {
+        const rule = flow.paywall.followUpRules?.[event];
+        const valid = () => this.activeFlow === flow && flow.epoch === this.epoch && flow.paywall.attributionUserId === this.userId;
+        if (!valid())
+            return;
+        if (rule?.enabled && (rule.actionType || 'trigger') === 'trigger' && rule.triggerKey?.trim()) {
+            this.followUps.schedule(`${flow.paywall.id}:${event}:${rule.triggerKey}`, rule, flow.depth, this.premium, () => {
+                if (!valid())
+                    return;
+                const result = this.resolveTrigger(rule.triggerKey, flow.metadata);
+                if (!result.show || !result.paywall || (rule.skipIfPremium && this.premium) ||
+                    (rule.preventRepeatPaywall !== false && flow.seen.includes(result.paywall.id)))
+                    return;
+                this.present(result.paywall, flow.callbacks, flow.metadata, flow.depth + 1, flow.seen);
+            });
+            return;
+        }
+        // Legacy close recovery is one additional screen, never an unbounded chain.
+        const id = flow.paywall.dismissFollowUpPaywallId;
+        if (event !== 'onDismiss' || flow.depth !== 0 || !id || flow.seen.includes(id))
+            return;
+        const next = this.manifestService.manifest?.paywalls[id];
+        if (!next)
+            return;
+        this.followUps.schedule(`${flow.paywall.id}:legacy`, { enabled: true, actionType: 'trigger', triggerKey: 'legacy', maxChainDepth: 1 }, 0, false, () => {
+            if (valid())
+                this.present({ ...next, attributionUserId: this.userId, attributionScope: manifestService_1.ManifestService.scopeKey(this.manifestOptions()), triggerKey: flow.paywall.triggerKey,
+                    followUpRules: next.contentJson?.followUpRules }, flow.callbacks, flow.metadata, 1, flow.seen);
+        });
+    }
+}
+exports.MySuperwall = MySuperwall;

package/lib/engine/localRuleEngine.d.ts

@@ -0,0 +1,44 @@
+import { ManifestCondition, ManifestRule, ManifestTrigger, ManifestVariant } from '../models/manifest';
+export interface RuleEngineResolution {
+    matchedRuleId?: string;
+    show: boolean;
+    paywallId: string | null;
+    abVariant: string | null;
+    matchedRuleName: string | null;
+    isHoldout: boolean;
+    reason: string;
+}
+export declare class LocalRuleEngine {
+    /**
+     * Deterministic bucket from 0 to 99 matching backend SHA-256 logic.
+     */
+    getDeterministicBucket(userId?: string | null, salt?: string): number;
+    /**
+     * Compares two semantic version strings.
+     */
+    compareVersions(v1?: string | null, v2?: string | null): number;
+    /**
+     * Resolves nested field access like "metadata.tier".
+     */
+    resolveContextValue(field: string, context: Record<string, any>): any;
+    /**
+     * Evaluates a single condition.
+     */
+    evaluateCondition(condition: ManifestCondition, context: Record<string, any>): boolean;
+    /**
+     * Checks if a rule matches given context.
+     */
+    matchesRule(rule: ManifestRule, context: Record<string, any>): boolean;
+    /**
+     * Deterministically selects a variant respecting holdout.
+     */
+    selectDeterministicVariant(userId: string | null | undefined, salt: string, variants: ManifestVariant[], fallbackPaywallId: string | null, holdoutPercentage?: number): {
+        paywallId: string | null;
+        abVariant: string | null;
+        isHoldout: boolean;
+    };
+    /**
+     * Resolves a trigger in-memory with 0 ms latency.
+     */
+    resolveTrigger(trigger: ManifestTrigger, userId: string | null | undefined, context: Record<string, any>): RuleEngineResolution;
+}