@bananalytics/react-native 0.1.0

package/dist/core/client.js

@@ -0,0 +1,283 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BananalyticsClient = void 0;
+const config_1 = require("./config");
+const logger_1 = require("../utils/logger");
+const queue_1 = require("../transport/queue");
+const transport_1 = require("../transport/transport");
+const batcher_1 = require("../transport/batcher");
+const persister_1 = require("../transport/persister");
+const event_builder_1 = require("../tracking/event-builder");
+const user_identity_1 = require("../tracking/user-identity");
+const lifecycle_tracker_1 = require("../tracking/lifecycle-tracker");
+const screen_tracker_1 = require("../tracking/screen-tracker");
+const session_1 = require("../context/session");
+const consent_1 = require("../privacy/consent");
+const device_1 = require("../context/device");
+const app_1 = require("../context/app");
+/**
+ * Main Bananalytics analytics client.
+ * Orchestrates all SDK components: tracking, transport, sessions, and privacy.
+ */
+class BananalyticsClient {
+    constructor(config, asyncStorage) {
+        this.initialized = false;
+        this.deviceContext = (0, device_1.getDeviceContext)();
+        this.appContext = (0, app_1.getAppContext)();
+        this.config = (0, config_1.resolveConfig)(config);
+        this.logger = new logger_1.Logger(this.config.debug);
+        this.persister = new persister_1.Persister(asyncStorage, this.logger);
+        this.queue = new queue_1.EventQueue(this.config.maxQueueSize, this.logger);
+        this.transport = new transport_1.Transport(this.config.endpoint, this.config.apiKey, this.logger);
+        this.batcher = new batcher_1.Batcher(this.queue, this.transport, this.logger, this.config.flushInterval, this.config.flushAt, this.config.maxRetries);
+        this.identity = new user_identity_1.UserIdentity(this.persister, this.logger);
+        this.sessionManager = new session_1.SessionManager(this.config.sessionTimeout, this.persister, this.logger);
+        this.consent = new consent_1.ConsentManager(this.persister, this.logger);
+        this.lifecycleTracker = new lifecycle_tracker_1.LifecycleTracker(this.logger);
+        this.screenTracker = new screen_tracker_1.ScreenTracker(this.logger);
+        this.eventBuilder = new event_builder_1.EventBuilder({
+            getAnonymousId: () => this.identity.getAnonymousId(),
+            getUserId: () => this.identity.getUserId(),
+            getContext: () => this.getContext(),
+        }, this.logger);
+    }
+    /**
+     * 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();
+     * ```
+     */
+    async initialize() {
+        if (this.initialized)
+            return;
+        try {
+            await Promise.all([
+                this.identity.initialize(),
+                this.sessionManager.initialize(),
+                this.consent.initialize(),
+            ]);
+            // Load persisted queue
+            const persistedEvents = await this.persister.loadQueue();
+            if (persistedEvents.length > 0) {
+                this.queue.unshift(persistedEvents);
+                await this.persister.clearQueue();
+                this.logger.debug(`Restored ${persistedEvents.length} persisted events`);
+            }
+            // Set up session callbacks
+            this.sessionManager.setCallbacks((session) => {
+                this.enqueueEvent(this.eventBuilder.track('$session_start', {
+                    session_id: session.id,
+                }));
+            }, (session) => {
+                this.enqueueEvent(this.eventBuilder.track('$session_end', {
+                    session_id: session.id,
+                }));
+            });
+            // Start auto-tracking
+            if (this.config.trackAppLifecycle) {
+                this.lifecycleTracker.start((eventName, props) => this.track(eventName, props), () => { this.flush().catch(() => { }); }, () => { this.persistQueue(); });
+            }
+            this.batcher.start();
+            this.initialized = true;
+            this.logger.debug('Bananalytics SDK initialized');
+        }
+        catch (err) {
+            this.logger.error('Failed to initialize Bananalytics SDK', err);
+        }
+    }
+    /**
+     * 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, properties) {
+        if (this.consent.isOptedOut())
+            return;
+        try {
+            this.sessionManager.getSession(); // ensure active session
+            const payload = this.eventBuilder.track(eventName, properties);
+            this.enqueueEvent(payload);
+        }
+        catch (err) {
+            this.logger.error('Failed to track event', err);
+        }
+    }
+    /**
+     * Tracks a screen view event.
+     *
+     * @param screenName - The name of the screen
+     * @param properties - Optional screen properties
+     *
+     * @example
+     * ```ts
+     * client.screen('HomeScreen');
+     * ```
+     */
+    screen(screenName, properties) {
+        if (this.consent.isOptedOut())
+            return;
+        try {
+            this.sessionManager.getSession();
+            const payload = this.eventBuilder.screen(screenName, properties);
+            this.enqueueEvent(payload);
+        }
+        catch (err) {
+            this.logger.error('Failed to track screen', err);
+        }
+    }
+    /**
+     * Identifies the current user.
+     *
+     * @param userId - The user identifier
+     * @param traits - Optional user traits
+     *
+     * @example
+     * ```ts
+     * client.identify('user-123', { plan: 'pro' });
+     * ```
+     */
+    identify(userId, traits) {
+        if (this.consent.isOptedOut())
+            return;
+        try {
+            this.identity.identify(userId).catch((err) => {
+                this.logger.error('Failed to persist identity', err);
+            });
+            const payload = this.eventBuilder.identify(userId, traits);
+            this.enqueueEvent(payload);
+        }
+        catch (err) {
+            this.logger.error('Failed to identify user', err);
+        }
+    }
+    /**
+     * Clears user identity, generates a new anonymous ID, and clears the queue.
+     *
+     * @example
+     * ```ts
+     * client.reset();
+     * ```
+     */
+    reset() {
+        try {
+            this.identity.reset().catch((err) => {
+                this.logger.error('Failed to persist reset', err);
+            });
+            this.queue.clear();
+            this.persister.clearQueue().catch((err) => {
+                this.logger.error('Failed to clear persisted queue', err);
+            });
+            this.logger.debug('Client reset');
+        }
+        catch (err) {
+            this.logger.error('Failed to reset', err);
+        }
+    }
+    /**
+     * Opts the user into analytics tracking.
+     */
+    optIn() {
+        this.consent.optIn().catch((err) => {
+            this.logger.error('Failed to opt in', err);
+        });
+    }
+    /**
+     * Opts the user out of analytics tracking. Stops all event collection.
+     */
+    optOut() {
+        this.consent.optOut().catch((err) => {
+            this.logger.error('Failed to opt out', err);
+        });
+    }
+    /**
+     * Manually flushes all queued events to the backend.
+     *
+     * @returns Promise that resolves when the flush completes
+     *
+     * @example
+     * ```ts
+     * await client.flush();
+     * ```
+     */
+    async flush() {
+        try {
+            await this.batcher.flush();
+        }
+        catch (err) {
+            this.logger.error('Manual flush failed', err);
+        }
+    }
+    /**
+     * Shuts down the SDK — stops auto-tracking and flushes remaining events.
+     */
+    async shutdown() {
+        this.batcher.stop();
+        this.lifecycleTracker.stop();
+        await this.flush();
+        this.persistQueue();
+    }
+    /** Returns the screen tracker for React Navigation integration. */
+    getScreenTracker() {
+        return this.screenTracker;
+    }
+    getContext() {
+        const session = this.sessionManager.getSession();
+        return {
+            device: this.deviceContext,
+            app: this.appContext,
+            session: {
+                id: session.id,
+                startedAt: session.startedAt,
+            },
+            locale: this.getLocale(),
+            timezone: this.getTimezone(),
+        };
+    }
+    enqueueEvent(payload) {
+        if (payload) {
+            this.batcher.enqueue(payload);
+        }
+    }
+    persistQueue() {
+        const events = this.queue.peek();
+        if (events.length > 0) {
+            this.persister.saveQueue(events).catch((err) => {
+                this.logger.error('Failed to persist queue', err);
+            });
+        }
+    }
+    getLocale() {
+        try {
+            // eslint-disable-next-line @typescript-eslint/no-var-requires -- Runtime require
+            const { NativeModules, Platform } = require('react-native');
+            if (Platform.OS === 'ios') {
+                return (NativeModules.SettingsManager?.settings?.AppleLocale ??
+                    NativeModules.SettingsManager?.settings?.AppleLanguages?.[0] ??
+                    'en');
+            }
+            return NativeModules.I18nManager?.localeIdentifier ?? 'en';
+        }
+        catch {
+            return 'en';
+        }
+    }
+    getTimezone() {
+        try {
+            return Intl.DateTimeFormat().resolvedOptions().timeZone;
+        }
+        catch {
+            return 'UTC';
+        }
+    }
+}
+exports.BananalyticsClient = BananalyticsClient;

package/dist/core/config.d.ts

@@ -0,0 +1,27 @@
+import { BananalyticsConfig } from '../types/config';
+/** Resolved configuration with all defaults applied. */
+export interface ResolvedConfig {
+    apiKey: string;
+    endpoint: string;
+    flushInterval: number;
+    flushAt: number;
+    maxQueueSize: number;
+    maxRetries: number;
+    debug: boolean;
+    trackAppLifecycle: boolean;
+    trackScreens: boolean;
+    sessionTimeout: number;
+}
+/**
+ * Validates and resolves a user-provided config, applying defaults.
+ *
+ * @param config - User-provided configuration
+ * @returns Fully resolved configuration with defaults applied
+ * @throws ConfigError if required fields are missing
+ *
+ * @example
+ * ```ts
+ * const resolved = resolveConfig({ apiKey: 'rk_...', endpoint: 'https://...' });
+ * ```
+ */
+export declare function resolveConfig(config: BananalyticsConfig): ResolvedConfig;

package/dist/core/config.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveConfig = resolveConfig;
+const errors_1 = require("./errors");
+const DEFAULT_FLUSH_INTERVAL = 30000;
+const DEFAULT_FLUSH_AT = 20;
+const DEFAULT_MAX_QUEUE_SIZE = 1000;
+const DEFAULT_MAX_RETRIES = 3;
+const DEFAULT_SESSION_TIMEOUT = 1800000; // 30 minutes
+/**
+ * Validates and resolves a user-provided config, applying defaults.
+ *
+ * @param config - User-provided configuration
+ * @returns Fully resolved configuration with defaults applied
+ * @throws ConfigError if required fields are missing
+ *
+ * @example
+ * ```ts
+ * const resolved = resolveConfig({ apiKey: 'rk_...', endpoint: 'https://...' });
+ * ```
+ */
+function resolveConfig(config) {
+    if (!config.apiKey) {
+        throw new errors_1.ConfigError('apiKey is required');
+    }
+    if (!config.endpoint) {
+        throw new errors_1.ConfigError('endpoint is required');
+    }
+    return {
+        apiKey: config.apiKey,
+        endpoint: config.endpoint.replace(/\/+$/, ''),
+        flushInterval: config.flushInterval ?? DEFAULT_FLUSH_INTERVAL,
+        flushAt: config.flushAt ?? DEFAULT_FLUSH_AT,
+        maxQueueSize: config.maxQueueSize ?? DEFAULT_MAX_QUEUE_SIZE,
+        maxRetries: config.maxRetries ?? DEFAULT_MAX_RETRIES,
+        debug: config.debug ?? false,
+        trackAppLifecycle: config.trackAppLifecycle ?? true,
+        trackScreens: config.trackScreens ?? false,
+        sessionTimeout: config.sessionTimeout ?? DEFAULT_SESSION_TIMEOUT,
+    };
+}

package/dist/core/errors.d.ts

@@ -0,0 +1,19 @@
+/** Base error class for all Bananalytics SDK errors. */
+export declare class BananalyticsError extends Error {
+    constructor(message: string);
+}
+/** Error thrown when a network request fails. */
+export declare class NetworkError extends BananalyticsError {
+    readonly statusCode: number | undefined;
+    constructor(message: string, statusCode?: number);
+    /** Whether the error is retryable (5xx or no status code / network error). */
+    get isRetryable(): boolean;
+}
+/** Error thrown for invalid configuration. */
+export declare class ConfigError extends BananalyticsError {
+    constructor(message: string);
+}
+/** Error thrown for validation failures. */
+export declare class ValidationError extends BananalyticsError {
+    constructor(message: string);
+}

package/dist/core/errors.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ValidationError = exports.ConfigError = exports.NetworkError = exports.BananalyticsError = void 0;
+/** Base error class for all Bananalytics SDK errors. */
+class BananalyticsError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'BananalyticsError';
+    }
+}
+exports.BananalyticsError = BananalyticsError;
+/** Error thrown when a network request fails. */
+class NetworkError extends BananalyticsError {
+    constructor(message, statusCode) {
+        super(message);
+        this.name = 'NetworkError';
+        this.statusCode = statusCode;
+    }
+    /** Whether the error is retryable (5xx or no status code / network error). */
+    get isRetryable() {
+        return this.statusCode === undefined || this.statusCode >= 500;
+    }
+}
+exports.NetworkError = NetworkError;
+/** Error thrown for invalid configuration. */
+class ConfigError extends BananalyticsError {
+    constructor(message) {
+        super(message);
+        this.name = 'ConfigError';
+    }
+}
+exports.ConfigError = ConfigError;
+/** Error thrown for validation failures. */
+class ValidationError extends BananalyticsError {
+    constructor(message) {
+        super(message);
+        this.name = 'ValidationError';
+    }
+}
+exports.ValidationError = ValidationError;

package/dist/hooks/BananalyticsProvider.d.ts

@@ -0,0 +1,22 @@
+import React from 'react';
+import { BananalyticsConfig } from '../types/config';
+import { BananalyticsClient } from '../core/client';
+export declare const BananalyticsContext: React.Context<BananalyticsClient | null>;
+interface BananalyticsProviderProps {
+    config: BananalyticsConfig;
+    children: React.ReactNode;
+}
+/**
+ * React context provider that initializes and provides the Bananalytics client.
+ *
+ * @param props - Provider props with config and children
+ *
+ * @example
+ * ```tsx
+ * <BananalyticsProvider config={{ apiKey: 'rk_...', endpoint: 'https://...' }}>
+ *   <App />
+ * </BananalyticsProvider>
+ * ```
+ */
+export declare function BananalyticsProvider({ config, children }: BananalyticsProviderProps): JSX.Element;
+export {};

package/dist/hooks/BananalyticsProvider.js

@@ -0,0 +1,72 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BananalyticsContext = void 0;
+exports.BananalyticsProvider = BananalyticsProvider;
+const react_1 = __importStar(require("react"));
+const client_1 = require("../core/client");
+// eslint-disable-next-line @typescript-eslint/no-var-requires -- Runtime require for AsyncStorage peer dep
+const AsyncStorage = require('@react-native-async-storage/async-storage').default;
+exports.BananalyticsContext = (0, react_1.createContext)(null);
+/**
+ * React context provider that initializes and provides the Bananalytics client.
+ *
+ * @param props - Provider props with config and children
+ *
+ * @example
+ * ```tsx
+ * <BananalyticsProvider config={{ apiKey: 'rk_...', endpoint: 'https://...' }}>
+ *   <App />
+ * </BananalyticsProvider>
+ * ```
+ */
+function BananalyticsProvider({ config, children }) {
+    const clientRef = (0, react_1.useRef)(null);
+    if (!clientRef.current) {
+        clientRef.current = new client_1.BananalyticsClient(config, AsyncStorage);
+    }
+    (0, react_1.useEffect)(() => {
+        const client = clientRef.current;
+        if (client) {
+            client.initialize().catch((err) => {
+                console.error('[Bananalytics] Failed to initialize:', err);
+            });
+            return () => {
+                client.shutdown().catch(() => { });
+            };
+        }
+    }, []);
+    return (react_1.default.createElement(exports.BananalyticsContext.Provider, { value: clientRef.current }, children));
+}

package/dist/hooks/RochadeProvider.d.ts

@@ -0,0 +1,22 @@
+import React from 'react';
+import { RochadeConfig } from '../types/config';
+import { RochadeClient } from '../core/client';
+export declare const RochadeContext: React.Context<RochadeClient | null>;
+interface RochadeProviderProps {
+    config: RochadeConfig;
+    children: React.ReactNode;
+}
+/**
+ * React context provider that initializes and provides the Rochade client.
+ *
+ * @param props - Provider props with config and children
+ *
+ * @example
+ * ```tsx
+ * <RochadeProvider config={{ apiKey: 'rk_...', endpoint: 'https://...' }}>
+ *   <App />
+ * </RochadeProvider>
+ * ```
+ */
+export declare function RochadeProvider({ config, children }: RochadeProviderProps): JSX.Element;
+export {};

package/dist/hooks/RochadeProvider.js

@@ -0,0 +1,72 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RochadeContext = void 0;
+exports.RochadeProvider = RochadeProvider;
+const react_1 = __importStar(require("react"));
+const client_1 = require("../core/client");
+// eslint-disable-next-line @typescript-eslint/no-var-requires -- Runtime require for AsyncStorage peer dep
+const AsyncStorage = require('@react-native-async-storage/async-storage').default;
+exports.RochadeContext = (0, react_1.createContext)(null);
+/**
+ * React context provider that initializes and provides the Rochade client.
+ *
+ * @param props - Provider props with config and children
+ *
+ * @example
+ * ```tsx
+ * <RochadeProvider config={{ apiKey: 'rk_...', endpoint: 'https://...' }}>
+ *   <App />
+ * </RochadeProvider>
+ * ```
+ */
+function RochadeProvider({ config, children }) {
+    const clientRef = (0, react_1.useRef)(null);
+    if (!clientRef.current) {
+        clientRef.current = new client_1.RochadeClient(config, AsyncStorage);
+    }
+    (0, react_1.useEffect)(() => {
+        const client = clientRef.current;
+        if (client) {
+            client.initialize().catch((err) => {
+                console.error('[Rochade] Failed to initialize:', err);
+            });
+            return () => {
+                client.shutdown().catch(() => { });
+            };
+        }
+    }, []);
+    return (react_1.default.createElement(exports.RochadeContext.Provider, { value: clientRef.current }, children));
+}

package/dist/hooks/useBananalytics.d.ts

@@ -0,0 +1,16 @@
+import { BananalyticsClient } from '../core/client';
+/**
+ * React hook to access the Bananalytics client instance.
+ *
+ * @returns The initialized Bananalytics client
+ * @throws Error if used outside BananalyticsProvider
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const bananalytics = useBananalytics();
+ *   bananalytics.track('button_clicked');
+ * }
+ * ```
+ */
+export declare function useBananalytics(): BananalyticsClient;

package/dist/hooks/useBananalytics.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useBananalytics = useBananalytics;
+const react_1 = require("react");
+const BananalyticsProvider_1 = require("./BananalyticsProvider");
+/**
+ * React hook to access the Bananalytics client instance.
+ *
+ * @returns The initialized Bananalytics client
+ * @throws Error if used outside BananalyticsProvider
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const bananalytics = useBananalytics();
+ *   bananalytics.track('button_clicked');
+ * }
+ * ```
+ */
+function useBananalytics() {
+    const client = (0, react_1.useContext)(BananalyticsProvider_1.BananalyticsContext);
+    if (!client) {
+        throw new Error('useBananalytics must be used within a <BananalyticsProvider>');
+    }
+    return client;
+}

package/dist/hooks/useRochade.d.ts

@@ -0,0 +1,16 @@
+import { RochadeClient } from '../core/client';
+/**
+ * React hook to access the Rochade client instance.
+ *
+ * @returns The initialized Rochade client
+ * @throws Error if used outside RochadeProvider
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const rochade = useRochade();
+ *   rochade.track('button_clicked');
+ * }
+ * ```
+ */
+export declare function useRochade(): RochadeClient;