auditledge

Official JavaScript SDK for Auditledge — the audit log API for SaaS developers.

Add "who did what and when" to your app in minutes. No infrastructure to manage, no database to maintain.

Install

npm install auditledge

Quickstart

const AuditLedge = require('auditledge');

const client = new AuditLedge('your_api_key');

// Log an event
await client.log({
  actor: { id: 'user_123', name: 'Alice', email: 'alice@example.com' },
  action: 'invoice.deleted',
  resource: { type: 'invoice', id: 'inv_456', name: 'Invoice #1042' },
  organization_id: 'org_789',
  metadata: { ip: '192.168.1.1' }
});

// Query events
const events = await client.query({
  organization_id: 'org_789',
  from: '2026-01-01T00:00:00Z',
  limit: 50
});

// Export events
const csv = await client.export({
  format: 'csv',
  organization_id: 'org_789'
});

API Reference

new AuditLedge(apiKey, options?)

Parameter	Type	Description
apiKey	string	Your Auditledge API key
options.baseUrl	string	Override API base URL (optional)

client.log(event)

Log an audit event.

Field	Type	Required	Description
actor	object	✅	Who performed the action
actor.id	string	✅	Unique actor ID
actor.name	string	—	Display name
actor.email	string	—	Email address
action	string	✅	Action name (e.g. invoice.deleted)
resource	object	—	What was affected
resource.type	string	—	Resource type
resource.id	string	—	Resource ID
organization_id	string	—	Organization/tenant ID
metadata	object	—	Any additional data

client.query(filters?)

Query audit events with optional filters.

Filter	Type	Description
actor_id	string	Filter by actor
action	string	Filter by action
organization_id	string	Filter by organization
from	string	ISO date start
to	string	ISO date end
limit	number	Max results (default 50)
offset	number	Pagination offset

client.get(eventId)

Get a single event by ID.

client.export(options?)

Export events as CSV or JSON.

Option	Type	Description
format	string	csv or json
organization_id	string	Filter by organization
from	string	ISO date start
to	string	ISO date end

Common Action Naming Convention

We recommend dot-notation for action names:

user.created
user.deleted
invoice.sent
invoice.deleted
subscription.upgraded
subscription.cancelled
settings.updated
member.invited
member.removed

Framework Examples

See auditledge-examples for full examples with:

• Next.js
• Express
• NestJS

Links

• 🌐 Website: auditledge.com
• 📖 Docs: docs.auditledge.com
• 📦 npm: npmjs.com/package/auditledge
• 🐛 Issues: github.com/auditledge/auditledge-js/issues

License

MIT