autotel 2.1.0

package/dist/event-subscriber.d.cts

@@ -0,0 +1,116 @@
+/**
+ * Event Subscriber Interface (Type-only)
+ *
+ * Import this interface to create custom subscribers without importing implementations.
+ * Keeps core package focused on OpenTelemetry with zero extra dependencies.
+ *
+ * For ready-made subscribers (PostHog, Mixpanel, Amplitude, Segment),
+ * see the separate `autotel-subscribers` package.
+ *
+ * @example Custom subscriber
+ * ```typescript
+ * import { EventSubscriber } from 'autotel/event-subscriber';
+ *
+ * class MyCustomSubscriber implements EventSubscriber {
+ *   trackEvent(name: string, attributes?: Record<string, any>): void {
+ *     // Send to your events platform
+ *   }
+ *   // ... implement other methods
+ * }
+ * ```
+ *
+ * @example Use pre-built subscribers
+ * ```typescript
+ * import { Events } from 'autotel/events';
+ * import { PostHogSubscriber } from 'autotel-subscribers/posthog';
+ * import { MixpanelSubscriber } from 'autotel-subscribers/mixpanel';
+ *
+ * const event =new Event('checkout', {
+ *   subscribers: [
+ *     new PostHogSubscriber({ apiKey: 'phc_...' }),
+ *     new MixpanelSubscriber({ token: '...' })
+ *   ]
+ * });
+ * ```
+ */
+/**
+ * Event attributes (supports any JSON-serializable values)
+ */
+type EventAttributes = Record<string, string | number | boolean>;
+/**
+ * Funnel step status
+ */
+type FunnelStatus = 'started' | 'completed' | 'abandoned' | 'failed';
+/**
+ * Outcome status
+ */
+type OutcomeStatus = 'success' | 'failure' | 'partial';
+/**
+ * Event subscriber interface
+ *
+ * Implement this to send events to any platform.
+ * Zero runtime dependencies - just types.
+ *
+ * All tracking methods are async to support:
+ * - Backpressure signaling (buffer full)
+ * - Streaming platforms (Kafka, Kinesis, Pub/Sub)
+ * - Await delivery confirmation
+ * - Proper error propagation
+ */
+interface EventSubscriber {
+    /**
+     * Track an event (e.g., "user.registered", "order.created")
+     *
+     * @returns Promise that resolves when event is sent (or buffered)
+     */
+    trackEvent(name: string, attributes?: EventAttributes): Promise<void>;
+    /**
+     * Track a funnel step (e.g., checkout: started → completed)
+     *
+     * @returns Promise that resolves when event is sent (or buffered)
+     */
+    trackFunnelStep(funnelName: string, step: FunnelStatus, attributes?: EventAttributes): Promise<void>;
+    /**
+     * Track an outcome (e.g., "payment.processing" → success/failure)
+     *
+     * @returns Promise that resolves when event is sent (or buffered)
+     */
+    trackOutcome(operationName: string, outcome: OutcomeStatus, attributes?: EventAttributes): Promise<void>;
+    /**
+     * Track a value/metric (e.g., revenue, cart value)
+     *
+     * @returns Promise that resolves when event is sent (or buffered)
+     */
+    trackValue(name: string, value: number, attributes?: EventAttributes): Promise<void>;
+    /**
+     * Optional: Flush pending events and clean up resources
+     *
+     * Implement this if your subscriber buffers events, maintains connections,
+     * or needs cleanup before shutdown. Called during graceful shutdown.
+     *
+     * @example
+     * ```typescript
+     * class MySubscriber implements EventSubscriber {
+     *   async shutdown(): Promise<void> {
+     *     await this.flushBuffer();
+     *     await this.closeConnections();
+     *   }
+     * }
+     * ```
+     */
+    shutdown?(): Promise<void>;
+    /**
+     * Optional: Subscriber name for debugging and error reporting
+     *
+     * @example "PostHogSubscriber", "SnowflakeSubscriber", "CustomWebhookSubscriber"
+     */
+    readonly name?: string;
+    /**
+     * Optional: Subscriber version for debugging
+     *
+     * @example "1.0.0"
+     */
+    readonly version?: string;
+}
+
+export type { EventAttributes, EventSubscriber, FunnelStatus, OutcomeStatus };

package/dist/event-subscriber.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Event Subscriber Interface (Type-only)
+ *
+ * Import this interface to create custom subscribers without importing implementations.
+ * Keeps core package focused on OpenTelemetry with zero extra dependencies.
+ *
+ * For ready-made subscribers (PostHog, Mixpanel, Amplitude, Segment),
+ * see the separate `autotel-subscribers` package.
+ *
+ * @example Custom subscriber
+ * ```typescript
+ * import { EventSubscriber } from 'autotel/event-subscriber';
+ *
+ * class MyCustomSubscriber implements EventSubscriber {
+ *   trackEvent(name: string, attributes?: Record<string, any>): void {
+ *     // Send to your events platform
+ *   }
+ *   // ... implement other methods
+ * }
+ * ```
+ *
+ * @example Use pre-built subscribers
+ * ```typescript
+ * import { Events } from 'autotel/events';
+ * import { PostHogSubscriber } from 'autotel-subscribers/posthog';
+ * import { MixpanelSubscriber } from 'autotel-subscribers/mixpanel';
+ *
+ * const event =new Event('checkout', {
+ *   subscribers: [
+ *     new PostHogSubscriber({ apiKey: 'phc_...' }),
+ *     new MixpanelSubscriber({ token: '...' })
+ *   ]
+ * });
+ * ```
+ */
+/**
+ * Event attributes (supports any JSON-serializable values)
+ */
+type EventAttributes = Record<string, string | number | boolean>;
+/**
+ * Funnel step status
+ */
+type FunnelStatus = 'started' | 'completed' | 'abandoned' | 'failed';
+/**
+ * Outcome status
+ */
+type OutcomeStatus = 'success' | 'failure' | 'partial';
+/**
+ * Event subscriber interface
+ *
+ * Implement this to send events to any platform.
+ * Zero runtime dependencies - just types.
+ *
+ * All tracking methods are async to support:
+ * - Backpressure signaling (buffer full)
+ * - Streaming platforms (Kafka, Kinesis, Pub/Sub)
+ * - Await delivery confirmation
+ * - Proper error propagation
+ */
+interface EventSubscriber {
+    /**
+     * Track an event (e.g., "user.registered", "order.created")
+     *
+     * @returns Promise that resolves when event is sent (or buffered)
+     */
+    trackEvent(name: string, attributes?: EventAttributes): Promise<void>;
+    /**
+     * Track a funnel step (e.g., checkout: started → completed)
+     *
+     * @returns Promise that resolves when event is sent (or buffered)
+     */
+    trackFunnelStep(funnelName: string, step: FunnelStatus, attributes?: EventAttributes): Promise<void>;
+    /**
+     * Track an outcome (e.g., "payment.processing" → success/failure)
+     *
+     * @returns Promise that resolves when event is sent (or buffered)
+     */
+    trackOutcome(operationName: string, outcome: OutcomeStatus, attributes?: EventAttributes): Promise<void>;
+    /**
+     * Track a value/metric (e.g., revenue, cart value)
+     *
+     * @returns Promise that resolves when event is sent (or buffered)
+     */
+    trackValue(name: string, value: number, attributes?: EventAttributes): Promise<void>;
+    /**
+     * Optional: Flush pending events and clean up resources
+     *
+     * Implement this if your subscriber buffers events, maintains connections,
+     * or needs cleanup before shutdown. Called during graceful shutdown.
+     *
+     * @example
+     * ```typescript
+     * class MySubscriber implements EventSubscriber {
+     *   async shutdown(): Promise<void> {
+     *     await this.flushBuffer();
+     *     await this.closeConnections();
+     *   }
+     * }
+     * ```
+     */
+    shutdown?(): Promise<void>;
+    /**
+     * Optional: Subscriber name for debugging and error reporting
+     *
+     * @example "PostHogSubscriber", "SnowflakeSubscriber", "CustomWebhookSubscriber"
+     */
+    readonly name?: string;
+    /**
+     * Optional: Subscriber version for debugging
+     *
+     * @example "1.0.0"
+     */
+    readonly version?: string;
+}
+
+export type { EventAttributes, EventSubscriber, FunnelStatus, OutcomeStatus };

package/dist/event-subscriber.js

@@ -0,0 +1,3 @@
+import './chunk-LITNXTTT.js';
+//# sourceMappingURL=event-subscriber.js.map
+//# sourceMappingURL=event-subscriber.js.map

package/dist/event-subscriber.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"event-subscriber.js"}

package/dist/event-testing.cjs

@@ -0,0 +1,21 @@
+'use strict';
+
+var chunkUY3UYPBZ_cjs = require('./chunk-UY3UYPBZ.cjs');
+require('./chunk-G7VZBCD6.cjs');
+
+
+
+Object.defineProperty(exports, "assertEventTracked", {
+  enumerable: true,
+  get: function () { return chunkUY3UYPBZ_cjs.assertEventTracked; }
+});
+Object.defineProperty(exports, "assertOutcomeTracked", {
+  enumerable: true,
+  get: function () { return chunkUY3UYPBZ_cjs.assertOutcomeTracked; }
+});
+Object.defineProperty(exports, "createEventCollector", {
+  enumerable: true,
+  get: function () { return chunkUY3UYPBZ_cjs.createEventCollector; }
+});
+//# sourceMappingURL=event-testing.cjs.map
+//# sourceMappingURL=event-testing.cjs.map

package/dist/event-testing.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"event-testing.cjs"}

package/dist/event-testing.d.cts

@@ -0,0 +1,110 @@
+import { EventAttributes, FunnelStatus, OutcomeStatus } from './event-subscriber.cjs';
+
+/**
+ * Testing utilities for Events
+ *
+ * Provides in-memory collection of events for testing purposes.
+ */
+
+interface EventData {
+    event: string;
+    attributes?: EventAttributes;
+    service: string;
+    timestamp: number;
+}
+interface EventsFunnelStep {
+    funnel: string;
+    status: FunnelStatus;
+    attributes?: EventAttributes;
+    service: string;
+    timestamp: number;
+}
+interface EventsOutcome {
+    operation: string;
+    status: OutcomeStatus;
+    attributes?: EventAttributes;
+    service: string;
+    timestamp: number;
+}
+interface EventsValue {
+    metric: string;
+    value: number;
+    attributes?: EventAttributes;
+    service: string;
+    timestamp: number;
+}
+/**
+ * In-memory events collector for testing
+ */
+interface EventCollector {
+    /** Get all collected events */
+    getEvents(): EventData[];
+    /** Get all collected funnel steps */
+    getFunnelSteps(): EventsFunnelStep[];
+    /** Get all collected outcomes */
+    getOutcomes(): EventsOutcome[];
+    /** Get all collected values */
+    getValues(): EventsValue[];
+    /** Clear all collected events */
+    clear(): void;
+    /** Record an event (internal use) */
+    recordEvent(event: EventData): void;
+    /** Record a funnel step (internal use) */
+    recordFunnelStep(step: EventsFunnelStep): void;
+    /** Record an outcome (internal use) */
+    recordOutcome(outcome: EventsOutcome): void;
+    /** Record a value (internal use) */
+    recordValue(value: EventsValue): void;
+}
+/**
+ * Create an in-memory events collector for testing
+ *
+ * @example
+ * ```typescript
+ * const collector = createEventCollector()
+ *
+ * const events = new Event('test-service', { collector })
+ * events.trackEvent('application.submitted', { jobId: '123' })
+ *
+ * const event =collector.getEvents()
+ * expect(events).toHaveLength(1)
+ * expect(events[0].event).toBe('application.submitted')
+ * ```
+ */
+declare function createEventCollector(): EventCollector;
+/**
+ * Assert that an events event was tracked
+ *
+ * @example
+ * ```typescript
+ * assertEventTracked({
+ *   collector,
+ *   eventName: 'application.submitted',
+ *   attributes: { jobId: '123' }
+ * })
+ * ```
+ */
+declare function assertEventTracked(options: {
+    collector: EventCollector;
+    eventName: string;
+    attributes?: Record<string, unknown>;
+}): void;
+/**
+ * Assert that an outcome was tracked
+ *
+ * @example
+ * ```typescript
+ * assertOutcomeTracked({
+ *   collector,
+ *   operation: 'email.delivery',
+ *   status: 'success'
+ * })
+ * ```
+ */
+declare function assertOutcomeTracked(options: {
+    collector: EventCollector;
+    operation: string;
+    status: 'success' | 'failure' | 'partial';
+}): void;
+
+export { type EventCollector, type EventData, type EventsFunnelStep, type EventsOutcome, type EventsValue, assertEventTracked, assertOutcomeTracked, createEventCollector };

package/dist/event-testing.d.ts

@@ -0,0 +1,110 @@
+import { EventAttributes, FunnelStatus, OutcomeStatus } from './event-subscriber.js';
+
+/**
+ * Testing utilities for Events
+ *
+ * Provides in-memory collection of events for testing purposes.
+ */
+
+interface EventData {
+    event: string;
+    attributes?: EventAttributes;
+    service: string;
+    timestamp: number;
+}
+interface EventsFunnelStep {
+    funnel: string;
+    status: FunnelStatus;
+    attributes?: EventAttributes;
+    service: string;
+    timestamp: number;
+}
+interface EventsOutcome {
+    operation: string;
+    status: OutcomeStatus;
+    attributes?: EventAttributes;
+    service: string;
+    timestamp: number;
+}
+interface EventsValue {
+    metric: string;
+    value: number;
+    attributes?: EventAttributes;
+    service: string;
+    timestamp: number;
+}
+/**
+ * In-memory events collector for testing
+ */
+interface EventCollector {
+    /** Get all collected events */
+    getEvents(): EventData[];
+    /** Get all collected funnel steps */
+    getFunnelSteps(): EventsFunnelStep[];
+    /** Get all collected outcomes */
+    getOutcomes(): EventsOutcome[];
+    /** Get all collected values */
+    getValues(): EventsValue[];
+    /** Clear all collected events */
+    clear(): void;
+    /** Record an event (internal use) */
+    recordEvent(event: EventData): void;
+    /** Record a funnel step (internal use) */
+    recordFunnelStep(step: EventsFunnelStep): void;
+    /** Record an outcome (internal use) */
+    recordOutcome(outcome: EventsOutcome): void;
+    /** Record a value (internal use) */
+    recordValue(value: EventsValue): void;
+}
+/**
+ * Create an in-memory events collector for testing
+ *
+ * @example
+ * ```typescript
+ * const collector = createEventCollector()
+ *
+ * const events = new Event('test-service', { collector })
+ * events.trackEvent('application.submitted', { jobId: '123' })
+ *
+ * const event =collector.getEvents()
+ * expect(events).toHaveLength(1)
+ * expect(events[0].event).toBe('application.submitted')
+ * ```
+ */
+declare function createEventCollector(): EventCollector;
+/**
+ * Assert that an events event was tracked
+ *
+ * @example
+ * ```typescript
+ * assertEventTracked({
+ *   collector,
+ *   eventName: 'application.submitted',
+ *   attributes: { jobId: '123' }
+ * })
+ * ```
+ */
+declare function assertEventTracked(options: {
+    collector: EventCollector;
+    eventName: string;
+    attributes?: Record<string, unknown>;
+}): void;
+/**
+ * Assert that an outcome was tracked
+ *
+ * @example
+ * ```typescript
+ * assertOutcomeTracked({
+ *   collector,
+ *   operation: 'email.delivery',
+ *   status: 'success'
+ * })
+ * ```
+ */
+declare function assertOutcomeTracked(options: {
+    collector: EventCollector;
+    operation: string;
+    status: 'success' | 'failure' | 'partial';
+}): void;
+
+export { type EventCollector, type EventData, type EventsFunnelStep, type EventsOutcome, type EventsValue, assertEventTracked, assertOutcomeTracked, createEventCollector };

package/dist/event-testing.js

@@ -0,0 +1,4 @@
+export { assertEventTracked, assertOutcomeTracked, createEventCollector } from './chunk-BZHG5IZ4.js';
+import './chunk-Z6ZWNWWR.js';
+//# sourceMappingURL=event-testing.js.map
+//# sourceMappingURL=event-testing.js.map

package/dist/event-testing.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"event-testing.js"}

package/dist/event.cjs

@@ -0,0 +1,30 @@
+'use strict';
+
+var chunk77MSMAUQ_cjs = require('./chunk-77MSMAUQ.cjs');
+require('./chunk-NZ72VDNY.cjs');
+require('./chunk-UY3UYPBZ.cjs');
+require('./chunk-YLPNXZFI.cjs');
+require('./chunk-ABPEQ6RK.cjs');
+require('./chunk-GVLK7YUU.cjs');
+require('./chunk-HE6T6FIX.cjs');
+require('./chunk-4OAT42CA.cjs');
+require('./chunk-Y4Y2S7BM.cjs');
+require('./chunk-URRW6M2C.cjs');
+require('./chunk-G7VZBCD6.cjs');
+
+
+
+Object.defineProperty(exports, "Event", {
+  enumerable: true,
+  get: function () { return chunk77MSMAUQ_cjs.Event; }
+});
+Object.defineProperty(exports, "getEvents", {
+  enumerable: true,
+  get: function () { return chunk77MSMAUQ_cjs.getEvents; }
+});
+Object.defineProperty(exports, "resetEvents", {
+  enumerable: true,
+  get: function () { return chunk77MSMAUQ_cjs.resetEvents; }
+});
+//# sourceMappingURL=event.cjs.map
+//# sourceMappingURL=event.cjs.map

package/dist/event.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"event.cjs"}