autotel-subscribers 10.0.0 → 11.0.0

package/dist/posthog.d.cts

@@ -1,5 +1,5 @@
 import { EventAttributes } from 'autotel/event-subscriber';
-import { E as EventSubscriber, a as EventPayload } from './event-subscriber-base-CnF3V56W.cjs';
+import { E as EventSubscriber, a as EventPayload } from './event-subscriber-base-uT-C_zrL.cjs';
 import { PostHog } from 'posthog-node';
 
 /**
@@ -90,6 +90,23 @@ import { PostHog } from 'posthog-node';
  * ```
  */
 
+/**
+ * Error context for enhanced error handling
+ *
+ * Provides detailed context about the event that caused an error.
+ */
+interface ErrorContext {
+    /** The error that occurred */
+    error: Error;
+    /** Event name (if applicable) */
+    eventName?: string;
+    /** Event type (event, funnel, outcome, value) */
+    eventType?: 'event' | 'funnel' | 'outcome' | 'value';
+    /** Event attributes (filtered) */
+    attributes?: EventAttributes;
+    /** Subscriber name */
+    subscriberName: string;
+}
 interface PostHogConfig {
     /** PostHog API key (starts with phc_) - required if not providing custom client */
     apiKey?: string;
@@ -99,6 +116,39 @@ interface PostHogConfig {
     enabled?: boolean;
     /** Custom PostHog client instance (bypasses apiKey/host) */
     client?: PostHog;
+    /**
+     * Use global browser client (window.posthog)
+     *
+     * When true, uses the PostHog client already loaded on the page via script tag.
+     * This is useful for Next.js apps that initialize PostHog in _app.tsx.
+     *
+     * @example
+     * ```typescript
+     * // Browser - uses window.posthog
+     * const subscriber = new PostHogSubscriber({
+     *   useGlobalClient: true,
+     * });
+     * ```
+     */
+    useGlobalClient?: boolean;
+    /**
+     * Serverless mode preset (AWS Lambda, Vercel Functions, Next.js API routes)
+     *
+     * When true, auto-configures for serverless environments:
+     * - flushAt: 1 (send immediately, don't batch)
+     * - flushInterval: 0 (disable interval-based flushing)
+     * - requestTimeout: 3000 (shorter timeout for fast responses)
+     *
+     * @example
+     * ```typescript
+     * // Vercel / Next.js API route
+     * const subscriber = new PostHogSubscriber({
+     *   apiKey: 'phc_...',
+     *   serverless: true,
+     * });
+     * ```
+     */
+    serverless?: boolean;
     /** 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) */
@@ -109,8 +159,45 @@ interface PostHogConfig {
     requestTimeout?: number;
     /** Send feature flag evaluation events (default: true) */
     sendFeatureFlags?: boolean;
+    /**
+     * Automatically filter out undefined and null values from attributes
+     *
+     * When true (default), undefined and null values are removed before sending.
+     * This improves DX when passing objects with optional properties.
+     *
+     * @default true
+     *
+     * @example
+     * ```typescript
+     * // With filterUndefinedValues: true (default)
+     * subscriber.trackEvent('user.action', {
+     *   userId: user.id,
+     *   email: user.email,        // might be undefined - will be filtered
+     *   plan: user.subscription,  // might be null - will be filtered
+     * });
+     * ```
+     */
+    filterUndefinedValues?: boolean;
     /** Error callback for debugging and monitoring */
     onError?: (error: Error) => void;
+    /**
+     * Enhanced error callback with event context
+     *
+     * Provides detailed context about the event that caused the error.
+     * If both onError and onErrorWithContext are provided, both are called.
+     *
+     * @example
+     * ```typescript
+     * const subscriber = new PostHogSubscriber({
+     *   apiKey: 'phc_...',
+     *   onErrorWithContext: (ctx) => {
+     *     console.error(`Failed to track ${ctx.eventType}: ${ctx.eventName}`, ctx.error);
+     *     Sentry.captureException(ctx.error, { extra: ctx });
+     *   }
+     * });
+     * ```
+     */
+    onErrorWithContext?: (context: ErrorContext) => void;
     /** Enable debug logging (default: false) */
     debug?: boolean;
 }
@@ -146,6 +233,8 @@ declare class PostHogSubscriber extends EventSubscriber {
     private posthog;
     private config;
     private initPromise;
+    /** True when using browser's window.posthog (different API signature) */
+    private isBrowserClient;
     constructor(config: PostHogConfig);
     private initialize;
     private setupErrorHandling;
@@ -296,4 +385,4 @@ declare class PostHogSubscriber extends EventSubscriber {
     protected handleError(error: Error, payload: EventPayload): void;
 }
 
-export { type FeatureFlagOptions, type PersonProperties, type PostHogConfig, PostHogSubscriber };
+export { type ErrorContext, type FeatureFlagOptions, type PersonProperties, type PostHogConfig, PostHogSubscriber };

package/dist/posthog.d.ts

@@ -1,5 +1,5 @@
 import { EventAttributes } from 'autotel/event-subscriber';
-import { E as EventSubscriber, a as EventPayload } from './event-subscriber-base-CnF3V56W.js';
+import { E as EventSubscriber, a as EventPayload } from './event-subscriber-base-uT-C_zrL.js';
 import { PostHog } from 'posthog-node';
 
 /**
@@ -90,6 +90,23 @@ import { PostHog } from 'posthog-node';
  * ```
  */
 
+/**
+ * Error context for enhanced error handling
+ *
+ * Provides detailed context about the event that caused an error.
+ */
+interface ErrorContext {
+    /** The error that occurred */
+    error: Error;
+    /** Event name (if applicable) */
+    eventName?: string;
+    /** Event type (event, funnel, outcome, value) */
+    eventType?: 'event' | 'funnel' | 'outcome' | 'value';
+    /** Event attributes (filtered) */
+    attributes?: EventAttributes;
+    /** Subscriber name */
+    subscriberName: string;
+}
 interface PostHogConfig {
     /** PostHog API key (starts with phc_) - required if not providing custom client */
     apiKey?: string;
@@ -99,6 +116,39 @@ interface PostHogConfig {
     enabled?: boolean;
     /** Custom PostHog client instance (bypasses apiKey/host) */
     client?: PostHog;
+    /**
+     * Use global browser client (window.posthog)
+     *
+     * When true, uses the PostHog client already loaded on the page via script tag.
+     * This is useful for Next.js apps that initialize PostHog in _app.tsx.
+     *
+     * @example
+     * ```typescript
+     * // Browser - uses window.posthog
+     * const subscriber = new PostHogSubscriber({
+     *   useGlobalClient: true,
+     * });
+     * ```
+     */
+    useGlobalClient?: boolean;
+    /**
+     * Serverless mode preset (AWS Lambda, Vercel Functions, Next.js API routes)
+     *
+     * When true, auto-configures for serverless environments:
+     * - flushAt: 1 (send immediately, don't batch)
+     * - flushInterval: 0 (disable interval-based flushing)
+     * - requestTimeout: 3000 (shorter timeout for fast responses)
+     *
+     * @example
+     * ```typescript
+     * // Vercel / Next.js API route
+     * const subscriber = new PostHogSubscriber({
+     *   apiKey: 'phc_...',
+     *   serverless: true,
+     * });
+     * ```
+     */
+    serverless?: boolean;
     /** 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) */
@@ -109,8 +159,45 @@ interface PostHogConfig {
     requestTimeout?: number;
     /** Send feature flag evaluation events (default: true) */
     sendFeatureFlags?: boolean;
+    /**
+     * Automatically filter out undefined and null values from attributes
+     *
+     * When true (default), undefined and null values are removed before sending.
+     * This improves DX when passing objects with optional properties.
+     *
+     * @default true
+     *
+     * @example
+     * ```typescript
+     * // With filterUndefinedValues: true (default)
+     * subscriber.trackEvent('user.action', {
+     *   userId: user.id,
+     *   email: user.email,        // might be undefined - will be filtered
+     *   plan: user.subscription,  // might be null - will be filtered
+     * });
+     * ```
+     */
+    filterUndefinedValues?: boolean;
     /** Error callback for debugging and monitoring */
     onError?: (error: Error) => void;
+    /**
+     * Enhanced error callback with event context
+     *
+     * Provides detailed context about the event that caused the error.
+     * If both onError and onErrorWithContext are provided, both are called.
+     *
+     * @example
+     * ```typescript
+     * const subscriber = new PostHogSubscriber({
+     *   apiKey: 'phc_...',
+     *   onErrorWithContext: (ctx) => {
+     *     console.error(`Failed to track ${ctx.eventType}: ${ctx.eventName}`, ctx.error);
+     *     Sentry.captureException(ctx.error, { extra: ctx });
+     *   }
+     * });
+     * ```
+     */
+    onErrorWithContext?: (context: ErrorContext) => void;
     /** Enable debug logging (default: false) */
     debug?: boolean;
 }
@@ -146,6 +233,8 @@ declare class PostHogSubscriber extends EventSubscriber {
     private posthog;
     private config;
     private initPromise;
+    /** True when using browser's window.posthog (different API signature) */
+    private isBrowserClient;
     constructor(config: PostHogConfig);
     private initialize;
     private setupErrorHandling;
@@ -296,4 +385,4 @@ declare class PostHogSubscriber extends EventSubscriber {
     protected handleError(error: Error, payload: EventPayload): void;
 }
 
-export { type FeatureFlagOptions, type PersonProperties, type PostHogConfig, PostHogSubscriber };
+export { type ErrorContext, type FeatureFlagOptions, type PersonProperties, type PostHogConfig, PostHogSubscriber };

package/dist/posthog.js

@@ -3682,6 +3682,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
    */
@@ -3739,6 +3768,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
    *
@@ -3799,19 +3853,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();
@@ -3858,19 +3940,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
   /**
@@ -4092,6 +4186,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);
   }
 };