@dereekb/firebase-server 13.3.0 → 13.4.0

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

@@ -0,0 +1,56 @@
+import { type InjectionToken } from '@nestjs/common';
+import { type AuthData } from '../../type';
+import { type FirebaseAuthUserId, type OnCallFunctionType, type FirestoreModelType, type ModelFirebaseCrudFunctionSpecifier } from '@dereekb/firebase';
+import { type Maybe } from '@dereekb/util';
+/**
+ * Structured analytics event emitted by the onCall CRUD dispatch chain.
+ *
+ * Each event captures the full context of a handler invocation — the operation being performed,
+ * the model type, the lifecycle stage, the authenticated user, and any custom properties.
+ *
+ * Consumed by {@link OnCallModelAnalyticsService} and forwarded to provider-specific listeners.
+ */
+export interface OnCallModelAnalyticsEvent {
+    /** The event name describing what happened (e.g., `'Guestbook Created'`). */
+    readonly event: string;
+    /** The lifecycle stage at which this event was emitted. */
+    readonly lifecycle: 'triggered' | 'success' | 'error' | 'complete';
+    /** The CRUD operation type (e.g., `'create'`, `'update'`, `'delete'`). */
+    readonly call: OnCallFunctionType;
+    /** The model type being operated on (e.g., `'guestbook'`, `'profile'`). */
+    readonly modelType: FirestoreModelType;
+    /** Optional operation specifier for variant handlers (e.g., `'subscribeToNotifications'`). */
+    readonly specifier?: Maybe<ModelFirebaseCrudFunctionSpecifier>;
+    /** The Firebase Auth UID of the calling user, if authenticated. */
+    readonly uid?: Maybe<FirebaseAuthUserId>;
+    /** The full Firebase Auth context, if available. */
+    readonly auth?: Maybe<AuthData>;
+    /** The raw request object passed to the handler. */
+    readonly request?: Maybe<unknown>;
+    /** Custom key-value properties attached by lifecycle callbacks. */
+    readonly properties?: Maybe<Record<string, any>>;
+    /** The error object, if this event was emitted during the `'error'` lifecycle stage. */
+    readonly error?: Maybe<unknown>;
+}
+/**
+ * Abstract analytics service that apps implement to process analytics events.
+ *
+ * Analogous to {@link DbxAnalyticsService} on the frontend.
+ * Apps extend this class and provide it via {@link ON_CALL_MODEL_ANALYTICS_SERVICE}.
+ */
+export declare abstract class OnCallModelAnalyticsService {
+    abstract handleOnCallAnalyticsEvent(event: OnCallModelAnalyticsEvent): void;
+}
+/**
+ * Default injection token for the analytics service.
+ * Apps provide this in their NestJS module to enable analytics in the onCall dispatch chain.
+ */
+export declare const ON_CALL_MODEL_ANALYTICS_SERVICE: InjectionToken<OnCallModelAnalyticsService>;
+/**
+ * @deprecated Use {@link OnCallModelAnalyticsService} instead.
+ */
+export type OnCallModelAnalyticsHandler = OnCallModelAnalyticsService;
+/**
+ * @deprecated Use {@link ON_CALL_MODEL_ANALYTICS_SERVICE} instead.
+ */
+export declare const ON_CALL_MODEL_ANALYTICS_HANDLER: InjectionToken<OnCallModelAnalyticsService>;

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

@@ -1,4 +1,6 @@
 import { type Maybe } from '@dereekb/util';
+import { type OnCallFunctionType, type FirestoreModelType, type ModelFirebaseCrudFunctionSpecifier } from '@dereekb/firebase';
+import { type OnCallModelFunctionAnalyticsDetails } from './analytics.details';
 /**
  * Reference to a type that can produce a JSON Schema representation.
  *
@@ -43,6 +45,11 @@ export interface OnCallModelFunctionApiDetails {
      * MCP-specific customization. Auto-generated if omitted.
      */
     readonly mcp?: OnCallModelFunctionMcpDetails;
+    /**
+     * Analytics lifecycle configuration for this handler.
+     * When provided, the dispatch chain will call lifecycle hooks around handler execution.
+     */
+    readonly analytics?: OnCallModelFunctionAnalyticsDetails;
 }
 /**
  * Ref interface for objects (functions) that carry handler-level _apiDetails.
@@ -56,7 +63,8 @@ export interface OnCallModelFunctionApiDetailsRef {
  * Produced by onCallSpecifierHandler when its handlers carry _apiDetails.
  * Maps specifier keys (e.g., '_', 'username', 'fromUpload') to handler-level details.
  */
-export interface OnCallSpecifierApiDetails {
+export interface OnCallModelTypeApiDetails {
+    readonly isSpecifier: boolean;
     readonly specifiers: {
         readonly [key: string]: OnCallModelFunctionApiDetails | undefined;
     };
@@ -65,12 +73,13 @@ export interface OnCallSpecifierApiDetails {
  * API details aggregated at the CRUD model level.
  *
  * Produced by onCallCreateModel/onCallReadModel/etc.
- * Maps model type strings (e.g., 'profile', 'guestbook') to either handler-level
- * details (for direct handlers) or specifier-level details (for specifier handlers).
+ * Maps model type strings (e.g., 'profile', 'guestbook') to specifier-level details.
+ * Direct (non-specifier) handlers are wrapped with `isSpecifier: false` and their
+ * details placed under the `_` key.
  */
 export interface OnCallCrudModelApiDetails {
     readonly modelTypes: {
-        readonly [key: string]: OnCallModelFunctionApiDetails | OnCallSpecifierApiDetails | undefined;
+        readonly [key: string]: OnCallModelTypeApiDetails | undefined;
     };
 }
 /**
@@ -88,7 +97,7 @@ export interface OnCallModelApiDetails {
 /**
  * Union of all API details types at any aggregation level.
  */
-export type OnCallApiDetails = OnCallModelFunctionApiDetails | OnCallSpecifierApiDetails | OnCallCrudModelApiDetails | OnCallModelApiDetails;
+export type OnCallApiDetails = OnCallModelFunctionApiDetails | OnCallModelTypeApiDetails | OnCallCrudModelApiDetails | OnCallModelApiDetails;
 /**
  * Ref interface for functions at any level of the call model tree.
  */
@@ -98,7 +107,7 @@ export interface OnCallApiDetailsRef {
 /**
  * Whether the details are specifier-level (has specifiers map).
  */
-export declare function isOnCallSpecifierApiDetails(details: OnCallApiDetails): details is OnCallSpecifierApiDetails;
+export declare function isOnCallModelTypeApiDetails(details: OnCallApiDetails): details is OnCallModelTypeApiDetails;
 /**
  * Whether the details are CRUD-model-level (has modelTypes map).
  */
@@ -107,6 +116,11 @@ export declare function isOnCallCrudModelApiDetails(details: OnCallApiDetails):
  * Whether the details are handler-level (leaf node — no specifiers or modelTypes).
  */
 export declare function isOnCallHandlerApiDetails(details: OnCallApiDetails): details is OnCallModelFunctionApiDetails;
+/**
+ * Whether the specifier-level details represent a true specifier (multiple sub-operations)
+ * vs a wrapped direct handler (`isSpecifier: false`, details under `_`).
+ */
+export declare function isActualSpecifier(details: OnCallModelTypeApiDetails): boolean;
 /**
  * Configuration for withApiDetails().
  *
@@ -121,6 +135,14 @@ export interface WithApiDetailsConfig<F extends (...args: any[]) => any> extends
      * which would lose _apiDetails since optionalAuthContext creates a new wrapper function.
      */
     readonly optionalAuth?: boolean;
+    /**
+     * Optional analytics lifecycle configuration for this handler.
+     * When provided, the dispatch chain will call lifecycle hooks around handler execution.
+     *
+     * The request type and return type are inferred from the `fn` parameter, providing
+     * full type safety in lifecycle callbacks.
+     */
+    readonly analytics?: OnCallModelFunctionAnalyticsDetails<Parameters<F>[0], Awaited<ReturnType<F>>>;
     /**
      * The handler function.
      */
@@ -160,15 +182,15 @@ export declare function withApiDetails<F extends (...args: any[]) => any>(config
 /**
  * Reads _apiDetails from a function if present.
  */
-export declare function readApiDetails(fn: Maybe<OnCallApiDetailsRef>): OnCallApiDetails | undefined;
+export declare function readApiDetails(fn: Maybe<OnCallApiDetailsRef>): Maybe<OnCallApiDetails>;
 /**
  * Aggregates _apiDetails from a specifier handler config object.
  *
- * Returns OnCallSpecifierApiDetails if any handlers have _apiDetails, otherwise undefined.
+ * Returns OnCallModelTypeApiDetails if any handlers have _apiDetails, otherwise undefined.
  */
 export declare function aggregateSpecifierApiDetails(config: {
     readonly [key: string]: Maybe<OnCallApiDetailsRef>;
-}): OnCallSpecifierApiDetails | undefined;
+}): Maybe<OnCallModelTypeApiDetails>;
 /**
  * Aggregates _apiDetails from a model type map (used by onCallCreateModel, etc.).
  *
@@ -176,7 +198,7 @@ export declare function aggregateSpecifierApiDetails(config: {
  */
 export declare function aggregateCrudModelApiDetails(map: {
     readonly [key: string]: Maybe<OnCallApiDetailsRef>;
-}): OnCallCrudModelApiDetails | undefined;
+}): Maybe<OnCallCrudModelApiDetails>;
 /**
  * Aggregates _apiDetails from the top-level call model map.
  *
@@ -184,16 +206,19 @@ export declare function aggregateCrudModelApiDetails(map: {
  */
 export declare function aggregateModelApiDetails(map: {
     readonly [key: string]: Maybe<OnCallApiDetailsRef>;
-}): OnCallModelApiDetails | undefined;
+}): Maybe<OnCallModelApiDetails>;
 /**
- * Handler or specifier-level details for a single CRUD call on a model type.
+ * API details for a single CRUD call on a model type.
+ *
+ * Always {@link OnCallModelTypeApiDetails} — direct handlers are wrapped with
+ * `isSpecifier: false` and their details placed under the `_` key.
  */
-export type ModelCallApiDetails = OnCallModelFunctionApiDetails | OnCallSpecifierApiDetails;
+export type ModelCallApiDetails = OnCallModelTypeApiDetails;
 /**
  * CRUD calls available for a single model type.
  *
  * Keyed by call type ('create', 'read', 'update', 'delete').
- * Each value is either handler-level details (direct handler) or specifier-level details.
+ * Each value is specifier-level details (direct handlers wrapped with `isSpecifier: false`).
  */
 export interface ModelCallsApiDetails {
     readonly create?: ModelCallApiDetails;
@@ -246,4 +271,19 @@ export interface ModelApiDetailsModelEntry {
  * // details.models['profile'].calls.update => { specifiers: { _: {...}, username: {...} } }
  * ```
  */
-export declare function getModelApiDetails(callModelFn: Maybe<OnCallApiDetailsRef>): ModelApiDetailsResult | undefined;
+export declare function getModelApiDetails(callModelFn: Maybe<OnCallApiDetailsRef>): Maybe<ModelApiDetailsResult>;
+/**
+ * Resolves leaf-level analytics details from the aggregated _apiDetails tree.
+ *
+ * Walks: call → modelType → specifier (if specifier-level), then reads the `analytics`
+ * field from the handler-level {@link OnCallModelFunctionApiDetails}.
+ */
+export declare function resolveAnalyticsFromApiDetails(apiDetails: OnCallModelApiDetails, call: OnCallFunctionType, modelType: FirestoreModelType, specifier?: ModelFirebaseCrudFunctionSpecifier): Maybe<OnCallModelFunctionAnalyticsDetails>;
+/**
+ * @deprecated Use {@link OnCallModelTypeApiDetails} instead.
+ */
+export type OnCallSpecifierApiDetails = OnCallModelTypeApiDetails;
+/**
+ * @deprecated Use {@link isOnCallModelTypeApiDetails} instead.
+ */
+export declare const isOnCallSpecifierApiDetails: typeof isOnCallModelTypeApiDetails;

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

@@ -25,6 +25,11 @@ export interface OnCallModelConfig {
      * Throw to reject the request.
      */
     readonly preAssert?: AssertModelCrudRequestFunction<unknown, OnCallTypedModelParams>;
+    /**
+     * Override the analytics handler injection token.
+     * Default: {@link ON_CALL_MODEL_ANALYTICS_SERVICE}
+     */
+    readonly analyticsToken?: string;
 }
 /**
  * Top-level factory that creates a single callable function dispatching to CRUD operations.

package/src/lib/nest/model/crud.assert.function.d.ts

@@ -1,6 +1,6 @@
 import { type Maybe } from '@dereekb/util';
 import { type NestContextCallableRequest } from '../function/nest';
-import { type OnCallFunctionType } from '@dereekb/firebase';
+import { type OnCallFunctionType, type FirestoreModelType } from '@dereekb/firebase';
 /**
  * Discriminator for the category of CRUD operation being asserted.
  *
@@ -23,7 +23,7 @@ export interface AssertModelCrudRequestFunctionContext<N, I = unknown> {
     /** The CRUD call type string (e.g., 'create', 'read'). */
     readonly call: OnCallFunctionType;
     /** The Firestore model type being targeted (e.g., 'profile', 'guestbook'). */
-    readonly modelType: string;
+    readonly modelType: FirestoreModelType;
     /** The optional sub-operation specifier (e.g., 'username', 'fromUpload'). */
     readonly specifier: Maybe<string>;
 }

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

@@ -1,3 +1,6 @@
+export * from './analytics.details';
+export * from './analytics.emit';
+export * from './analytics.handler';
 export * from './api.details';
 export * from './permission.error';
 export * from './specifier.function';

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

@@ -58,7 +58,7 @@ export type OnCallSpecifierHandlerConfig<N> = {
  * delegated to each individual specifier handler.
  *
  * API details from all specifier handlers are aggregated into
- * {@link OnCallSpecifierApiDetails} for MCP introspection.
+ * {@link OnCallModelTypeApiDetails} for MCP introspection.
  *
  * @param config - Maps specifier keys to their handler functions.
  * @returns A callable function that dispatches by specifier, with aggregated API details.

package/test/package.json

@@ -1,24 +1,28 @@
 {
   "name": "@dereekb/firebase-server/test",
-  "version": "13.3.0",
+  "version": "13.4.0",
   "peerDependencies": {
-    "@dereekb/date": "13.3.0",
-    "@dereekb/firebase": "13.3.0",
-    "@dereekb/firebase-server": "13.3.0",
-    "@dereekb/model": "13.3.0",
-    "@dereekb/nestjs": "13.3.0",
-    "@dereekb/rxjs": "13.3.0",
-    "@dereekb/util": "13.3.0",
+    "@dereekb/analytics": "13.4.0",
+    "@dereekb/date": "13.4.0",
+    "@dereekb/firebase": "13.4.0",
+    "@dereekb/firebase-server": "13.4.0",
+    "@dereekb/model": "13.4.0",
+    "@dereekb/nestjs": "13.4.0",
+    "@dereekb/rxjs": "13.4.0",
+    "@dereekb/util": "13.4.0",
     "@google-cloud/firestore": "^7.11.6",
     "@google-cloud/storage": "^7.19.0",
-    "@nestjs/common": "^11.0.0",
-    "@nestjs/testing": "^11.0.0",
+    "@nestjs/common": "^11.1.16",
+    "@nestjs/testing": "^11.1.14",
     "firebase-admin": "^13.0.0",
     "firebase-functions": "^7.0.0",
     "firebase-functions-test": "3.4.1",
     "jsonwebtoken": "^9.0.0",
     "make-error": "^1.3.0"
   },
+  "devDependencies": {
+    "@dereekb/nestjs": "13.4.0"
+  },
   "exports": {
     "./package.json": "./package.json",
     ".": {

package/zoho/package.json

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