@dereekb/dbx-analytics 13.2.2 → 13.3.1

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

@@ -6,49 +6,155 @@ import { DbxActionContextStoreSourceInstance } from '@dereekb/dbx-core';
 import { PrimativeKey, Maybe, Destroyable, ReadableError } from '@dereekb/util';
 import { AbstractAsyncWindowLoadedService } from '@dereekb/browser';
 
+/**
+ * Name identifier for an analytics event (e.g., `'User Registered'`, `'Page Viewed'`).
+ */
 type DbxAnalyticsEventName = string;
+/**
+ * Unique identifier for an analytics user, typically a UID from the auth system.
+ */
 type DbxAnalyticsUserId = string;
+/**
+ * Key-value map of user properties sent alongside identify calls to analytics providers.
+ *
+ * Used to enrich user profiles in tools like Segment with traits such as roles, plan type, or onboarding status.
+ *
+ * @example
+ * ```ts
+ * const properties: DbxAnalyticsUserProperties = {
+ *   isOnboarded: true,
+ *   role: 'admin',
+ *   plan: 'pro'
+ * };
+ * ```
+ */
 interface DbxAnalyticsUserProperties {
     readonly [key: string]: PrimativeKey | boolean;
 }
+/**
+ * Represents a user for analytics identification, pairing a unique user ID with optional trait properties.
+ *
+ * Passed to analytics providers (e.g., Segment `identify()`) to associate events with a specific user.
+ *
+ * @example
+ * ```ts
+ * const user: DbxAnalyticsUser = {
+ *   user: 'uid_abc123',
+ *   properties: { isOnboarded: true, role: 'worker' }
+ * };
+ * ```
+ */
 interface DbxAnalyticsUser {
     readonly user: DbxAnalyticsUserId;
     readonly properties?: DbxAnalyticsUserProperties;
 }
+/**
+ * Key-value map of event-specific data attached to an analytics event.
+ *
+ * Sent as properties in `track()` calls to analytics providers.
+ *
+ * @example
+ * ```ts
+ * const data: DbxAnalyticsEventData = {
+ *   code: 'PERMISSION_DENIED',
+ *   seconds: 120
+ * };
+ * ```
+ */
 interface DbxAnalyticsEventData {
     readonly [key: string]: PrimativeKey | boolean;
 }
+/**
+ * Describes an analytics event with an optional name, numeric value, and arbitrary data payload.
+ *
+ * This is the core event shape emitted through {@link DbxAnalyticsService} and consumed by listeners like Segment.
+ *
+ * @example
+ * ```ts
+ * const event: DbxAnalyticsEvent = {
+ *   name: 'Button Clicked',
+ *   value: 1,
+ *   data: { buttonId: 'submit-form' }
+ * };
+ * ```
+ */
 interface DbxAnalyticsEvent {
     readonly name?: DbxAnalyticsEventName;
     readonly value?: number;
     readonly data?: DbxAnalyticsEventData;
 }
+/**
+ * Extends {@link DbxAnalyticsEvent} with an optional user association.
+ *
+ * Used internally by {@link DbxAnalyticsService} to attach the current user context to each emitted event.
+ */
 interface DbxUserAnalyticsEvent extends DbxAnalyticsEvent {
     readonly user?: Maybe<DbxAnalyticsUser>;
 }
+/**
+ * Registration method used to create a new user account (e.g., `'facebook'`, `'google'`, `'email'`).
+ */
 type NewUserRegistrationMethod = 'facebook' | 'google' | 'email' | string;
+/**
+ * Event data for new user registration events, requiring the registration method.
+ *
+ * @example
+ * ```ts
+ * const data: NewUserAnalyticsEventData = {
+ *   method: 'google'
+ * };
+ * ```
+ */
 interface NewUserAnalyticsEventData extends DbxAnalyticsEventData {
     method: NewUserRegistrationMethod;
 }
 
+/**
+ * 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>;
@@ -56,26 +162,83 @@ interface DbxAnalyticsStreamEvent {
     readonly userId?: DbxAnalyticsUserId;
 }
 
+/**
+ * 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;
+    /**
+     * @deprecated When sending an event with no data, use {@link sendEventType} instead.
+     */
+    abstract sendEventData(name: DbxAnalyticsEventName): void;
+    abstract sendEventData(name: DbxAnalyticsEventName, data: DbxAnalyticsEventData): void;
     abstract sendEvent(event: DbxAnalyticsEvent): 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 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,18 +249,57 @@ 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 type: DbxAnalyticsStreamEventType;
     readonly user: Maybe<DbxAnalyticsUser>;
     readonly userId: string | undefined;
 }
+/**
+ * Wraps a {@link DbxUserAnalyticsEvent} 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: DbxUserAnalyticsEvent, type?: DbxAnalyticsStreamEventType): {
     event: DbxUserAnalyticsEvent;
     type: DbxAnalyticsStreamEventType;
@@ -105,7 +307,27 @@ declare function dbxAnalyticsStreamEventAnalyticsEventWrapper(event: DbxUserAnal
     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;
@@ -122,20 +344,98 @@ declare class DbxAnalyticsService implements DbxAnalyticsEventStreamService, Dbx
     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<DbxAnalyticsUser>): 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
+     */
     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: DbxAnalyticsUser, 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: DbxAnalyticsUser, data?: DbxAnalyticsEventData): 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?: DbxAnalyticsEventData, 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: DbxAnalyticsUser, data?: DbxAnalyticsEventData): void;
-    sendEventData(name: DbxAnalyticsEventName, data?: DbxAnalyticsEventData): void;
+    /**
+     * @deprecated When sending an event with no data, use {@link sendEventType} instead.
+     */
+    sendEventData(name: DbxAnalyticsEventName): 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: DbxAnalyticsEventName, data: DbxAnalyticsEventData): 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: DbxAnalyticsEventName): void;
+    /**
+     * Sends a fully constructed analytics event object.
+     *
+     * @param event - the event containing name, optional value, and data
+     */
     sendEvent(event: DbxAnalyticsEvent): 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();
+     * });
+     * ```
+     */
     sendPageView(page?: string): void;
     /**
      * Sends the next event.
@@ -153,16 +453,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>;
@@ -183,37 +522,120 @@ declare class DbxAnalyticsActionModule {
     static ɵinj: i0.ɵɵInjectorDeclaration<DbxAnalyticsActionModule>;
 }
 
+/**
+ * Factory function that creates a {@link DbxAnalyticsServiceConfiguration} using the Angular injector.
+ *
+ * Used by {@link provideDbxAnalyticsService} to defer configuration resolution to runtime.
+ */
 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.
  *
- * @param config Configuration
- * @returns EnvironmentProviders
+ * 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
+ *
+ * @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;
     constructor();
+    /**
+     * Subscribes to the Segment API service and analytics event stream, forwarding events to the Segment SDK.
+     *
+     * Events are only sent when the Segment configuration is marked as active.
+     */
     protected _initializeServiceSubscription(): rxjs.Subscription;
+    /**
+     * Routes an analytics stream event to the appropriate Segment API method based on event type.
+     *
+     * @param api - The Segment analytics SDK instance
+     * @param streamEvent - The analytics event to process
+     */
     protected handleStreamEvent(api: SegmentAnalytics.AnalyticsJS, streamEvent: DbxAnalyticsStreamEvent): void;
+    /**
+     * Handles a new user registration event by identifying the user in Segment.
+     *
+     * @param api - The Segment analytics SDK instance
+     * @param streamEvent - The event containing the new user data
+     */
     protected updateWithNewUserEvent(api: SegmentAnalytics.AnalyticsJS, streamEvent: DbxAnalyticsStreamEvent): void;
+    /**
+     * Sends a track event to Segment with the event name, value, and additional data properties.
+     *
+     * @param api - The Segment analytics SDK instance
+     * @param streamEvent - The analytics event containing name, value, and data
+     * @param name - Optional override for the event name
+     */
     protected updateWithEvent(api: SegmentAnalytics.AnalyticsJS, streamEvent: DbxAnalyticsStreamEvent, name?: string): void;
     private changeUser;
     static ɵfac: i0.ɵɵFactoryDeclaration<DbxAnalyticsSegmentServiceListener, never>;
     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;
@@ -221,9 +643,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`.
  *
- * This requires some setup in index.html.
+ * 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`.
+ *
+ * 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;
@@ -237,19 +676,51 @@ 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;