npm package: @frozotrailbase/sdk
Description: Official TypeScript SDK for Trailbase — audit logs, RBAC, and compliance for B2B SaaS
Author: Frozo Software Pvt Ltd
Latest version: 0.1.1

# @frozotrailbase/sdk

The official TypeScript SDK for [Trailbase](https://trailbase.frozo.ai) — 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

```bash
npm install @frozotrailbase/sdk
```

## Quick Start

```typescript
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: 'jane@acme.com' },
    resource: { type: 'document', id: 'doc_456' },
    outcome: 'success',
    metadata: { department: 'Engineering' },
});

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

## Usage with Express

```typescript
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`

```typescript
// 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)

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

## License

MIT