Skip to content
Volidator Docs

VolidatorClient

VolidatorClient is the main class exported by @volidator/node. Create one instance per application process and reuse it.

Import

Section titled “Import”
import { VolidatorClient } from '@volidator/node';

Constructor

Section titled “Constructor”
new VolidatorClient(config: VolidatorClientConfig)

Config options

Section titled “Config options”
Name Type Required Default Description
apiKey string Yes Bearer token for the ingestion worker. Authenticate requests to POST /v1/log.
encryptionKey string No AES-256-GCM client-side encryption key. Required if keyring and activeEncryptionKeyId are not provided. The SDK hashes it with SHA-256 to derive a 256-bit key.
activeEncryptionKeyId string No Specifies which key ID from the keyring to use for encrypting new incoming logs.
keyring Record<string, string> No A mapping of key IDs to encryption key strings. Used to retain historical keys for decrypting older logs while writing with the active key. Maximum of 5 keys.
endpoint string No https://ingestion.volidator.com Base URL of the ingestion worker. Override to proxy requests through a custom domain or gateway.
projectId string No Required for generateEmbedToken(). Found in the Volidator project settings.
clientSecret string No Required for generateEmbedToken(). Used to sign HS256 JWTs.
telemetry TelemetryConfig No { preset: 'standard' } Controls IP, user-agent, and location collection. See Telemetry Presets.
redactKeys string[] No [] Fields to replace with [REDACTED:key] before encryption. Supports 'actor', 'target', and 'metadata.fieldName'.
referenceKeys string[] No [] Fields to replace with [REF:id] before encryption. Supports 'actor', 'target', and 'metadata.fieldName'. Enables JIT Hydration.

TelemetryConfig

Section titled “TelemetryConfig”
Name Type Values Description
preset string 'strict', 'standard', 'full' Shorthand for a set of ip/userAgent/location defaults.
ip string 'track', 'anonymize', 'skip' Overrides the preset’s IP setting.
userAgent string 'track', 'parse', 'skip' Overrides the preset’s user-agent setting.
location boolean Overrides the preset’s location collection setting.

Methods

Section titled “Methods”

Example

Section titled “Example”

Single-Key Setup

Section titled “Single-Key Setup”
import { VolidatorClient } from '@volidator/node';


export const volidator = new VolidatorClient({
  apiKey: process.env.VOLIDATOR_API_KEY!,
  encryptionKey: process.env.VOLIDATOR_ENCRYPTION_KEY!,
  projectId: process.env.VOLIDATOR_PROJECT_ID,
  clientSecret: process.env.VOLIDATOR_CLIENT_SECRET,
  telemetry: { preset: 'standard' },
  redactKeys: ['metadata.ssn'],
  referenceKeys: ['actor', 'metadata.email'], // Enables JIT Hydration
});

Keyring Rotation Setup

Section titled “Keyring Rotation Setup”
import { VolidatorClient } from '@volidator/node';


export const volidator = new VolidatorClient({
  apiKey: process.env.VOLIDATOR_API_KEY!,
  activeEncryptionKeyId: 'v2',
  keyring: {
    'v2': process.env.VOLIDATOR_ENCRYPTION_KEY_V2!,
    'v1': process.env.VOLIDATOR_ENCRYPTION_KEY_V1!,
  },
  projectId: process.env.VOLIDATOR_PROJECT_ID,
  clientSecret: process.env.VOLIDATOR_CLIENT_SECRET,
});
Section titled “Related”