autotel-subscribers 10.0.0 → 12.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

@@ -4628,7 +4628,7 @@ var require_dist = __commonJS({
     var http3 = __importStar(__require("http"));
     var https_1 = __require("https");
     __exportStar(require_helpers(), exports$1);
-    var INTERNAL2 = Symbol("AgentBaseInternalState");
+    var INTERNAL2 = /* @__PURE__ */ Symbol("AgentBaseInternalState");
     var Agent = class extends http3.Agent {
       constructor(opts) {
         super(opts);
@@ -12287,8 +12287,8 @@ var require_utils3 = __commonJS({
         Object.defineProperty(target, keys[i], Object.getOwnPropertyDescriptor(source, keys[i]));
       }
     };
-    module.exports.wrapperSymbol = Symbol("wrapper");
-    module.exports.implSymbol = Symbol("impl");
+    module.exports.wrapperSymbol = /* @__PURE__ */ Symbol("wrapper");
+    module.exports.implSymbol = /* @__PURE__ */ Symbol("impl");
     module.exports.wrapperForImpl = function(impl) {
       return impl[module.exports.wrapperSymbol];
     };
@@ -12479,7 +12479,7 @@ var require_url_state_machine = __commonJS({
       ws: 80,
       wss: 443
     };
-    var failure = Symbol("failure");
+    var failure = /* @__PURE__ */ Symbol("failure");
     function countSymbols(str) {
       return punycode.ucs2.decode(str).length;
     }
@@ -14492,8 +14492,8 @@ var init_lib = __esm({
   "../../node_modules/.pnpm/node-fetch@2.7.0/node_modules/node-fetch/lib/index.mjs"() {
     import_whatwg_url = __toESM(require_public_api());
     Readable = Stream__default.default.Readable;
-    BUFFER2 = Symbol("buffer");
-    TYPE = Symbol("type");
+    BUFFER2 = /* @__PURE__ */ Symbol("buffer");
+    TYPE = /* @__PURE__ */ Symbol("type");
     Blob2 = class _Blob {
       constructor() {
         this[TYPE] = "";
@@ -14598,7 +14598,7 @@ var init_lib = __esm({
       convert = __require("encoding").convert;
     } catch (e) {
     }
-    INTERNALS = Symbol("Body internals");
+    INTERNALS = /* @__PURE__ */ Symbol("Body internals");
     PassThrough = Stream__default.default.PassThrough;
     Body.prototype = {
       get body() {
@@ -14701,7 +14701,7 @@ var init_lib = __esm({
     Body.Promise = global.Promise;
     invalidTokenRegex = /[^\^_`a-zA-Z\-0-9!#$%&'*+.|~]/;
     invalidHeaderCharRegex = /[^\t\x20-\x7e\x80-\xff]/;
-    MAP = Symbol("map");
+    MAP = /* @__PURE__ */ Symbol("map");
     Headers = class _Headers {
       /**
        * Headers class
@@ -14898,7 +14898,7 @@ var init_lib = __esm({
       values: { enumerable: true },
       entries: { enumerable: true }
     });
-    INTERNAL = Symbol("internal");
+    INTERNAL = /* @__PURE__ */ Symbol("internal");
     HeadersIteratorPrototype = Object.setPrototypeOf({
       next() {
         if (!this || Object.getPrototypeOf(this) !== HeadersIteratorPrototype) {
@@ -14927,7 +14927,7 @@ var init_lib = __esm({
       enumerable: false,
       configurable: true
     });
-    INTERNALS$1 = Symbol("Response internals");
+    INTERNALS$1 = /* @__PURE__ */ Symbol("Response internals");
     STATUS_CODES = http2__namespace.default.STATUS_CODES;
     Response2 = class _Response {
       constructor() {
@@ -15003,7 +15003,7 @@ var init_lib = __esm({
       enumerable: false,
       configurable: true
     });
-    INTERNALS$2 = Symbol("Request internals");
+    INTERNALS$2 = /* @__PURE__ */ Symbol("Request internals");
     URL2 = Url__default.default.URL || import_whatwg_url.default.URL;
     parse_url = Url__default.default.parse;
     format_url = Url__default.default.format;
@@ -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);
   }
 };