@journium/js 1.0.7 → 1.1.0

package/README.md

@@ -4,243 +4,64 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)
 
-**The official Journium JavaScript SDK for web browsers**
+The official Journium JavaScript SDK for web browsers. Track events, pageviews, and user interactions with ease.
 
-Track events, pageviews, and user interactions with ease. Perfect for SPAs, vanilla JavaScript apps, and any web application.
+---
 
-## Installation
+## Getting Started
 
-### npm
-```bash
-npm install @journium/js
-```
+Learn how to use Journium to power your application:
 
-### pnpm
-```bash
-pnpm add @journium/js
-```
+- [Quick Start Guide](https://journium.app/docs/js)
+- [Concepts](https://journium.app/docs/js/concepts)
+- [SDK Reference](https://journium.app/docs/js)
+
+### Prerequisites
+- Modern browser (ES2017+)
+- Node.js `>=18.17.0` or later
+- An existing Journium application. [Create your account for free](https://dashboard.journium.app/sign-up?utm_source=github&utm_medium=journium_js).
+
+## Installation
 
-### yarn
 ```bash
-yarn add @journium/js
+npm install @journium/js
 ```
 
-## Basic Setup
-
-### Initialize Journium
-Initialize the Journium SDK with your publishable key to start tracking events.
+## Usage
 
 ```javascript
 import { init } from '@journium/js';
 
 const journium = init({
-  publishableKey: 'your-journium-publishable-key'
+  publishableKey: "your-publishable-key"
 });
-```
 
-### Track a Custom Event
-Track user actions and business events with custom properties.
-
-```javascript
 journium.track('button_clicked', {
-  button_name: 'signup',
-  page: 'homepage',
-  user_type: 'visitor'
+  button_name: 'signup'
 });
 ```
 
-### Identify a User
-Identify users when they log in or sign up to connect their actions across sessions.
+For more detailed examples and configuration options, visit the [Journium documentation](https://journium.app/docs/js/).
 
-```javascript
-journium.identify('user_12345', {
-  name: 'John Doe',
-  email: 'john@example.com',
-  plan: 'premium'
-});
-```
-
-### Reset User Identity
-Reset user identity when they log out to ensure privacy and accurate tracking.
-
-```javascript
-journium.reset();
-```
-
-## Advanced Setup
-
-You can override default configurations:
-
-```javascript
-import { init } from '@journium/js';
-
-const journium = init({
-  publishableKey: 'your-journium-publishable-key',
-  apiHost: 'https://your-custom-instance.com', // Optional: defaults to 'https://events.journium.app'
-  options: {
-    debug: true,                    // Enable debug logging
-    flushAt: 10,                   // Send events after N events
-    flushInterval: 5000,           // Send events every N milliseconds
-    sessionTimeout: 1800000,       // Session timeout (30 minutes)
-    autoTrackPageviews: true,        // Track pageview events (default: true)
-    autocapture: {                 // Configure automatic event capture
-      captureClicks: true,         // Track click events
-      captureFormSubmits: true,    // Track form submissions
-      captureFormChanges: false,   // Track form field changes
-      ignoreClasses: ['no-track'], // CSS classes to ignore
-      ignoreElements: ['input[type="password"]'] // Elements to ignore
-    }
-  }
-});
-
-// Start automatic event capture
-journium.startAutocapture();
-```
+## Other SDKs
 
-## API Reference
+- [@journium/nextjs](https://www.npmjs.com/package/@journium/nextjs) - Next.js SDK
+- [@journium/react](https://www.npmjs.com/package/@journium/react) - React SDK
 
-### Functions
+## Support
 
-#### `init(config: JourniumConfig)`
-Initializes and returns a new JourniumAnalytics instance.
-
-**Parameters:**
-- `config: JourniumConfig` - Configuration object for Journium
-  - `publishableKey: string` - Your Journium publishable key (required)
-  - `apiHost?: string` - Custom API endpoint (optional, defaults to 'https://events.journium.app')
-  - `options?: JourniumLocalOptions` - Local configuration options (optional)
-
-**Returns:** `JourniumAnalytics` - Analytics instance for tracking events
-
-### JourniumAnalytics Instance Methods
-
-#### `track(event: string, properties?: Record<string, unknown>): void`
-Tracks custom events with optional properties.
-
-**Parameters:**
-- `event: string` - Event name to track
-- `properties?: Record<string, unknown>` - Optional event properties
-
-#### `identify(distinctId: string, attributes?: Record<string, unknown>): void`
-Identifies a user and associates future events with their identity.
-
-**Parameters:**
-- `distinctId: string` - Unique user identifier
-- `attributes?: Record<string, unknown>` - Optional user attributes
-
-#### `reset(): void`
-Resets user identity, typically called on logout.
-
-**Returns:** `void`
-
-#### `capturePageview(properties?: Record<string, unknown>): void`
-Manually captures pageview events.
-
-**Parameters:**
-- `properties?: Record<string, unknown>` - Optional pageview properties
-
-#### `startAutocapture(): void`
-Starts automatic event capture for clicks, form interactions, and pageviews.
-
-**Returns:** `void`
-
-**Note:** Autocapture behavior is configured during initialization via the `autocapture` option.
-
-#### `stopAutocapture(): void`
-Stops automatic event capture.
-
-**Returns:** `void`
-
-#### `flush(): Promise<void>`
-Manually sends all queued events to the server immediately.
-
-**Returns:** `Promise<void>` - Promise that resolves when events are sent
-
-#### `destroy(): void`
-Cleans up the SDK, stops all tracking, and sends remaining events.
-
-**Returns:** `void`
-
-#### `getEffectiveOptions(): JourniumLocalOptions`
-Returns the effective configuration options (merged local and remote options).
-
-**Returns:** `JourniumLocalOptions` - Current effective configuration
-
-### Types
-
-#### `JourniumConfig`
-Configuration object for initializing Journium.
-
-```typescript
-interface JourniumConfig {
-  publishableKey: string;
-  apiHost?: string;
-  options?: JourniumLocalOptions;
-}
-```
-
-#### `JourniumLocalOptions`
-Local configuration options that can be set on the client.
-
-```typescript
-interface JourniumLocalOptions {
-  debug?: boolean;                    // Enable debug logging
-  flushAt?: number;                   // Number of events before auto-flush
-  flushInterval?: number;             // Flush interval in milliseconds
-  autocapture?: boolean | AutocaptureOptions; // Auto-capture configuration
-  autoTrackPageviews?: boolean;       // Automatic pageview tracking
-  sessionTimeout?: number;            // Session timeout in milliseconds
-  sampling?: {
-    enabled?: boolean;
-    rate?: number;
-  };
-  features?: {
-    enableGeolocation?: boolean;
-    enableSessionRecording?: boolean;
-    enablePerformanceTracking?: boolean;
-  };
-}
-```
-
-#### `AutocaptureOptions`
-Configuration for automatic event capture.
-
-```typescript
-interface AutocaptureOptions {
-  captureClicks?: boolean;            // Capture click events
-  captureFormSubmits?: boolean;       // Capture form submissions
-  captureFormChanges?: boolean;       // Capture form field changes
-  captureTextSelection?: boolean;     // Capture text selection events
-  ignoreClasses?: string[];           // CSS classes to ignore
-  ignoreElements?: string[];          // HTML elements to ignore
-  captureContentText?: boolean;       // Capture element text content
-}
-```
+Need help? Reach out to us:
 
-### Browser Support
+- 📖 Join our official community [Discord server](https://journium.app/discord)
+- 🐛 [Issue Tracker](https://github.com/journium/journium-js/issues)
 
-- ✅ Modern browsers (ES2017+)
-- ✅ Chrome 60+
-- ✅ Firefox 55+
-- ✅ Safari 11+
-- ✅ Edge 79+
+## Contributing
 
-### Bundle Formats
+We're open to all community contributions! If you'd like to contribute in any way, please read [our contribution guidelines](https://github.com/journium/journium-js/blob/main/CONTRIBUTING.md) and [code of conduct](https://github.com/journium/journium-js/blob/main/CODE_OF_CONDUCT.md).
 
-The package includes multiple build formats:
 
-- **ESM**: `dist/index.esm.js` - For modern bundlers (webpack, Vite, Rollup)
-- **CommonJS**: `dist/index.cjs` - For Node.js environments
-- **UMD**: `dist/index.umd.js` - For browser `<script>` tags
+## License
 
-#### UMD Usage
+This project is licensed under the **MIT license**.
 
-```html
-<script src="node_modules/@journium/js/dist/index.umd.js"></script>
-<script>
-  const analytics = window.JourniumAnalytics.init({
-    publishableKey: 'your-publishable-key'
-  });
-  analytics.track('page_loaded');
-</script>
-```
+See [LICENSE](https://github.com/journium/journium-js/blob/main/LICENSE) for more information.

package/dist/JourniumAnalytics.d.ts

@@ -14,6 +14,11 @@ export declare class JourniumAnalytics {
     capturePageview(properties?: Record<string, unknown>): void;
     startAutocapture(): void;
     stopAutocapture(): void;
+    /**
+     * Automatically start autocapture if enabled in options
+     * Handles both initial options and empty options during remote-first initialization
+     */
+    private startAutocaptureIfEnabled;
     /**
      * Handle effective options change (e.g., when remote options are fetched)
      */

package/dist/JourniumAnalytics.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"JourniumAnalytics.d.ts","sourceRoot":"","sources":["../src/JourniumAnalytics.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAsB,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAK1F,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,MAAM,CAAiB;IAC/B,OAAO,CAAC,eAAe,CAAkB;IACzC,OAAO,CAAC,kBAAkB,CAAqB;IAC/C,OAAO,CAAC,MAAM,CAAiB;IAC/B,OAAO,CAAC,kBAAkB,CAAkB;IAC5C,OAAO,CAAC,wBAAwB,CAAC,CAAa;gBAElC,MAAM,EAAE,cAAc;IAiBlC,OAAO,CAAC,yBAAyB;IAiBjC,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAIhE,QAAQ,CAAC,UAAU,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAIxE,KAAK,IAAI,IAAI;IAIb,eAAe,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAI3D,gBAAgB,IAAI,IAAI;IAqBxB,eAAe,IAAI,IAAI;IAMvB;;OAEG;IACH,OAAO,CAAC,mBAAmB;IA8BrB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAI5B,mBAAmB;IAInB;;OAEG;IACH,eAAe,CAAC,QAAQ,EAAE,CAAC,OAAO,EAAE,oBAAoB,KAAK,IAAI,GAAG,MAAM,IAAI;IAI9E,OAAO,IAAI,IAAI;CAQhB;AAED,eAAO,MAAM,IAAI,GAAI,QAAQ,cAAc,KAAG,iBAE7C,CAAC;;mBAF2B,cAAc,KAAG,iBAAiB;;;AAI/D,wBAA2C"}
+{"version":3,"file":"JourniumAnalytics.d.ts","sourceRoot":"","sources":["../src/JourniumAnalytics.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAsB,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAK1F,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,MAAM,CAAiB;IAC/B,OAAO,CAAC,eAAe,CAAkB;IACzC,OAAO,CAAC,kBAAkB,CAAqB;IAC/C,OAAO,CAAC,MAAM,CAAiB;IAC/B,OAAO,CAAC,kBAAkB,CAAkB;IAC5C,OAAO,CAAC,wBAAwB,CAAC,CAAa;gBAElC,MAAM,EAAE,cAAc;IAqBlC,OAAO,CAAC,yBAAyB;IAiBjC,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAIhE,QAAQ,CAAC,UAAU,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAIxE,KAAK,IAAI,IAAI;IAIb,eAAe,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAI3D,gBAAgB,IAAI,IAAI;IA4BxB,eAAe,IAAI,IAAI;IAMvB;;;OAGG;IACH,OAAO,CAAC,yBAAyB;IAkCjC;;OAEG;IACH,OAAO,CAAC,mBAAmB;IA6BrB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAI5B,mBAAmB;IAInB;;OAEG;IACH,eAAe,CAAC,QAAQ,EAAE,CAAC,OAAO,EAAE,oBAAoB,KAAK,IAAI,GAAG,MAAM,IAAI;IAI9E,OAAO,IAAI,IAAI;CAQhB;AAED,eAAO,MAAM,IAAI,GAAI,QAAQ,cAAc,KAAG,iBAE7C,CAAC;;mBAF2B,cAAc,KAAG,iBAAiB;;;AAI/D,wBAA2C"}

package/dist/JourniumClient.d.ts

@@ -3,22 +3,25 @@ export declare class JourniumClient {
     private config;
     private effectiveOptions;
     private queue;
+    private stagedEvents;
     private flushTimer;
-    private initialized;
+    private initializationComplete;
+    private initializationFailed;
     private identityManager;
     private optionsStorageKey;
+    private disabled;
     private optionsChangeCallbacks;
     constructor(config: JourniumConfig);
     private loadCachedOptions;
     private saveCachedOptions;
-    private initializeSync;
-    private fetchRemoteOptionsAsync;
-    private fetchAndCacheRemoteOptions;
+    private initializeAsync;
+    private fetchRemoteOptionsWithRetry;
     /**
      * Register a callback to be notified when effective options change (e.g., when remote options are fetched)
      */
     onOptionsChange(callback: (options: JourniumLocalOptions) => void): () => void;
     private notifyOptionsChange;
+    private processStagedEvents;
     private startFlushTimer;
     private sendEvents;
     identify(distinctId: string, attributes?: Record<string, unknown>): void;

package/dist/JourniumClient.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"JourniumClient.d.ts","sourceRoot":"","sources":["../src/JourniumClient.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiB,cAAc,EAAE,oBAAoB,EAAyG,MAAM,gBAAgB,CAAC;AAE5L,qBAAa,cAAc;IACzB,OAAO,CAAC,MAAM,CAAkB;IAChC,OAAO,CAAC,gBAAgB,CAAwB;IAChD,OAAO,CAAC,KAAK,CAAuB;IACpC,OAAO,CAAC,UAAU,CAA+C;IACjE,OAAO,CAAC,WAAW,CAAkB;IACrC,OAAO,CAAC,eAAe,CAA0B;IACjD,OAAO,CAAC,iBAAiB,CAAU;IACnC,OAAO,CAAC,sBAAsB,CAA2D;gBAE7E,MAAM,EAAE,cAAc;IA0ClC,OAAO,CAAC,iBAAiB;IAczB,OAAO,CAAC,iBAAiB;IAYzB,OAAO,CAAC,cAAc;YA8BR,uBAAuB;YAOvB,0BAA0B;IAyCxC;;OAEG;IACH,eAAe,CAAC,QAAQ,EAAE,CAAC,OAAO,EAAE,oBAAoB,KAAK,IAAI,GAAG,MAAM,IAAI;IAQ9E,OAAO,CAAC,mBAAmB;IAU3B,OAAO,CAAC,eAAe;YAWT,UAAU;IA0BxB,QAAQ,CAAC,UAAU,EAAE,MAAM,EAAE,UAAU,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GAAG,IAAI;IAqB5E,KAAK,IAAI,IAAI;IAab,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GAAG,IAAI;IAwC9D,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAmB5B,OAAO,IAAI,IAAI;IAQf,mBAAmB,IAAI,oBAAoB;CAG5C"}
+{"version":3,"file":"JourniumClient.d.ts","sourceRoot":"","sources":["../src/JourniumClient.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiB,cAAc,EAAE,oBAAoB,EAAyG,MAAM,gBAAgB,CAAC;AAE5L,qBAAa,cAAc;IACzB,OAAO,CAAC,MAAM,CAAkB;IAChC,OAAO,CAAC,gBAAgB,CAAwB;IAChD,OAAO,CAAC,KAAK,CAAuB;IACpC,OAAO,CAAC,YAAY,CAAuB;IAC3C,OAAO,CAAC,UAAU,CAA+C;IACjE,OAAO,CAAC,sBAAsB,CAAkB;IAChD,OAAO,CAAC,oBAAoB,CAAkB;IAC9C,OAAO,CAAC,eAAe,CAA0B;IACjD,OAAO,CAAC,iBAAiB,CAAU;IACnC,OAAO,CAAC,QAAQ,CAAkB;IAClC,OAAO,CAAC,sBAAsB,CAA2D;gBAE7E,MAAM,EAAE,cAAc;IAoClC,OAAO,CAAC,iBAAiB;IAczB,OAAO,CAAC,iBAAiB;YAYX,eAAe;YAwEf,2BAA2B;IA8CzC;;OAEG;IACH,eAAe,CAAC,QAAQ,EAAE,CAAC,OAAO,EAAE,oBAAoB,KAAK,IAAI,GAAG,MAAM,IAAI;IAQ9E,OAAO,CAAC,mBAAmB;IAU3B,OAAO,CAAC,mBAAmB;IA0C3B,OAAO,CAAC,eAAe;YAYT,UAAU;IA0BxB,QAAQ,CAAC,UAAU,EAAE,MAAM,EAAE,UAAU,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GAAG,IAAI;IA2B5E,KAAK,IAAI,IAAI;IAmBb,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GAAG,IAAI;IAiE9D,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAyB5B,OAAO,IAAI,IAAI;IAQf,mBAAmB,IAAI,oBAAoB;CAG5C"}

package/dist/PageviewTracker.d.ts

@@ -11,7 +11,7 @@ export declare class PageviewTracker {
      * Start automatic autocapture for pageviews
      * @returns void
      */
-    startAutocapture(): void;
+    startAutoPageviewTracking(): void;
     /**
      * Stop automatic autocapture for pageviews
      * @returns void

package/dist/PageviewTracker.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"PageviewTracker.d.ts","sourceRoot":"","sources":["../src/PageviewTracker.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAElD,qBAAa,eAAe;IAC1B,OAAO,CAAC,MAAM,CAAiB;IAC/B,OAAO,CAAC,OAAO,CAAc;IAC7B,OAAO,CAAC,iBAAiB,CAAgD;IACzE,OAAO,CAAC,oBAAoB,CAAmD;IAC/E,OAAO,CAAC,eAAe,CAA6B;gBAExC,MAAM,EAAE,cAAc;IAIlC,eAAe,CAAC,gBAAgB,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GAAG,IAAI;IAkBrE;;;OAGG;IACH,gBAAgB,IAAI,IAAI;IA0BxB;;;OAGG;IACH,eAAe,IAAI,IAAI;CAmBxB"}
+{"version":3,"file":"PageviewTracker.d.ts","sourceRoot":"","sources":["../src/PageviewTracker.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAElD,qBAAa,eAAe;IAC1B,OAAO,CAAC,MAAM,CAAiB;IAC/B,OAAO,CAAC,OAAO,CAAc;IAC7B,OAAO,CAAC,iBAAiB,CAAgD;IACzE,OAAO,CAAC,oBAAoB,CAAmD;IAC/E,OAAO,CAAC,eAAe,CAA6B;gBAExC,MAAM,EAAE,cAAc;IAIlC,eAAe,CAAC,gBAAgB,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GAAG,IAAI;IAkBrE;;;OAGG;IACH,yBAAyB,IAAI,IAAI;IA0BjC;;;OAGG;IACH,eAAe,IAAI,IAAI;CAmBxB"}