autotel 2.1.0

package/dist/event.d.cts

@@ -0,0 +1,282 @@
+import { Logger } from './logger.cjs';
+import { EventSubscriber, EventAttributes, FunnelStatus, OutcomeStatus } from './event-subscriber.cjs';
+import { EventCollector } from './event-testing.cjs';
+import 'pino';
+
+/**
+ * Events API for product events platforms
+ *
+ * Track user behavior, business events, and critical actions.
+ * Sends to product events platforms (PostHog, Mixpanel, Amplitude) via subscribers.
+ * For business people who think in events/funnels.
+ *
+ * For OpenTelemetry metrics (Prometheus/Grafana), use the Metrics class instead.
+ *
+ * @example Recommended: Configure subscribers in init(), use track() function
+ * ```typescript
+ * import { init, track } from 'autotel';
+ * import { PostHogSubscriber } from 'autotel-subscribers/posthog';
+ *
+ * init({
+ *   service: 'my-app',
+ *   subscribers: [new PostHogSubscriber({ apiKey: 'phc_...' })]
+ * });
+ *
+ * // Track events - uses subscribers from init()
+ * track('application.submitted', { jobId: '123', userId: '456' });
+ * ```
+ *
+ * @example Create Event instance (inherits subscribers from init)
+ * ```typescript
+ * import { Event } from 'autotel/event';
+ *
+ * // Uses subscribers configured in init()
+ * const event = new Event('job-application');
+ * event.trackEvent('application.submitted', { jobId: '123' });
+ * ```
+ *
+ * @example Override subscribers for specific Event instance
+ * ```typescript
+ * import { Event } from 'autotel/event';
+ * import { PostHogSubscriber } from 'autotel-subscribers/posthog';
+ *
+ * // Override: use different subscribers for this instance
+ * const event = new Event('job-application', {
+ *   subscribers: [new PostHogSubscriber({ apiKey: 'phc_different_project' })]
+ * });
+ *
+ * event.trackEvent('application.submitted', { jobId: '123' });
+ * ```
+ */
+
+/**
+ * Events class for tracking user behavior and product events
+ *
+ * Track critical indicators such as:
+ * - User events (signups, purchases, feature usage)
+ * - Conversion funnels (signup → activation → purchase)
+ * - Business outcomes (success/failure rates)
+ * - Product metrics (revenue, engagement, retention)
+ *
+ * All events are sent to events platforms via subscribers (PostHog, Mixpanel, etc.).
+ * For OpenTelemetry metrics, use the Metrics class instead.
+ */
+/**
+ * Events options
+ */
+interface EventsOptions {
+    /** Optional logger for audit trail */
+    logger?: Logger;
+    /** Optional collector for testing (captures events in memory) */
+    collector?: EventCollector;
+    /**
+     * Optional subscribers to send events to other platforms
+     * (e.g., PostHog, Mixpanel, Amplitude)
+     *
+     * **Subscriber Resolution**:
+     * - If provided → uses these subscribers (instance override)
+     * - If not provided → falls back to subscribers from `init()` (global config)
+     * - If neither → no subscribers (events logged only)
+     *
+     * Install `autotel-subscribers` package for ready-made subscribers
+     */
+    subscribers?: EventSubscriber[];
+}
+declare class Event {
+    private serviceName;
+    private logger?;
+    private collector?;
+    private subscribers;
+    private hasSubscribers;
+    private circuitBreakers;
+    /**
+     * Create a new Event instance
+     *
+     * **Note**: Most users should use `init()` + `track()` instead of creating Event instances directly.
+     *
+     * **Subscriber Resolution**:
+     * - If `subscribers` provided in options → uses those (instance override)
+     * - If `subscribers` not provided → falls back to subscribers from `init()` (global config)
+     * - If neither → no subscribers (events logged only)
+     *
+     * @param serviceName - Service name for identifying events
+     * @param options - Optional configuration (logger, collector, subscribers)
+     *
+     * @example Recommended: Use track() with init()
+     * ```typescript
+     * import { init, track } from 'autotel';
+     * import { PostHogSubscriber } from 'autotel-subscribers/posthog';
+     *
+     * init({
+     *   service: 'checkout',
+     *   subscribers: [new PostHogSubscriber({ apiKey: 'phc_...' })]
+     * });
+     *
+     * track('purchase.completed', { amount: 99.99 });
+     * ```
+     *
+     * @example Inherit subscribers from init()
+     * ```typescript
+     * // Uses subscribers configured in init()
+     * const event = new Event('checkout');
+     * event.trackEvent('purchase.completed', { amount: 99.99 });
+     * ```
+     *
+     * @example Override subscribers for this instance
+     * ```typescript
+     * import { Event } from 'autotel/event';
+     * import { PostHogSubscriber } from 'autotel-subscribers/posthog';
+     *
+     * // Override: use different subscribers for this instance only
+     * const event = new Event('checkout', {
+     *   subscribers: [new PostHogSubscriber({ apiKey: 'phc_different_project' })]
+     * });
+     * ```
+     */
+    constructor(serviceName: string, options?: EventsOptions);
+    /**
+     * Automatically enrich attributes with all available telemetry context
+     *
+     * Auto-captures:
+     * - Resource attributes: service.version, deployment.environment
+     * - Trace context: traceId, spanId, correlationId
+     * - Operation context: operation.name
+     */
+    private enrichWithTelemetryContext;
+    /**
+     * Track a business event
+     *
+     * Use this for tracking user actions, business events, product usage:
+     * - "user.signup"
+     * - "order.completed"
+     * - "feature.used"
+     *
+     * Events are sent to configured subscribers (PostHog, Mixpanel, etc.).
+     *
+     * @example
+     * ```typescript
+     * // Track user signup
+     * events.trackEvent('user.signup', {
+     *   userId: '123',
+     *   plan: 'pro'
+     * })
+     *
+     * // Track order
+     * events.trackEvent('order.completed', {
+     *   orderId: 'ord_123',
+     *   amount: 99.99
+     * })
+     * ```
+     */
+    trackEvent(eventName: string, attributes?: EventAttributes): void;
+    /**
+     * Notify all subscribers concurrently without blocking
+     * Uses circuit breakers to protect against failing subscribers
+     * Uses Promise.allSettled to prevent subscriber errors from affecting other subscribers
+     */
+    private notifySubscribers;
+    /**
+     * Track conversion funnel steps
+     *
+     * Monitor where users drop off in multi-step processes.
+     *
+     * @example
+     * ```typescript
+     * // Track signup funnel
+     * events.trackFunnelStep('signup', 'started', { userId: '123' })
+     * events.trackFunnelStep('signup', 'email_verified', { userId: '123' })
+     * events.trackFunnelStep('signup', 'completed', { userId: '123' })
+     *
+     * // Track checkout flow
+     * events.trackFunnelStep('checkout', 'started', { cartValue: 99.99 })
+     * events.trackFunnelStep('checkout', 'payment_info', { cartValue: 99.99 })
+     * events.trackFunnelStep('checkout', 'completed', { cartValue: 99.99 })
+     * ```
+     */
+    trackFunnelStep(funnelName: string, status: FunnelStatus, attributes?: EventAttributes): void;
+    /**
+     * Track outcomes (success/failure/partial)
+     *
+     * Monitor success rates of critical operations.
+     *
+     * @example
+     * ```typescript
+     * // Track email delivery
+     * events.trackOutcome('email.delivery', 'success', {
+     *   recipientType: 'user',
+     *   emailType: 'welcome'
+     * })
+     *
+     * events.trackOutcome('email.delivery', 'failure', {
+     *   recipientType: 'user',
+     *   errorCode: 'invalid_email'
+     * })
+     *
+     * // Track payment processing
+     * events.trackOutcome('payment.process', 'success', { amount: 99.99 })
+     * events.trackOutcome('payment.process', 'failure', { error: 'insufficient_funds' })
+     * ```
+     */
+    trackOutcome(operationName: string, status: OutcomeStatus, attributes?: EventAttributes): void;
+    /**
+     * Track value metrics
+     *
+     * Record numerical values like revenue, transaction amounts,
+     * item counts, processing times, engagement scores, etc.
+     *
+     * @example
+     * ```typescript
+     * // Track revenue
+     * events.trackValue('order.revenue', 149.99, {
+     *   currency: 'USD',
+     *   productCategory: 'electronics'
+     * })
+     *
+     * // Track items per cart
+     * events.trackValue('cart.item_count', 5, {
+     *   userId: '123'
+     * })
+     *
+     * // Track processing time
+     * events.trackValue('api.response_time', 250, {
+     *   unit: 'ms',
+     *   endpoint: '/api/checkout'
+     * })
+     * ```
+     */
+    trackValue(metricName: string, value: number, attributes?: EventAttributes): void;
+    /**
+     * Flush all subscribers and wait for pending events
+     *
+     * Call this before shutdown to ensure all events are delivered.
+     *
+     * @example
+     * ```typescript
+     * const event =new Event('app', { subscribers: [...] });
+     *
+     * // Before shutdown
+     * await events.flush();
+     * ```
+     */
+    flush(): Promise<void>;
+}
+/**
+ * Get or create an Events instance for a service
+ *
+ * @param serviceName - Service name for identifying events
+ * @param logger - Optional logger
+ * @returns Events instance
+ *
+ * @example
+ * ```typescript
+ * const event =getEvents('job-application')
+ * events.trackEvent('application.submitted', { jobId: '123' })
+ * ```
+ */
+declare function getEvents(serviceName: string, logger?: Logger): Event;
+/**
+ * Reset all events instances (mainly for testing)
+ */
+declare function resetEvents(): void;
+
+export { Event, EventAttributes, type EventsOptions, FunnelStatus, OutcomeStatus, getEvents, resetEvents };

package/dist/event.d.ts

@@ -0,0 +1,282 @@
+import { Logger } from './logger.js';
+import { EventSubscriber, EventAttributes, FunnelStatus, OutcomeStatus } from './event-subscriber.js';
+import { EventCollector } from './event-testing.js';
+import 'pino';
+
+/**
+ * Events API for product events platforms
+ *
+ * Track user behavior, business events, and critical actions.
+ * Sends to product events platforms (PostHog, Mixpanel, Amplitude) via subscribers.
+ * For business people who think in events/funnels.
+ *
+ * For OpenTelemetry metrics (Prometheus/Grafana), use the Metrics class instead.
+ *
+ * @example Recommended: Configure subscribers in init(), use track() function
+ * ```typescript
+ * import { init, track } from 'autotel';
+ * import { PostHogSubscriber } from 'autotel-subscribers/posthog';
+ *
+ * init({
+ *   service: 'my-app',
+ *   subscribers: [new PostHogSubscriber({ apiKey: 'phc_...' })]
+ * });
+ *
+ * // Track events - uses subscribers from init()
+ * track('application.submitted', { jobId: '123', userId: '456' });
+ * ```
+ *
+ * @example Create Event instance (inherits subscribers from init)
+ * ```typescript
+ * import { Event } from 'autotel/event';
+ *
+ * // Uses subscribers configured in init()
+ * const event = new Event('job-application');
+ * event.trackEvent('application.submitted', { jobId: '123' });
+ * ```
+ *
+ * @example Override subscribers for specific Event instance
+ * ```typescript
+ * import { Event } from 'autotel/event';
+ * import { PostHogSubscriber } from 'autotel-subscribers/posthog';
+ *
+ * // Override: use different subscribers for this instance
+ * const event = new Event('job-application', {
+ *   subscribers: [new PostHogSubscriber({ apiKey: 'phc_different_project' })]
+ * });
+ *
+ * event.trackEvent('application.submitted', { jobId: '123' });
+ * ```
+ */
+
+/**
+ * Events class for tracking user behavior and product events
+ *
+ * Track critical indicators such as:
+ * - User events (signups, purchases, feature usage)
+ * - Conversion funnels (signup → activation → purchase)
+ * - Business outcomes (success/failure rates)
+ * - Product metrics (revenue, engagement, retention)
+ *
+ * All events are sent to events platforms via subscribers (PostHog, Mixpanel, etc.).
+ * For OpenTelemetry metrics, use the Metrics class instead.
+ */
+/**
+ * Events options
+ */
+interface EventsOptions {
+    /** Optional logger for audit trail */
+    logger?: Logger;
+    /** Optional collector for testing (captures events in memory) */
+    collector?: EventCollector;
+    /**
+     * Optional subscribers to send events to other platforms
+     * (e.g., PostHog, Mixpanel, Amplitude)
+     *
+     * **Subscriber Resolution**:
+     * - If provided → uses these subscribers (instance override)
+     * - If not provided → falls back to subscribers from `init()` (global config)
+     * - If neither → no subscribers (events logged only)
+     *
+     * Install `autotel-subscribers` package for ready-made subscribers
+     */
+    subscribers?: EventSubscriber[];
+}
+declare class Event {
+    private serviceName;
+    private logger?;
+    private collector?;
+    private subscribers;
+    private hasSubscribers;
+    private circuitBreakers;
+    /**
+     * Create a new Event instance
+     *
+     * **Note**: Most users should use `init()` + `track()` instead of creating Event instances directly.
+     *
+     * **Subscriber Resolution**:
+     * - If `subscribers` provided in options → uses those (instance override)
+     * - If `subscribers` not provided → falls back to subscribers from `init()` (global config)
+     * - If neither → no subscribers (events logged only)
+     *
+     * @param serviceName - Service name for identifying events
+     * @param options - Optional configuration (logger, collector, subscribers)
+     *
+     * @example Recommended: Use track() with init()
+     * ```typescript
+     * import { init, track } from 'autotel';
+     * import { PostHogSubscriber } from 'autotel-subscribers/posthog';
+     *
+     * init({
+     *   service: 'checkout',
+     *   subscribers: [new PostHogSubscriber({ apiKey: 'phc_...' })]
+     * });
+     *
+     * track('purchase.completed', { amount: 99.99 });
+     * ```
+     *
+     * @example Inherit subscribers from init()
+     * ```typescript
+     * // Uses subscribers configured in init()
+     * const event = new Event('checkout');
+     * event.trackEvent('purchase.completed', { amount: 99.99 });
+     * ```
+     *
+     * @example Override subscribers for this instance
+     * ```typescript
+     * import { Event } from 'autotel/event';
+     * import { PostHogSubscriber } from 'autotel-subscribers/posthog';
+     *
+     * // Override: use different subscribers for this instance only
+     * const event = new Event('checkout', {
+     *   subscribers: [new PostHogSubscriber({ apiKey: 'phc_different_project' })]
+     * });
+     * ```
+     */
+    constructor(serviceName: string, options?: EventsOptions);
+    /**
+     * Automatically enrich attributes with all available telemetry context
+     *
+     * Auto-captures:
+     * - Resource attributes: service.version, deployment.environment
+     * - Trace context: traceId, spanId, correlationId
+     * - Operation context: operation.name
+     */
+    private enrichWithTelemetryContext;
+    /**
+     * Track a business event
+     *
+     * Use this for tracking user actions, business events, product usage:
+     * - "user.signup"
+     * - "order.completed"
+     * - "feature.used"
+     *
+     * Events are sent to configured subscribers (PostHog, Mixpanel, etc.).
+     *
+     * @example
+     * ```typescript
+     * // Track user signup
+     * events.trackEvent('user.signup', {
+     *   userId: '123',
+     *   plan: 'pro'
+     * })
+     *
+     * // Track order
+     * events.trackEvent('order.completed', {
+     *   orderId: 'ord_123',
+     *   amount: 99.99
+     * })
+     * ```
+     */
+    trackEvent(eventName: string, attributes?: EventAttributes): void;
+    /**
+     * Notify all subscribers concurrently without blocking
+     * Uses circuit breakers to protect against failing subscribers
+     * Uses Promise.allSettled to prevent subscriber errors from affecting other subscribers
+     */
+    private notifySubscribers;
+    /**
+     * Track conversion funnel steps
+     *
+     * Monitor where users drop off in multi-step processes.
+     *
+     * @example
+     * ```typescript
+     * // Track signup funnel
+     * events.trackFunnelStep('signup', 'started', { userId: '123' })
+     * events.trackFunnelStep('signup', 'email_verified', { userId: '123' })
+     * events.trackFunnelStep('signup', 'completed', { userId: '123' })
+     *
+     * // Track checkout flow
+     * events.trackFunnelStep('checkout', 'started', { cartValue: 99.99 })
+     * events.trackFunnelStep('checkout', 'payment_info', { cartValue: 99.99 })
+     * events.trackFunnelStep('checkout', 'completed', { cartValue: 99.99 })
+     * ```
+     */
+    trackFunnelStep(funnelName: string, status: FunnelStatus, attributes?: EventAttributes): void;
+    /**
+     * Track outcomes (success/failure/partial)
+     *
+     * Monitor success rates of critical operations.
+     *
+     * @example
+     * ```typescript
+     * // Track email delivery
+     * events.trackOutcome('email.delivery', 'success', {
+     *   recipientType: 'user',
+     *   emailType: 'welcome'
+     * })
+     *
+     * events.trackOutcome('email.delivery', 'failure', {
+     *   recipientType: 'user',
+     *   errorCode: 'invalid_email'
+     * })
+     *
+     * // Track payment processing
+     * events.trackOutcome('payment.process', 'success', { amount: 99.99 })
+     * events.trackOutcome('payment.process', 'failure', { error: 'insufficient_funds' })
+     * ```
+     */
+    trackOutcome(operationName: string, status: OutcomeStatus, attributes?: EventAttributes): void;
+    /**
+     * Track value metrics
+     *
+     * Record numerical values like revenue, transaction amounts,
+     * item counts, processing times, engagement scores, etc.
+     *
+     * @example
+     * ```typescript
+     * // Track revenue
+     * events.trackValue('order.revenue', 149.99, {
+     *   currency: 'USD',
+     *   productCategory: 'electronics'
+     * })
+     *
+     * // Track items per cart
+     * events.trackValue('cart.item_count', 5, {
+     *   userId: '123'
+     * })
+     *
+     * // Track processing time
+     * events.trackValue('api.response_time', 250, {
+     *   unit: 'ms',
+     *   endpoint: '/api/checkout'
+     * })
+     * ```
+     */
+    trackValue(metricName: string, value: number, attributes?: EventAttributes): void;
+    /**
+     * Flush all subscribers and wait for pending events
+     *
+     * Call this before shutdown to ensure all events are delivered.
+     *
+     * @example
+     * ```typescript
+     * const event =new Event('app', { subscribers: [...] });
+     *
+     * // Before shutdown
+     * await events.flush();
+     * ```
+     */
+    flush(): Promise<void>;
+}
+/**
+ * Get or create an Events instance for a service
+ *
+ * @param serviceName - Service name for identifying events
+ * @param logger - Optional logger
+ * @returns Events instance
+ *
+ * @example
+ * ```typescript
+ * const event =getEvents('job-application')
+ * events.trackEvent('application.submitted', { jobId: '123' })
+ * ```
+ */
+declare function getEvents(serviceName: string, logger?: Logger): Event;
+/**
+ * Reset all events instances (mainly for testing)
+ */
+declare function resetEvents(): void;
+
+export { Event, EventAttributes, type EventsOptions, FunnelStatus, OutcomeStatus, getEvents, resetEvents };

package/dist/event.js

@@ -0,0 +1,13 @@
+export { Event, getEvents, resetEvents } from './chunk-WFJ7L2RV.js';
+import './chunk-LITNXTTT.js';
+import './chunk-BZHG5IZ4.js';
+import './chunk-UL33I6IS.js';
+import './chunk-3HENGDW2.js';
+import './chunk-X4RMFFMR.js';
+import './chunk-5R2M36QB.js';
+import './chunk-5GWX5LFW.js';
+import './chunk-KVGNW3FC.js';
+import './chunk-P6JUDYNO.js';
+import './chunk-Z6ZWNWWR.js';
+//# sourceMappingURL=event.js.map
+//# sourceMappingURL=event.js.map

package/dist/event.js.map

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

package/dist/exporters.cjs

@@ -0,0 +1,17 @@
+'use strict';
+
+require('./chunk-G7VZBCD6.cjs');
+var sdkTraceBase = require('@opentelemetry/sdk-trace-base');
+
+
+
+Object.defineProperty(exports, "ConsoleSpanExporter", {
+  enumerable: true,
+  get: function () { return sdkTraceBase.ConsoleSpanExporter; }
+});
+Object.defineProperty(exports, "InMemorySpanExporter", {
+  enumerable: true,
+  get: function () { return sdkTraceBase.InMemorySpanExporter; }
+});
+//# sourceMappingURL=exporters.cjs.map
+//# sourceMappingURL=exporters.cjs.map

package/dist/exporters.cjs.map

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

package/dist/exporters.d.cts

@@ -0,0 +1 @@
+export { ConsoleSpanExporter, InMemorySpanExporter } from '@opentelemetry/sdk-trace-base';

package/dist/exporters.d.ts

@@ -0,0 +1 @@
+export { ConsoleSpanExporter, InMemorySpanExporter } from '@opentelemetry/sdk-trace-base';

package/dist/exporters.js

@@ -0,0 +1,4 @@
+import './chunk-Z6ZWNWWR.js';
+export { ConsoleSpanExporter, InMemorySpanExporter } from '@opentelemetry/sdk-trace-base';
+//# sourceMappingURL=exporters.js.map
+//# sourceMappingURL=exporters.js.map

package/dist/exporters.js.map

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

package/dist/functional.cjs

@@ -0,0 +1,46 @@
+'use strict';
+
+var chunkWBWNM6LB_cjs = require('./chunk-WBWNM6LB.cjs');
+require('./chunk-TRI4V5BF.cjs');
+require('./chunk-NHCNRQD3.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, "ctx", {
+  enumerable: true,
+  get: function () { return chunkWBWNM6LB_cjs.ctx; }
+});
+Object.defineProperty(exports, "instrument", {
+  enumerable: true,
+  get: function () { return chunkWBWNM6LB_cjs.instrument; }
+});
+Object.defineProperty(exports, "span", {
+  enumerable: true,
+  get: function () { return chunkWBWNM6LB_cjs.span; }
+});
+Object.defineProperty(exports, "trace", {
+  enumerable: true,
+  get: function () { return chunkWBWNM6LB_cjs.trace; }
+});
+Object.defineProperty(exports, "withBaggage", {
+  enumerable: true,
+  get: function () { return chunkWBWNM6LB_cjs.withBaggage; }
+});
+Object.defineProperty(exports, "withNewContext", {
+  enumerable: true,
+  get: function () { return chunkWBWNM6LB_cjs.withNewContext; }
+});
+Object.defineProperty(exports, "withTracing", {
+  enumerable: true,
+  get: function () { return chunkWBWNM6LB_cjs.withTracing; }
+});
+//# sourceMappingURL=functional.cjs.map
+//# sourceMappingURL=functional.cjs.map

package/dist/functional.cjs.map

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