autotel-subscribers 40.0.0 → 41.0.0

package/src/factories.ts

@@ -1,342 +0,0 @@
-/**
- * Factory functions for creating events subscribers
- *
- * Function-based alternatives to `new SubscriberClass()` pattern.
- * Provides a consistent API and better tree-shaking.
- *
- * @example
- * ```typescript
- * import { createPostHogSubscriber, createWebhookSubscriber } from 'autotel-subscribers/factories'
- *
- * const events = new Events('my-service', {
- *   subscribers: [
- *     createPostHogSubscriber({ apiKey: 'phc_...' }),
- *     createWebhookSubscriber({ url: 'https://...' })
- *   ]
- * })
- * ```
- */
-
-import { PostHogSubscriber } from './posthog';
-import { MixpanelSubscriber } from './mixpanel';
-import { AmplitudeSubscriber } from './amplitude';
-import { SegmentSubscriber } from './segment';
-import { WebhookSubscriber } from './webhook';
-import { SlackSubscriber } from './slack';
-import { MockEventSubscriber } from './mock-event-subscriber';
-
-import type {
-  EventSubscriber,
-  EventAttributes,
-  OutcomeStatus,
-  FunnelStatus,
-  EventTrackingOptions,
-} from 'autotel/event-subscriber';
-
-export type { PostHogConfig } from './posthog';
-export type { MixpanelConfig } from './mixpanel';
-export type { AmplitudeConfig } from './amplitude';
-export type { SegmentConfig } from './segment';
-export type { WebhookConfig } from './webhook';
-export type { SlackSubscriberConfig } from './slack';
-
-/** Create a PostHog events subscriber */
-export function createPostHogSubscriber(config: {
-  apiKey: string;
-  host?: string;
-  enabled?: boolean;
-}): EventSubscriber {
-  return new PostHogSubscriber(config);
-}
-
-/** Create a Mixpanel events subscriber */
-export function createMixpanelSubscriber(config: {
-  token: string;
-  enabled?: boolean;
-}): EventSubscriber {
-  return new MixpanelSubscriber(config);
-}
-
-/** Create an Amplitude events subscriber */
-export function createAmplitudeSubscriber(config: {
-  apiKey: string;
-  enabled?: boolean;
-}): EventSubscriber {
-  return new AmplitudeSubscriber(config);
-}
-
-/** Create a Segment events subscriber */
-export function createSegmentSubscriber(config: {
-  writeKey: string;
-  enabled?: boolean;
-}): EventSubscriber {
-  return new SegmentSubscriber(config);
-}
-
-/** Create a Webhook events subscriber with retry and timeout support */
-export function createWebhookSubscriber(config: {
-  url: string;
-  method?: 'POST' | 'PUT';
-  headers?: Record<string, string>;
-  enabled?: boolean;
-  maxRetries?: number;
-  timeoutMs?: number;
-  retryDelayMs?: number;
-}): EventSubscriber {
-  return new WebhookSubscriber(config);
-}
-
-/** Create a Slack events subscriber */
-export function createSlackSubscriber(config: {
-  webhookUrl: string;
-  channel?: string;
-  enabled?: boolean;
-}): EventSubscriber {
-  return new SlackSubscriber(config);
-}
-
-/** Create a mock events subscriber for testing */
-export function createMockSubscriber(): MockEventSubscriber {
-  return new MockEventSubscriber();
-}
-
-/**
- * Strategy for composing multiple subscribers
- *
- * - `parallel`: Send to all subscribers concurrently, fail if any fails
- * - `failover`: Try subscribers in order until one succeeds
- * - `round-robin`: Cycle through subscribers sequentially
- * - `random`: Pick a random subscriber each time
- * - `race`: Send to all, succeed when any succeeds
- * - `mirrored`: Send to primary, mirror to others (primary failure fails all)
- */
-export type ComposeSubscriberStrategy =
-  | 'parallel'
-  | 'failover'
-  | 'round-robin'
-  | 'random'
-  | 'race'
-  | 'mirrored';
-
-/** Configuration options for composing multiple subscribers */
-export type ComposeSubscribersOptions = {
-  name?: string;
-  strategy?: ComposeSubscriberStrategy;
-  maxAttemptsPerSubscriber?: number;
-  initialRetryDelayMs?: number;
-  maxRetryDelayMs?: number;
-  isRetriable?: (error: unknown) => boolean;
-  logger?: Pick<Console, 'debug' | 'warn' | 'error'>;
-};
-
-type SubscriberMethod =
-  | 'trackEvent'
-  | 'trackFunnelStep'
-  | 'trackOutcome'
-  | 'trackValue';
-
-type MethodCall = {
-  method: SubscriberMethod;
-  args: unknown[];
-};
-
-function backoffDelay(attempt: number, initialMs: number, maxMs: number): number {
-  return Math.min(maxMs, initialMs * 2 ** (attempt - 1));
-}
-
-async function callSubscriber(subscriber: EventSubscriber, call: MethodCall): Promise<void> {
-  switch (call.method) {
-    case 'trackEvent': {
-      await subscriber.trackEvent(
-        call.args[0] as string,
-        call.args[1] as EventAttributes | undefined,
-        call.args[2] as EventTrackingOptions | undefined,
-      );
-      return;
-    }
-    case 'trackFunnelStep': {
-      await subscriber.trackFunnelStep(
-        call.args[0] as string,
-        call.args[1] as FunnelStatus,
-        call.args[2] as EventAttributes | undefined,
-        call.args[3] as EventTrackingOptions | undefined,
-      );
-      return;
-    }
-    case 'trackOutcome': {
-      await subscriber.trackOutcome(
-        call.args[0] as string,
-        call.args[1] as OutcomeStatus,
-        call.args[2] as EventAttributes | undefined,
-        call.args[3] as EventTrackingOptions | undefined,
-      );
-      return;
-    }
-    case 'trackValue': {
-      await subscriber.trackValue(
-        call.args[0] as string,
-        call.args[1] as number,
-        call.args[2] as EventAttributes | undefined,
-        call.args[3] as EventTrackingOptions | undefined,
-      );
-    }
-  }
-}
-
-/**
- * Compose multiple subscribers into one with a specified strategy
- *
- * @example
- * ```typescript
- * const multiSubscriber = composeSubscribers(
- *   [
- *     createPostHogSubscriber({ apiKey: '...' }),
- *     createWebhookSubscriber({ url: '...' })
- *   ],
- *   { strategy: 'parallel' }
- * )
- * ```
- *
- * @param subscribers - Array of subscribers to compose
- * @param options - Configuration for composition strategy and retry behavior
- * @returns A composite EventSubscriber that applies the strategy
- */
-export function composeSubscribers(
-  subscribers: EventSubscriber[],
-  options: ComposeSubscribersOptions = {},
-): EventSubscriber {
-  const strategy = options.strategy ?? 'parallel';
-  const name = options.name ?? `ComposedSubscriber(${strategy})`;
-  const maxAttempts = options.maxAttemptsPerSubscriber ?? 1;
-  const initialRetryDelayMs = options.initialRetryDelayMs ?? 250;
-  const maxRetryDelayMs = options.maxRetryDelayMs ?? 10_000;
-  const isRetriable = options.isRetriable ?? (() => true);
-  const logger = options.logger ?? console;
-  let rrCounter = 0;
-
-  const sendOne = async (subscriber: EventSubscriber, call: MethodCall): Promise<void> => {
-    let lastError: unknown;
-
-    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
-      try {
-        await callSubscriber(subscriber, call);
-        return;
-      } catch (error) {
-        lastError = error;
-        const retryable = isRetriable(error);
-        logger.warn?.('composeSubscribers attempt failed', {
-          subscriber: subscriber.name,
-          attempt,
-          retryable,
-          strategy,
-          error,
-        });
-
-        if (!retryable || attempt >= maxAttempts) break;
-        await new Promise((resolve) =>
-          setTimeout(resolve, backoffDelay(attempt, initialRetryDelayMs, maxRetryDelayMs)),
-        );
-      }
-    }
-
-    throw (lastError instanceof Error ? lastError : new Error(String(lastError)));
-  };
-
-  const orderForSequential = (): number[] => {
-    const n = subscribers.length;
-    if (n === 0) return [];
-
-    if (strategy === 'failover') {
-      return Array.from({ length: n }, (_, i) => i);
-    }
-
-    const start =
-      strategy === 'random' ? Math.floor(Math.random() * n) : rrCounter++ % n;
-
-    return Array.from({ length: n }, (_, i) => (start + i) % n);
-  };
-
-  const execute = async (call: MethodCall): Promise<void> => {
-    if (subscribers.length === 0) return;
-
-    if (strategy === 'parallel') {
-      await Promise.all(subscribers.map((subscriber) => sendOne(subscriber, call)));
-      return;
-    }
-
-    if (strategy === 'race') {
-      const attempts = subscribers.map(async (subscriber) => {
-        await sendOne(subscriber, call);
-        return subscriber.name ?? 'unknown';
-      });
-
-      try {
-        await Promise.any(attempts);
-      } catch (error) {
-        if (error instanceof AggregateError && error.errors.length > 0) {
-          throw error.errors.at(-1);
-        }
-        throw error;
-      }
-      return;
-    }
-
-    if (strategy === 'mirrored') {
-      const primary = subscribers[0];
-      if (!primary) return;
-      await sendOne(primary, call);
-
-      for (const mirror of subscribers.slice(1)) {
-        void sendOne(mirror, call).catch((error) => {
-          logger.warn?.('composeSubscribers mirror failed', {
-            subscriber: mirror.name,
-            error,
-          });
-        });
-      }
-      return;
-    }
-
-    const order = orderForSequential();
-    let lastError: unknown;
-
-    for (const index of order) {
-      const subscriber = subscribers[index];
-      if (!subscriber) continue;
-
-      try {
-        await sendOne(subscriber, call);
-        return;
-      } catch (error) {
-        lastError = error;
-      }
-    }
-
-    throw (lastError instanceof Error ? lastError : new Error(String(lastError)));
-  };
-
-  return {
-    name,
-    async trackEvent(name_, attributes, options_) {
-      await execute({ method: 'trackEvent', args: [name_, attributes, options_] });
-    },
-    async trackFunnelStep(funnel, step, attributes, options_) {
-      await execute({
-        method: 'trackFunnelStep',
-        args: [funnel, step, attributes, options_],
-      });
-    },
-    async trackOutcome(operation, outcome, attributes, options_) {
-      await execute({
-        method: 'trackOutcome',
-        args: [operation, outcome, attributes, options_],
-      });
-    },
-    async trackValue(name_, value, attributes, options_) {
-      await execute({ method: 'trackValue', args: [name_, value, attributes, options_] });
-    },
-    async shutdown() {
-      await Promise.all(subscribers.map(async (subscriber) => subscriber.shutdown?.()));
-    },
-  };
-}

package/src/file.test.ts

@@ -1,87 +0,0 @@
-import { describe, it, expect, beforeEach, afterEach } from 'vitest';
-import { mkdtemp, readFile, rm } from 'node:fs/promises';
-import { tmpdir } from 'node:os';
-import nodePath from 'node:path';
-import { FileSubscriber } from './file';
-
-describe('FileSubscriber', () => {
-  let dir: string;
-
-  beforeEach(async () => {
-    dir = await mkdtemp(nodePath.join(tmpdir(), 'autotel-file-sub-'));
-  });
-
-  afterEach(async () => {
-    await rm(dir, { recursive: true, force: true });
-  });
-
-  it('appends one NDJSON line per event', async () => {
-    const path = nodePath.join(dir, 'events.ndjson');
-    const sub = new FileSubscriber({ path });
-
-    await sub.trackEvent('order.completed', { amount: 99 });
-    await sub.trackEvent('order.refunded', { amount: 99 });
-    await sub.shutdown();
-
-    const contents = await readFile(path, 'utf8');
-    const lines = contents.trim().split('\n');
-    expect(lines).toHaveLength(2);
-
-    const first = JSON.parse(lines[0]);
-    expect(first.name).toBe('order.completed');
-    expect(first.type).toBe('event');
-    expect(first.attributes).toEqual({ amount: 99 });
-
-    const second = JSON.parse(lines[1]);
-    expect(second.name).toBe('order.refunded');
-  });
-
-  it('creates parent directories when missing', async () => {
-    const path = nodePath.join(dir, 'nested', 'deep', 'events.ndjson');
-    const sub = new FileSubscriber({ path });
-
-    await sub.trackEvent('created');
-    await sub.shutdown();
-
-    const contents = await readFile(path, 'utf8');
-    expect(JSON.parse(contents.trim()).name).toBe('created');
-  });
-
-  it('supports pretty multi-line output', async () => {
-    const path = nodePath.join(dir, 'pretty.json');
-    const sub = new FileSubscriber({ path, pretty: true });
-
-    await sub.trackEvent('pretty.event', { nested: { a: 1 } });
-    await sub.shutdown();
-
-    const contents = await readFile(path, 'utf8');
-    expect(contents).toContain('\n  "name": "pretty.event"');
-  });
-
-  it('skips events when transform returns null', async () => {
-    const path = nodePath.join(dir, 'filtered.ndjson');
-    const sub = new FileSubscriber({
-      path,
-      transform: (p) => (p.name === 'keep' ? { kept: p.name } : null),
-    });
-
-    await sub.trackEvent('drop');
-    await sub.trackEvent('keep');
-    await sub.shutdown();
-
-    const contents = await readFile(path, 'utf8');
-    const lines = contents.trim().split('\n');
-    expect(lines).toHaveLength(1);
-    expect(JSON.parse(lines[0])).toEqual({ kept: 'keep' });
-  });
-
-  it('writes nothing when disabled', async () => {
-    const path = nodePath.join(dir, 'disabled.ndjson');
-    const sub = new FileSubscriber({ path, enabled: false });
-
-    await sub.trackEvent('ignored');
-    await sub.shutdown();
-
-    await expect(readFile(path, 'utf8')).rejects.toThrow();
-  });
-});

package/src/file.ts

@@ -1,97 +0,0 @@
-/**
- * File subscriber for autotel.
- *
- * Appends each tracked event to a file as newline-delimited JSON (NDJSON).
- * Useful for AI agents, scripts, evals, and local debugging that want
- * structured events on disk without a hosted backend. Query the file with
- * `jq`, load it into a notebook, or feed it to an agent.
- *
- * @example
- * ```typescript
- * import { Event } from 'autotel/events';
- * import { FileSubscriber } from 'autotel-subscribers/file';
- *
- * const events = new Event('worker', {
- *   subscribers: [new FileSubscriber({ path: './telemetry/events.ndjson' })],
- * });
- * ```
- */
-
-import { appendFile, mkdir } from 'node:fs/promises';
-import path from 'node:path';
-import { EventSubscriber, type EventPayload } from './event-subscriber-base';
-
-export interface FileSubscriberConfig {
-  /** File path to append newline-delimited JSON events to. */
-  path: string;
-  /** Enable or disable the subscriber. Default `true`. */
-  enabled?: boolean;
-  /** Pretty-print each event as indented JSON instead of one line. Default `false`. */
-  pretty?: boolean;
-  /** Create parent directories if they do not exist. Default `true`. */
-  mkdir?: boolean;
-  /**
-   * Transform a payload before writing. Return `null` to skip the event.
-   * Defaults to writing the normalized payload unchanged.
-   */
-  transform?: (payload: EventPayload) => Record<string, unknown> | null;
-}
-
-export class FileSubscriber extends EventSubscriber {
-  readonly name = 'FileSubscriber';
-  readonly version = '1.0.0';
-
-  private readonly filePath: string;
-  private readonly pretty: boolean;
-  private readonly ensureDir: boolean;
-  private readonly transform?: (
-    payload: EventPayload,
-  ) => Record<string, unknown> | null;
-
-  /** Serializes writes so concurrent events never interleave on disk. */
-  private writeChain: Promise<void> = Promise.resolve();
-  private dirEnsured = false;
-
-  constructor(config: FileSubscriberConfig) {
-    super();
-    this.filePath = config.path;
-    this.enabled = config.enabled ?? true;
-    this.pretty = config.pretty ?? false;
-    this.ensureDir = config.mkdir ?? true;
-    this.transform = config.transform;
-  }
-
-  protected async sendToDestination(payload: EventPayload): Promise<void> {
-    if (!this.enabled) return;
-
-    const record = this.transform ? this.transform(payload) : payload;
-    if (record === null) return;
-
-    const json = this.pretty
-      ? JSON.stringify(record, null, 2)
-      : JSON.stringify(record);
-    const line = `${json}\n`;
-
-    const run = this.writeChain.then(() => this.write(line));
-    // Keep the chain ordered and alive even if one write rejects; the failed
-    // write still rejects `run` so the base class can report it.
-    this.writeChain = run.catch(() => {});
-    await run;
-  }
-
-  private async write(line: string): Promise<void> {
-    if (this.ensureDir && !this.dirEnsured) {
-      const dir = path.dirname(this.filePath);
-      if (dir && dir !== '.') {
-        await mkdir(dir, { recursive: true });
-      }
-      this.dirEnsured = true;
-    }
-    await appendFile(this.filePath, line, 'utf8');
-  }
-
-  override async shutdown(): Promise<void> {
-    await this.writeChain;
-    await super.shutdown();
-  }
-}

package/src/http-client.ts

@@ -1,127 +0,0 @@
-/**
- * HTTP client for sending webhook events
- *
- * Provides proper error handling, timeout support, and response parsing
- */
-
-export type HttpRetryOptions = {
-  retries?: number;
-  delayMs?: number;
-};
-
-export type HttpClientOptions = {
-  timeoutMs?: number;
-  retry?: HttpRetryOptions;
-};
-
-export type HttpSuccess<T = unknown> = {
-  ok: true;
-  status: number;
-  data: T | null;
-};
-
-export type HttpNetworkError = {
-  ok: false;
-  kind: 'network';
-  timedOut: boolean;
-  cause: Error;
-};
-
-export type HttpStatusError<E = unknown> = {
-  ok: false;
-  kind: 'http';
-  status: number;
-  statusText: string;
-  body: E;
-};
-
-export type HttpResult<T = unknown, E = unknown> =
-  | HttpSuccess<T>
-  | HttpNetworkError
-  | HttpStatusError<E>;
-
-export type HttpRequestOptions = {
-  method?: string;
-  headers?: Record<string, string>;
-  body?: string;
-  timeoutMs?: number;
-};
-
-async function parseBody(response: Response): Promise<unknown> {
-  const text = await response.text();
-  if (text.trim().length === 0) return null;
-
-  try {
-    return JSON.parse(text) as unknown;
-  } catch {
-    return text;
-  }
-}
-
-function isTimeoutError(error: unknown): boolean {
-  if (!(error instanceof Error)) return false;
-  return error.name === 'AbortError' || error.name === 'TimeoutError';
-}
-
-/**
- * Create an HTTP client with timeout and error handling
- *
- * @param options Configuration for timeout and retry behavior
- * @returns HTTP client with request method
- *
- * @example
- * ```typescript
- * const client = createHttpClient({ timeoutMs: 5000 })
- * const result = await client.request('https://example.com', {
- *   method: 'POST',
- *   body: JSON.stringify({ event: 'test' })
- * })
- * ```
- */
-export function createHttpClient(options: HttpClientOptions = {}) {
-  const defaultTimeoutMs = options.timeoutMs ?? 30_000;
-
-  return {
-    async request<T = unknown, E = unknown>(
-      url: string,
-      requestOptions: HttpRequestOptions = {},
-    ): Promise<HttpResult<T, E>> {
-      const timeoutMs = requestOptions.timeoutMs ?? defaultTimeoutMs;
-      const controller = new AbortController();
-      const timeoutHandle = setTimeout(() => controller.abort(), timeoutMs);
-
-      try {
-        const response = await fetch(url, {
-          method: requestOptions.method ?? 'GET',
-          headers: requestOptions.headers,
-          body: requestOptions.body,
-          signal: controller.signal,
-        });
-
-        if (!response.ok) {
-          const body = (await parseBody(response)) as E;
-          return {
-            ok: false,
-            kind: 'http',
-            status: response.status,
-            statusText: response.statusText,
-            body,
-          };
-        }
-
-        const data = (await parseBody(response)) as T;
-        return { ok: true, status: response.status, data };
-      } catch (error) {
-        const cause = error instanceof Error ? error : new Error(String(error));
-        return {
-          ok: false,
-          kind: 'network',
-          timedOut: isTimeoutError(error),
-          cause,
-        };
-      } finally {
-        clearTimeout(timeoutHandle);
-      }
-    },
-  };
-}