@scoperat/audit

Server-side audit logging SDK.

Install

npm install @scoperat/audit

Quick Start

import audit from "@scoperat/audit";

// Initialize once at server startup
audit.init("tk_live_your_write_key", {
  endpoint: "https://your-api.example.com",
});

// Log an audit event
audit.log({
  actor_type: "user",
  actor_id: "user_123",
  action: "project.created",
  target_type: "project",
  target_id: "proj_456",
  after: { name: "My Project" },
});

// Graceful shutdown (flush remaining events)
await audit.shutdown();

API

audit.init(writeKey, options)

Initialize the audit client. Must be called before any other method.

| Option | Type | Default | Description | | --------------- | ------------------------- | ------------ | ---------------------------- | | endpoint | string | required | API base URL | | flushAt | number | 20 | Flush after this many events | | flushInterval | number | 5000 | Auto-flush interval in ms | | timeout | number | 10000 | Request timeout in ms | | onError | (error, events) => void | — | Error callback |

audit.log(event)

Enqueue an audit event. Events are batched and flushed automatically.

audit.log({
  actor_type: "user", // "user" | "api_key" | "system"
  actor_id: "user_123",
  action: "document.updated",
  target_type: "document",
  target_id: "doc_789",
  before: { title: "Old Title" },
  after: { title: "New Title" },
});

audit.setActor(info)

Set persistent actor metadata merged into every event's context.actor.

audit.setActor({ name: "Alice", email: "[email protected]" });

audit.flush()

Manually flush the event buffer. Returns a Promise<FlushResult>.

audit.shutdown()

Flush remaining events and stop the auto-flush timer. Call on SIGTERM / SIGINT.

computeChanges(before, after, opts?)

Compare two objects and return only the fields that differ. Useful for generating compact before/after payloads.

import { computeChanges } from "@scoperat/audit";

const { before, after, hasChanges } = computeChanges(
  { name: "Old", status: "active", internal: "secret" },
  { name: "New", status: "active", internal: "secret" },
  { exclude: ["internal"] },
);
// before = { name: "Old" }
// after  = { name: "New" }

Features

• Auto-batching — events are buffered and sent in batches for efficiency
• Retry on failure — failed batches are re-queued for the next flush
• Change diffing — computeChanges utility for compact before/after payloads
• Graceful shutdown — flush timer uses unref() so it won't keep the process alive
• Zero dependencies — no runtime dependencies
• Tree-shakeable — marked as side-effect-free for optimal bundling
• ESM-only — ships as pure ES modules

License

MIT