Core reference
Event schema, configuration and transport interface of @doclight/core 0.1.0, for building adapters and custom transports.
@doclight/core provides event validation, redaction, queueing, flushing and the Transport interface. Version
covered: npm 0.1.0. Source: sdk-core ·
npm.
pnpm add @doclight/[email protected]Requires Node.js >=18; depends on zod.
Core alone sends nothing
The default transport is NoopTransport, so new Doclight(...) from core does not deliver events over HTTP. For normal
applications use createDoclight() from @doclight/node.
website_request and trackWebsiteRequest() are not in 0.1.0; they exist only in repository code. Do not use them.
Configuration
| Option | Default | Notes |
|---|---|---|
apiKey | required | Server-side only |
projectId | required | |
endpoint | https://ingest.doclight.app | Base URL; /v1/events/batch is appended |
environment | none | Free-form label |
transport.batchSize | 50 | Contract maximum is 500 |
transport.flushIntervalMs | 3000 | |
transport.maxQueueSize | 5000 | |
transport.requestTimeoutMs | 500 | |
transport.dropPolicy | drop_oldest | or drop_newest |
transport.retries | 3 | |
privacy.captureInputs / captureOutputs | false | |
privacy.captureContext | true | Set false to drop context |
privacy.redactSecrets | true | Do not disable |
debug | false | Warn-once diagnostics |
enabled | true | |
strict | false |
Event fields
Wire format is camelCase. The client supplies eventId and timestamp.
| Field | Type |
|---|---|
eventId, timestamp (ISO 8601), type, sessionId | required |
traceId, parentId, environment, source (sdk, synthetic, manual) | optional |
agentType, agentVendor, model, goal, stepName | optional strings |
toolName, mcpServerName | optional strings |
apiEndpoint, httpMethod (GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS) | optional |
status (success, failed, timeout, cancelled), durationMs (non-negative integer) | optional |
errorType, errorMessageRedacted, inputSchemaHash, outputSchemaHash | optional strings |
metadata, context | records of string, number or boolean values; at most 50 keys and 1 KB serialized |
Rules: tool_called requires toolName; api_called requires apiEndpoint; error_occurred requires errorType.
Event types: session_started, session_completed, agent_detected, step_started, step_completed, tool_listed,
tool_called, resource_read, prompt_used, api_called, error_occurred, retry_attempted, auth_failed,
schema_validation_failed, rate_limited, timeout_occurred.
Batch contract
POST {endpoint}/v1/events/batch with { schemaVersion: "1", projectId, sdk: { name, version }, events: [1..500] }.
The response schema is { accepted, rejected, errors?: [{ index, reason }] }. In 0.1.0 the Node transport does not
read this body; see delivery and limits.
Custom transport
Implement Transport: send(batch, { timeoutMs }) resolves to { ok: true } or { ok: false, retryable, reason }.
Retryable failures are retried with backoff up to transport.retries.
Other exports
Doclight, NoopTransport, redactEvent, redactString, REDACTION_PATTERNS, DOCLIGHT_EVENT_TYPES, SCHEMA_VERSION,
INGEST_BATCH_PATH, DEFAULT_INGEST_ENDPOINT, and the Zod schemas (doclightEventSchema, doclightConfigSchema,
ingestBatchRequestSchema, ingestBatchResponseSchema, ...).