Node.js SDK

API Reference

Full documentation for the Vigilry client class, its constructor, and all public methods.

Type Definitions

interface VigilryOptions {
  apiKey: string;
  baseUrl?: string; // default: "https://ingest.vigilry.com"
}

interface CaptureCorrelation {
  user_id?: string;
  customer_id?: string;
  order_id?: string;
  [key: string]: string | undefined; // any custom key
}

interface CaptureOptions {
  type: string;
  severity: "info" | "warn" | "error" | "critical";
  message: string;
  correlation?: CaptureCorrelation;
}

interface CaptureErrorContext {
  status_code?: number;
  path?: string;
  method?: string;
  correlation?: CaptureCorrelation;
}

interface IngestResult {
  jobId: string;
  status: "queued";
}

new Vigilry(options: VigilryOptions)

Creates a new Vigilry client. Create one instance and reuse it across your application.

Parameters

Name	Type	Required	Description
`options.apiKey`	string	required	Your project API key (vig_live_...).
`options.baseUrl`	string	optional	Base URL of the Ingestion Service. Defaults to https://ingest.vigilry.com. Override to https://ingest.vigilry.com for local development.

Returns

Vigilry

Example

import { Vigilry } from "@vigilry/node";

const vigilry = new Vigilry({
  apiKey: process.env.VIGILRY_API_KEY!,
  baseUrl: "https://ingest.vigilry.com", // local dev
});

vigilry.capture(options: CaptureOptions): Promise<IngestResult | null>

Send a custom event to the ingestion pipeline. Returns the job ID and status on success, or null if the request failed.

The SDK never throws. If the request fails (network error, invalid key, etc.), null is returned and the error is logged to console.error.

Parameters

Name	Type	Required	Description
`options.type`	string	required	Event type identifier (e.g. checkout_started, feature_flag_evaluated).
`options.severity`	"info" \| "warn" \| "error" \| "critical"	required	Event severity level.
`options.message`	string	required	Human-readable description of the event.
`options.correlation`	CaptureCorrelation	optional	Key-value metadata for grouping related events. Keys: user_id, customer_id, order_id, and any custom string keys.

Returns

Promise<IngestResult | null>

Example

const result = await vigilry.capture({
  type: "order_placed",
  severity: "info",
  message: "Customer placed a new order",
  correlation: {
    user_id: "usr_42",
    order_id: "ord_9988",
    customer_id: "cust_7",
  },
});
// result: { jobId: "bull-12345", status: "queued" } | null

vigilry.captureError(error: Error, context?: CaptureErrorContext): Promise<IngestResult | null>

Report a server-side error. Automatically extracts the error message and stack trace. Maps to the POST /ingest/server-error endpoint.

Safe to call without awaiting in fire-and-forget patterns, but awaiting ensures delivery before the process exits.

The stack trace is included when available and helps the risk worker identify error hotspots.

Parameters

Name	Type	Required	Description
`error`	Error	required	The error instance. Name, message, and stack are extracted automatically.
`context.status_code`	number	optional	HTTP status code of the failed request (e.g. 500).
`context.path`	string	optional	Request path where the error occurred (e.g. /api/checkout).
`context.method`	string	optional	HTTP method (GET, POST, etc.).
`context.correlation`	CaptureCorrelation	optional	Correlation context for linking this error to a user or transaction.

Returns

Promise<IngestResult | null>

Example

try {
  await processPayment(order);
} catch (err) {
  await vigilry.captureError(err as Error, {
    status_code: 500,
    path: "/api/checkout",
    method: "POST",
    correlation: {
      user_id: req.user.id,
      order_id: order.id,
    },
  });
  res.status(500).json({ error: "Payment failed" });
}