autotel-subscribers 10.0.0 → 11.0.0

package/dist/index.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);
   }
 };