@amplitude/ai 0.1.0

package/dist/session.d.ts

@@ -0,0 +1,46 @@
+import { SessionEnrichments } from "./core/enrichments.js";
+import { AiMessageOpts, BoundAgent, EmbeddingOpts, ScoreOpts, SpanOpts, ToolCallOpts, UserMessageOpts } from "./bound-agent.js";
+
+//#region src/session.d.ts
+
+declare class Session {
+  readonly sessionId: string;
+  traceId: string | null;
+  readonly idleTimeoutMinutes: number | null;
+  readonly userId: string | null;
+  readonly deviceId: string | null;
+  readonly browserSessionId: string | null;
+  private _agent;
+  private _enrichments;
+  private _sessionReplayId;
+  constructor(agent: BoundAgent, opts?: {
+    sessionId?: string | null;
+    idleTimeoutMinutes?: number | null;
+    userId?: string | null;
+    deviceId?: string | null;
+    browserSessionId?: string | null;
+  });
+  private _buildSessionContext;
+  newTrace(): string;
+  setEnrichments(enrichments: SessionEnrichments): void;
+  /**
+   * Run a callback within this session context.
+   * This is the Node.js equivalent of Python's `with session as s:` block.
+   */
+  run<T>(fn: (session: Session) => T | Promise<T>): Promise<T>;
+  /**
+   * Synchronous version of run() for non-async code.
+   */
+  runSync<T>(fn: (session: Session) => T): T;
+  private _autoEnd;
+  private _inject;
+  trackUserMessage(content: string, opts?: UserMessageOpts): string;
+  trackAiMessage(content: string, model: string, provider: string, latencyMs: number, opts?: AiMessageOpts): string;
+  trackToolCall(toolName: string, latencyMs: number, success: boolean, opts?: ToolCallOpts): string;
+  trackEmbedding(model: string, provider: string, latencyMs: number, opts?: EmbeddingOpts): string;
+  trackSpan(spanName: string, latencyMs: number, opts?: SpanOpts): string;
+  score(name: string, value: number, targetId: string, opts?: ScoreOpts): void;
+}
+//#endregion
+export { Session };
+//# sourceMappingURL=session.d.ts.map

package/dist/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","names":[],"sources":["../src/session.ts"],"sourcesContent":[],"mappings":";;;;;AAkLU,cA9IG,OAAA,CA8IH;EAeA,SAAA,SAAA,EAAA,MAAA;EAcA,OAAA,EAAA,MAAA,GAAA,IAAA;EAU6C,SAAA,kBAAA,EAAA,MAAA,GAAA,IAAA;EAQ7C,SAAA,MAAA,EAAA,MAAA,GAAA,IAAA;EAAc,SAAA,QAAA,EAAA,MAAA,GAAA,IAAA;;;;;qBAjLb;;;;;;;;;8BAyDmB;;;;;uBAQD,YAAY,IAAI,QAAQ,KAAK,QAAQ;;;;2BAavC,YAAY,IAAI;;;2CA2CD;6FAShC;8EAeA;4EAcA;wDAU6C;8DAQ7C"}

package/dist/session.js

@@ -0,0 +1,144 @@
+import { getLogger } from "./utils/logger.js";
+import { PROP_SESSION_REPLAY_ID } from "./core/constants.js";
+import { SessionContext, _sessionStorage, getActiveContext } from "./context.js";
+import { randomUUID } from "node:crypto";
+
+//#region src/session.ts
+/**
+* Session context manager using Node.js AsyncLocalStorage.
+*
+* Use `.run()` to execute code within session context. The session
+* auto-ends when the callback completes, emitting `[Agent] Session End`.
+*
+* @example
+* ```typescript
+* const session = agent.session();
+* await session.run(async (s) => {
+*   s.trackUserMessage('What is retention?');
+*   s.trackAiMessage('Retention is...', 'gpt-4', 'openai', 200);
+* });
+* ```
+*/
+var Session = class {
+	sessionId;
+	traceId = null;
+	idleTimeoutMinutes;
+	userId;
+	deviceId;
+	browserSessionId;
+	_agent;
+	_enrichments = null;
+	_sessionReplayId;
+	constructor(agent, opts = {}) {
+		this.sessionId = opts.sessionId ?? randomUUID();
+		this.idleTimeoutMinutes = opts.idleTimeoutMinutes ?? null;
+		this.userId = opts.userId ?? null;
+		this.deviceId = opts.deviceId ?? agent._defaults.deviceId;
+		this.browserSessionId = opts.browserSessionId ?? agent._defaults.browserSessionId;
+		this._agent = agent;
+		this._sessionReplayId = this.deviceId && this.browserSessionId ? `${this.deviceId}/${this.browserSessionId}` : null;
+	}
+	_buildSessionContext() {
+		const defaults = this._agent._defaults;
+		const ai = this._agent._ai;
+		const sid = this.sessionId;
+		return new SessionContext({
+			sessionId: sid,
+			traceId: this.traceId,
+			userId: this.userId ?? defaults.userId,
+			agentId: defaults.agentId,
+			parentAgentId: defaults.parentAgentId,
+			env: defaults.env,
+			customerOrgId: defaults.customerOrgId,
+			agentVersion: defaults.agentVersion,
+			context: defaults.context,
+			groups: defaults.groups,
+			idleTimeoutMinutes: this.idleTimeoutMinutes,
+			deviceId: this.deviceId ?? defaults.deviceId,
+			browserSessionId: this.browserSessionId ?? defaults.browserSessionId,
+			nextTurnIdFn: () => ai._nextTurnId(sid)
+		});
+	}
+	newTrace() {
+		this.traceId = randomUUID();
+		const ctx = getActiveContext();
+		if (ctx != null) ctx.traceId = this.traceId;
+		return this.traceId;
+	}
+	setEnrichments(enrichments) {
+		this._enrichments = enrichments;
+	}
+	/**
+	* Run a callback within this session context.
+	* This is the Node.js equivalent of Python's `with session as s:` block.
+	*/
+	async run(fn) {
+		const ctx = this._buildSessionContext();
+		try {
+			return await _sessionStorage.run(ctx, () => fn(this));
+		} finally {
+			this._autoEnd();
+		}
+	}
+	/**
+	* Synchronous version of run() for non-async code.
+	*/
+	runSync(fn) {
+		const ctx = this._buildSessionContext();
+		try {
+			return _sessionStorage.run(ctx, () => fn(this));
+		} finally {
+			this._autoEnd();
+		}
+	}
+	_autoEnd() {
+		try {
+			const endOpts = {
+				sessionId: this.sessionId,
+				enrichments: this._enrichments,
+				idleTimeoutMinutes: this.idleTimeoutMinutes
+			};
+			if (this.userId != null) endOpts.userId = this.userId;
+			this._agent.trackSessionEnd(this._inject(endOpts));
+		} catch (e) {
+			getLogger().debug(`Failed to auto-end session ${this.sessionId}: ${e}`);
+		}
+	}
+	_inject(kwargs) {
+		const merged = { ...kwargs };
+		if (merged.sessionId == null) merged.sessionId = this.sessionId;
+		if (this.traceId != null && merged.traceId == null) merged.traceId = this.traceId;
+		if (this.userId != null && merged.userId == null) merged.userId = this.userId;
+		if (this._sessionReplayId != null) {
+			const existingEp = merged.eventProperties;
+			const ep = existingEp != null ? { ...existingEp } : {};
+			if (!(PROP_SESSION_REPLAY_ID in ep)) {
+				ep[PROP_SESSION_REPLAY_ID] = this._sessionReplayId;
+				merged.eventProperties = ep;
+			}
+		}
+		return merged;
+	}
+	trackUserMessage(content, opts = {}) {
+		return this._agent.trackUserMessage(content, this._inject(opts));
+	}
+	trackAiMessage(content, model, provider, latencyMs, opts = {}) {
+		return this._agent.trackAiMessage(content, model, provider, latencyMs, this._inject(opts));
+	}
+	trackToolCall(toolName, latencyMs, success, opts = {}) {
+		return this._agent.trackToolCall(toolName, latencyMs, success, this._inject(opts));
+	}
+	trackEmbedding(model, provider, latencyMs, opts = {}) {
+		return this._agent.trackEmbedding(model, provider, latencyMs, this._inject(opts));
+	}
+	trackSpan(spanName, latencyMs, opts = {}) {
+		return this._agent.trackSpan(spanName, latencyMs, this._inject(opts));
+	}
+	score(name, value, targetId, opts = {}) {
+		this._agent.score(name, value, targetId, this._inject(opts));
+	}
+};
+
+//#endregion
+export { Session };
+//# sourceMappingURL=session.js.map

package/dist/session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.js","names":["endOpts: SessionEndOpts"],"sources":["../src/session.ts"],"sourcesContent":["/**\n * Session context manager using Node.js AsyncLocalStorage.\n *\n * Use `.run()` to execute code within session context. The session\n * auto-ends when the callback completes, emitting `[Agent] Session End`.\n *\n * @example\n * ```typescript\n * const session = agent.session();\n * await session.run(async (s) => {\n *   s.trackUserMessage('What is retention?');\n *   s.trackAiMessage('Retention is...', 'gpt-4', 'openai', 200);\n * });\n * ```\n */\n\nimport { randomUUID } from 'node:crypto';\nimport type {\n  AiMessageOpts,\n  BoundAgent,\n  EmbeddingOpts,\n  ScoreOpts,\n  SessionEndOpts,\n  SpanOpts,\n  ToolCallOpts,\n  UserMessageOpts,\n} from './bound-agent.js';\nimport {\n  _sessionStorage,\n  getActiveContext,\n  SessionContext,\n} from './context.js';\nimport type { SessionEnrichments } from './core/enrichments.js';\nimport { PROP_SESSION_REPLAY_ID } from './core/tracking.js';\nimport { getLogger } from './utils/logger.js';\n\nexport class Session {\n  readonly sessionId: string;\n  traceId: string | null = null;\n  readonly idleTimeoutMinutes: number | null;\n  readonly userId: string | null;\n  readonly deviceId: string | null;\n  readonly browserSessionId: string | null;\n  private _agent: BoundAgent;\n  private _enrichments: SessionEnrichments | null = null;\n  private _sessionReplayId: string | null;\n\n  constructor(\n    agent: BoundAgent,\n    opts: {\n      sessionId?: string | null;\n      idleTimeoutMinutes?: number | null;\n      userId?: string | null;\n      deviceId?: string | null;\n      browserSessionId?: string | null;\n    } = {},\n  ) {\n    this.sessionId = opts.sessionId ?? randomUUID();\n    this.idleTimeoutMinutes = opts.idleTimeoutMinutes ?? null;\n    this.userId = opts.userId ?? null;\n    this.deviceId =\n      opts.deviceId ?? (agent._defaults.deviceId as string | null);\n    this.browserSessionId =\n      opts.browserSessionId ??\n      (agent._defaults.browserSessionId as string | null);\n    this._agent = agent;\n    this._sessionReplayId =\n      this.deviceId && this.browserSessionId\n        ? `${this.deviceId}/${this.browserSessionId}`\n        : null;\n  }\n\n  private _buildSessionContext(): SessionContext {\n    const defaults = this._agent._defaults;\n    const ai = this._agent._ai;\n    const sid = this.sessionId;\n\n    return new SessionContext({\n      sessionId: sid,\n      traceId: this.traceId,\n      userId: (this.userId ?? defaults.userId) as string | null,\n      agentId: defaults.agentId as string | null,\n      parentAgentId: defaults.parentAgentId as string | null,\n      env: defaults.env as string | null,\n      customerOrgId: defaults.customerOrgId as string | null,\n      agentVersion: defaults.agentVersion as string | null,\n      context: defaults.context as Record<string, unknown> | null,\n      groups: defaults.groups as Record<string, unknown> | null,\n      idleTimeoutMinutes: this.idleTimeoutMinutes,\n      deviceId: this.deviceId ?? (defaults.deviceId as string | null),\n      browserSessionId:\n        this.browserSessionId ?? (defaults.browserSessionId as string | null),\n      nextTurnIdFn: () => ai._nextTurnId(sid),\n    });\n  }\n\n  newTrace(): string {\n    this.traceId = randomUUID();\n    const ctx = getActiveContext();\n    if (ctx != null) {\n      ctx.traceId = this.traceId;\n    }\n    return this.traceId;\n  }\n\n  setEnrichments(enrichments: SessionEnrichments): void {\n    this._enrichments = enrichments;\n  }\n\n  /**\n   * Run a callback within this session context.\n   * This is the Node.js equivalent of Python's `with session as s:` block.\n   */\n  async run<T>(fn: (session: Session) => T | Promise<T>): Promise<T> {\n    const ctx = this._buildSessionContext();\n    try {\n      const result = await _sessionStorage.run(ctx, () => fn(this));\n      return result;\n    } finally {\n      this._autoEnd();\n    }\n  }\n\n  /**\n   * Synchronous version of run() for non-async code.\n   */\n  runSync<T>(fn: (session: Session) => T): T {\n    const ctx = this._buildSessionContext();\n    try {\n      return _sessionStorage.run(ctx, () => fn(this));\n    } finally {\n      this._autoEnd();\n    }\n  }\n\n  private _autoEnd(): void {\n    try {\n      const endOpts: SessionEndOpts = {\n        sessionId: this.sessionId,\n        enrichments: this._enrichments,\n        idleTimeoutMinutes: this.idleTimeoutMinutes,\n      };\n      if (this.userId != null) endOpts.userId = this.userId;\n      this._agent.trackSessionEnd(this._inject(endOpts));\n    } catch (e) {\n      getLogger().debug(`Failed to auto-end session ${this.sessionId}: ${e}`);\n    }\n  }\n\n  private _inject<T extends Record<string, unknown>>(kwargs: T): T {\n    const merged = { ...kwargs } as Record<string, unknown>;\n    if (merged.sessionId == null) merged.sessionId = this.sessionId;\n    if (this.traceId != null && merged.traceId == null)\n      merged.traceId = this.traceId;\n    if (this.userId != null && merged.userId == null)\n      merged.userId = this.userId;\n    if (this._sessionReplayId != null) {\n      const existingEp = merged.eventProperties as\n        | Record<string, unknown>\n        | undefined;\n      const ep = existingEp != null ? { ...existingEp } : {};\n      if (!(PROP_SESSION_REPLAY_ID in ep)) {\n        ep[PROP_SESSION_REPLAY_ID] = this._sessionReplayId;\n        merged.eventProperties = ep;\n      }\n    }\n    return merged as T;\n  }\n\n  trackUserMessage(content: string, opts: UserMessageOpts = {}): string {\n    return this._agent.trackUserMessage(content, this._inject(opts));\n  }\n\n  trackAiMessage(\n    content: string,\n    model: string,\n    provider: string,\n    latencyMs: number,\n    opts: AiMessageOpts = {},\n  ): string {\n    return this._agent.trackAiMessage(\n      content,\n      model,\n      provider,\n      latencyMs,\n      this._inject(opts),\n    );\n  }\n\n  trackToolCall(\n    toolName: string,\n    latencyMs: number,\n    success: boolean,\n    opts: ToolCallOpts = {},\n  ): string {\n    return this._agent.trackToolCall(\n      toolName,\n      latencyMs,\n      success,\n      this._inject(opts),\n    );\n  }\n\n  trackEmbedding(\n    model: string,\n    provider: string,\n    latencyMs: number,\n    opts: EmbeddingOpts = {},\n  ): string {\n    return this._agent.trackEmbedding(\n      model,\n      provider,\n      latencyMs,\n      this._inject(opts),\n    );\n  }\n\n  trackSpan(spanName: string, latencyMs: number, opts: SpanOpts = {}): string {\n    return this._agent.trackSpan(spanName, latencyMs, this._inject(opts));\n  }\n\n  score(\n    name: string,\n    value: number,\n    targetId: string,\n    opts: ScoreOpts = {},\n  ): void {\n    this._agent.score(name, value, targetId, this._inject(opts));\n  }\n}\n"],"mappings":"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"}

package/dist/tenant.d.ts

@@ -0,0 +1,30 @@
+import { AmplitudeAI } from "./client.js";
+import { BoundAgent } from "./bound-agent.js";
+
+//#region src/tenant.d.ts
+
+declare class TenantHandle {
+  private _ai;
+  private _customerOrgId;
+  private _groups;
+  private _env;
+  constructor(ai: AmplitudeAI, opts: {
+    customerOrgId: string;
+    groups?: Record<string, unknown> | null;
+    env?: string | null;
+  });
+  agent(agentId: string, opts?: {
+    userId?: string | null;
+    parentAgentId?: string | null;
+    customerOrgId?: string | null;
+    agentVersion?: string | null;
+    context?: Record<string, unknown> | null;
+    env?: string | null;
+    sessionId?: string | null;
+    traceId?: string | null;
+    groups?: Record<string, unknown> | null;
+  }): BoundAgent;
+}
+//#endregion
+export { TenantHandle };
+//# sourceMappingURL=tenant.d.ts.map

package/dist/tenant.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tenant.d.ts","names":[],"sources":["../src/tenant.ts"],"sourcesContent":[],"mappings":";;;;;cAaa,YAAA;;;;;kBAOL;;aAGO;;;;;;;;cAiBC;;;;aAID;MAEV"}

package/dist/tenant.js

@@ -0,0 +1,23 @@
+//#region src/tenant.ts
+var TenantHandle = class {
+	_ai;
+	_customerOrgId;
+	_groups;
+	_env;
+	constructor(ai, opts) {
+		this._ai = ai;
+		this._customerOrgId = opts.customerOrgId;
+		this._groups = opts.groups ?? null;
+		this._env = opts.env ?? null;
+	}
+	agent(agentId, opts = {}) {
+		if (!("customerOrgId" in opts)) opts.customerOrgId = this._customerOrgId;
+		if (this._groups != null && !("groups" in opts)) opts.groups = this._groups;
+		if (this._env != null && !("env" in opts)) opts.env = this._env;
+		return this._ai.agent(agentId, opts);
+	}
+};
+
+//#endregion
+export { TenantHandle };
+//# sourceMappingURL=tenant.js.map

package/dist/tenant.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tenant.js","names":[],"sources":["../src/tenant.ts"],"sourcesContent":["/**\n * TenantHandle — multi-tenant helper that pre-binds a customerOrgId to agents.\n *\n * @example\n * ```typescript\n * const tenant = ai.tenant('org-123');\n * const agent = tenant.agent('support-bot');\n * ```\n */\n\nimport type { BoundAgent } from './bound-agent.js';\nimport type { AmplitudeAI } from './client.js';\n\nexport class TenantHandle {\n  private _ai: AmplitudeAI;\n  private _customerOrgId: string;\n  private _groups: Record<string, unknown> | null;\n  private _env: string | null;\n\n  constructor(\n    ai: AmplitudeAI,\n    opts: {\n      customerOrgId: string;\n      groups?: Record<string, unknown> | null;\n      env?: string | null;\n    },\n  ) {\n    this._ai = ai;\n    this._customerOrgId = opts.customerOrgId;\n    this._groups = opts.groups ?? null;\n    this._env = opts.env ?? null;\n  }\n\n  agent(\n    agentId: string,\n    opts: {\n      userId?: string | null;\n      parentAgentId?: string | null;\n      customerOrgId?: string | null;\n      agentVersion?: string | null;\n      context?: Record<string, unknown> | null;\n      env?: string | null;\n      sessionId?: string | null;\n      traceId?: string | null;\n      groups?: Record<string, unknown> | null;\n    } = {},\n  ): BoundAgent {\n    if (!('customerOrgId' in opts)) opts.customerOrgId = this._customerOrgId;\n    if (this._groups != null && !('groups' in opts)) opts.groups = this._groups;\n    if (this._env != null && !('env' in opts)) opts.env = this._env;\n    return this._ai.agent(agentId, opts);\n  }\n}\n"],"mappings":";AAaA,IAAa,eAAb,MAA0B;CACxB,AAAQ;CACR,AAAQ;CACR,AAAQ;CACR,AAAQ;CAER,YACE,IACA,MAKA;AACA,OAAK,MAAM;AACX,OAAK,iBAAiB,KAAK;AAC3B,OAAK,UAAU,KAAK,UAAU;AAC9B,OAAK,OAAO,KAAK,OAAO;;CAG1B,MACE,SACA,OAUI,EAAE,EACM;AACZ,MAAI,EAAE,mBAAmB,MAAO,MAAK,gBAAgB,KAAK;AAC1D,MAAI,KAAK,WAAW,QAAQ,EAAE,YAAY,MAAO,MAAK,SAAS,KAAK;AACpE,MAAI,KAAK,QAAQ,QAAQ,EAAE,SAAS,MAAO,MAAK,MAAM,KAAK;AAC3D,SAAO,KAAK,IAAI,MAAM,SAAS,KAAK"}

package/dist/testing.d.ts

@@ -0,0 +1,46 @@
+import { AIConfig } from "./config.js";
+import { AmplitudeAI } from "./client.js";
+
+//#region src/testing.d.ts
+interface MockEvent {
+  event_type?: string;
+  user_id?: string;
+  event_properties?: Record<string, unknown>;
+  user_properties?: Record<string, unknown>;
+  groups?: Record<string, unknown>;
+}
+declare class MockAmplitudeAI extends AmplitudeAI {
+  events: MockEvent[];
+  private _simulatedError;
+  private _simulatedLatencyMs;
+  constructor(config?: AIConfig);
+  getEvents(eventType?: string): MockEvent[];
+  assertEventTracked(eventType: string, options?: {
+    userId?: string;
+    [key: string]: unknown;
+  }): MockEvent;
+  /**
+   * Configure the mock to throw an error on the next tracking call.
+   * Useful for testing error-handling paths in your application.
+   *
+   * @param type - Error type (e.g., 'rate_limit', 'network', 'auth')
+   * @param message - Optional custom error message
+   */
+  simulateError(type: string, message?: string): void;
+  /**
+   * Configure a simulated latency (in ms) added to each tracking call.
+   * Combined with async tests, this helps verify timeout and retry logic.
+   */
+  simulateLatency(ms: number): void;
+  /**
+   * Clear any simulated error or latency, restoring normal capture behavior.
+   */
+  clearSimulations(): void;
+  reset(): void;
+  eventsForSession(sessionId: string): MockEvent[];
+  eventsForAgent(agentId: string): MockEvent[];
+  assertSessionClosed(sessionId: string): MockEvent;
+}
+//#endregion
+export { MockAmplitudeAI };
+//# sourceMappingURL=testing.d.ts.map

package/dist/testing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"testing.d.ts","names":[],"sources":["../src/testing.ts"],"sourcesContent":[],"mappings":";;;;UAQU,SAAA;;EAAA,OAAA,CAAA,EAAA,MAAS;EAGE,gBAAA,CAAA,EAAA,MAAA,CAAA,MAAA,EAAA,OAAA,CAAA;EACD,eAAA,CAAA,EAAA,MAAA,CAAA,MAAA,EAAA,OAAA,CAAA;EACT,MAAA,CAAA,EAAA,MAAA,CAAA,MAAA,EAAA,OAAA,CAAA;;AAqBE,cAAA,eAAA,SAAwB,WAAA,CAAR;EACnB,MAAA,EAAA,SAAA,EAAA;EAIa,QAAA,eAAA;EA8BU,QAAA,mBAAA;EAQ5B,WAAA,CAAA,MAAA,CAAA,EAtCkB,QAsClB;EA0GkC,SAAA,CAAA,SAAA,CAAA,EAAA,MAAA,CAAA,EAlHN,SAkHM,EAAA;EAMJ,kBAAA,CAAA,SAAA,EAAA,MAAA,EAAA,OA3Ja,CA2Jb,EAAA;IAMO,MAAA,CAAA,EAAA,MAAA;IAjKL,CAAA,GAAA,EAAA,MAAA,CAAA,EAAA,OAAA;EAAW,CAAA,CAAA,EA2C3C,SA3C2C;;;;;;;;;;;;;;;;;;;uCAqJT;mCAMJ;0CAMO"}

package/dist/testing.js

@@ -0,0 +1,120 @@
+import { EVENT_SESSION_END, PROP_AGENT_ID, PROP_SESSION_ID } from "./core/constants.js";
+import { AmplitudeAI } from "./client.js";
+
+//#region src/testing.ts
+var MockAmplitudeAI = class extends AmplitudeAI {
+	events = [];
+	_simulatedError = null;
+	_simulatedLatencyMs = 0;
+	constructor(config) {
+		const mockAmplitude = {
+			track: () => {},
+			flush: () => [],
+			shutdown: () => {},
+			init: () => mockAmplitude
+		};
+		super({
+			amplitude: mockAmplitude,
+			config
+		});
+		this._amplitude.track = (event) => {
+			this.events.push(event);
+		};
+		if (this._config.debug || this._config.dryRun || this._config.onEventCallback != null) this._installTrackHook?.();
+	}
+	getEvents(eventType) {
+		if (eventType == null) return [...this.events];
+		return this.events.filter((e) => e.event_type === eventType);
+	}
+	assertEventTracked(eventType, options = {}) {
+		const { userId, ...expectedProps } = options;
+		const candidates = this.getEvents(eventType);
+		if (!candidates.length) {
+			const trackedTypes = new Set(this.events.map((e) => e.event_type));
+			throw new Error(`No '${eventType}' event tracked. Tracked types: ${[...trackedTypes].join(", ") || "(none)"}`);
+		}
+		for (const event of candidates) {
+			if (userId != null && event.user_id !== userId) continue;
+			if (Object.keys(expectedProps).length > 0) {
+				const props = event.event_properties ?? {};
+				if (Object.entries(expectedProps).every(([k, v]) => props[k] === v)) return event;
+			} else return event;
+		}
+		const filters = [];
+		if (userId != null) filters.push(`userId=${userId}`);
+		for (const [k, v] of Object.entries(expectedProps)) filters.push(`${k}=${String(v)}`);
+		throw new Error(`Found ${candidates.length} '${eventType}' event(s) but none matched filters: ${filters.join(", ")}`);
+	}
+	/**
+	* Configure the mock to throw an error on the next tracking call.
+	* Useful for testing error-handling paths in your application.
+	*
+	* @param type - Error type (e.g., 'rate_limit', 'network', 'auth')
+	* @param message - Optional custom error message
+	*/
+	simulateError(type, message) {
+		this._simulatedError = {
+			type,
+			message: message ?? `Simulated ${type} error`
+		};
+		this._amplitude.track = () => {
+			const err = this._simulatedError;
+			if (err) throw new Error(`[MockAmplitudeAI] ${err.type}: ${err.message}`);
+		};
+	}
+	/**
+	* Configure a simulated latency (in ms) added to each tracking call.
+	* Combined with async tests, this helps verify timeout and retry logic.
+	*/
+	simulateLatency(ms) {
+		this._simulatedLatencyMs = ms;
+		const originalCapture = (event) => {
+			this.events.push(event);
+		};
+		this._amplitude.track = (event) => {
+			if (this._simulatedLatencyMs > 0) {
+				const start = Date.now();
+				while (Date.now() - start < this._simulatedLatencyMs);
+			}
+			originalCapture(event);
+		};
+	}
+	/**
+	* Clear any simulated error or latency, restoring normal capture behavior.
+	*/
+	clearSimulations() {
+		this._simulatedError = null;
+		this._simulatedLatencyMs = 0;
+		this._amplitude.track = (event) => {
+			this.events.push(event);
+		};
+	}
+	reset() {
+		this.events = [];
+		this._simulatedError = null;
+		this._simulatedLatencyMs = 0;
+		this._amplitude.track = (event) => {
+			this.events.push(event);
+		};
+		if (this._config.debug || this._config.dryRun || this._config.onEventCallback != null) this._installTrackHook?.();
+		this._sessionTurnCounters.clear();
+	}
+	eventsForSession(sessionId) {
+		return this.events.filter((e) => e.event_properties?.[PROP_SESSION_ID] === sessionId);
+	}
+	eventsForAgent(agentId) {
+		return this.events.filter((e) => e.event_properties?.[PROP_AGENT_ID] === agentId);
+	}
+	assertSessionClosed(sessionId) {
+		const candidates = this.events.filter((e) => e.event_type === EVENT_SESSION_END && e.event_properties?.[PROP_SESSION_ID] === sessionId);
+		if (!candidates.length) {
+			const ended = this.events.filter((e) => e.event_type === EVENT_SESSION_END).map((e) => e.event_properties?.[PROP_SESSION_ID]);
+			throw new Error(`No '${EVENT_SESSION_END}' event for session '${sessionId}'. Ended sessions: ${ended.length ? ended.join(", ") : "(none)"}`);
+		}
+		return candidates[0];
+	}
+};
+
+//#endregion
+export { MockAmplitudeAI };
+//# sourceMappingURL=testing.js.map

package/dist/testing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"testing.js","names":[],"sources":["../src/testing.ts"],"sourcesContent":["import { AmplitudeAI } from './client.js';\nimport type { AIConfig } from './config.js';\nimport {\n  EVENT_SESSION_END,\n  PROP_AGENT_ID,\n  PROP_SESSION_ID,\n} from './core/constants.js';\n\ninterface MockEvent {\n  event_type?: string;\n  user_id?: string;\n  event_properties?: Record<string, unknown>;\n  user_properties?: Record<string, unknown>;\n  groups?: Record<string, unknown>;\n}\n\n/**\n * Test double for AmplitudeAI that captures events in-memory.\n *\n * Use in unit tests to assert tracked events without sending data.\n *\n * @example\n * ```typescript\n * const mock = new MockAmplitudeAI();\n * const agent = mock.agent('test-agent', { userId: 'u1' });\n * agent.trackUserMessage('hello', { sessionId: 's1' });\n * mock.assertEventTracked('[Agent] User Message', { userId: 'u1' });\n * ```\n */\ntype SimulatedError = {\n  type: string;\n  message: string;\n};\n\nexport class MockAmplitudeAI extends AmplitudeAI {\n  events: MockEvent[] = [];\n  private _simulatedError: SimulatedError | null = null;\n  private _simulatedLatencyMs = 0;\n\n  constructor(config?: AIConfig) {\n    const mockAmplitude = {\n      track: () => {},\n      flush: () => [],\n      shutdown: () => {},\n      init: () => mockAmplitude,\n    };\n\n    super({\n      amplitude: mockAmplitude as unknown as ConstructorParameters<\n        typeof AmplitudeAI\n      >[0]['amplitude'],\n      config,\n    });\n\n    this._amplitude.track = (event) => {\n      this.events.push(event as MockEvent);\n    };\n\n    if (\n      this._config.debug ||\n      this._config.dryRun ||\n      this._config.onEventCallback != null\n    ) {\n      (\n        this as unknown as { _installTrackHook: () => void }\n      )._installTrackHook?.();\n    }\n  }\n\n  getEvents(eventType?: string): MockEvent[] {\n    if (eventType == null) return [...this.events];\n    return this.events.filter((e) => e.event_type === eventType);\n  }\n\n  assertEventTracked(\n    eventType: string,\n    options: { userId?: string; [key: string]: unknown } = {},\n  ): MockEvent {\n    const { userId, ...expectedProps } = options;\n    const candidates = this.getEvents(eventType);\n\n    if (!candidates.length) {\n      const trackedTypes = new Set(this.events.map((e) => e.event_type));\n      throw new Error(\n        `No '${eventType}' event tracked. Tracked types: ${[...trackedTypes].join(', ') || '(none)'}`,\n      );\n    }\n\n    for (const event of candidates) {\n      if (userId != null && event.user_id !== userId) continue;\n\n      if (Object.keys(expectedProps).length > 0) {\n        const props = event.event_properties ?? {};\n        if (Object.entries(expectedProps).every(([k, v]) => props[k] === v)) {\n          return event;\n        }\n      } else {\n        return event;\n      }\n    }\n\n    const filters = [];\n    if (userId != null) filters.push(`userId=${userId}`);\n    for (const [k, v] of Object.entries(expectedProps)) {\n      filters.push(`${k}=${String(v)}`);\n    }\n    throw new Error(\n      `Found ${candidates.length} '${eventType}' event(s) but none matched filters: ${filters.join(', ')}`,\n    );\n  }\n\n  /**\n   * Configure the mock to throw an error on the next tracking call.\n   * Useful for testing error-handling paths in your application.\n   *\n   * @param type - Error type (e.g., 'rate_limit', 'network', 'auth')\n   * @param message - Optional custom error message\n   */\n  simulateError(type: string, message?: string): void {\n    this._simulatedError = {\n      type,\n      message: message ?? `Simulated ${type} error`,\n    };\n    this._amplitude.track = () => {\n      const err = this._simulatedError;\n      if (err) {\n        throw new Error(`[MockAmplitudeAI] ${err.type}: ${err.message}`);\n      }\n    };\n  }\n\n  /**\n   * Configure a simulated latency (in ms) added to each tracking call.\n   * Combined with async tests, this helps verify timeout and retry logic.\n   */\n  simulateLatency(ms: number): void {\n    this._simulatedLatencyMs = ms;\n    const originalCapture = (event: MockEvent): void => {\n      this.events.push(event);\n    };\n    this._amplitude.track = (event) => {\n      if (this._simulatedLatencyMs > 0) {\n        const start = Date.now();\n        while (Date.now() - start < this._simulatedLatencyMs) {\n          // busy wait for synchronous latency simulation\n        }\n      }\n      originalCapture(event as MockEvent);\n    };\n  }\n\n  /**\n   * Clear any simulated error or latency, restoring normal capture behavior.\n   */\n  clearSimulations(): void {\n    this._simulatedError = null;\n    this._simulatedLatencyMs = 0;\n    this._amplitude.track = (event) => {\n      this.events.push(event as MockEvent);\n    };\n  }\n\n  reset(): void {\n    this.events = [];\n    this._simulatedError = null;\n    this._simulatedLatencyMs = 0;\n    // Restore base capture (not clearSimulations, which would lose debug hooks)\n    this._amplitude.track = (event) => {\n      this.events.push(event as MockEvent);\n    };\n    // Re-install debug/dryRun hooks if configured\n    if (\n      this._config.debug ||\n      this._config.dryRun ||\n      this._config.onEventCallback != null\n    ) {\n      (\n        this as unknown as { _installTrackHook: () => void }\n      )._installTrackHook?.();\n    }\n    this._sessionTurnCounters.clear();\n  }\n\n  eventsForSession(sessionId: string): MockEvent[] {\n    return this.events.filter(\n      (e) => e.event_properties?.[PROP_SESSION_ID] === sessionId,\n    );\n  }\n\n  eventsForAgent(agentId: string): MockEvent[] {\n    return this.events.filter(\n      (e) => e.event_properties?.[PROP_AGENT_ID] === agentId,\n    );\n  }\n\n  assertSessionClosed(sessionId: string): MockEvent {\n    const candidates = this.events.filter(\n      (e) =>\n        e.event_type === EVENT_SESSION_END &&\n        e.event_properties?.[PROP_SESSION_ID] === sessionId,\n    );\n\n    if (!candidates.length) {\n      const ended = this.events\n        .filter((e) => e.event_type === EVENT_SESSION_END)\n        .map((e) => e.event_properties?.[PROP_SESSION_ID]);\n      throw new Error(\n        `No '${EVENT_SESSION_END}' event for session '${sessionId}'. Ended sessions: ${ended.length ? ended.join(', ') : '(none)'}`,\n      );\n    }\n\n    return candidates[0] as Record<string, unknown>;\n  }\n}\n"],"mappings":"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"}