autotel-subscribers 4.0.0

package/dist/posthog.d.cts

@@ -0,0 +1,299 @@
+import { EventAttributes } from 'autotel/event-subscriber';
+import { E as EventSubscriber, a as EventPayload } from './event-subscriber-base-CnF3V56W.cjs';
+import { PostHog } from 'posthog-node';
+
+/**
+ * PostHog Subscriber for autotel
+ *
+ * Send events to PostHog for product events, feature flags, and A/B testing.
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { Events } from 'autotel/events';
+ * import { PostHogSubscriber } from 'autotel-subscribers/posthog';
+ *
+ * const events = new Events('checkout', {
+ *   subscribers: [
+ *     new PostHogSubscriber({
+ *       apiKey: process.env.POSTHOG_API_KEY!,
+ *       host: 'https://us.i.posthog.com' // optional, defaults to US cloud
+ *     })
+ *   ]
+ * });
+ *
+ * // Events go to both OpenTelemetry AND PostHog
+ * events.trackEvent('order.completed', { userId: '123', amount: 99.99 });
+ * ```
+ *
+ * @example Feature flags
+ * ```typescript
+ * const subscriber = new PostHogSubscriber({ apiKey: 'phc_...' });
+ *
+ * // Check if feature is enabled
+ * const isEnabled = await subscriber.isFeatureEnabled('new-checkout', 'user-123');
+ *
+ * // Get feature flag value (string, boolean, number)
+ * const variant = await subscriber.getFeatureFlag('experiment-variant', 'user-123');
+ *
+ * // Get all flags for a user
+ * const allFlags = await subscriber.getAllFlags('user-123');
+ * ```
+ *
+ * @example Person and group events
+ * ```typescript
+ * // Identify user and set properties
+ * await subscriber.identify('user-123', {
+ *   email: 'user@example.com',
+ *   plan: 'premium'
+ * });
+ *
+ * // Identify a group (e.g., organization)
+ * await subscriber.groupIdentify('company', 'acme-corp', {
+ *   industry: 'saas',
+ *   employees: 500
+ * });
+ * ```
+ *
+ * @example Serverless configuration
+ * ```typescript
+ * // Optimized for AWS Lambda / Vercel Functions
+ * const subscriber = new PostHogSubscriber({
+ *   apiKey: 'phc_...',
+ *   flushAt: 1,        // Send immediately (don't batch)
+ *   flushInterval: 0,  // Disable interval-based flushing
+ * });
+ * ```
+ *
+ * @example Custom PostHog client
+ * ```typescript
+ * import { PostHog } from 'posthog-node';
+ *
+ * const customClient = new PostHog('phc_...', {
+ *   host: 'https://eu.i.posthog.com',
+ *   // ... other PostHog options
+ * });
+ *
+ * const subscriber = new PostHogSubscriber({
+ *   client: customClient
+ * });
+ * ```
+ *
+ * @example Error handling
+ * ```typescript
+ * const subscriber = new PostHogSubscriber({
+ *   apiKey: 'phc_...',
+ *   onError: (error) => {
+ *     console.error('PostHog error:', error);
+ *     // Send to error tracking service
+ *   }
+ * });
+ * ```
+ */
+
+interface PostHogConfig {
+    /** PostHog API key (starts with phc_) - required if not providing custom client */
+    apiKey?: string;
+    /** PostHog host (defaults to US cloud) */
+    host?: string;
+    /** Enable/disable the subscriber */
+    enabled?: boolean;
+    /** Custom PostHog client instance (bypasses apiKey/host) */
+    client?: PostHog;
+    /** Flush batch when it reaches this size (default: 20, set to 1 for immediate send) */
+    flushAt?: number;
+    /** Flush interval in milliseconds (default: 10000, set to 0 to disable) */
+    flushInterval?: number;
+    /** Disable geoip lookup to reduce request size (default: false) */
+    disableGeoip?: boolean;
+    /** Request timeout in milliseconds (default: 10000) */
+    requestTimeout?: number;
+    /** Send feature flag evaluation events (default: true) */
+    sendFeatureFlags?: boolean;
+    /** Error callback for debugging and monitoring */
+    onError?: (error: Error) => void;
+    /** Enable debug logging (default: false) */
+    debug?: boolean;
+}
+/**
+ * PostHog feature flag options
+ */
+interface FeatureFlagOptions {
+    /** Group context for group-based feature flags */
+    groups?: Record<string, string | number>;
+    /** Group properties for feature flag evaluation */
+    groupProperties?: Record<string, Record<string, any>>;
+    /** Person properties for feature flag evaluation */
+    personProperties?: Record<string, any>;
+    /** Only evaluate locally, don't send $feature_flag_called event */
+    onlyEvaluateLocally?: boolean;
+    /** Send feature flag events even if disabled globally */
+    sendFeatureFlagEvents?: boolean;
+}
+/**
+ * Person properties for identify calls
+ */
+interface PersonProperties {
+    /** Set properties (will update existing values) */
+    $set?: Record<string, any>;
+    /** Set properties only if they don't exist */
+    $set_once?: Record<string, any>;
+    /** Any custom properties */
+    [key: string]: any;
+}
+declare class PostHogSubscriber extends EventSubscriber {
+    readonly name = "PostHogSubscriber";
+    readonly version = "2.0.0";
+    private posthog;
+    private config;
+    private initPromise;
+    constructor(config: PostHogConfig);
+    private initialize;
+    private setupErrorHandling;
+    private ensureInitialized;
+    private extractDistinctId;
+    /**
+     * Send payload to PostHog
+     */
+    protected sendToDestination(payload: EventPayload): Promise<void>;
+    /**
+     * Check if a feature flag is enabled for a user
+     *
+     * @param flagKey - Feature flag key
+     * @param distinctId - User ID or anonymous ID
+     * @param options - Feature flag evaluation options
+     * @returns true if enabled, false otherwise
+     *
+     * @example
+     * ```typescript
+     * const isEnabled = await subscriber.isFeatureEnabled('new-checkout', 'user-123');
+     *
+     * // With groups
+     * const isEnabled = await subscriber.isFeatureEnabled('beta-features', 'user-123', {
+     *   groups: { company: 'acme-corp' }
+     * });
+     * ```
+     */
+    isFeatureEnabled(flagKey: string, distinctId: string, options?: FeatureFlagOptions): Promise<boolean>;
+    /**
+     * Get feature flag value for a user
+     *
+     * @param flagKey - Feature flag key
+     * @param distinctId - User ID or anonymous ID
+     * @param options - Feature flag evaluation options
+     * @returns Flag value (string, boolean, or undefined)
+     *
+     * @example
+     * ```typescript
+     * const variant = await subscriber.getFeatureFlag('experiment-variant', 'user-123');
+     * // Returns: 'control' | 'test' | 'test-2' | undefined
+     *
+     * // With person properties
+     * const variant = await subscriber.getFeatureFlag('premium-feature', 'user-123', {
+     *   personProperties: { plan: 'premium' }
+     * });
+     * ```
+     */
+    getFeatureFlag(flagKey: string, distinctId: string, options?: FeatureFlagOptions): Promise<string | boolean | undefined>;
+    /**
+     * Get all feature flags for a user
+     *
+     * @param distinctId - User ID or anonymous ID
+     * @param options - Feature flag evaluation options
+     * @returns Object mapping flag keys to their values
+     *
+     * @example
+     * ```typescript
+     * const flags = await subscriber.getAllFlags('user-123');
+     * // Returns: { 'new-checkout': true, 'experiment-variant': 'test', ... }
+     * ```
+     */
+    getAllFlags(distinctId: string, options?: FeatureFlagOptions): Promise<Record<string, string | number | boolean>>;
+    /**
+     * Reload feature flags from PostHog server
+     *
+     * Call this to refresh feature flag definitions without restarting.
+     *
+     * @example
+     * ```typescript
+     * await subscriber.reloadFeatureFlags();
+     * ```
+     */
+    reloadFeatureFlags(): Promise<void>;
+    /**
+     * Identify a user and set their properties
+     *
+     * @param distinctId - User ID
+     * @param properties - Person properties ($set, $set_once, or custom properties)
+     *
+     * @example
+     * ```typescript
+     * // Set properties (will update existing values)
+     * await subscriber.identify('user-123', {
+     *   $set: {
+     *     email: 'user@example.com',
+     *     plan: 'premium'
+     *   }
+     * });
+     *
+     * // Set properties only once (won't update if already exists)
+     * await subscriber.identify('user-123', {
+     *   $set_once: {
+     *     signup_date: '2025-01-17'
+     *   }
+     * });
+     * ```
+     */
+    identify(distinctId: string, properties?: PersonProperties): Promise<void>;
+    /**
+     * Identify a group and set its properties
+     *
+     * Groups are useful for B2B SaaS to track organizations, teams, or accounts.
+     *
+     * @param groupType - Type of group (e.g., 'company', 'organization', 'team')
+     * @param groupKey - Unique identifier for the group
+     * @param properties - Group properties
+     *
+     * @example
+     * ```typescript
+     * await subscriber.groupIdentify('company', 'acme-corp', {
+     *   $set: {
+     *     name: 'Acme Corporation',
+     *     industry: 'saas',
+     *     employees: 500,
+     *     plan: 'enterprise'
+     *   }
+     * });
+     * ```
+     */
+    groupIdentify(groupType: string, groupKey: string | number, properties?: Record<string, any>): Promise<void>;
+    /**
+     * Track an event with group context
+     *
+     * Use this to associate events with groups (e.g., organizations).
+     *
+     * @param name - Event name
+     * @param attributes - Event attributes
+     * @param groups - Group context (e.g., { company: 'acme-corp' })
+     *
+     * @example
+     * ```typescript
+     * await subscriber.trackEventWithGroups('feature.used', {
+     *   userId: 'user-123',
+     *   feature: 'advanced-events'
+     * }, {
+     *   company: 'acme-corp'
+     * });
+     * ```
+     */
+    trackEventWithGroups(name: string, attributes?: EventAttributes, groups?: Record<string, string | number>): Promise<void>;
+    /**
+     * Flush pending events and clean up resources
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Handle errors with custom error handler
+     */
+    protected handleError(error: Error, payload: EventPayload): void;
+}
+
+export { type FeatureFlagOptions, type PersonProperties, type PostHogConfig, PostHogSubscriber };

package/dist/posthog.d.ts

@@ -0,0 +1,299 @@
+import { EventAttributes } from 'autotel/event-subscriber';
+import { E as EventSubscriber, a as EventPayload } from './event-subscriber-base-CnF3V56W.js';
+import { PostHog } from 'posthog-node';
+
+/**
+ * PostHog Subscriber for autotel
+ *
+ * Send events to PostHog for product events, feature flags, and A/B testing.
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { Events } from 'autotel/events';
+ * import { PostHogSubscriber } from 'autotel-subscribers/posthog';
+ *
+ * const events = new Events('checkout', {
+ *   subscribers: [
+ *     new PostHogSubscriber({
+ *       apiKey: process.env.POSTHOG_API_KEY!,
+ *       host: 'https://us.i.posthog.com' // optional, defaults to US cloud
+ *     })
+ *   ]
+ * });
+ *
+ * // Events go to both OpenTelemetry AND PostHog
+ * events.trackEvent('order.completed', { userId: '123', amount: 99.99 });
+ * ```
+ *
+ * @example Feature flags
+ * ```typescript
+ * const subscriber = new PostHogSubscriber({ apiKey: 'phc_...' });
+ *
+ * // Check if feature is enabled
+ * const isEnabled = await subscriber.isFeatureEnabled('new-checkout', 'user-123');
+ *
+ * // Get feature flag value (string, boolean, number)
+ * const variant = await subscriber.getFeatureFlag('experiment-variant', 'user-123');
+ *
+ * // Get all flags for a user
+ * const allFlags = await subscriber.getAllFlags('user-123');
+ * ```
+ *
+ * @example Person and group events
+ * ```typescript
+ * // Identify user and set properties
+ * await subscriber.identify('user-123', {
+ *   email: 'user@example.com',
+ *   plan: 'premium'
+ * });
+ *
+ * // Identify a group (e.g., organization)
+ * await subscriber.groupIdentify('company', 'acme-corp', {
+ *   industry: 'saas',
+ *   employees: 500
+ * });
+ * ```
+ *
+ * @example Serverless configuration
+ * ```typescript
+ * // Optimized for AWS Lambda / Vercel Functions
+ * const subscriber = new PostHogSubscriber({
+ *   apiKey: 'phc_...',
+ *   flushAt: 1,        // Send immediately (don't batch)
+ *   flushInterval: 0,  // Disable interval-based flushing
+ * });
+ * ```
+ *
+ * @example Custom PostHog client
+ * ```typescript
+ * import { PostHog } from 'posthog-node';
+ *
+ * const customClient = new PostHog('phc_...', {
+ *   host: 'https://eu.i.posthog.com',
+ *   // ... other PostHog options
+ * });
+ *
+ * const subscriber = new PostHogSubscriber({
+ *   client: customClient
+ * });
+ * ```
+ *
+ * @example Error handling
+ * ```typescript
+ * const subscriber = new PostHogSubscriber({
+ *   apiKey: 'phc_...',
+ *   onError: (error) => {
+ *     console.error('PostHog error:', error);
+ *     // Send to error tracking service
+ *   }
+ * });
+ * ```
+ */
+
+interface PostHogConfig {
+    /** PostHog API key (starts with phc_) - required if not providing custom client */
+    apiKey?: string;
+    /** PostHog host (defaults to US cloud) */
+    host?: string;
+    /** Enable/disable the subscriber */
+    enabled?: boolean;
+    /** Custom PostHog client instance (bypasses apiKey/host) */
+    client?: PostHog;
+    /** Flush batch when it reaches this size (default: 20, set to 1 for immediate send) */
+    flushAt?: number;
+    /** Flush interval in milliseconds (default: 10000, set to 0 to disable) */
+    flushInterval?: number;
+    /** Disable geoip lookup to reduce request size (default: false) */
+    disableGeoip?: boolean;
+    /** Request timeout in milliseconds (default: 10000) */
+    requestTimeout?: number;
+    /** Send feature flag evaluation events (default: true) */
+    sendFeatureFlags?: boolean;
+    /** Error callback for debugging and monitoring */
+    onError?: (error: Error) => void;
+    /** Enable debug logging (default: false) */
+    debug?: boolean;
+}
+/**
+ * PostHog feature flag options
+ */
+interface FeatureFlagOptions {
+    /** Group context for group-based feature flags */
+    groups?: Record<string, string | number>;
+    /** Group properties for feature flag evaluation */
+    groupProperties?: Record<string, Record<string, any>>;
+    /** Person properties for feature flag evaluation */
+    personProperties?: Record<string, any>;
+    /** Only evaluate locally, don't send $feature_flag_called event */
+    onlyEvaluateLocally?: boolean;
+    /** Send feature flag events even if disabled globally */
+    sendFeatureFlagEvents?: boolean;
+}
+/**
+ * Person properties for identify calls
+ */
+interface PersonProperties {
+    /** Set properties (will update existing values) */
+    $set?: Record<string, any>;
+    /** Set properties only if they don't exist */
+    $set_once?: Record<string, any>;
+    /** Any custom properties */
+    [key: string]: any;
+}
+declare class PostHogSubscriber extends EventSubscriber {
+    readonly name = "PostHogSubscriber";
+    readonly version = "2.0.0";
+    private posthog;
+    private config;
+    private initPromise;
+    constructor(config: PostHogConfig);
+    private initialize;
+    private setupErrorHandling;
+    private ensureInitialized;
+    private extractDistinctId;
+    /**
+     * Send payload to PostHog
+     */
+    protected sendToDestination(payload: EventPayload): Promise<void>;
+    /**
+     * Check if a feature flag is enabled for a user
+     *
+     * @param flagKey - Feature flag key
+     * @param distinctId - User ID or anonymous ID
+     * @param options - Feature flag evaluation options
+     * @returns true if enabled, false otherwise
+     *
+     * @example
+     * ```typescript
+     * const isEnabled = await subscriber.isFeatureEnabled('new-checkout', 'user-123');
+     *
+     * // With groups
+     * const isEnabled = await subscriber.isFeatureEnabled('beta-features', 'user-123', {
+     *   groups: { company: 'acme-corp' }
+     * });
+     * ```
+     */
+    isFeatureEnabled(flagKey: string, distinctId: string, options?: FeatureFlagOptions): Promise<boolean>;
+    /**
+     * Get feature flag value for a user
+     *
+     * @param flagKey - Feature flag key
+     * @param distinctId - User ID or anonymous ID
+     * @param options - Feature flag evaluation options
+     * @returns Flag value (string, boolean, or undefined)
+     *
+     * @example
+     * ```typescript
+     * const variant = await subscriber.getFeatureFlag('experiment-variant', 'user-123');
+     * // Returns: 'control' | 'test' | 'test-2' | undefined
+     *
+     * // With person properties
+     * const variant = await subscriber.getFeatureFlag('premium-feature', 'user-123', {
+     *   personProperties: { plan: 'premium' }
+     * });
+     * ```
+     */
+    getFeatureFlag(flagKey: string, distinctId: string, options?: FeatureFlagOptions): Promise<string | boolean | undefined>;
+    /**
+     * Get all feature flags for a user
+     *
+     * @param distinctId - User ID or anonymous ID
+     * @param options - Feature flag evaluation options
+     * @returns Object mapping flag keys to their values
+     *
+     * @example
+     * ```typescript
+     * const flags = await subscriber.getAllFlags('user-123');
+     * // Returns: { 'new-checkout': true, 'experiment-variant': 'test', ... }
+     * ```
+     */
+    getAllFlags(distinctId: string, options?: FeatureFlagOptions): Promise<Record<string, string | number | boolean>>;
+    /**
+     * Reload feature flags from PostHog server
+     *
+     * Call this to refresh feature flag definitions without restarting.
+     *
+     * @example
+     * ```typescript
+     * await subscriber.reloadFeatureFlags();
+     * ```
+     */
+    reloadFeatureFlags(): Promise<void>;
+    /**
+     * Identify a user and set their properties
+     *
+     * @param distinctId - User ID
+     * @param properties - Person properties ($set, $set_once, or custom properties)
+     *
+     * @example
+     * ```typescript
+     * // Set properties (will update existing values)
+     * await subscriber.identify('user-123', {
+     *   $set: {
+     *     email: 'user@example.com',
+     *     plan: 'premium'
+     *   }
+     * });
+     *
+     * // Set properties only once (won't update if already exists)
+     * await subscriber.identify('user-123', {
+     *   $set_once: {
+     *     signup_date: '2025-01-17'
+     *   }
+     * });
+     * ```
+     */
+    identify(distinctId: string, properties?: PersonProperties): Promise<void>;
+    /**
+     * Identify a group and set its properties
+     *
+     * Groups are useful for B2B SaaS to track organizations, teams, or accounts.
+     *
+     * @param groupType - Type of group (e.g., 'company', 'organization', 'team')
+     * @param groupKey - Unique identifier for the group
+     * @param properties - Group properties
+     *
+     * @example
+     * ```typescript
+     * await subscriber.groupIdentify('company', 'acme-corp', {
+     *   $set: {
+     *     name: 'Acme Corporation',
+     *     industry: 'saas',
+     *     employees: 500,
+     *     plan: 'enterprise'
+     *   }
+     * });
+     * ```
+     */
+    groupIdentify(groupType: string, groupKey: string | number, properties?: Record<string, any>): Promise<void>;
+    /**
+     * Track an event with group context
+     *
+     * Use this to associate events with groups (e.g., organizations).
+     *
+     * @param name - Event name
+     * @param attributes - Event attributes
+     * @param groups - Group context (e.g., { company: 'acme-corp' })
+     *
+     * @example
+     * ```typescript
+     * await subscriber.trackEventWithGroups('feature.used', {
+     *   userId: 'user-123',
+     *   feature: 'advanced-events'
+     * }, {
+     *   company: 'acme-corp'
+     * });
+     * ```
+     */
+    trackEventWithGroups(name: string, attributes?: EventAttributes, groups?: Record<string, string | number>): Promise<void>;
+    /**
+     * Flush pending events and clean up resources
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Handle errors with custom error handler
+     */
+    protected handleError(error: Error, payload: EventPayload): void;
+}
+
+export { type FeatureFlagOptions, type PersonProperties, type PostHogConfig, PostHogSubscriber };