npm package: @sealtrail/sdk
Description: Official Node.js SDK for the SealTrail cryptographic audit trail API
Author: Zero Loop Labs
Latest version: 0.2.0

# @sealtrail/sdk

Tamper-proof audit trails for developers. Log, verify, and prove every action with cryptographic hash chains.

[![npm version](https://img.shields.io/npm/v/@sealtrail/sdk.svg?style=flat-square)](https://www.npmjs.com/package/@sealtrail/sdk)
[![npm downloads](https://img.shields.io/npm/dm/@sealtrail/sdk.svg?style=flat-square)](https://www.npmjs.com/package/@sealtrail/sdk)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square)](https://opensource.org/licenses/MIT)

## Installation

```bash
npm install @sealtrail/sdk
# or
yarn add @sealtrail/sdk
# or
pnpm add @sealtrail/sdk
```

## Quick Start

```typescript
import { SealTrail } from "@sealtrail/sdk";

const st = new SealTrail({ apiKey: "stl_live_..." });

// Log an audit event
const event = await st.events.log({
  actor: "user_123",
  action: "document.signed",
  resource: "doc_456",
  context: { ip: "192.168.1.1" },
});

console.log(event.hash); // cryptographic proof
```

## Features

- **Zero dependencies** — uses `globalThis.fetch` (Node 18+, Bun, Deno)
- **Fully typed** — complete TypeScript definitions
- **Automatic retries** — exponential backoff on 429, 5xx, and 409 (chain conflicts)
- **Auto-pagination** — async iterator for large result sets
- **Typed errors** — catch specific error classes (`RateLimitError`, `ValidationError`, etc.)

## API Reference

### Client

```typescript
const st = new SealTrail({
  apiKey: "stl_live_...",     // required
  baseUrl: "https://...",     // default: "https://api.sealtrail.dev"
  timeout: 30_000,            // request timeout in ms
  maxRetries: 3,              // retry attempts on retryable errors
  debug: false,               // log requests to console.debug
  fetch: customFetch,         // custom fetch for edge runtimes
});
```

### Events

```typescript
// Log an event
const event = await st.events.log({
  actor: "user_123",
  action: "document.signed",
  resource: "doc_456",        // optional
  context: { ip: "..." },    // optional metadata
  chain: "documents",         // optional, default: "default"
});

// Get a single event
const event = await st.events.get("evt_abc123");

// List events with filters
const { data, nextCursor } = await st.events.list({
  actor: "user_123",
  action: "document.signed",
  limit: 50,
  after: "2025-01-01T00:00:00Z",
});

// Auto-paginate through all events
for await (const event of st.events.listAutoPaginate({ actor: "user_123" })) {
  console.log(event.id, event.action);
}

// Verify an event's cryptographic integrity
const result = await st.events.verify("evt_abc123");
console.log(result.valid);       // true/false
console.log(result.chainIntact); // hash chain verification
```

### Chains

```typescript
// List all chains
const chains = await st.chains.list();

// Get chain status
const chain = await st.chains.status("chain_id");
console.log(chain.eventCount, chain.lastPosition);
```

### Error Handling

```typescript
import { SealTrail, RateLimitError, ValidationError } from "@sealtrail/sdk";

try {
  await st.events.log({ actor: "user_123", action: "test" });
} catch (err) {
  if (err instanceof RateLimitError) {
    console.log("Rate limited, retry after:", err.retryAfter);
  } else if (err instanceof ValidationError) {
    console.log("Invalid input:", err.details);
  }
}
```

All error classes: `AuthenticationError` (401), `ForbiddenError` (403), `NotFoundError` (404), `ValidationError` (400), `RateLimitError` (429), `QuotaExceededError` (429), `ConflictError` (409), `InternalError` (5xx).

## Requirements

- Node.js 18+ / Bun / Deno (any runtime with `globalThis.fetch`)
- Zero dependencies

## Documentation

Full docs and guides at [sealtrail.dev/docs](https://sealtrail.dev/docs)

## Contributing

Bug reports and pull requests are welcome on [GitHub](https://github.com/zerolooplabs/sealtrail-docs).

## License

[MIT](./LICENSE) - Zero Loop Labs