@dereekb/dbx-analytics 13.3.0 → 13.4.0

package/types/dereekb-dbx-analytics.d.ts

@@ -3,79 +3,156 @@ import { Injector, EnvironmentProviders, InjectionToken } from '@angular/core';
 import * as rxjs from 'rxjs';
 import { Observable, BehaviorSubject, Subscription } from 'rxjs';
 import { DbxActionContextStoreSourceInstance } from '@dereekb/dbx-core';
-import { PrimativeKey, Maybe, Destroyable, ReadableError } from '@dereekb/util';
+import { AnalyticsEvent, AnalyticsEventData, AnalyticsEventName, AnalyticsUser, AnalyticsUserId, AnalyticsUserProperties, UserAnalyticsEvent, NewUserAnalyticsEventData } from '@dereekb/analytics';
+export { AnalyticsEvent, AnalyticsEventData, AnalyticsEventName, AnalyticsUser, AnalyticsUserId, AnalyticsUserProperties, NewUserAnalyticsEventData, NewUserRegistrationMethod, UserAnalyticsEvent } from '@dereekb/analytics';
+import { Maybe, Destroyable, ReadableError } from '@dereekb/util';
 import { AbstractAsyncWindowLoadedService } from '@dereekb/browser';
 
-type DbxAnalyticsEventName = string;
-type DbxAnalyticsUserId = string;
-interface DbxAnalyticsUserProperties {
-    readonly [key: string]: PrimativeKey | boolean;
-}
-interface DbxAnalyticsUser {
-    readonly user: DbxAnalyticsUserId;
-    readonly properties?: DbxAnalyticsUserProperties;
-}
-interface DbxAnalyticsEventData {
-    readonly [key: string]: PrimativeKey | boolean;
-}
-interface DbxAnalyticsEvent {
-    readonly name?: DbxAnalyticsEventName;
-    readonly value?: number;
-    readonly data?: DbxAnalyticsEventData;
-}
-interface DbxUserAnalyticsEvent extends DbxAnalyticsEvent {
-    readonly user?: Maybe<DbxAnalyticsUser>;
-}
-type NewUserRegistrationMethod = 'facebook' | 'google' | 'email' | string;
-interface NewUserAnalyticsEventData extends DbxAnalyticsEventData {
-    method: NewUserRegistrationMethod;
-}
+/** @deprecated Use {@link AnalyticsEventName} from `@dereekb/analytics` instead. */
+type DbxAnalyticsEventName = AnalyticsEventName;
+/** @deprecated Use {@link AnalyticsUserId} from `@dereekb/analytics` instead. */
+type DbxAnalyticsUserId = AnalyticsUserId;
+/** @deprecated Use {@link AnalyticsUserProperties} from `@dereekb/analytics` instead. */
+type DbxAnalyticsUserProperties = AnalyticsUserProperties;
+/** @deprecated Use {@link AnalyticsUser} from `@dereekb/analytics` instead. */
+type DbxAnalyticsUser = AnalyticsUser;
+/** @deprecated Use {@link AnalyticsEventData} from `@dereekb/analytics` instead. */
+type DbxAnalyticsEventData = AnalyticsEventData;
+/** @deprecated Use {@link AnalyticsEvent} from `@dereekb/analytics` instead. */
+type DbxAnalyticsEvent = AnalyticsEvent;
+/** @deprecated Use {@link UserAnalyticsEvent} from `@dereekb/analytics` instead. */
+type DbxUserAnalyticsEvent = UserAnalyticsEvent;
 
+/**
+ * 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()`).
+ */
 declare enum DbxAnalyticsStreamEventType {
+    /** A page/screen view event, typically sent on route transitions. */
     PageView = 0,
     /**
-     * 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.
      */
     UserChange = 1,
     /**
-     * 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.
      */
     UserIdChange = 2,
+    /** A new user registration event. */
     NewUserEvent = 3,
+    /** A returning user login event. */
     UserLoginEvent = 4,
+    /** A user logout event. */
     UserLogoutEvent = 5,
+    /** An update to user profile properties/traits. */
     UserPropertiesEvent = 6,
+    /** A generic custom analytics event. */
     Event = 7
 }
+/**
+ * Represents a single event in the analytics stream, combining the event type, payload, and user context.
+ *
+ * Emitted by {@link DbxAnalyticsService} and consumed by {@link DbxAnalyticsServiceListener} implementations
+ * (e.g., {@link DbxAnalyticsSegmentServiceListener}) to forward events to external analytics providers.
+ *
+ * @example
+ * ```ts
+ * // Subscribe to the analytics event stream
+ * analyticsService.events$.subscribe((streamEvent: DbxAnalyticsStreamEvent) => {
+ *   console.log(streamEvent.type, streamEvent.event?.name, streamEvent.userId);
+ * });
+ * ```
+ */
 interface DbxAnalyticsStreamEvent {
     readonly type: DbxAnalyticsStreamEventType;
-    readonly user?: Maybe<DbxAnalyticsUser>;
-    readonly event?: DbxUserAnalyticsEvent;
-    readonly userId?: DbxAnalyticsUserId;
+    readonly user?: Maybe<AnalyticsUser>;
+    readonly event?: UserAnalyticsEvent;
+    readonly userId?: AnalyticsUserId;
 }
 
+/**
+ * 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' });
+ * ```
+ */
 declare abstract class DbxAnalyticsEventEmitterService {
-    abstract sendNewUserEvent(user: DbxAnalyticsUser, data: NewUserAnalyticsEventData): void;
-    abstract sendUserLoginEvent(user: DbxAnalyticsUser, data?: DbxAnalyticsEventData): void;
-    abstract sendUserLogoutEvent(data?: DbxAnalyticsEventData): void;
-    abstract sendUserPropertiesEvent(user: DbxAnalyticsUser, data?: DbxAnalyticsEventData): void;
-    abstract sendEventData(name: DbxAnalyticsEventName, data?: DbxAnalyticsEventData): void;
-    abstract sendEvent(event: DbxAnalyticsEvent): void;
+    abstract sendNewUserEvent(user: AnalyticsUser, data: NewUserAnalyticsEventData): void;
+    abstract sendUserLoginEvent(user: AnalyticsUser, data?: AnalyticsEventData): void;
+    abstract sendUserLogoutEvent(data?: AnalyticsEventData): void;
+    abstract sendUserPropertiesEvent(user: AnalyticsUser, data?: AnalyticsEventData): void;
+    /**
+     * @deprecated When sending an event with no data, use {@link sendEventType} instead.
+     */
+    abstract sendEventData(name: AnalyticsEventName): void;
+    abstract sendEventData(name: AnalyticsEventName, data: AnalyticsEventData): void;
+    abstract sendEvent(event: AnalyticsEvent): void;
     abstract sendPageView(page?: string): void;
 }
+/**
+ * Abstract interface exposing the analytics event stream as an observable.
+ *
+ * Implemented by {@link DbxAnalyticsService}. Listeners subscribe to `events$` to forward events to external providers.
+ */
 declare abstract class DbxAnalyticsEventStreamService {
     abstract readonly events$: Observable<DbxAnalyticsStreamEvent>;
 }
+/**
+ * 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' } })
+ * };
+ * ```
+ */
 declare abstract class DbxAnalyticsUserSource {
-    abstract readonly analyticsUser$: Observable<Maybe<DbxAnalyticsUser>>;
+    abstract readonly analyticsUser$: Observable<Maybe<AnalyticsUser>>;
 }
+/**
+ * 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}.
+ */
 declare abstract class DbxAnalyticsServiceListener {
     abstract listenToService(service: DbxAnalyticsService): void;
 }
 /**
- * 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);
+ *     });
+ *   }
+ * }
+ * ```
  */
 declare abstract class AbstractDbxAnalyticsServiceListener implements DbxAnalyticsServiceListener, Destroyable {
     private _sub;
@@ -86,26 +163,85 @@ declare abstract class AbstractDbxAnalyticsServiceListener implements DbxAnalyti
     protected abstract _initializeServiceSubscription(): Subscription | false;
     destroy(): void;
 }
+/**
+ * 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
+ * };
+ * ```
+ */
 declare abstract class DbxAnalyticsServiceConfiguration {
     readonly listeners: DbxAnalyticsServiceListener[];
     readonly isProduction?: boolean;
     readonly logEvents?: boolean;
     readonly userSource?: DbxAnalyticsUserSource;
 }
+/**
+ * A fully resolved analytics stream event that includes the event payload, type, user context, and extracted user ID.
+ *
+ * Created by {@link dbxAnalyticsStreamEventAnalyticsEventWrapper} and emitted through the analytics event stream.
+ */
 interface DbxAnalyticsStreamEventAnalyticsEventWrapper extends DbxAnalyticsStreamEvent {
-    readonly event: DbxUserAnalyticsEvent;
+    readonly event: UserAnalyticsEvent;
     readonly type: DbxAnalyticsStreamEventType;
-    readonly user: Maybe<DbxAnalyticsUser>;
+    readonly user: Maybe<AnalyticsUser>;
     readonly userId: string | undefined;
 }
-declare function dbxAnalyticsStreamEventAnalyticsEventWrapper(event: DbxUserAnalyticsEvent, type?: DbxAnalyticsStreamEventType): {
-    event: DbxUserAnalyticsEvent;
+/**
+ * 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'
+ * ```
+ */
+declare function dbxAnalyticsStreamEventAnalyticsEventWrapper(event: UserAnalyticsEvent, type?: DbxAnalyticsStreamEventType): {
+    event: UserAnalyticsEvent;
     type: DbxAnalyticsStreamEventType;
-    user: Maybe<DbxAnalyticsUser>;
+    user: Maybe<AnalyticsUser>;
     userId: string | undefined;
 };
 /**
- * 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();
+ * });
+ * ```
  */
 declare class DbxAnalyticsService implements DbxAnalyticsEventStreamService, DbxAnalyticsEventEmitterService, Destroyable {
     private readonly _config;
@@ -116,26 +252,104 @@ declare class DbxAnalyticsService implements DbxAnalyticsEventStreamService, Dbx
     private _subject;
     readonly events$: Observable<DbxAnalyticsStreamEvent>;
     private _userSource;
-    readonly user$: Observable<Maybe<DbxAnalyticsUser>>;
+    readonly user$: Observable<Maybe<AnalyticsUser>>;
     private _userSourceSub;
     private _userIdEventSub;
     private _loggerSub;
     constructor();
     /**
-     * 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: Maybe<AnalyticsUser>): void;
+    /**
+     * 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
      */
-    setUser(user: Maybe<DbxAnalyticsUser>): void;
     setUserSource(source: DbxAnalyticsUserSource): void;
     /**
-     * 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: AnalyticsUser, data: NewUserAnalyticsEventData): void;
+    /**
+     * 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: AnalyticsUser, data?: AnalyticsEventData): void;
+    /**
+     * 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?: AnalyticsEventData, clearUser?: boolean): void;
+    /**
+     * 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: AnalyticsUser, data?: AnalyticsEventData): void;
+    /**
+     * @deprecated When sending an event with no data, use {@link sendEventType} instead.
+     */
+    sendEventData(name: AnalyticsEventName): void;
+    /**
+     * Sends a named analytics event with a data payload.
+     *
+     * This is the primary method for tracking custom events with associated properties.
+     *
+     * @param name - the event name (e.g., `'Interview Ended'`)
+     * @param data - key-value data attached to the event
+     *
+     * @example
+     * ```ts
+     * analytics.sendEventData('Interview Ended', {
+     *   seconds: 120,
+     *   endedDueToTime: 'true'
+     * });
+     * ```
+     */
+    sendEventData(name: AnalyticsEventName, data: AnalyticsEventData): void;
+    /**
+     * 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: AnalyticsEventName): void;
+    /**
+     * Sends a fully constructed analytics event object.
+     *
+     * @param event - the event containing name, optional value, and data
+     */
+    sendEvent(event: AnalyticsEvent): void;
+    /**
+     * 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();
+     * });
+     * ```
      */
-    sendNewUserEvent(user: DbxAnalyticsUser, data: NewUserAnalyticsEventData): void;
-    sendUserLoginEvent(user: DbxAnalyticsUser, data?: DbxAnalyticsEventData): void;
-    sendUserLogoutEvent(data?: DbxAnalyticsEventData, clearUser?: boolean): void;
-    sendUserPropertiesEvent(user: DbxAnalyticsUser, data?: DbxAnalyticsEventData): void;
-    sendEventData(name: DbxAnalyticsEventName, data?: DbxAnalyticsEventData): void;
-    sendEventType(eventType: DbxAnalyticsEventName): void;
-    sendEvent(event: DbxAnalyticsEvent): void;
     sendPageView(page?: string): void;
     /**
      * Sends the next event.
@@ -144,8 +358,8 @@ declare class DbxAnalyticsService implements DbxAnalyticsEventStreamService, Dbx
      * @param type
      * @param userOverride Uses this user if set as null or an override value. If undefined the current analytics user is used.
      */
-    protected sendNextEvent(event: DbxAnalyticsEvent | undefined, type: DbxAnalyticsStreamEventType, userOverride?: Maybe<DbxAnalyticsUser>): void;
-    protected nextEvent(event: DbxUserAnalyticsEvent, type: DbxAnalyticsStreamEventType): void;
+    protected sendNextEvent(event: AnalyticsEvent | undefined, type: DbxAnalyticsStreamEventType, userOverride?: Maybe<AnalyticsUser>): void;
+    protected nextEvent(event: UserAnalyticsEvent, type: DbxAnalyticsStreamEventType): void;
     private _init;
     destroy(): void;
     static ɵfac: i0.ɵɵFactoryDeclaration<DbxAnalyticsService, never>;
@@ -153,16 +367,55 @@ declare class DbxAnalyticsService implements DbxAnalyticsEventStreamService, Dbx
 }
 
 /**
- * DbxActionAnalyticsDirective config
+ * Configuration for {@link DbxActionAnalyticsDirective} that maps action lifecycle events to analytics calls.
+ *
+ * Each callback receives the {@link DbxAnalyticsService} and relevant action data, allowing you to
+ * send targeted analytics events at each stage of an action's lifecycle (trigger, ready, success, error).
+ *
+ * @example
+ * ```ts
+ * // In a component, define analytics config for a form submit action
+ * readonly submitAnalytics: DbxActionAnalyticsConfig<MyFormValue, MyResult> = {
+ *   onReady: (service, value) => {
+ *     service.sendEventData('Form Submitted', { formType: 'onboard' });
+ *   },
+ *   onSuccess: (service, result, value) => {
+ *     service.sendEventType('Onboarding Complete');
+ *   },
+ *   onError: (service, error) => {
+ *     service.sendEventData('Form Submit Failed', { code: error?.code ?? 'unknown' });
+ *   }
+ * };
+ *
+ * // In the template
+ * // <button dbxAction [dbxActionAnalytics]="submitAnalytics">Submit</button>
+ * ```
  */
 interface DbxActionAnalyticsConfig<T = unknown, O = unknown> {
+    /** Called when the action is triggered (button pressed). */
     readonly onTriggered?: (service: DbxAnalyticsService) => void;
+    /** Called when the action value is ready and about to be processed. */
     readonly onReady?: (service: DbxAnalyticsService, value: T) => void;
+    /** Called when the action completes successfully. */
     readonly onSuccess?: (service: DbxAnalyticsService, result: Maybe<O>, value: T) => void;
+    /** Called when the action encounters an error. */
     readonly onError?: (service: DbxAnalyticsService, error: Maybe<ReadableError>) => void;
 }
 /**
- * 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>
+ * ```
  */
 declare class DbxActionAnalyticsDirective<T, O> {
     readonly source: DbxActionContextStoreSourceInstance<T, O>;
@@ -190,21 +443,62 @@ declare class DbxAnalyticsActionModule {
  */
 type DbxAnalyticsServiceConfigurationFactory = (injector: Injector) => DbxAnalyticsServiceConfiguration;
 /**
- * Configuration for provideDbxAnalyticsService()
+ * Configuration for {@link provideDbxAnalyticsService}.
  */
 interface ProvideDbxAnalyticsConfig {
     readonly dbxAnalyticsServiceConfigurationFactory: DbxAnalyticsServiceConfigurationFactory;
 }
 /**
- * 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 - contains the factory function that produces a {@link DbxAnalyticsServiceConfiguration}
+ * @returns environment providers for the analytics service
  *
- * @param config Configuration
- * @returns EnvironmentProviders
+ * @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)
+ *       })
+ *     })
+ *   ]
+ * };
+ * ```
  */
 declare function provideDbxAnalyticsService(config: ProvideDbxAnalyticsConfig): EnvironmentProviders;
 
 /**
- * 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]
+ *   };
+ * }
+ * ```
  */
 declare class DbxAnalyticsSegmentServiceListener extends AbstractDbxAnalyticsServiceListener {
     private readonly _segmentApi;
@@ -242,7 +536,20 @@ declare class DbxAnalyticsSegmentServiceListener extends AbstractDbxAnalyticsSer
     static ɵprov: i0.ɵɵInjectableDeclaration<DbxAnalyticsSegmentServiceListener>;
 }
 
+/**
+ * Injection token for optionally preloading the Segment analytics script.
+ */
 declare const PRELOAD_SEGMENT_TOKEN: InjectionToken<string>;
+/**
+ * Configuration for the Segment analytics integration.
+ *
+ * @example
+ * ```ts
+ * const config = new DbxAnalyticsSegmentApiServiceConfig('your-segment-write-key');
+ * config.active = environment.production;
+ * config.logging = !environment.production;
+ * ```
+ */
 declare class DbxAnalyticsSegmentApiServiceConfig {
     writeKey: string;
     logging: boolean;
@@ -250,9 +557,26 @@ declare class DbxAnalyticsSegmentApiServiceConfig {
     constructor(writeKey: string);
 }
 /**
- * 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;
+ *   }
+ * })
+ * ```
  */
 declare class DbxAnalyticsSegmentApiService extends AbstractAsyncWindowLoadedService<SegmentAnalytics.AnalyticsJS> {
     private readonly _config;
@@ -266,21 +590,53 @@ declare class DbxAnalyticsSegmentApiService extends AbstractAsyncWindowLoadedSer
     static ɵprov: i0.ɵɵInjectableDeclaration<DbxAnalyticsSegmentApiService>;
 }
 
+/**
+ * Factory function that creates a {@link DbxAnalyticsSegmentApiServiceConfig} using the Angular injector.
+ *
+ * Used by {@link provideDbxAnalyticsSegmentApiService} to defer Segment configuration to runtime.
+ */
 type DbxAnalyticsSegmentApiServiceConfigFactory = (injector: Injector) => DbxAnalyticsSegmentApiServiceConfig;
 /**
- * Configuration for provideDbxAnalyticsSegmentApiService()
+ * Configuration for {@link provideDbxAnalyticsSegmentApiService}.
  */
 interface ProvideDbxAnalyticsSegmentModuleConfig {
+    /** Whether to preload the Segment script token. */
     readonly preloadSegmentToken?: boolean;
+    /** Factory function that produces the Segment API service configuration. */
     readonly dbxAnalyticsSegmentApiServiceConfigFactory: DbxAnalyticsSegmentApiServiceConfigFactory;
 }
 /**
- * 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)]
+ *       })
+ *     })
+ *   ]
+ * };
+ * ```
  */
 declare function provideDbxAnalyticsSegmentApiService(config: ProvideDbxAnalyticsSegmentModuleConfig): EnvironmentProviders;
 
 export { AbstractDbxAnalyticsServiceListener, DbxActionAnalyticsDirective, DbxAnalyticsActionModule, DbxAnalyticsEventEmitterService, DbxAnalyticsEventStreamService, DbxAnalyticsSegmentApiService, DbxAnalyticsSegmentApiServiceConfig, DbxAnalyticsSegmentServiceListener, DbxAnalyticsService, DbxAnalyticsServiceConfiguration, DbxAnalyticsServiceListener, DbxAnalyticsStreamEventType, DbxAnalyticsUserSource, PRELOAD_SEGMENT_TOKEN, dbxAnalyticsStreamEventAnalyticsEventWrapper, provideDbxAnalyticsSegmentApiService, provideDbxAnalyticsService };
-export type { DbxActionAnalyticsConfig, DbxAnalyticsEvent, DbxAnalyticsEventData, DbxAnalyticsEventName, DbxAnalyticsSegmentApiServiceConfigFactory, DbxAnalyticsServiceConfigurationFactory, DbxAnalyticsStreamEvent, DbxAnalyticsStreamEventAnalyticsEventWrapper, DbxAnalyticsUser, DbxAnalyticsUserId, DbxAnalyticsUserProperties, DbxUserAnalyticsEvent, NewUserAnalyticsEventData, NewUserRegistrationMethod, ProvideDbxAnalyticsConfig, ProvideDbxAnalyticsSegmentModuleConfig };
+export type { DbxActionAnalyticsConfig, DbxAnalyticsEvent, DbxAnalyticsEventData, DbxAnalyticsEventName, DbxAnalyticsSegmentApiServiceConfigFactory, DbxAnalyticsServiceConfigurationFactory, DbxAnalyticsStreamEvent, DbxAnalyticsStreamEventAnalyticsEventWrapper, DbxAnalyticsUser, DbxAnalyticsUserId, DbxAnalyticsUserProperties, DbxUserAnalyticsEvent, ProvideDbxAnalyticsConfig, ProvideDbxAnalyticsSegmentModuleConfig };