@altertable/altertable-js 0.4.0 → 0.5.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-present Altertable
+
+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

@@ -0,0 +1,306 @@
+# @altertable/altertable-js
+
+JavaScript SDK for capturing and sending analytics events to Altertable.
+
+## Installation
+
+```bash
+npm install @altertable/altertable-js
+# or
+pnpm add @altertable/altertable-js
+# or
+yarn add @altertable/altertable-js
+# or
+bun add @altertable/altertable-js
+```
+
+## Quick Start
+
+```javascript
+import { altertable } from '@altertable/altertable-js';
+
+// Initialize with your API key
+altertable.init('YOUR_API_KEY');
+
+// Track an event
+altertable.track('Step Completed', {
+  step: 1,
+});
+
+// Identify a user
+altertable.identify('u_01jza857w4f23s1hf2s61befmw', {
+  email: 'john.doe@example.com',
+  name: 'John Doe',
+  company: 'Acme Corp',
+  role: 'Software Engineer',
+});
+
+// Update user traits
+altertable.updateTraits({
+  onboarding_completed: true,
+});
+```
+
+## Features
+
+- **Automatic page view tracking** – Captures page views automatically
+- **Session management** – Handles visitor and session IDs automatically
+- **Event queuing** – Queues events when offline or consent is pending
+- **Privacy compliance** – Built-in tracking consent management
+- **Multiple storage options** – localStorage, cookies, or both
+- **TypeScript support** – Full TypeScript definitions included
+- **Lightweight** – Minimal bundle size with no external dependencies
+
+## API Reference
+
+### Initialization
+
+#### `altertable.init(apiKey, config?)`
+
+Initializes the Altertable SDK with your API key and optional configuration.
+
+**Parameters:**
+
+| Parameter | Type                                    | Required | Description             |
+| --------- | --------------------------------------- | -------- | ----------------------- |
+| `apiKey`  | `string`                                | Yes      | Your Altertable API key |
+| `config`  | [`AltertableConfig`](#altertableconfig) | No       | Configuration options   |
+
+**Example:**
+
+```javascript
+altertable.init('YOUR_API_KEY', {
+  environment: 'development',
+});
+```
+
+### Event Tracking
+
+#### `altertable.track(event, properties?)`
+
+Tracks a custom event with optional properties.
+
+**Parameters:**
+
+| Parameter    | Type                                  | Required | Default | Description             |
+| ------------ | ------------------------------------- | -------- | ------- | ----------------------- |
+| `event`      | `string`                              | Yes      | -       | The event name          |
+| `properties` | [`EventProperties`](#eventproperties) | No       | `{}`    | Custom event properties |
+
+**Example:**
+
+```javascript
+altertable.track('Purchase Completed', {
+  product_id: 'p_01jza8fr5efvgbxxdd1bwkd0m5',
+  amount: 29.99,
+  currency: 'USD',
+});
+```
+
+#### `altertable.page(url)`
+
+Tracks a page view event.
+
+When [`autoCapture`](#autocapture) is enabled, this method is automatically called when the page URL changes.
+
+**Parameters:**
+
+| Parameter | Type     | Required | Description  |
+| --------- | -------- | -------- | ------------ |
+| `url`     | `string` | Yes      | The page URL |
+
+**Example:**
+
+```javascript
+altertable.page('https://example.com/products');
+```
+
+### User Identification
+
+#### `altertable.identify(userId, traits?)`
+
+Identifies a user with their ID and optional traits.
+
+**Parameters:**
+
+| Parameter | Type                        | Required | Default | Description                  |
+| --------- | --------------------------- | -------- | ------- | ---------------------------- |
+| `userId`  | `string`                    | Yes      | -       | The user's unique identifier |
+| `traits`  | [`UserTraits`](#usertraits) | No       | `{}`    | User properties              |
+
+**Example:**
+
+```javascript
+altertable.identify('u_01jza857w4f23s1hf2s61befmw', {
+  email: 'john.doe@example.com',
+  name: 'John Doe',
+  company: 'Acme Corp',
+  role: 'Software Engineer',
+});
+```
+
+#### `altertable.updateTraits(traits)`
+
+Updates user traits for the current user.
+
+**Parameters:**
+
+| Parameter | Type                        | Required | Description               |
+| --------- | --------------------------- | -------- | ------------------------- |
+| `traits`  | [`UserTraits`](#usertraits) | Yes      | User properties to update |
+
+**Example:**
+
+```javascript
+altertable.updateTraits({
+  onboarding_completed: true,
+});
+```
+
+### Session Management
+
+#### `altertable.reset(options?)`
+
+Resets visitor and session IDs.
+
+**Parameters:**
+
+| Parameter                | Type      | Required | Default | Description                 |
+| ------------------------ | --------- | -------- | ------- | --------------------------- |
+| `options`                | `object`  | No       | `{}`    | Reset options               |
+| `options.resetVisitorId` | `boolean` | No       | `false` | Whether to reset visitor ID |
+| `options.resetSessionId` | `boolean` | No       | `true`  | Whether to reset session ID |
+
+**Example:**
+
+```javascript
+// Reset session only (default)
+altertable.reset();
+
+// Reset both visitor and session
+altertable.reset({
+  resetVisitorId: true,
+  resetSessionId: true,
+});
+```
+
+### Configuration
+
+#### `altertable.configure(updates)`
+
+Updates the configuration after initialization.
+
+**Parameters:**
+
+| Parameter | Type                                             | Required | Description           |
+| --------- | ------------------------------------------------ | -------- | --------------------- |
+| `updates` | [`Partial<AltertableConfig>`](#altertableconfig) | Yes      | Configuration updates |
+
+**Example:**
+
+```javascript
+altertable.configure({
+  trackingConsent: 'granted',
+});
+```
+
+### Privacy & Consent
+
+#### `altertable.getTrackingConsent()`
+
+Returns the current tracking consent state.
+
+**Returns:** [`TrackingConsentType`](#trackingconsenttype)
+
+**Example:**
+
+```javascript
+const consent = altertable.getTrackingConsent();
+if (consent === 'granted') {
+  // Tracking is allowed
+}
+```
+
+## Types
+
+### `AltertableConfig`
+
+Configuration options for the Altertable SDK.
+
+| Property          | Type                                          | Default                       | Description                                            |
+| ----------------- | --------------------------------------------- | ----------------------------- | ------------------------------------------------------ |
+| `baseUrl`         | `string`                                      | `"https://api.altertable.ai"` | The base URL of the Altertable API                     |
+| `environment`     | `string`                                      | `"production"`                | The environment of the application                     |
+| `autoCapture`     | `boolean`                                     | `true`                        | Whether to automatically capture page views and events |
+| `release`         | `string`                                      | -                             | The release ID of the application                      |
+| `debug`           | `boolean`                                     | `false`                       | Whether to log events to the console                   |
+| `persistence`     | [`StorageType`](#storagetype)                 | `"localStorage+cookie"`       | The persistence strategy for storing IDs               |
+| `trackingConsent` | [`TrackingConsentType`](#trackingconsenttype) | `"pending"`                   | The tracking consent state                             |
+
+### `EventProperties`
+
+Custom properties for events.
+
+```typescript
+type EventProperties = Record<string, unknown>;
+```
+
+**Example:**
+
+```javascript
+{
+  product_id: 'p_01jza8fr5efvgbxxdd1bwkd0m5',
+  amount: 29.99,
+  currency: 'USD',
+  category: 'electronics',
+  user_type: 'premium'
+}
+```
+
+### `UserTraits`
+
+User properties for identification.
+
+```typescript
+type UserTraits = Record<string, unknown>;
+```
+
+**Example:**
+
+```javascript
+{
+  email: 'john.doe@example.com',
+  name: 'John Doe',
+  company: 'Acme Corp',
+  role: 'Software Engineer',
+  plan: 'premium',
+  signup_date: '2024-01-15'
+}
+```
+
+### `StorageType`
+
+Available storage strategies.
+
+| Value                   | Description                           |
+| ----------------------- | ------------------------------------- |
+| `"localStorage"`        | Use localStorage only                 |
+| `"sessionStorage"`      | Use sessionStorage only               |
+| `"cookie"`              | Use cookies only                      |
+| `"memory"`              | Use in-memory storage (not persisted) |
+| `"localStorage+cookie"` | Use localStorage with cookie fallback |
+
+### `TrackingConsentType`
+
+Available tracking consent states.
+
+| Value         | Description                           |
+| ------------- | ------------------------------------- |
+| `"granted"`   | User has granted consent for tracking |
+| `"denied"`    | User has denied consent for tracking  |
+| `"pending"`   | User hasn't made a decision yet       |
+| `"dismissed"` | User dismissed the consent prompt     |
+
+## License
+
+[MIT](./LICENSE)

package/dist/index.d.mts

@@ -1,4 +1,19 @@
-interface Config {
+declare const TrackingConsent: {
+    readonly DENIED: "denied";
+    readonly DISMISSED: "dismissed";
+    readonly GRANTED: "granted";
+    readonly PENDING: "pending";
+};
+type TrackingConsentType = (typeof TrackingConsent)[keyof typeof TrackingConsent];
+
+type StorageType = 'localStorage' | 'sessionStorage' | 'cookie' | 'memory' | 'localStorage+cookie';
+
+type EventProperties = Record<string, unknown>;
+interface UserTraits extends Record<string, unknown> {
+    email?: string;
+}
+
+interface AltertableConfig {
     /**
      * The base URL of the Altertable API.
      * @default https://api.altertable.ai
@@ -19,27 +34,51 @@ interface Config {
      * This is helpful to identify the version of the application an event is coming from.
      */
     release?: string;
+    /**
+     * Whether to log events to the console.
+     * @default false
+     */
+    debug?: boolean;
+    /**
+     * The persistence strategy for storing IDs.
+     * @default "localStorage+cookie"
+     */
+    persistence?: StorageType;
+    /**
+     * The tracking consent state.
+     * @default "pending"
+     */
+    trackingConsent?: TrackingConsentType;
 }
-type EventProperties = Record<string, unknown>;
 declare class Altertable {
-    private _lastUrl;
     private _apiKey;
+    private _cleanupAutoCapture;
     private _config;
-    private _sessionId;
-    private _visitorId;
-    private _userId;
+    private _eventQueue;
+    private _isInitialized;
+    private _lastUrl;
+    private _logger;
     private _referrer;
+    private _sessionManager;
+    private _storage;
+    private _storageKey;
     constructor();
-    init(apiKey: string, config?: Config): void;
-    identify(userId: string): void;
+    init(apiKey: string, config?: AltertableConfig): () => void;
+    configure(updates: Partial<AltertableConfig>): void;
+    private _handleAutoCaptureChange;
+    identify(userId: string, traits?: UserTraits): void;
+    updateTraits(traits: UserTraits): void;
+    reset({ resetVisitorId, resetSessionId, }?: {
+        resetVisitorId?: boolean;
+        resetSessionId?: boolean;
+    }): void;
     page(url: string): void;
     track(event: string, properties?: EventProperties): void;
+    getTrackingConsent(): TrackingConsentType;
     private _checkForChanges;
+    private _getEventContext;
+    private _processEvent;
     private _request;
-    private _getSessionId;
-    private _getVisitorId;
-    private _generateId;
-    private _getViewport;
 }
 
 declare global {
@@ -49,4 +88,4 @@ declare global {
 }
 declare const altertable: Altertable;
 
-export { Altertable, altertable };
+export { Altertable, type AltertableConfig, TrackingConsent, altertable };

package/dist/index.d.ts

@@ -1,4 +1,19 @@
-interface Config {
+declare const TrackingConsent: {
+    readonly DENIED: "denied";
+    readonly DISMISSED: "dismissed";
+    readonly GRANTED: "granted";
+    readonly PENDING: "pending";
+};
+type TrackingConsentType = (typeof TrackingConsent)[keyof typeof TrackingConsent];
+
+type StorageType = 'localStorage' | 'sessionStorage' | 'cookie' | 'memory' | 'localStorage+cookie';
+
+type EventProperties = Record<string, unknown>;
+interface UserTraits extends Record<string, unknown> {
+    email?: string;
+}
+
+interface AltertableConfig {
     /**
      * The base URL of the Altertable API.
      * @default https://api.altertable.ai
@@ -19,27 +34,51 @@ interface Config {
      * This is helpful to identify the version of the application an event is coming from.
      */
     release?: string;
+    /**
+     * Whether to log events to the console.
+     * @default false
+     */
+    debug?: boolean;
+    /**
+     * The persistence strategy for storing IDs.
+     * @default "localStorage+cookie"
+     */
+    persistence?: StorageType;
+    /**
+     * The tracking consent state.
+     * @default "pending"
+     */
+    trackingConsent?: TrackingConsentType;
 }
-type EventProperties = Record<string, unknown>;
 declare class Altertable {
-    private _lastUrl;
     private _apiKey;
+    private _cleanupAutoCapture;
     private _config;
-    private _sessionId;
-    private _visitorId;
-    private _userId;
+    private _eventQueue;
+    private _isInitialized;
+    private _lastUrl;
+    private _logger;
     private _referrer;
+    private _sessionManager;
+    private _storage;
+    private _storageKey;
     constructor();
-    init(apiKey: string, config?: Config): void;
-    identify(userId: string): void;
+    init(apiKey: string, config?: AltertableConfig): () => void;
+    configure(updates: Partial<AltertableConfig>): void;
+    private _handleAutoCaptureChange;
+    identify(userId: string, traits?: UserTraits): void;
+    updateTraits(traits: UserTraits): void;
+    reset({ resetVisitorId, resetSessionId, }?: {
+        resetVisitorId?: boolean;
+        resetSessionId?: boolean;
+    }): void;
     page(url: string): void;
     track(event: string, properties?: EventProperties): void;
+    getTrackingConsent(): TrackingConsentType;
     private _checkForChanges;
+    private _getEventContext;
+    private _processEvent;
     private _request;
-    private _getSessionId;
-    private _getVisitorId;
-    private _generateId;
-    private _getViewport;
 }
 
 declare global {
@@ -49,4 +88,4 @@ declare global {
 }
 declare const altertable: Altertable;
 
-export { Altertable, altertable };
+export { Altertable, type AltertableConfig, TrackingConsent, altertable };