@journium/js 1.0.1 → 1.0.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Journium
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -77,11 +77,12 @@ 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'
-  config: {
+  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
@@ -98,85 +99,148 @@ journium.startAutocapture();
 
 ## API Reference
 
-### `init(config: JourniumConfig)`
-Initialize the Journium SDK with your configuration.
+### Functions
 
-```javascript
-const journium = init({
-  publishableKey: 'your-journium-publishable-key',
-  apiHost: 'https://events.journium.app', // Optional
-  config: { /* optional local config */ }
-});
-```
+#### `init(config: JourniumConfig)`
+Initializes and returns a new JourniumAnalytics instance.
 
-### `journium.track(eventName, properties?)`
-Track custom events with optional properties.
+**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)
 
-```javascript
-// Simple event
-journium.track('feature_used');
-
-// Event with properties
-journium.track('purchase_completed', {
-  product_id: 'prod_123',
-  amount: 29.99,
-  currency: 'USD'
-});
-```
+**Returns:** `JourniumAnalytics` - Analytics instance for tracking events
 
-### `journium.identify(distinctId, attributes?)`
-Identify a user when they log in or sign up.
+### JourniumAnalytics Instance Methods
 
-```javascript
-journium.identify('user_12345', {
-  name: 'John Doe',
-  email: 'john@example.com',
-  signup_date: '2024-01-15'
-});
-```
+#### `track(event: string, properties?: Record<string, unknown>): void`
+Tracks custom events with optional properties.
 
-### `journium.reset()`
-Reset user identity when they log out.
+**Parameters:**
+- `event: string` - Event name to track
+- `properties?: Record<string, unknown>` - Optional event properties
 
-```javascript
-journium.reset();
-```
+#### `identify(distinctId: string, attributes?: Record<string, unknown>): void`
+Identifies a user and associates future events with their identity.
 
-### `journium.capturePageview(properties?)`
-Manually capture pageview events.
+**Parameters:**
+- `distinctId: string` - Unique user identifier
+- `attributes?: Record<string, unknown>` - Optional user attributes
 
-```javascript
-// Simple pageview
-journium.capturePageview();
+#### `reset(): void`
+Resets user identity, typically called on logout.
 
-// Pageview with custom properties
-journium.capturePageview({
-  section: 'pricing',
-  experiment_variant: 'v2'
-});
-```
+**Returns:** `void`
 
-### `journium.startAutocapture()` / `journium.stopAutocapture()`
-Control automatic event capture for clicks, pageviews, and form interactions.
+#### `capturePageview(properties?: Record<string, unknown>): void`
+Manually captures pageview events.
 
-```javascript
-// Start automatic capture
-journium.startAutocapture();
+**Parameters:**
+- `properties?: Record<string, unknown>` - Optional pageview properties
 
-// Stop automatic capture
-journium.stopAutocapture();
+#### `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;
+}
 ```
 
-### `journium.flush()`
-Manually send queued events to the server.
+#### `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;
+  };
+}
+```
 
-```javascript
-await journium.flush();
+#### `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
+}
 ```
 
-### `journium.destroy()`
-Clean up the SDK and send any remaining events.
+### Browser Support
 
-```javascript
-journium.destroy();
+- ✅ Modern browsers (ES2017+)
+- ✅ Chrome 60+
+- ✅ Firefox 55+
+- ✅ Safari 11+
+- ✅ Edge 79+
+
+### Bundle Formats
+
+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
+
+#### UMD Usage
+
+```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>
 ```

package/dist/JourniumAnalytics.d.ts

@@ -0,0 +1,26 @@
+import { JourniumConfig } from '@journium/core';
+export declare class JourniumAnalytics {
+    private client;
+    private pageviewTracker;
+    private autocaptureTracker;
+    private config;
+    private autocaptureEnabled;
+    constructor(config: JourniumConfig);
+    private resolveAutocaptureOptions;
+    track(event: string, properties?: Record<string, unknown>): void;
+    identify(distinctId: string, attributes?: Record<string, unknown>): void;
+    reset(): void;
+    capturePageview(properties?: Record<string, unknown>): void;
+    startAutocapture(): void;
+    stopAutocapture(): void;
+    flush(): Promise<void>;
+    getEffectiveOptions(): import("@journium/core").JourniumLocalOptions;
+    destroy(): void;
+}
+export declare const init: (config: JourniumConfig) => JourniumAnalytics;
+declare const _default: {
+    init: (config: JourniumConfig) => JourniumAnalytics;
+    JourniumAnalytics: typeof JourniumAnalytics;
+};
+export default _default;
+//# sourceMappingURL=JourniumAnalytics.d.ts.map

package/dist/JourniumAnalytics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"JourniumAnalytics.d.ts","sourceRoot":"","sources":["../src/JourniumAnalytics.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAsB,MAAM,gBAAgB,CAAC;AAKpE,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,CAAU;gBAExB,MAAM,EAAE,cAAc;IAYlC,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;IAcxB,eAAe,IAAI,IAAI;IAMjB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAI5B,mBAAmB;IAInB,OAAO,IAAI,IAAI;CAKhB;AAED,eAAO,MAAM,IAAI,GAAI,QAAQ,cAAc,KAAG,iBAE7C,CAAC;;mBAF2B,cAAc,KAAG,iBAAiB;;;AAI/D,wBAA2C"}

package/dist/JourniumClient.d.ts

@@ -0,0 +1,25 @@
+import { JourniumConfig, JourniumLocalOptions } from '@journium/core';
+export declare class JourniumClient {
+    private config;
+    private effectiveOptions;
+    private queue;
+    private flushTimer;
+    private initialized;
+    private identityManager;
+    private optionsStorageKey;
+    constructor(config: JourniumConfig);
+    private loadCachedOptions;
+    private saveCachedOptions;
+    private initializeSync;
+    private fetchRemoteOptionsAsync;
+    private fetchAndCacheRemoteOptions;
+    private startFlushTimer;
+    private sendEvents;
+    identify(distinctId: string, attributes?: Record<string, unknown>): void;
+    reset(): void;
+    track(event: string, properties?: Record<string, unknown>): void;
+    flush(): Promise<void>;
+    destroy(): void;
+    getEffectiveOptions(): JourniumLocalOptions;
+}
+//# sourceMappingURL=JourniumClient.d.ts.map

package/dist/JourniumClient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"JourniumClient.d.ts","sourceRoot":"","sources":["../src/JourniumClient.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiB,cAAc,EAAE,oBAAoB,EAAwH,MAAM,gBAAgB,CAAC;AAE3M,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;gBAEvB,MAAM,EAAE,cAAc;IAsClC,OAAO,CAAC,iBAAiB;IAgBzB,OAAO,CAAC,iBAAiB;IAczB,OAAO,CAAC,cAAc;YA0BR,uBAAuB;YAOvB,0BAA0B;IAyCxC,OAAO,CAAC,eAAe;YAWT,UAAU;IA8BxB,QAAQ,CAAC,UAAU,EAAE,MAAM,EAAE,UAAU,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GAAG,IAAI;IAyB5E,KAAK,IAAI,IAAI;IAiBb,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GAAG,IAAI;IA4C9D,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAmB5B,OAAO,IAAI,IAAI;IAQf,mBAAmB,IAAI,oBAAoB;CAG5C"}

package/dist/autocapture.d.ts

@@ -1,23 +1,11 @@
-import { JourniumClient } from './client';
-export interface AutocaptureConfig {
-    captureClicks?: boolean;
-    captureFormSubmits?: boolean;
-    captureFormChanges?: boolean;
-    captureTextSelection?: boolean;
-    ignoreClasses?: string[];
-    ignoreElements?: string[];
-    captureContentText?: boolean;
-}
-export interface AutocaptureEvent {
-    event: string;
-    properties: Record<string, any>;
-}
+import { JourniumClient } from './JourniumClient';
+import { AutocaptureOptions } from '@journium/core';
 export declare class AutocaptureTracker {
     private client;
-    private config;
+    private options;
     private listeners;
     private isActive;
-    constructor(client: JourniumClient, config?: AutocaptureConfig);
+    constructor(client: JourniumClient, options?: AutocaptureOptions);
     start(): void;
     stop(): void;
     private addClickListener;

package/dist/autocapture.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"autocapture.d.ts","sourceRoot":"","sources":["../src/autocapture.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAG1C,MAAM,WAAW,iBAAiB;IAChC,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAC9B;AAED,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CACjC;AAED,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,MAAM,CAAiB;IAC/B,OAAO,CAAC,MAAM,CAAoB;IAClC,OAAO,CAAC,SAAS,CAAyC;IAC1D,OAAO,CAAC,QAAQ,CAAkB;gBAEtB,MAAM,EAAE,cAAc,EAAE,MAAM,GAAE,iBAAsB;IAclE,KAAK,IAAI,IAAI;IAwBb,IAAI,IAAI,IAAI;IAcZ,OAAO,CAAC,gBAAgB;IAoBxB,OAAO,CAAC,qBAAqB;IAoB7B,OAAO,CAAC,qBAAqB;IAoB7B,OAAO,CAAC,wBAAwB;IAuBhC,OAAO,CAAC,mBAAmB;IA2B3B,OAAO,CAAC,aAAa;IAKrB,OAAO,CAAC,oBAAoB;IAiE5B,OAAO,CAAC,iBAAiB;IAsBzB,OAAO,CAAC,kBAAkB;IAuC1B,OAAO,CAAC,cAAc;IActB,OAAO,CAAC,cAAc;IAiBtB,OAAO,CAAC,gBAAgB;IAqFxB,OAAO,CAAC,eAAe;CAKxB"}
+{"version":3,"file":"autocapture.d.ts","sourceRoot":"","sources":["../src/autocapture.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,EAAa,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAE/D,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,MAAM,CAAiB;IAC/B,OAAO,CAAC,OAAO,CAAqB;IACpC,OAAO,CAAC,SAAS,CAAyC;IAC1D,OAAO,CAAC,QAAQ,CAAkB;gBAEtB,MAAM,EAAE,cAAc,EAAE,OAAO,GAAE,kBAAuB;IAcpE,KAAK,IAAI,IAAI;IAwBb,IAAI,IAAI,IAAI;IAcZ,OAAO,CAAC,gBAAgB;IAoBxB,OAAO,CAAC,qBAAqB;IAoB7B,OAAO,CAAC,qBAAqB;IAoB7B,OAAO,CAAC,wBAAwB;IAuBhC,OAAO,CAAC,mBAAmB;IA2B3B,OAAO,CAAC,aAAa;IAKrB,OAAO,CAAC,oBAAoB;IAiE5B,OAAO,CAAC,iBAAiB;IAsBzB,OAAO,CAAC,kBAAkB;IAuC1B,OAAO,CAAC,cAAc;IActB,OAAO,CAAC,cAAc;IAiBtB,OAAO,CAAC,gBAAgB;IAqFxB,OAAO,CAAC,eAAe;CAKxB"}