@grainql/analytics-web 1.0.0

package/dist/index.js

@@ -0,0 +1,294 @@
+"use strict";
+/**
+ * Grain Analytics Web SDK
+ * A lightweight, dependency-free TypeScript SDK for sending analytics events to Grain's REST API
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GrainAnalytics = void 0;
+exports.createGrainAnalytics = createGrainAnalytics;
+class GrainAnalytics {
+    constructor(config) {
+        this.eventQueue = [];
+        this.flushTimer = null;
+        this.isDestroyed = false;
+        this.config = {
+            apiUrl: 'https://api.grainql.com',
+            authStrategy: 'NONE',
+            batchSize: 50,
+            flushInterval: 5000, // 5 seconds
+            retryAttempts: 3,
+            retryDelay: 1000, // 1 second
+            debug: false,
+            ...config,
+            tenantId: config.tenantId,
+        };
+        this.validateConfig();
+        this.setupBeforeUnload();
+        this.startFlushTimer();
+    }
+    validateConfig() {
+        if (!this.config.tenantId) {
+            throw new Error('Grain Analytics: tenantId is required');
+        }
+        if (this.config.authStrategy === 'SERVER_SIDE' && !this.config.secretKey) {
+            throw new Error('Grain Analytics: secretKey is required for SERVER_SIDE auth strategy');
+        }
+        if (this.config.authStrategy === 'JWT' && !this.config.authProvider) {
+            throw new Error('Grain Analytics: authProvider is required for JWT auth strategy');
+        }
+    }
+    log(...args) {
+        if (this.config.debug) {
+            console.log('[Grain Analytics]', ...args);
+        }
+    }
+    generateInsertId() {
+        return `${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
+    }
+    formatEvent(event) {
+        const timestamp = event.timestamp || new Date();
+        const eventTs = timestamp.toISOString();
+        const eventDate = timestamp.toISOString().split('T')[0];
+        return {
+            eventName: event.eventName,
+            eventTs,
+            userId: event.userId || 'anonymous',
+            properties: event.properties || {},
+            eventDate,
+            insertId: this.generateInsertId(),
+        };
+    }
+    async getAuthHeaders() {
+        const headers = {
+            'Content-Type': 'application/json',
+        };
+        switch (this.config.authStrategy) {
+            case 'NONE':
+                break;
+            case 'SERVER_SIDE':
+                headers['Authorization'] = `Chase ${this.config.secretKey}`;
+                break;
+            case 'JWT':
+                if (this.config.authProvider) {
+                    const token = await this.config.authProvider.getToken();
+                    headers['Authorization'] = `Bearer ${token}`;
+                }
+                break;
+        }
+        return headers;
+    }
+    async delay(ms) {
+        return new Promise(resolve => setTimeout(resolve, ms));
+    }
+    isRetriableError(error) {
+        if (error instanceof Error) {
+            // Check for network errors or server errors
+            if (error.message.includes('fetch'))
+                return true;
+            if (error.message.includes('network'))
+                return true;
+        }
+        // Check for HTTP status codes that are retriable
+        if (typeof error === 'object' && error !== null && 'status' in error) {
+            const status = error.status;
+            return status >= 500 || status === 429; // Server errors or rate limiting
+        }
+        return false;
+    }
+    async sendEvents(events) {
+        if (events.length === 0)
+            return;
+        let lastError;
+        for (let attempt = 0; attempt <= this.config.retryAttempts; attempt++) {
+            try {
+                const headers = await this.getAuthHeaders();
+                const url = `${this.config.apiUrl}/v1/events/${encodeURIComponent(this.config.tenantId)}`;
+                this.log(`Sending ${events.length} events to ${url} (attempt ${attempt + 1})`);
+                const response = await fetch(url, {
+                    method: 'POST',
+                    headers,
+                    body: JSON.stringify({ events }),
+                });
+                if (!response.ok) {
+                    let errorMessage = `HTTP ${response.status}`;
+                    try {
+                        const errorBody = await response.json();
+                        if (errorBody?.message) {
+                            errorMessage = errorBody.message;
+                        }
+                    }
+                    catch {
+                        const errorText = await response.text();
+                        if (errorText) {
+                            errorMessage = errorText;
+                        }
+                    }
+                    const error = new Error(`Failed to send events: ${errorMessage}`);
+                    error.status = response.status;
+                    throw error;
+                }
+                this.log(`Successfully sent ${events.length} events`);
+                return; // Success, exit retry loop
+            }
+            catch (error) {
+                lastError = error;
+                if (attempt === this.config.retryAttempts) {
+                    // Last attempt, don't retry
+                    break;
+                }
+                if (!this.isRetriableError(error)) {
+                    // Non-retriable error, don't retry
+                    break;
+                }
+                const delayMs = this.config.retryDelay * Math.pow(2, attempt); // Exponential backoff
+                this.log(`Retrying in ${delayMs}ms after error:`, error);
+                await this.delay(delayMs);
+            }
+        }
+        console.error('[Grain Analytics] Failed to send events after all retries:', lastError);
+        throw lastError;
+    }
+    async sendEventsWithBeacon(events) {
+        if (events.length === 0)
+            return;
+        try {
+            const headers = await this.getAuthHeaders();
+            const url = `${this.config.apiUrl}/v1/events/${encodeURIComponent(this.config.tenantId)}`;
+            const body = JSON.stringify({ events });
+            // Try beacon API first (more reliable for page unload)
+            if (typeof navigator !== 'undefined' && 'sendBeacon' in navigator) {
+                const blob = new Blob([body], { type: 'application/json' });
+                const success = navigator.sendBeacon(url, blob);
+                if (success) {
+                    this.log(`Successfully sent ${events.length} events via beacon`);
+                    return;
+                }
+            }
+            // Fallback to fetch with keepalive
+            await fetch(url, {
+                method: 'POST',
+                headers,
+                body,
+                keepalive: true,
+            });
+            this.log(`Successfully sent ${events.length} events via fetch (keepalive)`);
+        }
+        catch (error) {
+            console.error('[Grain Analytics] Failed to send events via beacon:', error);
+        }
+    }
+    startFlushTimer() {
+        if (this.flushTimer) {
+            clearInterval(this.flushTimer);
+        }
+        this.flushTimer = window.setInterval(() => {
+            if (this.eventQueue.length > 0) {
+                this.flush().catch((error) => {
+                    console.error('[Grain Analytics] Auto-flush failed:', error);
+                });
+            }
+        }, this.config.flushInterval);
+    }
+    setupBeforeUnload() {
+        if (typeof window === 'undefined')
+            return;
+        const handleBeforeUnload = () => {
+            if (this.eventQueue.length > 0) {
+                // Use beacon API for reliable delivery during page unload
+                this.sendEventsWithBeacon([...this.eventQueue]).catch(() => {
+                    // Silently fail - page is unloading
+                });
+                this.eventQueue = [];
+            }
+        };
+        // Handle page unload
+        window.addEventListener('beforeunload', handleBeforeUnload);
+        window.addEventListener('pagehide', handleBeforeUnload);
+        // Handle visibility change (page hidden)
+        document.addEventListener('visibilitychange', () => {
+            if (document.visibilityState === 'hidden' && this.eventQueue.length > 0) {
+                this.sendEventsWithBeacon([...this.eventQueue]).catch(() => {
+                    // Silently fail
+                });
+                this.eventQueue = [];
+            }
+        });
+    }
+    async track(eventOrName, propertiesOrOptions, options) {
+        if (this.isDestroyed) {
+            throw new Error('Grain Analytics: Client has been destroyed');
+        }
+        let event;
+        let opts = {};
+        if (typeof eventOrName === 'string') {
+            event = {
+                eventName: eventOrName,
+                properties: propertiesOrOptions,
+            };
+            opts = options || {};
+        }
+        else {
+            event = eventOrName;
+            opts = propertiesOrOptions || {};
+        }
+        const formattedEvent = this.formatEvent(event);
+        this.eventQueue.push(formattedEvent);
+        this.log(`Queued event: ${event.eventName}`, event.properties);
+        // Check if we should flush immediately
+        if (opts.flush || this.eventQueue.length >= this.config.batchSize) {
+            await this.flush();
+        }
+    }
+    /**
+     * Identify a user (sets userId for subsequent events)
+     */
+    identify(userId) {
+        // Store userId for future events - this would typically be handled
+        // by the application layer, but we can provide a helper
+        this.log(`Identified user: ${userId}`);
+    }
+    /**
+     * Manually flush all queued events
+     */
+    async flush() {
+        if (this.eventQueue.length === 0)
+            return;
+        const eventsToSend = [...this.eventQueue];
+        this.eventQueue = [];
+        await this.sendEvents(eventsToSend);
+    }
+    /**
+     * Destroy the client and clean up resources
+     */
+    destroy() {
+        this.isDestroyed = true;
+        if (this.flushTimer) {
+            clearInterval(this.flushTimer);
+            this.flushTimer = null;
+        }
+        // Send any remaining events
+        if (this.eventQueue.length > 0) {
+            this.sendEventsWithBeacon([...this.eventQueue]).catch(() => {
+                // Silently fail during cleanup
+            });
+            this.eventQueue = [];
+        }
+    }
+}
+exports.GrainAnalytics = GrainAnalytics;
+/**
+ * Create a new Grain Analytics client
+ */
+function createGrainAnalytics(config) {
+    return new GrainAnalytics(config);
+}
+// Default export for convenience
+exports.default = GrainAnalytics;
+// Auto-setup for IIFE build
+if (typeof window !== 'undefined') {
+    window.Grain = {
+        GrainAnalytics,
+        createGrainAnalytics,
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/index.mjs

@@ -0,0 +1,289 @@
+/**
+ * Grain Analytics Web SDK
+ * A lightweight, dependency-free TypeScript SDK for sending analytics events to Grain's REST API
+ */
+export class GrainAnalytics {
+    constructor(config) {
+        this.eventQueue = [];
+        this.flushTimer = null;
+        this.isDestroyed = false;
+        this.config = {
+            apiUrl: 'https://api.grainql.com',
+            authStrategy: 'NONE',
+            batchSize: 50,
+            flushInterval: 5000, // 5 seconds
+            retryAttempts: 3,
+            retryDelay: 1000, // 1 second
+            debug: false,
+            ...config,
+            tenantId: config.tenantId,
+        };
+        this.validateConfig();
+        this.setupBeforeUnload();
+        this.startFlushTimer();
+    }
+    validateConfig() {
+        if (!this.config.tenantId) {
+            throw new Error('Grain Analytics: tenantId is required');
+        }
+        if (this.config.authStrategy === 'SERVER_SIDE' && !this.config.secretKey) {
+            throw new Error('Grain Analytics: secretKey is required for SERVER_SIDE auth strategy');
+        }
+        if (this.config.authStrategy === 'JWT' && !this.config.authProvider) {
+            throw new Error('Grain Analytics: authProvider is required for JWT auth strategy');
+        }
+    }
+    log(...args) {
+        if (this.config.debug) {
+            console.log('[Grain Analytics]', ...args);
+        }
+    }
+    generateInsertId() {
+        return `${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
+    }
+    formatEvent(event) {
+        const timestamp = event.timestamp || new Date();
+        const eventTs = timestamp.toISOString();
+        const eventDate = timestamp.toISOString().split('T')[0];
+        return {
+            eventName: event.eventName,
+            eventTs,
+            userId: event.userId || 'anonymous',
+            properties: event.properties || {},
+            eventDate,
+            insertId: this.generateInsertId(),
+        };
+    }
+    async getAuthHeaders() {
+        const headers = {
+            'Content-Type': 'application/json',
+        };
+        switch (this.config.authStrategy) {
+            case 'NONE':
+                break;
+            case 'SERVER_SIDE':
+                headers['Authorization'] = `Chase ${this.config.secretKey}`;
+                break;
+            case 'JWT':
+                if (this.config.authProvider) {
+                    const token = await this.config.authProvider.getToken();
+                    headers['Authorization'] = `Bearer ${token}`;
+                }
+                break;
+        }
+        return headers;
+    }
+    async delay(ms) {
+        return new Promise(resolve => setTimeout(resolve, ms));
+    }
+    isRetriableError(error) {
+        if (error instanceof Error) {
+            // Check for network errors or server errors
+            if (error.message.includes('fetch'))
+                return true;
+            if (error.message.includes('network'))
+                return true;
+        }
+        // Check for HTTP status codes that are retriable
+        if (typeof error === 'object' && error !== null && 'status' in error) {
+            const status = error.status;
+            return status >= 500 || status === 429; // Server errors or rate limiting
+        }
+        return false;
+    }
+    async sendEvents(events) {
+        if (events.length === 0)
+            return;
+        let lastError;
+        for (let attempt = 0; attempt <= this.config.retryAttempts; attempt++) {
+            try {
+                const headers = await this.getAuthHeaders();
+                const url = `${this.config.apiUrl}/v1/events/${encodeURIComponent(this.config.tenantId)}`;
+                this.log(`Sending ${events.length} events to ${url} (attempt ${attempt + 1})`);
+                const response = await fetch(url, {
+                    method: 'POST',
+                    headers,
+                    body: JSON.stringify({ events }),
+                });
+                if (!response.ok) {
+                    let errorMessage = `HTTP ${response.status}`;
+                    try {
+                        const errorBody = await response.json();
+                        if (errorBody?.message) {
+                            errorMessage = errorBody.message;
+                        }
+                    }
+                    catch {
+                        const errorText = await response.text();
+                        if (errorText) {
+                            errorMessage = errorText;
+                        }
+                    }
+                    const error = new Error(`Failed to send events: ${errorMessage}`);
+                    error.status = response.status;
+                    throw error;
+                }
+                this.log(`Successfully sent ${events.length} events`);
+                return; // Success, exit retry loop
+            }
+            catch (error) {
+                lastError = error;
+                if (attempt === this.config.retryAttempts) {
+                    // Last attempt, don't retry
+                    break;
+                }
+                if (!this.isRetriableError(error)) {
+                    // Non-retriable error, don't retry
+                    break;
+                }
+                const delayMs = this.config.retryDelay * Math.pow(2, attempt); // Exponential backoff
+                this.log(`Retrying in ${delayMs}ms after error:`, error);
+                await this.delay(delayMs);
+            }
+        }
+        console.error('[Grain Analytics] Failed to send events after all retries:', lastError);
+        throw lastError;
+    }
+    async sendEventsWithBeacon(events) {
+        if (events.length === 0)
+            return;
+        try {
+            const headers = await this.getAuthHeaders();
+            const url = `${this.config.apiUrl}/v1/events/${encodeURIComponent(this.config.tenantId)}`;
+            const body = JSON.stringify({ events });
+            // Try beacon API first (more reliable for page unload)
+            if (typeof navigator !== 'undefined' && 'sendBeacon' in navigator) {
+                const blob = new Blob([body], { type: 'application/json' });
+                const success = navigator.sendBeacon(url, blob);
+                if (success) {
+                    this.log(`Successfully sent ${events.length} events via beacon`);
+                    return;
+                }
+            }
+            // Fallback to fetch with keepalive
+            await fetch(url, {
+                method: 'POST',
+                headers,
+                body,
+                keepalive: true,
+            });
+            this.log(`Successfully sent ${events.length} events via fetch (keepalive)`);
+        }
+        catch (error) {
+            console.error('[Grain Analytics] Failed to send events via beacon:', error);
+        }
+    }
+    startFlushTimer() {
+        if (this.flushTimer) {
+            clearInterval(this.flushTimer);
+        }
+        this.flushTimer = window.setInterval(() => {
+            if (this.eventQueue.length > 0) {
+                this.flush().catch((error) => {
+                    console.error('[Grain Analytics] Auto-flush failed:', error);
+                });
+            }
+        }, this.config.flushInterval);
+    }
+    setupBeforeUnload() {
+        if (typeof window === 'undefined')
+            return;
+        const handleBeforeUnload = () => {
+            if (this.eventQueue.length > 0) {
+                // Use beacon API for reliable delivery during page unload
+                this.sendEventsWithBeacon([...this.eventQueue]).catch(() => {
+                    // Silently fail - page is unloading
+                });
+                this.eventQueue = [];
+            }
+        };
+        // Handle page unload
+        window.addEventListener('beforeunload', handleBeforeUnload);
+        window.addEventListener('pagehide', handleBeforeUnload);
+        // Handle visibility change (page hidden)
+        document.addEventListener('visibilitychange', () => {
+            if (document.visibilityState === 'hidden' && this.eventQueue.length > 0) {
+                this.sendEventsWithBeacon([...this.eventQueue]).catch(() => {
+                    // Silently fail
+                });
+                this.eventQueue = [];
+            }
+        });
+    }
+    async track(eventOrName, propertiesOrOptions, options) {
+        if (this.isDestroyed) {
+            throw new Error('Grain Analytics: Client has been destroyed');
+        }
+        let event;
+        let opts = {};
+        if (typeof eventOrName === 'string') {
+            event = {
+                eventName: eventOrName,
+                properties: propertiesOrOptions,
+            };
+            opts = options || {};
+        }
+        else {
+            event = eventOrName;
+            opts = propertiesOrOptions || {};
+        }
+        const formattedEvent = this.formatEvent(event);
+        this.eventQueue.push(formattedEvent);
+        this.log(`Queued event: ${event.eventName}`, event.properties);
+        // Check if we should flush immediately
+        if (opts.flush || this.eventQueue.length >= this.config.batchSize) {
+            await this.flush();
+        }
+    }
+    /**
+     * Identify a user (sets userId for subsequent events)
+     */
+    identify(userId) {
+        // Store userId for future events - this would typically be handled
+        // by the application layer, but we can provide a helper
+        this.log(`Identified user: ${userId}`);
+    }
+    /**
+     * Manually flush all queued events
+     */
+    async flush() {
+        if (this.eventQueue.length === 0)
+            return;
+        const eventsToSend = [...this.eventQueue];
+        this.eventQueue = [];
+        await this.sendEvents(eventsToSend);
+    }
+    /**
+     * Destroy the client and clean up resources
+     */
+    destroy() {
+        this.isDestroyed = true;
+        if (this.flushTimer) {
+            clearInterval(this.flushTimer);
+            this.flushTimer = null;
+        }
+        // Send any remaining events
+        if (this.eventQueue.length > 0) {
+            this.sendEventsWithBeacon([...this.eventQueue]).catch(() => {
+                // Silently fail during cleanup
+            });
+            this.eventQueue = [];
+        }
+    }
+}
+/**
+ * Create a new Grain Analytics client
+ */
+export function createGrainAnalytics(config) {
+    return new GrainAnalytics(config);
+}
+// Default export for convenience
+export default GrainAnalytics;
+// Auto-setup for IIFE build
+if (typeof window !== 'undefined') {
+    window.Grain = {
+        GrainAnalytics,
+        createGrainAnalytics,
+    };
+}
+//# sourceMappingURL=index.js.map

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@grainql/analytics-web",
+  "version": "1.0.0",
+  "description": "Lightweight TypeScript SDK for sending analytics events to Grain's REST API",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist/"
+  ],
+  "scripts": {
+    "build": "npm run build:types && npm run build:esm && npm run build:cjs && npm run build:iife",
+    "build:types": "tsc --declaration --emitDeclarationOnly --outDir dist",
+    "build:esm": "tsc --module esnext --target es2020 --outDir dist/esm && mv dist/esm/index.js dist/index.mjs",
+    "build:cjs": "tsc --module commonjs --target es2020 --outDir dist/cjs && mv dist/cjs/index.js dist/index.js",
+    "build:iife": "node scripts/build-iife.js",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "npm run clean && npm run build"
+  },
+  "keywords": [
+    "analytics",
+    "tracking",
+    "events",
+    "grain",
+    "typescript",
+    "sdk"
+  ],
+  "author": "Grain Analytics",
+  "license": "MIT",
+  "dependencies": {},
+  "devDependencies": {
+    "typescript": "^5.5.3",
+    "esbuild": "^0.19.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/grain-analytics/web-sdk.git"
+  },
+  "homepage": "https://grainql.com",
+  "private": false
+}