@journium/js 1.0.0 → 1.0.1

package/README.md

@@ -8,63 +8,108 @@
 
 Track events, pageviews, and user interactions with ease. Perfect for SPAs, vanilla JavaScript apps, and any web application.
 
-## 🚀 Quick Start
-
-### Installation
+## Installation
 
+### npm
 ```bash
 npm install @journium/js
 ```
 
-### Basic Usage
+### pnpm
+```bash
+pnpm add @journium/js
+```
+
+### yarn
+```bash
+yarn add @journium/js
+```
+
+## Basic Setup
+
+### Initialize Journium
+Initialize the Journium SDK with your publishable key to start tracking events.
 
 ```javascript
 import { init } from '@journium/js';
 
-// Initialize Journium
 const journium = init({
-  token: 'your-journium-token',
-  apiHost: 'https://your-journium-instance.com'
+  publishableKey: 'your-journium-publishable-key'
 });
+```
+
+### Track a Custom Event
+Track user actions and business events with custom properties.
 
-// Track events
+```javascript
 journium.track('button_clicked', {
   button_name: 'signup',
-  page: 'homepage'
+  page: 'homepage',
+  user_type: 'visitor'
 });
+```
 
-// Track pageviews (optional - can be automatic)
-journium.capturePageview();
+### Identify a User
+Identify users when they log in or sign up to connect their actions across sessions.
 
-// Start auto-capture - automatically enabled when calling startAutoCapture()
-// Autocapture is enabled by default, but you need to start it:
-journium.startAutoCapture();
+```javascript
+journium.identify('user_12345', {
+  name: 'John Doe',
+  email: 'john@example.com',
+  plan: 'premium'
+});
 ```
 
-## 📖 API Reference
+### Reset User Identity
+Reset user identity when they log out to ensure privacy and accurate tracking.
 
-### Initialization
+```javascript
+journium.reset();
+```
 
-#### `init(config: JourniumConfig)`
+## Advanced Setup
 
-Initialize the Journium SDK with your configuration.
+You can override default configurations:
 
 ```javascript
+import { init } from '@journium/js';
+
 const journium = init({
-  token: 'your-journium-token',          // Required: Your project token
-  apiHost: 'https://api.journium.com',   // Required: Your API endpoint
-  debug: false,                          // Optional: Enable debug logs
-  flushAt: 20,                          // Optional: Flush after N events
-  flushInterval: 10000,                 // Optional: Flush interval (ms)
-  autocapture: true,                    // Optional: (default: true) - set false to disable
-  sessionTimeout: 1800000               // Optional: Session timeout (30m)
+  publishableKey: 'your-journium-publishable-key',
+  apiHost: 'https://your-custom-instance.com', // Optional: defaults to 'https://events.journium.app'
+  config: {
+    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)
+    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();
 ```
 
-### Event Tracking
+## API Reference
 
-#### `journium.track(eventName, properties?)`
+### `init(config: JourniumConfig)`
+Initialize the Journium SDK with your configuration.
 
+```javascript
+const journium = init({
+  publishableKey: 'your-journium-publishable-key',
+  apiHost: 'https://events.journium.app', // Optional
+  config: { /* optional local config */ }
+});
+```
+
+### `journium.track(eventName, properties?)`
 Track custom events with optional properties.
 
 ```javascript
@@ -75,46 +120,29 @@ journium.track('feature_used');
 journium.track('purchase_completed', {
   product_id: 'prod_123',
   amount: 29.99,
-  currency: 'USD',
-  category: 'digital',
-  plan: 'premium'
-});
-
-// User action with context
-journium.track('video_played', {
-  video_id: 'intro-2024',
-  video_length: 120,
-  quality: '1080p',
-  autoplay: false
+  currency: 'USD'
 });
 ```
 
-#### `journium.identify(distinctId, attributes?)`
-
-Identify a user when they log in or sign up. This method should be used instead of tracking user login as a custom event.
+### `journium.identify(distinctId, attributes?)`
+Identify a user when they log in or sign up.
 
 ```javascript
-// When user logs in or signs up
 journium.identify('user_12345', {
   name: 'John Doe',
-  email: 'john@example.com'
+  email: 'john@example.com',
+  signup_date: '2024-01-15'
 });
-
-// Minimal identification (just user ID)
-journium.identify('user_67890');
 ```
 
-#### `journium.reset()`
-
-Reset user identity when they log out. This generates a new anonymous distinct ID and should be called on user logout.
+### `journium.reset()`
+Reset user identity when they log out.
 
 ```javascript
-// When user logs out
 journium.reset();
 ```
 
-#### `journium.capturePageview(properties?)`
-
+### `journium.capturePageview(properties?)`
 Manually capture pageview events.
 
 ```javascript
@@ -124,243 +152,31 @@ journium.capturePageview();
 // Pageview with custom properties
 journium.capturePageview({
   section: 'pricing',
-  experiment_variant: 'v2',
-  user_plan: 'free'
+  experiment_variant: 'v2'
 });
 ```
 
-### Auto-Capture
-
-#### `journium.startAutoCapture()` / `journium.stopAutoCapture()`
-
+### `journium.startAutocapture()` / `journium.stopAutocapture()`
 Control automatic event capture for clicks, pageviews, and form interactions.
 
-**Note:** Autocapture is enabled by default. You can disable it entirely with `autocapture: false` in your config, or control it programmatically:
-
 ```javascript
-// Start capturing events automatically (autocapture is enabled by default)
-journium.startAutoCapture();
+// Start automatic capture
+journium.startAutocapture();
 
 // Stop automatic capture
-journium.stopAutoCapture();
-
-// Or disable entirely in configuration:
-const journium = init({
-  token: 'your-token',
-  apiHost: 'your-api.com',
-  autocapture: false  // Disables all autocapture functionality
-});
-```
-
-Configure what gets auto-captured:
-
-```javascript
-const journium = init({
-  token: 'your-token',
-  apiHost: 'https://your-api.com',
-  autocapture: {
-    captureClicks: true,              // Track click events
-    captureFormSubmits: true,         // Track form submissions
-    captureFormChanges: false,        // Track form field changes
-    captureTextSelection: false,      // Track text selections
-    captureContentText: true,         // Include element text
-    ignoreClasses: ['no-track'],      // CSS classes to ignore
-    ignoreElements: ['input[type="password"]'] // Elements to ignore
-  }
-});
+journium.stopAutocapture();
 ```
 
-### Data Management
-
-#### `journium.flush()`
-
+### `journium.flush()`
 Manually send queued events to the server.
 
 ```javascript
-// Send all pending events immediately
 await journium.flush();
 ```
 
-#### `journium.destroy()`
-
+### `journium.destroy()`
 Clean up the SDK and send any remaining events.
 
 ```javascript
-// Cleanup before page unload
 journium.destroy();
-```
-
-## 🏗️ Event Properties
-
-### Automatic Properties
-
-Journium automatically includes these properties with every event:
-
-- `$device_id` - Unique device identifier (persistent across user sessions)
-- `$session_id` - Current session ID
-- `distinct_id` - User identifier (anonymous until `identify()` is called)
-- `$is_identified` - Whether the user has been identified (true/false)
-- `$current_url` - Current page URL
-- `$pathname` - URL pathname
-- `$browser` - Browser name (Chrome, Firefox, etc.)
-- `$os` - Operating system (Windows, macOS, etc.)
-- `$device_type` - Device type (desktop, mobile, tablet)
-- `$lib_version` - SDK version
-- `$platform` - Always "web"
-
-### Custom Properties
-
-Add any custom properties to track additional context:
-
-```javascript
-journium.track('feature_used', {
-  // Your custom properties
-  feature_name: 'dark_mode',
-  user_plan: 'premium',
-  user_role: 'admin',
-  experiment_group: 'control',
-  
-  // Nested objects work too
-  user_preferences: {
-    theme: 'dark',
-    language: 'en',
-    timezone: 'UTC'
-  }
-});
-```
-
-## 🔧 Configuration Options
-
-### Required Configuration
-
-```javascript
-{
-  token: 'your-journium-token',        // Your project token from Journium
-  apiHost: 'https://api.journium.com'  // Your Journium API endpoint
-}
-```
-
-### Optional Configuration
-
-```javascript
-{
-  debug: false,                        // Enable console logging
-  flushAt: 20,                        // Send events after N events queued
-  flushInterval: 10000,               // Send events every N milliseconds
-  sessionTimeout: 1800000,            // Session timeout (30 minutes)
-  autocapture: true                   // Default: true - set false to disable auto-capture
-}
-```
-
-### Advanced Auto-Capture Configuration
-
-```javascript
-{
-  autocapture: {
-    captureClicks: true,              // Capture click events
-    captureFormSubmits: true,         // Capture form submissions  
-    captureFormChanges: false,        // Capture form field changes
-    captureTextSelection: false,      // Capture text selection events
-    captureContentText: true,         // Include element text content
-    ignoreClasses: [                  // CSS classes to ignore
-      'no-track',
-      'sensitive-data',
-      'admin-only'
-    ],
-    ignoreElements: [                 // CSS selectors to ignore
-      'input[type="password"]',
-      '.credit-card-input',
-      '[data-private]'
-    ]
-  }
-}
-```
-
-## 🔒 Privacy & Security
-
-Journium is designed with privacy in mind:
-
-- **No PII by default** - We don't automatically collect personally identifiable information
-- **Configurable tracking** - Exclude sensitive elements and data
-- **Secure transmission** - All data sent over HTTPS
-- **Session-based** - Automatic session management without persistent user tracking
-
-### Excluding Sensitive Data
-
-```javascript
-// Method 1: CSS classes
-<button class="signup-btn no-track">Sign Up</button>
-
-// Method 2: Configuration
-const journium = init({
-  token: 'your-token',
-  apiHost: 'your-api.com',
-  autocapture: {
-    ignoreClasses: ['no-track', 'sensitive'],
-    ignoreElements: ['input[type="password"]', '.credit-card']
-  }
-});
-```
-
-## 🌐 Browser Support
-
-- ✅ **Chrome** 60+
-- ✅ **Firefox** 55+  
-- ✅ **Safari** 12+
-- ✅ **Edge** 79+
-- ✅ **Mobile browsers** (iOS Safari, Chrome Mobile)
-
-## 📝 TypeScript Support
-
-Full TypeScript support with complete type definitions:
-
-```typescript
-import { init, JourniumConfig, Journium } from '@journium/js';
-
-const config: JourniumConfig = {
-  token: 'your-token',
-  apiHost: 'https://api.journium.com',
-  debug: true
-};
-
-const journium: Journium = init(config);
-
-// Type-safe event tracking
-journium.track('user_action', {
-  action_type: 'click',
-  element_id: 'signup-button',
-  timestamp: new Date().toISOString()
-});
-```
-
-## 🔗 Related Packages
-
-Part of the Journium JavaScript SDK ecosystem:
-
-- **[@journium/react](https://npmjs.com/package/@journium/react)** - React integration with hooks and providers
-- **[@journium/nextjs](https://npmjs.com/package/@journium/nextjs)** - Next.js integration with SSR support
-- **[@journium/node](https://npmjs.com/package/@journium/node)** - Node.js server-side tracking
-- **[@journium/core](https://npmjs.com/package/@journium/core)** - Core utilities and types
-
-## 📖 Documentation
-
-For complete documentation, guides, and examples:
-
-- **[Documentation](https://docs.journium.app)** - Complete guides and API reference
-- **[Getting Started](https://docs.journium.app/getting-started)** - Quick setup guide
-- **[Examples](https://docs.journium.app/examples)** - Code examples and patterns
-
-## 🤝 Contributing
-
-We welcome contributions! Please see our [Contributing Guide](https://github.com/journium/journium-js/blob/main/CONTRIBUTING.md).
-
-## 📄 License
-
-MIT License - see [LICENSE](https://github.com/journium/journium-js/blob/main/LICENSE) file for details.
-
-## 🆘 Support
-
-- **📚 Docs**: [docs.journium.app](https://docs.journium.app)
-- **🐛 Issues**: [GitHub Issues](https://github.com/journium/journium-js/issues)
-- **💬 Discussions**: [GitHub Discussions](https://github.com/journium/journium-js/discussions)
-- **📧 Email**: support@journium.com
+```

package/dist/client.d.ts

@@ -1,6 +1,7 @@
 import { JourniumConfig } from '@journium/core';
 export declare class JourniumClient {
     private config;
+    private effectiveConfig;
     private queue;
     private flushTimer;
     private initialized;

package/dist/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiB,cAAc,EAAgH,MAAM,gBAAgB,CAAC;AAE7K,qBAAa,cAAc;IACzB,OAAO,CAAC,MAAM,CAAkB;IAChC,OAAO,CAAC,KAAK,CAAuB;IACpC,OAAO,CAAC,UAAU,CAA+C;IACjE,OAAO,CAAC,WAAW,CAAkB;IACrC,OAAO,CAAC,eAAe,CAA0B;IACjD,OAAO,CAAC,gBAAgB,CAAU;gBAEtB,MAAM,EAAE,cAAc;IAyBlC,OAAO,CAAC,gBAAgB;IAgBxB,OAAO,CAAC,gBAAgB;IAcxB,OAAO,CAAC,cAAc;YAoDR,sBAAsB;YAOtB,yBAAyB;IA0CvC,OAAO,CAAC,eAAe;YAWT,UAAU;IA8BxB,QAAQ,CAAC,UAAU,EAAE,MAAM,EAAE,UAAU,GAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAM,GAAG,IAAI;IAyBxE,KAAK,IAAI,IAAI;IAiBb,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,GAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAM,GAAG,IAAI;IA4C1D,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAmB5B,OAAO,IAAI,IAAI;CAOhB"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiB,cAAc,EAAqI,MAAM,gBAAgB,CAAC;AAElM,qBAAa,cAAc;IACzB,OAAO,CAAC,MAAM,CAAkB;IAChC,OAAO,CAAC,eAAe,CAAuB;IAC9C,OAAO,CAAC,KAAK,CAAuB;IACpC,OAAO,CAAC,UAAU,CAA+C;IACjE,OAAO,CAAC,WAAW,CAAkB;IACrC,OAAO,CAAC,eAAe,CAA0B;IACjD,OAAO,CAAC,gBAAgB,CAAU;gBAEtB,MAAM,EAAE,cAAc;IAsClC,OAAO,CAAC,gBAAgB;IAgBxB,OAAO,CAAC,gBAAgB;IAcxB,OAAO,CAAC,cAAc;YA0BR,sBAAsB;YAOtB,yBAAyB;IAyCvC,OAAO,CAAC,eAAe;YAWT,UAAU;IA8BxB,QAAQ,CAAC,UAAU,EAAE,MAAM,EAAE,UAAU,GAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAM,GAAG,IAAI;IAyBxE,KAAK,IAAI,IAAI;IAiBb,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,GAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAM,GAAG,IAAI;IA4C1D,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAmB5B,OAAO,IAAI,IAAI;CAOhB"}