@bananalytics/react-native 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Bananalytics
+
+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

@@ -0,0 +1,93 @@
+# @bananalytics/react-native
+
+Self-hosted analytics SDK for React Native apps. Track events, identify users, and auto-capture lifecycle data.
+
+## Installation
+
+```bash
+npm install @bananalytics/react-native uuid
+npm install @react-native-async-storage/async-storage
+```
+
+## Quick Start
+
+### Imperative API
+
+```typescript
+import { Bananalytics } from '@bananalytics/react-native';
+
+Bananalytics.init({
+  apiKey: 'rk_your_write_key',
+  endpoint: 'https://your-server.com',
+});
+
+Bananalytics.track('button_clicked', { button: 'signup' });
+Bananalytics.identify('user-123', { plan: 'pro' });
+Bananalytics.screen('HomeScreen');
+```
+
+### React Provider
+
+```tsx
+import { BananalyticsProvider, useBananalytics, useTrackScreen } from '@bananalytics/react-native';
+
+function App() {
+  return (
+    <BananalyticsProvider config={{ apiKey: 'rk_...', endpoint: 'https://...' }}>
+      <HomeScreen />
+    </BananalyticsProvider>
+  );
+}
+
+function HomeScreen() {
+  useTrackScreen('HomeScreen');
+  const bananalytics = useBananalytics();
+
+  return (
+    <Button onPress={() => bananalytics.track('button_clicked')} title="Click me" />
+  );
+}
+```
+
+## Configuration
+
+```typescript
+interface BananalyticsConfig {
+  apiKey: string;           // Write-only public key (required)
+  endpoint: string;         // Ingestion API URL (required)
+  flushInterval?: number;   // ms between auto-flushes (default: 30000)
+  flushAt?: number;         // Events before auto-flush (default: 20)
+  maxQueueSize?: number;    // Max events in memory (default: 1000)
+  maxRetries?: number;      // Retry attempts (default: 3)
+  debug?: boolean;          // Enable console logging (default: false)
+  trackAppLifecycle?: boolean; // Auto-track foreground/background (default: true)
+  trackScreens?: boolean;   // Auto-track screen views (default: false)
+  sessionTimeout?: number;  // Session timeout in ms (default: 1800000)
+}
+```
+
+## API
+
+| Method | Description |
+|---|---|
+| `Bananalytics.init(config)` | Initialize the SDK |
+| `Bananalytics.track(event, properties?)` | Track a custom event |
+| `Bananalytics.screen(name, properties?)` | Track a screen view |
+| `Bananalytics.identify(userId, traits?)` | Identify the current user |
+| `Bananalytics.reset()` | Clear identity and generate new anonymous ID |
+| `Bananalytics.optIn()` | Resume tracking |
+| `Bananalytics.optOut()` | Stop all tracking |
+| `Bananalytics.flush()` | Manually flush queued events |
+
+## Features
+
+- Automatic event batching and flushing
+- Offline persistence with AsyncStorage
+- Exponential backoff retry on network failures
+- Session tracking with configurable timeout
+- Privacy controls (opt-in/opt-out)
+- Zero uncaught exceptions (host app stability is sacred)
+
+## License
+
+MIT

package/dist/context/app.d.ts

@@ -0,0 +1,12 @@
+import { AppContext } from '../types/events';
+/**
+ * Collects application information.
+ *
+ * @returns App context object
+ *
+ * @example
+ * ```ts
+ * const app = getAppContext();
+ * ```
+ */
+export declare function getAppContext(): AppContext;

package/dist/context/app.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getAppContext = getAppContext;
+/**
+ * Collects application information.
+ *
+ * @returns App context object
+ *
+ * @example
+ * ```ts
+ * const app = getAppContext();
+ * ```
+ */
+function getAppContext() {
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-var-requires -- React Native module must be required at runtime
+        const { Platform } = require('react-native');
+        const constants = Platform.constants ?? {};
+        return {
+            name: constants.appName ?? 'unknown',
+            version: constants.appVersion ?? 'unknown',
+            build: constants.buildNumber ?? 'unknown',
+            bundleId: constants.bundleIdentifier ?? 'unknown',
+        };
+    }
+    catch {
+        return {
+            name: 'unknown',
+            version: 'unknown',
+            build: 'unknown',
+            bundleId: 'unknown',
+        };
+    }
+}

package/dist/context/device.d.ts

@@ -0,0 +1,12 @@
+import { DeviceContext } from '../types/events';
+/**
+ * Collects device information from the React Native platform.
+ *
+ * @returns Device context object
+ *
+ * @example
+ * ```ts
+ * const device = getDeviceContext();
+ * ```
+ */
+export declare function getDeviceContext(): DeviceContext;

package/dist/context/device.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getDeviceContext = getDeviceContext;
+/**
+ * Collects device information from the React Native platform.
+ *
+ * @returns Device context object
+ *
+ * @example
+ * ```ts
+ * const device = getDeviceContext();
+ * ```
+ */
+function getDeviceContext() {
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-var-requires -- React Native module must be required at runtime
+        const { Platform, Dimensions } = require('react-native');
+        const { width, height } = Dimensions.get('window');
+        return {
+            os: Platform.OS,
+            osVersion: String(Platform.Version),
+            model: Platform.constants?.Model ?? 'unknown',
+            manufacturer: Platform.constants?.Manufacturer ?? 'unknown',
+            screenWidth: width,
+            screenHeight: height,
+        };
+    }
+    catch {
+        return {
+            os: 'unknown',
+            osVersion: 'unknown',
+            model: 'unknown',
+            manufacturer: 'unknown',
+            screenWidth: 0,
+            screenHeight: 0,
+        };
+    }
+}

package/dist/context/session.d.ts

@@ -0,0 +1,49 @@
+import { Logger } from '../utils/logger';
+import { Persister } from '../transport/persister';
+/** Session state tracked across app lifecycle. */
+export interface SessionState {
+    id: string;
+    startedAt: string;
+    lastActivity: string;
+}
+/**
+ * Manages user sessions with inactivity timeout.
+ * Generates session IDs and emits session start/end events.
+ */
+export declare class SessionManager {
+    private session;
+    private readonly timeout;
+    private readonly logger;
+    private readonly persister;
+    private onSessionStart;
+    private onSessionEnd;
+    constructor(timeout: number, persister: Persister, logger: Logger);
+    /**
+     * Sets callbacks for session lifecycle events.
+     *
+     * @param onStart - Called when a new session starts
+     * @param onEnd - Called when a session ends
+     */
+    setCallbacks(onStart: (session: SessionState) => void, onEnd: (session: SessionState) => void): void;
+    /**
+     * Initializes the session manager, loading persisted state.
+     */
+    initialize(): Promise<void>;
+    /**
+     * Gets the current session, creating a new one if needed.
+     *
+     * @returns The current session state
+     *
+     * @example
+     * ```ts
+     * const session = sessionManager.getSession();
+     * ```
+     */
+    getSession(): SessionState;
+    /** Returns the current session ID, or null if no active session. */
+    getSessionId(): string | null;
+    /** Ends the current session. */
+    endSession(): void;
+    private startNewSession;
+    private persistSession;
+}

package/dist/context/session.js

@@ -0,0 +1,99 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SessionManager = void 0;
+const id_1 = require("../utils/id");
+const time_1 = require("../utils/time");
+/**
+ * Manages user sessions with inactivity timeout.
+ * Generates session IDs and emits session start/end events.
+ */
+class SessionManager {
+    constructor(timeout, persister, logger) {
+        this.session = null;
+        this.onSessionStart = null;
+        this.onSessionEnd = null;
+        this.timeout = timeout;
+        this.persister = persister;
+        this.logger = logger;
+    }
+    /**
+     * Sets callbacks for session lifecycle events.
+     *
+     * @param onStart - Called when a new session starts
+     * @param onEnd - Called when a session ends
+     */
+    setCallbacks(onStart, onEnd) {
+        this.onSessionStart = onStart;
+        this.onSessionEnd = onEnd;
+    }
+    /**
+     * Initializes the session manager, loading persisted state.
+     */
+    async initialize() {
+        const persisted = await this.persister.loadSession();
+        if (persisted) {
+            this.session = persisted;
+            this.logger.debug('Restored session', this.session.id);
+        }
+    }
+    /**
+     * Gets the current session, creating a new one if needed.
+     *
+     * @returns The current session state
+     *
+     * @example
+     * ```ts
+     * const session = sessionManager.getSession();
+     * ```
+     */
+    getSession() {
+        const currentTime = (0, time_1.now)();
+        if (this.session) {
+            const lastActivity = new Date(this.session.lastActivity).getTime();
+            const elapsed = Date.now() - lastActivity;
+            if (elapsed > this.timeout) {
+                this.endSession();
+                return this.startNewSession(currentTime);
+            }
+            this.session.lastActivity = currentTime;
+            this.persistSession();
+            return this.session;
+        }
+        return this.startNewSession(currentTime);
+    }
+    /** Returns the current session ID, or null if no active session. */
+    getSessionId() {
+        return this.session?.id ?? null;
+    }
+    /** Ends the current session. */
+    endSession() {
+        if (this.session) {
+            this.logger.debug('Session ended', this.session.id);
+            if (this.onSessionEnd) {
+                this.onSessionEnd(this.session);
+            }
+            this.session = null;
+        }
+    }
+    startNewSession(timestamp) {
+        this.session = {
+            id: (0, id_1.generateId)(),
+            startedAt: timestamp,
+            lastActivity: timestamp,
+        };
+        this.logger.debug('New session started', this.session.id);
+        this.persistSession();
+        if (this.onSessionStart) {
+            this.onSessionStart(this.session);
+        }
+        return this.session;
+    }
+    persistSession() {
+        if (this.session) {
+            this.persister.saveSession(this.session).catch((err) => {
+                this.logger.error('Failed to persist session', err);
+            });
+        }
+    }
+}
+exports.SessionManager = SessionManager;

package/dist/core/client.d.ts

@@ -0,0 +1,112 @@
+import { BananalyticsConfig } from '../types/config';
+import { Properties } from '../types/common';
+import { AsyncStorageInterface } from '../transport/persister';
+import { ScreenTracker } from '../tracking/screen-tracker';
+/**
+ * Main Bananalytics analytics client.
+ * Orchestrates all SDK components: tracking, transport, sessions, and privacy.
+ */
+export declare class BananalyticsClient {
+    private config;
+    private logger;
+    private queue;
+    private transport;
+    private batcher;
+    private persister;
+    private identity;
+    private eventBuilder;
+    private sessionManager;
+    private lifecycleTracker;
+    private screenTracker;
+    private consent;
+    private initialized;
+    private deviceContext;
+    private appContext;
+    constructor(config: BananalyticsConfig, asyncStorage: AsyncStorageInterface);
+    /**
+     * Initializes the SDK — loads persisted state and starts auto-tracking.
+     * Must be called before any tracking methods.
+     *
+     * @example
+     * ```ts
+     * const client = new BananalyticsClient(config, AsyncStorage);
+     * await client.initialize();
+     * ```
+     */
+    initialize(): Promise<void>;
+    /**
+     * Tracks a custom event.
+     *
+     * @param eventName - The name of the event
+     * @param properties - Optional event properties
+     *
+     * @example
+     * ```ts
+     * client.track('button_clicked', { button: 'signup' });
+     * ```
+     */
+    track(eventName: string, properties?: Properties): void;
+    /**
+     * Tracks a screen view event.
+     *
+     * @param screenName - The name of the screen
+     * @param properties - Optional screen properties
+     *
+     * @example
+     * ```ts
+     * client.screen('HomeScreen');
+     * ```
+     */
+    screen(screenName: string, properties?: Properties): void;
+    /**
+     * Identifies the current user.
+     *
+     * @param userId - The user identifier
+     * @param traits - Optional user traits
+     *
+     * @example
+     * ```ts
+     * client.identify('user-123', { plan: 'pro' });
+     * ```
+     */
+    identify(userId: string, traits?: Properties): void;
+    /**
+     * Clears user identity, generates a new anonymous ID, and clears the queue.
+     *
+     * @example
+     * ```ts
+     * client.reset();
+     * ```
+     */
+    reset(): void;
+    /**
+     * Opts the user into analytics tracking.
+     */
+    optIn(): void;
+    /**
+     * Opts the user out of analytics tracking. Stops all event collection.
+     */
+    optOut(): void;
+    /**
+     * Manually flushes all queued events to the backend.
+     *
+     * @returns Promise that resolves when the flush completes
+     *
+     * @example
+     * ```ts
+     * await client.flush();
+     * ```
+     */
+    flush(): Promise<void>;
+    /**
+     * Shuts down the SDK — stops auto-tracking and flushes remaining events.
+     */
+    shutdown(): Promise<void>;
+    /** Returns the screen tracker for React Navigation integration. */
+    getScreenTracker(): ScreenTracker;
+    private getContext;
+    private enqueueEvent;
+    private persistQueue;
+    private getLocale;
+    private getTimezone;
+}