@athena-tracker/tracker 1.0.0 → 1.0.2

package/README.md

@@ -1,317 +1,243 @@
-# @athena/tracker
+# @athena-tracker/tracker
 
-> Behavioral analytics tracker with edge AI for React Native and Web
-
-## Features
-
-- ✅ 90+ behavioral event types auto-captured
-- ✅ On-device ML inference (<10ms latency)
-- ✅ Server-side fallback for OTA apps
-- ✅ Works on Web, iOS, Android
-- ✅ Zero configuration required
-- ✅ TypeScript support
+ATHENA Analytics tracker SDK wrapper for easy integration
 
 ## Installation
 
 ```bash
-npm install @athena/tracker
-```
-
-### For React Native with On-Device Inference
-
-```bash
-npm install @athena/tracker onnxruntime-react-native
+npm install @athena-tracker/tracker
 ```
 
-### For OTA Updates (Server-Side Inference)
-
-```bash
-npm install @athena/tracker
-```
-
-(No `onnxruntime-react-native` required - will automatically fall back to server-side inference)
-
-## Quick Start
+## Usage
 
-### React Native
+### Basic Setup
 
 ```typescript
-import AthenaTracker from '@athena/tracker';
+import { initTracker, identify, track, page } from '@athena-tracker/tracker';
+
+// Initialize the tracker
+const tracker = initTracker({
+  projectId: 'your-project-id',
+  apiKey: 'your-api-key',
+  sampleRate: 1.0, // Track 100% of sessions
+  recording: {
+    enabled: true,
+    sampleRate: 0.1, // Record 10% of sessions
+    maskAllInputs: true,
+  },
+  edgeAI: {
+    enabled: true,
+    webhook: {
+      url: 'https://your-backend.com/webhooks/athena',
+      enabled: true,
+    },
+  },
+});
 
-// Initialize tracker
-AthenaTracker.init({
-  appToken: 'at_live_xxxxx',
-  inferenceMode: 'auto', // Auto-detects environment
-  webhook: {
-    url: 'https://your-backend.com/webhooks/athena',
-    enabled: true
-  }
+// Load the tracker script
+await tracker.load();
+
+// Identify user
+identify('user-123', {
+  email: 'user@example.com',
+  name: 'John Doe',
+  plan: 'pro',
 });
-```
 
-### Web
+// Track custom events
+track('button_clicked', {
+  buttonId: 'cta-signup',
+  location: 'homepage',
+});
 
-```html
-<script src="https://tracker.pascal.cx/v1/tracker.min.js"></script>
-<script>
-  const tracker = new PascalTracker({
-    projectId: 'your-app-token',
-    edgeAI: {
-      enabled: true,
-      modelPath: 'https://tracker.pascal.cx/models/base_model_int8.onnx'
-    }
-  });
-</script>
+// Track page views
+page('Home Page', {
+  category: 'marketing',
+});
 ```
 
-## Configuration
+### React Integration
 
-### AthenaConfig
-
-```typescript
-interface AthenaConfig {
-  appToken: string;              // Required: App token from ATHENA provisioning
-  apiUrl?: string;               // Optional: API base URL (default: https://tracker.pascal.cx)
-  inferenceMode?: 'auto' | 'on-device' | 'server'; // Optional: Inference mode
-  modelPath?: string;            // Optional: ONNX model path (for on-device)
-  serverInferenceUrl?: string;   // Optional: Server inference endpoint
-  webhook?: WebhookConfig;       // Optional: Webhook configuration
-  batching?: BatchingConfig;     // Optional: Event batching
-  debug?: boolean;               // Optional: Debug mode
+```tsx
+import React, { useEffect } from 'react';
+import { initTracker } from '@athena-tracker/tracker';
+
+function App() {
+  useEffect(() => {
+    const tracker = initTracker({
+      projectId: 'your-project-id',
+      apiKey: 'your-api-key',
+    });
+
+    tracker.load().then(() => {
+      console.log('ATHENA tracker loaded');
+    });
+  }, []);
+
+  return <div>Your App</div>;
 }
 ```
 
-### Inference Modes
+### Next.js Integration
 
-#### Auto Mode (Recommended)
+```tsx
+// pages/_app.tsx
+import { useEffect } from 'react';
+import { initTracker } from '@athena-tracker/tracker';
+
+function MyApp({ Component, pageProps }) {
+  useEffect(() => {
+    if (typeof window !== 'undefined') {
+      const tracker = initTracker({
+        projectId: process.env.NEXT_PUBLIC_ATHENA_PROJECT_ID,
+        apiKey: process.env.NEXT_PUBLIC_ATHENA_API_KEY,
+      });
+
+      tracker.load();
+    }
+  }, []);
 
-Automatically detects whether `onnxruntime-react-native` is available:
+  return <Component {...pageProps} />;
+}
 
-```typescript
-AthenaTracker.init({
-  appToken: 'at_live_xxxxx',
-  inferenceMode: 'auto' // Default
-});
+export default MyApp;
 ```
 
-#### On-Device Mode (Forced)
+### Vue.js Integration
 
-Force on-device inference (requires `onnxruntime-react-native`):
+```javascript
+// main.js
+import { createApp } from 'vue';
+import { initTracker } from '@athena-tracker/tracker';
+import App from './App.vue';
 
-```typescript
-AthenaTracker.init({
-  appToken: 'at_live_xxxxx',
-  inferenceMode: 'on-device',
-  modelPath: '/path/to/model.onnx'
-});
-```
-
-#### Server Mode (Forced)
-
-Force server-side inference:
+const app = createApp(App);
 
-```typescript
-AthenaTracker.init({
-  appToken: 'at_live_xxxxx',
-  inferenceMode: 'server',
-  serverInferenceUrl: 'https://api.pascal.cx/v1/predict'
+// Initialize tracker
+const tracker = initTracker({
+  projectId: import.meta.env.VITE_ATHENA_PROJECT_ID,
+  apiKey: import.meta.env.VITE_ATHENA_API_KEY,
 });
-```
-
-## Webhook Integration
-
-Receive real-time predictions via webhooks:
 
-```typescript
-AthenaTracker.init({
-  appToken: 'at_live_xxxxx',
-  webhook: {
-    url: 'https://your-backend.com/webhooks/athena',
-    enabled: true,
-    retry: {
-      maxAttempts: 3,
-      backoffMs: 1000
-    }
-  }
+tracker.load().then(() => {
+  console.log('ATHENA tracker loaded');
 });
-```
 
-### Webhook Payload
-
-```json
-{
-  "user_id": "user_abc",
-  "session_id": "sess_123",
-  "predicted_class": "engaged_explorer",
-  "confidence": 0.85,
-  "archetype": "on_track",
-  "purchase_intent": 0.72,
-  "cart_abandonment_risk": 0.15,
-  "recommended_action": "Show 10% discount offer",
-  "urgency": "high",
-  "trigger_reason": "High-value cart ($249), 80% scroll depth, 45s time-on-page",
-  "timestamp": "2026-02-24T12:34:56Z"
-}
+app.mount('#app');
 ```
 
-## User Archetypes
-
-| Archetype | Description | Similarity Score |
-|-----------|-------------|------------------|
-| **fast_mover** | High purchase intent, quick decision-maker | >85% |
-| **on_track** | Steady browsing, likely to convert | 60-85% |
-| **slow_adopter** | Needs guidance, price-sensitive | 40-60% |
-| **at_risk** | Low engagement, high abandonment risk | <40% |
-| **different_path** | Unconventional browsing pattern | Unique |
-
 ## API Reference
 
-### AthenaTracker
+### `initTracker(config)`
 
-```typescript
-class AthenaTracker {
-  static init(config: AthenaConfig): Promise<void>
-  static identify(userId: string, traits?: Record<string, any>): void
-  static track(eventType: string, properties?: Record<string, any>): void
-  static getInferenceMode(): 'on-device' | 'server' | null
-  static getSessionId(): string | null
-}
-```
+Initialize the ATHENA tracker with configuration.
 
-### Methods
+**Parameters:**
+- `config.projectId` (required): Your ATHENA project ID
+- `config.apiKey` (required): Your ATHENA API key
+- `config.apiUrl` (optional): API endpoint URL (default: 'https://tracker.pascal.cx')
+- `config.sampleRate` (optional): Session sampling rate 0.0-1.0 (default: 1.0)
+- `config.recording` (optional): Recording configuration
+  - `enabled`: Enable session recording (default: true)
+  - `sampleRate`: Recording sampling rate 0.0-1.0 (default: 0.1)
+  - `maskAllInputs`: Mask all input fields (default: true)
+  - `maskInputOptions`: Specific input masking options
+- `config.edgeAI` (optional): Edge AI configuration
+  - `enabled`: Enable client-side ML predictions (default: true)
+  - `modelPath`: Custom ONNX model path
+  - `webhook`: Webhook configuration
 
-#### `init(config)`
+**Returns:** `AthenaTrackerSDK` instance
 
-Initialize the tracker with configuration.
+### `tracker.load()`
 
-```typescript
-await AthenaTracker.init({
-  appToken: 'at_live_xxxxx'
-});
-```
+Load the ATHENA tracker script asynchronously.
 
-#### `identify(userId, traits?)`
+**Returns:** `Promise<void>`
 
-Identify a user.
+### `identify(userId, properties?)`
 
-```typescript
-AthenaTracker.identify('user_123', {
-  email: 'user@example.com',
-  name: 'John Doe'
-});
-```
+Identify a user with optional properties.
+
+**Parameters:**
+- `userId`: Unique user identifier
+- `properties`: Optional user properties (email, name, etc.)
 
-#### `track(eventType, properties?)`
+### `track(eventName, properties?)`
 
 Track a custom event.
 
-```typescript
-AthenaTracker.track('button_click', {
-  button_id: 'checkout',
-  page: '/cart'
-});
-```
+**Parameters:**
+- `eventName`: Name of the event
+- `properties`: Optional event properties
 
-## React Native Components
+### `page(pageName?, properties?)`
 
-### AthenaOTAWrapper
+Track a page view.
 
-For apps using Expo OTA updates, wrap your app with `AthenaOTAWrapper`:
+**Parameters:**
+- `pageName`: Optional page name
+- `properties`: Optional page properties
 
-```tsx
-import { AthenaOTAWrapper } from '@athena/tracker';
-
-export default function App() {
-  return (
-    <AthenaOTAWrapper
-      loadingMessage="Loading..."
-      updateMessage="Updating..."
-    >
-      <YourApp />
-    </AthenaOTAWrapper>
-  );
-}
-```
+### `reset()`
 
-**What it does:**
-- Checks for OTA updates on app launch
-- Fetches and applies updates automatically
-- Forces immediate reload (<2 seconds)
-- Displays loading spinner during update
+Reset user identity (useful for logout).
 
-**Props:**
-- `loadingMessage` (string, optional): Message during initial load (default: "Loading...")
-- `updateMessage` (string, optional): Message during update (default: "Updating...")
+### `getSessionId()`
 
----
+Get the current session ID.
 
-### ReactNativeEventCapture
+**Returns:** `string | null`
 
-Advanced event capture for custom use cases:
+### `getUserId()`
 
-```tsx
-import { ReactNativeEventCapture } from '@athena/tracker';
-
-const capture = new ReactNativeEventCapture({
-  captureTouch: true,
-  captureNavigation: true,
-  captureLifecycle: true,
-  captureNetworkErrors: true,
-  batchSize: 10,
-  batchIntervalMs: 10000
-});
+Get the current user ID.
 
-// Start capturing
-capture.start();
+**Returns:** `string | null`
 
-// Track screen view manually
-capture.trackScreenView('ProductDetails', { productId: '123' });
+## Configuration Options
 
-// Track custom event
-capture.track('AddToCart', { productId: '123', price: 49.99 });
+### Session Recording
 
-// Stop capturing
-capture.stop();
+```typescript
+recording: {
+  enabled: true,          // Enable recording
+  sampleRate: 0.1,        // Record 10% of sessions
+  maskAllInputs: true,    // Mask all input fields
+  maskInputOptions: {
+    password: true,       // Mask password fields
+    email: true,          // Mask email fields
+  },
+  compressionLevel: 6,    // Compression level (1-9)
+  maxChunkSize: 102400,   // Max chunk size in bytes
+}
 ```
 
-**Configuration:**
-- `captureTouch` (boolean): Capture touch events (Tap, Swipe, LongPress)
-- `captureNavigation` (boolean): Capture screen navigation
-- `captureLifecycle` (boolean): Capture app lifecycle (Open, Background, Foreground)
-- `captureNetworkErrors` (boolean): Capture failed network requests
-- `batchSize` (number): Events per batch (default: 10)
-- `batchIntervalMs` (number): Batch interval in milliseconds (default: 10000)
-
-**Captured Events:**
-- `AppOpen`, `AppForeground`, `AppBackground`, `AppInactive`
-- `Tap`, `Swipe`, `LongPress`
-- `ScreenView`
-- `NetworkError`
+### Edge AI
 
-## Performance
+```typescript
+edgeAI: {
+  enabled: true,
+  modelPath: 'https://tracker.pascal.cx/models/base_model_int8.onnx',
+  webhook: {
+    url: 'https://your-backend.com/webhooks/athena',
+    enabled: true,
+  },
+}
+```
 
-- **Bundle size**: ~10MB (includes ONNX model for on-device mode)
-- **On-device inference latency**: <10ms P95
-- **Server-side inference latency**: <100ms P95
-- **Memory overhead**: <50MB
-- **Battery impact**: Negligible (<1%)
+## TypeScript Support
 
-## Browser Support
+Full TypeScript support with type definitions included.
 
-- Chrome/Edge 90+
-- Safari 14+
-- Firefox 88+
-- React Native 0.70+
+```typescript
+import type {
+  AthenaTrackerConfig,
+  UserProperties,
+  EventProperties,
+} from '@athena-tracker/tracker';
+```
 
 ## License
 
 MIT
-
-## Documentation
-
-Full documentation: https://docs.athena.ai/tracker
-
-## Support
-
-- Issues: https://github.com/RubaiyatF/Pascal/issues
-- Email: support@pascal.cx

package/dist/index.d.ts

@@ -1,13 +1,108 @@
 /**
- * @athena/tracker
- *
- * Behavioral analytics tracker with edge AI
- */
-export { AthenaTracker as default } from './tracker';
-export { AthenaTracker } from './tracker';
-export * from './types';
-export { detectInferenceMode, getPlatform, isReactNative, isBrowser } from './inference/auto-detect';
-export { AthenaOTAWrapper } from './react-native/ForcedReloadWrapper';
-export { ReactNativeEventCapture } from './events/capture-react-native';
-export declare const VERSION = "1.0.0";
+ * @athena-tracker/tracker
+ * ATHENA Analytics tracker SDK wrapper
+ */
+export interface AthenaTrackerConfig {
+    projectId: string;
+    apiKey: string;
+    apiUrl?: string;
+    sampleRate?: number;
+    recording?: {
+        enabled?: boolean;
+        sampleRate?: number;
+        maskAllInputs?: boolean;
+        maskInputOptions?: {
+            password?: boolean;
+            email?: boolean;
+        };
+        compressionLevel?: number;
+        maxChunkSize?: number;
+    };
+    edgeAI?: {
+        enabled?: boolean;
+        modelPath?: string;
+        webhook?: {
+            url?: string;
+            enabled?: boolean;
+        };
+    };
+}
+export interface UserProperties {
+    email?: string;
+    name?: string;
+    [key: string]: any;
+}
+export interface EventProperties {
+    [key: string]: any;
+}
+declare class AthenaTrackerSDK {
+    private config;
+    private scriptLoaded;
+    private loadPromise;
+    constructor(config: AthenaTrackerConfig);
+    /**
+     * Load the ATHENA tracker script dynamically
+     */
+    load(): Promise<void>;
+    /**
+     * Initialize the tracker with configuration
+     */
+    private initialize;
+    /**
+     * Get the underlying tracker instance
+     */
+    private getTracker;
+    /**
+     * Identify a user
+     */
+    identify(userId: string, properties?: UserProperties): void;
+    /**
+     * Track a custom event
+     */
+    track(eventName: string, properties?: EventProperties): void;
+    /**
+     * Track a page view
+     */
+    page(pageName?: string, properties?: EventProperties): void;
+    /**
+     * Reset user identity (logout)
+     */
+    reset(): void;
+    /**
+     * Get current session ID
+     */
+    getSessionId(): string | null;
+    /**
+     * Get current user ID
+     */
+    getUserId(): string | null;
+}
+/**
+ * Initialize ATHENA tracker
+ */
+export declare function initTracker(config: AthenaTrackerConfig): AthenaTrackerSDK;
+/**
+ * Get the tracker instance
+ */
+export declare function getTracker(): AthenaTrackerSDK | null;
+/**
+ * Convenience methods (use singleton instance)
+ */
+export declare function identify(userId: string, properties?: UserProperties): void;
+export declare function track(eventName: string, properties?: EventProperties): void;
+export declare function page(pageName?: string, properties?: EventProperties): void;
+export declare function reset(): void;
+export declare function getSessionId(): string | null;
+export declare function getUserId(): string | null;
+declare const _default: {
+    initTracker: typeof initTracker;
+    getTracker: typeof getTracker;
+    identify: typeof identify;
+    track: typeof track;
+    page: typeof page;
+    reset: typeof reset;
+    getSessionId: typeof getSessionId;
+    getUserId: typeof getUserId;
+};
+export default _default;
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,aAAa,IAAI,OAAO,EAAE,MAAM,WAAW,CAAC;AACrD,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAG1C,cAAc,SAAS,CAAC;AAGxB,OAAO,EAAE,mBAAmB,EAAE,WAAW,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAGrG,OAAO,EAAE,gBAAgB,EAAE,MAAM,oCAAoC,CAAC;AACtE,OAAO,EAAE,uBAAuB,EAAE,MAAM,+BAA+B,CAAC;AAGxE,eAAO,MAAM,OAAO,UAAU,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,WAAW,mBAAmB;IAClC,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE;QACV,OAAO,CAAC,EAAE,OAAO,CAAC;QAClB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,aAAa,CAAC,EAAE,OAAO,CAAC;QACxB,gBAAgB,CAAC,EAAE;YACjB,QAAQ,CAAC,EAAE,OAAO,CAAC;YACnB,KAAK,CAAC,EAAE,OAAO,CAAC;SACjB,CAAC;QACF,gBAAgB,CAAC,EAAE,MAAM,CAAC;QAC1B,YAAY,CAAC,EAAE,MAAM,CAAC;KACvB,CAAC;IACF,MAAM,CAAC,EAAE;QACP,OAAO,CAAC,EAAE,OAAO,CAAC;QAClB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,OAAO,CAAC,EAAE;YACR,GAAG,CAAC,EAAE,MAAM,CAAC;YACb,OAAO,CAAC,EAAE,OAAO,CAAC;SACnB,CAAC;KACH,CAAC;CACH;AAED,MAAM,WAAW,cAAc;IAC7B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;CACpB;AAED,MAAM,WAAW,eAAe;IAC9B,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;CACpB;AAED,cAAM,gBAAgB;IACpB,OAAO,CAAC,MAAM,CAAsB;IACpC,OAAO,CAAC,YAAY,CAAkB;IACtC,OAAO,CAAC,WAAW,CAA8B;gBAErC,MAAM,EAAE,mBAAmB;IAQvC;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAyB3B;;OAEG;IACH,OAAO,CAAC,UAAU;IAMlB;;OAEG;IACH,OAAO,CAAC,UAAU;IAclB;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,cAAc,GAAG,IAAI;IAU3D;;OAEG;IACH,KAAK,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,eAAe,GAAG,IAAI;IAO5D;;OAEG;IACH,IAAI,CAAC,QAAQ,CAAC,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,eAAe,GAAG,IAAI;IAO3D;;OAEG;IACH,KAAK,IAAI,IAAI;IAOb;;OAEG;IACH,YAAY,IAAI,MAAM,GAAG,IAAI;IAQ7B;;OAEG;IACH,SAAS,IAAI,MAAM,GAAG,IAAI;CAO3B;AAKD;;GAEG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,mBAAmB,GAAG,gBAAgB,CAKzE;AAED;;GAEG;AACH,wBAAgB,UAAU,IAAI,gBAAgB,GAAG,IAAI,CAKpD;AAED;;GAEG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,cAAc,GAAG,IAAI,CAE1E;AAED,wBAAgB,KAAK,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,eAAe,GAAG,IAAI,CAE3E;AAED,wBAAgB,IAAI,CAAC,QAAQ,CAAC,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,eAAe,GAAG,IAAI,CAE1E;AAED,wBAAgB,KAAK,IAAI,IAAI,CAE5B;AAED,wBAAgB,YAAY,IAAI,MAAM,GAAG,IAAI,CAE5C;AAED,wBAAgB,SAAS,IAAI,MAAM,GAAG,IAAI,CAEzC;;;;;;;;;;;AAGD,wBASE"}