@athena-tracker/tracker 1.0.0

package/README.md

@@ -0,0 +1,317 @@
+# @athena/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
+
+## Installation
+
+```bash
+npm install @athena/tracker
+```
+
+### For React Native with On-Device Inference
+
+```bash
+npm install @athena/tracker onnxruntime-react-native
+```
+
+### 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
+
+### React Native
+
+```typescript
+import AthenaTracker from '@athena/tracker';
+
+// Initialize tracker
+AthenaTracker.init({
+  appToken: 'at_live_xxxxx',
+  inferenceMode: 'auto', // Auto-detects environment
+  webhook: {
+    url: 'https://your-backend.com/webhooks/athena',
+    enabled: true
+  }
+});
+```
+
+### Web
+
+```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
+
+```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)
+
+Automatically detects whether `onnxruntime-react-native` is available:
+
+```typescript
+AthenaTracker.init({
+  appToken: 'at_live_xxxxx',
+  inferenceMode: 'auto' // Default
+});
+```
+
+#### On-Device Mode (Forced)
+
+Force on-device inference (requires `onnxruntime-react-native`):
+
+```typescript
+AthenaTracker.init({
+  appToken: 'at_live_xxxxx',
+  inferenceMode: 'on-device',
+  modelPath: '/path/to/model.onnx'
+});
+```
+
+#### Server Mode (Forced)
+
+Force server-side inference:
+
+```typescript
+AthenaTracker.init({
+  appToken: 'at_live_xxxxx',
+  inferenceMode: 'server',
+  serverInferenceUrl: 'https://api.pascal.cx/v1/predict'
+});
+```
+
+## 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
+    }
+  }
+});
+```
+
+### 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"
+}
+```
+
+## 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
+
+```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
+}
+```
+
+### Methods
+
+#### `init(config)`
+
+Initialize the tracker with configuration.
+
+```typescript
+await AthenaTracker.init({
+  appToken: 'at_live_xxxxx'
+});
+```
+
+#### `identify(userId, traits?)`
+
+Identify a user.
+
+```typescript
+AthenaTracker.identify('user_123', {
+  email: 'user@example.com',
+  name: 'John Doe'
+});
+```
+
+#### `track(eventType, properties?)`
+
+Track a custom event.
+
+```typescript
+AthenaTracker.track('button_click', {
+  button_id: 'checkout',
+  page: '/cart'
+});
+```
+
+## React Native Components
+
+### AthenaOTAWrapper
+
+For apps using Expo OTA updates, wrap your app with `AthenaOTAWrapper`:
+
+```tsx
+import { AthenaOTAWrapper } from '@athena/tracker';
+
+export default function App() {
+  return (
+    <AthenaOTAWrapper
+      loadingMessage="Loading..."
+      updateMessage="Updating..."
+    >
+      <YourApp />
+    </AthenaOTAWrapper>
+  );
+}
+```
+
+**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
+
+**Props:**
+- `loadingMessage` (string, optional): Message during initial load (default: "Loading...")
+- `updateMessage` (string, optional): Message during update (default: "Updating...")
+
+---
+
+### ReactNativeEventCapture
+
+Advanced event capture for custom use cases:
+
+```tsx
+import { ReactNativeEventCapture } from '@athena/tracker';
+
+const capture = new ReactNativeEventCapture({
+  captureTouch: true,
+  captureNavigation: true,
+  captureLifecycle: true,
+  captureNetworkErrors: true,
+  batchSize: 10,
+  batchIntervalMs: 10000
+});
+
+// Start capturing
+capture.start();
+
+// Track screen view manually
+capture.trackScreenView('ProductDetails', { productId: '123' });
+
+// Track custom event
+capture.track('AddToCart', { productId: '123', price: 49.99 });
+
+// Stop capturing
+capture.stop();
+```
+
+**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%)
+
+## Browser Support
+
+- Chrome/Edge 90+
+- Safari 14+
+- Firefox 88+
+- React Native 0.70+
+
+## License
+
+MIT
+
+## Documentation
+
+Full documentation: https://docs.athena.ai/tracker
+
+## Support
+
+- Issues: https://github.com/RubaiyatF/Pascal/issues
+- Email: support@pascal.cx

package/dist/events/capture-react-native.d.ts

@@ -0,0 +1,77 @@
+/**
+ * React Native Event Capture
+ *
+ * Captures behavioral events from React Native apps
+ * - Touch events (Tap, Swipe, LongPress)
+ * - Navigation events (Screen changes)
+ * - App lifecycle events (Open, Background, Foreground, Close)
+ * - Form interactions
+ * - Network errors
+ */
+import { Event } from '../types';
+export interface CaptureConfig {
+    captureTouch?: boolean;
+    captureNavigation?: boolean;
+    captureLifecycle?: boolean;
+    captureNetworkErrors?: boolean;
+    batchSize?: number;
+    batchIntervalMs?: number;
+}
+export declare class ReactNativeEventCapture {
+    private events;
+    private config;
+    private appStateSubscription;
+    private panResponder;
+    private batchTimer;
+    private currentScreen;
+    private sessionStartTime;
+    constructor(config?: CaptureConfig);
+    /**
+     * Start capturing events
+     */
+    start(): void;
+    /**
+     * Stop capturing events
+     */
+    stop(): void;
+    /**
+     * Setup app lifecycle tracking (Open, Background, Foreground, Close)
+     */
+    private setupLifecycleTracking;
+    /**
+     * Setup touch event tracking
+     */
+    private setupTouchTracking;
+    /**
+     * Setup network error tracking
+     */
+    private setupNetworkErrorTracking;
+    /**
+     * Manually track screen navigation
+     * Should be called by navigation library (React Navigation, etc.)
+     */
+    trackScreenView(screenName: string, params?: Record<string, any>): void;
+    /**
+     * Manually track custom event
+     */
+    track(eventType: string, properties?: Record<string, any>): void;
+    /**
+     * Capture an event and add to batch
+     */
+    private captureEvent;
+    /**
+     * Flush accumulated events (to be sent to server)
+     */
+    private flushEvents;
+    /**
+     * Callback for batch events (set by tracker)
+     */
+    onEventBatch?: (events: Event[]) => void;
+    /**
+     * Get PanResponder for manual integration
+     * Usage: <View {...capture.getPanResponderProps()}>
+     */
+    getPanResponderProps(): any;
+}
+export default ReactNativeEventCapture;
+//# sourceMappingURL=capture-react-native.d.ts.map

package/dist/events/capture-react-native.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capture-react-native.d.ts","sourceRoot":"","sources":["../../src/events/capture-react-native.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,EAAE,KAAK,EAAE,MAAM,UAAU,CAAC;AAEjC,MAAM,WAAW,aAAa;IAC5B,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,qBAAa,uBAAuB;IAClC,OAAO,CAAC,MAAM,CAAe;IAC7B,OAAO,CAAC,MAAM,CAA0B;IACxC,OAAO,CAAC,oBAAoB,CAAa;IACzC,OAAO,CAAC,YAAY,CAAa;IACjC,OAAO,CAAC,UAAU,CAAa;IAC/B,OAAO,CAAC,aAAa,CAAqB;IAC1C,OAAO,CAAC,gBAAgB,CAAsB;gBAElC,MAAM,GAAE,aAAkB;IAWtC;;OAEG;IACH,KAAK,IAAI,IAAI;IA+Bb;;OAEG;IACH,IAAI,IAAI,IAAI;IAeZ;;OAEG;IACH,OAAO,CAAC,sBAAsB;IA+B9B;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAiE1B;;OAEG;IACH,OAAO,CAAC,yBAAyB;IA2CjC;;;OAGG;IACH,eAAe,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI;IAcvE;;OAEG;IACH,KAAK,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI;IAWhE;;OAEG;IACH,OAAO,CAAC,YAAY;IASpB;;OAEG;IACH,OAAO,CAAC,WAAW;IAUnB;;OAEG;IACH,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE,KAAK,EAAE,KAAK,IAAI,CAAC;IAEzC;;;OAGG;IACH,oBAAoB,IAAI,GAAG;CAG5B;AAED,eAAe,uBAAuB,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @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";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +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"}