@bananalytics/react-native 0.1.0

package/dist/tracking/user-identity.js

@@ -0,0 +1,75 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UserIdentity = void 0;
+const id_1 = require("../utils/id");
+/**
+ * Manages user identity — anonymous ID, user ID, and identity lifecycle.
+ */
+class UserIdentity {
+    constructor(persister, logger) {
+        this.userId = null;
+        this.persister = persister;
+        this.logger = logger;
+        this.anonymousId = (0, id_1.generateId)();
+    }
+    /**
+     * Initializes identity, loading persisted anonymous and user IDs.
+     */
+    async initialize() {
+        const storedAnonId = await this.persister.loadAnonymousId();
+        if (storedAnonId) {
+            this.anonymousId = storedAnonId;
+            this.logger.debug('Restored anonymous ID', this.anonymousId);
+        }
+        else {
+            await this.persister.saveAnonymousId(this.anonymousId);
+            this.logger.debug('Generated new anonymous ID', this.anonymousId);
+        }
+        const storedUserId = await this.persister.loadUserId();
+        if (storedUserId) {
+            this.userId = storedUserId;
+            this.logger.debug('Restored user ID', this.userId);
+        }
+    }
+    /**
+     * Sets the user ID for all subsequent events.
+     *
+     * @param userId - The user identifier
+     *
+     * @example
+     * ```ts
+     * identity.identify('user-123');
+     * ```
+     */
+    async identify(userId) {
+        this.userId = userId;
+        await this.persister.saveUserId(userId);
+        this.logger.debug('User identified', userId);
+    }
+    /**
+     * Clears the user ID and generates a new anonymous ID.
+     *
+     * @example
+     * ```ts
+     * identity.reset();
+     * ```
+     */
+    async reset() {
+        this.userId = null;
+        this.anonymousId = (0, id_1.generateId)();
+        await Promise.all([
+            this.persister.saveUserId(null),
+            this.persister.saveAnonymousId(this.anonymousId),
+        ]);
+        this.logger.debug('Identity reset, new anonymous ID', this.anonymousId);
+    }
+    /** Returns the current anonymous ID. */
+    getAnonymousId() {
+        return this.anonymousId;
+    }
+    /** Returns the current user ID, or null if not identified. */
+    getUserId() {
+        return this.userId;
+    }
+}
+exports.UserIdentity = UserIdentity;

package/dist/transport/batcher.d.ts

@@ -0,0 +1,44 @@
+import { EventPayload } from '../types/events';
+import { Logger } from '../utils/logger';
+import { EventQueue } from './queue';
+import { Transport } from './transport';
+/**
+ * Manages automatic batching and flushing of events.
+ * Flushes on a timer interval or when the queue reaches the threshold.
+ */
+export declare class Batcher {
+    private readonly queue;
+    private readonly transport;
+    private readonly logger;
+    private readonly flushInterval;
+    private readonly flushAt;
+    private readonly maxRetries;
+    private timer;
+    private flushing;
+    constructor(queue: EventQueue, transport: Transport, logger: Logger, flushInterval: number, flushAt: number, maxRetries: number);
+    /**
+     * Starts the automatic flush timer.
+     */
+    start(): void;
+    /**
+     * Stops the automatic flush timer.
+     */
+    stop(): void;
+    /**
+     * Adds an event and triggers a flush if the threshold is reached.
+     *
+     * @param event - Event payload to enqueue
+     */
+    enqueue(event: EventPayload): void;
+    /**
+     * Flushes all queued events to the backend.
+     *
+     * @returns Promise that resolves when the flush completes
+     *
+     * @example
+     * ```ts
+     * await batcher.flush();
+     * ```
+     */
+    flush(): Promise<void>;
+}

package/dist/transport/batcher.js

@@ -0,0 +1,91 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Batcher = void 0;
+const network_1 = require("../utils/network");
+const retry_1 = require("./retry");
+/**
+ * Manages automatic batching and flushing of events.
+ * Flushes on a timer interval or when the queue reaches the threshold.
+ */
+class Batcher {
+    constructor(queue, transport, logger, flushInterval, flushAt, maxRetries) {
+        this.timer = null;
+        this.flushing = false;
+        this.queue = queue;
+        this.transport = transport;
+        this.logger = logger;
+        this.flushInterval = flushInterval;
+        this.flushAt = flushAt;
+        this.maxRetries = maxRetries;
+    }
+    /**
+     * Starts the automatic flush timer.
+     */
+    start() {
+        if (this.timer)
+            return;
+        this.timer = setInterval(() => {
+            this.flush().catch((err) => {
+                this.logger.error('Auto-flush failed', err);
+            });
+        }, this.flushInterval);
+    }
+    /**
+     * Stops the automatic flush timer.
+     */
+    stop() {
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+    }
+    /**
+     * Adds an event and triggers a flush if the threshold is reached.
+     *
+     * @param event - Event payload to enqueue
+     */
+    enqueue(event) {
+        this.queue.push(event);
+        if (this.queue.length >= this.flushAt) {
+            this.flush().catch((err) => {
+                this.logger.error('Threshold flush failed', err);
+            });
+        }
+    }
+    /**
+     * Flushes all queued events to the backend.
+     *
+     * @returns Promise that resolves when the flush completes
+     *
+     * @example
+     * ```ts
+     * await batcher.flush();
+     * ```
+     */
+    async flush() {
+        if (this.flushing)
+            return;
+        if (this.queue.length === 0)
+            return;
+        // Skip flush if offline — events stay in queue for next attempt
+        const online = await (0, network_1.isOnline)();
+        if (!online) {
+            this.logger.debug('Skipping flush — device is offline');
+            return;
+        }
+        this.flushing = true;
+        const events = this.queue.flush();
+        try {
+            await (0, retry_1.withRetry)(() => this.transport.send(events), this.maxRetries, this.logger);
+            this.logger.debug(`Flushed ${events.length} events`);
+        }
+        catch (err) {
+            this.logger.error('Flush failed after retries, re-queueing events', err);
+            this.queue.unshift(events);
+        }
+        finally {
+            this.flushing = false;
+        }
+    }
+}
+exports.Batcher = Batcher;

package/dist/transport/persister.d.ts

@@ -0,0 +1,49 @@
+import { EventPayload } from '../types/events';
+import { Logger } from '../utils/logger';
+/** AsyncStorage interface — matches @react-native-async-storage/async-storage. */
+export interface AsyncStorageInterface {
+    getItem(key: string): Promise<string | null>;
+    setItem(key: string, value: string): Promise<void>;
+    removeItem(key: string): Promise<void>;
+}
+/**
+ * Handles persistence of SDK state to AsyncStorage.
+ * Persists the event queue, anonymous ID, user ID, opt-out state, and session.
+ */
+export declare class Persister {
+    private readonly storage;
+    private readonly logger;
+    constructor(storage: AsyncStorageInterface, logger: Logger);
+    /** Maximum bytes to persist in AsyncStorage. Older events are dropped if exceeded. */
+    private static readonly MAX_PERSIST_BYTES;
+    /** Saves the event queue to storage, trimming oldest events if it exceeds the size limit. */
+    saveQueue(events: ReadonlyArray<EventPayload>): Promise<void>;
+    /** Loads the event queue from storage. */
+    loadQueue(): Promise<EventPayload[]>;
+    /** Clears the persisted queue. */
+    clearQueue(): Promise<void>;
+    /** Saves the anonymous ID. */
+    saveAnonymousId(id: string): Promise<void>;
+    /** Loads the anonymous ID. */
+    loadAnonymousId(): Promise<string | null>;
+    /** Saves the user ID. */
+    saveUserId(id: string | null): Promise<void>;
+    /** Loads the user ID. */
+    loadUserId(): Promise<string | null>;
+    /** Saves the opt-out state. */
+    saveOptOut(optedOut: boolean): Promise<void>;
+    /** Loads the opt-out state. */
+    loadOptOut(): Promise<boolean>;
+    /** Saves session state. */
+    saveSession(session: {
+        id: string;
+        startedAt: string;
+        lastActivity: string;
+    }): Promise<void>;
+    /** Loads session state. */
+    loadSession(): Promise<{
+        id: string;
+        startedAt: string;
+        lastActivity: string;
+    } | null>;
+}

package/dist/transport/persister.js

@@ -0,0 +1,148 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Persister = void 0;
+const QUEUE_STORAGE_KEY = '@bananalytics/queue';
+const ANONYMOUS_ID_KEY = '@bananalytics/anonymous_id';
+const USER_ID_KEY = '@bananalytics/user_id';
+const OPT_OUT_KEY = '@bananalytics/opt_out';
+const SESSION_KEY = '@bananalytics/session';
+/**
+ * Handles persistence of SDK state to AsyncStorage.
+ * Persists the event queue, anonymous ID, user ID, opt-out state, and session.
+ */
+class Persister {
+    constructor(storage, logger) {
+        this.storage = storage;
+        this.logger = logger;
+    }
+    /** Saves the event queue to storage, trimming oldest events if it exceeds the size limit. */
+    async saveQueue(events) {
+        try {
+            let toSave = [...events];
+            let serialized = JSON.stringify(toSave);
+            // Drop oldest events until we're under the size limit
+            while (serialized.length > Persister.MAX_PERSIST_BYTES && toSave.length > 0) {
+                const dropped = toSave.length;
+                toSave = toSave.slice(Math.ceil(toSave.length / 2));
+                this.logger.warn(`Persisted queue too large (${serialized.length} bytes), dropped ${dropped - toSave.length} oldest events`);
+                serialized = JSON.stringify(toSave);
+            }
+            await this.storage.setItem(QUEUE_STORAGE_KEY, serialized);
+        }
+        catch (err) {
+            this.logger.error('Failed to persist queue', err);
+        }
+    }
+    /** Loads the event queue from storage. */
+    async loadQueue() {
+        try {
+            const data = await this.storage.getItem(QUEUE_STORAGE_KEY);
+            if (data) {
+                return JSON.parse(data);
+            }
+        }
+        catch (err) {
+            this.logger.error('Failed to load persisted queue', err);
+        }
+        return [];
+    }
+    /** Clears the persisted queue. */
+    async clearQueue() {
+        try {
+            await this.storage.removeItem(QUEUE_STORAGE_KEY);
+        }
+        catch (err) {
+            this.logger.error('Failed to clear persisted queue', err);
+        }
+    }
+    /** Saves the anonymous ID. */
+    async saveAnonymousId(id) {
+        try {
+            await this.storage.setItem(ANONYMOUS_ID_KEY, id);
+        }
+        catch (err) {
+            this.logger.error('Failed to persist anonymous ID', err);
+        }
+    }
+    /** Loads the anonymous ID. */
+    async loadAnonymousId() {
+        try {
+            return await this.storage.getItem(ANONYMOUS_ID_KEY);
+        }
+        catch (err) {
+            this.logger.error('Failed to load anonymous ID', err);
+            return null;
+        }
+    }
+    /** Saves the user ID. */
+    async saveUserId(id) {
+        try {
+            if (id === null) {
+                await this.storage.removeItem(USER_ID_KEY);
+            }
+            else {
+                await this.storage.setItem(USER_ID_KEY, id);
+            }
+        }
+        catch (err) {
+            this.logger.error('Failed to persist user ID', err);
+        }
+    }
+    /** Loads the user ID. */
+    async loadUserId() {
+        try {
+            return await this.storage.getItem(USER_ID_KEY);
+        }
+        catch (err) {
+            this.logger.error('Failed to load user ID', err);
+            return null;
+        }
+    }
+    /** Saves the opt-out state. */
+    async saveOptOut(optedOut) {
+        try {
+            await this.storage.setItem(OPT_OUT_KEY, JSON.stringify(optedOut));
+        }
+        catch (err) {
+            this.logger.error('Failed to persist opt-out state', err);
+        }
+    }
+    /** Loads the opt-out state. */
+    async loadOptOut() {
+        try {
+            const data = await this.storage.getItem(OPT_OUT_KEY);
+            if (data !== null) {
+                return JSON.parse(data);
+            }
+        }
+        catch (err) {
+            this.logger.error('Failed to load opt-out state', err);
+        }
+        return false;
+    }
+    /** Saves session state. */
+    async saveSession(session) {
+        try {
+            await this.storage.setItem(SESSION_KEY, JSON.stringify(session));
+        }
+        catch (err) {
+            this.logger.error('Failed to persist session', err);
+        }
+    }
+    /** Loads session state. */
+    async loadSession() {
+        try {
+            const data = await this.storage.getItem(SESSION_KEY);
+            if (data) {
+                return JSON.parse(data);
+            }
+        }
+        catch (err) {
+            this.logger.error('Failed to load session', err);
+        }
+        return null;
+    }
+}
+exports.Persister = Persister;
+/** Maximum bytes to persist in AsyncStorage. Older events are dropped if exceeded. */
+Persister.MAX_PERSIST_BYTES = 512 * 1024; // 512KB

package/dist/transport/queue.d.ts

@@ -0,0 +1,41 @@
+import { EventPayload } from '../types/events';
+import { Logger } from '../utils/logger';
+/**
+ * In-memory event queue with a configurable max size.
+ * Events exceeding the max size are dropped (oldest first).
+ */
+export declare class EventQueue {
+    private items;
+    private readonly maxSize;
+    private readonly logger;
+    constructor(maxSize: number, logger: Logger);
+    /**
+     * Adds an event to the queue.
+     *
+     * @param event - The event payload to enqueue
+     *
+     * @example
+     * ```ts
+     * queue.push(eventPayload);
+     * ```
+     */
+    push(event: EventPayload): void;
+    /**
+     * Adds events to the front of the queue (used for retry).
+     *
+     * @param events - Events to prepend
+     */
+    unshift(events: EventPayload[]): void;
+    /**
+     * Takes all events from the queue, clearing it.
+     *
+     * @returns All queued events
+     */
+    flush(): EventPayload[];
+    /** Returns the current number of events in the queue. */
+    get length(): number;
+    /** Returns all events without removing them. */
+    peek(): ReadonlyArray<EventPayload>;
+    /** Clears all events from the queue. */
+    clear(): void;
+}

package/dist/transport/queue.js

@@ -0,0 +1,67 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EventQueue = void 0;
+/**
+ * In-memory event queue with a configurable max size.
+ * Events exceeding the max size are dropped (oldest first).
+ */
+class EventQueue {
+    constructor(maxSize, logger) {
+        this.items = [];
+        this.maxSize = maxSize;
+        this.logger = logger;
+    }
+    /**
+     * Adds an event to the queue.
+     *
+     * @param event - The event payload to enqueue
+     *
+     * @example
+     * ```ts
+     * queue.push(eventPayload);
+     * ```
+     */
+    push(event) {
+        if (this.items.length >= this.maxSize) {
+            this.items.shift();
+            this.logger.warn(`Queue full (max ${this.maxSize}), dropping oldest event`);
+        }
+        this.items.push(event);
+    }
+    /**
+     * Adds events to the front of the queue (used for retry).
+     *
+     * @param events - Events to prepend
+     */
+    unshift(events) {
+        const available = this.maxSize - this.items.length;
+        const toAdd = events.slice(0, available);
+        this.items.unshift(...toAdd);
+        if (events.length > available) {
+            this.logger.warn(`Dropped ${events.length - available} events during retry (queue full)`);
+        }
+    }
+    /**
+     * Takes all events from the queue, clearing it.
+     *
+     * @returns All queued events
+     */
+    flush() {
+        const events = this.items;
+        this.items = [];
+        return events;
+    }
+    /** Returns the current number of events in the queue. */
+    get length() {
+        return this.items.length;
+    }
+    /** Returns all events without removing them. */
+    peek() {
+        return this.items;
+    }
+    /** Clears all events from the queue. */
+    clear() {
+        this.items = [];
+    }
+}
+exports.EventQueue = EventQueue;

package/dist/transport/retry.d.ts

@@ -0,0 +1,15 @@
+import { Logger } from '../utils/logger';
+/**
+ * Executes a function with exponential backoff retry logic.
+ *
+ * @param fn - The async function to retry
+ * @param maxRetries - Maximum number of retry attempts
+ * @param logger - Logger instance
+ * @returns The result of the function if successful
+ *
+ * @example
+ * ```ts
+ * await withRetry(() => transport.send(events), 3, logger);
+ * ```
+ */
+export declare function withRetry(fn: () => Promise<void>, maxRetries: number, logger: Logger): Promise<void>;

package/dist/transport/retry.js

@@ -0,0 +1,52 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withRetry = withRetry;
+const errors_1 = require("../core/errors");
+const BASE_DELAY_MS = 1000;
+/**
+ * Executes a function with exponential backoff retry logic.
+ *
+ * @param fn - The async function to retry
+ * @param maxRetries - Maximum number of retry attempts
+ * @param logger - Logger instance
+ * @returns The result of the function if successful
+ *
+ * @example
+ * ```ts
+ * await withRetry(() => transport.send(events), 3, logger);
+ * ```
+ */
+async function withRetry(fn, maxRetries, logger) {
+    let lastError;
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+        try {
+            await fn();
+            return;
+        }
+        catch (err) {
+            lastError = err instanceof Error ? err : new Error(String(err));
+            // Don't retry client errors (400, 401, 403)
+            if (err instanceof errors_1.NetworkError && !err.isRetryable) {
+                logger.warn(`Non-retryable error (status ${err.statusCode}), dropping events: ${err.message}`);
+                return;
+            }
+            if (attempt < maxRetries) {
+                const delay = addJitter(BASE_DELAY_MS * Math.pow(2, attempt));
+                logger.debug(`Retry attempt ${attempt + 1}/${maxRetries} in ${delay}ms`);
+                await sleep(delay);
+            }
+        }
+    }
+    throw lastError;
+}
+/**
+ * Adds random jitter (0-50% of base) to prevent thundering herd.
+ * When many clients retry at the same time after an outage,
+ * jitter spreads them out so the server isn't overwhelmed.
+ */
+function addJitter(baseMs) {
+    return Math.floor(baseMs + Math.random() * baseMs * 0.5);
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/dist/transport/transport.d.ts

@@ -0,0 +1,23 @@
+import { EventPayload } from '../types/events';
+import { Logger } from '../utils/logger';
+/**
+ * HTTP transport that sends event batches to the ingestion endpoint.
+ */
+export declare class Transport {
+    private readonly endpoint;
+    private readonly apiKey;
+    private readonly logger;
+    constructor(endpoint: string, apiKey: string, logger: Logger);
+    /**
+     * Sends a batch of events to the ingestion endpoint.
+     *
+     * @param events - Array of event payloads to send
+     * @throws NetworkError on failure
+     *
+     * @example
+     * ```ts
+     * await transport.send(eventBatch);
+     * ```
+     */
+    send(events: EventPayload[]): Promise<void>;
+}

package/dist/transport/transport.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Transport = void 0;
+const errors_1 = require("../core/errors");
+/**
+ * HTTP transport that sends event batches to the ingestion endpoint.
+ */
+class Transport {
+    constructor(endpoint, apiKey, logger) {
+        this.endpoint = endpoint;
+        this.apiKey = apiKey;
+        this.logger = logger;
+    }
+    /**
+     * Sends a batch of events to the ingestion endpoint.
+     *
+     * @param events - Array of event payloads to send
+     * @throws NetworkError on failure
+     *
+     * @example
+     * ```ts
+     * await transport.send(eventBatch);
+     * ```
+     */
+    async send(events) {
+        const url = `${this.endpoint}/v1/ingest`;
+        const body = JSON.stringify({ batch: events });
+        this.logger.debug(`Sending ${events.length} events to ${url}`);
+        try {
+            const response = await fetch(url, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    'Authorization': `Bearer ${this.apiKey}`,
+                },
+                body,
+            });
+            if (!response.ok) {
+                throw new errors_1.NetworkError(`Ingestion failed with status ${response.status}`, response.status);
+            }
+            this.logger.debug(`Successfully sent ${events.length} events`);
+        }
+        catch (err) {
+            if (err instanceof errors_1.NetworkError) {
+                throw err;
+            }
+            throw new errors_1.NetworkError(`Network request failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+}
+exports.Transport = Transport;

package/dist/types/common.d.ts

@@ -0,0 +1,6 @@
+/** Generic properties map for event data. */
+export type Properties = Record<string, unknown>;
+/** ISO 8601 timestamp string. */
+export type Timestamp = string;
+/** UUID v4 string identifier. */
+export type UUID = string;

package/dist/types/common.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });