@athena-tracker/react-hooks

React hooks for ATHENA analytics integration

Features

• ✅ useAthenaAnalytics - Fetch analytics data with auto-refresh
• ✅ useLiveAnalytics - Real-time event stream via WebSocket
• ✅ useAthenaTracker - Initialize ATHENA tracker in React apps
• ✅ TypeScript Support - Full type definitions included
• ✅ Zero Dependencies - Only requires React 18+

Installation

npm install @athena-tracker/react-hooks

Quick Start

useAthenaAnalytics

Fetch analytics data from ATHENA API:

import { useAthenaAnalytics } from '@athena-tracker/react-hooks';

function AnalyticsDashboard() {
  const { data, loading, error, refetch } = useAthenaAnalytics({
    appId: 'app_123',
    workspaceToken: process.env.ATHENA_WORKSPACE_JWT,
    endpoint: 'overview',
    period: '7d',
    refreshInterval: 30000 // Auto-refresh every 30 seconds
  });

  if (loading) return <div>Loading...</div>;
  if (error) return <div>Error: {error.message}</div>;

  return (
    <div>
      <h2>Analytics Overview</h2>
      <p>Sessions: {data.sessions}</p>
      <p>Events: {data.events}</p>
      <p>Users: {data.users}</p>
      <button onClick={refetch}>Refresh</button>
    </div>
  );
}

useLiveAnalytics

Stream real-time events via WebSocket:

import { useLiveAnalytics } from '@athena-tracker/react-hooks';

function LiveEventStream() {
  const { events, connected, error, clearEvents } = useLiveAnalytics({
    appId: 'app_123',
    workspaceToken: process.env.ATHENA_WORKSPACE_JWT,
    onEvent: (event) => {
      console.log('Live event:', event);
      // Trigger notifications, update UI, etc.
    }
  });

  return (
    <div>
      <div>Status: {connected ? '🟢 Connected' : '🔴 Disconnected'}</div>
      {error && <div>Error: {error.message}</div>}
      <button onClick={clearEvents}>Clear Events</button>

      <ul>
        {events.map((event, i) => (
          <li key={i}>
            {event.event_type} - {event.user_id} - {new Date(event.timestamp).toLocaleTimeString()}
          </li>
        ))}
      </ul>
    </div>
  );
}

useAthenaTracker

Initialize tracker in React Native or web apps:

import { useAthenaTracker } from '@athena-tracker/react-hooks';

function App() {
  const { initialized, mode, sessionId, error } = useAthenaTracker({
    appToken: 'at_live_xxxxx',
    apiUrl: 'https://tracker.pascal.cx',
    serverInferenceUrl: 'https://pascal-ml-api-cgn7rucynq-uc.a.run.app/v1/predict',
    inferenceMode: 'server',
    debug: true
  });

  if (!initialized) {
    return <div>Initializing ATHENA tracker...</div>;
  }

  return (
    <div>
      <p>Tracker Mode: {mode}</p>
      <p>Session ID: {sessionId}</p>
      <YourApp />
    </div>
  );
}

API Reference

useAthenaAnalytics

const { data, loading, error, refetch } = useAthenaAnalytics(config);

Config: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | appId | string | ✅ | ATHENA app ID | | workspaceToken | string | ✅ | JWT workspace token | | endpoint | string | ✅ | 'overview' | 'journeys' | 'friction' | 'heatmap' | 'predictions' | 'live' | | period | string | ❌ | '1h' | '24h' | '7d' | '30d' | '90d' (default: '7d') | | apiUrl | string | ❌ | API base URL (default: 'https://tracker.pascal.cx') | | refreshInterval | number | ❌ | Auto-refresh interval in ms (default: off) |

Returns:

{
  data: AnalyticsData | null;
  loading: boolean;
  error: Error | null;
  refetch: () => Promise<void>;
}

useLiveAnalytics

const { events, connected, error, clearEvents } = useLiveAnalytics(config);

Config: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | appId | string | ✅ | ATHENA app ID | | workspaceToken | string | ✅ | JWT workspace token | | wsUrl | string | ❌ | WebSocket URL (default: 'wss://tracker.pascal.cx/ws') | | onEvent | function | ❌ | Callback fired for each event |

Returns:

{
  events: LiveEvent[];
  connected: boolean;
  error: Error | null;
  clearEvents: () => void;
}

useAthenaTracker

const { initialized, mode, sessionId, error } = useAthenaTracker(config);

Config: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | appToken | string | ✅ | ATHENA app token | | apiUrl | string | ❌ | API base URL (default: 'https://tracker.pascal.cx') | | serverInferenceUrl | string | ❌ | ML inference endpoint | | inferenceMode | string | ❌ | 'auto' | 'on-device' | 'server' (default: 'auto') | | debug | boolean | ❌ | Enable debug logging (default: false) |

Returns:

{
  initialized: boolean;
  mode: string | null;
  sessionId: string | null;
  error: Error | null;
}

Advanced Usage

Combined Dashboard Example

import { useAthenaAnalytics, useLiveAnalytics } from '@athena-tracker/react-hooks';

function Dashboard({ appId, workspaceToken }) {
  // Fetch overview data
  const overview = useAthenaAnalytics({
    appId,
    workspaceToken,
    endpoint: 'overview',
    period: '7d',
    refreshInterval: 60000 // Refresh every minute
  });

  // Stream live events
  const liveStream = useLiveAnalytics({
    appId,
    workspaceToken,
    onEvent: (event) => {
      if (event.event_type === 'checkout_completed') {
        // Show toast notification
        showToast(`🎉 New purchase: ${event.properties.order_value}`);
      }
    }
  });

  return (
    <div>
      {/* Overview Section */}
      <div>
        <h2>Overview (Last 7 Days)</h2>
        {overview.loading ? (
          <p>Loading...</p>
        ) : overview.error ? (
          <p>Error: {overview.error.message}</p>
        ) : (
          <div>
            <p>Sessions: {overview.data.sessions}</p>
            <p>Events: {overview.data.events}</p>
            <p>Users: {overview.data.users}</p>
          </div>
        )}
      </div>

      {/* Live Stream Section */}
      <div>
        <h2>Live Events</h2>
        <p>Status: {liveStream.connected ? '🟢 Connected' : '🔴 Disconnected'}</p>
        <ul>
          {liveStream.events.slice(-10).map((event, i) => (
            <li key={i}>{event.event_type}</li>
          ))}
        </ul>
      </div>
    </div>
  );
}

Error Handling

All hooks return an error property for handling failures:

const { data, loading, error } = useAthenaAnalytics(config);

if (error) {
  if (error.message.includes('401')) {
    return <div>Authentication failed. Check your workspace token.</div>;
  } else if (error.message.includes('404')) {
    return <div>App not found. Check your appId.</div>;
  } else {
    return <div>Error: {error.message}</div>;
  }
}

TypeScript Support

Full TypeScript definitions are included:

import type { AthenaAnalyticsConfig, AnalyticsData, LiveEvent } from '@athena-tracker/react-hooks';

License

MIT

Documentation

• Full documentation: https://docs.athena.ai/react-hooks
• Integration guide: See PARTNER_INTEGRATION_GUIDE.md
• API reference: https://tracker.pascal.cx/docs

Support

• Issues: https://github.com/RubaiyatF/Pascal/issues
• Email: [email protected]