@athena-tracker/tracker 1.0.1 → 1.2.0

package/README.md

@@ -1,6 +1,20 @@
 # @athena-tracker/tracker
 
-ATHENA Analytics tracker SDK wrapper for easy integration
+> Behavioral analytics tracker with edge AI for React Native and Web
+
+[![npm version](https://img.shields.io/npm/v/@athena-tracker/tracker.svg)](https://www.npmjs.com/package/@athena-tracker/tracker)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Features
+
+- ✅ **90+ Behavioral Event Types** - Auto-captured touch, navigation, lifecycle events
+- ✅ **Dual-Mode ML Inference** - On-device (ONNX) or server-side (auto-fallback)
+- ✅ **Purchase Intent Prediction** - Real-time predictions for e-commerce (0.0-1.0)
+- ✅ **5 User Archetypes** - Fast Mover, On Track, Slow Adopter, At Risk, Different Path
+- ✅ **Cross-Platform** - Works on Web, iOS, Android (React Native)
+- ✅ **Privacy-First** - Optional on-device inference (data never leaves device)
+- ✅ **Zero Config** - Smart auto-detection of best inference mode
+- ✅ **TypeScript Support** - Full type definitions included
 
 ## Installation
 
@@ -8,236 +22,448 @@ ATHENA Analytics tracker SDK wrapper for easy integration
 npm install @athena-tracker/tracker
 ```
 
-## Usage
+### For React Native with On-Device Inference
 
-### Basic Setup
+```bash
+npm install @athena-tracker/tracker onnxruntime-react-native
+```
 
-```typescript
-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,
+### For OTA Updates (Server-Side Inference)
+
+```bash
+npm install @athena-tracker/tracker
+```
+
+(No `onnxruntime-react-native` required - will automatically fall back to server-side inference)
+
+---
+
+## ⚠️ Getting Credentials (Required Before Installation)
+
+**Before you can use this package, you need an `appToken` from Pascal.**
+
+### For B2B Platform Partners (App Generators like Anything.com, Bubble.io)
+
+If you're building a platform that generates apps for customers:
+
+1. **Contact Pascal** to get partner credentials:
+   - Email: partnerships@pascal.cx
+   - Request: ATHENA B2B partner workspace
+
+2. **Receive credentials**:
+   - Workspace ID: `ws_your_company_com`
+   - JWT Token: `eyJhbGc...` (perpetual token)
+
+3. **Provision apps via API**:
+
+```javascript
+// Your backend code
+const axios = require('axios');
+
+async function provisionApp(appDetails) {
+  const response = await axios.post(
+    'https://tracker.pascal.cx/api/athena/provision',
+    {
+      workspaceId: process.env.ATHENA_WORKSPACE_ID,
+      appId: appDetails.id,
+      appName: appDetails.name,
+      platform: ['web', 'ios', 'android']
     },
+    {
+      headers: {
+        'Authorization': `Bearer ${process.env.ATHENA_WORKSPACE_JWT}`,
+        'Content-Type': 'application/json'
+      }
+    }
+  );
+
+  const { appToken } = response.data;
+
+  // Store appToken in your database
+  await db.apps.update({
+    id: appDetails.id,
+    athena_app_token: appToken
+  });
+
+  return appToken;
+}
+```
+
+4. **Inject token into generated apps** (see Quick Start below)
+
+### For Agencies/Merchants (Website Integration)
+
+If you're integrating tracking for merchant websites:
+
+1. **Contact Pascal** for a partner API key:
+   - Email: partnerships@pascal.cx
+   - Request: Partner merchant provisioning
+
+2. **Provision merchants via API**:
+
+```javascript
+const response = await axios.post(
+  'https://tracker.pascal.cx/api/partners/YOUR_PARTNER_NAME/merchants',
+  {
+    merchant_id: 'merchant_001',
+    merchant_email: 'owner@merchant.com',
+    webhook_url: 'https://your-platform.com/webhooks/pascal'
   },
-});
+  {
+    headers: {
+      'Authorization': `Bearer ${process.env.PASCAL_PARTNER_API_KEY}`,
+      'Content-Type': 'application/json'
+    }
+  }
+);
 
-// Load the tracker script
-await tracker.load();
+const { api_key } = response.data;  // This IS your appToken
+```
 
-// Identify user
-identify('user-123', {
-  email: 'user@example.com',
-  name: 'John Doe',
-  plan: 'pro',
-});
+### Testing with Demo Token
 
-// Track custom events
-track('button_clicked', {
-  buttonId: 'cta-signup',
-  location: 'homepage',
-});
+For testing purposes, you can use a demo token:
 
-// Track page views
-page('Home Page', {
-  category: 'marketing',
+```javascript
+// ⚠️ FOR TESTING ONLY - NOT FOR PRODUCTION
+AthenaTracker.init({
+  appToken: 'at_demo_test_mode_no_predictions',
+  debug: true
 });
 ```
 
-### React Integration
+**📖 Complete Guide**: See `PARTNER_INTEGRATION_GUIDE.md` for full details on both integration patterns.
 
-```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>;
-}
+## Quick Start
+
+### React Native
+
+```typescript
+import AthenaTracker from '@athena-tracker/tracker';
+
+// Initialize tracker
+AthenaTracker.init({
+  appToken: 'at_live_xxxxx',
+  inferenceMode: 'auto', // Auto-detects environment
+  webhook: {
+    url: 'https://your-backend.com/webhooks/athena',
+    enabled: true
+  }
+});
 ```
 
-### Next.js Integration
+### Web
 
-```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();
+```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>
+```
+
+## Configuration
+
+### AthenaConfig
 
-  return <Component {...pageProps} />;
+```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
 }
+```
+
+### Inference Modes
+
+#### Auto Mode (Recommended)
 
-export default MyApp;
+Automatically detects whether `onnxruntime-react-native` is available:
+
+```typescript
+AthenaTracker.init({
+  appToken: 'at_live_xxxxx',
+  inferenceMode: 'auto' // Default
+});
 ```
 
-### Vue.js Integration
+#### On-Device Mode (Forced)
 
-```javascript
-// main.js
-import { createApp } from 'vue';
-import { initTracker } from '@athena-tracker/tracker';
-import App from './App.vue';
+Force on-device inference (requires `onnxruntime-react-native`):
 
-const app = createApp(App);
+```typescript
+AthenaTracker.init({
+  appToken: 'at_live_xxxxx',
+  inferenceMode: 'on-device',
+  modelPath: '/path/to/model.onnx'
+});
+```
 
-// Initialize tracker
-const tracker = initTracker({
-  projectId: import.meta.env.VITE_ATHENA_PROJECT_ID,
-  apiKey: import.meta.env.VITE_ATHENA_API_KEY,
+#### Server Mode (Forced)
+
+Force server-side inference:
+
+```typescript
+AthenaTracker.init({
+  appToken: 'at_live_xxxxx',
+  inferenceMode: 'server',
+  // ⚠️ REQUIRED for predictions - this is a separate service from apiUrl
+  serverInferenceUrl: 'https://pascal-ml-api-cgn7rucynq-uc.a.run.app/v1/predict'
 });
+```
+
+**⚠️ CRITICAL**: The `serverInferenceUrl` parameter is **REQUIRED** for ML predictions. This is a **separate service** from `apiUrl`:
+- `apiUrl` (default: `https://tracker.pascal.cx`) - Handles event ingestion only
+- `serverInferenceUrl` - Handles ML inference and predictions (separate Cloud Run service)
 
-tracker.load().then(() => {
-  console.log('ATHENA tracker loaded');
+Without `serverInferenceUrl`, predictions will fail with HTTP 404 errors. See troubleshooting below for details.
+
+## 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
+    }
+  }
 });
+```
 
-app.mount('#app');
+### 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"
+}
 ```
 
-## API Reference
+## User Archetypes
 
-### `initTracker(config)`
+| 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 |
 
-Initialize the ATHENA tracker with configuration.
+## API Reference
 
-**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
+### AthenaTracker
 
-**Returns:** `AthenaTrackerSDK` instance
+```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
+}
+```
 
-### `tracker.load()`
+### Methods
 
-Load the ATHENA tracker script asynchronously.
+#### `init(config)`
 
-**Returns:** `Promise<void>`
+Initialize the tracker with configuration.
 
-### `identify(userId, properties?)`
+```typescript
+await AthenaTracker.init({
+  appToken: 'at_live_xxxxx'
+});
+```
+
+#### `identify(userId, traits?)`
 
-Identify a user with optional properties.
+Identify a user.
 
-**Parameters:**
-- `userId`: Unique user identifier
-- `properties`: Optional user properties (email, name, etc.)
+```typescript
+AthenaTracker.identify('user_123', {
+  email: 'user@example.com',
+  name: 'John Doe'
+});
+```
 
-### `track(eventName, properties?)`
+#### `track(eventType, properties?)`
 
 Track a custom event.
 
-**Parameters:**
-- `eventName`: Name of the event
-- `properties`: Optional event properties
+```typescript
+AthenaTracker.track('button_click', {
+  button_id: 'checkout',
+  page: '/cart'
+});
+```
 
-### `page(pageName?, properties?)`
+## React Native Components
 
-Track a page view.
+### AthenaOTAWrapper
 
-**Parameters:**
-- `pageName`: Optional page name
-- `properties`: Optional page properties
+For apps using Expo OTA updates, wrap your app with `AthenaOTAWrapper`:
 
-### `reset()`
+```tsx
+import { AthenaOTAWrapper } from '@athena-tracker/tracker';
+
+export default function App() {
+  return (
+    <AthenaOTAWrapper
+      loadingMessage="Loading..."
+      updateMessage="Updating..."
+    >
+      <YourApp />
+    </AthenaOTAWrapper>
+  );
+}
+```
 
-Reset user identity (useful for logout).
+**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
 
-### `getSessionId()`
+**Props:**
+- `loadingMessage` (string, optional): Message during initial load (default: "Loading...")
+- `updateMessage` (string, optional): Message during update (default: "Updating...")
 
-Get the current session ID.
+---
 
-**Returns:** `string | null`
+### ReactNativeEventCapture
 
-### `getUserId()`
+Advanced event capture for custom use cases:
 
-Get the current user ID.
+```tsx
+import { ReactNativeEventCapture } from '@athena-tracker/tracker';
+
+const capture = new ReactNativeEventCapture({
+  captureTouch: true,
+  captureNavigation: true,
+  captureLifecycle: true,
+  captureNetworkErrors: true,
+  batchSize: 10,
+  batchIntervalMs: 10000
+});
 
-**Returns:** `string | null`
+// Start capturing
+capture.start();
 
-## Configuration Options
+// Track screen view manually
+capture.trackScreenView('ProductDetails', { productId: '123' });
 
-### Session Recording
+// Track custom event
+capture.track('AddToCart', { productId: '123', price: 49.99 });
 
-```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
-}
+// Stop capturing
+capture.stop();
 ```
 
-### Edge AI
+**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`
+
+## Performance
+
+- **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%)
+
+## Troubleshooting
+
+### "Server inference failed: 404 Not Found" Error
+
+**Symptom**: Predictions fail with 404 errors in console logs.
+
+**Cause**: Missing or incorrect `serverInferenceUrl` configuration.
+
+**Solution**: Explicitly set the `serverInferenceUrl` parameter:
 
 ```typescript
-edgeAI: {
-  enabled: true,
-  modelPath: 'https://tracker.pascal.cx/models/base_model_int8.onnx',
-  webhook: {
-    url: 'https://your-backend.com/webhooks/athena',
-    enabled: true,
-  },
-}
+AthenaTracker.init({
+  appToken: 'at_live_xxxxx',
+  apiUrl: 'https://tracker.pascal.cx', // Event ingestion
+  serverInferenceUrl: 'https://pascal-ml-api-cgn7rucynq-uc.a.run.app/v1/predict', // ML inference
+  inferenceMode: 'server'
+});
 ```
 
-## TypeScript Support
+### Event Tracking Works But No Predictions
 
-Full TypeScript support with type definitions included.
+**Cause**: Event tracking and ML predictions use separate endpoints.
 
-```typescript
-import type {
-  AthenaTrackerConfig,
-  UserProperties,
-  EventProperties,
-} from '@athena-tracker/tracker';
+**Solution**: Verify `serverInferenceUrl` is set correctly. Test with:
+
+```bash
+curl -X POST https://pascal-ml-api-cgn7rucynq-uc.a.run.app/v1/predict \
+  -H "Content-Type: application/json" \
+  -d '{"app_token":"your_token","events":[...]}'
 ```
 
+## What's New in v1.1.0
+
+- ✅ **Updated ML inference endpoint** to latest production URL
+- ✅ **70+ event types supported** via EVENT_MAPPING (cart_viewed, coupon_applied, etc.)
+- ✅ **Enhanced documentation** with critical configuration requirements
+- ✅ **React Native integration validated** with production test app
+- ✅ **Improved error messages** for missing serverInferenceUrl
+
+## Browser Support
+
+- Chrome/Edge 90+
+- Safari 14+
+- Firefox 88+
+- React Native 0.70+
+
 ## License
 
 MIT
+
+## Documentation
+
+- Full documentation: https://docs.athena.ai/tracker
+- Integration guide: See ATHENA_HANDOVER_DOCUMENTATION.md
+- API reference: https://tracker.pascal.cx/docs
+
+## Support
+
+- Issues: https://github.com/RubaiyatF/Pascal/issues
+- Email: support@pascal.cx
+- Slack: #athena-integration (for partners)