@agentstats/sdk 0.0.0-stage → 0.4.1

package/dist/index.d.cts

@@ -0,0 +1,269 @@
+//#region src/web.d.ts
+/**
+ * Visitors: privacy-friendly web analytics for people. One small request per pageview or custom
+ * event, no cookies, nothing stored in the browser. The server counts unique visitors from a
+ * daily-salted hash of the IP and user agent, the way Plausible does, and keeps neither.
+ *
+ * Used by the full SDK (on by default, `trackPageviews: false` turns it off) and on its own by
+ * the lite script (`/sdk/lite.js`) for sites without WebMCP tools.
+ */
+type EventProps = Record<string, string | number | boolean>;
+//#endregion
+//#region src/index.d.ts
+export declare const SDK_VERSION = "0.4.1";
+export type ToolStatus = 'success' | 'error' | 'cancelled';
+export interface ToolAnnotations {
+  readOnlyHint?: boolean;
+  untrustedContentHint?: boolean;
+  consequentialHint?: boolean;
+  [key: string]: unknown;
+}
+export interface ToolExecuteOptions {
+  signal?: AbortSignal;
+  [key: string]: unknown;
+}
+/** Mirrors the WebMCP `ModelContextTool` dictionary. */
+export interface ModelContextTool {
+  name: string;
+  title?: string;
+  description?: string;
+  inputSchema?: unknown;
+  annotations?: ToolAnnotations;
+  execute: (input: unknown, options?: ToolExecuteOptions) => unknown | Promise<unknown>;
+  [key: string]: unknown;
+}
+export interface ToolDescriptor {
+  name: string;
+  title?: string;
+  description?: string;
+  inputSchema?: unknown;
+  annotations?: ToolAnnotations;
+  origin?: string;
+}
+export type ArgsCapture = boolean | ((tool: string, args: unknown) => unknown);
+/** `true`, `false`, or a function returning what to keep (`undefined` keeps nothing). Stringified and cut at 2,000 chars. */
+export type ResultCapture = boolean | ((tool: string, result: unknown) => unknown);
+/** A failed tool call, as passed to a `captureErrors` function. */
+export interface ErrorInfo {
+  tool: string;
+  /** `error.message`, or the thrown value as a string. */
+  message: string;
+  /** `error.name`, e.g. `TypeError`. */
+  name: string | null;
+  /** `error.code` when the thrown value has one. */
+  code: string | number | null;
+  /** What was thrown. */
+  error: unknown;
+}
+/**
+ * What to keep of an error's message: `true` (default), `false` (the call still counts as
+ * failed and keeps the error name), or a function returning the text to keep, or null for none.
+ */
+export type ErrorCapture = boolean | ((error: ErrorInfo) => string | null | undefined);
+export interface AgentStatsOptions {
+  /** Public site key from your dashboard, e.g. `al_pub_…`. */
+  key: string;
+  /** Ingest endpoint. Defaults to the origin the SDK script was loaded from, or the built-in cloud endpoint. */
+  endpoint?: string;
+  /** Capture tool arguments. `true` (default, sent as-is apart from `redactKeys`), `false`, or a custom sanitizer. */
+  captureArgs?: ArgsCapture;
+  /** Capture tool results (stringified, cut at 2,000 chars). `false` (default), `true`, or a function. */
+  captureResults?: ResultCapture;
+  /** Capture error messages of failed calls. `true` (default), `false`, or a function. */
+  captureErrors?: ErrorCapture;
+  /** Keys whose values are replaced with `[redacted]` in args and `track()` props (case-insensitive substring match). Empty by default. */
+  redactKeys?: string[];
+  /** Static properties attached to every event. */
+  metadata?: Record<string, unknown>;
+  /** Idle time before a new agent session is started. Default 30 minutes. */
+  sessionTimeoutMs?: number;
+  /** How often queued events are sent. Default 2000ms. */
+  flushIntervalMs?: number;
+  /** Max events per request. Default 25. */
+  maxBatchSize?: number;
+  /** Automatically patch `document.modelContext`. Default `true`. */
+  autoInstrument?: boolean;
+  /**
+   * Record AI agents browsing ordinary pages in a real browser (Claude in Chrome taking control,
+   * Claude's built-in browser, automation like Playwright, agents the server middleware verified).
+   * Only agents are recorded, page by page; nothing about people. Default `true`.
+   */
+  trackAgentBrowsers?: boolean;
+  /**
+   * Record pageviews and `track()` events for Visitors, privacy-friendly analytics for people:
+   * no cookies, nothing stored in the browser, no IP address kept. Ignored on localhost unless
+   * `allowLocalhost` is set. Default `true`.
+   */
+  trackPageviews?: boolean;
+  /** Count the part after `#/` as the page, for hash-based routers. Default `false`. */
+  hashRouting?: boolean;
+  /** Record clicks on links to other sites as `Outbound Link: Click`. Default `false`. */
+  outboundLinks?: boolean;
+  /** Record clicks on file links as `File Download`: `true` for the usual types, or your own extensions. Default `false`. */
+  fileDownloads?: boolean | string[];
+  /** Record pageviews on localhost too. Default `false`. */
+  allowLocalhost?: boolean;
+  /** Log to console. */
+  debug?: boolean;
+  /** Do nothing (useful in dev/test). */
+  disabled?: boolean;
+  /** Custom fetch implementation (tests / non-browser runtimes). */
+  fetch?: typeof fetch;
+}
+export interface ToolCallEvent {
+  type: 'tool_call';
+  id: string;
+  ts: number;
+  tool: string;
+  status: ToolStatus;
+  duration_ms: number;
+  args?: unknown;
+  result?: string;
+  error?: string;
+  error_name?: string;
+  url?: string;
+}
+export interface ToolRegisteredEvent {
+  type: 'tool_registered' | 'tool_unregistered';
+  id: string;
+  ts: number;
+  tool: string;
+  descriptor?: ToolDescriptor;
+  url?: string;
+}
+export interface ToolsSnapshotEvent {
+  type: 'tools_snapshot';
+  id: string;
+  ts: number;
+  tools: ToolDescriptor[];
+  url?: string;
+}
+export interface CustomEvent {
+  type: 'custom';
+  id: string;
+  ts: number;
+  name: string;
+  props?: Record<string, unknown>;
+  url?: string;
+}
+/** Landing page reached from an AI assistant (ChatGPT, Perplexity, …). Sent once per session; the server classifies it. */
+export interface ReferralEvent {
+  type: 'referral';
+  id: string;
+  ts: number;
+  url: string;
+  referrer: string | null;
+}
+/**
+ * An AI agent on an ordinary page, browsing in a real browser: a page it loaded
+ * (`agent_pageview`), or when it took and gave back control (`agent_control`, Claude in Chrome).
+ */
+export interface AgentBrowserEvent {
+  type: 'agent_pageview' | 'agent_control';
+  id: string;
+  ts: number;
+  /** Which agent: claude-in-chrome, claude-browser, automation, or verified-visit (the server names it from the visit cookie). */
+  name: string;
+  props: {
+    via: 'dom' | 'user-agent' | 'webdriver' | 'visit';
+    phase?: 'start' | 'stop';
+    duration_ms?: number;
+  };
+  url?: string;
+}
+export type AgentStatsEvent = ToolCallEvent | ToolRegisteredEvent | ToolsSnapshotEvent | CustomEvent | ReferralEvent | AgentBrowserEvent;
+export interface IngestPayload {
+  key: string;
+  sdk: string;
+  session_id: string;
+  sent_at: number;
+  metadata?: Record<string, unknown>;
+  /** Visit id from the `_al_v` cookie the server integration sets on responses to AI agents. */
+  visit?: string;
+  /** Client signals used to attribute the session to an agent when there is no visit cookie. */
+  client?: {
+    ua?: string;
+    webdriver?: boolean;
+  };
+  events: AgentStatsEvent[];
+}
+export declare class AgentStatsClient {
+  readonly options: Required<Pick<AgentStatsOptions, 'key' | 'endpoint' | 'captureArgs' | 'captureResults' | 'captureErrors' | 'redactKeys' | 'sessionTimeoutMs' | 'flushIntervalMs' | 'maxBatchSize' | 'autoInstrument' | 'trackAgentBrowsers' | 'debug' | 'disabled'>> & AgentStatsOptions;
+  private queue;
+  private timer;
+  private snapshotTimer;
+  private pollTimer;
+  private sessionId;
+  private lastActivity;
+  private lastSnapshotHash;
+  private _fetch;
+  private inflight;
+  private web;
+  constructor(opts: AgentStatsOptions);
+  /** Wrap a WebMCP tool definition so its `execute` is tracked. Safe to call on already-wrapped tools. */
+  wrap<T extends ModelContextTool>(tool: T): T;
+  /**
+   * Track a custom event (e.g. a conversion). It counts for the agent session it happens in, and
+   * as a goal in Visitors when a person does it (string, number and boolean props only there).
+   */
+  track(name: string, props?: Record<string, unknown>): void;
+  /** Record a pageview now, e.g. after a client-side navigation the SDK can't see. Pageviews are otherwise automatic. */
+  pageview(): void;
+  /** Take a snapshot of the currently registered tools now (also happens automatically). */
+  snapshot(): Promise<ToolDescriptor[]>;
+  /** Send everything queued right now. */
+  flush(useBeacon?: boolean): Promise<void>;
+  /** Remove patches and stop timers. */
+  destroy(): void;
+  get session(): string;
+  private log;
+  private url;
+  private redactKeys;
+  private modelContext;
+  private captureArgs;
+  private captureResult;
+  private captureError;
+  /** Runs a user-supplied capture function. One that throws keeps nothing rather than breaking the tool call. */
+  private callOption;
+  private recordCall;
+  private enqueue;
+  private scheduleSnapshot;
+  private instrument;
+  private patch;
+  private bindLifecycle;
+  /** User agent + webdriver flag, so a session can be attributed to an agent that browses with a real browser. */
+  private clientHints;
+  /** The agent browsing this page, if one is: in control right now (Claude in Chrome), or the browser itself is one. */
+  detectAgentBrowser(): {
+    name: string;
+    via: AgentBrowserEvent['props']['via'];
+  } | null;
+  private agentPage;
+  private controlStarted;
+  /** Record agent page views (on load and on client-side navigation) and Claude in Chrome taking and giving back control. */
+  private watchAgentBrowsers;
+  /** If this page was reached from an AI assistant, tell the server once per session. */
+  private reportReferral;
+  private loadSession;
+  private touchSession;
+}
+/** Initialise AgentStats. Call once, as early as possible (before registering tools). */
+export declare function init(options: AgentStatsOptions): AgentStatsClient;
+export declare function getClient(): AgentStatsClient | null;
+export declare function track(name: string, props?: Record<string, unknown>): void;
+export declare function wrap<T extends ModelContextTool>(tool: T): T;
+export declare function flush(): Promise<void>;
+export declare function snapshot(): Promise<ToolDescriptor[]>;
+export declare function pageview(): void;
+export declare const AgentStats: {
+  init: typeof init;
+  track: typeof track;
+  pageview: typeof pageview;
+  wrap: typeof wrap;
+  flush: typeof flush;
+  snapshot: typeof snapshot;
+  getClient: typeof getClient;
+  version: string;
+};
+//#endregion
+export { AgentStats as default, type EventProps };

package/dist/index.d.ts

@@ -0,0 +1,269 @@
+//#region src/web.d.ts
+/**
+ * Visitors: privacy-friendly web analytics for people. One small request per pageview or custom
+ * event, no cookies, nothing stored in the browser. The server counts unique visitors from a
+ * daily-salted hash of the IP and user agent, the way Plausible does, and keeps neither.
+ *
+ * Used by the full SDK (on by default, `trackPageviews: false` turns it off) and on its own by
+ * the lite script (`/sdk/lite.js`) for sites without WebMCP tools.
+ */
+type EventProps = Record<string, string | number | boolean>;
+//#endregion
+//#region src/index.d.ts
+export declare const SDK_VERSION = "0.4.1";
+export type ToolStatus = 'success' | 'error' | 'cancelled';
+export interface ToolAnnotations {
+  readOnlyHint?: boolean;
+  untrustedContentHint?: boolean;
+  consequentialHint?: boolean;
+  [key: string]: unknown;
+}
+export interface ToolExecuteOptions {
+  signal?: AbortSignal;
+  [key: string]: unknown;
+}
+/** Mirrors the WebMCP `ModelContextTool` dictionary. */
+export interface ModelContextTool {
+  name: string;
+  title?: string;
+  description?: string;
+  inputSchema?: unknown;
+  annotations?: ToolAnnotations;
+  execute: (input: unknown, options?: ToolExecuteOptions) => unknown | Promise<unknown>;
+  [key: string]: unknown;
+}
+export interface ToolDescriptor {
+  name: string;
+  title?: string;
+  description?: string;
+  inputSchema?: unknown;
+  annotations?: ToolAnnotations;
+  origin?: string;
+}
+export type ArgsCapture = boolean | ((tool: string, args: unknown) => unknown);
+/** `true`, `false`, or a function returning what to keep (`undefined` keeps nothing). Stringified and cut at 2,000 chars. */
+export type ResultCapture = boolean | ((tool: string, result: unknown) => unknown);
+/** A failed tool call, as passed to a `captureErrors` function. */
+export interface ErrorInfo {
+  tool: string;
+  /** `error.message`, or the thrown value as a string. */
+  message: string;
+  /** `error.name`, e.g. `TypeError`. */
+  name: string | null;
+  /** `error.code` when the thrown value has one. */
+  code: string | number | null;
+  /** What was thrown. */
+  error: unknown;
+}
+/**
+ * What to keep of an error's message: `true` (default), `false` (the call still counts as
+ * failed and keeps the error name), or a function returning the text to keep, or null for none.
+ */
+export type ErrorCapture = boolean | ((error: ErrorInfo) => string | null | undefined);
+export interface AgentStatsOptions {
+  /** Public site key from your dashboard, e.g. `al_pub_…`. */
+  key: string;
+  /** Ingest endpoint. Defaults to the origin the SDK script was loaded from, or the built-in cloud endpoint. */
+  endpoint?: string;
+  /** Capture tool arguments. `true` (default, sent as-is apart from `redactKeys`), `false`, or a custom sanitizer. */
+  captureArgs?: ArgsCapture;
+  /** Capture tool results (stringified, cut at 2,000 chars). `false` (default), `true`, or a function. */
+  captureResults?: ResultCapture;
+  /** Capture error messages of failed calls. `true` (default), `false`, or a function. */
+  captureErrors?: ErrorCapture;
+  /** Keys whose values are replaced with `[redacted]` in args and `track()` props (case-insensitive substring match). Empty by default. */
+  redactKeys?: string[];
+  /** Static properties attached to every event. */
+  metadata?: Record<string, unknown>;
+  /** Idle time before a new agent session is started. Default 30 minutes. */
+  sessionTimeoutMs?: number;
+  /** How often queued events are sent. Default 2000ms. */
+  flushIntervalMs?: number;
+  /** Max events per request. Default 25. */
+  maxBatchSize?: number;
+  /** Automatically patch `document.modelContext`. Default `true`. */
+  autoInstrument?: boolean;
+  /**
+   * Record AI agents browsing ordinary pages in a real browser (Claude in Chrome taking control,
+   * Claude's built-in browser, automation like Playwright, agents the server middleware verified).
+   * Only agents are recorded, page by page; nothing about people. Default `true`.
+   */
+  trackAgentBrowsers?: boolean;
+  /**
+   * Record pageviews and `track()` events for Visitors, privacy-friendly analytics for people:
+   * no cookies, nothing stored in the browser, no IP address kept. Ignored on localhost unless
+   * `allowLocalhost` is set. Default `true`.
+   */
+  trackPageviews?: boolean;
+  /** Count the part after `#/` as the page, for hash-based routers. Default `false`. */
+  hashRouting?: boolean;
+  /** Record clicks on links to other sites as `Outbound Link: Click`. Default `false`. */
+  outboundLinks?: boolean;
+  /** Record clicks on file links as `File Download`: `true` for the usual types, or your own extensions. Default `false`. */
+  fileDownloads?: boolean | string[];
+  /** Record pageviews on localhost too. Default `false`. */
+  allowLocalhost?: boolean;
+  /** Log to console. */
+  debug?: boolean;
+  /** Do nothing (useful in dev/test). */
+  disabled?: boolean;
+  /** Custom fetch implementation (tests / non-browser runtimes). */
+  fetch?: typeof fetch;
+}
+export interface ToolCallEvent {
+  type: 'tool_call';
+  id: string;
+  ts: number;
+  tool: string;
+  status: ToolStatus;
+  duration_ms: number;
+  args?: unknown;
+  result?: string;
+  error?: string;
+  error_name?: string;
+  url?: string;
+}
+export interface ToolRegisteredEvent {
+  type: 'tool_registered' | 'tool_unregistered';
+  id: string;
+  ts: number;
+  tool: string;
+  descriptor?: ToolDescriptor;
+  url?: string;
+}
+export interface ToolsSnapshotEvent {
+  type: 'tools_snapshot';
+  id: string;
+  ts: number;
+  tools: ToolDescriptor[];
+  url?: string;
+}
+export interface CustomEvent {
+  type: 'custom';
+  id: string;
+  ts: number;
+  name: string;
+  props?: Record<string, unknown>;
+  url?: string;
+}
+/** Landing page reached from an AI assistant (ChatGPT, Perplexity, …). Sent once per session; the server classifies it. */
+export interface ReferralEvent {
+  type: 'referral';
+  id: string;
+  ts: number;
+  url: string;
+  referrer: string | null;
+}
+/**
+ * An AI agent on an ordinary page, browsing in a real browser: a page it loaded
+ * (`agent_pageview`), or when it took and gave back control (`agent_control`, Claude in Chrome).
+ */
+export interface AgentBrowserEvent {
+  type: 'agent_pageview' | 'agent_control';
+  id: string;
+  ts: number;
+  /** Which agent: claude-in-chrome, claude-browser, automation, or verified-visit (the server names it from the visit cookie). */
+  name: string;
+  props: {
+    via: 'dom' | 'user-agent' | 'webdriver' | 'visit';
+    phase?: 'start' | 'stop';
+    duration_ms?: number;
+  };
+  url?: string;
+}
+export type AgentStatsEvent = ToolCallEvent | ToolRegisteredEvent | ToolsSnapshotEvent | CustomEvent | ReferralEvent | AgentBrowserEvent;
+export interface IngestPayload {
+  key: string;
+  sdk: string;
+  session_id: string;
+  sent_at: number;
+  metadata?: Record<string, unknown>;
+  /** Visit id from the `_al_v` cookie the server integration sets on responses to AI agents. */
+  visit?: string;
+  /** Client signals used to attribute the session to an agent when there is no visit cookie. */
+  client?: {
+    ua?: string;
+    webdriver?: boolean;
+  };
+  events: AgentStatsEvent[];
+}
+export declare class AgentStatsClient {
+  readonly options: Required<Pick<AgentStatsOptions, 'key' | 'endpoint' | 'captureArgs' | 'captureResults' | 'captureErrors' | 'redactKeys' | 'sessionTimeoutMs' | 'flushIntervalMs' | 'maxBatchSize' | 'autoInstrument' | 'trackAgentBrowsers' | 'debug' | 'disabled'>> & AgentStatsOptions;
+  private queue;
+  private timer;
+  private snapshotTimer;
+  private pollTimer;
+  private sessionId;
+  private lastActivity;
+  private lastSnapshotHash;
+  private _fetch;
+  private inflight;
+  private web;
+  constructor(opts: AgentStatsOptions);
+  /** Wrap a WebMCP tool definition so its `execute` is tracked. Safe to call on already-wrapped tools. */
+  wrap<T extends ModelContextTool>(tool: T): T;
+  /**
+   * Track a custom event (e.g. a conversion). It counts for the agent session it happens in, and
+   * as a goal in Visitors when a person does it (string, number and boolean props only there).
+   */
+  track(name: string, props?: Record<string, unknown>): void;
+  /** Record a pageview now, e.g. after a client-side navigation the SDK can't see. Pageviews are otherwise automatic. */
+  pageview(): void;
+  /** Take a snapshot of the currently registered tools now (also happens automatically). */
+  snapshot(): Promise<ToolDescriptor[]>;
+  /** Send everything queued right now. */
+  flush(useBeacon?: boolean): Promise<void>;
+  /** Remove patches and stop timers. */
+  destroy(): void;
+  get session(): string;
+  private log;
+  private url;
+  private redactKeys;
+  private modelContext;
+  private captureArgs;
+  private captureResult;
+  private captureError;
+  /** Runs a user-supplied capture function. One that throws keeps nothing rather than breaking the tool call. */
+  private callOption;
+  private recordCall;
+  private enqueue;
+  private scheduleSnapshot;
+  private instrument;
+  private patch;
+  private bindLifecycle;
+  /** User agent + webdriver flag, so a session can be attributed to an agent that browses with a real browser. */
+  private clientHints;
+  /** The agent browsing this page, if one is: in control right now (Claude in Chrome), or the browser itself is one. */
+  detectAgentBrowser(): {
+    name: string;
+    via: AgentBrowserEvent['props']['via'];
+  } | null;
+  private agentPage;
+  private controlStarted;
+  /** Record agent page views (on load and on client-side navigation) and Claude in Chrome taking and giving back control. */
+  private watchAgentBrowsers;
+  /** If this page was reached from an AI assistant, tell the server once per session. */
+  private reportReferral;
+  private loadSession;
+  private touchSession;
+}
+/** Initialise AgentStats. Call once, as early as possible (before registering tools). */
+export declare function init(options: AgentStatsOptions): AgentStatsClient;
+export declare function getClient(): AgentStatsClient | null;
+export declare function track(name: string, props?: Record<string, unknown>): void;
+export declare function wrap<T extends ModelContextTool>(tool: T): T;
+export declare function flush(): Promise<void>;
+export declare function snapshot(): Promise<ToolDescriptor[]>;
+export declare function pageview(): void;
+export declare const AgentStats: {
+  init: typeof init;
+  track: typeof track;
+  pageview: typeof pageview;
+  wrap: typeof wrap;
+  flush: typeof flush;
+  snapshot: typeof snapshot;
+  getClient: typeof getClient;
+  version: string;
+};
+//#endregion
+export { AgentStats as default, type EventProps };