@frozotrailbase/sdk

The official TypeScript SDK for Trailbase — audit logs, RBAC, and compliance for B2B SaaS.

Features

• Automatic Batching — Buffers events and flushes in a single HTTP request
• Type-Safe — Full TypeScript support with Zod validation
• Resilient — Exponential backoff retries for network and server errors
• Lightweight — Zero external runtime dependencies, uses native fetch
• SHA-256 Hash Chains — Every event is cryptographically linked for tamper evidence

Installation

npm install @frozotrailbase/sdk

Quick Start

import { TrailbaseClient } from '@frozotrailbase/sdk';

const tb = new TrailbaseClient({
    apiKey: 'tb_your_api_key',
    tenantId: 'tn_your_tenant',
});

// Track an audit event
await tb.trackEvent({
    action: 'document.viewed',
    actor: { id: 'user_123', email: '[email protected]' },
    resource: { type: 'document', id: 'doc_456' },
    outcome: 'success',
    metadata: { department: 'Engineering' },
});

// Flush remaining events on shutdown
await tb.shutdown();

Usage with Express

import express from 'express';
import { TrailbaseClient } from '@frozotrailbase/sdk';

const app = express();
const tb = new TrailbaseClient({
    apiKey: process.env.TRAILBASE_API_KEY!,
    tenantId: process.env.TRAILBASE_TENANT_ID!,
});

app.post('/api/documents/:id', async (req, res) => {
    // Your business logic
    await updateDocument(req.params.id, req.body);

    // Log the audit event
    await tb.trackEvent({
        action: 'document.updated',
        actor: { id: req.user.id, email: req.user.email },
        resource: { type: 'document', id: req.params.id },
    });

    res.json({ success: true });
});

// Flush on graceful shutdown
process.on('SIGTERM', () => tb.shutdown());

Configuration

| Option | Type | Default | Description | | --- | --- | --- | --- | | apiKey | string | Required | Your Trailbase API key (starts with tb_) | | tenantId | string | Required | Your tenant ID (starts with tn_) | | baseUrl | string | https://trailbase.frozo.ai | API base URL | | flushInterval | number | 1000 | ms between auto-flushes. 0 = send immediately | | maxBatchSize | number | 50 | Max events per batch | | maxRetries | number | 3 | Retry attempts with exponential backoff |

API Reference

TrailbaseClient

// Track an audit event
await tb.trackEvent({ action, actor, resource?, outcome?, metadata? });

// Compliance
await tb.runComplianceCheck('SOC2');
await tb.getComplianceResults('SOC2');

// Alerts
await tb.listAlerts({ status: 'FIRING' });
await tb.acknowledgeAlert(alertId);
await tb.resolveAlert(alertId);

// Alert Rules
await tb.createAlertRule({ name, type, condition, severity?, channels? });
await tb.listAlertRules();

// Dashboard
await tb.createDashboardSession(userJwt);

// Lifecycle
await tb.flush();    // Force flush queued events
await tb.shutdown(); // Flush + cleanup timers

AuditLogClient (lower-level)

// Direct event logging
await client.log({ action, actor, resource, outcome, metadata });
await client.logBatch([event1, event2, event3]);

License

MIT