respectlytics-react-native 1.0.1

package/LICENSE

@@ -0,0 +1,24 @@
+Respectlytics SDK License
+Copyright (c) 2025 Respectlytics. All rights reserved.
+
+PERMITTED USES:
+- View and read the source code for transparency and security review
+- Install the SDK via official package managers (SPM, npm, pub.dev)
+- Use the SDK to send analytics data to the official Respectlytics service
+
+PROHIBITED USES:
+- Copying, forking, or redistributing the source code
+- Modifying the SDK source code
+- Using the SDK with any backend other than the official Respectlytics API
+- Creating derivative works based on this SDK
+- Reverse engineering beyond what is necessary for interoperability
+
+NO WARRANTY:
+This SDK is provided "as is" without warranty of any kind. Respectlytics
+shall not be liable for any damages arising from the use of this SDK.
+
+TERMINATION:
+This license terminates automatically if you violate any of its terms.
+Upon termination, you must cease all use and destroy all copies.
+
+For licensing inquiries: respectlytics@loheden.com

package/README.md

@@ -0,0 +1,160 @@
+# Respectlytics React Native SDK
+
+[![npm version](https://img.shields.io/npm/v/respectlytics-react-native.svg)](https://www.npmjs.com/package/respectlytics-react-native)
+[![Platform](https://img.shields.io/badge/platform-iOS%20%7C%20Android-lightgrey.svg)](https://github.com/respectlytics/respectlytics-react-native)
+[![License](https://img.shields.io/badge/license-Proprietary-blue.svg)](LICENSE)
+
+Official Respectlytics SDK for React Native. Privacy-first analytics with automatic session management, offline event queuing, and zero device identifier collection.
+
+## Features
+
+- 🔒 **Privacy-First**: No device identifiers (IDFA, GAID, Android ID)
+- ⚡ **Simple Integration**: 3 lines of code to get started
+- 📡 **Offline Support**: Events queue automatically and sync when online
+- 🔄 **Automatic Sessions**: 30-minute inactivity timeout, handled internally
+- 🎯 **Cross-Session Tracking**: Optional persistent user IDs
+- 📱 **Cross-Platform**: iOS and Android support
+
+## Requirements
+
+- React Native 0.70+
+- iOS 15.0+ / Android API 21+
+- Node.js 16+
+
+## Installation
+
+```bash
+npm install respectlytics-react-native @react-native-async-storage/async-storage @react-native-community/netinfo
+```
+
+or with Yarn:
+
+```bash
+yarn add respectlytics-react-native @react-native-async-storage/async-storage @react-native-community/netinfo
+```
+
+### iOS Setup
+
+```bash
+cd ios && pod install
+```
+
+### Android Setup
+
+No additional setup required - autolinking handles everything.
+
+## Quick Start
+
+```typescript
+import Respectlytics from 'respectlytics-react-native';
+
+// 1. Configure at app startup
+Respectlytics.configure('your-api-key');
+
+// 2. Enable user tracking (optional)
+Respectlytics.identify();
+
+// 3. Track events
+Respectlytics.track('purchase');
+Respectlytics.track('view_product', 'ProductScreen');
+```
+
+## API Reference
+
+### `configure(apiKey: string)`
+
+Initialize the SDK with your API key. Call once at app startup.
+
+```typescript
+Respectlytics.configure('your-api-key');
+```
+
+### `track(eventName: string, screen?: string)`
+
+Track an event with an optional screen name.
+
+```typescript
+Respectlytics.track('button_clicked');
+Respectlytics.track('checkout_started', 'CartScreen');
+```
+
+### `identify()`
+
+Enable cross-session user tracking. Generates and persists a random user ID.
+
+```typescript
+Respectlytics.identify();
+```
+
+### `reset()`
+
+Clear the user ID. Call when user logs out.
+
+```typescript
+Respectlytics.reset();
+```
+
+### `flush()`
+
+Force send all queued events immediately. Rarely needed - the SDK auto-flushes.
+
+```typescript
+await Respectlytics.flush();
+```
+
+## Privacy by Design
+
+| What we DON'T collect | Why |
+|----------------------|-----|
+| IDFA / GAID | Device advertising IDs can track users across apps |
+| Device fingerprints | Can be used to identify users without consent |
+| IP addresses | Used only for geolocation lookup, then discarded |
+| Custom properties | Prevents accidental PII collection |
+
+| What we DO collect | Purpose |
+|-------------------|---------|
+| Event name | Analytics |
+| Screen name | Navigation analytics |
+| Random session ID | Group events in a session |
+| Random user ID (opt-in) | Cross-session analytics |
+| Platform, OS version | Debugging |
+| App version | Debugging |
+
+## Automatic Behaviors
+
+The SDK handles these automatically - no developer action needed:
+
+| Feature | Behavior |
+|---------|----------|
+| **Session Management** | New session ID generated on first event, rotates after 30 min inactivity |
+| **Event Batching** | Events queued and sent in batches (max 10 events or 30 seconds) |
+| **Offline Support** | Events queued when offline, sent when connectivity returns |
+| **Retry Logic** | Failed requests retry with exponential backoff (max 3 attempts) |
+| **Background Sync** | Events flushed when app enters background |
+
+## Offline Support
+
+Events are automatically queued when offline and sent when connectivity returns:
+
+1. Events are immediately persisted to AsyncStorage
+2. Network status is monitored via NetInfo
+3. Queue is flushed when connectivity is restored
+4. Failed sends are retried with exponential backoff
+
+## Session Management
+
+Sessions are managed automatically:
+
+- New session starts on first event
+- Session rotates after 30 minutes of inactivity
+- No developer action required
+
+## License
+
+This SDK is provided under a proprietary license. See [LICENSE](LICENSE) for details.
+
+## Support
+
+- Documentation: [https://respectlytics.com/docs/](https://respectlytics.com/docs/)
+- Issues: [https://github.com/respectlytics/respectlytics-react-native/issues](https://github.com/respectlytics/respectlytics-react-native/issues)
+- Email: respectlytics@loheden.com

package/package.json

@@ -0,0 +1,94 @@
+{
+  "name": "respectlytics-react-native",
+  "version": "1.0.1",
+  "description": "Official Respectlytics SDK for React Native. Privacy-first analytics with automatic session management, offline event queuing, and zero device identifier collection.",
+  "main": "lib/commonjs/index.js",
+  "module": "lib/module/index.js",
+  "types": "lib/typescript/src/index.d.ts",
+  "react-native": "src/index.ts",
+  "source": "src/index.ts",
+  "files": [
+    "src",
+    "lib",
+    "!**/__tests__",
+    "!**/__fixtures__",
+    "!**/__mocks__",
+    "!**/.*"
+  ],
+  "scripts": {
+    "typescript": "tsc --noEmit",
+    "lint": "eslint \"**/*.{js,ts,tsx}\"",
+    "build": "bob build",
+    "test": "jest",
+    "test:integration": "jest --config jest.integration.config.js",
+    "clean": "rm -rf lib"
+  },
+  "keywords": [
+    "react-native",
+    "analytics",
+    "privacy",
+    "tracking",
+    "events",
+    "respectlytics",
+    "ios",
+    "android"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/respectlytics/respectlytics-react-native.git"
+  },
+  "author": "Respectlytics <respectlytics@loheden.com>",
+  "license": "SEE LICENSE IN LICENSE",
+  "bugs": {
+    "url": "https://github.com/respectlytics/respectlytics-react-native/issues"
+  },
+  "homepage": "https://github.com/respectlytics/respectlytics-react-native#readme",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/"
+  },
+  "devDependencies": {
+    "@react-native-async-storage/async-storage": "^2.0.0",
+    "@react-native-community/netinfo": "^11.3.0",
+    "@types/jest": "^29.5.12",
+    "@types/react": "^18.2.0",
+    "@types/react-native": "^0.72.0",
+    "eslint": "^8.56.0",
+    "jest": "^29.7.0",
+    "react": "^18.2.0",
+    "react-native": "^0.73.0",
+    "react-native-builder-bob": "^0.23.2",
+    "tsx": "^4.20.6",
+    "typescript": "^5.3.3"
+  },
+  "peerDependencies": {
+    "@react-native-async-storage/async-storage": ">=1.17.0",
+    "@react-native-community/netinfo": ">=9.0.0",
+    "react": ">=18.0.0",
+    "react-native": ">=0.70.0"
+  },
+  "peerDependenciesMeta": {
+    "@react-native-async-storage/async-storage": {
+      "optional": false
+    },
+    "@react-native-community/netinfo": {
+      "optional": false
+    }
+  },
+  "engines": {
+    "node": ">=16.0.0"
+  },
+  "react-native-builder-bob": {
+    "source": "src",
+    "output": "lib",
+    "targets": [
+      "commonjs",
+      "module",
+      [
+        "typescript",
+        {
+          "project": "tsconfig.build.json"
+        }
+      ]
+    ]
+  }
+}

package/src/EventQueue.ts

@@ -0,0 +1,182 @@
+/**
+ * EventQueue.ts
+ * Respectlytics React Native SDK
+ * 
+ * Manages event batching, persistence, and automatic flushing.
+ * Events are NEVER lost - they are persisted immediately and retried on failure.
+ * Copyright (c) 2025 Respectlytics. All rights reserved.
+ */
+
+import { AppState, AppStateStatus } from 'react-native';
+import NetInfo, { NetInfoState } from '@react-native-community/netinfo';
+import { Event } from './types';
+import { Storage } from './Storage';
+import { NetworkClient } from './NetworkClient';
+
+const MAX_QUEUE_SIZE = 10;
+const FLUSH_INTERVAL_MS = 30000; // 30 seconds
+const QUEUE_STORAGE_KEY = 'com.respectlytics.eventQueue';
+
+export class EventQueue {
+  private events: Event[] = [];
+  private isOnline = true;
+  private flushTimer: ReturnType<typeof setInterval> | null = null;
+  private networkClient: NetworkClient;
+  private isFlushing = false;
+  private unsubscribeNetInfo: (() => void) | null = null;
+  private appStateSubscription: { remove: () => void } | null = null;
+
+  constructor(networkClient: NetworkClient) {
+    this.networkClient = networkClient;
+  }
+
+  /**
+   * Initialize the queue - load persisted events and set up listeners
+   */
+  async start(): Promise<void> {
+    await this.loadPersistedQueue();
+    this.setupNetworkMonitor();
+    this.setupAppStateMonitor();
+    this.scheduleFlush();
+    console.log('[Respectlytics] ✓ Event queue started');
+  }
+
+  /**
+   * Stop the queue and clean up resources
+   */
+  stop(): void {
+    if (this.flushTimer) {
+      clearInterval(this.flushTimer);
+      this.flushTimer = null;
+    }
+    if (this.unsubscribeNetInfo) {
+      this.unsubscribeNetInfo();
+      this.unsubscribeNetInfo = null;
+    }
+    if (this.appStateSubscription) {
+      this.appStateSubscription.remove();
+      this.appStateSubscription = null;
+    }
+  }
+
+  /**
+   * Add an event to the queue
+   * CRITICAL: Events are persisted IMMEDIATELY before any async operations
+   */
+  async add(event: Event): Promise<void> {
+    this.events.push(event);
+    
+    // IMMEDIATELY persist before any async operations
+    await this.persistQueue();
+    
+    // Check if we should flush
+    if (this.events.length >= MAX_QUEUE_SIZE) {
+      this.flush();
+    }
+  }
+
+  /**
+   * Force flush all queued events
+   */
+  async flush(): Promise<void> {
+    if (this.isFlushing || this.events.length === 0) {
+      return;
+    }
+
+    if (!this.isOnline) {
+      console.log('[Respectlytics] Offline, skipping flush');
+      return;
+    }
+
+    if (!this.networkClient.isConfigured()) {
+      console.log('[Respectlytics] ⚠️ SDK not configured, skipping flush');
+      return;
+    }
+
+    this.isFlushing = true;
+
+    // Take a snapshot of events to send
+    const batch = [...this.events];
+    this.events = [];
+    await this.persistQueue();
+
+    try {
+      await this.networkClient.send(batch);
+      console.log(`[Respectlytics] ✓ Sent ${batch.length} event(s)`);
+    } catch (error) {
+      // Re-add failed events to the front of the queue
+      this.events = [...batch, ...this.events];
+      await this.persistQueue();
+      console.log('[Respectlytics] Failed to send events, will retry later');
+    } finally {
+      this.isFlushing = false;
+    }
+  }
+
+  /**
+   * Get current queue size (for testing)
+   */
+  getQueueSize(): number {
+    return this.events.length;
+  }
+
+  // MARK: - Private Helpers
+
+  private scheduleFlush(): void {
+    if (this.flushTimer) {
+      clearInterval(this.flushTimer);
+    }
+    this.flushTimer = setInterval(() => {
+      this.flush();
+    }, FLUSH_INTERVAL_MS);
+  }
+
+  private setupNetworkMonitor(): void {
+    this.unsubscribeNetInfo = NetInfo.addEventListener((state: NetInfoState) => {
+      const wasOffline = !this.isOnline;
+      this.isOnline = state.isConnected ?? false;
+
+      // If we just came online, try to flush
+      if (wasOffline && this.isOnline) {
+        console.log('[Respectlytics] Network restored, flushing queue');
+        this.flush();
+      }
+    });
+  }
+
+  private setupAppStateMonitor(): void {
+    this.appStateSubscription = AppState.addEventListener(
+      'change',
+      (nextAppState: AppStateStatus) => {
+        // Flush when app goes to background
+        if (nextAppState === 'background' || nextAppState === 'inactive') {
+          this.flush();
+        }
+      }
+    );
+  }
+
+  private async persistQueue(): Promise<void> {
+    try {
+      await Storage.setItem(QUEUE_STORAGE_KEY, JSON.stringify(this.events));
+    } catch (error) {
+      console.log('[Respectlytics] Failed to persist queue:', error);
+    }
+  }
+
+  private async loadPersistedQueue(): Promise<void> {
+    try {
+      const data = await Storage.getItem(QUEUE_STORAGE_KEY);
+      if (data) {
+        const parsed = JSON.parse(data);
+        if (Array.isArray(parsed)) {
+          this.events = parsed;
+          console.log(`[Respectlytics] Loaded ${this.events.length} persisted event(s)`);
+        }
+      }
+    } catch (error) {
+      console.log('[Respectlytics] Failed to load persisted queue:', error);
+      this.events = [];
+    }
+  }
+}

package/src/NetworkClient.ts

@@ -0,0 +1,165 @@
+/**
+ * NetworkClient.ts
+ * Respectlytics React Native SDK
+ * 
+ * Handles HTTP communication with the Respectlytics API.
+ * Copyright (c) 2025 Respectlytics. All rights reserved.
+ */
+
+import { Event } from './types';
+
+const API_ENDPOINT = 'https://respectlytics.com/api/v1/events/';
+const MAX_RETRIES = 3;
+const TIMEOUT_MS = 30000;
+
+export enum NetworkError {
+  NotConfigured = 'NOT_CONFIGURED',
+  InvalidResponse = 'INVALID_RESPONSE',
+  Unauthorized = 'UNAUTHORIZED',
+  BadRequest = 'BAD_REQUEST',
+  RateLimited = 'RATE_LIMITED',
+  ServerError = 'SERVER_ERROR',
+  NetworkError = 'NETWORK_ERROR',
+  Timeout = 'TIMEOUT',
+}
+
+export class NetworkClient {
+  private apiKey: string | null = null;
+
+  /**
+   * Configure the network client with an API key
+   */
+  configure(apiKey: string): void {
+    this.apiKey = apiKey;
+  }
+
+  /**
+   * Check if the client is configured
+   */
+  isConfigured(): boolean {
+    return this.apiKey !== null;
+  }
+
+  /**
+   * Send events to the API
+   */
+  async send(events: Event[]): Promise<void> {
+    if (!this.apiKey) {
+      throw new Error(NetworkError.NotConfigured);
+    }
+
+    for (const event of events) {
+      await this.sendEvent(event, 1);
+    }
+  }
+
+  /**
+   * Send a single event with retry logic
+   */
+  private async sendEvent(event: Event, attempt: number): Promise<void> {
+    if (!this.apiKey) {
+      throw new Error(NetworkError.NotConfigured);
+    }
+
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), TIMEOUT_MS);
+
+    try {
+      const response = await fetch(API_ENDPOINT, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'X-App-Key': this.apiKey,
+        },
+        body: JSON.stringify(this.eventToPayload(event)),
+        signal: controller.signal,
+      });
+
+      clearTimeout(timeoutId);
+
+      if (response.ok) {
+        return; // Success
+      }
+
+      switch (response.status) {
+        case 401:
+          throw new Error(NetworkError.Unauthorized);
+        case 400:
+          throw new Error(NetworkError.BadRequest);
+        case 429:
+          // Rate limited - retry with backoff
+          if (attempt < MAX_RETRIES) {
+            await this.delay(Math.pow(2, attempt) * 1000);
+            return this.sendEvent(event, attempt + 1);
+          }
+          throw new Error(NetworkError.RateLimited);
+        default:
+          if (response.status >= 500) {
+            // Server error - retry with backoff
+            if (attempt < MAX_RETRIES) {
+              await this.delay(Math.pow(2, attempt) * 1000);
+              return this.sendEvent(event, attempt + 1);
+            }
+            throw new Error(NetworkError.ServerError);
+          }
+          throw new Error(NetworkError.InvalidResponse);
+      }
+    } catch (error) {
+      clearTimeout(timeoutId);
+
+      if (error instanceof Error) {
+        // Don't retry auth or bad request errors
+        if (
+          error.message === NetworkError.Unauthorized ||
+          error.message === NetworkError.BadRequest
+        ) {
+          throw error;
+        }
+
+        // Check for abort (timeout)
+        if (error.name === 'AbortError') {
+          if (attempt < MAX_RETRIES) {
+            await this.delay(Math.pow(2, attempt) * 1000);
+            return this.sendEvent(event, attempt + 1);
+          }
+          throw new Error(NetworkError.Timeout);
+        }
+      }
+
+      // Network error - retry with backoff
+      if (attempt < MAX_RETRIES) {
+        await this.delay(Math.pow(2, attempt) * 1000);
+        return this.sendEvent(event, attempt + 1);
+      }
+
+      throw new Error(NetworkError.NetworkError);
+    }
+  }
+
+  /**
+   * Convert Event object to API payload format
+   */
+  private eventToPayload(event: Event): Record<string, unknown> {
+    return {
+      event_name: event.eventName,
+      timestamp: event.timestamp,
+      session_id: event.sessionId,
+      user_id: event.userId || undefined,
+      screen: event.screen || undefined,
+      platform: event.platform,
+      os_version: event.osVersion,
+      app_version: event.appVersion,
+      locale: event.locale,
+      device_type: event.deviceType,
+    };
+  }
+
+  /**
+   * Helper to delay for exponential backoff
+   */
+  private delay(ms: number): Promise<void> {
+    return new Promise(resolve => setTimeout(resolve, ms));
+  }
+}
+
+export const networkClient = new NetworkClient();

package/src/Respectlytics.ts

@@ -0,0 +1,199 @@
+/**
+ * Respectlytics.ts
+ * Respectlytics React Native SDK
+ * 
+ * Main entry point for the SDK.
+ * Copyright (c) 2025 Respectlytics. All rights reserved.
+ */
+
+import { Platform, Dimensions, NativeModules } from 'react-native';
+import { Event } from './types';
+import { SessionManager } from './SessionManager';
+import { UserManager } from './UserManager';
+import { NetworkClient } from './NetworkClient';
+import { EventQueue } from './EventQueue';
+
+/**
+ * Main entry point for the Respectlytics SDK.
+ * 
+ * Usage:
+ * ```typescript
+ * // 1. Configure at app launch
+ * Respectlytics.configure('your-api-key');
+ * 
+ * // 2. Enable user tracking (optional)
+ * Respectlytics.identify();
+ * 
+ * // 3. Track events
+ * Respectlytics.track('purchase');
+ * Respectlytics.track('view_product', 'ProductScreen');
+ * ```
+ */
+class RespectlyticsSDK {
+  private isConfigured = false;
+  private networkClient: NetworkClient;
+  private eventQueue: EventQueue;
+  private sessionManager: SessionManager;
+  private userManager: UserManager;
+
+  constructor() {
+    this.networkClient = new NetworkClient();
+    this.eventQueue = new EventQueue(this.networkClient);
+    this.sessionManager = new SessionManager();
+    this.userManager = new UserManager();
+  }
+
+  /**
+   * Initialize the SDK with your API key.
+   * Call once at app startup.
+   * 
+   * @param apiKey Your Respectlytics API key from the dashboard
+   */
+  configure(apiKey: string): void {
+    if (!apiKey || apiKey.trim() === '') {
+      console.log('[Respectlytics] ⚠️ API key cannot be empty');
+      return;
+    }
+
+    this.networkClient.configure(apiKey);
+    this.eventQueue.start();
+    this.userManager.loadUserId();
+    this.isConfigured = true;
+
+    console.log('[Respectlytics] ✓ SDK configured');
+  }
+
+  /**
+   * Track an event with an optional screen name.
+   * 
+   * The SDK automatically collects privacy-safe metadata:
+   * - timestamp, session_id, platform, os_version, app_version, locale
+   * 
+   * @param eventName Name of the event (e.g., "purchase", "button_clicked")
+   * @param screen Optional screen name where the event occurred
+   */
+  track(eventName: string, screen?: string): void {
+    if (!this.isConfigured) {
+      console.log('[Respectlytics] ⚠️ SDK not configured. Call configure(apiKey) first.');
+      return;
+    }
+
+    if (!eventName || eventName.trim() === '') {
+      console.log('[Respectlytics] ⚠️ Event name cannot be empty');
+      return;
+    }
+
+    if (eventName.length > 100) {
+      console.log('[Respectlytics] ⚠️ Event name too long (max 100 characters)');
+      return;
+    }
+
+    const event = this.createEvent(eventName, screen);
+    this.eventQueue.add(event);
+  }
+
+  /**
+   * Enable cross-session user tracking.
+   * Generates and persists a random user ID that will be included in all subsequent events.
+   * 
+   * Note: User IDs are auto-generated and cannot be overridden. This is by design for privacy.
+   */
+  async identify(): Promise<void> {
+    await this.userManager.identify();
+    console.log('[Respectlytics] ✓ User identified');
+  }
+
+  /**
+   * Clear the user ID.
+   * Call when the user logs out. Subsequent events will be anonymous until identify() is called again.
+   */
+  async reset(): Promise<void> {
+    await this.userManager.reset();
+    console.log('[Respectlytics] ✓ User reset');
+  }
+
+  /**
+   * Force send all queued events immediately.
+   * Rarely needed - the SDK auto-flushes every 30 seconds or when the queue reaches 10 events.
+   */
+  async flush(): Promise<void> {
+    await this.eventQueue.flush();
+  }
+
+  // MARK: - Private Helpers
+
+  private createEvent(eventName: string, screen?: string): Event {
+    const metadata = this.collectMetadata();
+    
+    return {
+      eventName,
+      timestamp: new Date().toISOString(),
+      sessionId: this.sessionManager.getSessionId(),
+      userId: this.userManager.getUserId(),
+      screen: screen || null,
+      ...metadata,
+    };
+  }
+
+  private collectMetadata(): {
+    platform: string;
+    osVersion: string;
+    appVersion: string;
+    locale: string;
+    deviceType: string;
+  } {
+    // Determine platform
+    const platform = Platform.OS === 'ios' ? 'iOS' : 'Android';
+
+    // Get OS version
+    const osVersion = String(Platform.Version);
+
+    // Get app version - try to get from native modules
+    let appVersion = 'unknown';
+    try {
+      // React Native provides app info through different native modules
+      const { PlatformConstants } = NativeModules;
+      if (PlatformConstants?.reactNativeVersion) {
+        // This is React Native version, not app version
+        // App version should come from the host app
+      }
+      // For now, use 'unknown' as we can't reliably get app version without additional dependencies
+      // In a real app, the developer would configure this
+    } catch {
+      appVersion = 'unknown';
+    }
+
+    // Get locale
+    let locale = 'en_US';
+    try {
+      // React Native doesn't expose locale directly, but we can get it from platform
+      if (Platform.OS === 'ios') {
+        locale = NativeModules.SettingsManager?.settings?.AppleLocale || 
+                 NativeModules.SettingsManager?.settings?.AppleLanguages?.[0] || 
+                 'en_US';
+      } else {
+        locale = NativeModules.I18nManager?.localeIdentifier || 'en_US';
+      }
+    } catch {
+      locale = 'en_US';
+    }
+
+    // Determine device type based on screen size
+    const { width, height } = Dimensions.get('window');
+    const minDimension = Math.min(width, height);
+    const deviceType = minDimension >= 600 ? 'tablet' : 'phone';
+
+    return {
+      platform,
+      osVersion,
+      appVersion,
+      locale,
+      deviceType,
+    };
+  }
+}
+
+// Export singleton instance
+const Respectlytics = new RespectlyticsSDK();
+export default Respectlytics;
+export { RespectlyticsSDK };

package/src/SessionManager.ts

@@ -0,0 +1,64 @@
+/**
+ * SessionManager.ts
+ * Respectlytics React Native SDK
+ *
+ * Manages session ID generation and rotation.
+ * Sessions automatically rotate after 30 minutes of inactivity.
+ *
+ * Copyright (c) 2025 Respectlytics. All rights reserved.
+ */
+
+/**
+ * Generate a UUID v4 string
+ */
+function generateUUID(): string {
+  return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (c) => {
+    const r = (Math.random() * 16) | 0;
+    const v = c === 'x' ? r : (r & 0x3) | 0x8;
+    return v.toString(16);
+  });
+}
+
+/**
+ * Manages session ID generation and rotation
+ */
+export class SessionManager {
+  private sessionId: string | null = null;
+  private lastEventTime: number | null = null;
+
+  // 30 minutes in milliseconds
+  private readonly SESSION_TIMEOUT_MS = 30 * 60 * 1000;
+
+  /**
+   * Get current session ID, rotating if necessary.
+   * Session rotates after 30 minutes of inactivity.
+   */
+  getSessionId(): string {
+    const now = Date.now();
+
+    // Check if session expired
+    if (
+      this.lastEventTime !== null &&
+      now - this.lastEventTime > this.SESSION_TIMEOUT_MS
+    ) {
+      // Force new session
+      this.sessionId = null;
+    }
+
+    // Generate new session if needed
+    if (this.sessionId === null) {
+      this.sessionId = this.generateSessionId();
+    }
+
+    this.lastEventTime = now;
+    return this.sessionId;
+  }
+
+  /**
+   * Generate a new session ID (32 lowercase hex characters)
+   * UUID without dashes, all lowercase
+   */
+  private generateSessionId(): string {
+    return generateUUID().toLowerCase().replace(/-/g, '');
+  }
+}

package/src/Storage.ts

@@ -0,0 +1,49 @@
+/**
+ * Storage.ts
+ * Respectlytics React Native SDK
+ *
+ * Wrapper around AsyncStorage for persisting SDK data.
+ *
+ * Copyright (c) 2025 Respectlytics. All rights reserved.
+ */
+
+import AsyncStorage from '@react-native-async-storage/async-storage';
+
+/**
+ * Storage wrapper providing typed access to AsyncStorage
+ */
+export class Storage {
+  /**
+   * Get a string value from storage
+   */
+  static async getItem(key: string): Promise<string | null> {
+    try {
+      return await AsyncStorage.getItem(key);
+    } catch (error) {
+      console.log(`[Respectlytics] Failed to read from storage: ${key}`);
+      return null;
+    }
+  }
+
+  /**
+   * Set a string value in storage
+   */
+  static async setItem(key: string, value: string): Promise<void> {
+    try {
+      await AsyncStorage.setItem(key, value);
+    } catch (error) {
+      console.log(`[Respectlytics] Failed to write to storage: ${key}`);
+    }
+  }
+
+  /**
+   * Remove a value from storage
+   */
+  static async removeItem(key: string): Promise<void> {
+    try {
+      await AsyncStorage.removeItem(key);
+    } catch (error) {
+      console.log(`[Respectlytics] Failed to remove from storage: ${key}`);
+    }
+  }
+}

package/src/UserManager.ts

@@ -0,0 +1,74 @@
+/**
+ * UserManager.ts
+ * Respectlytics React Native SDK
+ *
+ * Manages user ID generation, persistence, and reset.
+ * User IDs are auto-generated and cannot be overridden.
+ * This is by design for maximum privacy.
+ *
+ * Copyright (c) 2025 Respectlytics. All rights reserved.
+ */
+
+import { Storage } from './Storage';
+import { STORAGE_KEYS } from './types';
+
+/**
+ * Manages user ID generation, persistence, and reset
+ */
+export class UserManager {
+  private _userId: string | null = null;
+
+  /**
+   * Current user ID (null if not identified)
+   */
+  getUserId(): string | null {
+    return this._userId;
+  }
+
+  /**
+   * Load any persisted user ID from storage
+   */
+  async loadUserId(): Promise<void> {
+    this._userId = await Storage.getItem(STORAGE_KEYS.USER_ID);
+  }
+
+  /**
+   * Generate or retrieve user ID.
+   * If already identified, returns existing ID.
+   * If not, generates a new ID and persists it.
+   */
+  async identify(): Promise<void> {
+    // Check storage first
+    const stored = await Storage.getItem(STORAGE_KEYS.USER_ID);
+    if (stored) {
+      this._userId = stored;
+      return;
+    }
+
+    // Generate new ID (32 lowercase hex chars)
+    const newId = this.generateUserId();
+    await Storage.setItem(STORAGE_KEYS.USER_ID, newId);
+    this._userId = newId;
+  }
+
+  /**
+   * Clear user ID. Call on logout.
+   */
+  async reset(): Promise<void> {
+    await Storage.removeItem(STORAGE_KEYS.USER_ID);
+    this._userId = null;
+  }
+
+  /**
+   * Generate a new user ID (32 lowercase hex characters)
+   * UUID without dashes, all lowercase
+   */
+  private generateUserId(): string {
+    const uuid = 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (c) => {
+      const r = (Math.random() * 16) | 0;
+      const v = c === 'x' ? r : (r & 0x3) | 0x8;
+      return v.toString(16);
+    });
+    return uuid.toLowerCase().replace(/-/g, '');
+  }
+}

package/src/index.ts

@@ -0,0 +1,15 @@
+/**
+ * Respectlytics React Native SDK
+ * 
+ * Official SDK for privacy-first analytics.
+ * Copyright (c) 2025 Respectlytics. All rights reserved.
+ */
+
+import Respectlytics from './Respectlytics';
+
+// Default export - the main SDK instance
+export default Respectlytics;
+
+// Named exports for advanced usage
+export { RespectlyticsSDK } from './Respectlytics';
+export { Event } from './types';

package/src/types.ts

@@ -0,0 +1,36 @@
+/**
+ * types.ts
+ * Respectlytics React Native SDK
+ *
+ * Copyright (c) 2025 Respectlytics. All rights reserved.
+ * This SDK is provided under a proprietary license.
+ * See LICENSE file for details.
+ */
+
+/**
+ * Represents an analytics event - flat structure matching API payload
+ *
+ * This interface only contains fields accepted by the Respectlytics API.
+ * The API uses a strict allowlist for privacy protection.
+ * Custom properties are NOT supported - this is by design for privacy.
+ */
+export interface Event {
+  eventName: string;
+  timestamp: string;
+  sessionId: string;
+  userId: string | null;
+  screen: string | null;
+  platform: string;
+  osVersion: string;
+  appVersion: string;
+  locale: string;
+  deviceType: string;
+}
+
+/**
+ * Storage keys used by the SDK
+ */
+export const STORAGE_KEYS = {
+  USER_ID: 'com.respectlytics.userId',
+  EVENT_QUEUE: 'com.respectlytics.eventQueue',
+} as const;