@analytickit/sdk-node

Status: published. npm install @analytickit/sdk-node

Node client for AgentGraph. Two things live in this package:

1. A plain track()/trackBatch() client — for an AI agent, job, or backend service that wants to emit its own events.
2. Request middleware (trackRequest() plus three framework adapters) that turns any Node server into a server-side event collector, so traffic that never runs the browser SDK's JavaScript — AI crawlers in particular — still produces events.

Full install guide and the F0.3 access-log import mapping: docs/help/server-side-collection.md.

Install

npm install @analytickit/sdk-node

(Inside this monorepo, import it as @analytickit/sdk-node from any workspace, no install step needed.)

Client

import { AnalyticKit } from '@analytickit/sdk-node';

const client = new AnalyticKit({
  apiKey: process.env.ANALYTICKIT_SDK_KEY!,
  endpoint: 'https://app.analytickit.com', // bare origin — no trailing /v1
  // actorType: 'human' (default) | 'ai_agent' | 'cli' | ...
  // maxRetries: 2 (default) — only retries 5xx and network errors, never 4xx
  // timeout: 5000 (default, ms)
});

track(eventName, options?)

await client.track('report_generated', {
  actorType: 'ai_agent',
  agentId: 'agent_123',
  taskId: 'task_456',
  properties: { reportType: 'weekly_summary' },
});

trackBatch(events)

const { accepted, rejected } = await client.trackBatch([
  { eventName: 'agent_step', taskId: 't1' },
  { eventName: 'agent_step', taskId: 't1' },
]);

trackRequest(context, options?)

Records one inbound HTTP request as observed by a server-side collector. Normally you don't call this directly — the middleware adapters below call it for you — but it's the primitive they're built on, useful for a custom collector (e.g. one that wants to attach a response status):

await client.trackRequest(
  { userAgent, ip, path, referrer, host, method, status },
  { eventName: 'page_view', visitorId, sessionId },
);

request_context on the sent payload takes priority over ingest's own transport headers for Web2 enrichment — see the install guide, §3.

Middleware adapters

All three are re-exported from the package root (as well as from @analytickit/sdk-node/middleware):

import {
  analyticKitExpress,
  analyticKitFastify,
  analyticKitFetch,
  extractContext,
  shouldCollect,
  DEFAULT_IGNORE,
} from '@analytickit/sdk-node';

| Export | For | | --- | --- | | analyticKitExpress(options) | app.use(...) | | analyticKitFastify(options) | app.addHook('onRequest', ...) | | analyticKitFetch(options) | Next.js middleware, Hono, edge runtimes — anything handed a Fetch API Request | | extractContext(req, options?) | Pull a RequestContext off a node-style request object directly | | shouldCollect(path, options) | The ignore/sample-rate decision, exposed standalone | | DEFAULT_IGNORE | The default ignore regex list (static assets, health checks, _next, favicon) |

All three take MiddlewareOptions — at minimum { client }. See the install guide for ignore, sampleRate, trustProxy, and onError, and for why collection adds no request latency and cannot fail the request.

Full docs, the privacy/capture_ip behavior, volume-control gotchas, and the F0.3 CSV access-log import mapping: docs/help/server-side-collection.md.