@efx/sdk

🚀 EFX Experience Adaptation Engine SDK - Real-time user experience optimization

Installation

npm install @efx/sdk

Quick Start

import { EfxClient } from '@efx/sdk';

const efx = new EfxClient({
  apiKey: 'efx_xxx.yyy',
  baseUrl: 'https://your-project.supabase.co/functions/v1'
});

// Start a session
const session = await efx.startSession({ 
  source: 'web-app', 
  user_agent: navigator.userAgent 
});

// Send signals
const result = await efx.sendSignal({
  session_id: session.data.id,
  page: '/checkout',
  value: { 
    cognitive_load: 0.8,
    stress_level: 0.6,
    attention_score: 0.9
  }
});

// Check quotas
console.log('Remaining:', result.headers.remaining);
console.log('Limit:', result.headers.limit);

Browser Usage (CDN)

<script src="https://unpkg.com/@efx/[email protected]/dist/index.global.js"></script>
<script>
const efx = new EFX.EfxClient({
  apiKey: 'efx_xxx.yyy',
  baseUrl: 'https://your-project.supabase.co/functions/v1'
});
</script>

API Reference

EfxClient

Constructor

new EfxClient(options: EfxClientOpts)

Options:

• apiKey: string - Your EFX API key
• baseUrl?: string - EFX API base URL
• fetch?: typeof fetch - Custom fetch implementation

Methods

startSession(meta?: Record<string, unknown>)

Creates a new EFX session.

const session = await efx.startSession({
  user_id: 'user-123',
  source: 'mobile-app',
  experiment: 'checkout-v2'
});

sendSignal(input: EfxSignal)

Sends a signal to trigger adaptations.

const result = await efx.sendSignal({
  session_id: 'session-id',
  page: '/product/123',
  value: {
    cognitive_load: 0.7,
    engagement: 0.8,
    confusion: 0.2
  }
});

onAdaptation(input: { session_id: string })

Polls for adaptations (SSE fallback).

const adaptations = await efx.onAdaptation({
  session_id: 'session-id'
});

Response Format

All methods return an EfxResponse<T> object:

interface EfxResponse<T> {
  ok: boolean;           // HTTP success status
  status: number;        // HTTP status code  
  data: T;              // Response payload
  headers: {            // Quota information
    limit?: string;     // Monthly limit
    used?: string;      // Used this month
    remaining?: string; // Remaining quota
    warning?: string;   // Quota warning (80%, 90%)
  };
}

Quota Monitoring

EFX automatically includes quota information in response headers:

const result = await efx.sendSignal(/* ... */);

if (result.headers.warning === '80%') {
  console.warn('Approaching quota limit!');
}

console.log(`Quota: ${result.headers.used}/${result.headers.limit}`);

Error Handling

try {
  const result = await efx.sendSignal(signalData);
  if (!result.ok) {
    console.error('API Error:', result.status, result.data);
  }
} catch (error) {
  console.error('Network Error:', error);
}

TypeScript Support

Full TypeScript support with exported types:

import { 
  EfxClient, 
  EfxSession, 
  EfxSignal, 
  EfxAdaptation,
  EfxResponse 
} from '@efx/sdk';

Environment Variables

# For Node.js applications
EFX_API_KEY=efx_xxx.yyy
EFX_BASE_URL=https://your-project.supabase.co/functions/v1

Examples

React Hook

import { useEffect, useState } from 'react';
import { EfxClient } from '@efx/sdk';

export function useEfx() {
  const [efx] = useState(() => new EfxClient({
    apiKey: process.env.REACT_APP_EFX_KEY!,
    baseUrl: process.env.REACT_APP_EFX_URL!
  }));

  const sendSignal = async (page: string, value: any) => {
    const session = await efx.startSession();
    return efx.sendSignal({
      session_id: session.data.id,
      page,
      value
    });
  };

  return { efx, sendSignal };
}

Next.js API Route

// pages/api/efx-signal.ts
import { EfxClient } from '@efx/sdk';

const efx = new EfxClient({
  apiKey: process.env.EFX_API_KEY!,
  baseUrl: process.env.EFX_BASE_URL!
});

export default async function handler(req, res) {
  const result = await efx.sendSignal(req.body);
  res.json(result);
}

License

MIT

Support

• 📖 Documentation
• 💬 Discord Community
• 📧 Email Support