Quickstart

This page covers installation, client initialization, and sending your first log. The entire integration takes under 5 minutes.

Install

npm install @volidator/node

Initialize the client

Create one VolidatorClient instance per application and reuse it. Initializing per-request is wasteful.

import { VolidatorClient } from '@volidator/node';

export const volidator = new VolidatorClient({
  apiKey: process.env.VOLIDATOR_API_KEY!,
  encryptionKey: process.env.VOLIDATOR_ENCRYPTION_KEY!,
});

The apiKey authenticates requests to the ingestion worker. The encryptionKey is the AES-256-GCM key used to encrypt log payloads client-side before they leave your server.

Store both values as environment secrets. Never commit them.

Send a log

await volidator.log({
  actor: 'user_abc123',
  action: 'invoice.download',
  target: 'invoice_789',
  metadata: {
    invoiceNumber: 'INV-2024-001',
    amount: 4900,
  },
});

log() returns true if the log was accepted by the ingestion worker, false otherwise. It does not throw.

Add request context

Pass the HTTP request object directly. The SDK extracts IP, user-agent, and geolocation headers automatically.

// In a Next.js route handler:
await volidator.log({
  actor: session.userId,
  action: 'settings.update',
  req: request,
});

Supported runtimes: Node.js IncomingMessage, Cloudflare Request, and any runtime with a Headers object.

Next steps

• Read Installation for the full constructor option table.
• Read Telemetry to control what context data is collected.
• Read PII Redaction if you need HIPAA or GDPR compliance out of the box.