sealtrail 0.1.0

package/README.md

@@ -0,0 +1,121 @@
+# sealtrail
+
+Official Node.js SDK for the [SealTrail](https://sealtrail.dev) cryptographic audit trail API.
+
+## Installation
+
+```bash
+npm install sealtrail
+```
+
+## Quick Start
+
+```typescript
+import { SealTrail } from "sealtrail";
+
+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";
+
+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`)
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,396 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  AuthenticationError: () => AuthenticationError,
+  ConflictError: () => ConflictError,
+  ForbiddenError: () => ForbiddenError,
+  InternalError: () => InternalError,
+  NotFoundError: () => NotFoundError,
+  QuotaExceededError: () => QuotaExceededError,
+  RateLimitError: () => RateLimitError,
+  SealTrail: () => SealTrail,
+  SealTrailError: () => SealTrailError,
+  ValidationError: () => ValidationError
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/errors.ts
+var SealTrailError = class extends Error {
+  constructor(message, code, status, details) {
+    super(message);
+    this.code = code;
+    this.status = status;
+    this.details = details;
+    this.name = "SealTrailError";
+  }
+};
+var AuthenticationError = class extends SealTrailError {
+  constructor(message, code) {
+    super(message, code, 401);
+    this.name = "AuthenticationError";
+  }
+};
+var ForbiddenError = class extends SealTrailError {
+  constructor(message, code) {
+    super(message, code, 403);
+    this.name = "ForbiddenError";
+  }
+};
+var NotFoundError = class extends SealTrailError {
+  constructor(message, code) {
+    super(message, code, 404);
+    this.name = "NotFoundError";
+  }
+};
+var ValidationError = class extends SealTrailError {
+  constructor(message, code, details) {
+    super(message, code, 400, details);
+    this.name = "ValidationError";
+  }
+};
+var ConflictError = class extends SealTrailError {
+  constructor(message, code) {
+    super(message, code, 409);
+    this.name = "ConflictError";
+  }
+};
+var RateLimitError = class extends SealTrailError {
+  retryAfter;
+  constructor(message, code, retryAfter) {
+    super(message, code, 429);
+    this.name = "RateLimitError";
+    this.retryAfter = retryAfter;
+  }
+};
+var QuotaExceededError = class extends SealTrailError {
+  constructor(message, code) {
+    super(message, code, 429);
+    this.name = "QuotaExceededError";
+  }
+};
+var InternalError = class extends SealTrailError {
+  constructor(message, code, status) {
+    super(message, code, status);
+    this.name = "InternalError";
+  }
+};
+function mapError(status, body, retryAfter) {
+  const { code, message, details } = body.error;
+  switch (status) {
+    case 400:
+      return new ValidationError(message, code, details);
+    case 401:
+      return new AuthenticationError(message, code);
+    case 403:
+      return new ForbiddenError(message, code);
+    case 404:
+      return new NotFoundError(message, code);
+    case 409:
+      return new ConflictError(message, code);
+    case 429:
+      if (code === "QUOTA_EXCEEDED") {
+        return new QuotaExceededError(message, code);
+      }
+      return new RateLimitError(message, code, retryAfter);
+    default:
+      if (status >= 500) {
+        return new InternalError(message, code, status);
+      }
+      return new SealTrailError(message, code, status, details);
+  }
+}
+
+// src/version.ts
+var VERSION = true ? "0.1.0" : "0.1.0";
+
+// src/lib/fetch.ts
+var DEFAULT_BASE_URL = "https://api.sealtrail.dev";
+var DEFAULT_TIMEOUT = 3e4;
+var DEFAULT_MAX_RETRIES = 3;
+var MAX_BACKOFF = 3e4;
+function resolveConfig(config) {
+  return {
+    apiKey: config.apiKey,
+    baseUrl: (config.baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/, ""),
+    timeout: config.timeout ?? DEFAULT_TIMEOUT,
+    maxRetries: config.maxRetries ?? DEFAULT_MAX_RETRIES,
+    debug: config.debug ?? false,
+    fetch: config.fetch ?? globalThis.fetch
+  };
+}
+function buildUrl(baseUrl, path, query) {
+  const url = new URL(path, baseUrl);
+  if (query) {
+    for (const [key, value] of Object.entries(query)) {
+      if (value !== void 0) {
+        url.searchParams.set(key, String(value));
+      }
+    }
+  }
+  return url.toString();
+}
+function backoff(attempt) {
+  const base = Math.min(1e3 * 2 ** attempt, MAX_BACKOFF);
+  return base + Math.random() * base * 0.25;
+}
+function isRetryable(status, method) {
+  if (status === 429 || status >= 500) return true;
+  if (status === 409 && method === "POST") return true;
+  return false;
+}
+function parseRetryAfter(headers) {
+  const retryAfter = headers.get("retry-after");
+  if (retryAfter) {
+    const seconds = Number(retryAfter);
+    if (!Number.isNaN(seconds)) return seconds;
+  }
+  const reset = headers.get("ratelimit-reset");
+  if (reset) {
+    const timestamp = Number(reset);
+    if (!Number.isNaN(timestamp)) {
+      return Math.max(0, timestamp - Math.floor(Date.now() / 1e3));
+    }
+  }
+  return void 0;
+}
+async function request(config, method, path, options) {
+  const url = buildUrl(config.baseUrl, path, options?.query);
+  const headers = {
+    Authorization: `Bearer ${config.apiKey}`,
+    "User-Agent": `sealtrail-node/${VERSION}`
+  };
+  if (options?.body !== void 0) {
+    headers["Content-Type"] = "application/json";
+  }
+  let lastError;
+  for (let attempt = 0; attempt <= config.maxRetries; attempt++) {
+    if (attempt > 0) {
+      const retryAfterMs = lastError instanceof RateLimitError && lastError.retryAfter !== void 0 ? lastError.retryAfter * 1e3 : 0;
+      const delay = Math.max(backoff(attempt - 1), retryAfterMs);
+      if (config.debug) {
+        console.debug(
+          `[sealtrail] retry ${attempt}/${config.maxRetries} after ${Math.round(delay)}ms`
+        );
+      }
+      await new Promise((r) => setTimeout(r, delay));
+    }
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), config.timeout);
+    const start = Date.now();
+    try {
+      const response = await config.fetch(url, {
+        method,
+        headers,
+        body: options?.body !== void 0 ? JSON.stringify(options.body) : void 0,
+        signal: controller.signal
+      });
+      if (config.debug) {
+        console.debug(
+          `[sealtrail] ${method} ${path} \u2192 ${response.status} (${Date.now() - start}ms)`
+        );
+      }
+      if (response.ok) {
+        return await response.json();
+      }
+      let errorBody;
+      try {
+        errorBody = await response.json();
+      } catch {
+        errorBody = {
+          error: {
+            code: "UNKNOWN",
+            message: `HTTP ${response.status}`
+          }
+        };
+      }
+      const retryAfter = parseRetryAfter(response.headers);
+      const error = mapError(response.status, errorBody, retryAfter);
+      if (error instanceof QuotaExceededError) {
+        throw error;
+      }
+      if (isRetryable(response.status, method) && attempt < config.maxRetries) {
+        lastError = error;
+        continue;
+      }
+      throw error;
+    } catch (err) {
+      if (err instanceof Error && err.name === "AbortError") {
+        lastError = new Error(`Request timed out after ${config.timeout}ms`);
+        if (attempt < config.maxRetries) continue;
+        throw lastError;
+      }
+      if (err instanceof RateLimitError || err instanceof ConflictError || err instanceof Error && "status" in err) {
+        throw err;
+      }
+      lastError = err instanceof Error ? err : new Error(String(err));
+      if (attempt < config.maxRetries) continue;
+      throw lastError;
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
+  throw lastError ?? new Error("Request failed after retries");
+}
+
+// src/resources/base.ts
+var BaseResource = class {
+  constructor(client) {
+    this.client = client;
+  }
+};
+
+// src/resources/chains.ts
+var ChainsResource = class extends BaseResource {
+  /**
+   * List all chains for the authenticated tenant.
+   */
+  async list() {
+    const response = await this.client._request("GET", "/v1/chains");
+    return response.data;
+  }
+  /**
+   * Get the current status of a specific chain.
+   */
+  async status(chainId) {
+    const response = await this.client._request(
+      "GET",
+      `/v1/chain/${chainId}/status`
+    );
+    return response.data;
+  }
+};
+
+// src/lib/pagination.ts
+function createAutoPaginator(fetchPage) {
+  return {
+    [Symbol.asyncIterator]() {
+      let currentPage = [];
+      let nextCursor = void 0;
+      let index = 0;
+      let started = false;
+      let done = false;
+      return {
+        async next() {
+          while (index >= currentPage.length) {
+            if (done) return { done: true, value: void 0 };
+            if (started && nextCursor === void 0) {
+              done = true;
+              return { done: true, value: void 0 };
+            }
+            const result = await fetchPage(started ? nextCursor : void 0);
+            started = true;
+            currentPage = result.data;
+            nextCursor = result.nextCursor;
+            index = 0;
+            if (currentPage.length === 0) {
+              done = true;
+              return { done: true, value: void 0 };
+            }
+          }
+          return { done: false, value: currentPage[index++] };
+        }
+      };
+    }
+  };
+}
+
+// src/resources/events.ts
+var EventsResource = class extends BaseResource {
+  /**
+   * Log a new audit event to the chain.
+   */
+  async log(params) {
+    const response = await this.client._request("POST", "/v1/events", {
+      body: params
+    });
+    return response.data;
+  }
+  /**
+   * List events with optional filters and cursor pagination.
+   */
+  async list(params) {
+    return this.client._request("GET", "/v1/events", {
+      query: params
+    });
+  }
+  /**
+   * Get a single event by ID.
+   */
+  async get(eventId) {
+    const response = await this.client._request(
+      "GET",
+      `/v1/events/${eventId}`
+    );
+    return response.data;
+  }
+  /**
+   * Verify the hash integrity of an event.
+   */
+  async verify(eventId) {
+    return this.client._request("GET", `/v1/events/${eventId}/verify`);
+  }
+  /**
+   * Auto-paginate through all events matching the given filters.
+   *
+   * @example
+   * ```ts
+   * for await (const event of st.events.listAutoPaginate({ actor: 'user_123' })) {
+   *   console.log(event.id);
+   * }
+   * ```
+   */
+  listAutoPaginate(params) {
+    return createAutoPaginator((cursor) => this.list({ ...params, cursor }));
+  }
+};
+
+// src/client.ts
+var SealTrail = class {
+  events;
+  chains;
+  config;
+  constructor(config) {
+    if (!config.apiKey) {
+      throw new Error("SealTrail: apiKey is required");
+    }
+    this.config = resolveConfig(config);
+    this.events = new EventsResource(this);
+    this.chains = new ChainsResource(this);
+  }
+  /** @internal Used by resources to make API requests */
+  async _request(method, path, options) {
+    return request(this.config, method, path, options);
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  AuthenticationError,
+  ConflictError,
+  ForbiddenError,
+  InternalError,
+  NotFoundError,
+  QuotaExceededError,
+  RateLimitError,
+  SealTrail,
+  SealTrailError,
+  ValidationError
+});

package/dist/index.d.cts

@@ -0,0 +1,176 @@
+interface SealTrailConfig {
+    /** API key starting with stl_live_ or stl_test_ */
+    apiKey: string;
+    /** API base URL (default: "https://api.sealtrail.dev") */
+    baseUrl?: string;
+    /** Request timeout in ms (default: 30000) */
+    timeout?: number;
+    /** Max retry attempts on 429/5xx/409 (default: 3) */
+    maxRetries?: number;
+    /** Log requests to console.debug (default: false) */
+    debug?: boolean;
+    /** Custom fetch implementation for edge runtimes */
+    fetch?: typeof globalThis.fetch;
+}
+interface LogEventParams {
+    /** Who performed the action */
+    actor: string;
+    /** What action was performed */
+    action: string;
+    /** What resource was affected */
+    resource?: string;
+    /** Additional context metadata */
+    context?: Record<string, unknown>;
+    /** Chain name (default: "default") */
+    chain?: string;
+}
+interface AuditEvent {
+    id: string;
+    actor: string;
+    action: string;
+    resource: string | null;
+    context: Record<string, unknown> | null;
+    chain: {
+        id: string;
+        name: string;
+        position: number;
+    };
+    hash: string;
+    previousHash: string;
+    timestamp: string;
+    createdAt: string;
+}
+interface ListEventsParams {
+    /** Cursor for pagination */
+    cursor?: string;
+    /** Number of results per page (1-200) */
+    limit?: number;
+    /** Filter by actor */
+    actor?: string;
+    /** Filter by action */
+    action?: string;
+    /** Filter by resource */
+    resource?: string;
+    /** Filter by chain ID */
+    chain_id?: string;
+    /** Filter events after this ISO 8601 date */
+    after?: string;
+    /** Filter events before this ISO 8601 date */
+    before?: string;
+}
+interface EventListResponse {
+    data: AuditEvent[];
+    nextCursor?: string;
+}
+interface VerifyResult {
+    valid: boolean;
+    errors: string[];
+    eventHash: string;
+    computedHash: string;
+    chainIntact: boolean;
+    verifiedAt: string;
+}
+interface Chain {
+    id: string;
+    name: string;
+    lastHash: string;
+    lastPosition: number;
+    eventCount: number;
+    createdAt: string;
+}
+interface RequestOptions {
+    body?: unknown;
+    query?: Record<string, string | number | undefined>;
+}
+
+interface ResourceClient {
+    _request<T>(method: string, path: string, options?: RequestOptions): Promise<T>;
+}
+declare abstract class BaseResource {
+    protected readonly client: ResourceClient;
+    constructor(client: ResourceClient);
+}
+
+declare class ChainsResource extends BaseResource {
+    /**
+     * List all chains for the authenticated tenant.
+     */
+    list(): Promise<Chain[]>;
+    /**
+     * Get the current status of a specific chain.
+     */
+    status(chainId: string): Promise<Chain>;
+}
+
+declare class EventsResource extends BaseResource {
+    /**
+     * Log a new audit event to the chain.
+     */
+    log(params: LogEventParams): Promise<AuditEvent>;
+    /**
+     * List events with optional filters and cursor pagination.
+     */
+    list(params?: ListEventsParams): Promise<EventListResponse>;
+    /**
+     * Get a single event by ID.
+     */
+    get(eventId: string): Promise<AuditEvent>;
+    /**
+     * Verify the hash integrity of an event.
+     */
+    verify(eventId: string): Promise<VerifyResult>;
+    /**
+     * Auto-paginate through all events matching the given filters.
+     *
+     * @example
+     * ```ts
+     * for await (const event of st.events.listAutoPaginate({ actor: 'user_123' })) {
+     *   console.log(event.id);
+     * }
+     * ```
+     */
+    listAutoPaginate(params?: Omit<ListEventsParams, "cursor">): AsyncIterable<AuditEvent>;
+}
+
+declare class SealTrail {
+    readonly events: EventsResource;
+    readonly chains: ChainsResource;
+    private readonly config;
+    constructor(config: SealTrailConfig);
+    /** @internal Used by resources to make API requests */
+    _request<T>(method: string, path: string, options?: RequestOptions): Promise<T>;
+}
+
+declare class SealTrailError extends Error {
+    readonly code: string;
+    readonly status: number;
+    readonly details?: Record<string, string[]> | undefined;
+    constructor(message: string, code: string, status: number, details?: Record<string, string[]> | undefined);
+}
+declare class AuthenticationError extends SealTrailError {
+    constructor(message: string, code: string);
+}
+declare class ForbiddenError extends SealTrailError {
+    constructor(message: string, code: string);
+}
+declare class NotFoundError extends SealTrailError {
+    constructor(message: string, code: string);
+}
+declare class ValidationError extends SealTrailError {
+    constructor(message: string, code: string, details?: Record<string, string[]>);
+}
+declare class ConflictError extends SealTrailError {
+    constructor(message: string, code: string);
+}
+declare class RateLimitError extends SealTrailError {
+    readonly retryAfter?: number;
+    constructor(message: string, code: string, retryAfter?: number);
+}
+declare class QuotaExceededError extends SealTrailError {
+    constructor(message: string, code: string);
+}
+declare class InternalError extends SealTrailError {
+    constructor(message: string, code: string, status: number);
+}
+
+export { type AuditEvent, AuthenticationError, type Chain, ConflictError, type EventListResponse, ForbiddenError, InternalError, type ListEventsParams, type LogEventParams, NotFoundError, QuotaExceededError, RateLimitError, SealTrail, type SealTrailConfig, SealTrailError, ValidationError, type VerifyResult };

package/dist/index.d.ts

@@ -0,0 +1,176 @@
+interface SealTrailConfig {
+    /** API key starting with stl_live_ or stl_test_ */
+    apiKey: string;
+    /** API base URL (default: "https://api.sealtrail.dev") */
+    baseUrl?: string;
+    /** Request timeout in ms (default: 30000) */
+    timeout?: number;
+    /** Max retry attempts on 429/5xx/409 (default: 3) */
+    maxRetries?: number;
+    /** Log requests to console.debug (default: false) */
+    debug?: boolean;
+    /** Custom fetch implementation for edge runtimes */
+    fetch?: typeof globalThis.fetch;
+}
+interface LogEventParams {
+    /** Who performed the action */
+    actor: string;
+    /** What action was performed */
+    action: string;
+    /** What resource was affected */
+    resource?: string;
+    /** Additional context metadata */
+    context?: Record<string, unknown>;
+    /** Chain name (default: "default") */
+    chain?: string;
+}
+interface AuditEvent {
+    id: string;
+    actor: string;
+    action: string;
+    resource: string | null;
+    context: Record<string, unknown> | null;
+    chain: {
+        id: string;
+        name: string;
+        position: number;
+    };
+    hash: string;
+    previousHash: string;
+    timestamp: string;
+    createdAt: string;
+}
+interface ListEventsParams {
+    /** Cursor for pagination */
+    cursor?: string;
+    /** Number of results per page (1-200) */
+    limit?: number;
+    /** Filter by actor */
+    actor?: string;
+    /** Filter by action */
+    action?: string;
+    /** Filter by resource */
+    resource?: string;
+    /** Filter by chain ID */
+    chain_id?: string;
+    /** Filter events after this ISO 8601 date */
+    after?: string;
+    /** Filter events before this ISO 8601 date */
+    before?: string;
+}
+interface EventListResponse {
+    data: AuditEvent[];
+    nextCursor?: string;
+}
+interface VerifyResult {
+    valid: boolean;
+    errors: string[];
+    eventHash: string;
+    computedHash: string;
+    chainIntact: boolean;
+    verifiedAt: string;
+}
+interface Chain {
+    id: string;
+    name: string;
+    lastHash: string;
+    lastPosition: number;
+    eventCount: number;
+    createdAt: string;
+}
+interface RequestOptions {
+    body?: unknown;
+    query?: Record<string, string | number | undefined>;
+}
+
+interface ResourceClient {
+    _request<T>(method: string, path: string, options?: RequestOptions): Promise<T>;
+}
+declare abstract class BaseResource {
+    protected readonly client: ResourceClient;
+    constructor(client: ResourceClient);
+}
+
+declare class ChainsResource extends BaseResource {
+    /**
+     * List all chains for the authenticated tenant.
+     */
+    list(): Promise<Chain[]>;
+    /**
+     * Get the current status of a specific chain.
+     */
+    status(chainId: string): Promise<Chain>;
+}
+
+declare class EventsResource extends BaseResource {
+    /**
+     * Log a new audit event to the chain.
+     */
+    log(params: LogEventParams): Promise<AuditEvent>;
+    /**
+     * List events with optional filters and cursor pagination.
+     */
+    list(params?: ListEventsParams): Promise<EventListResponse>;
+    /**
+     * Get a single event by ID.
+     */
+    get(eventId: string): Promise<AuditEvent>;
+    /**
+     * Verify the hash integrity of an event.
+     */
+    verify(eventId: string): Promise<VerifyResult>;
+    /**
+     * Auto-paginate through all events matching the given filters.
+     *
+     * @example
+     * ```ts
+     * for await (const event of st.events.listAutoPaginate({ actor: 'user_123' })) {
+     *   console.log(event.id);
+     * }
+     * ```
+     */
+    listAutoPaginate(params?: Omit<ListEventsParams, "cursor">): AsyncIterable<AuditEvent>;
+}
+
+declare class SealTrail {
+    readonly events: EventsResource;
+    readonly chains: ChainsResource;
+    private readonly config;
+    constructor(config: SealTrailConfig);
+    /** @internal Used by resources to make API requests */
+    _request<T>(method: string, path: string, options?: RequestOptions): Promise<T>;
+}
+
+declare class SealTrailError extends Error {
+    readonly code: string;
+    readonly status: number;
+    readonly details?: Record<string, string[]> | undefined;
+    constructor(message: string, code: string, status: number, details?: Record<string, string[]> | undefined);
+}
+declare class AuthenticationError extends SealTrailError {
+    constructor(message: string, code: string);
+}
+declare class ForbiddenError extends SealTrailError {
+    constructor(message: string, code: string);
+}
+declare class NotFoundError extends SealTrailError {
+    constructor(message: string, code: string);
+}
+declare class ValidationError extends SealTrailError {
+    constructor(message: string, code: string, details?: Record<string, string[]>);
+}
+declare class ConflictError extends SealTrailError {
+    constructor(message: string, code: string);
+}
+declare class RateLimitError extends SealTrailError {
+    readonly retryAfter?: number;
+    constructor(message: string, code: string, retryAfter?: number);
+}
+declare class QuotaExceededError extends SealTrailError {
+    constructor(message: string, code: string);
+}
+declare class InternalError extends SealTrailError {
+    constructor(message: string, code: string, status: number);
+}
+
+export { type AuditEvent, AuthenticationError, type Chain, ConflictError, type EventListResponse, ForbiddenError, InternalError, type ListEventsParams, type LogEventParams, NotFoundError, QuotaExceededError, RateLimitError, SealTrail, type SealTrailConfig, SealTrailError, ValidationError, type VerifyResult };

package/dist/index.mjs

@@ -0,0 +1,360 @@
+// src/errors.ts
+var SealTrailError = class extends Error {
+  constructor(message, code, status, details) {
+    super(message);
+    this.code = code;
+    this.status = status;
+    this.details = details;
+    this.name = "SealTrailError";
+  }
+};
+var AuthenticationError = class extends SealTrailError {
+  constructor(message, code) {
+    super(message, code, 401);
+    this.name = "AuthenticationError";
+  }
+};
+var ForbiddenError = class extends SealTrailError {
+  constructor(message, code) {
+    super(message, code, 403);
+    this.name = "ForbiddenError";
+  }
+};
+var NotFoundError = class extends SealTrailError {
+  constructor(message, code) {
+    super(message, code, 404);
+    this.name = "NotFoundError";
+  }
+};
+var ValidationError = class extends SealTrailError {
+  constructor(message, code, details) {
+    super(message, code, 400, details);
+    this.name = "ValidationError";
+  }
+};
+var ConflictError = class extends SealTrailError {
+  constructor(message, code) {
+    super(message, code, 409);
+    this.name = "ConflictError";
+  }
+};
+var RateLimitError = class extends SealTrailError {
+  retryAfter;
+  constructor(message, code, retryAfter) {
+    super(message, code, 429);
+    this.name = "RateLimitError";
+    this.retryAfter = retryAfter;
+  }
+};
+var QuotaExceededError = class extends SealTrailError {
+  constructor(message, code) {
+    super(message, code, 429);
+    this.name = "QuotaExceededError";
+  }
+};
+var InternalError = class extends SealTrailError {
+  constructor(message, code, status) {
+    super(message, code, status);
+    this.name = "InternalError";
+  }
+};
+function mapError(status, body, retryAfter) {
+  const { code, message, details } = body.error;
+  switch (status) {
+    case 400:
+      return new ValidationError(message, code, details);
+    case 401:
+      return new AuthenticationError(message, code);
+    case 403:
+      return new ForbiddenError(message, code);
+    case 404:
+      return new NotFoundError(message, code);
+    case 409:
+      return new ConflictError(message, code);
+    case 429:
+      if (code === "QUOTA_EXCEEDED") {
+        return new QuotaExceededError(message, code);
+      }
+      return new RateLimitError(message, code, retryAfter);
+    default:
+      if (status >= 500) {
+        return new InternalError(message, code, status);
+      }
+      return new SealTrailError(message, code, status, details);
+  }
+}
+
+// src/version.ts
+var VERSION = true ? "0.1.0" : "0.1.0";
+
+// src/lib/fetch.ts
+var DEFAULT_BASE_URL = "https://api.sealtrail.dev";
+var DEFAULT_TIMEOUT = 3e4;
+var DEFAULT_MAX_RETRIES = 3;
+var MAX_BACKOFF = 3e4;
+function resolveConfig(config) {
+  return {
+    apiKey: config.apiKey,
+    baseUrl: (config.baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/, ""),
+    timeout: config.timeout ?? DEFAULT_TIMEOUT,
+    maxRetries: config.maxRetries ?? DEFAULT_MAX_RETRIES,
+    debug: config.debug ?? false,
+    fetch: config.fetch ?? globalThis.fetch
+  };
+}
+function buildUrl(baseUrl, path, query) {
+  const url = new URL(path, baseUrl);
+  if (query) {
+    for (const [key, value] of Object.entries(query)) {
+      if (value !== void 0) {
+        url.searchParams.set(key, String(value));
+      }
+    }
+  }
+  return url.toString();
+}
+function backoff(attempt) {
+  const base = Math.min(1e3 * 2 ** attempt, MAX_BACKOFF);
+  return base + Math.random() * base * 0.25;
+}
+function isRetryable(status, method) {
+  if (status === 429 || status >= 500) return true;
+  if (status === 409 && method === "POST") return true;
+  return false;
+}
+function parseRetryAfter(headers) {
+  const retryAfter = headers.get("retry-after");
+  if (retryAfter) {
+    const seconds = Number(retryAfter);
+    if (!Number.isNaN(seconds)) return seconds;
+  }
+  const reset = headers.get("ratelimit-reset");
+  if (reset) {
+    const timestamp = Number(reset);
+    if (!Number.isNaN(timestamp)) {
+      return Math.max(0, timestamp - Math.floor(Date.now() / 1e3));
+    }
+  }
+  return void 0;
+}
+async function request(config, method, path, options) {
+  const url = buildUrl(config.baseUrl, path, options?.query);
+  const headers = {
+    Authorization: `Bearer ${config.apiKey}`,
+    "User-Agent": `sealtrail-node/${VERSION}`
+  };
+  if (options?.body !== void 0) {
+    headers["Content-Type"] = "application/json";
+  }
+  let lastError;
+  for (let attempt = 0; attempt <= config.maxRetries; attempt++) {
+    if (attempt > 0) {
+      const retryAfterMs = lastError instanceof RateLimitError && lastError.retryAfter !== void 0 ? lastError.retryAfter * 1e3 : 0;
+      const delay = Math.max(backoff(attempt - 1), retryAfterMs);
+      if (config.debug) {
+        console.debug(
+          `[sealtrail] retry ${attempt}/${config.maxRetries} after ${Math.round(delay)}ms`
+        );
+      }
+      await new Promise((r) => setTimeout(r, delay));
+    }
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), config.timeout);
+    const start = Date.now();
+    try {
+      const response = await config.fetch(url, {
+        method,
+        headers,
+        body: options?.body !== void 0 ? JSON.stringify(options.body) : void 0,
+        signal: controller.signal
+      });
+      if (config.debug) {
+        console.debug(
+          `[sealtrail] ${method} ${path} \u2192 ${response.status} (${Date.now() - start}ms)`
+        );
+      }
+      if (response.ok) {
+        return await response.json();
+      }
+      let errorBody;
+      try {
+        errorBody = await response.json();
+      } catch {
+        errorBody = {
+          error: {
+            code: "UNKNOWN",
+            message: `HTTP ${response.status}`
+          }
+        };
+      }
+      const retryAfter = parseRetryAfter(response.headers);
+      const error = mapError(response.status, errorBody, retryAfter);
+      if (error instanceof QuotaExceededError) {
+        throw error;
+      }
+      if (isRetryable(response.status, method) && attempt < config.maxRetries) {
+        lastError = error;
+        continue;
+      }
+      throw error;
+    } catch (err) {
+      if (err instanceof Error && err.name === "AbortError") {
+        lastError = new Error(`Request timed out after ${config.timeout}ms`);
+        if (attempt < config.maxRetries) continue;
+        throw lastError;
+      }
+      if (err instanceof RateLimitError || err instanceof ConflictError || err instanceof Error && "status" in err) {
+        throw err;
+      }
+      lastError = err instanceof Error ? err : new Error(String(err));
+      if (attempt < config.maxRetries) continue;
+      throw lastError;
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
+  throw lastError ?? new Error("Request failed after retries");
+}
+
+// src/resources/base.ts
+var BaseResource = class {
+  constructor(client) {
+    this.client = client;
+  }
+};
+
+// src/resources/chains.ts
+var ChainsResource = class extends BaseResource {
+  /**
+   * List all chains for the authenticated tenant.
+   */
+  async list() {
+    const response = await this.client._request("GET", "/v1/chains");
+    return response.data;
+  }
+  /**
+   * Get the current status of a specific chain.
+   */
+  async status(chainId) {
+    const response = await this.client._request(
+      "GET",
+      `/v1/chain/${chainId}/status`
+    );
+    return response.data;
+  }
+};
+
+// src/lib/pagination.ts
+function createAutoPaginator(fetchPage) {
+  return {
+    [Symbol.asyncIterator]() {
+      let currentPage = [];
+      let nextCursor = void 0;
+      let index = 0;
+      let started = false;
+      let done = false;
+      return {
+        async next() {
+          while (index >= currentPage.length) {
+            if (done) return { done: true, value: void 0 };
+            if (started && nextCursor === void 0) {
+              done = true;
+              return { done: true, value: void 0 };
+            }
+            const result = await fetchPage(started ? nextCursor : void 0);
+            started = true;
+            currentPage = result.data;
+            nextCursor = result.nextCursor;
+            index = 0;
+            if (currentPage.length === 0) {
+              done = true;
+              return { done: true, value: void 0 };
+            }
+          }
+          return { done: false, value: currentPage[index++] };
+        }
+      };
+    }
+  };
+}
+
+// src/resources/events.ts
+var EventsResource = class extends BaseResource {
+  /**
+   * Log a new audit event to the chain.
+   */
+  async log(params) {
+    const response = await this.client._request("POST", "/v1/events", {
+      body: params
+    });
+    return response.data;
+  }
+  /**
+   * List events with optional filters and cursor pagination.
+   */
+  async list(params) {
+    return this.client._request("GET", "/v1/events", {
+      query: params
+    });
+  }
+  /**
+   * Get a single event by ID.
+   */
+  async get(eventId) {
+    const response = await this.client._request(
+      "GET",
+      `/v1/events/${eventId}`
+    );
+    return response.data;
+  }
+  /**
+   * Verify the hash integrity of an event.
+   */
+  async verify(eventId) {
+    return this.client._request("GET", `/v1/events/${eventId}/verify`);
+  }
+  /**
+   * Auto-paginate through all events matching the given filters.
+   *
+   * @example
+   * ```ts
+   * for await (const event of st.events.listAutoPaginate({ actor: 'user_123' })) {
+   *   console.log(event.id);
+   * }
+   * ```
+   */
+  listAutoPaginate(params) {
+    return createAutoPaginator((cursor) => this.list({ ...params, cursor }));
+  }
+};
+
+// src/client.ts
+var SealTrail = class {
+  events;
+  chains;
+  config;
+  constructor(config) {
+    if (!config.apiKey) {
+      throw new Error("SealTrail: apiKey is required");
+    }
+    this.config = resolveConfig(config);
+    this.events = new EventsResource(this);
+    this.chains = new ChainsResource(this);
+  }
+  /** @internal Used by resources to make API requests */
+  async _request(method, path, options) {
+    return request(this.config, method, path, options);
+  }
+};
+export {
+  AuthenticationError,
+  ConflictError,
+  ForbiddenError,
+  InternalError,
+  NotFoundError,
+  QuotaExceededError,
+  RateLimitError,
+  SealTrail,
+  SealTrailError,
+  ValidationError
+};

package/package.json

@@ -0,0 +1,51 @@
+{
+	"name": "sealtrail",
+	"version": "0.1.0",
+	"description": "Official Node.js SDK for the SealTrail cryptographic audit trail API",
+	"type": "module",
+	"sideEffects": false,
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.mjs",
+			"require": {
+				"types": "./dist/index.d.cts",
+				"default": "./dist/index.cjs"
+			}
+		}
+	},
+	"main": "./dist/index.cjs",
+	"module": "./dist/index.mjs",
+	"types": "./dist/index.d.ts",
+	"files": ["dist", "README.md", "LICENSE"],
+	"engines": {
+		"node": ">=18"
+	},
+	"scripts": {
+		"build": "tsup",
+		"test": "vitest run",
+		"test:watch": "vitest",
+		"typecheck": "tsc --build",
+		"prepublishOnly": "npm run build"
+	},
+	"keywords": [
+		"audit",
+		"audit-trail",
+		"audit-log",
+		"compliance",
+		"cryptographic",
+		"hash-chain",
+		"sealtrail"
+	],
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/zerolooplabs/sealtrail"
+	},
+	"homepage": "https://sealtrail.dev",
+	"devDependencies": {
+		"tsup": "^8.4.0",
+		"typescript": "^5.7.3",
+		"vitest": "^3.1.1"
+	}
+}