autotel-subscribers 10.0.0 → 11.0.0

package/README.md

@@ -191,12 +191,56 @@ const events = new Event('checkout', {
 });
 
 // Sent to: OpenTelemetry + PostHog
-events.trackEvent('order.completed', { 
-  userId: '123', 
-  amount: 99.99 
+events.trackEvent('order.completed', {
+  userId: '123',
+  amount: 99.99
+});
+```
+
+**Serverless Configuration (AWS Lambda, Vercel, Next.js):**
+
+```typescript
+const subscriber = new PostHogSubscriber({
+  apiKey: 'phc_...',
+  serverless: true,  // Auto-configures for serverless (flushAt: 1, flushInterval: 0)
+});
+```
+
+**Browser Usage (with global PostHog client):**
+
+```typescript
+// When PostHog is already loaded via script tag
+const subscriber = new PostHogSubscriber({
+  useGlobalClient: true,  // Uses window.posthog
+});
+```
+
+**Advanced Options:**
+
+```typescript
+const subscriber = new PostHogSubscriber({
+  apiKey: 'phc_...',
+
+  // Automatic filtering (enabled by default)
+  filterUndefinedValues: true,  // Removes undefined/null from attributes
+
+  // Enhanced error handling
+  onErrorWithContext: (ctx) => {
+    console.error(`${ctx.eventType} failed: ${ctx.eventName}`, ctx.error);
+    Sentry.captureException(ctx.error, { extra: ctx });
+  },
 });
 ```
 
+**Custom Funnel Tracking:**
+
+```typescript
+// Track custom step names (not limited to 'started'/'completed')
+event.trackFunnelProgression('checkout', 'cart_viewed', 1);
+event.trackFunnelProgression('checkout', 'shipping_selected', 2);
+event.trackFunnelProgression('checkout', 'payment_entered', 3);
+```
+
 ### Mixpanel
 
 ```typescript
@@ -357,28 +401,39 @@ All subscribers implement these methods:
 ```typescript
 interface EventSubscriber {
   // Track events
-  trackEvent(name: string, attributes?: Record<string, any>): void;
-  
-  // Track conversion funnels
+  trackEvent(name: string, attributes?: Record<string, any>): Promise<void>;
+
+  // Track conversion funnels (enum-based steps)
   trackFunnelStep(
-    funnelName: string, 
+    funnelName: string,
     step: 'started' | 'completed' | 'abandoned' | 'failed',
     attributes?: Record<string, any>
-  ): void;
-  
+  ): Promise<void>;
+
+  // Track funnel progression (custom step names)
+  trackFunnelProgression?(
+    funnelName: string,
+    stepName: string,         // Any string, not limited to enum
+    stepNumber?: number,      // Optional numeric position
+    attributes?: Record<string, any>
+  ): Promise<void>;
+
   // Track business outcomes
   trackOutcome(
     operationName: string,
     outcome: 'success' | 'failure' | 'partial',
     attributes?: Record<string, any>
-  ): void;
-  
+  ): Promise<void>;
+
   // Track business values (revenue, counts, etc.)
   trackValue(
-    name: string, 
+    name: string,
     value: number,
     attributes?: Record<string, any>
-  ): void;
+  ): Promise<void>;
+
+  // Flush and clean up resources
+  shutdown?(): Promise<void>;
 }
 ```
 

package/dist/{event-subscriber-base-CnF3V56W.d.cts → event-subscriber-base-uT-C_zrL.d.cts}

@@ -1,4 +1,4 @@
-import { EventSubscriber as EventSubscriber$1, EventAttributes, FunnelStatus, OutcomeStatus } from 'autotel/event-subscriber';
+import { EventSubscriber as EventSubscriber$1, EventAttributes, FunnelStatus, OutcomeStatus, EventAttributesInput } from 'autotel/event-subscriber';
 
 /**
  * EventSubscriber - Standard base class for building custom subscribers
@@ -78,8 +78,12 @@ interface EventPayload {
     attributes?: EventAttributes;
     /** For funnel events: funnel name */
     funnel?: string;
-    /** For funnel events: step status */
-    step?: FunnelStatus;
+    /** For funnel events: step status (from FunnelStatus enum) */
+    step?: FunnelStatus | string;
+    /** For funnel events: custom step name (from trackFunnelProgression) */
+    stepName?: string;
+    /** For funnel events: numeric position in funnel */
+    stepNumber?: number;
     /** For outcome events: operation name */
     operation?: string;
     /** For outcome events: outcome status */
@@ -141,6 +145,26 @@ declare abstract class EventSubscriber implements EventSubscriber$1 {
      * @param payload - Event payload that failed
      */
     protected handleError(error: Error, payload: EventPayload): void;
+    /**
+     * Filter out undefined and null values from attributes
+     *
+     * This improves DX by allowing callers to pass objects with optional properties
+     * without having to manually filter them first.
+     *
+     * @param attributes - Input attributes (may contain undefined/null)
+     * @returns Filtered attributes with only defined values, or undefined if empty
+     *
+     * @example
+     * ```typescript
+     * const filtered = this.filterAttributes({
+     *   userId: user.id,
+     *   email: user.email,      // might be undefined
+     *   plan: null,             // will be filtered out
+     * });
+     * // Result: { userId: 'abc', email: 'test@example.com' } or { userId: 'abc' }
+     * ```
+     */
+    protected filterAttributes(attributes?: EventAttributesInput): EventAttributes | undefined;
     /**
      * Track an event
      */
@@ -157,6 +181,18 @@ declare abstract class EventSubscriber implements EventSubscriber$1 {
      * Track a value/metric
      */
     trackValue(name: string, value: number, attributes?: EventAttributes): Promise<void>;
+    /**
+     * Track funnel progression with custom step names
+     *
+     * Unlike trackFunnelStep which uses FunnelStatus enum values,
+     * this method allows any string as the step name for flexible funnel tracking.
+     *
+     * @param funnelName - Name of the funnel (e.g., "checkout", "onboarding")
+     * @param stepName - Custom step name (e.g., "cart_viewed", "payment_entered")
+     * @param stepNumber - Optional numeric position in the funnel
+     * @param attributes - Optional event attributes
+     */
+    trackFunnelProgression(funnelName: string, stepName: string, stepNumber?: number, attributes?: EventAttributes): Promise<void>;
     /**
      * Flush pending requests and clean up
      *

package/dist/{event-subscriber-base-CnF3V56W.d.ts → event-subscriber-base-uT-C_zrL.d.ts}

@@ -1,4 +1,4 @@
-import { EventSubscriber as EventSubscriber$1, EventAttributes, FunnelStatus, OutcomeStatus } from 'autotel/event-subscriber';
+import { EventSubscriber as EventSubscriber$1, EventAttributes, FunnelStatus, OutcomeStatus, EventAttributesInput } from 'autotel/event-subscriber';
 
 /**
  * EventSubscriber - Standard base class for building custom subscribers
@@ -78,8 +78,12 @@ interface EventPayload {
     attributes?: EventAttributes;
     /** For funnel events: funnel name */
     funnel?: string;
-    /** For funnel events: step status */
-    step?: FunnelStatus;
+    /** For funnel events: step status (from FunnelStatus enum) */
+    step?: FunnelStatus | string;
+    /** For funnel events: custom step name (from trackFunnelProgression) */
+    stepName?: string;
+    /** For funnel events: numeric position in funnel */
+    stepNumber?: number;
     /** For outcome events: operation name */
     operation?: string;
     /** For outcome events: outcome status */
@@ -141,6 +145,26 @@ declare abstract class EventSubscriber implements EventSubscriber$1 {
      * @param payload - Event payload that failed
      */
     protected handleError(error: Error, payload: EventPayload): void;
+    /**
+     * Filter out undefined and null values from attributes
+     *
+     * This improves DX by allowing callers to pass objects with optional properties
+     * without having to manually filter them first.
+     *
+     * @param attributes - Input attributes (may contain undefined/null)
+     * @returns Filtered attributes with only defined values, or undefined if empty
+     *
+     * @example
+     * ```typescript
+     * const filtered = this.filterAttributes({
+     *   userId: user.id,
+     *   email: user.email,      // might be undefined
+     *   plan: null,             // will be filtered out
+     * });
+     * // Result: { userId: 'abc', email: 'test@example.com' } or { userId: 'abc' }
+     * ```
+     */
+    protected filterAttributes(attributes?: EventAttributesInput): EventAttributes | undefined;
     /**
      * Track an event
      */
@@ -157,6 +181,18 @@ declare abstract class EventSubscriber implements EventSubscriber$1 {
      * Track a value/metric
      */
     trackValue(name: string, value: number, attributes?: EventAttributes): Promise<void>;
+    /**
+     * Track funnel progression with custom step names
+     *
+     * Unlike trackFunnelStep which uses FunnelStatus enum values,
+     * this method allows any string as the step name for flexible funnel tracking.
+     *
+     * @param funnelName - Name of the funnel (e.g., "checkout", "onboarding")
+     * @param stepName - Custom step name (e.g., "cart_viewed", "payment_entered")
+     * @param stepNumber - Optional numeric position in the funnel
+     * @param attributes - Optional event attributes
+     */
+    trackFunnelProgression(funnelName: string, stepName: string, stepNumber?: number, attributes?: EventAttributes): Promise<void>;
     /**
      * Flush pending requests and clean up
      *

package/dist/factories.cjs

@@ -15425,6 +15425,35 @@ var EventSubscriber = class {
       payload
     );
   }
+  /**
+   * Filter out undefined and null values from attributes
+   *
+   * This improves DX by allowing callers to pass objects with optional properties
+   * without having to manually filter them first.
+   *
+   * @param attributes - Input attributes (may contain undefined/null)
+   * @returns Filtered attributes with only defined values, or undefined if empty
+   *
+   * @example
+   * ```typescript
+   * const filtered = this.filterAttributes({
+   *   userId: user.id,
+   *   email: user.email,      // might be undefined
+   *   plan: null,             // will be filtered out
+   * });
+   * // Result: { userId: 'abc', email: 'test@example.com' } or { userId: 'abc' }
+   * ```
+   */
+  filterAttributes(attributes) {
+    if (!attributes) return void 0;
+    const filtered = {};
+    for (const [key, value] of Object.entries(attributes)) {
+      if (value !== void 0 && value !== null) {
+        filtered[key] = value;
+      }
+    }
+    return Object.keys(filtered).length > 0 ? filtered : void 0;
+  }
   /**
    * Track an event
    */
@@ -15482,6 +15511,31 @@ var EventSubscriber = class {
     };
     await this.send(payload);
   }
+  /**
+   * Track funnel progression with custom step names
+   *
+   * Unlike trackFunnelStep which uses FunnelStatus enum values,
+   * this method allows any string as the step name for flexible funnel tracking.
+   *
+   * @param funnelName - Name of the funnel (e.g., "checkout", "onboarding")
+   * @param stepName - Custom step name (e.g., "cart_viewed", "payment_entered")
+   * @param stepNumber - Optional numeric position in the funnel
+   * @param attributes - Optional event attributes
+   */
+  async trackFunnelProgression(funnelName, stepName, stepNumber, attributes) {
+    if (!this.enabled) return;
+    const payload = {
+      type: "funnel",
+      name: `${funnelName}.${stepName}`,
+      funnel: funnelName,
+      step: stepName,
+      stepName,
+      stepNumber,
+      attributes,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    await this.send(payload);
+  }
   /**
    * Flush pending requests and clean up
    *
@@ -15542,19 +15596,47 @@ var PostHogSubscriber = class extends EventSubscriber {
   posthog = null;
   config;
   initPromise = null;
+  /** True when using browser's window.posthog (different API signature) */
+  isBrowserClient = false;
   constructor(config) {
     super();
-    if (!config.apiKey && !config.client) {
-      throw new Error("PostHogSubscriber requires either apiKey or client to be provided");
+    if (config.serverless) {
+      config = {
+        flushAt: 1,
+        flushInterval: 0,
+        requestTimeout: 3e3,
+        ...config
+        // User config overrides serverless defaults
+      };
+    }
+    if (!config.apiKey && !config.client && !config.useGlobalClient) {
+      throw new Error(
+        "PostHogSubscriber requires either apiKey, client, or useGlobalClient to be provided"
+      );
     }
     this.enabled = config.enabled ?? true;
-    this.config = config;
+    this.config = {
+      filterUndefinedValues: true,
+      ...config
+    };
     if (this.enabled) {
       this.initPromise = this.initialize();
     }
   }
   async initialize() {
     try {
+      if (this.config.useGlobalClient) {
+        const globalWindow = typeof globalThis === "undefined" ? void 0 : globalThis;
+        if (globalWindow?.posthog) {
+          this.posthog = globalWindow.posthog;
+          this.isBrowserClient = true;
+          this.setupErrorHandling();
+          return;
+        }
+        throw new Error(
+          "useGlobalClient enabled but window.posthog not found. Ensure PostHog script is loaded before initializing the subscriber."
+        );
+      }
       if (this.config.client) {
         this.posthog = this.config.client;
         this.setupErrorHandling();
@@ -15601,19 +15683,31 @@ var PostHogSubscriber = class extends EventSubscriber {
    */
   async sendToDestination(payload) {
     await this.ensureInitialized();
-    let properties = payload.attributes;
+    const filteredAttributes = this.config.filterUndefinedValues === false ? payload.attributes : this.filterAttributes(payload.attributes);
+    const properties = { ...filteredAttributes };
     if (payload.value !== void 0) {
-      properties = { ...payload.attributes, value: payload.value };
+      properties.value = payload.value;
     }
-    const capturePayload = {
-      distinctId: this.extractDistinctId(payload.attributes),
-      event: payload.name,
-      properties
-    };
-    if (payload.attributes?.groups) {
-      capturePayload.groups = payload.attributes.groups;
+    if (payload.stepNumber !== void 0) {
+      properties.step_number = payload.stepNumber;
+    }
+    if (payload.stepName !== void 0) {
+      properties.step_name = payload.stepName;
+    }
+    const distinctId = this.extractDistinctId(filteredAttributes);
+    if (this.isBrowserClient) {
+      this.posthog?.capture(payload.name, properties);
+    } else {
+      const capturePayload = {
+        distinctId,
+        event: payload.name,
+        properties
+      };
+      if (filteredAttributes?.groups) {
+        capturePayload.groups = filteredAttributes.groups;
+      }
+      this.posthog?.capture(capturePayload);
     }
-    this.posthog?.capture(capturePayload);
   }
   // Feature Flag Methods
   /**
@@ -15835,6 +15929,15 @@ var PostHogSubscriber = class extends EventSubscriber {
    */
   handleError(error, payload) {
     this.config.onError?.(error);
+    if (this.config.onErrorWithContext) {
+      this.config.onErrorWithContext({
+        error,
+        eventName: payload.name,
+        eventType: payload.type,
+        attributes: payload.attributes,
+        subscriberName: this.name
+      });
+    }
     super.handleError(error, payload);
   }
 };