@athena-ai/sdk

Official JavaScript/TypeScript SDK for ATHENA Trust Calibration API.

Installation

npm install @athena-ai/sdk

Quick Start

import { Athena } from '@athena-ai/sdk';

const athena = new Athena({ apiKey: 'ak_xxx' });

// Detect bias in a decision
const result = await athena.bias.detect({
  userId: 'user_123',
  decision: {
    actionTaken: 'approved',
    aiRecommended: 'approved'
  }
});

if (result.biasDetected) {
  console.log('Warning:', result.riskLevel);
}

Features

• ✅ Full TypeScript support with 100% autocomplete coverage
• ✅ Automatic retries with exponential backoff
• ✅ Rate limit handling with Retry-After support
• ✅ Webhook signature verification (HMAC-SHA256)
• ✅ Express middleware included
• ✅ Browser and Node.js compatible
• ✅ Zero runtime dependencies

API Reference

Initialize

const athena = new Athena({
  apiKey: 'ak_xxx',           // Required
  baseUrl: 'https://...',     // Optional
  timeout: 30000,             // Optional (ms)
  maxRetries: 3               // Optional
});

Bias Detection

const result = await athena.bias.detect({
  userId: 'user_123',
  decision: {
    actionTaken: 'approved',
    aiRecommended: 'rejected',
    timeToDecisionMs: 500
  }
});

Trust Score

const score = await athena.trustScore.calculate({
  userId: 'user_123',
  domain: 'healthcare'
});

console.log(`Trust: ${score.trustScorePct}%`);

Calibration Analysis

const result = await athena.calibrate.analyze({
  userId: 'user_123',
  domain: 'healthcare',
  timeWindowDays: 30
});

console.log('Calibration:', result.calibration);

Stats & Analytics

const stats = await athena.stats.get();
const users = await athena.users.atRisk(10);
const engines = await athena.engines.status();
const benchmarks = await athena.engines.benchmarks();

Audit Trail

const audit = await athena.audit.list({
  limit: 50,
  offset: 0,
  startDate: '2025-01-01',
  endDate: '2025-12-31'
});

Compliance Export

const pdf = await athena.export.generatePdf({
  template: 'eu-ai-act',
  format: 'pdf'
});

// Save to file (Node.js)
const fs = require('fs');
const buffer = Buffer.from(await pdf.arrayBuffer());
fs.writeFileSync('report.pdf', buffer);

Webhooks

// Create webhook
const webhook = await athena.webhooks.create({
  url: 'https://example.com/webhook',
  events: ['bias.detected', 'trust.drop']
});

// SAVE THIS! Only shown once
console.log('Secret:', webhook.secret);

// List webhooks
const { webhooks } = await athena.webhooks.list();

// Test webhook
await athena.webhooks.test(webhook.id);

// Get delivery history
const deliveries = await athena.webhooks.deliveries(webhook.id, { limit: 10 });

Verify Webhooks

import { verifyWebhookSignature } from '@athena-ai/sdk';

app.post('/webhook', express.text({ type: '*/*' }), async (req, res) => {
  try {
    await verifyWebhookSignature(
      req.body,
      req.headers['x-athena-signature'],
      process.env.WEBHOOK_SECRET
    );
    // Process webhook...
    res.sendStatus(200);
  } catch {
    res.sendStatus(401);
  }
});

Express Middleware

import { athenaWebhookMiddleware } from '@athena-ai/sdk';

app.post(
  '/webhook',
  express.text({ type: 'application/json' }),
  athenaWebhookMiddleware({ secret: process.env.WEBHOOK_SECRET }),
  (req, res) => {
    console.log('Verified webhook:', JSON.parse(req.body));
    res.sendStatus(200);
  }
);

Error Handling

import { AthenaError, RateLimitError, AuthenticationError } from '@athena-ai/sdk';

try {
  await athena.bias.detect({...});
} catch (error) {
  if (error instanceof RateLimitError) {
    console.log(`Rate limited. Retry in ${error.retryAfter}s`);
  } else if (error instanceof AuthenticationError) {
    console.error('Invalid API key');
  } else if (error instanceof AthenaError) {
    console.error(`API error: ${error.message} (${error.status})`);
  }
}

TypeScript Support

All types are exported and fully documented:

import type {
  CalibrationCategory,
  TrustScoreResponse,
  WebhookEvent,
  BiasDetectedPayload
} from '@athena-ai/sdk';

License

MIT

Support

For issues and questions, visit: https://github.com/athena-ai/sdk-javascript/issues