@dereekb/analytics 13.4.0

package/nestjs/src/lib/interceptor/analytics.interceptor.d.ts

@@ -0,0 +1,65 @@
+import { type Maybe } from '@dereekb/util';
+import { type AnalyticsEventName } from '@dereekb/analytics';
+import { type CallHandler, type ExecutionContext, type NestInterceptor } from '@nestjs/common';
+import { type Reflector } from '@nestjs/core';
+import { type EventEmitter2 } from '@nestjs/event-emitter';
+import { type Observable } from 'rxjs';
+export declare const ANALYTICS_INTERCEPTOR_METADATA_KEY = "analyticsevent";
+/**
+ * Function that extracts analytics event data from a handler result.
+ *
+ * @param result - The handler's return value.
+ * @param context - The NestJS execution context for the current request.
+ * @returns An object of event data to attach to the analytics event, or nothing if no data should be emitted.
+ */
+export type AnalyticsEventDataFunction<T> = (result: T, context: ExecutionContext) => Maybe<object>;
+/**
+ * Configuration for the {@link EmitAnalyticsEvent} decorator.
+ */
+export interface AnalyticsEventInterceptorConfig<T> {
+    /**
+     * The analytics event name to emit.
+     */
+    readonly name: AnalyticsEventName;
+    /**
+     * Optional function to extract event data from the handler result.
+     */
+    readonly fn?: AnalyticsEventDataFunction<T>;
+}
+/**
+ * Decorator that marks a controller method for analytics event emission.
+ *
+ * Used in conjunction with {@link AnalyticsEventInterceptor} to emit events
+ * to NestJS EventEmitter2 after the handler completes.
+ *
+ * @param config - The analytics event configuration specifying the event name and optional data extractor.
+ * @returns A method decorator that attaches analytics metadata.
+ *
+ * @example
+ * ```ts
+ * @EmitAnalyticsEvent({ name: 'User Registered', fn: (result) => ({ userId: result.id }) })
+ * @Post('register')
+ * async register(@Body() body: RegisterDto) {
+ *   return this.authService.register(body);
+ * }
+ * ```
+ */
+export declare const EmitAnalyticsEvent: <T>(config: AnalyticsEventInterceptorConfig<T>) => import("@nestjs/common").CustomDecorator<string>;
+/**
+ * NestJS interceptor that emits analytics events via EventEmitter2
+ * for controller methods decorated with {@link EmitAnalyticsEvent}.
+ */
+export declare class AnalyticsEventInterceptor<T = any> implements NestInterceptor {
+    readonly reflector: Reflector;
+    readonly eventEmitter: EventEmitter2;
+    constructor(reflector: Reflector, eventEmitter: EventEmitter2);
+    /**
+     * Intercepts the request pipeline, emitting an analytics event after the handler completes
+     * if the method is decorated with {@link EmitAnalyticsEvent}.
+     *
+     * @param context - The NestJS execution context.
+     * @param next - The next handler in the pipeline.
+     * @returns An observable that emits the handler result after triggering the analytics event.
+     */
+    intercept(context: ExecutionContext, next: CallHandler): Observable<any>;
+}

package/nestjs/src/lib/interceptor/index.d.ts

@@ -0,0 +1 @@
+export * from './analytics.interceptor';

package/nestjs/src/lib/segment/index.d.ts

@@ -0,0 +1,5 @@
+export * from './segment.api';
+export * from './segment.config';
+export * from './segment.module';
+export * from './segment.service';
+export * from './segment.type';

package/nestjs/src/lib/segment/segment.api.d.ts

@@ -0,0 +1,15 @@
+import { type OnModuleDestroy } from '@nestjs/common';
+import { Analytics } from '@segment/analytics-node';
+import { SegmentServiceConfig } from './segment.config';
+/**
+ * Injectable wrapper around the Segment Analytics Node SDK.
+ *
+ * Manages the Analytics client lifecycle, including flushing on module destroy.
+ */
+export declare class SegmentApi implements OnModuleDestroy {
+    readonly config: SegmentServiceConfig;
+    readonly analytics: Analytics;
+    constructor(config: SegmentServiceConfig);
+    get logOnly(): boolean;
+    onModuleDestroy(): Promise<void>;
+}

package/nestjs/src/lib/segment/segment.config.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Application context included in Segment event contexts.
+ */
+export interface SegmentServiceAppContext {
+    readonly name: string;
+    readonly version?: string;
+    readonly namespace?: string;
+}
+/**
+ * Configuration for the Segment analytics service.
+ */
+export declare class SegmentServiceConfig {
+    /**
+     * Segment write key for the source.
+     */
+    readonly writeKey: string;
+    /**
+     * When true, events are logged to the console instead of sent to Segment.
+     */
+    readonly logOnly: boolean;
+    /**
+     * Optional application context included in all Segment event contexts.
+     */
+    readonly appContext?: SegmentServiceAppContext;
+    /**
+     * Validates that the given config has the required fields (e.g., a non-empty write key).
+     *
+     * @param config - The config instance to validate.
+     * @throws {Error} When the write key is missing or empty.
+     *
+     * @example
+     * ```ts
+     * SegmentServiceConfig.assertValidConfig(config);
+     * ```
+     */
+    static assertValidConfig(config: SegmentServiceConfig): void;
+}

package/nestjs/src/lib/segment/segment.module.d.ts

@@ -0,0 +1,28 @@
+import { ConfigService } from '@nestjs/config';
+import { ServerEnvironmentService } from '@dereekb/nestjs';
+import { SegmentServiceConfig } from './segment.config';
+/**
+ * Factory that creates a SegmentServiceConfig from environment variables.
+ *
+ * When a {@link ServerEnvironmentService} is provided and the current environment is a
+ * testing environment, `logOnly` is forced to true regardless of the env variable.
+ *
+ * @param configService - NestJS ConfigService for reading environment variables.
+ * @param serverEnvironmentService - Service that identifies the current server environment.
+ * @returns A validated {@link SegmentServiceConfig} instance.
+ *
+ * @example
+ * ```ts
+ * const config = segmentServiceConfigFactory(configService, serverEnvironmentService);
+ * ```
+ */
+export declare function segmentServiceConfigFactory(configService: ConfigService, serverEnvironmentService: ServerEnvironmentService): SegmentServiceConfig;
+/**
+ * NestJS module that provides the {@link SegmentService} and its dependencies.
+ *
+ * Reads `SEGMENT_WRITE_KEY` and `SEGMENT_LOG_ONLY` from environment variables via {@link ConfigModule}.
+ * When a {@link ServerEnvironmentService} is available and the environment is a testing environment,
+ * `logOnly` is forced to `true`.
+ */
+export declare class SegmentServiceModule {
+}

package/nestjs/src/lib/segment/segment.service.d.ts

@@ -0,0 +1,62 @@
+import { type Maybe } from '@dereekb/util';
+import { type AnalyticsUserId } from '@dereekb/analytics';
+import { SegmentApi } from './segment.api';
+import { SegmentServiceConfig } from './segment.config';
+import { type SegmentTrackEvent, type SegmentIdentifyParams } from './segment.type';
+/**
+ * High-level Segment analytics service.
+ *
+ * Handles track and identify calls, merging application context and
+ * supporting log-only mode for development/testing.
+ */
+export declare class SegmentService {
+    readonly segmentApi: SegmentApi;
+    readonly config: SegmentServiceConfig;
+    private readonly logger;
+    constructor(segmentApi: SegmentApi, config: SegmentServiceConfig);
+    /**
+     * Tracks an event for a user. Requires a userId.
+     *
+     * In log-only mode, events are logged to the console instead of being sent to Segment.
+     *
+     * @param userId - the user to associate with the event
+     * @param event - the track event containing event name, properties, and optional context
+     *
+     * @throws {Error} When userId is falsy.
+     *
+     * @example
+     * ```ts
+     * segmentService.track('uid_123', {
+     *   event: 'Item Purchased',
+     *   properties: { itemId: 'sku_abc', price: 29.99 }
+     * });
+     * ```
+     */
+    track(userId: AnalyticsUserId, event: SegmentTrackEvent): void;
+    /**
+     * Tracks an event only if userId is provided. No-op if userId is nullish.
+     *
+     * Convenience wrapper around {@link track} for cases where the user may not be authenticated.
+     *
+     * @param userId - the user to associate with the event, or nullish to skip
+     * @param event - the track event containing event name, properties, and optional context
+     */
+    tryTrack(userId: Maybe<AnalyticsUserId>, event: SegmentTrackEvent): void;
+    /**
+     * Identifies a user with optional traits, syncing user properties to Segment.
+     *
+     * In log-only mode, the identify call is logged to the console instead of being sent.
+     *
+     * @param params - the identify parameters including userId and optional traits
+     *
+     * @example
+     * ```ts
+     * segmentService.identify({
+     *   userId: 'uid_123',
+     *   traits: { plan: 'premium', role: 'admin' }
+     * });
+     * ```
+     */
+    identify(params: SegmentIdentifyParams): void;
+    private _appContext;
+}

package/nestjs/src/lib/segment/segment.type.d.ts

@@ -0,0 +1,26 @@
+import { type TrackParams, type IdentifyParams, type UserTraits } from '@segment/analytics-node';
+import { type SegmentServiceAppContext } from './segment.config';
+/**
+ * Segment event context derived from the SDK's TrackParams context,
+ * with an explicit `app` field for better typing.
+ */
+export type SegmentEventContext = TrackParams['context'] & {
+    readonly app?: SegmentServiceAppContext;
+};
+/**
+ * Segment track event parameters derived from the SDK's TrackParams.
+ *
+ * Picks the commonly used fields without requiring userId/anonymousId
+ * (since those are provided separately by the service).
+ */
+export type SegmentTrackEvent = Pick<TrackParams, 'event' | 'properties' | 'context' | 'timestamp'>;
+/**
+ * Segment identify parameters derived from the SDK's IdentifyParams.
+ */
+export type SegmentIdentifyParams = IdentifyParams;
+/**
+ * Segment identify traits derived from the SDK's UserTraits.
+ *
+ * Includes standard fields like email, name, plus arbitrary key-value pairs.
+ */
+export type SegmentIdentifyTraits = UserTraits;

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@dereekb/analytics",
+  "version": "13.4.0",
+  "exports": {
+    "./nestjs": {
+      "module": "./nestjs/index.esm.js",
+      "types": "./nestjs/index.d.ts",
+      "import": "./nestjs/index.cjs.mjs",
+      "default": "./nestjs/index.cjs.js"
+    },
+    "./package.json": "./package.json",
+    ".": {
+      "module": "./index.esm.js",
+      "types": "./index.d.ts",
+      "import": "./index.cjs.mjs",
+      "default": "./index.cjs.js"
+    }
+  },
+  "peerDependencies": {
+    "@dereekb/nestjs": "13.4.0",
+    "@dereekb/util": "13.4.0",
+    "@nestjs/common": "^11.1.16",
+    "@nestjs/config": "^4.0.3",
+    "@nestjs/core": "^11.1.16",
+    "@nestjs/event-emitter": "^3.0.1",
+    "@segment/analytics-node": "^2.3.0",
+    "rxjs": "^7.8.0"
+  },
+  "module": "./index.esm.js",
+  "main": "./index.cjs.js",
+  "types": "./index.d.ts"
+}

package/src/index.d.ts

@@ -0,0 +1 @@
+export * from './lib';

package/src/lib/analytics.event.d.ts

@@ -0,0 +1,62 @@
+import { type Maybe, type PrimativeKey } from '@dereekb/util';
+/**
+ * Name identifier for an analytics event (e.g., `'User Registered'`, `'Page Viewed'`).
+ */
+export type AnalyticsEventName = string;
+/**
+ * Unique identifier for an analytics user, typically a UID from the auth system.
+ */
+export type AnalyticsUserId = 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.
+ */
+export interface AnalyticsUserProperties {
+    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.
+ */
+export interface AnalyticsUser {
+    readonly user: AnalyticsUserId;
+    readonly properties?: AnalyticsUserProperties;
+}
+/**
+ * Key-value map of event-specific data attached to an analytics event.
+ *
+ * Sent as properties in `track()` calls to analytics providers.
+ */
+export interface AnalyticsEventData {
+    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 analytics services and consumed by listeners like Segment.
+ */
+export interface AnalyticsEvent {
+    readonly name?: AnalyticsEventName;
+    readonly value?: number;
+    readonly data?: AnalyticsEventData;
+}
+/**
+ * Extends {@link AnalyticsEvent} with an optional user association.
+ *
+ * Used to attach the current user context to each emitted event.
+ */
+export interface UserAnalyticsEvent extends AnalyticsEvent {
+    readonly user?: Maybe<AnalyticsUser>;
+}
+/**
+ * Registration method used to create a new user account (e.g., `'facebook'`, `'google'`, `'email'`).
+ */
+export type NewUserRegistrationMethod = 'facebook' | 'google' | 'email' | string;
+/**
+ * Event data for new user registration events, requiring the registration method.
+ */
+export interface NewUserAnalyticsEventData extends AnalyticsEventData {
+    readonly method: NewUserRegistrationMethod;
+}

package/src/lib/analytics.event.util.d.ts

@@ -0,0 +1,55 @@
+import { type Maybe } from '@dereekb/util';
+import { type AnalyticsEventData } from './analytics.event';
+/**
+ * Configuration for {@link asAnalyticsEventData}.
+ */
+export interface AsAnalyticsEventDataConfig {
+    /**
+     * Whether to flatten nested objects into dot-separated keys before filtering.
+     *
+     * When true, nested plain objects are recursively flattened so their primitive values
+     * are preserved with concatenated key paths (e.g., `{ user: { age: 25 } }` becomes `{ 'user.age': 25 }`).
+     *
+     * @defaultValue true
+     */
+    readonly flattenObjects?: boolean;
+    /**
+     * Separator for flattened key paths.
+     *
+     * Only applicable when {@link flattenObjects} is true.
+     *
+     * @defaultValue '.'
+     */
+    readonly separator?: string;
+    /**
+     * Maximum nesting depth to flatten.
+     *
+     * Only applicable when {@link flattenObjects} is true.
+     *
+     * @defaultValue Infinity (unlimited)
+     */
+    readonly maxDepth?: number;
+}
+/**
+ * Converts an arbitrary object into valid {@link AnalyticsEventData} by flattening nested objects
+ * and filtering out values that are not compatible with analytics providers.
+ *
+ * Processing steps:
+ * 1. Flattens nested plain objects into dot-separated key paths (configurable, enabled by default)
+ * 2. Filters out any values that are not `string`, `number`, or `boolean`
+ * 3. Filters out non-finite numbers (`NaN`, `Infinity`, `-Infinity`)
+ *
+ * @example
+ * ```ts
+ * asAnalyticsEventData({ action: 'click', user: { age: 25, name: 'Jo' }, tags: [1, 2] });
+ * // { action: 'click', 'user.age': 25, 'user.name': 'Jo' }
+ *
+ * asAnalyticsEventData({ a: 'ok', b: { nested: 1 } }, { flattenObjects: false });
+ * // { a: 'ok' }
+ * ```
+ *
+ * @param input - The object to convert. If nullish, returns an empty object.
+ * @param config - Optional configuration for flattening behavior.
+ * @returns A new {@link AnalyticsEventData} object containing only valid analytics values.
+ */
+export declare function asAnalyticsEventData(input: Maybe<Record<string, unknown>>, config?: AsAnalyticsEventDataConfig): AnalyticsEventData;

package/src/lib/index.d.ts

@@ -0,0 +1,2 @@
+export * from './analytics.event';
+export * from './analytics.event.util';