@meistrari/audit-sdk

TypeScript client for the Audit Service. Sends audit events to POST /v1/events with retries, backoff and 429 Retry-After handling. Failures after retries are logged via @meistrari/logger instead of throwing.

Install

bun add @meistrari/audit-sdk
# or
npm install @meistrari/audit-sdk

Configuration

| Option | Env var | Default | Description | | --- | --- | --- | --- | | baseUrl | AUDIT_API_BASE_URL | — (required) | Base URL of the Audit API | | sourceApp | AUDIT_SOURCE_APP | — (required) | Identifier of the application sending events (e.g. tela) | | timeoutMs | — | 5000 | Per-request timeout | | maxRetries | — | 3 | Retry attempts on 5xx / network errors |

The constructor throws if baseUrl or sourceApp cannot be resolved from either the config object or the environment.

Event shape

interface AuditEvent {
    action: string                       // required, e.g. 'create'
    object_type: string                  // required, e.g. 'api_key'
    origin: 'api' | 'worker' | 'ui'      // required
    object_id?: string
    actor_type?: 'user' | 'system' | 'api_key'
    correlation_id?: string
    user_agent?: string
    occurred_at?: Date
    ip_address?: string
    metadata?: Record<string, unknown>
}

All calls require a dataToken issued by the API Gateway / Auth API. It carries the workspace (and user, when available) the events belong to.

Examples

Track a single event

import { AuditClient } from '@meistrari/audit-sdk'

const audit = new AuditClient({
    baseUrl: 'https://audit.tela.com',
    sourceApp: 'tela',
})

await audit.track(dataToken, {
    action: 'create',
    object_type: 'api_key',
    object_id: 'key_abc123',
    origin: 'api',
    actor_type: 'user',
    metadata: { name: 'CI token' },
})

Configure from environment

// AUDIT_API_BASE_URL and AUDIT_SOURCE_APP must be set
const audit = new AuditClient()

await audit.track(dataToken, {
    action: 'login',
    object_type: 'session',
    origin: 'ui',
})

Batch multiple events

await audit.trackMany(dataToken, [
    {
        action: 'create',
        object_type: 'document',
        object_id: 'doc_1',
        origin: 'worker',
        actor_type: 'system',
        correlation_id: 'job_42',
    },
    {
        action: 'update',
        object_type: 'document',
        object_id: 'doc_1',
        origin: 'worker',
        actor_type: 'system',
        correlation_id: 'job_42',
        metadata: { fields: ['title'] },
    },
])

Custom timeout and retries

const audit = new AuditClient({
    baseUrl: 'https://audit.tela.com',
    sourceApp: 'my-app',
    timeoutMs: 2000,
    maxRetries: 5,
})

Handling errors

track / trackMany only throw AuditError for 4xx responses (the request is malformed and retrying won't help). 5xx, network errors and timeouts are retried with exponential backoff; if all attempts fail, the SDK logs the failure and resolves without throwing — the caller's flow is never blocked by audit.

import { AuditClient, AuditError } from '@meistrari/audit-sdk'

try {
    await audit.track(dataToken, event)
}
catch (err) {
    if (err instanceof AuditError) {
        // 4xx — bad payload, missing fields, invalid token, etc.
        console.error('Audit rejected event:', err.details)
    }
    throw err
}