@founderroute/analytics-react-native 0.1.0-beta.1

package/FounderRouteAnalytics.podspec

@@ -0,0 +1,16 @@
+require "json"
+package = JSON.parse(File.read(File.join(__dir__, "package.json")))
+Pod::Spec.new do |s|
+  s.name = "FounderRouteAnalytics"
+  s.version = package["version"]
+  s.summary = "Native consent-first FounderRoute Analytics for React Native"
+  s.homepage = "https://github.com/itsreed/founderroute-analytics"
+  s.license = "MIT"
+  s.author = "FounderRoute"
+  s.source = { :git => s.homepage + ".git", :tag => "v#{s.version}" }
+  s.platform = :ios, "15.0"
+  s.swift_version = "5.9"
+  s.source_files = "ios/**/*.{swift,h,m}"
+  s.resource_bundles = {"FounderRoutePrivacy" => ["ios/core/PrivacyInfo.xcprivacy"]}
+  s.dependency "React-Core"
+end

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 FounderRoute
+
+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/android/build.gradle

@@ -0,0 +1,16 @@
+buildscript { repositories { google(); mavenCentral() }; dependencies { classpath 'com.android.tools.build:gradle:8.9.2'; classpath 'org.jetbrains.kotlin:kotlin-gradle-plugin:2.1.20' } }
+apply plugin: 'com.android.library'
+apply plugin: 'org.jetbrains.kotlin.android'
+android {
+  namespace 'com.founderroute.analytics.reactnative'
+  compileSdk 35
+  defaultConfig { minSdk 24 }
+  compileOptions { sourceCompatibility JavaVersion.VERSION_17; targetCompatibility JavaVersion.VERSION_17 }
+  kotlinOptions { jvmTarget = '17' }
+}
+repositories { google(); mavenCentral() }
+dependencies {
+  implementation 'com.facebook.react:react-android'
+  implementation 'androidx.work:work-runtime-ktx:2.10.1'
+  implementation 'androidx.lifecycle:lifecycle-process:2.8.7'
+}

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android"><uses-permission android:name="android.permission.INTERNET"/><uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/></manifest>

package/android/src/main/java/com/founderroute/analytics/FounderRouteAnalytics.kt

@@ -0,0 +1,128 @@
+package com.founderroute.analytics
+
+import android.content.Context
+import androidx.lifecycle.DefaultLifecycleObserver
+import androidx.lifecycle.LifecycleOwner
+import androidx.lifecycle.ProcessLifecycleOwner
+import androidx.work.*
+import org.json.JSONArray
+import org.json.JSONObject
+import java.io.File
+import java.net.HttpURLConnection
+import java.net.URL
+import java.text.SimpleDateFormat
+import java.util.Date
+import java.util.Locale
+import java.util.TimeZone
+import java.util.UUID
+import java.util.concurrent.Executors
+import java.util.concurrent.TimeUnit
+import java.util.concurrent.Callable
+import java.util.concurrent.atomic.AtomicBoolean
+
+class FounderRouteAnalytics private constructor(private val context: Context, private val key: String, private val endpoint: String, private val appId: String, private val allowedProperties: Set<String>, private val allowedTraits: Set<String>,private val verificationId:String?) : DefaultLifecycleObserver {
+    companion object {
+        private fun timestamp(value:Long):String = SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",Locale.US).apply { timeZone=TimeZone.getTimeZone("UTC") }.format(Date(value))
+        private fun timestampMillis(value:String):Long {
+            val pattern=if(value.contains('.')) "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'" else "yyyy-MM-dd'T'HH:mm:ss'Z'"
+            return SimpleDateFormat(pattern,Locale.US).apply { timeZone=TimeZone.getTimeZone("UTC");isLenient=false }.parse(value)?.time ?: 0L
+        }
+        @Volatile internal var connectionFactory:(URL)->HttpURLConnection = { it.openConnection() as HttpURLConnection }
+        @Volatile private var instance: FounderRouteAnalytics? = null
+        @Synchronized fun init(context: Context, key: String, endpoint: String, appId: String, allowedProperties: Set<String> = emptySet(), allowedTraits: Set<String> = emptySet(),verificationId:String?=null): FounderRouteAnalytics {
+            require(key.startsWith("fr_pk_")); require(endpoint.startsWith("https://") || endpoint.startsWith("http://localhost"))
+            return instance ?: FounderRouteAnalytics(context.applicationContext,key,endpoint.trimEnd('/'),appId,allowedProperties,allowedTraits,verificationId).also { instance=it; android.os.Handler(android.os.Looper.getMainLooper()).post { ProcessLifecycleOwner.get().lifecycle.addObserver(it) } }
+        }
+        fun current() = instance
+        fun restore(context:Context,data:Data):FounderRouteAnalytics? {
+            val key=data.getString("key")?:return null
+            val file=File(context.noBackupFilesDir,"founderroute-${key.takeLast(16)}.json")
+            if(!file.exists())return null
+            val saved=try{JSONObject(file.readText())}catch(_:Exception){return null}
+            if(!saved.optBoolean("consent",false))return null
+            return init(context,key,data.getString("endpoint")?:return null,data.getString("appId")?:return null,
+              (data.getStringArray("properties")?:emptyArray()).toSet(),(data.getStringArray("traits")?:emptyArray()).toSet(),data.getString("verificationId")).also{it.setConsent(true)}
+        }
+    }
+    private val executor = Executors.newSingleThreadScheduledExecutor()
+    private val permitted = AtomicBoolean(false)
+    @Volatile private var activeConnection:HttpURLConnection?=null
+    private var consent = false; private var foreground = true; private var events = mutableListOf<JSONObject>()
+    private var anonymousId: String? = null; private var userId: String? = null; private var accountId: String? = null; private var token: String? = null
+    private var traits = JSONObject(); private var session = ""; private var lastActivity = 0L
+    private var campaign = JSONObject()
+    private var dropped = 0; private var rejected = 0; private var acknowledged = 0; private var lastError: String? = null; private var retryAt = 0L; private var failures = 0
+    private val file get() = File(context.noBackupFilesDir,"founderroute-${key.takeLast(16)}.json")
+    init { executor.scheduleWithFixedDelay({ if(consent) { if(foreground) enqueue("fr_session","session",JSONObject(),JSONObject().put("active_ms",15000)); deliver() } },15,15,TimeUnit.SECONDS) }
+    fun setConsent(granted: Boolean) { permitted.set(granted); if(!granted)activeConnection?.disconnect(); executor.execute {
+        if(consent==granted)return@execute
+        consent=granted
+        if(!granted) { events.clear(); anonymousId=null; userId=null; accountId=null; token=null; traits=JSONObject(); campaign=JSONObject(); file.delete(); WorkManager.getInstance(context).cancelUniqueWork("founderroute-delivery"); return@execute }
+        try { if(file.exists()) { val saved=JSONObject(file.readText()); dropped=saved.optInt("dropped",0); anonymousId=saved.optString("anonymous_id").takeIf{it.isNotBlank()}; val queue=saved.optJSONArray("events")?:JSONArray(); events=(0 until queue.length()).map { queue.getJSONObject(it) }.toMutableList() } } catch(_:Exception) { lastError="storage_unavailable" }
+        if(anonymousId==null)anonymousId=UUID.randomUUID().toString()
+        prune(); persist(); schedule(); deliver()
+    } }
+    fun identify(id:String, identityToken:String?=null, userTraits:JSONObject=JSONObject()) { executor.execute { if(consent) { if(userId!=null&&userId!=id) resetIdentity(); userId=id;token=identityToken;traits=JSONObject(userTraits.toString());enqueue("fr_identify","identify",JSONObject()) } } }
+    fun setAccount(id:String?) { executor.execute { if(consent)accountId=id } }
+    fun reset() { executor.execute { if(consent) {resetIdentity();persist()} } }
+    private fun resetIdentity() { anonymousId=UUID.randomUUID().toString();userId=null;accountId=null;token=null;traits=JSONObject();session=UUID.randomUUID().toString();lastActivity=0 }
+    fun track(name:String, properties:JSONObject=JSONObject(), outcomeId:String?=null) { val snapshot=JSONObject(properties.toString());executor.execute { enqueue(name,"custom",snapshot,outcomeId=outcomeId) } }
+    fun screen(name:String) { executor.execute { enqueue("screen_view","screen",JSONObject(),JSONObject().put("screen",name.take(150))) } }
+    /** Pass an installed-app deep link only after consent. No app-store attribution is inferred. */
+    fun setCampaignContext(url:String) { executor.execute {
+        if(!consent||!permitted.get())return@execute
+        val uri=android.net.Uri.parse(url);val next=JSONObject()
+        for((key,limit) in mapOf("utm_source" to 100,"utm_medium" to 100,"utm_campaign" to 150,"utm_content" to 150)) uri.getQueryParameter(key)?.let{next.put(key,it.take(limit))}
+        uri.getQueryParameter("fr_link")?.let { try { next.put("campaign_link",UUID.fromString(it).toString()) } catch(_:Exception){} }
+        campaign=next
+    } }
+    fun flush() { executor.execute { deliver() } }
+    fun flushForWorker():Boolean = executor.submit(Callable {
+        val deadline=System.currentTimeMillis()+25000
+        while(consent&&permitted.get()&&events.isNotEmpty()&&System.currentTimeMillis()<deadline&&System.currentTimeMillis()>=retryAt)deliver()
+        !permitted.get()||events.isEmpty()
+    }).get(30,TimeUnit.SECONDS)
+    fun getDiagnostics(callback:(JSONObject)->Unit) { executor.execute { callback(JSONObject().put("consent",consent).put("queued",events.size).put("dropped",dropped).put("rejected",rejected).put("acknowledged",acknowledged).put("anonymousId",anonymousId?:JSONObject.NULL).put("lastError",lastError?:JSONObject.NULL)) } }
+    private fun sanitize(input:JSONObject, allowed:Set<String>):JSONObject { val output=JSONObject();input.keys().forEach { key -> val value=input.opt(key); if(key in allowed&&!Regex("password|secret|token|email|phone|authorization|address|full.?name",RegexOption.IGNORE_CASE).containsMatchIn(key)) { if(value is String)output.put(key,value.take(500));else if(value is Number||value is Boolean||value==JSONObject.NULL)output.put(key,value) } };return output }
+    private fun enqueue(name:String,kind:String,properties:JSONObject,extra:JSONObject=JSONObject(),outcomeId:String?=null) {
+        if(!consent||!permitted.get()||anonymousId==null)return
+        val now=System.currentTimeMillis();if(now-lastActivity>=1800000)session=UUID.randomUUID().toString();lastActivity=now
+        val ctx=JSONObject().put("sdk","android").put("sdk_version","0.1.0-beta.1").put("app_id",appId);extra.keys().forEach { ctx.put(it,extra.get(it)) }
+        verificationId?.let{ctx.put("verification_id",it)}
+        campaign.keys().forEach { ctx.put(it,campaign.get(it)) }
+        val event=JSONObject().put("event_id",UUID.randomUUID().toString()).put("protocol",1).put("name",name).put("kind",kind).put("occurred_at",timestamp(now)).put("anonymous_id",anonymousId).put("session_id",session).put("consent",true).put("properties",sanitize(properties,allowedProperties)).put("traits",sanitize(traits,allowedTraits)).put("context",ctx)
+        userId?.let{event.put("user_id",it)};accountId?.let{event.put("account_id",it)};token?.let{event.put("identity_token",it)};outcomeId?.let{event.put("outcome_id",it)}
+        if(event.toString().toByteArray().size>8192){rejected++;lastError="event_too_large";return}
+        events.add(event);prune();persist();schedule()
+    }
+    private fun prune() {
+        val cutoff=System.currentTimeMillis()-7*86400000L;val size=events.size
+        events.removeAll { try { timestampMillis(it.getString("occurred_at"))<cutoff } catch(_:Exception){true} };dropped+=size-events.size
+        while(events.size>10000||JSONArray(events).toString().toByteArray().size>10*1024*1024){events.removeAt(0);dropped++}
+    }
+    private fun persist() { if(!consent||!permitted.get())return;try { val temp=File(file.path+".tmp");temp.writeText(JSONObject().put("consent",true).put("dropped",dropped).put("anonymous_id",anonymousId).put("events",JSONArray(events)).toString()); if(!temp.renameTo(file)){file.writeText(temp.readText());temp.delete()} }catch(_:Exception){lastError="storage_unavailable"} }
+    private fun schedule() { val constraints=Constraints.Builder().setRequiredNetworkType(NetworkType.CONNECTED).build();val request=OneTimeWorkRequestBuilder<AnalyticsDeliveryWorker>().setInputData(workDataOf("key" to key,"endpoint" to endpoint,"appId" to appId,"properties" to allowedProperties.toTypedArray(),"traits" to allowedTraits.toTypedArray(),"verificationId" to verificationId)).setConstraints(constraints).setBackoffCriteria(BackoffPolicy.EXPONENTIAL,30,TimeUnit.SECONDS).build();WorkManager.getInstance(context).enqueueUniqueWork("founderroute-delivery",ExistingWorkPolicy.KEEP,request) }
+    private fun deliver() {
+        if(!consent||!permitted.get()||System.currentTimeMillis()<retryAt)return
+        prune();val batch=mutableListOf<JSONObject>();for(event in events.take(50)){if(JSONObject().put("key",key).put("events",JSONArray(batch+event)).toString().toByteArray().size>65536)break;batch.add(event)};if(batch.isEmpty())return
+        var connection:HttpURLConnection?=null
+        try {
+            connection=connectionFactory(URL("$endpoint/api/analytics/v1/collect"));activeConnection=connection;connection.requestMethod="POST";connection.setRequestProperty("Content-Type","application/json");connection.doOutput=true;connection.connectTimeout=10000;connection.readTimeout=15000
+            if(!permitted.get())return
+            connection.outputStream.use{it.write(JSONObject().put("key",key).put("events",JSONArray(batch)).toString().toByteArray())}
+            val status=connection.responseCode
+            if(!permitted.get())return
+            if(status==429||status>=500){retry("delivery_$status");return}
+            if(status!=200){val ids=batch.map{it.getString("event_id")}.toSet();events.removeAll{it.getString("event_id") in ids};rejected+=ids.size;lastError="delivery_rejected";persist();return}
+            val response=JSONObject(connection.inputStream.bufferedReader().use{it.readText()});val results=response.optJSONArray("results")?:JSONArray();val ids=mutableSetOf<String>()
+            for(i in 0 until results.length()){val receipt=results.getJSONObject(i);val state=receipt.optString("status");if(state in listOf("accepted","duplicate","rejected")){ids.add(receipt.getString("event_id"));if(state=="rejected"){rejected++;lastError=receipt.optString("reason")}else acknowledged++}}
+            events.removeAll{it.getString("event_id") in ids};failures=0;retryAt=0;persist()
+        }catch(_:Exception){retry("network_unavailable")}finally{connection?.disconnect();activeConnection=null}
+    }
+    private fun retry(reason:String){lastError=reason;failures++;retryAt=System.currentTimeMillis()+minOf(300000L,1000L shl minOf(failures,8));schedule()}
+    override fun onStart(owner:LifecycleOwner){executor.execute{foreground=true;retryAt=0;deliver()}}
+    override fun onStop(owner:LifecycleOwner){executor.execute{foreground=false;deliver()}}
+}
+class AnalyticsDeliveryWorker(context:Context,params:WorkerParameters):Worker(context,params){
+    override fun doWork():Result { val client=FounderRouteAnalytics.current()?:FounderRouteAnalytics.restore(applicationContext,inputData)?:return Result.success();return try{if(client.flushForWorker())Result.success()else Result.retry()}catch(_:Exception){Result.retry()} }
+}

package/android/src/main/java/com/founderroute/analytics/reactnative/FounderRouteAnalyticsModule.kt

@@ -0,0 +1,25 @@
+package com.founderroute.analytics.reactnative
+import com.facebook.react.bridge.*
+import com.facebook.react.ReactPackage
+import com.facebook.react.uimanager.ViewManager
+import com.founderroute.analytics.FounderRouteAnalytics
+import org.json.JSONObject
+
+class FounderRouteAnalyticsModule(private val context:ReactApplicationContext):ReactContextBaseJavaModule(context) {
+    override fun getName()="FounderRouteAnalyticsModule"
+    private var client:FounderRouteAnalytics?=null
+    @ReactMethod fun configure(key:String,endpoint:String,appId:String,properties:ReadableArray,traits:ReadableArray,verificationId:String?) { client=FounderRouteAnalytics.init(context,key,endpoint,appId,properties.toArrayList().map{it.toString()}.toSet(),traits.toArrayList().map{it.toString()}.toSet(),verificationId) }
+    @ReactMethod fun setConsent(value:Boolean){client?.setConsent(value)}
+    @ReactMethod fun identify(id:String,token:String?,traits:ReadableMap){client?.identify(id,token,JSONObject(traits.toHashMap()))}
+    @ReactMethod fun setAccount(id:String?){client?.setAccount(id)}
+    @ReactMethod fun track(name:String,properties:ReadableMap,outcomeId:String?){client?.track(name,JSONObject(properties.toHashMap()),outcomeId)}
+    @ReactMethod fun screen(name:String){client?.screen(name)}
+    @ReactMethod fun setCampaignContext(url:String){client?.setCampaignContext(url)}
+    @ReactMethod fun reset(){client?.reset()}
+    @ReactMethod fun flush(){client?.flush()}
+    @ReactMethod fun getDiagnostics(promise:Promise){val analytics=client;if(analytics==null){promise.reject("not_initialized","Initialize FounderRoute first.");return};analytics.getDiagnostics{data->val result=Arguments.createMap();data.keys().forEach{key->when(val v=data.get(key)){is Boolean->result.putBoolean(key,v);is Number->result.putDouble(key,v.toDouble());JSONObject.NULL->result.putNull(key);else->result.putString(key,v.toString())}};promise.resolve(result)}}
+}
+class FounderRouteAnalyticsPackage:ReactPackage {
+    override fun createNativeModules(context:ReactApplicationContext)=listOf<NativeModule>(FounderRouteAnalyticsModule(context))
+    override fun createViewManagers(context:ReactApplicationContext)=emptyList<ViewManager<*,*>>()
+}

package/bridge.js

@@ -0,0 +1,18 @@
+// All persistence, consent, identity, and delivery live in the native SDK once.
+export function createBridge(native, platform, options) {
+  if (!native) throw new Error("Link FounderRoute's native module and rebuild the application.");
+  const config = {...options, ...options[platform]};
+  if (!config.key || !config.appId) throw new Error(`Register a ${platform} property and provide its public key and app ID.`);
+  native.configure(config.key, config.endpoint, config.appId, config.allowedProperties ?? [], config.allowedTraits ?? [],config.verificationId??null);
+  return {
+    setConsent: granted => native.setConsent(Boolean(granted)),
+    identify: (id, {token, traits = {}} = {}) => native.identify(id, token ?? null, traits),
+    setAccount: id => native.setAccount(id ?? null),
+    track: (name, properties = {}, {outcomeId} = {}) => native.track(name, properties, outcomeId ?? null),
+    screen: name => native.screen(name),
+    setCampaignContext: url => native.setCampaignContext(url),
+    reset: () => native.reset(),
+    flush: () => native.flush(),
+    getDiagnostics: () => native.getDiagnostics(),
+  };
+}

package/index.d.ts

@@ -0,0 +1,12 @@
+export interface Options { endpoint: string; verificationId?:string; ios: {key:string;appId:string}; android: {key:string;appId:string}; allowedProperties?:string[]; allowedTraits?:string[] }
+export interface Client {
+  setConsent(granted:boolean):void;
+  identify(id:string,options?:{token?:string;traits?:Record<string,string|number|boolean|null>}):void;
+  setAccount(id:string|null):void;
+  track(name:string,properties?:Record<string,string|number|boolean|null>,options?:{outcomeId?:string}):void;
+  screen(name:string):void; reset():void; flush():void;
+  setCampaignContext(url:string):void;
+  getDiagnostics():Promise<{consent:boolean;queued:number;dropped:number;anonymousId:string|null}>;
+}
+export function init(options:Options):Client;
+export function navigationAdapter(client:Client,ref:{current?:{getCurrentRoute():{name:string}|undefined}|null}):()=>void;

package/index.js

@@ -0,0 +1,14 @@
+import { NativeModules, Platform } from "react-native";
+import { createBridge } from "./bridge.js";
+let client;
+export function init(options) {
+  client ??= createBridge(NativeModules.FounderRouteAnalyticsModule, Platform.OS, options);
+  return client;
+}
+export function navigationAdapter(client, navigationRef) {
+  let previous;
+  return () => {
+    const name = navigationRef.current?.getCurrentRoute()?.name;
+    if (name && name !== previous) { previous = name; client.screen(name); }
+  };
+}

package/ios/FounderRouteAnalyticsModule.m

@@ -0,0 +1,13 @@
+#import <React/RCTBridgeModule.h>
+@interface RCT_EXTERN_MODULE(FounderRouteAnalyticsModule, NSObject)
+RCT_EXTERN_METHOD(configure:(NSString *)key endpoint:(NSString *)endpoint appId:(NSString *)appId properties:(NSArray *)properties traits:(NSArray *)traits verificationId:(NSString *)verificationId)
+RCT_EXTERN_METHOD(setConsent:(BOOL)value)
+RCT_EXTERN_METHOD(identify:(NSString *)identifier token:(NSString *)token traits:(NSDictionary *)traits)
+RCT_EXTERN_METHOD(setAccount:(NSString *)identifier)
+RCT_EXTERN_METHOD(track:(NSString *)name properties:(NSDictionary *)properties outcomeId:(NSString *)outcomeId)
+RCT_EXTERN_METHOD(screen:(NSString *)name)
+RCT_EXTERN_METHOD(setCampaignContext:(NSString *)url)
+RCT_EXTERN_METHOD(reset)
+RCT_EXTERN_METHOD(flush)
+RCT_EXTERN_METHOD(getDiagnostics:(RCTPromiseResolveBlock)resolve rejecter:(RCTPromiseRejectBlock)reject)
+@end

package/ios/FounderRouteAnalyticsModule.swift

@@ -0,0 +1,18 @@
+import Foundation
+import React
+
+@objc(FounderRouteAnalyticsModule)
+final class FounderRouteAnalyticsModule: NSObject {
+    private let analytics = FounderRouteAnalytics.shared
+    @objc static func requiresMainQueueSetup() -> Bool { false }
+    @objc func configure(_ key: String, endpoint: String, appId: String, properties: [String], traits: [String], verificationId: String?) { analytics.configure(key: key, endpoint: endpoint, appId: appId, allowedProperties: properties, allowedTraits: traits, verificationId: verificationId) }
+    @objc func setConsent(_ value: Bool) { analytics.setConsent(value) }
+    @objc func identify(_ id: String, token: String?, traits: [String: Any]) { analytics.identify(id, token: token, traits: traits) }
+    @objc func setAccount(_ id: String?) { analytics.setAccount(id) }
+    @objc func track(_ name: String, properties: [String: Any], outcomeId: String?) { analytics.track(name, properties: properties, outcomeId: outcomeId) }
+    @objc func screen(_ name: String) { analytics.screen(name) }
+    @objc func setCampaignContext(_ url: String) { analytics.setCampaignContext(url) }
+    @objc func reset() { analytics.reset() }
+    @objc func flush() { analytics.flush() }
+    @objc func getDiagnostics(_ resolve: @escaping RCTPromiseResolveBlock, rejecter reject: @escaping RCTPromiseRejectBlock) { analytics.getDiagnostics { resolve($0) } }
+}

package/ios/core/FounderRouteAnalytics.swift

@@ -0,0 +1,161 @@
+import Foundation
+#if canImport(UIKit)
+import UIKit
+#endif
+
+public final class FounderRouteAnalytics: @unchecked Sendable {
+    public static let shared = FounderRouteAnalytics()
+    private let work = DispatchQueue(label: "com.founderroute.analytics", qos: .utility)
+    private var key = "", endpoint = "", appId = ""
+    private var verificationId: String?
+    private var campaign: [String:Any] = [:]
+    private var consent = false, sending = false, foreground = true
+    private var anonymousId: String?, userId: String?, accountId: String?, identityToken: String?
+    private var traits: [String: Any] = [:], allowedTraits: Set<String> = [], allowedProperties: Set<String> = []
+    private var events: [[String: Any]] = []
+    private var sessionId = "", lastActivity = Date.distantPast
+    private var dropped = 0, rejected = 0, acknowledged = 0, failures = 0, generation = 0
+    private var retryAt = Date.distantPast, lastError: String?
+    private var timer: DispatchSourceTimer?, task: URLSessionDataTask?
+    private var observers: [NSObjectProtocol] = []
+    private let transport: URLSession
+    public init(transport: URLSession = .shared) { self.transport = transport }
+
+    public func configure(key: String, endpoint: String, appId: String, allowedProperties: [String] = [], allowedTraits: [String] = [], verificationId: String? = nil) {
+        work.async {
+            guard self.key.isEmpty else { return }
+            guard key.hasPrefix("fr_pk_"), let url = URL(string: endpoint), url.scheme == "https" || url.host == "localhost" else { self.lastError = "invalid_configuration"; return }
+            self.key = key; self.endpoint = endpoint.trimmingCharacters(in: CharacterSet(charactersIn: "/")); self.appId = appId
+            self.verificationId = verificationId
+            self.allowedProperties = Set(allowedProperties); self.allowedTraits = Set(allowedTraits)
+            #if canImport(UIKit)
+            self.observers.append(NotificationCenter.default.addObserver(forName: UIApplication.didEnterBackgroundNotification, object: nil, queue: nil) { [weak self] _ in
+                self?.work.async { self?.foreground = false; self?.deliver() }
+            })
+            self.observers.append(NotificationCenter.default.addObserver(forName: UIApplication.didBecomeActiveNotification, object: nil, queue: nil) { [weak self] _ in
+                self?.work.async { self?.foreground = true; self?.retryAt = .distantPast; self?.deliver() }
+            })
+            #endif
+        }
+    }
+    private var fileURL: URL? {
+        guard !key.isEmpty else { return nil }
+        return FileManager.default.urls(for: .applicationSupportDirectory, in: .userDomainMask).first?.appendingPathComponent("founderroute-\(key.suffix(16)).json")
+    }
+    public func setConsent(_ granted: Bool) {
+        work.async {
+            guard granted != self.consent, !self.key.isEmpty else { return }
+            self.consent = granted; self.generation += 1
+            if !granted {
+                self.task?.cancel(); self.timer?.cancel(); self.timer = nil; self.events = []; self.anonymousId = nil
+                self.userId = nil; self.accountId = nil; self.identityToken = nil; self.traits = [:]; self.campaign = [:]
+                if let file = self.fileURL { try? FileManager.default.removeItem(at: file) }; return
+            }
+            if let file = self.fileURL, let data = try? Data(contentsOf: file), let saved = (try? JSONSerialization.jsonObject(with: data)) as? [String: Any] {
+                self.dropped = saved["dropped"] as? Int ?? 0
+                self.events = saved["events"] as? [[String: Any]] ?? []; self.anonymousId = saved["anonymous_id"] as? String
+            }
+            self.anonymousId = self.anonymousId ?? UUID().uuidString
+            self.prune(); self.persist()
+            let timer = DispatchSource.makeTimerSource(queue: self.work)
+            timer.schedule(deadline: .now() + 15, repeating: 15)
+            timer.setEventHandler { [weak self] in
+                guard let self else { return }
+                if self.foreground { self.enqueue("fr_session", kind: "session", properties: [:], context: ["active_ms": 15000]) }
+                self.deliver()
+            }
+            self.timer = timer; timer.resume(); self.deliver()
+        }
+    }
+    public func identify(_ userId: String, token: String? = nil, traits: [String: Any] = [:]) {
+        work.async {
+            guard self.consent else { return }
+            if let old = self.userId, old != userId { self.resetIdentity() }
+            self.userId = userId; self.identityToken = token; self.traits = traits
+            self.enqueue("fr_identify", kind: "identify", properties: [:])
+        }
+    }
+    public func setAccount(_ id: String?) { work.async { if self.consent { self.accountId = id } } }
+    public func reset() { work.async { if self.consent { self.resetIdentity(); self.persist() } } }
+    private func resetIdentity() { anonymousId = UUID().uuidString; userId = nil; accountId = nil; identityToken = nil; traits = [:]; sessionId = UUID().uuidString; lastActivity = .distantPast }
+    public func track(_ name: String, properties: [String: Any] = [:], outcomeId: String? = nil) { work.async { self.enqueue(name, kind: "custom", properties: properties, outcomeId: outcomeId) } }
+    public func screen(_ name: String) { work.async { self.enqueue("screen_view", kind: "screen", properties: [:], context: ["screen": String(name.prefix(150))]) } }
+    /// Supply an installed-app deep link after consent; this does not infer app-store attribution.
+    public func setCampaignContext(_ url: String) { work.async {
+        guard self.consent, let items = URLComponents(string:url)?.queryItems else { return }
+        var next: [String:Any] = [:]
+        for item in items {
+            guard let value = item.value else { continue }
+            if let limit = ["utm_source":100,"utm_medium":100,"utm_campaign":150,"utm_content":150][item.name] { next[item.name] = String(value.prefix(limit)) }
+            if item.name == "fr_link", let id = UUID(uuidString:value) { next["campaign_link"] = id.uuidString.lowercased() }
+        }
+        self.campaign = next
+    } }
+    public func flush() { work.async { self.deliver() } }
+    public func getDiagnostics(_ completion: @escaping ([String: Any]) -> Void) {
+        work.async { let result: [String: Any] = ["consent": self.consent, "queued": self.events.count, "dropped": self.dropped, "rejected": self.rejected, "acknowledged": self.acknowledged, "anonymousId": self.anonymousId.map { $0 as Any } ?? NSNull(), "lastError": self.lastError.map { $0 as Any } ?? NSNull()]; completion(result) }
+    }
+    private func sanitize(_ input: [String: Any], allowed: Set<String>) -> [String: Any] {
+        var result: [String: Any] = [:]
+        for (key, value) in input where allowed.contains(key) && key.range(of: "password|secret|token|email|phone|authorization|address|full.?name", options: .regularExpression) == nil {
+            if let string = value as? String { result[key] = String(string.prefix(500)) }
+            else if value is NSNumber || value is NSNull { result[key] = value }
+        }
+        return result
+    }
+    private func enqueue(_ name: String, kind: String, properties: [String: Any], context: [String: Any] = [:], outcomeId: String? = nil) {
+        guard consent, let anonymousId else { return }
+        let now = Date(); if now.timeIntervalSince(lastActivity) >= 1800 { sessionId = UUID().uuidString }; lastActivity = now
+        var ctx: [String: Any] = ["sdk": "ios", "sdk_version": "0.1.0-beta.1", "app_id": appId]
+        ctx["verification_id"] = verificationId
+        for (key, value) in campaign { ctx[key] = value }
+        for (key, value) in context { ctx[key] = value }
+        var event: [String: Any] = ["event_id": UUID().uuidString, "protocol": 1, "name": name, "kind": kind, "occurred_at": ISO8601DateFormatter().string(from: now), "anonymous_id": anonymousId, "session_id": sessionId, "consent": true, "properties": sanitize(properties, allowed: allowedProperties), "traits": sanitize(traits, allowed: allowedTraits), "context": ctx]
+        event["user_id"] = userId; event["identity_token"] = identityToken; event["account_id"] = accountId; event["outcome_id"] = outcomeId
+        guard let bytes = try? JSONSerialization.data(withJSONObject: event), bytes.count <= 8192 else { rejected += 1; lastError = "event_too_large"; return }
+        events.append(event); prune(); persist()
+    }
+    private func prune() {
+        let cutoff = Date().addingTimeInterval(-7 * 86400); let before = events.count
+        events.removeAll { event in guard let at = event["occurred_at"] as? String, let date = ISO8601DateFormatter().date(from: at) else { return true }; return date < cutoff }
+        dropped += before - events.count
+        while events.count > 10000 || ((try? JSONSerialization.data(withJSONObject: events).count) ?? 0) > 10 * 1024 * 1024 { events.removeFirst(); dropped += 1 }
+    }
+    private func persist() {
+        guard consent, let file = fileURL else { return }
+        do {
+            try FileManager.default.createDirectory(at: file.deletingLastPathComponent(), withIntermediateDirectories: true)
+            let data = try JSONSerialization.data(withJSONObject: ["anonymous_id": anonymousId ?? "", "events": events, "dropped": dropped])
+            try data.write(to: file, options: .atomic)
+            var resource = URLResourceValues(); resource.isExcludedFromBackup = true; var mutable = file; try mutable.setResourceValues(resource)
+        } catch { lastError = "storage_unavailable" }
+    }
+    private func deliver() {
+        guard consent, !sending, Date() >= retryAt, let url = URL(string: endpoint + "/api/analytics/v1/collect") else { return }
+        prune(); var batch: [[String: Any]] = []
+        for event in events.prefix(50) {
+            guard let data = try? JSONSerialization.data(withJSONObject: ["key": key, "events": batch + [event]]), data.count <= 65536 else { break }; batch.append(event)
+        }
+        guard !batch.isEmpty, let body = try? JSONSerialization.data(withJSONObject: ["key": key, "events": batch]) else { return }
+        var request = URLRequest(url: url); request.httpMethod = "POST"; request.httpBody = body; request.setValue("application/json", forHTTPHeaderField: "Content-Type"); request.timeoutInterval = 20
+        sending = true; let currentGeneration = generation; let batchIDs = Set(batch.compactMap { $0["event_id"] as? String })
+        task = transport.dataTask(with: request) { [weak self] data, response, error in
+            guard let self else { return }
+            self.work.async {
+                self.sending = false; guard self.consent, self.generation == currentGeneration else { return }
+                guard error == nil, let response = response as? HTTPURLResponse else { self.retry("network_unavailable"); return }
+                let status = response.statusCode
+                if status == 429 || status >= 500 { self.retry("delivery_\(status)"); return }
+                guard status == 200, let data, let result = (try? JSONSerialization.jsonObject(with: data)) as? [String: Any], let receipts = result["results"] as? [[String: Any]] else {
+                    self.events.removeAll { batchIDs.contains($0["event_id"] as? String ?? "") }; self.rejected += batchIDs.count; self.lastError = "delivery_rejected"; self.persist(); return
+                }
+                var ids = Set<String>()
+                for receipt in receipts { if let id = receipt["event_id"] as? String, let state = receipt["status"] as? String, ["accepted", "duplicate", "rejected"].contains(state) { ids.insert(id); if state == "rejected" { self.rejected += 1; self.lastError = receipt["reason"] as? String } else { self.acknowledged += 1 } } }
+                self.events.removeAll { ids.contains($0["event_id"] as? String ?? "") }; self.failures = 0; self.retryAt = .distantPast; self.persist()
+            }
+        }
+        task?.resume()
+    }
+    private func retry(_ error: String) { lastError = error; failures += 1; retryAt = Date().addingTimeInterval(min(300, pow(2, Double(min(8, failures))))); persist() }
+    deinit { timer?.cancel(); task?.cancel(); observers.forEach { NotificationCenter.default.removeObserver($0) } }
+}

package/ios/core/PrivacyInfo.xcprivacy

@@ -0,0 +1,10 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0"><dict>
+<key>NSPrivacyTracking</key><false/>
+<key>NSPrivacyTrackingDomains</key><array/>
+<key>NSPrivacyAccessedAPITypes</key><array/>
+<key>NSPrivacyCollectedDataTypes</key><array>
+<dict><key>NSPrivacyCollectedDataType</key><string>NSPrivacyCollectedDataTypeProductInteraction</string><key>NSPrivacyCollectedDataTypeLinked</key><true/><key>NSPrivacyCollectedDataTypeTracking</key><false/><key>NSPrivacyCollectedDataTypePurposes</key><array><string>NSPrivacyCollectedDataTypePurposeAnalytics</string></array></dict>
+<dict><key>NSPrivacyCollectedDataType</key><string>NSPrivacyCollectedDataTypeUserID</string><key>NSPrivacyCollectedDataTypeLinked</key><true/><key>NSPrivacyCollectedDataTypeTracking</key><false/><key>NSPrivacyCollectedDataTypePurposes</key><array><string>NSPrivacyCollectedDataTypePurposeAnalytics</string></array></dict>
+</array></dict></plist>

package/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "@founderroute/analytics-react-native",
+  "version": "0.1.0-beta.1",
+  "description": "Consent-first FounderRoute analytics for React Native",
+  "license": "MIT",
+  "type": "module",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "files": ["*.js", "*.cjs", "*.d.ts", "*.podspec", "android", "ios", "LICENSE"],
+  "peerDependencies": {"react": ">=18 <20", "react-native": ">=0.76 <1"},
+  "repository": { "type": "git", "url": "git+https://github.com/itsreed/founderroute-analytics.git", "directory": "packages/react-native" },
+  "homepage": "https://github.com/itsreed/founderroute-analytics#readme",
+  "bugs": { "url": "https://github.com/itsreed/founderroute-analytics/issues" },
+  "publishConfig": { "access": "public", "provenance": true }
+}

package/react-native.config.cjs

@@ -0,0 +1 @@
+module.exports = { dependency: { platforms: { android: { packageImportPath: 'import com.founderroute.analytics.reactnative.FounderRouteAnalyticsPackage;', packageInstance: 'new FounderRouteAnalyticsPackage()' } } } };