@dereekb/firebase-server 13.3.1 → 13.4.1

package/mailgun/package.json

@@ -1,14 +1,15 @@
 {
   "name": "@dereekb/firebase-server/mailgun",
-  "version": "13.3.1",
+  "version": "13.4.1",
   "peerDependencies": {
-    "@dereekb/firebase": "13.3.1",
-    "@dereekb/firebase-server": "13.3.1",
-    "@dereekb/date": "13.3.1",
-    "@dereekb/nestjs": "13.3.1",
-    "@dereekb/model": "13.3.1",
-    "@dereekb/rxjs": "13.3.1",
-    "@dereekb/util": "13.3.1"
+    "@dereekb/analytics": "13.4.1",
+    "@dereekb/firebase": "13.4.1",
+    "@dereekb/firebase-server": "13.4.1",
+    "@dereekb/date": "13.4.1",
+    "@dereekb/nestjs": "13.4.1",
+    "@dereekb/model": "13.4.1",
+    "@dereekb/rxjs": "13.4.1",
+    "@dereekb/util": "13.4.1"
   },
   "exports": {
     "./package.json": "./package.json",

package/model/package.json

@@ -1,14 +1,15 @@
 {
   "name": "@dereekb/firebase-server/model",
-  "version": "13.3.1",
+  "version": "13.4.1",
   "peerDependencies": {
-    "@dereekb/date": "13.3.1",
-    "@dereekb/firebase": "13.3.1",
-    "@dereekb/firebase-server": "13.3.1",
-    "@dereekb/model": "13.3.1",
-    "@dereekb/nestjs": "13.3.1",
-    "@dereekb/rxjs": "13.3.1",
-    "@dereekb/util": "13.3.1",
+    "@dereekb/analytics": "13.4.1",
+    "@dereekb/date": "13.4.1",
+    "@dereekb/firebase": "13.4.1",
+    "@dereekb/firebase-server": "13.4.1",
+    "@dereekb/model": "13.4.1",
+    "@dereekb/nestjs": "13.4.1",
+    "@dereekb/rxjs": "13.4.1",
+    "@dereekb/util": "13.4.1",
     "@nestjs/common": "^11.1.16",
     "@nestjs/config": "^4.0.3",
     "archiver": "^7.0.0",

package/oidc/package.json

@@ -1,14 +1,21 @@
 {
   "name": "@dereekb/firebase-server/oidc",
-  "version": "13.3.1",
+  "version": "13.4.1",
   "peerDependencies": {
-    "@dereekb/date": "13.3.1",
-    "@dereekb/model": "13.3.1",
-    "@dereekb/nestjs": "13.3.1",
-    "@dereekb/rxjs": "13.3.1",
-    "@dereekb/firebase": "13.3.1",
-    "@dereekb/util": "13.3.1",
-    "@dereekb/zoho": "13.3.1",
+    "@dereekb/analytics": "13.4.1",
+    "@dereekb/date": "13.4.1",
+    "@dereekb/firebase": "13.4.1",
+    "@dereekb/firebase-server": "13.4.1",
+    "@dereekb/model": "13.4.1",
+    "@dereekb/nestjs": "13.4.1",
+    "@dereekb/rxjs": "13.4.1",
+    "@dereekb/util": "13.4.1",
+    "@dereekb/zoho": "13.4.1",
+    "@nestjs/common": "^11.1.16",
+    "@nestjs/config": "^4.0.3",
+    "express": "^5.0.0",
+    "firebase-admin": "^13.0.0",
+    "nanoid": "^5.1.7",
     "oidc-provider": "^9.7.0"
   },
   "exports": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dereekb/firebase-server",
-  "version": "13.3.1",
+  "version": "13.4.1",
   "exports": {
     "./test": {
       "module": "./test/index.esm.js",
@@ -43,14 +43,15 @@
   "main": "./index.cjs.js",
   "types": "./src/index.d.ts",
   "peerDependencies": {
-    "@dereekb/date": "13.3.1",
-    "@dereekb/dbx-core": "13.3.1",
-    "@dereekb/firebase": "13.3.1",
-    "@dereekb/model": "13.3.1",
-    "@dereekb/nestjs": "13.3.1",
-    "@dereekb/rxjs": "13.3.1",
-    "@dereekb/util": "13.3.1",
-    "@dereekb/zoho": "13.3.1",
+    "@dereekb/analytics": "13.4.1",
+    "@dereekb/date": "13.4.1",
+    "@dereekb/dbx-core": "13.4.1",
+    "@dereekb/firebase": "13.4.1",
+    "@dereekb/model": "13.4.1",
+    "@dereekb/nestjs": "13.4.1",
+    "@dereekb/rxjs": "13.4.1",
+    "@dereekb/util": "13.4.1",
+    "@dereekb/zoho": "13.4.1",
     "@google-cloud/firestore": "^7.11.6",
     "@google-cloud/storage": "^7.19.0",
     "@nestjs/common": "^11.1.16",
@@ -65,9 +66,10 @@
     "firebase-admin": "^13.0.0",
     "firebase-functions": "^7.0.0",
     "firebase-functions-test": "3.4.1",
-    "oidc-provider": "^9.7.0",
     "jsonwebtoken": "^9.0.0",
     "make-error": "^1.3.0",
+    "nanoid": "^5.1.7",
+    "oidc-provider": "^9.7.0",
     "rxjs": "^7.8.0",
     "ts-essentials": "^10.0.0"
   },

package/src/lib/auth/auth.service.d.ts

@@ -322,7 +322,10 @@ export interface FirebaseServerAuthInitializeNewUser<D = unknown> {
      */
     readonly email?: EmailAddress;
     /**
-     * Phone for the new user, if applicable.
+     * Phone for the new user, if applicable. Must be a valid {@link E164PhoneNumber} (e.g. `'+17206620850'`).
+     *
+     * Firebase Auth requires E.164 format. If the value is not valid, {@link FirebaseServerAuthUserBadInputError}
+     * is thrown with code `auth/invalid-phone-number`.
      */
     readonly phone?: E164PhoneNumber;
     /**

package/src/lib/auth/auth.service.error.d.ts

@@ -1,4 +1,50 @@
+import { type FirebaseErrorCode } from '@dereekb/firebase';
 import { BaseError } from 'make-error';
+/**
+ * The type of identifier that caused the user-already-exists conflict.
+ */
+export type FirebaseServerAuthUserExistsErrorIdentifierType = 'phone' | 'email';
+/**
+ * Thrown by {@link AbstractFirebaseServerNewUserService.createNewUser} when Firebase Auth rejects
+ * user creation because the provided phone number or email is already associated with another account.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await newUserService.initializeNewUser({ email, phone });
+ * } catch (e) {
+ *   if (e instanceof FirebaseServerAuthUserExistsError && e.identifierType === 'phone') {
+ *     const existingUser = await auth.getUserByPhoneNumber(e.identifierValue);
+ *   }
+ * }
+ * ```
+ */
+export declare class FirebaseServerAuthUserExistsError extends BaseError {
+    readonly code: FirebaseErrorCode;
+    readonly identifierType: FirebaseServerAuthUserExistsErrorIdentifierType;
+    readonly identifierValue: string;
+    constructor(code: FirebaseErrorCode, identifierType: FirebaseServerAuthUserExistsErrorIdentifierType, identifierValue: string);
+}
+/**
+ * Thrown by {@link AbstractFirebaseServerNewUserService.createNewUser} when Firebase Auth rejects
+ * user creation due to invalid input (e.g., a malformed phone number).
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await newUserService.initializeNewUser({ email, phone: 'not-e164' });
+ * } catch (e) {
+ *   if (e instanceof FirebaseServerAuthUserBadInputError) {
+ *     console.log(`Bad input (${e.code}): ${e.inputValue}`);
+ *   }
+ * }
+ * ```
+ */
+export declare class FirebaseServerAuthUserBadInputError extends BaseError {
+    readonly code: FirebaseErrorCode;
+    readonly inputValue: string;
+    constructor(code: FirebaseErrorCode, inputValue: string, message?: string);
+}
 /**
  * Thrown by sendSetupDetails() if the user has no setup configuration available, meaning they probably already have accepted their invite or is in an invalid state.
  */

package/src/lib/env/env.config.d.ts

@@ -1,12 +1,13 @@
 import { type InjectionToken, type Provider } from '@nestjs/common';
 import { type ServerEnvironmentConfig } from '@dereekb/nestjs';
+import { type WebsiteUrlWithPrefix } from '@dereekb/util';
 /**
  * Extension of ServerEnvironmentConfig for Firebase server applications.
  *
  * Requires appUrl to be provided.
  */
 export interface FirebaseServerEnvironmentConfig extends ServerEnvironmentConfig {
-    readonly appUrl: string;
+    readonly appUrl: WebsiteUrlWithPrefix;
 }
 /**
  * Token to access a configured FirebaseServerEnvironmentServiceConfig for the app.

package/src/lib/function/error.d.ts

@@ -1,4 +1,4 @@
-import { type ErrorMessageOrPartialServerError, type ServerError, type StringErrorCode, type ThrowErrorFunction } from '@dereekb/util';
+import { type ErrorMessageOrPartialServerError, type Maybe, type ServerError, type StringErrorCode, type ThrowErrorFunction } from '@dereekb/util';
 import type * as admin from 'firebase-admin';
 import { type FirebaseErrorCode } from '@dereekb/firebase';
 import { HttpsError } from 'firebase-functions/https';
@@ -119,15 +119,15 @@ export declare function firebaseServerErrorInfo(e: unknown): FirebaseServerError
 /**
  * Returns a tuple of [firebaseErrorCode, errorInfo] for pattern-matching on Firebase error codes.
  */
-export declare function firebaseServerErrorInfoCodePair(e: unknown): [FirebaseErrorCode | undefined, FirebaseServerErrorInfo];
+export declare function firebaseServerErrorInfoCodePair(e: unknown): [Maybe<FirebaseErrorCode>, FirebaseServerErrorInfo];
 /**
  * Returns a tuple of [serverError, errorInfo] for pattern-matching on embedded server error details.
  */
-export declare function firebaseServerErrorInfoServerErrorPair(e: unknown): [ServerError | undefined, FirebaseServerErrorInfo];
+export declare function firebaseServerErrorInfoServerErrorPair(e: unknown): [Maybe<ServerError>, FirebaseServerErrorInfo];
 /**
  * Returns a tuple of [serverErrorCode, errorInfo] for pattern-matching on server error string codes.
  */
-export declare function firebaseServerErrorInfoServerErrorCodePair(e: unknown): [StringErrorCode | undefined, FirebaseServerErrorInfo];
+export declare function firebaseServerErrorInfoServerErrorCodePair(e: unknown): [Maybe<StringErrorCode>, FirebaseServerErrorInfo];
 /**
  * Handles a caught error if it is a Firebase Admin error, passing it to the given handler function.
  *

package/src/lib/nest/analytics/analytics.module.d.ts

@@ -0,0 +1,38 @@
+import { type ModuleMetadata } from '@nestjs/common';
+import { type Maybe } from '@dereekb/util';
+/**
+ * Configuration for {@link appAnalyticsModuleMetadata}.
+ */
+export interface ProvideAppAnalyticsMetadataConfig extends Pick<ModuleMetadata, 'imports' | 'exports' | 'providers'> {
+    /**
+     * Optional dependency module that provides a {@link FirebaseServerAnalyticsServiceListener} implementation.
+     *
+     * If omitted, the {@link FirebaseServerAnalyticsService} falls back to a no-op listener.
+     *
+     * @example
+     * ```ts
+     * appAnalyticsModuleMetadata({
+     *   dependencyModule: FirebaseServerAnalyticsSegmentModule
+     * })
+     * ```
+     */
+    readonly dependencyModule?: Maybe<Required<ModuleMetadata>['imports'][0]>;
+}
+/**
+ * Generates NestJS {@link ModuleMetadata} for an app's analytics module.
+ *
+ * Provides {@link FirebaseServerAnalyticsService} and registers it as the
+ * {@link ON_CALL_MODEL_ANALYTICS_SERVICE} token for the onCall dispatch chain.
+ *
+ * @param config - the configuration including an optional dependency module and additional providers
+ * @returns module metadata ready for use with `@Module()`
+ *
+ * @example
+ * ```ts
+ * @Module(appAnalyticsModuleMetadata({
+ *   dependencyModule: FirebaseServerAnalyticsSegmentModule
+ * }))
+ * export class AppAnalyticsModule {}
+ * ```
+ */
+export declare function appAnalyticsModuleMetadata(config: ProvideAppAnalyticsMetadataConfig): ModuleMetadata;

package/src/lib/nest/analytics/analytics.service.d.ts

@@ -0,0 +1,40 @@
+import { type AnalyticsEvent, type AnalyticsEventData, type AnalyticsEventName, type AnalyticsUser } from '@dereekb/analytics';
+import { type Maybe } from '@dereekb/util';
+import { type OnCallModelAnalyticsEvent, OnCallModelAnalyticsService } from '../model/analytics.handler';
+import { FirebaseServerAnalyticsServiceListener } from './analytics.service.listener';
+/**
+ * Reference interface for injecting {@link FirebaseServerAnalyticsService}.
+ */
+export interface FirebaseServerAnalyticsServiceRef {
+    readonly analyticsService: FirebaseServerAnalyticsService;
+}
+/**
+ * Central server-side analytics service that delegates events to a registered {@link FirebaseServerAnalyticsServiceListener}.
+ *
+ * Extends {@link OnCallModelAnalyticsService} for CRUD lifecycle events and adds general-purpose
+ * methods (`sendEventData`, `sendEventType`, `sendEvent`, `sendUserPropertiesEvent`) mirroring the
+ * Angular {@link DbxAnalyticsService}.
+ *
+ * If no listener is provided via DI, a no-op listener is used and a warning is logged.
+ *
+ * Provided via {@link appAnalyticsModuleMetadata} with an optional dependency module
+ * (e.g., {@link FirebaseServerAnalyticsSegmentModule}).
+ *
+ * @example
+ * ```ts
+ * // Send a custom event from a NestJS service
+ * analyticsService.sendEventData(uid, 'Report Generated', { reportId: 'rpt_123' });
+ *
+ * // Send user properties update
+ * analyticsService.sendUserPropertiesEvent({ user: uid, properties: { plan: 'premium' } });
+ * ```
+ */
+export declare class FirebaseServerAnalyticsService extends OnCallModelAnalyticsService {
+    private readonly _listener;
+    constructor(listener: FirebaseServerAnalyticsServiceListener);
+    handleOnCallAnalyticsEvent(event: OnCallModelAnalyticsEvent): void;
+    sendEventData(userId: Maybe<string>, name: AnalyticsEventName, data: AnalyticsEventData): void;
+    sendEventType(userId: Maybe<string>, eventType: AnalyticsEventName): void;
+    sendEvent(userId: Maybe<string>, event: AnalyticsEvent): void;
+    sendUserPropertiesEvent(user: AnalyticsUser): void;
+}

package/src/lib/nest/analytics/analytics.service.listener.d.ts

@@ -0,0 +1,50 @@
+import { type AnalyticsEvent, type AnalyticsEventData, type AnalyticsEventName, type AnalyticsUser } from '@dereekb/analytics';
+import { type Maybe } from '@dereekb/util';
+import { type OnCallModelAnalyticsEvent } from '../model/analytics.handler';
+/**
+ * Listener for {@link FirebaseServerAnalyticsService}.
+ * Events are forwarded from FirebaseServerAnalyticsService to this listener
+ * for processing by an analytics provider (e.g., Segment).
+ */
+export declare abstract class FirebaseServerAnalyticsServiceListener {
+    /**
+     * Handles a structured analytics event from the onCall CRUD dispatch chain.
+     *
+     * @param event - the lifecycle event containing call context, model type, and properties
+     */
+    abstract handleOnCallAnalyticsEvent(event: OnCallModelAnalyticsEvent): void;
+    /**
+     * Sends a named analytics event with a data payload.
+     *
+     * @param userId - the user to associate with the event, or nullish to skip
+     * @param name - the event name (e.g., `'Item Purchased'`)
+     * @param data - key-value data attached to the event
+     */
+    abstract sendEventData(userId: Maybe<string>, name: AnalyticsEventName, data: AnalyticsEventData): void;
+    /**
+     * Sends a named analytics event with no additional data.
+     *
+     * @param userId - the user to associate with the event, or nullish to skip
+     * @param eventType - the event name to track
+     */
+    abstract sendEventType(userId: Maybe<string>, eventType: AnalyticsEventName): void;
+    /**
+     * Sends a fully constructed {@link AnalyticsEvent} object.
+     *
+     * @param userId - the user to associate with the event, or nullish to skip
+     * @param event - the event containing name, optional value, and data
+     */
+    abstract sendEvent(userId: Maybe<string>, event: AnalyticsEvent): void;
+    /**
+     * Sends a user properties/traits update to the analytics provider (e.g., Segment `identify()`).
+     *
+     * @param user - the user whose properties are being synced
+     */
+    abstract sendUserPropertiesEvent(user: AnalyticsUser): void;
+}
+/**
+ * Creates a default no-op {@link FirebaseServerAnalyticsServiceListener}.
+ *
+ * Used when no analytics provider is configured. All methods are no-ops.
+ */
+export declare function noopFirebaseServerAnalyticsServiceListener(): FirebaseServerAnalyticsServiceListener;

package/src/lib/nest/analytics/index.d.ts

@@ -0,0 +1,5 @@
+export * from './analytics.module';
+export * from './analytics.service';
+export * from './analytics.service.listener';
+export * from './providers/segment.listener.service';
+export * from './providers/segment.analytics.module';

package/src/lib/nest/analytics/providers/segment.analytics.module.d.ts

@@ -0,0 +1,7 @@
+/**
+ * A pre-configured dependency module that can be imported into the {@link appAnalyticsModuleMetadata} call.
+ *
+ * This module provides the {@link FirebaseServerAnalyticsSegmentListenerService} as the {@link FirebaseServerAnalyticsServiceListener} implementation and exports {@link SegmentServiceModule} for use in the app.
+ */
+export declare class FirebaseServerAnalyticsSegmentModule {
+}

package/src/lib/nest/analytics/providers/segment.listener.service.d.ts

@@ -0,0 +1,24 @@
+import { type AnalyticsEvent, type AnalyticsEventData, type AnalyticsEventName, type AnalyticsUser } from '@dereekb/analytics';
+import { type Maybe } from '@dereekb/util';
+import { SegmentService } from '@dereekb/analytics/nestjs';
+import { FirebaseServerAnalyticsServiceListener } from '../analytics.service.listener';
+import { type OnCallModelAnalyticsEvent } from '../../model/analytics.handler';
+/**
+ * Segment implementation of {@link FirebaseServerAnalyticsServiceListener}.
+ *
+ * Routes analytics events to the {@link SegmentService}:
+ * - CRUD lifecycle events → `tryTrack()` with call/model/lifecycle context as properties
+ * - General events (`sendEventData`, `sendEventType`, `sendEvent`) → `tryTrack()`
+ * - User properties (`sendUserPropertiesEvent`) → `identify()`
+ *
+ * Provided by {@link FirebaseServerAnalyticsSegmentModule}.
+ */
+export declare class FirebaseServerAnalyticsSegmentListenerService extends FirebaseServerAnalyticsServiceListener {
+    private readonly _segmentService;
+    constructor(_segmentService: SegmentService);
+    handleOnCallAnalyticsEvent(event: OnCallModelAnalyticsEvent): void;
+    sendEventData(userId: Maybe<string>, name: AnalyticsEventName, data: AnalyticsEventData): void;
+    sendEventType(userId: Maybe<string>, eventType: AnalyticsEventName): void;
+    sendEvent(userId: Maybe<string>, event: AnalyticsEvent): void;
+    sendUserPropertiesEvent(user: AnalyticsUser): void;
+}

package/src/lib/nest/controller/auth.context.server.d.ts

@@ -1,5 +1,6 @@
 import { type AuthData } from '../../type';
 import { type Request } from 'express';
+import { type FirebaseAuthUserId } from '@dereekb/firebase';
 /**
  * Minimum auth data shape shared by all server-side auth contexts.
  *
@@ -9,7 +10,7 @@ export interface FirebaseServerAuthData extends AuthData {
     /**
      * The authenticated user's UID.
      */
-    readonly uid: string;
+    readonly uid: FirebaseAuthUserId;
 }
 /**
  * Extends Express Request with an `auth` field for authenticated requests.

package/src/lib/nest/function/nest.d.ts

@@ -22,26 +22,30 @@ export type NestRef<N> = {
     readonly nest: N;
 };
 /**
- * Augments a request type with a typed nest context. This is the primary request shape used by
- * nest-integrated Firebase function handlers throughout the codebase.
+ * Augments a request type with a typed nest context and the raw {@link INestApplicationContext}.
+ *
+ * This is the primary request shape used by nest-integrated Firebase function handlers throughout the codebase.
+ * It extends {@link NestApplicationContextRequest} so that handlers always have access to both the
+ * typed domain context and the underlying NestJS application context.
  *
  * @typeParam N - The nest context type, typically an application-specific context class.
  * @typeParam R - The base request type to augment.
  */
-export type NestContextRequest<N, R> = R & {
+export type NestContextRequest<N, R> = NestApplicationContextRequest<R> & {
     readonly nest: N;
 };
 /**
  * Creates a new request object with the typed nest context spread into it.
  *
  * Unlike {@link injectNestApplicationContextIntoRequest}, this attaches a domain-specific context rather
- * than the raw NestJS application context.
+ * than the raw NestJS application context. The input request must already be a {@link NestApplicationContextRequest}
+ * so that the resulting {@link NestContextRequest} retains access to the raw application context.
  *
  * @param nest - The typed nest context to attach.
- * @param request - The base request to augment.
+ * @param request - The base request to augment (must include the nestApplication reference).
  * @returns A new object combining the request properties with the nest context.
  */
-export declare function injectNestIntoRequest<N, R>(nest: N, request: R): NestContextRequest<N, R>;
+export declare function injectNestIntoRequest<N, R>(nest: N, request: NestApplicationContextRequest<R>): NestContextRequest<N, R>;
 /**
  * Creates a new request object with the raw {@link INestApplicationContext} spread into it.
  *

package/src/lib/nest/function/schedule.d.ts

@@ -1,4 +1,4 @@
-import { type Minutes, type PromiseOrValue } from '@dereekb/util';
+import { type Minutes, type PromiseOrValue, type Seconds, type TimezoneString } from '@dereekb/util';
 import { type MakeNestContext, type NestApplicationFunctionFactory } from '../nest.provider';
 import { type NestApplicationContextRequest, type NestContextRequest } from './nest';
 /**
@@ -23,7 +23,7 @@ export interface OnScheduleConfig {
     /**
      * Optional timezone to specify.
      */
-    readonly timezone?: string;
+    readonly timezone?: TimezoneString;
     /**
      * The number of retry attempts for a failed run.
      */
@@ -31,15 +31,15 @@ export interface OnScheduleConfig {
     /**
      * The time limit for retrying.
      */
-    readonly maxRetrySeconds?: number;
+    readonly maxRetrySeconds?: Seconds;
     /**
      * The minimum time to wait before retying.
      */
-    readonly minBackoffSeconds?: number;
+    readonly minBackoffSeconds?: Seconds;
     /**
      * The maximum time to wait before retrying.
      */
-    readonly maxBackoffSeconds?: number;
+    readonly maxBackoffSeconds?: Seconds;
     /**
      * The time between will double max doublings times.
      */

package/src/lib/nest/index.d.ts

@@ -1,3 +1,4 @@
+export * from './analytics';
 export * from './auth';
 export * from './controller';
 export * from './development';

package/src/lib/nest/model/analytics.details.d.ts

@@ -0,0 +1,93 @@
+import { type OnCallModelAnalyticsService, type OnCallModelAnalyticsEvent } from './analytics.handler';
+import { type AuthData } from '../../type';
+import { type NestContextCallableRequestWithAuth } from '../function/nest';
+import { type ModelFirebaseCrudFunctionSpecifierRef, type FirebaseAuthUserId, type OnCallFunctionType, type FirestoreModelType, type ModelFirebaseCrudFunctionSpecifier } from '@dereekb/firebase';
+import { type Maybe } from '@dereekb/util';
+/**
+ * Per-invocation analytics emitter passed to lifecycle callbacks.
+ *
+ * Pre-binds the analytics service, dispatch context, and lifecycle stage so callbacks
+ * can send events with convenience methods without manually constructing full event objects.
+ *
+ * Analogous to how {@link DbxAnalyticsService} is passed to {@link DbxActionAnalyticsConfig} callbacks.
+ */
+export interface OnCallAnalyticsEmitter {
+    readonly service: OnCallModelAnalyticsService;
+    readonly context: OnCallAnalyticsContext;
+    readonly lifecycle: OnCallModelAnalyticsEvent['lifecycle'];
+    /**
+     * Send a named event with optional properties.
+     * Context (call, modelType, specifier, uid, lifecycle) is auto-filled from the dispatch context.
+     */
+    sendEvent(event: string, properties?: Record<string, any>): void;
+    /**
+     * Send a named event type with no properties.
+     */
+    sendEventType(event: string): void;
+}
+/**
+ * Analytics lifecycle configuration for a single onCall model handler.
+ *
+ * Mirrors the frontend {@link DbxActionAnalyticsConfig} pattern: lifecycle callbacks
+ * receive an {@link OnCallAnalyticsEmitter} and the typed request, and are responsible
+ * for deciding what analytics events to emit.
+ *
+ * @typeParam R - The request type passed to the handler function.
+ * @typeParam O - The output/return type of the handler function.
+ */
+export interface OnCallModelFunctionAnalyticsDetails<R = any, O = any> {
+    /**
+     * Called before handler executes.
+     */
+    readonly onTriggered?: OnCallAnalyticsLifecycleFn<R, void>;
+    /**
+     * Called after successful handler completion.
+     */
+    readonly onSuccess?: OnCallAnalyticsLifecycleFn<R, O>;
+    /**
+     * Called when handler throws.
+     */
+    readonly onError?: OnCallAnalyticsErrorFn<R>;
+    /**
+     * Called always after handler completes (success or error).
+     */
+    readonly onComplete?: OnCallAnalyticsCompleteFn<R, O>;
+}
+/**
+ * Context available to the dispatch chain for building analytics emitters.
+ *
+ * Captured at the start of a handler invocation and used to auto-fill event fields
+ * (call, modelType, specifier, uid, auth) on every emitted {@link OnCallModelAnalyticsEvent}.
+ *
+ * @typeParam I - The input/request data type.
+ */
+export interface OnCallAnalyticsContext<I = any> {
+    /** The CRUD operation type (e.g., `'create'`, `'update'`). */
+    readonly call: OnCallFunctionType;
+    /** The model type being operated on (e.g., `'guestbook'`). */
+    readonly modelType: FirestoreModelType;
+    /** Optional operation specifier for variant handlers. */
+    readonly specifier: Maybe<ModelFirebaseCrudFunctionSpecifier>;
+    /** The Firebase Auth UID of the calling user. */
+    readonly uid?: FirebaseAuthUserId;
+    /** The full Firebase Auth context. */
+    readonly auth?: AuthData;
+    /** The typed request data. */
+    readonly data?: I;
+    /** The full NestContext callable request with auth and specifier. */
+    readonly request: NestContextCallableRequestWithAuth<unknown, I> & ModelFirebaseCrudFunctionSpecifierRef;
+}
+/**
+ * Lifecycle function for onTriggered/onSuccess.
+ *
+ * Receives the {@link OnCallAnalyticsEmitter} for sending events and the typed request.
+ */
+export type OnCallAnalyticsLifecycleFn<R, O> = (emitter: OnCallAnalyticsEmitter, request: R, result?: O) => void;
+/**
+ * Lifecycle function for onError.
+ */
+export type OnCallAnalyticsErrorFn<R> = (emitter: OnCallAnalyticsEmitter, request: R, error: unknown) => void;
+/**
+ * Lifecycle function for onComplete.
+ */
+export type OnCallAnalyticsCompleteFn<R, O> = (emitter: OnCallAnalyticsEmitter, request: R, result?: O, error?: unknown) => void;