TraceAI Node.js SDK

Log every AI hiring decision with tamper-evident audit trails. Built for UK regulatory compliance (UK GDPR, Equality Act, ICO guidance).

Installation

npm install gettraceai

Quick Start (5 lines)

import { TraceAI } from 'gettraceai';

const trace = new TraceAI({ apiKey: 'sk_live_...' });

await trace.log({
  decisionType: 'cv_screening',
  inputs: { candidateId: 'c_abc123', cvText: 'Senior engineer...' },
  output: { score: 0.82, decision: 'shortlist' },
});

That's it. Every AI decision is now logged with a tamper-evident audit trail.

Full Example

import { TraceAI } from 'gettraceai';

const trace = new TraceAI({
  apiKey: 'sk_live_...',
  baseUrl: 'https://api.traceai.dev/v1', // optional, for self-hosted
  timeout: 10000, // milliseconds
  retries: 3,     // retry 5xx errors
  silent: true,   // don't crash your pipeline on errors
});

// Log a single decision
const result = await trace.log({
  decisionType: 'cv_screening',
  inputs: { candidateId: 'c_abc123', cvText: '...' },
  output: { score: 0.82, decision: 'shortlist', reasons: ['skills_match'] },
  model: { name: 'gpt-4o', version: '2025-03', provider: 'openai' },
  actor: { userId: 'recruiter_42', role: 'hiring_manager' },
  confidence: 0.82,
  metadata: { department: 'engineering', location: 'london' },
});
// result: { id: "d_...", hash: "...", status: "logged" }

// Fire-and-forget (non-blocking)
trace.logAsync({
  decisionType: 'cv_screening',
  inputs: { candidateId: 'c_def456' },
  output: { score: 0.45, decision: 'reject' },
});

// Batch log (up to 100 decisions)
await trace.logBatch([
  { decisionType: 'cv_screening', inputs: { candidateId: 'c_1' }, output: { decision: 'shortlist' } },
  { decisionType: 'cv_screening', inputs: { candidateId: 'c_2' }, output: { decision: 'reject' } },
]);

Error Handling

By default (silent: true), the SDK never crashes your pipeline. Errors are logged to stderr and methods return null.

Set silent: false for strict mode during development:

import { TraceAI, TraceAIError } from 'gettraceai';

const trace = new TraceAI({ apiKey: 'sk_live_...', silent: false });

try {
  await trace.log({
    decisionType: 'cv_screening',
    inputs: { candidateId: 'c_abc123' },
    output: { decision: 'shortlist' },
  });
} catch (err) {
  if (err instanceof TraceAIError) {
    console.error(err.statusCode);     // HTTP status code (if applicable)
    console.error(err.responseBody);   // Parsed response body (if applicable)
  }
}

API Reference

new TraceAI(options)

Create a client instance.

| Option | Type | Default | Description | |--------|------|---------|-------------| | apiKey | string | required | Your TraceAI API key | | baseUrl | string | https://api.traceai.dev/v1 | API base URL | | timeout | number | 10000 | Request timeout in milliseconds | | retries | number | 3 | Retries for 5xx/network errors | | silent | boolean | true | Suppress errors (return null instead of throwing) |

trace.log(options): Promise<LogResponse | null>

Log a single decision.

| Option | Type | Required | Description | |--------|------|----------|-------------| | decisionType | string | Yes | Type of decision (e.g. 'cv_screening') | | inputs | object | Yes | What the AI received | | output | object | Yes | What the AI decided | | model | object | No | Model name, version, provider | | actor | object | No | User ID, role, authority level | | confidence | number | No | Confidence score 0-1 | | humanOverride | object | No | Human override details | | metadata | object | No | Additional context |

trace.logAsync(options): void

Same parameters as log(), but fire-and-forget (does not await the result).

trace.logBatch(decisions): Promise<BatchResponse | null>

Log up to 100 decisions in a single request. Each decision object must include decisionType, inputs, and output.

License

MIT