@overdoser/timeline-client

Zero-dependency ingest client for CRK Timeline: send the events your application emits — requests, responses, jobs, stages — onto a live, searchable timeline. Works in Node 18+ and browsers (global fetch), ships ESM + CJS + TypeScript types.

npm install @overdoser/timeline-client

Setup

Create an application and a tlt_… API key in the timeline UI (Applications → Generate API key), then:

import { createTimelineClient } from '@overdoser/timeline-client';

const timeline = createTimelineClient({
  url: 'https://timeline.overdoser.org',
  apiKey: process.env.CRK_KEY,
});

Running the relay sidecar next to your app? Point url at it instead (http://localhost:7740) — same contract, sub-millisecond local acks, and apiKey becomes optional when the relay holds one.

Usage (TypeScript / ESM)

// Fire-and-forget: never throws, never blocks your request path.
timeline.event('ORDER-2481', {
  service: 'orders',
  op: 'order.create',
  method: 'POST',
  url: '/internal/orders',
  status: 201,
});

// A stage with a duration: begin → (work) → complete. The two messages
// correlate via the key — they may even be sent from different processes,
// in any order — and render as ONE bar spanning the real duration.
timeline.begin('ORDER-2481', 'charge-91b2', { service: 'payments', op: 'charge' });
// … work …
timeline.complete('ORDER-2481', 'charge-91b2', { status: 200, response: { state: 'captured' } });

// Awaited batch (up to 1000 events) — throws on failure.
await timeline.send('ORDER-2481', [
  { service: 'notifications', op: 'email.send', startedAt: Date.now() },
]);

Usage (plain JavaScript / CommonJS)

const { createTimelineClient } = require('@overdoser/timeline-client');

const timeline = createTimelineClient({
  url: 'https://timeline.overdoser.org',
  apiKey: process.env.CRK_KEY,
});

timeline.event('JOB-4711', { service: 'worker', op: 'job.run', status: 200 });

API

createTimelineClient({ url, apiKey?, onError?, fetch? }) → client:

| Method | Behavior | |---|---| | send(manifestId, events) | Awaited batch (≤ 1000 events). Throws on non-2xx. | | event(manifestId, event) | Fire-and-forget single event. Errors go to onError (default console.error). | | begin(manifestId, key, event?) | Start an in-flight stage — renders as a growing dashed bar. | | complete(manifestId, key, patch?) | Close that stage: merges status/response/… and stamps the end time. |

Every event field is optional (service, op, origin/destination, method/url/status, request/response, free-form properties, startedAt/endedAt) — see the event reference for what each one does on the timeline. Types are exported: EventInput, IngestRequest, IngestResponse, TimelineClient, TimelineClientOptions.