@analytickit/sdk-node 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AnalyticKit
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,108 @@
-# Temporary Holding Version
+# `@analytickit/sdk-node`
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> **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`](../../docs/help/server-side-collection.md).
+
+## Install
+
+```bash
+npm install @analytickit/sdk-node
+```
+
+(Inside this monorepo, import it as `@analytickit/sdk-node` from any
+workspace, no install step needed.)
+
+## Client
+
+```ts
+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?)`
+
+```ts
+await client.track('report_generated', {
+  actorType: 'ai_agent',
+  agentId: 'agent_123',
+  taskId: 'task_456',
+  properties: { reportType: 'weekly_summary' },
+});
+```
+
+### `trackBatch(events)`
+
+```ts
+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`):
+
+```ts
+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`):
+
+```ts
+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`](../../docs/help/server-side-collection.md).

package/dist/index.d.ts

@@ -0,0 +1,31 @@
+import type { NodeSdkConfig, TrackOptions, RequestContext, TrackRequestOptions } from './types.js';
+export type { NodeSdkConfig, TrackOptions, RequestContext, TrackRequestOptions } from './types.js';
+export { analyticKitExpress, analyticKitFastify, analyticKitFetch, extractContext, shouldCollect, DEFAULT_IGNORE, detectAgentProtocol, } from './middleware.js';
+export type { MiddlewareOptions, NodeLikeRequest } from './middleware.js';
+export declare class AnalyticKit {
+    private readonly apiKey;
+    private readonly endpoint;
+    private readonly actorType;
+    private readonly maxRetries;
+    private readonly timeout;
+    constructor(config: NodeSdkConfig);
+    track(eventName: string, options?: Partial<Omit<TrackOptions, 'eventName'>>): Promise<void>;
+    /**
+     * Record a single inbound HTTP request observed by a server-side collector.
+     *
+     * The ingest side reads `request_context` in preference to the transport
+     * headers on our own call, because those describe THIS process, not the end
+     * user. `page_path` is mirrored to the top level so the event also lights up
+     * the existing funnel UI without a server round-trip.
+     */
+    trackRequest(context: RequestContext, options?: TrackRequestOptions): Promise<void>;
+    trackBatch(events: TrackOptions[]): Promise<{
+        accepted: number;
+        rejected: number;
+    }>;
+    shutdown(): Promise<void>;
+    private _sendWithRetry;
+    private _sleep;
+}
+export default AnalyticKit;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAGnG,YAAY,EAAE,aAAa,EAAE,YAAY,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AACnG,OAAO,EACL,kBAAkB,EAClB,kBAAkB,EAClB,gBAAgB,EAChB,cAAc,EACd,aAAa,EACb,cAAc,EACd,mBAAmB,GACpB,MAAM,iBAAiB,CAAC;AACzB,YAAY,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAE1E,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;gBAErB,MAAM,EAAE,aAAa;IAW3B,KAAK,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC,YAAY,EAAE,WAAW,CAAC,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IA0BjG;;;;;;;OAOG;IACG,YAAY,CAChB,OAAO,EAAE,cAAc,EACvB,OAAO,CAAC,EAAE,mBAAmB,GAC5B,OAAO,CAAC,IAAI,CAAC;IAyCV,UAAU,CACd,MAAM,EAAE,YAAY,EAAE,GACrB,OAAO,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;IA+B5C,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;YAIjB,cAAc;IA0C5B,OAAO,CAAC,MAAM;CAGf;AAED,eAAe,WAAW,CAAC"}

package/dist/index.js

@@ -0,0 +1,157 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AnalyticKit = exports.detectAgentProtocol = exports.DEFAULT_IGNORE = exports.shouldCollect = exports.extractContext = exports.analyticKitFetch = exports.analyticKitFastify = exports.analyticKitExpress = void 0;
+const node_crypto_1 = require("node:crypto");
+const types_js_1 = require("./types.js");
+var middleware_js_1 = require("./middleware.js");
+Object.defineProperty(exports, "analyticKitExpress", { enumerable: true, get: function () { return middleware_js_1.analyticKitExpress; } });
+Object.defineProperty(exports, "analyticKitFastify", { enumerable: true, get: function () { return middleware_js_1.analyticKitFastify; } });
+Object.defineProperty(exports, "analyticKitFetch", { enumerable: true, get: function () { return middleware_js_1.analyticKitFetch; } });
+Object.defineProperty(exports, "extractContext", { enumerable: true, get: function () { return middleware_js_1.extractContext; } });
+Object.defineProperty(exports, "shouldCollect", { enumerable: true, get: function () { return middleware_js_1.shouldCollect; } });
+Object.defineProperty(exports, "DEFAULT_IGNORE", { enumerable: true, get: function () { return middleware_js_1.DEFAULT_IGNORE; } });
+Object.defineProperty(exports, "detectAgentProtocol", { enumerable: true, get: function () { return middleware_js_1.detectAgentProtocol; } });
+class AnalyticKit {
+    apiKey;
+    endpoint;
+    actorType;
+    maxRetries;
+    timeout;
+    constructor(config) {
+        if (!config.apiKey) {
+            throw new Error('AnalyticKit: apiKey is required');
+        }
+        this.apiKey = config.apiKey;
+        this.endpoint = config.endpoint.replace(/\/$/, '');
+        this.actorType = config.actorType ?? types_js_1.NODE_CONFIG_DEFAULTS.actorType;
+        this.maxRetries = config.maxRetries ?? types_js_1.NODE_CONFIG_DEFAULTS.maxRetries;
+        this.timeout = config.timeout ?? types_js_1.NODE_CONFIG_DEFAULTS.timeout;
+    }
+    async track(eventName, options) {
+        // Minted here, BEFORE _sendWithRetry — the whole point is that all
+        // retries of this event carry the same key, so ingest derives one
+        // event_id and the duplicate is absorbed. _sendWithRetry re-sends the
+        // identical body string, so the key is stable by construction
+        // (2026-07-04 critique, Arch #6: a 5xx retry used to create a second row).
+        const payload = {
+            idempotency_key: options?.idempotencyKey ?? (0, node_crypto_1.randomUUID)(),
+            event_name: eventName,
+            timestamp: Date.now(),
+            actor_type: options?.actorType ?? this.actorType,
+            properties: options?.properties,
+            agent_id: options?.agentId,
+            task_id: options?.taskId,
+            workflow_id: options?.workflowId,
+            wallet_address: options?.walletAddress,
+            chain: options?.chain,
+        };
+        await this._sendWithRetry(`${this.endpoint}/v1/events`, JSON.stringify(payload), this.maxRetries);
+    }
+    /**
+     * Record a single inbound HTTP request observed by a server-side collector.
+     *
+     * The ingest side reads `request_context` in preference to the transport
+     * headers on our own call, because those describe THIS process, not the end
+     * user. `page_path` is mirrored to the top level so the event also lights up
+     * the existing funnel UI without a server round-trip.
+     */
+    async trackRequest(context, options) {
+        const requestContext = {};
+        const map = [
+            ['userAgent', 'user_agent'],
+            ['ip', 'ip'],
+            ['path', 'path'],
+            ['referrer', 'referrer'],
+            ['host', 'host'],
+            ['method', 'method'],
+            ['status', 'status'],
+            ['protocol', 'protocol'],
+        ];
+        for (const [from, to] of map) {
+            const value = context[from];
+            // Omit absent fields entirely — sending explicit nulls would make the
+            // ingest-side "was this forwarded?" check ambiguous.
+            if (value !== undefined && value !== null && value !== '') {
+                requestContext[to] = value;
+            }
+        }
+        const payload = {
+            idempotency_key: options?.idempotencyKey ?? (0, node_crypto_1.randomUUID)(),
+            event_name: options?.eventName ?? 'page_view',
+            timestamp: Date.now(),
+            actor_type: options?.actorType ?? this.actorType,
+            properties: options?.properties,
+            visitor_id: options?.visitorId,
+            session_id: options?.sessionId,
+            page_path: context.path ?? undefined,
+            page_referrer: context.referrer ?? undefined,
+            request_context: requestContext,
+        };
+        await this._sendWithRetry(`${this.endpoint}/v1/events`, JSON.stringify(payload), this.maxRetries);
+    }
+    async trackBatch(events) {
+        const payloads = events.map((e) => ({
+            idempotency_key: e.idempotencyKey ?? (0, node_crypto_1.randomUUID)(),
+            event_name: e.eventName,
+            timestamp: Date.now(),
+            actor_type: e.actorType ?? this.actorType,
+            properties: e.properties,
+            agent_id: e.agentId,
+            task_id: e.taskId,
+            workflow_id: e.workflowId,
+            wallet_address: e.walletAddress,
+            chain: e.chain,
+        }));
+        const res = await this._sendWithRetry(`${this.endpoint}/v1/events/batch`, JSON.stringify(payloads), this.maxRetries);
+        if (res) {
+            const body = (await res.json());
+            return {
+                accepted: body.data?.accepted ?? events.length,
+                rejected: body.data?.rejected ?? 0,
+            };
+        }
+        return { accepted: events.length, rejected: 0 };
+    }
+    async shutdown() {
+        // No-op for now; future queue support would flush pending here
+    }
+    async _sendWithRetry(url, body, retriesLeft) {
+        const attempt = this.maxRetries - retriesLeft;
+        try {
+            const controller = new AbortController();
+            const timer = setTimeout(() => controller.abort(), this.timeout);
+            const res = await fetch(url, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    'Authorization': `Bearer ${this.apiKey}`,
+                },
+                body,
+                signal: controller.signal,
+            });
+            clearTimeout(timer);
+            if (res.status >= 500 && retriesLeft > 0) {
+                const backoff = 100 * Math.pow(2, attempt);
+                await this._sleep(backoff);
+                return this._sendWithRetry(url, body, retriesLeft - 1);
+            }
+            // 4xx: do NOT retry — return as-is
+            return res;
+        }
+        catch (err) {
+            // Network errors: retry if possible
+            if (retriesLeft > 0) {
+                const backoff = 100 * Math.pow(2, attempt);
+                await this._sleep(backoff);
+                return this._sendWithRetry(url, body, retriesLeft - 1);
+            }
+            return null;
+        }
+    }
+    _sleep(ms) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+}
+exports.AnalyticKit = AnalyticKit;
+exports.default = AnalyticKit;
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/middleware.d.ts

@@ -0,0 +1,79 @@
+import type { AnalyticKit } from './index.js';
+import type { RequestContext, TrackRequestOptions } from './types.js';
+/**
+ * Structural stand-ins for `http.IncomingMessage` and the Express/Fastify
+ * request objects that wrap it. Typed here rather than imported so this
+ * package keeps its zero-runtime-dependency guarantee.
+ */
+export interface NodeLikeRequest {
+    method?: string;
+    url?: string;
+    originalUrl?: string;
+    headers: Record<string, string | string[] | undefined>;
+    socket?: {
+        remoteAddress?: string;
+    };
+}
+export interface MiddlewareOptions {
+    client: AnalyticKit;
+    /** Event name for collected requests. Default 'page_view'. */
+    eventName?: string;
+    /**
+     * Paths matching any of these are not collected. REPLACES the defaults —
+     * pass `[...DEFAULT_IGNORE, /^\/admin/]` to extend them instead.
+     */
+    ignore?: RegExp[];
+    /** 0..1. Default 1 (collect everything). */
+    sampleRate?: number;
+    /** Read the client IP from X-Forwarded-For. Default true. */
+    trustProxy?: boolean;
+    /** Called instead of throwing when collection faults. Default: swallow. */
+    onError?: (err: unknown) => void;
+    /** Extra options forwarded to trackRequest (actorType, properties, ...). */
+    track?: Omit<TrackRequestOptions, 'eventName'>;
+}
+/**
+ * Requests a page-analytics product should not count. Static assets dominate
+ * request volume on any real site and would swamp both the customer's event
+ * quota and the AI-traffic signal this feature exists to surface.
+ */
+export declare const DEFAULT_IGNORE: RegExp[];
+/**
+ * Infer the agent protocol from request headers. `get` is a case-insensitive
+ * header lookup (`headerValue` for node-style requests, `Headers.get` for
+ * Fetch). Only the derived label is ever returned — header VALUES (session
+ * ids, payment payloads) never pass through this function's result.
+ *
+ * x402 wins when both signals are present: a paid MCP call is still a
+ * payment event.
+ */
+export declare function detectAgentProtocol(get: (name: string) => string | null | undefined): 'mcp' | 'x402' | null;
+/** True when this path should produce an event. */
+export declare function shouldCollect(path: string, options: Pick<MiddlewareOptions, 'ignore' | 'sampleRate'>): boolean;
+/** Pull the END USER's signals off a node-style request object. */
+export declare function extractContext(req: NodeLikeRequest, options?: Pick<MiddlewareOptions, 'trustProxy'>): RequestContext;
+/**
+ * Express / Connect middleware.
+ *
+ *   app.use(analyticKitExpress({ client }));
+ *
+ * `next()` is called synchronously before any I/O, so the collector adds no
+ * latency and cannot fail the request.
+ */
+export declare function analyticKitExpress(options: MiddlewareOptions): (req: NodeLikeRequest, res: unknown, next: () => void) => void;
+/**
+ * Fastify onRequest hook.
+ *
+ *   app.addHook('onRequest', analyticKitFastify({ client }));
+ */
+export declare function analyticKitFastify(options: MiddlewareOptions): (req: NodeLikeRequest, reply: unknown, done: () => void) => void;
+/**
+ * Fetch-API collector for Next.js middleware, Hono, and edge runtimes.
+ *
+ *   export function middleware(request: NextRequest) {
+ *     collect(request);
+ *     return NextResponse.next();
+ *   }
+ */
+export declare function analyticKitFetch(options: MiddlewareOptions): (request: Request) => void;
+//# sourceMappingURL=middleware.d.ts.map

package/dist/middleware.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"middleware.d.ts","sourceRoot":"","sources":["../src/middleware.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAC9C,OAAO,KAAK,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAEtE;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC,CAAC;IACvD,MAAM,CAAC,EAAE;QAAE,aAAa,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CACrC;AAED,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,WAAW,CAAC;IACpB,8DAA8D;IAC9D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,4CAA4C;IAC5C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,6DAA6D;IAC7D,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,2EAA2E;IAC3E,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,IAAI,CAAC;IACjC,4EAA4E;IAC5E,KAAK,CAAC,EAAE,IAAI,CAAC,mBAAmB,EAAE,WAAW,CAAC,CAAC;CAChD;AAED;;;;GAIG;AACH,eAAO,MAAM,cAAc,EAAE,MAAM,EAalC,CAAC;AAsBF;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CACjC,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,GAAG,SAAS,GAC/C,KAAK,GAAG,MAAM,GAAG,IAAI,CAIvB;AAED,mDAAmD;AACnD,wBAAgB,aAAa,CAC3B,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,IAAI,CAAC,iBAAiB,EAAE,QAAQ,GAAG,YAAY,CAAC,GACxD,OAAO,CAYT;AAED,mEAAmE;AACnE,wBAAgB,cAAc,CAC5B,GAAG,EAAE,eAAe,EACpB,OAAO,GAAE,IAAI,CAAC,iBAAiB,EAAE,YAAY,CAAM,GAClD,cAAc,CAuBhB;AA6CD;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,iBAAiB,GACzB,CAAC,GAAG,EAAE,eAAe,EAAE,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,IAAI,KAAK,IAAI,CAchE;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,iBAAiB,GACzB,CAAC,GAAG,EAAE,eAAe,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,IAAI,KAAK,IAAI,CAWlE;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,iBAAiB,GACzB,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,CA4B5B"}

package/dist/middleware.js

@@ -0,0 +1,223 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_IGNORE = void 0;
+exports.detectAgentProtocol = detectAgentProtocol;
+exports.shouldCollect = shouldCollect;
+exports.extractContext = extractContext;
+exports.analyticKitExpress = analyticKitExpress;
+exports.analyticKitFastify = analyticKitFastify;
+exports.analyticKitFetch = analyticKitFetch;
+/**
+ * Requests a page-analytics product should not count. Static assets dominate
+ * request volume on any real site and would swamp both the customer's event
+ * quota and the AI-traffic signal this feature exists to surface.
+ */
+exports.DEFAULT_IGNORE = [
+    // Static assets. Anchored with `$` and matched against the PATHNAME only
+    // (see shouldCollect) — an unanchored form applied to path+query would drop
+    // a real page like `/search?q=file.js`.
+    /\.(?:js|mjs|cjs|css|map|png|jpe?g|gif|svg|webp|avif|ico|woff2?|ttf|eot|txt|xml|json)$/i,
+    // Health checks. These MUST be anchored: a bare `/^\/health/` also swallows
+    // real content pages such as `/health-insurance-quotes` or `/healthcare`,
+    // and silently losing a customer's pageviews is close to impossible to
+    // notice from the outside.
+    /^\/healthz?(?:\/|$)/,
+    /^\/_next\//,
+    /^\/__nextjs/,
+    /^\/favicon\.ico$/,
+];
+function headerValue(headers, name) {
+    // Fast path: Node's own http parser (and Express/Fastify on top of it)
+    // already lowercases header names, which covers nearly every real request.
+    // Falls back to a case-insensitive scan for the rare proxy/framework that
+    // doesn't normalize, and for callers constructing headers by hand.
+    const direct = headers[name];
+    if (direct !== undefined)
+        return Array.isArray(direct) ? direct[0] : direct;
+    const lower = name.toLowerCase();
+    for (const key of Object.keys(headers)) {
+        if (key.toLowerCase() === lower) {
+            const raw = headers[key];
+            return Array.isArray(raw) ? raw[0] : raw;
+        }
+    }
+    return undefined;
+}
+/**
+ * Infer the agent protocol from request headers. `get` is a case-insensitive
+ * header lookup (`headerValue` for node-style requests, `Headers.get` for
+ * Fetch). Only the derived label is ever returned — header VALUES (session
+ * ids, payment payloads) never pass through this function's result.
+ *
+ * x402 wins when both signals are present: a paid MCP call is still a
+ * payment event.
+ */
+function detectAgentProtocol(get) {
+    if (get('payment-signature') || get('x-payment'))
+        return 'x402';
+    if (get('mcp-session-id') || get('mcp-protocol-version'))
+        return 'mcp';
+    return null;
+}
+/** True when this path should produce an event. */
+function shouldCollect(path, options) {
+    const ignore = options.ignore ?? exports.DEFAULT_IGNORE;
+    // Ignore patterns are matched against the pathname; the query string takes
+    // no part in the decision. Without this, `/search?q=file.js` reads as a
+    // JavaScript asset and the pageview is thrown away.
+    const pathname = path.split('?')[0] ?? path;
+    if (ignore.some((re) => re.test(pathname)))
+        return false;
+    const rate = options.sampleRate ?? 1;
+    if (rate >= 1)
+        return true;
+    if (rate <= 0)
+        return false;
+    return Math.random() < rate;
+}
+/** Pull the END USER's signals off a node-style request object. */
+function extractContext(req, options = {}) {
+    const headers = req.headers ?? {};
+    const trustProxy = options.trustProxy ?? true;
+    let ip = req.socket?.remoteAddress ?? null;
+    if (trustProxy) {
+        const xff = headerValue(headers, 'x-forwarded-for');
+        // "client, proxy1, proxy2" — the first hop is the client.
+        const first = xff?.split(',')[0]?.trim();
+        if (first)
+            ip = first;
+    }
+    return {
+        userAgent: headerValue(headers, 'user-agent') ?? null,
+        ip,
+        path: req.originalUrl ?? req.url ?? null,
+        // Note the historical misspelling: the HTTP header is `Referer`.
+        referrer: headerValue(headers, 'referer') ?? headerValue(headers, 'referrer') ?? null,
+        host: headerValue(headers, 'host') ?? null,
+        method: req.method ?? null,
+        status: null,
+        protocol: detectAgentProtocol((name) => headerValue(headers, name)),
+    };
+}
+/**
+ * Report a collection fault to the caller's handler, absorbing anything that
+ * handler itself throws.
+ *
+ * The customer's `onError` is arbitrary code we invoke from inside a promise
+ * rejection handler. If it throws there, the rejection is unhandled — and Node
+ * 15+ terminates the process on an unhandled rejection by default. That would
+ * turn "your analytics had a hiccup" into "your server died", which is the
+ * exact outcome this middleware exists to make impossible. There is nowhere
+ * left to report a failure of the failure reporter, so it is swallowed.
+ */
+function reportError(options, err) {
+    try {
+        options.onError?.(err);
+    }
+    catch {
+        // Deliberately empty — see above.
+    }
+}
+/**
+ * Build the context and hand it to the client, fire-and-forget.
+ *
+ * Takes a factory rather than a value so that a throw from `extractContext`
+ * lands inside this try block. Passing `extractContext(req)` as an argument
+ * would evaluate it BEFORE the try, leaving that throw to escape into the
+ * host app after next()/done() had already run.
+ */
+function dispatch(buildContext, options) {
+    try {
+        const result = options.client.trackRequest(buildContext(), {
+            ...options.track,
+            eventName: options.eventName ?? 'page_view',
+        });
+        // Fire-and-forget: an ingest outage must not surface in the host app.
+        void Promise.resolve(result).catch((err) => reportError(options, err));
+    }
+    catch (err) {
+        reportError(options, err);
+    }
+}
+/**
+ * Express / Connect middleware.
+ *
+ *   app.use(analyticKitExpress({ client }));
+ *
+ * `next()` is called synchronously before any I/O, so the collector adds no
+ * latency and cannot fail the request.
+ */
+function analyticKitExpress(options) {
+    return (req, _res, next) => {
+        next();
+        // Everything after next() is wrapped: the contract this middleware sells
+        // is that installing it cannot break the host app, and that has to hold
+        // for a malformed request object or a pathological ignore pattern too.
+        try {
+            const path = req.originalUrl ?? req.url ?? '/';
+            if (!shouldCollect(path, options))
+                return;
+            dispatch(() => extractContext(req, options), options);
+        }
+        catch (err) {
+            reportError(options, err);
+        }
+    };
+}
+/**
+ * Fastify onRequest hook.
+ *
+ *   app.addHook('onRequest', analyticKitFastify({ client }));
+ */
+function analyticKitFastify(options) {
+    return (req, _reply, done) => {
+        done();
+        try {
+            const path = req.originalUrl ?? req.url ?? '/';
+            if (!shouldCollect(path, options))
+                return;
+            dispatch(() => extractContext(req, options), options);
+        }
+        catch (err) {
+            reportError(options, err);
+        }
+    };
+}
+/**
+ * Fetch-API collector for Next.js middleware, Hono, and edge runtimes.
+ *
+ *   export function middleware(request: NextRequest) {
+ *     collect(request);
+ *     return NextResponse.next();
+ *   }
+ */
+function analyticKitFetch(options) {
+    return (request) => {
+        // Same containment guarantee as the node adapters: a malformed URL or a
+        // hostile header must not propagate into the caller's request handler.
+        try {
+            const url = new URL(request.url);
+            const path = url.pathname + url.search;
+            if (!shouldCollect(path, options))
+                return;
+            const trustProxy = options.trustProxy ?? true;
+            dispatch(() => {
+                const xff = request.headers.get('x-forwarded-for');
+                return {
+                    userAgent: request.headers.get('user-agent'),
+                    ip: trustProxy ? (xff?.split(',')[0]?.trim() ?? null) : null,
+                    path,
+                    referrer: request.headers.get('referer') ?? request.headers.get('referrer'),
+                    host: request.headers.get('host') ?? url.host,
+                    method: request.method,
+                    status: null,
+                    protocol: detectAgentProtocol((name) => request.headers.get(name)),
+                };
+            }, options);
+        }
+        catch (err) {
+            reportError(options, err);
+        }
+    };
+}
+//# sourceMappingURL=middleware.js.map

package/dist/middleware.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"middleware.js","sourceRoot":"","sources":["../src/middleware.ts"],"names":[],"mappings":";;;AAoFA,kDAMC;AAGD,sCAeC;AAGD,wCA0BC;AAqDD,gDAgBC;AAOD,gDAaC;AAUD,4CA8BC;AAvOD;;;;GAIG;AACU,QAAA,cAAc,GAAa;IACtC,yEAAyE;IACzE,4EAA4E;IAC5E,wCAAwC;IACxC,wFAAwF;IACxF,4EAA4E;IAC5E,0EAA0E;IAC1E,uEAAuE;IACvE,2BAA2B;IAC3B,qBAAqB;IACrB,YAAY;IACZ,aAAa;IACb,kBAAkB;CACnB,CAAC;AAEF,SAAS,WAAW,CAClB,OAAmC,EACnC,IAAY;IAEZ,uEAAuE;IACvE,2EAA2E;IAC3E,0EAA0E;IAC1E,mEAAmE;IACnE,MAAM,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7B,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;IAC5E,MAAM,KAAK,GAAG,IAAI,CAAC,WAAW,EAAE,CAAC;IACjC,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;QACvC,IAAI,GAAG,CAAC,WAAW,EAAE,KAAK,KAAK,EAAE,CAAC;YAChC,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;YACzB,OAAO,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC;QAC3C,CAAC;IACH,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;;;;;;GAQG;AACH,SAAgB,mBAAmB,CACjC,GAAgD;IAEhD,IAAI,GAAG,CAAC,mBAAmB,CAAC,IAAI,GAAG,CAAC,WAAW,CAAC;QAAE,OAAO,MAAM,CAAC;IAChE,IAAI,GAAG,CAAC,gBAAgB,CAAC,IAAI,GAAG,CAAC,sBAAsB,CAAC;QAAE,OAAO,KAAK,CAAC;IACvE,OAAO,IAAI,CAAC;AACd,CAAC;AAED,mDAAmD;AACnD,SAAgB,aAAa,CAC3B,IAAY,EACZ,OAAyD;IAEzD,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,sBAAc,CAAC;IAChD,2EAA2E;IAC3E,wEAAwE;IACxE,oDAAoD;IACpD,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC;IAC5C,IAAI,MAAM,CAAC,IAAI,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QAAE,OAAO,KAAK,CAAC;IAEzD,MAAM,IAAI,GAAG,OAAO,CAAC,UAAU,IAAI,CAAC,CAAC;IACrC,IAAI,IAAI,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IAC3B,IAAI,IAAI,IAAI,CAAC;QAAE,OAAO,KAAK,CAAC;IAC5B,OAAO,IAAI,CAAC,MAAM,EAAE,GAAG,IAAI,CAAC;AAC9B,CAAC;AAED,mEAAmE;AACnE,SAAgB,cAAc,CAC5B,GAAoB,EACpB,UAAiD,EAAE;IAEnD,MAAM,OAAO,GAAG,GAAG,CAAC,OAAO,IAAI,EAAE,CAAC;IAClC,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,IAAI,IAAI,CAAC;IAE9C,IAAI,EAAE,GAAkB,GAAG,CAAC,MAAM,EAAE,aAAa,IAAI,IAAI,CAAC;IAC1D,IAAI,UAAU,EAAE,CAAC;QACf,MAAM,GAAG,GAAG,WAAW,CAAC,OAAO,EAAE,iBAAiB,CAAC,CAAC;QACpD,0DAA0D;QAC1D,MAAM,KAAK,GAAG,GAAG,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC;QACzC,IAAI,KAAK;YAAE,EAAE,GAAG,KAAK,CAAC;IACxB,CAAC;IAED,OAAO;QACL,SAAS,EAAE,WAAW,CAAC,OAAO,EAAE,YAAY,CAAC,IAAI,IAAI;QACrD,EAAE;QACF,IAAI,EAAE,GAAG,CAAC,WAAW,IAAI,GAAG,CAAC,GAAG,IAAI,IAAI;QACxC,iEAAiE;QACjE,QAAQ,EAAE,WAAW,CAAC,OAAO,EAAE,SAAS,CAAC,IAAI,WAAW,CAAC,OAAO,EAAE,UAAU,CAAC,IAAI,IAAI;QACrF,IAAI,EAAE,WAAW,CAAC,OAAO,EAAE,MAAM,CAAC,IAAI,IAAI;QAC1C,MAAM,EAAE,GAAG,CAAC,MAAM,IAAI,IAAI;QAC1B,MAAM,EAAE,IAAI;QACZ,QAAQ,EAAE,mBAAmB,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,WAAW,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;KACpE,CAAC;AACJ,CAAC;AAED;;;;;;;;;;GAUG;AACH,SAAS,WAAW,CAAC,OAA0B,EAAE,GAAY;IAC3D,IAAI,CAAC;QACH,OAAO,CAAC,OAAO,EAAE,CAAC,GAAG,CAAC,CAAC;IACzB,CAAC;IAAC,MAAM,CAAC;QACP,kCAAkC;IACpC,CAAC;AACH,CAAC;AAED;;;;;;;GAOG;AACH,SAAS,QAAQ,CACf,YAAkC,EAClC,OAA0B;IAE1B,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,YAAY,CAAC,YAAY,EAAE,EAAE;YACzD,GAAG,OAAO,CAAC,KAAK;YAChB,SAAS,EAAE,OAAO,CAAC,SAAS,IAAI,WAAW;SAC5C,CAAC,CAAC;QACH,sEAAsE;QACtE,KAAK,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,KAAK,CAAC,CAAC,GAAY,EAAE,EAAE,CAAC,WAAW,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC,CAAC;IAClF,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,WAAW,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;IAC5B,CAAC;AACH,CAAC;AAED;;;;;;;GAOG;AACH,SAAgB,kBAAkB,CAChC,OAA0B;IAE1B,OAAO,CAAC,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE;QACzB,IAAI,EAAE,CAAC;QACP,yEAAyE;QACzE,wEAAwE;QACxE,uEAAuE;QACvE,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,GAAG,CAAC,WAAW,IAAI,GAAG,CAAC,GAAG,IAAI,GAAG,CAAC;YAC/C,IAAI,CAAC,aAAa,CAAC,IAAI,EAAE,OAAO,CAAC;gBAAE,OAAO;YAC1C,QAAQ,CAAC,GAAG,EAAE,CAAC,cAAc,CAAC,GAAG,EAAE,OAAO,CAAC,EAAE,OAAO,CAAC,CAAC;QACxD,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,WAAW,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;QAC5B,CAAC;IACH,CAAC,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,SAAgB,kBAAkB,CAChC,OAA0B;IAE1B,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,EAAE;QAC3B,IAAI,EAAE,CAAC;QACP,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,GAAG,CAAC,WAAW,IAAI,GAAG,CAAC,GAAG,IAAI,GAAG,CAAC;YAC/C,IAAI,CAAC,aAAa,CAAC,IAAI,EAAE,OAAO,CAAC;gBAAE,OAAO;YAC1C,QAAQ,CAAC,GAAG,EAAE,CAAC,cAAc,CAAC,GAAG,EAAE,OAAO,CAAC,EAAE,OAAO,CAAC,CAAC;QACxD,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,WAAW,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;QAC5B,CAAC;IACH,CAAC,CAAC;AACJ,CAAC;AAED;;;;;;;GAOG;AACH,SAAgB,gBAAgB,CAC9B,OAA0B;IAE1B,OAAO,CAAC,OAAO,EAAE,EAAE;QACjB,wEAAwE;QACxE,uEAAuE;QACvE,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;YACjC,MAAM,IAAI,GAAG,GAAG,CAAC,QAAQ,GAAG,GAAG,CAAC,MAAM,CAAC;YACvC,IAAI,CAAC,aAAa,CAAC,IAAI,EAAE,OAAO,CAAC;gBAAE,OAAO;YAE1C,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,IAAI,IAAI,CAAC;YAE9C,QAAQ,CAAC,GAAG,EAAE;gBACZ,MAAM,GAAG,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAC;gBACnD,OAAO;oBACL,SAAS,EAAE,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC;oBAC5C,EAAE,EAAE,UAAU,CAAC,CAAC,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI;oBAC5D,IAAI;oBACJ,QAAQ,EAAE,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC;oBAC3E,IAAI,EAAE,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,GAAG,CAAC,IAAI;oBAC7C,MAAM,EAAE,OAAO,CAAC,MAAM;oBACtB,MAAM,EAAE,IAAI;oBACZ,QAAQ,EAAE,mBAAmB,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;iBACnE,CAAC;YACJ,CAAC,EAAE,OAAO,CAAC,CAAC;QACd,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,WAAW,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;QAC5B,CAAC;IACH,CAAC,CAAC;AACJ,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,60 @@
+export interface NodeSdkConfig {
+    apiKey: string;
+    endpoint: string;
+    actorType?: string;
+    maxRetries?: number;
+    timeout?: number;
+}
+export declare const NODE_CONFIG_DEFAULTS: {
+    readonly actorType: "human";
+    readonly maxRetries: 2;
+    readonly timeout: 5000;
+};
+export interface TrackOptions {
+    eventName: string;
+    /**
+     * Optional caller-supplied idempotency key. Defaults to a fresh UUID per
+     * event, which makes the SDK's own 5xx retries exactly-once. Supply your
+     * own (e.g. an order id) when the CALLER may also retry — that is the only
+     * way the server can tell a re-send from a genuinely new event.
+     */
+    idempotencyKey?: string;
+    properties?: Record<string, unknown>;
+    actorType?: string;
+    agentId?: string;
+    taskId?: string;
+    workflowId?: string;
+    walletAddress?: string;
+    chain?: string;
+}
+/**
+ * The original request's signals, as observed by a server-side collector.
+ * Every field is optional: a collector behind a proxy that strips headers,
+ * or a client with `capture_ip` off, still produces useful rows.
+ */
+export interface RequestContext {
+    userAgent?: string | null;
+    ip?: string | null;
+    path?: string | null;
+    referrer?: string | null;
+    host?: string | null;
+    method?: string | null;
+    status?: number | null;
+    /**
+     * Agent protocol inferred from request headers (`mcp` | `x402` | null).
+     * See `detectAgentProtocol` in `middleware.ts`. Header VALUES (session ids,
+     * payment payloads) are never captured — only this derived label.
+     */
+    protocol?: string | null;
+}
+export interface TrackRequestOptions {
+    /** Defaults to 'page_view' so server-collected traffic lands in the same
+     *  Web2 enrichment path as the browser SDK. */
+    eventName?: string;
+    properties?: Record<string, unknown>;
+    actorType?: string;
+    idempotencyKey?: string;
+    visitorId?: string;
+    sessionId?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,eAAO,MAAM,oBAAoB;;;;CAIvB,CAAC;AAEX,MAAM,WAAW,YAAY;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB;;;;;OAKG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED,MAAM,WAAW,mBAAmB;IAClC;mDAC+C;IAC/C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB"}

package/dist/types.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NODE_CONFIG_DEFAULTS = void 0;
+exports.NODE_CONFIG_DEFAULTS = {
+    actorType: 'human',
+    maxRetries: 2,
+    timeout: 5000,
+};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":";;;AAQa,QAAA,oBAAoB,GAAG;IAClC,SAAS,EAAE,OAAO;IAClB,UAAU,EAAE,CAAC;IACb,OAAO,EAAE,IAAI;CACL,CAAC"}

package/package.json

@@ -1,6 +1,39 @@
 {
   "name": "@analytickit/sdk-node",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Server-side event tracking + request middleware for the AgentGraph / AnalyticKit API. Captures AI crawlers and agents (GPTBot, ClaudeBot, MCP, x402, ...) that never run browser JS.",
+  "license": "MIT",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./middleware": {
+      "types": "./dist/middleware.d.ts",
+      "default": "./dist/middleware.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "test": "npx tsx --test test/*.test.ts"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.4.0"
+  },
+  "homepage": "https://analytickit.com"
+}