@dereekb/dbx-analytics 13.3.0 → 13.4.0

package/fesm2022/dereekb-dbx-analytics.mjs

@@ -7,38 +7,105 @@ import { safeCompareEquality, poll } from '@dereekb/util';
 import { toObservable } from '@angular/core/rxjs-interop';
 import { AbstractAsyncWindowLoadedService } from '@dereekb/browser';
 
+/**
+ * Categorizes the kind of analytics stream event emitted by {@link DbxAnalyticsService}.
+ *
+ * Listeners use this type to route events to the appropriate analytics provider method
+ * (e.g., Segment `track()`, `identify()`, `page()`).
+ */
 var DbxAnalyticsStreamEventType;
 (function (DbxAnalyticsStreamEventType) {
+    /** A page/screen view event, typically sent on route transitions. */
     DbxAnalyticsStreamEventType[DbxAnalyticsStreamEventType["PageView"] = 0] = "PageView";
     /**
-     * Emitted any time the user value changes.
+     * Emitted any time the user value changes, including when transitioning from defined to undefined.
      *
-     * Can emit when the user goes from defined to undefined.
+     * Used by listeners to update the identified user in analytics providers.
      */
     DbxAnalyticsStreamEventType[DbxAnalyticsStreamEventType["UserChange"] = 1] = "UserChange";
     /**
-     * Emitted any time the user id changes.
+     * Emitted only when the user's unique ID changes, filtering out property-only updates.
+     *
+     * Useful for triggering identity calls without redundant updates when only traits change.
      */
     DbxAnalyticsStreamEventType[DbxAnalyticsStreamEventType["UserIdChange"] = 2] = "UserIdChange";
     // User Events
+    /** A new user registration event. */
     DbxAnalyticsStreamEventType[DbxAnalyticsStreamEventType["NewUserEvent"] = 3] = "NewUserEvent";
+    /** A returning user login event. */
     DbxAnalyticsStreamEventType[DbxAnalyticsStreamEventType["UserLoginEvent"] = 4] = "UserLoginEvent";
+    /** A user logout event. */
     DbxAnalyticsStreamEventType[DbxAnalyticsStreamEventType["UserLogoutEvent"] = 5] = "UserLogoutEvent";
+    /** An update to user profile properties/traits. */
     DbxAnalyticsStreamEventType[DbxAnalyticsStreamEventType["UserPropertiesEvent"] = 6] = "UserPropertiesEvent";
     // Events
+    /** A generic custom analytics event. */
     DbxAnalyticsStreamEventType[DbxAnalyticsStreamEventType["Event"] = 7] = "Event";
 })(DbxAnalyticsStreamEventType || (DbxAnalyticsStreamEventType = {}));
 
+/**
+ * Abstract emitter interface for sending analytics events.
+ *
+ * Implemented by {@link DbxAnalyticsService} as the primary concrete implementation.
+ * Components and services use this to fire analytics events without coupling to a specific provider.
+ *
+ * @example
+ * ```ts
+ * // Inject and send a custom event
+ * const emitter = inject(DbxAnalyticsEventEmitterService);
+ * emitter.sendEventData('Button Clicked', { buttonId: 'save' });
+ * ```
+ */
 class DbxAnalyticsEventEmitterService {
 }
+/**
+ * Abstract interface exposing the analytics event stream as an observable.
+ *
+ * Implemented by {@link DbxAnalyticsService}. Listeners subscribe to `events$` to forward events to external providers.
+ */
 class DbxAnalyticsEventStreamService {
 }
+/**
+ * Abstract source for the current analytics user identity.
+ *
+ * Provide an implementation to automatically associate a user with all emitted analytics events.
+ * Typically backed by the auth system (e.g., {@link DbxFirebaseAnalyticsUserSource}).
+ *
+ * @example
+ * ```ts
+ * // Provide a static user source
+ * const userSource: DbxAnalyticsUserSource = {
+ *   analyticsUser$: of({ user: 'uid_abc123', properties: { role: 'admin' } })
+ * };
+ * ```
+ */
 class DbxAnalyticsUserSource {
 }
+/**
+ * Abstract listener that receives analytics events from {@link DbxAnalyticsService}.
+ *
+ * Implement this to forward events to an external analytics provider (e.g., Segment, Mixpanel).
+ * Register listeners via {@link DbxAnalyticsServiceConfiguration.listeners}.
+ */
 class DbxAnalyticsServiceListener {
 }
 /**
- * Abstract AnalyticsServiceListener implementation.
+ * Base class for analytics service listeners that manages subscription lifecycle and provides
+ * reactive access to the analytics service and its event stream.
+ *
+ * Subclasses implement {@link _initializeServiceSubscription} to subscribe to events and forward them
+ * to an external analytics provider.
+ *
+ * @example
+ * ```ts
+ * class MyAnalyticsListener extends AbstractDbxAnalyticsServiceListener {
+ *   protected _initializeServiceSubscription(): Subscription | false {
+ *     return this.analyticsEvents$.subscribe((event) => {
+ *       console.log('Event:', event.type, event.event?.name);
+ *     });
+ *   }
+ * }
+ * ```
  */
 class AbstractDbxAnalyticsServiceListener {
     _sub = new SubscriptionObject();
@@ -59,12 +126,46 @@ class AbstractDbxAnalyticsServiceListener {
         this._sub.destroy();
     }
 }
+/**
+ * Configuration for {@link DbxAnalyticsService}, controlling which listeners receive events,
+ * whether analytics runs in production mode, and optionally providing a user source.
+ *
+ * In non-production mode, listeners are not initialized and all events are logged to the console instead.
+ * Provide via {@link provideDbxAnalyticsService} using a factory function.
+ *
+ * @example
+ * ```ts
+ * const config: DbxAnalyticsServiceConfiguration = {
+ *   isProduction: environment.production,
+ *   logEvents: !environment.production,
+ *   listeners: [segmentListener],
+ *   userSource: firebaseAnalyticsUserSource
+ * };
+ * ```
+ */
 class DbxAnalyticsServiceConfiguration {
     listeners = [];
     isProduction;
     logEvents;
     userSource;
 }
+/**
+ * Wraps a {@link UserAnalyticsEvent} into a {@link DbxAnalyticsStreamEventAnalyticsEventWrapper},
+ * extracting the user ID for convenient access by listeners.
+ *
+ * @param event - the analytics event with optional user context
+ * @param type - the stream event type classification; defaults to `Event`
+ * @returns a wrapper combining the event, type, user, and extracted userId
+ *
+ * @example
+ * ```ts
+ * const wrapper = dbxAnalyticsStreamEventAnalyticsEventWrapper(
+ *   { name: 'Button Clicked', user: { user: 'uid_123' } },
+ *   DbxAnalyticsStreamEventType.Event
+ * );
+ * // wrapper.userId === 'uid_123'
+ * ```
+ */
 function dbxAnalyticsStreamEventAnalyticsEventWrapper(event, type = DbxAnalyticsStreamEventType.Event) {
     const { user } = event;
     const userId = user ? user.user : undefined;
@@ -76,7 +177,27 @@ function dbxAnalyticsStreamEventAnalyticsEventWrapper(event, type = DbxAnalytics
     };
 }
 /**
- * Primary analytics service that emits analytics events that components can listen to.
+ * Central analytics service that emits typed analytics events for consumption by registered listeners.
+ *
+ * Acts as both the event emitter (components call methods like {@link sendEventData}, {@link sendPageView})
+ * and the event stream source (listeners subscribe to {@link events$}).
+ *
+ * In production mode, registered {@link DbxAnalyticsServiceListener} instances (e.g., Segment) receive all events.
+ * In non-production mode, events are logged to the console for debugging.
+ *
+ * Provided via {@link provideDbxAnalyticsService} with a {@link DbxAnalyticsServiceConfiguration} factory.
+ *
+ * @example
+ * ```ts
+ * // Send a custom event from a component
+ * const analytics = inject(DbxAnalyticsService);
+ * analytics.sendEventData('Interview Started', { candidateId: 'abc123' });
+ *
+ * // Send a page view on route transitions
+ * transitionService.onSuccess({}, () => {
+ *   analytics.sendPageView();
+ * });
+ * ```
  */
 class DbxAnalyticsService {
     _config = inject(DbxAnalyticsServiceConfiguration);
@@ -102,7 +223,11 @@ class DbxAnalyticsService {
     }
     // MARK: Source
     /**
-     * Sets the user directly, overridding the UserSource.
+     * Sets the analytics user directly, overriding any configured {@link DbxAnalyticsUserSource}.
+     *
+     * Pass `undefined` to clear the current user (e.g., on logout).
+     *
+     * @param user - the user to identify, or undefined to clear
      */
     setUser(user) {
         let source;
@@ -114,12 +239,20 @@ class DbxAnalyticsService {
             console.warn('DbxAnalyticsService has a userSource that is set. Source is now overridden by setUser() value.');
         }
     }
+    /**
+     * Sets the reactive user source that automatically updates the analytics user as auth state changes.
+     *
+     * @param source - the user source providing an observable of the current analytics user
+     */
     setUserSource(source) {
         this._userSource.next(source);
     }
-    // MARK: AnalyticsEventEmitterService
+    // MARK: DbxAnalyticsEventEmitterService
     /**
-     * Sends an event.
+     * Emits a new user registration event, typically sent once after account creation.
+     *
+     * @param user - the newly registered user
+     * @param data - registration-specific data including the signup method
      */
     sendNewUserEvent(user, data) {
         this.sendNextEvent({
@@ -127,12 +260,24 @@ class DbxAnalyticsService {
             data
         }, DbxAnalyticsStreamEventType.NewUserEvent, user);
     }
+    /**
+     * Emits a user login event, identifying the user in analytics providers.
+     *
+     * @param user - the user who logged in
+     * @param data - optional additional event data
+     */
     sendUserLoginEvent(user, data) {
         this.sendNextEvent({
             name: DbxAnalyticsService.USER_LOGIN_EVENT_NAME,
             data
         }, DbxAnalyticsStreamEventType.UserLoginEvent, user);
     }
+    /**
+     * Emits a user logout event and optionally clears the current analytics user.
+     *
+     * @param data - optional additional event data
+     * @param clearUser - whether to reset the analytics user identity; defaults to `true`
+     */
     sendUserLogoutEvent(data, clearUser = true) {
         this.sendNextEvent({
             name: DbxAnalyticsService.USER_LOGOUT_EVENT_NAME,
@@ -142,6 +287,12 @@ class DbxAnalyticsService {
             this.setUser(undefined);
         }
     }
+    /**
+     * Emits a user properties update event, used to sync user traits to analytics providers.
+     *
+     * @param user - the user whose properties are being updated
+     * @param data - optional additional event data
+     */
     sendUserPropertiesEvent(user, data) {
         this.sendNextEvent({
             name: DbxAnalyticsService.USER_PROPERTIES_EVENT_NAME,
@@ -154,14 +305,42 @@ class DbxAnalyticsService {
             data
         });
     }
+    /**
+     * Sends a named event with no additional data, useful for simple occurrence tracking.
+     *
+     * @param eventType - the event name to track
+     *
+     * @example
+     * ```ts
+     * analytics.sendEventType('Finish Account Setup');
+     * ```
+     */
     sendEventType(eventType) {
         this.sendNextEvent({
             name: eventType
         }, DbxAnalyticsStreamEventType.Event);
     }
+    /**
+     * Sends a fully constructed analytics event object.
+     *
+     * @param event - the event containing name, optional value, and data
+     */
     sendEvent(event) {
         this.sendNextEvent(event, DbxAnalyticsStreamEventType.Event);
     }
+    /**
+     * Sends a page view event, typically called on successful route transitions.
+     *
+     * @param page - optional page name/path override; if omitted, the provider determines the current page
+     *
+     * @example
+     * ```ts
+     * // In a router config function
+     * transitionService.onSuccess({}, () => {
+     *   analyticsService.sendPageView();
+     * });
+     * ```
+     */
     sendPageView(page) {
         this.sendNextEvent({
             name: page
@@ -225,7 +404,20 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.0", ngImpor
         }], ctorParameters: () => [] });
 
 /**
- * Used to listen to an ActionContext and send analytical events based on action events.
+ * Standalone directive that listens to a host {@link DbxActionDirective} and fires analytics events
+ * based on the action's lifecycle (triggered, ready, success, error).
+ *
+ * Attach to any element that has a `dbxAction` directive and pass a {@link DbxActionAnalyticsConfig}
+ * to define which events to send at each lifecycle stage.
+ *
+ * @example
+ * ```html
+ * <button dbxAction
+ *   [dbxActionHandler]="handleSave"
+ *   [dbxActionAnalytics]="saveAnalytics">
+ *   Save
+ * </button>
+ * ```
  */
 class DbxActionAnalyticsDirective {
     source = inject((DbxActionContextStoreSourceInstance), { host: true });
@@ -288,10 +480,30 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.0", ngImpor
         }] });
 
 /**
- * Creates a EnvironmentProviders that provides a DbxAnalyticsService.
+ * Creates Angular environment providers that register {@link DbxAnalyticsService} and its configuration.
+ *
+ * Call this in your application's `providers` array to set up analytics with a custom configuration factory
+ * that resolves listeners, user sources, and environment flags at runtime.
  *
- * @param config Configuration
- * @returns EnvironmentProviders
+ * @param config - contains the factory function that produces a {@link DbxAnalyticsServiceConfiguration}
+ * @returns environment providers for the analytics service
+ *
+ * @example
+ * ```ts
+ * // In app.config.ts
+ * export const appConfig: ApplicationConfig = {
+ *   providers: [
+ *     provideDbxAnalyticsService({
+ *       dbxAnalyticsServiceConfigurationFactory: (injector: Injector) => ({
+ *         isProduction: environment.production,
+ *         logEvents: !environment.production,
+ *         listeners: [injector.get(DbxAnalyticsSegmentServiceListener)],
+ *         userSource: injector.get(DbxFirebaseAnalyticsUserSource)
+ *       })
+ *     })
+ *   ]
+ * };
+ * ```
  */
 function provideDbxAnalyticsService(config) {
     const { dbxAnalyticsServiceConfigurationFactory } = config;
@@ -308,7 +520,20 @@ function provideDbxAnalyticsService(config) {
     return makeEnvironmentProviders(providers);
 }
 
+/**
+ * Injection token for optionally preloading the Segment analytics script.
+ */
 const PRELOAD_SEGMENT_TOKEN = new InjectionToken('DbxAnalyticsSegmentApiServicePreload');
+/**
+ * Configuration for the Segment analytics integration.
+ *
+ * @example
+ * ```ts
+ * const config = new DbxAnalyticsSegmentApiServiceConfig('your-segment-write-key');
+ * config.active = environment.production;
+ * config.logging = !environment.production;
+ * ```
+ */
 class DbxAnalyticsSegmentApiServiceConfig {
     writeKey;
     logging = true;
@@ -318,9 +543,26 @@ class DbxAnalyticsSegmentApiServiceConfig {
     }
 }
 /**
- * Segment API Service used for waiting/retrieving the segment API from window when initialized.
+ * Service that manages the async loading and initialization of the Segment analytics SDK from `window.analytics`.
+ *
+ * Polls for the Segment snippet to be invoked, then calls `analytics.load()` with the configured write key.
+ * Once Segment reports ready, the resolved SDK instance is available via the inherited `service$` observable.
+ *
+ * Requires the Segment analytics snippet to be included in `index.html`.
  *
- * This requires some setup in index.html.
+ * Provided via {@link provideDbxAnalyticsSegmentApiService}.
+ *
+ * @example
+ * ```ts
+ * // In app.config.ts
+ * provideDbxAnalyticsSegmentApiService({
+ *   dbxAnalyticsSegmentApiServiceConfigFactory: (injector) => {
+ *     const config = new DbxAnalyticsSegmentApiServiceConfig(environment.analytics.segment);
+ *     config.active = environment.production;
+ *     return config;
+ *   }
+ * })
+ * ```
  */
 class DbxAnalyticsSegmentApiService extends AbstractAsyncWindowLoadedService {
     _config = inject(DbxAnalyticsSegmentApiServiceConfig);
@@ -365,7 +607,28 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.0", ngImpor
         }], ctorParameters: () => [] });
 
 /**
- * DbxAnalyticsServiceListener adapter for Segment.
+ * Analytics listener that forwards {@link DbxAnalyticsStreamEvent} events to the Segment SDK.
+ *
+ * Automatically maps event types to the appropriate Segment methods:
+ * - {@link DbxAnalyticsStreamEventType.Event} / {@link DbxAnalyticsStreamEventType.UserLoginEvent} -> `track()`
+ * - {@link DbxAnalyticsStreamEventType.UserChange} / {@link DbxAnalyticsStreamEventType.NewUserEvent} -> `identify()`
+ * - {@link DbxAnalyticsStreamEventType.UserLogoutEvent} -> `reset()`
+ * - {@link DbxAnalyticsStreamEventType.PageView} -> `page()`
+ *
+ * Events are only sent when the Segment configuration is marked as `active`.
+ * Provided at root level and registered as a listener via {@link DbxAnalyticsServiceConfiguration.listeners}.
+ *
+ * @example
+ * ```ts
+ * // Register in analytics configuration factory
+ * function analyticsConfigFactory(injector: Injector): DbxAnalyticsServiceConfiguration {
+ *   const segmentListener = injector.get(DbxAnalyticsSegmentServiceListener);
+ *   return {
+ *     isProduction: true,
+ *     listeners: [segmentListener]
+ *   };
+ * }
+ * ```
  */
 class DbxAnalyticsSegmentServiceListener extends AbstractDbxAnalyticsServiceListener {
     _segmentApi = inject(DbxAnalyticsSegmentApiService);
@@ -483,10 +746,35 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.0", ngImpor
         }], ctorParameters: () => [] });
 
 /**
- * Creates a EnvironmentProviders that provides a DbxAnalyticsSegmentApiService.
+ * Creates Angular environment providers that register {@link DbxAnalyticsSegmentApiService} for Segment analytics integration.
+ *
+ * Use alongside {@link provideDbxAnalyticsService} to wire Segment as an analytics listener.
+ *
+ * @param config - Segment-specific configuration including the write key factory
+ * @returns environment providers for Segment analytics
  *
- * @param config Configuration
- * @returns EnvironmentProviders
+ * @example
+ * ```ts
+ * // In app.config.ts
+ * export const appConfig: ApplicationConfig = {
+ *   providers: [
+ *     provideDbxAnalyticsSegmentApiService({
+ *       dbxAnalyticsSegmentApiServiceConfigFactory: (injector) => {
+ *         const config = new DbxAnalyticsSegmentApiServiceConfig(environment.analytics.segment);
+ *         config.active = environment.production;
+ *         config.logging = !environment.production;
+ *         return config;
+ *       }
+ *     }),
+ *     provideDbxAnalyticsService({
+ *       dbxAnalyticsServiceConfigurationFactory: (injector) => ({
+ *         isProduction: environment.production,
+ *         listeners: [injector.get(DbxAnalyticsSegmentServiceListener)]
+ *       })
+ *     })
+ *   ]
+ * };
+ * ```
  */
 function provideDbxAnalyticsSegmentApiService(config) {
     const { preloadSegmentToken, dbxAnalyticsSegmentApiServiceConfigFactory } = config;