@bananalytics/react-native 0.1.0

package/dist/hooks/useRochade.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useRochade = useRochade;
+const react_1 = require("react");
+const RochadeProvider_1 = require("./RochadeProvider");
+/**
+ * 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');
+ * }
+ * ```
+ */
+function useRochade() {
+    const client = (0, react_1.useContext)(RochadeProvider_1.RochadeContext);
+    if (!client) {
+        throw new Error('useRochade must be used within a <RochadeProvider>');
+    }
+    return client;
+}

package/dist/hooks/useTrackScreen.d.ts

@@ -0,0 +1,14 @@
+/**
+ * React hook that tracks a screen view when the component mounts.
+ *
+ * @param screenName - The name of the screen to track
+ *
+ * @example
+ * ```tsx
+ * function HomeScreen() {
+ *   useTrackScreen('HomeScreen');
+ *   return <View>...</View>;
+ * }
+ * ```
+ */
+export declare function useTrackScreen(screenName: string): void;

package/dist/hooks/useTrackScreen.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useTrackScreen = useTrackScreen;
+const react_1 = require("react");
+const useBananalytics_1 = require("./useBananalytics");
+/**
+ * React hook that tracks a screen view when the component mounts.
+ *
+ * @param screenName - The name of the screen to track
+ *
+ * @example
+ * ```tsx
+ * function HomeScreen() {
+ *   useTrackScreen('HomeScreen');
+ *   return <View>...</View>;
+ * }
+ * ```
+ */
+function useTrackScreen(screenName) {
+    const client = (0, useBananalytics_1.useBananalytics)();
+    (0, react_1.useEffect)(() => {
+        client.screen(screenName);
+    }, [client, screenName]);
+}

package/dist/index.d.ts

@@ -0,0 +1,61 @@
+export { BananalyticsClient } from './core/client';
+export { BananalyticsProvider } from './hooks/BananalyticsProvider';
+export { useBananalytics } from './hooks/useBananalytics';
+export { useTrackScreen } from './hooks/useTrackScreen';
+export type { BananalyticsConfig } from './types/config';
+export type { EventPayload, EventType, EventContext } from './types/events';
+export type { Properties } from './types/common';
+export { BananalyticsError, NetworkError, ConfigError, ValidationError } from './core/errors';
+import { BananalyticsConfig } from './types/config';
+import { Properties } from './types/common';
+import { AsyncStorageInterface } from './transport/persister';
+/**
+ * Static facade for the BananalyticsSDK.
+ * Provides a singleton interface for imperative usage outside React components.
+ *
+ * @example
+ * ```ts
+ * import { Bananalytics} from '@bananalytics/react-native';
+ *
+ * Bananalytics.init({ apiKey: 'rk_...', endpoint: 'https://...' });
+ * Bananalytics.track('button_clicked', { button: 'signup' });
+ * ```
+ */
+export declare const Bananalytics: {
+    /**
+     * Initializes the SDK with the given configuration.
+     *
+     * @param config - SDK configuration
+     * @param asyncStorage - AsyncStorage implementation (optional, auto-detected)
+     */
+    init(config: BananalyticsConfig, asyncStorage?: AsyncStorageInterface): void;
+    /**
+     * Tracks a custom event.
+     *
+     * @param eventName - The event name
+     * @param properties - Optional event properties
+     */
+    track(eventName: string, properties?: Properties): void;
+    /**
+     * Tracks a screen view.
+     *
+     * @param screenName - The screen name
+     * @param properties - Optional screen properties
+     */
+    screen(screenName: string, properties?: Properties): void;
+    /**
+     * Identifies the current user.
+     *
+     * @param userId - The user identifier
+     * @param traits - Optional user traits
+     */
+    identify(userId: string, traits?: Properties): void;
+    /** Clears user identity and generates a new anonymous ID. */
+    reset(): void;
+    /** Opts the user into tracking. */
+    optIn(): void;
+    /** Opts the user out of tracking. */
+    optOut(): void;
+    /** Manually flushes all queued events. */
+    flush(): Promise<void>;
+};

package/dist/index.js

@@ -0,0 +1,97 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Bananalytics = exports.ValidationError = exports.ConfigError = exports.NetworkError = exports.BananalyticsError = exports.useTrackScreen = exports.useBananalytics = exports.BananalyticsProvider = exports.BananalyticsClient = void 0;
+// Public API exports
+var client_1 = require("./core/client");
+Object.defineProperty(exports, "BananalyticsClient", { enumerable: true, get: function () { return client_1.BananalyticsClient; } });
+var BananalyticsProvider_1 = require("./hooks/BananalyticsProvider");
+Object.defineProperty(exports, "BananalyticsProvider", { enumerable: true, get: function () { return BananalyticsProvider_1.BananalyticsProvider; } });
+var useBananalytics_1 = require("./hooks/useBananalytics");
+Object.defineProperty(exports, "useBananalytics", { enumerable: true, get: function () { return useBananalytics_1.useBananalytics; } });
+var useTrackScreen_1 = require("./hooks/useTrackScreen");
+Object.defineProperty(exports, "useTrackScreen", { enumerable: true, get: function () { return useTrackScreen_1.useTrackScreen; } });
+// Errors
+var errors_1 = require("./core/errors");
+Object.defineProperty(exports, "BananalyticsError", { enumerable: true, get: function () { return errors_1.BananalyticsError; } });
+Object.defineProperty(exports, "NetworkError", { enumerable: true, get: function () { return errors_1.NetworkError; } });
+Object.defineProperty(exports, "ConfigError", { enumerable: true, get: function () { return errors_1.ConfigError; } });
+Object.defineProperty(exports, "ValidationError", { enumerable: true, get: function () { return errors_1.ValidationError; } });
+const client_2 = require("./core/client");
+let instance = null;
+/**
+ * Static facade for the BananalyticsSDK.
+ * Provides a singleton interface for imperative usage outside React components.
+ *
+ * @example
+ * ```ts
+ * import { Bananalytics} from '@bananalytics/react-native';
+ *
+ * Bananalytics.init({ apiKey: 'rk_...', endpoint: 'https://...' });
+ * Bananalytics.track('button_clicked', { button: 'signup' });
+ * ```
+ */
+exports.Bananalytics = {
+    /**
+     * Initializes the SDK with the given configuration.
+     *
+     * @param config - SDK configuration
+     * @param asyncStorage - AsyncStorage implementation (optional, auto-detected)
+     */
+    init(config, asyncStorage) {
+        try {
+            const storage = asyncStorage ??
+                // eslint-disable-next-line @typescript-eslint/no-var-requires -- Auto-detect AsyncStorage
+                require('@react-native-async-storage/async-storage').default;
+            instance = new client_2.BananalyticsClient(config, storage);
+            instance.initialize().catch((err) => {
+                console.error('[Bananalytics] Initialization failed:', err);
+            });
+        }
+        catch (err) {
+            console.error('[Bananalytics] Failed to create client:', err);
+        }
+    },
+    /**
+     * Tracks a custom event.
+     *
+     * @param eventName - The event name
+     * @param properties - Optional event properties
+     */
+    track(eventName, properties) {
+        instance?.track(eventName, properties);
+    },
+    /**
+     * Tracks a screen view.
+     *
+     * @param screenName - The screen name
+     * @param properties - Optional screen properties
+     */
+    screen(screenName, properties) {
+        instance?.screen(screenName, properties);
+    },
+    /**
+     * Identifies the current user.
+     *
+     * @param userId - The user identifier
+     * @param traits - Optional user traits
+     */
+    identify(userId, traits) {
+        instance?.identify(userId, traits);
+    },
+    /** Clears user identity and generates a new anonymous ID. */
+    reset() {
+        instance?.reset();
+    },
+    /** Opts the user into tracking. */
+    optIn() {
+        instance?.optIn();
+    },
+    /** Opts the user out of tracking. */
+    optOut() {
+        instance?.optOut();
+    },
+    /** Manually flushes all queued events. */
+    async flush() {
+        await instance?.flush();
+    },
+};

package/dist/privacy/consent.d.ts

@@ -0,0 +1,39 @@
+import { Logger } from '../utils/logger';
+import { Persister } from '../transport/persister';
+/**
+ * Manages user consent for analytics tracking.
+ */
+export declare class ConsentManager {
+    private optedOut;
+    private readonly persister;
+    private readonly logger;
+    constructor(persister: Persister, logger: Logger);
+    /**
+     * Initializes consent state from persisted storage.
+     */
+    initialize(): Promise<void>;
+    /**
+     * Opts the user into tracking.
+     *
+     * @example
+     * ```ts
+     * consent.optIn();
+     * ```
+     */
+    optIn(): Promise<void>;
+    /**
+     * Opts the user out of tracking. All event tracking stops immediately.
+     *
+     * @example
+     * ```ts
+     * consent.optOut();
+     * ```
+     */
+    optOut(): Promise<void>;
+    /**
+     * Returns whether the user has opted out of tracking.
+     *
+     * @returns true if opted out
+     */
+    isOptedOut(): boolean;
+}

package/dist/privacy/consent.js

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConsentManager = void 0;
+/**
+ * Manages user consent for analytics tracking.
+ */
+class ConsentManager {
+    constructor(persister, logger) {
+        this.optedOut = false;
+        this.persister = persister;
+        this.logger = logger;
+    }
+    /**
+     * Initializes consent state from persisted storage.
+     */
+    async initialize() {
+        this.optedOut = await this.persister.loadOptOut();
+        if (this.optedOut) {
+            this.logger.debug('User is opted out of tracking');
+        }
+    }
+    /**
+     * Opts the user into tracking.
+     *
+     * @example
+     * ```ts
+     * consent.optIn();
+     * ```
+     */
+    async optIn() {
+        this.optedOut = false;
+        await this.persister.saveOptOut(false);
+        this.logger.debug('User opted in to tracking');
+    }
+    /**
+     * Opts the user out of tracking. All event tracking stops immediately.
+     *
+     * @example
+     * ```ts
+     * consent.optOut();
+     * ```
+     */
+    async optOut() {
+        this.optedOut = true;
+        await this.persister.saveOptOut(true);
+        this.logger.debug('User opted out of tracking');
+    }
+    /**
+     * Returns whether the user has opted out of tracking.
+     *
+     * @returns true if opted out
+     */
+    isOptedOut() {
+        return this.optedOut;
+    }
+}
+exports.ConsentManager = ConsentManager;

package/dist/privacy/sanitizer.d.ts

@@ -0,0 +1,16 @@
+import { Properties } from '../types/common';
+/**
+ * Strips properties that look like PII from auto-captured events.
+ * Does NOT strip from user-provided properties (only auto-captured).
+ *
+ * @param properties - The properties to sanitize
+ * @param isAutoCaptured - Whether these are auto-captured (vs user-provided)
+ * @returns Sanitized properties
+ *
+ * @example
+ * ```ts
+ * const clean = sanitizeProperties({ email: 'test@example.com' }, true);
+ * // {} — stripped because auto-captured
+ * ```
+ */
+export declare function sanitizeProperties(properties: Properties, isAutoCaptured: boolean): Properties;

package/dist/privacy/sanitizer.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sanitizeProperties = sanitizeProperties;
+const PII_PATTERNS = [
+    /email/i,
+    /password/i,
+    /ssn/i,
+    /social.?security/i,
+    /credit.?card/i,
+    /phone.?number/i,
+    /passport/i,
+    /driver.?licen[sc]e/i,
+];
+/**
+ * Strips properties that look like PII from auto-captured events.
+ * Does NOT strip from user-provided properties (only auto-captured).
+ *
+ * @param properties - The properties to sanitize
+ * @param isAutoCaptured - Whether these are auto-captured (vs user-provided)
+ * @returns Sanitized properties
+ *
+ * @example
+ * ```ts
+ * const clean = sanitizeProperties({ email: 'test@example.com' }, true);
+ * // {} — stripped because auto-captured
+ * ```
+ */
+function sanitizeProperties(properties, isAutoCaptured) {
+    if (!isAutoCaptured) {
+        return properties;
+    }
+    const sanitized = {};
+    for (const [key, value] of Object.entries(properties)) {
+        const isPII = PII_PATTERNS.some((pattern) => pattern.test(key));
+        if (!isPII) {
+            sanitized[key] = value;
+        }
+    }
+    return sanitized;
+}

package/dist/tracking/event-builder.d.ts

@@ -0,0 +1,47 @@
+import { EventPayload, EventContext } from '../types/events';
+import { Properties } from '../types/common';
+import { Logger } from '../utils/logger';
+/** Dependencies for building events. */
+export interface EventBuilderDeps {
+    getAnonymousId: () => string;
+    getUserId: () => string | null;
+    getContext: () => EventContext;
+}
+/**
+ * Constructs validated event payloads with all required metadata.
+ */
+export declare class EventBuilder {
+    private readonly deps;
+    private readonly logger;
+    constructor(deps: EventBuilderDeps, logger: Logger);
+    /**
+     * Builds a track event payload.
+     *
+     * @param eventName - Name of the event
+     * @param properties - Optional event properties
+     * @returns The event payload, or null if validation fails
+     *
+     * @example
+     * ```ts
+     * const payload = builder.track('button_clicked', { button: 'signup' });
+     * ```
+     */
+    track(eventName: string, properties?: Properties): EventPayload | null;
+    /**
+     * Builds a screen event payload.
+     *
+     * @param screenName - Name of the screen
+     * @param properties - Optional screen properties
+     * @returns The event payload, or null if validation fails
+     */
+    screen(screenName: string, properties?: Properties): EventPayload | null;
+    /**
+     * Builds an identify event payload.
+     *
+     * @param userId - The user identifier
+     * @param traits - Optional user traits
+     * @returns The event payload, or null if validation fails
+     */
+    identify(userId: string, traits?: Properties): EventPayload | null;
+    private build;
+}

package/dist/tracking/event-builder.js

@@ -0,0 +1,73 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EventBuilder = void 0;
+const id_1 = require("../utils/id");
+const time_1 = require("../utils/time");
+const validation_1 = require("../utils/validation");
+/**
+ * Constructs validated event payloads with all required metadata.
+ */
+class EventBuilder {
+    constructor(deps, logger) {
+        this.deps = deps;
+        this.logger = logger;
+    }
+    /**
+     * Builds a track event payload.
+     *
+     * @param eventName - Name of the event
+     * @param properties - Optional event properties
+     * @returns The event payload, or null if validation fails
+     *
+     * @example
+     * ```ts
+     * const payload = builder.track('button_clicked', { button: 'signup' });
+     * ```
+     */
+    track(eventName, properties = {}) {
+        return this.build(eventName, 'track', properties);
+    }
+    /**
+     * Builds a screen event payload.
+     *
+     * @param screenName - Name of the screen
+     * @param properties - Optional screen properties
+     * @returns The event payload, or null if validation fails
+     */
+    screen(screenName, properties = {}) {
+        return this.build('$screen', 'screen', { ...properties, name: screenName });
+    }
+    /**
+     * Builds an identify event payload.
+     *
+     * @param userId - The user identifier
+     * @param traits - Optional user traits
+     * @returns The event payload, or null if validation fails
+     */
+    identify(userId, traits = {}) {
+        return this.build('$identify', 'identify', { ...traits, userId });
+    }
+    build(eventName, type, properties) {
+        const nameError = (0, validation_1.validateEventName)(eventName);
+        if (nameError) {
+            this.logger.warn(`Invalid event: ${nameError}`);
+            return null;
+        }
+        const propsError = (0, validation_1.validateProperties)(properties);
+        if (propsError) {
+            this.logger.warn(`Invalid properties for ${eventName}: ${propsError}`);
+            return null;
+        }
+        return {
+            event: eventName,
+            type,
+            properties,
+            context: this.deps.getContext(),
+            userId: this.deps.getUserId(),
+            anonymousId: this.deps.getAnonymousId(),
+            timestamp: (0, time_1.now)(),
+            messageId: (0, id_1.generateId)(),
+        };
+    }
+}
+exports.EventBuilder = EventBuilder;

package/dist/tracking/lifecycle-tracker.d.ts

@@ -0,0 +1,24 @@
+import { Logger } from '../utils/logger';
+type EventCallback = (eventName: string, properties?: Record<string, unknown>) => void;
+type FlushCallback = () => void;
+type PersistCallback = () => void;
+/**
+ * Tracks app lifecycle events (foreground/background).
+ * Auto-captures $app_foreground and $app_background events.
+ */
+export declare class LifecycleTracker {
+    private readonly logger;
+    private subscription;
+    constructor(logger: Logger);
+    /**
+     * Starts listening for app state changes.
+     *
+     * @param onTrack - Callback to track events
+     * @param onFlush - Callback to flush the queue on background
+     * @param onPersist - Callback to persist the queue on background
+     */
+    start(onTrack: EventCallback, onFlush: FlushCallback, onPersist: PersistCallback): void;
+    /** Stops listening for app state changes. */
+    stop(): void;
+}
+export {};

package/dist/tracking/lifecycle-tracker.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LifecycleTracker = void 0;
+/**
+ * Tracks app lifecycle events (foreground/background).
+ * Auto-captures $app_foreground and $app_background events.
+ */
+class LifecycleTracker {
+    constructor(logger) {
+        this.subscription = null;
+        this.logger = logger;
+    }
+    /**
+     * Starts listening for app state changes.
+     *
+     * @param onTrack - Callback to track events
+     * @param onFlush - Callback to flush the queue on background
+     * @param onPersist - Callback to persist the queue on background
+     */
+    start(onTrack, onFlush, onPersist) {
+        try {
+            // eslint-disable-next-line @typescript-eslint/no-var-requires -- Runtime require for RN module
+            const { AppState } = require('react-native');
+            let currentState = AppState.currentState;
+            this.subscription = AppState.addEventListener('change', (nextState) => {
+                if (currentState === 'background' && nextState === 'active') {
+                    this.logger.debug('App foregrounded');
+                    onTrack('$app_foreground');
+                }
+                else if (currentState === 'active' && nextState === 'background') {
+                    this.logger.debug('App backgrounded');
+                    onTrack('$app_background');
+                    onPersist();
+                    onFlush();
+                }
+                currentState = nextState;
+            });
+        }
+        catch {
+            this.logger.warn('Failed to set up lifecycle tracking (AppState not available)');
+        }
+    }
+    /** Stops listening for app state changes. */
+    stop() {
+        if (this.subscription) {
+            this.subscription.remove();
+            this.subscription = null;
+        }
+    }
+}
+exports.LifecycleTracker = LifecycleTracker;

package/dist/tracking/screen-tracker.d.ts

@@ -0,0 +1,20 @@
+import { Logger } from '../utils/logger';
+type ScreenCallback = (screenName: string, properties?: Record<string, unknown>) => void;
+/**
+ * Integrates with React Navigation to auto-track screen views.
+ * Requires the user to pass their navigation container ref.
+ */
+export declare class ScreenTracker {
+    private readonly logger;
+    private currentScreen;
+    constructor(logger: Logger);
+    /**
+     * Called when a navigation state change occurs.
+     * Determines the current screen name and fires a screen event if it changed.
+     *
+     * @param onScreen - Callback to emit screen events
+     * @param getCurrentRoute - Function that returns the current route name
+     */
+    handleStateChange(onScreen: ScreenCallback, getCurrentRoute: () => string | undefined): void;
+}
+export {};

package/dist/tracking/screen-tracker.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ScreenTracker = void 0;
+/**
+ * Integrates with React Navigation to auto-track screen views.
+ * Requires the user to pass their navigation container ref.
+ */
+class ScreenTracker {
+    constructor(logger) {
+        this.currentScreen = null;
+        this.logger = logger;
+    }
+    /**
+     * Called when a navigation state change occurs.
+     * Determines the current screen name and fires a screen event if it changed.
+     *
+     * @param onScreen - Callback to emit screen events
+     * @param getCurrentRoute - Function that returns the current route name
+     */
+    handleStateChange(onScreen, getCurrentRoute) {
+        try {
+            const routeName = getCurrentRoute();
+            if (routeName && routeName !== this.currentScreen) {
+                this.currentScreen = routeName;
+                this.logger.debug('Screen changed', routeName);
+                onScreen(routeName);
+            }
+        }
+        catch (err) {
+            this.logger.error('Screen tracking error', err);
+        }
+    }
+}
+exports.ScreenTracker = ScreenTracker;

package/dist/tracking/user-identity.d.ts

@@ -0,0 +1,40 @@
+import { Logger } from '../utils/logger';
+import { Persister } from '../transport/persister';
+/**
+ * Manages user identity — anonymous ID, user ID, and identity lifecycle.
+ */
+export declare class UserIdentity {
+    private anonymousId;
+    private userId;
+    private readonly persister;
+    private readonly logger;
+    constructor(persister: Persister, logger: Logger);
+    /**
+     * Initializes identity, loading persisted anonymous and user IDs.
+     */
+    initialize(): Promise<void>;
+    /**
+     * Sets the user ID for all subsequent events.
+     *
+     * @param userId - The user identifier
+     *
+     * @example
+     * ```ts
+     * identity.identify('user-123');
+     * ```
+     */
+    identify(userId: string): Promise<void>;
+    /**
+     * Clears the user ID and generates a new anonymous ID.
+     *
+     * @example
+     * ```ts
+     * identity.reset();
+     * ```
+     */
+    reset(): Promise<void>;
+    /** Returns the current anonymous ID. */
+    getAnonymousId(): string;
+    /** Returns the current user ID, or null if not identified. */
+    getUserId(): string | null;
+}