Node.js

@doclight/node is the client for server-side JavaScript. It re-exports everything from @doclight/core and adds an HTTP transport. Version covered: npm 0.1.0. Source: sdk-node · npm.

Install

pnpm add @doclight/[email protected]

Requires Node.js >=18. Configure DOCLIGHT_API_KEY, DOCLIGHT_PROJECT_ID and DOCLIGHT_ENDPOINT in the server environment as described on the Express page.

Send explicit events

Use one initialized client for the process, not one per request:

import { createDoclight } from "@doclight/node";

function required(name) {
  const value = process.env[name];
  if (!value) throw new Error(`${name} is required`);
  return value;
}

const client = createDoclight({
  apiKey: required("DOCLIGHT_API_KEY"),
  projectId: required("DOCLIGHT_PROJECT_ID"),
  endpoint: required("DOCLIGHT_ENDPOINT"),
  lifecycleHooks: false,
});

const sessionId = client.startSession("integration-smoke-test");
client.track("api_called", {
  sessionId,
  apiEndpoint: "/pricing",
  httpMethod: "GET",
  status: "success",
  durationMs: 12,
  metadata: { statusCode: "200", routePattern: "/pricing" },
});
client.endSession(sessionId, "success");
await client.shutdown();
console.log(client.getStats());

This sends explicit test events; it does not wrap a real HTTP request.

Client methods

Configuration

createDoclight(config) takes the core configuration plus lifecycleHooks.

Lifecycle hooks (flush on process exit signals) are on by default for the Node client. Pass lifecycleHooks: false when your application owns shutdown, or in a short script. The published Express and MCP wrappers turn them off internally.

Delivery and limits

The transport sends POST {endpoint}/v1/events/batch with a Bearer Authorization header, JSON content type and an x-doclight-sdk header. The body holds schemaVersion, projectId, SDK identity and events.

Override these under transport. Keep batchSize at or below the contract maximum of 500 events per request.

• HTTP 408, 429, 5xx and network errors (including timeouts) are retryable; other 4xx are not.
• In 0.1.0, any 2xx response counts as success, even if its body reports rejected events. Retry-After is not honored.
• Therefore sent means transport-level success, not durable ingestion or dashboard visibility. Confirm records on the receiver.
• The queue lives in memory. A crash or queue overflow loses events. This is best-effort instrumentation, not an audit log.