@axyle/expo-sdk 1.0.0

package/dist/client.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Main Axyle client
+ * Public API surface for the SDK
+ */
+import { SessionAnalyticsStats } from "./sessionAnalytics";
+import { AnalyticsEvent, AxyleInitConfig, EventProperties, UserTraits } from "./types";
+export declare class AxyleClient {
+    private config;
+    private logger;
+    private sessionManager;
+    private sessionAnalytics;
+    private transport;
+    private queue;
+    private anonymousId;
+    private userId;
+    private _isInitialized;
+    private isOptedOut;
+    private appStateSubscription;
+    /**
+     * Check if SDK is initialized (public getter)
+     */
+    get isInitialized(): boolean;
+    constructor();
+    /**
+     * Initialize the SDK
+     * Only accepts API key - all other settings use defaults
+     */
+    init(config: AxyleInitConfig): Promise<void>;
+    /**
+     * Track a custom event
+     */
+    track(eventName: string, properties?: EventProperties): Promise<void>;
+    /**
+     * Identify a user
+     */
+    identify(userId: string, traits?: UserTraits): Promise<void>;
+    /**
+     * Reset user data (logout)
+     */
+    reset(): Promise<void>;
+    /**
+     * Opt out of tracking
+     */
+    optOut(): Promise<void>;
+    /**
+     * Opt back in to tracking
+     */
+    optIn(): Promise<void>;
+    /**
+     * Delete user data
+     */
+    deleteUser(userId: string): Promise<void>;
+    /**
+     * Get session analytics statistics
+     */
+    getSessionStats(): SessionAnalyticsStats | null;
+    /**
+     * Get all events in current session
+     */
+    getSessionEvents(): AnalyticsEvent[];
+    /**
+     * Get events by type in current session
+     */
+    getEventsByType(eventName: string): AnalyticsEvent[];
+    /**
+     * Create an event object
+     */
+    private createEvent;
+    /**
+     * Track an auto event
+     */
+    private trackAutoEvent;
+    /**
+     * Handle session start
+     */
+    private handleSessionStart;
+    /**
+     * Handle session end
+     */
+    private handleSessionEnd;
+    /**
+     * Set up app state listener for background/foreground tracking
+     */
+    private setupAppStateListener;
+    /**
+     * Manually flush all queued events to the server
+     */
+    flush(): Promise<void>;
+    /**
+     * Cleanup resources
+     */
+    shutdown(): Promise<void>;
+}

package/dist/client.js

@@ -0,0 +1,416 @@
+"use strict";
+/**
+ * Main Axyle client
+ * Public API surface for the SDK
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AxyleClient = void 0;
+const react_native_1 = require("react-native");
+const constants_1 = require("./constants");
+const context_1 = require("./context");
+const queue_1 = require("./queue");
+const session_1 = require("./session");
+const sessionAnalytics_1 = require("./sessionAnalytics");
+const storage_1 = require("./storage");
+const transport_1 = require("./transport");
+const utils_1 = require("./utils");
+class AxyleClient {
+    /**
+     * Check if SDK is initialized (public getter)
+     */
+    get isInitialized() {
+        return this._isInitialized;
+    }
+    constructor() {
+        this.sessionAnalytics = null;
+        this.transport = null;
+        this.queue = null;
+        this.anonymousId = "";
+        this.userId = null;
+        this._isInitialized = false;
+        this.isOptedOut = false;
+        this.appStateSubscription = null;
+        // Initialize with defaults, will be overridden in init()
+        this.config = {
+            apiKey: "",
+            environment: constants_1.DEFAULT_CONFIG.environment,
+            baseUrl: constants_1.DEFAULT_CONFIG.baseUrl,
+            debug: constants_1.DEFAULT_CONFIG.debug,
+            maxQueueSize: constants_1.DEFAULT_CONFIG.maxQueueSize,
+            flushInterval: constants_1.DEFAULT_CONFIG.flushInterval,
+            sessionTimeout: constants_1.DEFAULT_CONFIG.sessionTimeout,
+            userId: "",
+        };
+        this.logger = (0, utils_1.createLogger)(this.config.debug);
+        this.sessionManager = new session_1.SessionManager(this.config.sessionTimeout, this.logger, {
+            onSessionStart: (sessionId) => this.handleSessionStart(sessionId),
+            onSessionEnd: (sessionId, duration) => this.handleSessionEnd(sessionId, duration),
+        });
+    }
+    /**
+     * Initialize the SDK
+     * Only accepts API key - all other settings use defaults
+     */
+    async init(config) {
+        try {
+            // Extract API key from string or object
+            const apiKey = typeof config === "string" ? config : config.apiKey;
+            if (!apiKey) {
+                this.logger.warn("API key is required for SDK initialization");
+            }
+            // Use defaults for all settings - only API key is configurable
+            this.config = {
+                apiKey: apiKey || "",
+                userId: "",
+                environment: constants_1.DEFAULT_CONFIG.environment,
+                debug: constants_1.DEFAULT_CONFIG.debug,
+                maxQueueSize: constants_1.DEFAULT_CONFIG.maxQueueSize,
+                flushInterval: constants_1.DEFAULT_CONFIG.flushInterval,
+                sessionTimeout: constants_1.DEFAULT_CONFIG.sessionTimeout,
+                baseUrl: constants_1.DEFAULT_CONFIG.baseUrl, // Always use production URL
+            };
+            // Update logger
+            this.logger = (0, utils_1.createLogger)(this.config.debug);
+            // Check opt-out status
+            this.isOptedOut = await storage_1.Storage.isOptedOut();
+            if (this.isOptedOut) {
+                this.logger.log("User has opted out, analytics disabled");
+                this._isInitialized = true; // Set initialized even if opted out
+                return;
+            }
+            // Load anonymous ID
+            this.anonymousId = await storage_1.Storage.getAnonymousId();
+            // Load user ID from storage (not configurable at init)
+            this.userId = await storage_1.Storage.getUserId();
+            // Initialize session manager
+            this.sessionManager = new session_1.SessionManager(this.config.sessionTimeout, this.logger, {
+                onSessionStart: (sessionId) => this.handleSessionStart(sessionId),
+                onSessionEnd: (sessionId, duration) => this.handleSessionEnd(sessionId, duration),
+            });
+            await this.sessionManager.initialize();
+            // Initialize session analytics with current session start time
+            const sessionId = this.sessionManager.getSessionId();
+            if (sessionId) {
+                // Use current time as session start time
+                this.sessionAnalytics = new sessionAnalytics_1.SessionAnalytics(Date.now());
+            }
+            // Initialize transport and queue if API key is provided
+            if (this.config.apiKey) {
+                this.transport = new transport_1.Transport({
+                    apiKey: this.config.apiKey,
+                    baseUrl: this.config.baseUrl,
+                    debug: this.config.debug,
+                }, this.logger);
+                this.queue = new queue_1.EventQueue({
+                    maxQueueSize: this.config.maxQueueSize,
+                    flushInterval: this.config.flushInterval,
+                }, this.transport, this.logger);
+                // Initialize queue (starts flush timer)
+                await this.queue.initialize();
+                this.logger.log("Event queue initialized");
+            }
+            else {
+                this.logger.log("No API key provided, events will only be tracked locally");
+            }
+            // Set initialized BEFORE tracking auto events
+            this._isInitialized = true;
+            this.logger.log("Axyle initialized successfully");
+            // Track app opened (after setting initialized flag)
+            await this.trackAutoEvent(constants_1.AUTO_TRACKED_EVENTS.APP_OPENED);
+            // Set up app state listener
+            this.setupAppStateListener();
+        }
+        catch (error) {
+            this.logger.error("Failed to initialize Axyle:", error);
+            this.logger.error("Error details:", error);
+            // Set initialized anyway to prevent infinite waiting
+            this._isInitialized = true;
+            // Fail silently - don't throw
+        }
+    }
+    /**
+     * Track a custom event
+     */
+    async track(eventName, properties = {}) {
+        try {
+            // Check if initialized and not opted out
+            if (!this._isInitialized) {
+                this.logger.warn("SDK not initialized, call init() first");
+                return;
+            }
+            if (this.isOptedOut) {
+                return;
+            }
+            // Validate event name
+            if (!(0, utils_1.isValidEventName)(eventName)) {
+                this.logger.error("Invalid event name:", eventName);
+                return;
+            }
+            // Update session activity
+            await this.sessionManager.updateActivity();
+            // Create event
+            const event = await this.createEvent(eventName, properties);
+            // Validate event size
+            if ((0, utils_1.getObjectSize)(event) > constants_1.MAX_EVENT_SIZE) {
+                this.logger.error("Event size exceeds limit:", eventName);
+                return;
+            }
+            // Add to session analytics (local counting)
+            if (this.sessionAnalytics) {
+                this.sessionAnalytics.addEvent(event);
+                this.logger.log(`Event tracked locally: ${eventName}`);
+            }
+            // Queue event for sending to API (if queue is initialized)
+            if (this.queue) {
+                await this.queue.enqueue(event);
+            }
+        }
+        catch (error) {
+            this.logger.error("Failed to track event:", error);
+            // Fail silently
+        }
+    }
+    /**
+     * Identify a user
+     */
+    async identify(userId, traits = {}) {
+        try {
+            if (!this._isInitialized || this.isOptedOut) {
+                return;
+            }
+            // Capture previous user ID before updating
+            const previousUserId = this.userId;
+            // Store new user ID
+            this.userId = userId;
+            await storage_1.Storage.setUserId(userId);
+            // Track identify event with traits
+            await this.track("User Identified", {
+                ...traits,
+                previousUserId: previousUserId || this.anonymousId,
+            });
+            this.logger.log("User identified:", userId);
+        }
+        catch (error) {
+            this.logger.error("Failed to identify user:", error);
+        }
+    }
+    /**
+     * Reset user data (logout)
+     */
+    async reset() {
+        try {
+            if (!this._isInitialized) {
+                return;
+            }
+            // Clear user ID
+            this.userId = null;
+            await storage_1.Storage.clearUserId();
+            // Reset session
+            await this.sessionManager.reset();
+            this.logger.log("User data reset");
+        }
+        catch (error) {
+            this.logger.error("Failed to reset:", error);
+        }
+    }
+    /**
+     * Opt out of tracking
+     */
+    async optOut() {
+        try {
+            this.isOptedOut = true;
+            await storage_1.Storage.setOptOut(true);
+            // Clear session analytics
+            if (this.sessionAnalytics) {
+                this.sessionAnalytics.clear();
+            }
+            this.logger.log("User opted out");
+        }
+        catch (error) {
+            this.logger.error("Failed to opt out:", error);
+        }
+    }
+    /**
+     * Opt back in to tracking
+     */
+    async optIn() {
+        try {
+            this.isOptedOut = false;
+            await storage_1.Storage.setOptOut(false);
+            // Reinitialize session if it was cleared during opt-out
+            if (!this.sessionManager || !this.sessionManager.getSessionId()) {
+                this.sessionManager = new session_1.SessionManager(this.config.sessionTimeout, this.logger, {
+                    onSessionStart: (sessionId) => this.handleSessionStart(sessionId),
+                    onSessionEnd: (sessionId, duration) => this.handleSessionEnd(sessionId, duration),
+                });
+                await this.sessionManager.initialize();
+                // Reinitialize session analytics
+                const sessionId = this.sessionManager.getSessionId();
+                if (sessionId) {
+                    this.sessionAnalytics = new sessionAnalytics_1.SessionAnalytics(Date.now());
+                }
+            }
+            this.logger.log("User opted in");
+        }
+        catch (error) {
+            this.logger.error("Failed to opt in:", error);
+        }
+    }
+    /**
+     * Delete user data
+     */
+    async deleteUser(userId) {
+        try {
+            // Track deletion request
+            await this.track("User Deletion Requested", { userId });
+            // Clear session analytics
+            if (this.sessionAnalytics) {
+                this.sessionAnalytics.clear();
+            }
+            // Clear local data
+            await storage_1.Storage.clearAll();
+            this.logger.log("User deletion requested:", userId);
+        }
+        catch (error) {
+            this.logger.error("Failed to delete user:", error);
+        }
+    }
+    /**
+     * Get session analytics statistics
+     */
+    getSessionStats() {
+        if (!this.sessionAnalytics) {
+            return null;
+        }
+        return this.sessionAnalytics.getStats();
+    }
+    /**
+     * Get all events in current session
+     */
+    getSessionEvents() {
+        if (!this.sessionAnalytics) {
+            return [];
+        }
+        return this.sessionAnalytics.getEvents();
+    }
+    /**
+     * Get events by type in current session
+     */
+    getEventsByType(eventName) {
+        if (!this.sessionAnalytics) {
+            return [];
+        }
+        return this.sessionAnalytics.getEventsByType(eventName);
+    }
+    /**
+     * Create an event object
+     */
+    async createEvent(name, properties) {
+        const context = await context_1.ContextCollector.getContext(this.config.environment);
+        // Get session ID, fallback to generating a temporary one if not available
+        let sessionId = this.sessionManager?.getSessionId();
+        if (!sessionId) {
+            sessionId = `temp_session_${Date.now()}`;
+            this.logger.warn("Session not initialized, using temporary session ID");
+        }
+        return {
+            id: (0, utils_1.generateUUID)(),
+            name,
+            properties: (0, utils_1.sanitizeProperties)(properties),
+            timestamp: Date.now(),
+            userId: this.userId || this.anonymousId,
+            anonymousId: this.anonymousId,
+            sessionId,
+            context,
+            schemaVersion: constants_1.SCHEMA_VERSION,
+        };
+    }
+    /**
+     * Track an auto event
+     */
+    async trackAutoEvent(eventName, properties = {}) {
+        await this.track(eventName, properties);
+    }
+    /**
+     * Handle session start
+     */
+    handleSessionStart(sessionId) {
+        // Initialize or reset session analytics for new session
+        const sessionStartTime = Date.now();
+        if (this.sessionAnalytics) {
+            this.sessionAnalytics.resetSession(sessionStartTime);
+        }
+        else {
+            this.sessionAnalytics = new sessionAnalytics_1.SessionAnalytics(sessionStartTime);
+        }
+        this.trackAutoEvent(constants_1.AUTO_TRACKED_EVENTS.SESSION_STARTED, { sessionId });
+    }
+    /**
+     * Handle session end
+     */
+    handleSessionEnd(sessionId, duration) {
+        this.trackAutoEvent(constants_1.AUTO_TRACKED_EVENTS.SESSION_ENDED, {
+            sessionId,
+            duration,
+        });
+    }
+    /**
+     * Set up app state listener for background/foreground tracking
+     */
+    setupAppStateListener() {
+        let previousState = react_native_1.AppState.currentState;
+        this.appStateSubscription = react_native_1.AppState.addEventListener("change", (nextState) => {
+            if (previousState === "active" &&
+                nextState.match(/inactive|background/)) {
+                // App went to background
+                this.trackAutoEvent(constants_1.AUTO_TRACKED_EVENTS.APP_BACKGROUNDED);
+            }
+            else if (previousState.match(/inactive|background/) &&
+                nextState === "active") {
+                // App came to foreground
+                this.trackAutoEvent(constants_1.AUTO_TRACKED_EVENTS.APP_FOREGROUNDED);
+                this.sessionManager.updateActivity(); // Update session
+            }
+            previousState = nextState;
+        });
+    }
+    /**
+     * Manually flush all queued events to the server
+     */
+    async flush() {
+        try {
+            if (!this._isInitialized) {
+                this.logger.warn("SDK not initialized, cannot flush");
+                return;
+            }
+            if (this.queue) {
+                await this.queue.flush();
+                this.logger.log("Events flushed successfully");
+            }
+        }
+        catch (error) {
+            this.logger.error("Failed to flush events:", error);
+        }
+    }
+    /**
+     * Cleanup resources
+     */
+    async shutdown() {
+        try {
+            // Remove app state listener
+            if (this.appStateSubscription) {
+                this.appStateSubscription.remove();
+            }
+            // Shutdown queue (flushes remaining events)
+            if (this.queue) {
+                await this.queue.shutdown();
+            }
+            this._isInitialized = false;
+            this.logger.log("Axyle shut down");
+        }
+        catch (error) {
+            this.logger.error("Error during shutdown:", error);
+        }
+    }
+}
+exports.AxyleClient = AxyleClient;

package/dist/config.example.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Sample Configuration File (Deprecated)
+ *
+ * NOTE: This file is kept for reference but is no longer used.
+ * The SDK now only accepts an API key during initialization.
+ *
+ * Use Axyle.init('your-api-key') instead.
+ */

package/dist/config.example.js

@@ -0,0 +1,13 @@
+"use strict";
+/**
+ * Sample Configuration File (Deprecated)
+ *
+ * NOTE: This file is kept for reference but is no longer used.
+ * The SDK now only accepts an API key during initialization.
+ *
+ * Use Axyle.init('your-api-key') instead.
+ */
+// This file is deprecated - SDK now only accepts API key
+// Example usage:
+// import { Axyle } from '@axyle/expo-sdk';
+// Axyle.init('your-api-key');

package/dist/configLoader.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Configuration Loader
+ *
+ * Handles API key validation for the SDK.
+ */
+/**
+ * Validate API key format
+ * Adjust the regex pattern based on your platform's API key format
+ */
+export declare function isValidApiKeyFormat(apiKey: string): boolean;

package/dist/configLoader.js

@@ -0,0 +1,22 @@
+"use strict";
+/**
+ * Configuration Loader
+ *
+ * Handles API key validation for the SDK.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isValidApiKeyFormat = isValidApiKeyFormat;
+/**
+ * Validate API key format
+ * Adjust the regex pattern based on your platform's API key format
+ */
+function isValidApiKeyFormat(apiKey) {
+    if (!apiKey || typeof apiKey !== "string") {
+        return false;
+    }
+    // UUID format: 550e8400-e29b-41d4-a716-446655440000
+    const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+    // Alphanumeric with dashes/underscores: at least 32 characters
+    const alphanumericRegex = /^[a-zA-Z0-9_-]{32,}$/;
+    return uuidRegex.test(apiKey) || alphanumericRegex.test(apiKey);
+}

package/dist/constants.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Constants used throughout the SDK
+ */
+export declare const STORAGE_PREFIX = "@axyle";
+export declare const STORAGE_KEYS: {
+    EVENTS_QUEUE: string;
+    ANONYMOUS_ID: string;
+    USER_ID: string;
+    SESSION_DATA: string;
+    OPT_OUT: string;
+};
+export declare const PRODUCTION_BASE_URL = "https://axyle-server-production.up.railway.app";
+export declare const DEFAULT_CONFIG: {
+    baseUrl: string;
+    debug: boolean;
+    maxQueueSize: number;
+    flushInterval: number;
+    sessionTimeout: number;
+    environment: "prod";
+};
+export declare const SCHEMA_VERSION = "1.0.0";
+export declare const MAX_EVENT_SIZE: number;
+export declare const MAX_BATCH_SIZE: number;
+export declare const MAX_EVENTS_PER_BATCH = 100;
+export declare const RETRY_CONFIG: {
+    maxRetries: number;
+    initialDelay: number;
+    maxDelay: number;
+    backoffMultiplier: number;
+};
+export declare const AUTO_TRACKED_EVENTS: {
+    APP_OPENED: string;
+    APP_BACKGROUNDED: string;
+    APP_FOREGROUNDED: string;
+    SESSION_STARTED: string;
+    SESSION_ENDED: string;
+    SCREEN_VIEWED: string;
+};

package/dist/constants.js

@@ -0,0 +1,42 @@
+"use strict";
+/**
+ * Constants used throughout the SDK
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AUTO_TRACKED_EVENTS = exports.RETRY_CONFIG = exports.MAX_EVENTS_PER_BATCH = exports.MAX_BATCH_SIZE = exports.MAX_EVENT_SIZE = exports.SCHEMA_VERSION = exports.DEFAULT_CONFIG = exports.PRODUCTION_BASE_URL = exports.STORAGE_KEYS = exports.STORAGE_PREFIX = void 0;
+exports.STORAGE_PREFIX = "@axyle";
+exports.STORAGE_KEYS = {
+    EVENTS_QUEUE: `${exports.STORAGE_PREFIX}/events-queue`,
+    ANONYMOUS_ID: `${exports.STORAGE_PREFIX}/anonymous-id`,
+    USER_ID: `${exports.STORAGE_PREFIX}/user-id`,
+    SESSION_DATA: `${exports.STORAGE_PREFIX}/session-data`,
+    OPT_OUT: `${exports.STORAGE_PREFIX}/opt-out`,
+};
+// Production server URL - not configurable by users
+exports.PRODUCTION_BASE_URL = "https://axyle-server-production.up.railway.app";
+exports.DEFAULT_CONFIG = {
+    baseUrl: exports.PRODUCTION_BASE_URL,
+    debug: false,
+    maxQueueSize: 100,
+    flushInterval: 10000, // 10 seconds
+    sessionTimeout: 30 * 60 * 1000, // 30 minutes
+    environment: "prod",
+};
+exports.SCHEMA_VERSION = "1.0.0";
+exports.MAX_EVENT_SIZE = 32 * 1024; // 32KB per event
+exports.MAX_BATCH_SIZE = 500 * 1024; // 500KB per batch
+exports.MAX_EVENTS_PER_BATCH = 100;
+exports.RETRY_CONFIG = {
+    maxRetries: 3,
+    initialDelay: 1000, // 1 second
+    maxDelay: 32000, // 32 seconds
+    backoffMultiplier: 2,
+};
+exports.AUTO_TRACKED_EVENTS = {
+    APP_OPENED: "App Opened",
+    APP_BACKGROUNDED: "App Backgrounded",
+    APP_FOREGROUNDED: "App Foregrounded",
+    SESSION_STARTED: "Session Started",
+    SESSION_ENDED: "Session Ended",
+    SCREEN_VIEWED: "Screen Viewed",
+};

package/dist/context.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Device and app context collection using Expo APIs
+ */
+import { EventContext } from "./types";
+export declare class ContextCollector {
+    private static cachedContext;
+    /**
+     * Get device and app context
+     * Caches result for performance
+     */
+    static getContext(environment: "dev" | "prod"): Promise<EventContext>;
+    /**
+     * Get device ID (may be null on some platforms)
+     */
+    private static getDeviceId;
+    /**
+     * Determine device type
+     */
+    private static getDeviceType;
+    /**
+     * Get device locale
+     */
+    private static getLocale;
+    /**
+     * Get device timezone
+     */
+    private static getTimezone;
+    /**
+     * Get minimal context as fallback
+     */
+    private static getMinimalContext;
+    /**
+     * Clear cached context (useful for testing or when app info changes)
+     */
+    static clearCache(): void;
+}