flux-analytics-sdk 1.0.0 → 1.0.6

package/README.md

@@ -0,0 +1,90 @@
+# Flux Analytics SDK (JS/Web)
+
+This is the official JavaScript/Web SDK for Flux Analytics. It is designed to work seamlessly with the Flux Dashboard and Supabase backend, providing feature parity with the Flutter SDK.
+
+## Installation
+
+```bash
+npm install flux-analytics-sdk
+```
+
+## Quick Start
+
+### 1. Initialize
+Initialize the SDK at the root of your application (e.g., `index.js`, `App.js`, or `main.ts`).
+
+```javascript
+import Flux from 'flux-analytics-sdk';
+
+Flux.init(
+  'YOUR_APP_ID',   // UUID (Application ID from Dashboard)
+  'YOUR_FIRM_ID'   // UUID (Firm/Workspace ID)
+);
+```
+
+> **Note:** The SDK comes pre-configured with the default Flux Cloud credentials. You do not need to provide an API Key.
+
+### 2. Track Events
+Track any custom event with optional metadata.
+
+```javascript
+// Simple event
+Flux.track('button_clicked');
+
+// Event with metadata
+Flux.track('purchase_completed', {
+  item_id: 'sku_123',
+  price: 99.99,
+  currency: 'USD'
+});
+```
+
+### 3. Identity Management
+Link sessions to a specific user ID once they log in.
+
+```javascript
+// When user logs in
+Flux.identify('user_123456');
+```
+
+## Features & Technical Details
+
+### 1. Automatic Session Management
+-   **Session Start**: Automatically tracks `session_start` when `Flux.init()` is called.
+-   **Session ID**: Generated (UUID v4) and persisted in memory for the duration of the page lifecycle.
+-   **Anonymous ID**: A persistent UUID is generated and stored in `localStorage` (`flux_anonymous_id`) to track unauthenticated users across sessions.
+
+### 2. Offline Support (Queue System)
+-   Events are not sent immediately if the device is offline.
+-   **Storage**: Events are stored in `localStorage` under the key `flux_event_queue`.
+-   **Sync**: The SDK automatically listens for the `online` window event and flushes the queue when the connection is restored.
+-   **Retry Logic**: Failed requests (non-4xx/5xx) are kept in the queue for retry.
+
+### 3. Automatic Metadata
+Every event automatically includes the following metadata:
+-   `platform`: 'web'
+-   `os_version`: Browser/OS details
+-   `user_agent`: Raw User-Agent string
+-   `language`: Browser language (e.g., 'en-US')
+-   `resolution`: Screen resolution (e.g., '1920x1080')
+-   `timezone`: User's timezone
+-   `page_url`: Current URL
+-   `referrer`: Previous URL (document.referrer)
+
+### 4. Attribution (Marketing Tracking)
+The SDK automatically checks URL parameters for marketing campaigns.
+-   **Parameters**: Looks for `campaign_id` (or `utm_campaign`) and `click_id` (or `gclid`).
+-   **Persistence**: If found, these are stored and attached to the `app_install` (first visit) event and subsequent events.
+
+### 5. API Compatibility
+The SDK communicates directly with the Flux/Supabase backend using the following endpoints:
+-   **Events**: `POST /rpc/insert_event_v2` (High-performance ingestion)
+-   **Sessions**: `POST /sessions` (Upsert on `session_id`)
+-   **Installs**: `POST /installs` (Tracked only once per device via `localStorage` flag `flux_app_installed`)
+
+## AI / LLM Context
+If you are an AI Assistant integrating this SDK:
+1.  Ensure `Flux.init` is called as early as possible.
+2.  Use `Flux.trackScreen(screenName)` on route changes for SPA (Single Page Applications).
+3.  The `app_id` and `firm_id` MUST be valid UUIDs.
+4.  The SDK handles authentication automatically. You do NOT need to ask the user for an API Key.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "flux-analytics-sdk",
-    "version": "1.0.0",
+    "version": "1.0.6",
     "description": "Flux Analytics SDK for JavaScript/Web",
     "main": "src/index.js",
     "scripts": {
@@ -17,4 +17,4 @@
     "dependencies": {
         "uuid": "^9.0.1"
     }
-}
+}

package/src/Flux.js

@@ -14,7 +14,10 @@ const Flux = (function () {
 
     // Base URL for API
     let _baseUrl = 'https://cnpawrfdekifurtkdblw.supabase.co/rest/v1';
-    let _apiKey = null;
+
+    // PUBLIC ANON KEY (Safe to expose in client-side code, restricted by RLS)
+    const _defaultApiKey = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6ImNucGF3cmZkZWtpZnVydGtkYmx3Iiwicm9sZSI6ImFub24iLCJpYXQiOjE3Njk2NzgyOTQsImV4cCI6MjA4NTI1NDI5NH0.IiMIagP7Guy1SsiWF4OdDmz1X6EwPkT4tWCumQLZXhg';
+    let _apiKey = _defaultApiKey;
 
     // Constants
     const _queueKey = 'flux_event_queue';
@@ -313,11 +316,12 @@ const Flux = (function () {
 
             // 2xx success, 409 conflict (duplicate) is also success
             if (response.ok || response.status === 409) {
+                if (_debug) console.log(`%c[Flux SDK] ✓ Sent to ${endpoint}`, 'color: #10b981; font-weight: bold;');
                 return true;
             } else {
-                if (_debug) console.error(`Flux Error: ${response.status} - ${response.statusText}`);
                 const text = await response.text();
-                if (_debug) console.error('Response:', text);
+                // Always log errors even if debug is off, but make them prominent if debug is on
+                console.error(`%c[Flux SDK] ✗ Error: ${response.status} - ${response.statusText}`, 'color: #ef4444; font-weight: bold;', text);
                 return false;
             }
 
@@ -429,7 +433,9 @@ const Flux = (function () {
             created_at: new Date().toISOString()
         };
 
-        if (_debug) console.log(`Flux Tracked: ${eventName}`, payload);
+        if (_debug) {
+            console.log(`%c[Flux SDK] ⚡ Event Tracked: ${eventName}`, 'color: #6366f1; font-weight: bold; font-size: 12px;', payload);
+        }
 
         await _addToQueue('events', payload);
     }