@dereekb/firebase-server 13.13.0 → 13.14.0

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

@@ -1,4 +1,4 @@
-import { type AuthRole, type Maybe } from '@dereekb/util';
+import { type AuthRole, type Maybe, type PromiseOrValue } from '@dereekb/util';
 import { type OnCallFunctionType, type OnCallTypedModelParams, type FirestoreModelType, type ModelFirebaseCrudFunctionSpecifier } from '@dereekb/firebase';
 import { type FirebaseServerAuthData } from '../controller/auth.context.server';
 import { type OnCallModelFunctionAnalyticsDetails } from './analytics.details';
@@ -132,43 +132,40 @@ export interface McpToolDetailsBuilderResult {
  */
 export type McpToolDetailsBuilder = (input: McpToolDetailsBuilderInput) => McpToolDetailsBuilderResult;
 /**
- * MCP-specific customization for a model function.
- *
- * When omitted, defaults are auto-generated from the handler's position in the call model tree.
+ * Context object passed as the second argument to the {@link OnCallModelFunctionMcpDetails}
+ * response tiers (`summarizeResponse` / `formatResponse`).
  *
- * Response formatting uses a tiered system:
- * - **Tier 1 (default)**: Auto-generated summary from the result shape. No config needed.
- * - **Tier 2**: Provide {@link summarizeResponse} to return a natural language string. The framework wraps it into MCP content + structuredContent automatically.
- * - **Tier 3**: Provide {@link formatResponse} for complete control over the MCP response content blocks.
+ * Exposes both the raw, pre-mapped handler result and the effective value the tiers operate on,
+ * plus the dispatched params — so a formatter can reach the original data even when a
+ * `mapSuccessfulResult` mapper has already trimmed/enriched it.
  *
- * Resolution order: formatResponse > summarizeResponse > auto-generated default.
+ * @typeParam R - The raw handler return type.
+ * @typeParam V - The effective value type (the mapper's output, or `R` when no mapper is defined).
  */
-export interface OnCallModelFunctionMcpDetails {
+export interface McpToolResponseContext<R = unknown, V = R> {
     /**
-     * Custom tool name override.
+     * The raw, pre-mapped handler result.
      */
-    readonly name?: string;
+    readonly raw: R;
     /**
-     * Tier 2 response formatter: returns a natural language summary string.
-     *
-     * The framework wraps the string into a text content block and attaches the raw result
-     * as structuredContent automatically.
-     *
-     * @param result - The handler's return value.
-     * @param params - The OnCallTypedModelParams that were dispatched.
-     * @returns A human-readable summary of the operation result.
+     * The effective value: the `mapSuccessfulResult` output when a mapper is defined, otherwise the
+     * raw result. Always identical to the tier callback's first argument.
      */
-    readonly summarizeResponse?: (result: unknown, params: OnCallTypedModelParams) => McpToolResponseSummary;
+    readonly value: V;
     /**
-     * Tier 3 response formatter: complete control over the MCP tool response.
-     *
-     * When provided, takes precedence over {@link summarizeResponse} and the auto-generated default.
-     *
-     * @param result - The handler's return value.
-     * @param params - The OnCallTypedModelParams that were dispatched.
-     * @returns The full MCP tool response content.
+     * The OnCallTypedModelParams that were dispatched.
      */
-    readonly formatResponse?: (result: unknown, params: OnCallTypedModelParams) => McpToolResponseContent;
+    readonly params: OnCallTypedModelParams;
+}
+/**
+ * Fields shared by both {@link OnCallModelFunctionMcpDetails} variants — everything that does not
+ * depend on the handler's result type.
+ */
+export interface OnCallModelFunctionMcpDetailsCommon {
+    /**
+     * Custom tool name override.
+     */
+    readonly name?: string;
     /**
      * Controls whether this handler's tool is advertised on `tools/list` for a given request.
      *
@@ -193,13 +190,101 @@ export interface OnCallModelFunctionMcpDetails {
      */
     readonly toolDetails?: McpToolDetailsBuilder;
 }
+/**
+ * MCP-details variant for handlers that do NOT remap their success result. The response tiers see
+ * the raw handler result `R` directly.
+ *
+ * @typeParam R - The raw handler return type.
+ */
+export interface BaseOnCallModelFunctionMcpDetails<R = unknown> extends OnCallModelFunctionMcpDetailsCommon {
+    /**
+     * Discriminant — absent on this variant. Keeps the {@link OnCallModelFunctionMcpDetails} union exclusive.
+     */
+    readonly mapSuccessfulResult?: never;
+    /**
+     * Tier 2 response formatter: returns a natural language summary string. The framework wraps the
+     * string into a text content block and exposes the result as `structuredContent` automatically.
+     *
+     * @param value - The handler's result (no mapper is defined on this variant, so this is the raw result).
+     * @param context - The {@link McpToolResponseContext} carrying the raw result + params.
+     * @returns A human-readable summary of the operation result.
+     */
+    readonly summarizeResponse?: (value: R, context: McpToolResponseContext<R, R>) => McpToolResponseSummary;
+    /**
+     * Tier 3 response formatter: complete control over the MCP tool response. Takes precedence over
+     * {@link summarizeResponse} and the auto-generated default.
+     *
+     * @param value - The handler's result (no mapper is defined on this variant, so this is the raw result).
+     * @param context - The {@link McpToolResponseContext} carrying the raw result + params.
+     * @returns The full MCP tool response content.
+     */
+    readonly formatResponse?: (value: R, context: McpToolResponseContext<R, R>) => McpToolResponseContent;
+}
+/**
+ * MCP-details variant for handlers that remap their success result before it is exposed via MCP.
+ *
+ * `mapSuccessfulResult` runs first (success path only, async-capable); the response tiers and the
+ * default Tier-1 path then operate on the mapped value `M`. `context.raw` still exposes the
+ * original `R`. Declare the mapped type in the model's `.api.ts` and tag the CRUD leaf with
+ * `@dbxModelApiMcpResult <TypeName>` so the generated MCP manifest output schema matches.
+ *
+ * @typeParam R - The raw handler return type.
+ * @typeParam M - The mapped result type exposed via MCP.
+ */
+export interface OnCallModelFunctionMcpDetailsWithMappedResult<R = unknown, M = unknown> extends OnCallModelFunctionMcpDetailsCommon {
+    /**
+     * Maps the handler's raw success result to the shape exposed via MCP. Async-capable. Runs before
+     * `summarizeResponse` / `formatResponse` / the default path, and only on success (errors are
+     * formatted separately).
+     *
+     * @param result - The handler's raw return value.
+     * @param params - The OnCallTypedModelParams that were dispatched.
+     * @returns The mapped value (or a promise of it).
+     */
+    readonly mapSuccessfulResult: (result: R, params: OnCallTypedModelParams) => PromiseOrValue<M>;
+    /**
+     * Tier 2 response formatter: returns a natural language summary string. The framework wraps the
+     * string into a text content block and exposes the mapped value as `structuredContent` automatically.
+     *
+     * @param value - The mapped result (the `mapSuccessfulResult` output).
+     * @param context - The {@link McpToolResponseContext} carrying both the raw + mapped values and params.
+     * @returns A human-readable summary of the operation result.
+     */
+    readonly summarizeResponse?: (value: M, context: McpToolResponseContext<R, M>) => McpToolResponseSummary;
+    /**
+     * Tier 3 response formatter: complete control over the MCP tool response. Takes precedence over
+     * {@link summarizeResponse} and the auto-generated default.
+     *
+     * @param value - The mapped result (the `mapSuccessfulResult` output).
+     * @param context - The {@link McpToolResponseContext} carrying both the raw + mapped values and params.
+     * @returns The full MCP tool response content.
+     */
+    readonly formatResponse?: (value: M, context: McpToolResponseContext<R, M>) => McpToolResponseContent;
+}
+/**
+ * MCP-specific customization for a model function.
+ *
+ * When omitted, defaults are auto-generated from the handler's position in the call model tree.
+ *
+ * Response formatting uses a tiered system, with an optional pre-map step:
+ * - **mapSuccessfulResult** (optional): remap the raw success result before the tiers run. See {@link OnCallModelFunctionMcpDetailsWithMappedResult}.
+ * - **Tier 1 (default)**: Auto-generated summary from the (possibly mapped) result shape. No config needed.
+ * - **Tier 2**: Provide `summarizeResponse` to return a natural language string. The framework wraps it into MCP content + structuredContent automatically.
+ * - **Tier 3**: Provide `formatResponse` for complete control over the MCP response content blocks.
+ *
+ * Resolution order: formatResponse > summarizeResponse > auto-generated default.
+ *
+ * @typeParam R - The raw handler return type.
+ * @typeParam M - The mapped result type exposed via MCP (when `mapSuccessfulResult` is used).
+ */
+export type OnCallModelFunctionMcpDetails<R = unknown, M = unknown> = BaseOnCallModelFunctionMcpDetails<R> | OnCallModelFunctionMcpDetailsWithMappedResult<R, M>;
 /**
  * API details metadata for a single model call handler function.
  *
  * Carries schema info (input/output types) and MCP-specific customization.
  * Attached to handler functions via withApiDetails().
  */
-export interface OnCallModelFunctionApiDetails {
+export interface OnCallModelFunctionApiDetails<R = unknown, M = unknown> {
     /**
      * The input parameter type. Must implement toJsonSchema() for MCP tool input schema generation.
      */
@@ -211,7 +296,7 @@ export interface OnCallModelFunctionApiDetails {
     /**
      * MCP-specific customization. Auto-generated if omitted.
      */
-    readonly mcp?: OnCallModelFunctionMcpDetails;
+    readonly mcp?: OnCallModelFunctionMcpDetails<R, M>;
     /**
      * Analytics lifecycle configuration for this handler.
      * When provided, the dispatch chain will call lifecycle hooks around handler execution.
@@ -305,7 +390,7 @@ export declare function isActualSpecifier(details: OnCallModelTypeApiDetails): b
  *
  * Combines API metadata, auth configuration, and the handler function into a single config object.
  */
-export interface WithApiDetailsConfig<F extends (...args: any[]) => any> extends OnCallModelFunctionApiDetails {
+export interface WithApiDetailsConfig<F extends (...args: any[]) => any> extends OnCallModelFunctionApiDetails<Awaited<ReturnType<F>>> {
     /**
      * When true, marks the handler as not requiring auth (equivalent to optionalAuthContext).
      * Sets `_requireAuth = false` on the function, allowing it to be called without auth data.

package/test/package.json

@@ -1,16 +1,16 @@
 {
   "name": "@dereekb/firebase-server/test",
-  "version": "13.13.0",
+  "version": "13.14.0",
   "peerDependencies": {
-    "@dereekb/analytics": "13.13.0",
-    "@dereekb/date": "13.13.0",
-    "@dereekb/firebase": "13.13.0",
-    "@dereekb/firebase-server": "13.13.0",
-    "@dereekb/firebase-server/oidc": "13.13.0",
-    "@dereekb/model": "13.13.0",
-    "@dereekb/nestjs": "13.13.0",
-    "@dereekb/rxjs": "13.13.0",
-    "@dereekb/util": "13.13.0",
+    "@dereekb/analytics": "13.14.0",
+    "@dereekb/date": "13.14.0",
+    "@dereekb/firebase": "13.14.0",
+    "@dereekb/firebase-server": "13.14.0",
+    "@dereekb/firebase-server/oidc": "13.14.0",
+    "@dereekb/model": "13.14.0",
+    "@dereekb/nestjs": "13.14.0",
+    "@dereekb/rxjs": "13.14.0",
+    "@dereekb/util": "13.14.0",
     "@google-cloud/firestore": "^7.11.6",
     "@google-cloud/storage": "^7.19.0",
     "@nestjs/common": "^11.1.19",
@@ -23,7 +23,7 @@
     "supertest": "^7.2.2"
   },
   "devDependencies": {
-    "@dereekb/nestjs": "13.13.0"
+    "@dereekb/nestjs": "13.14.0"
   },
   "exports": {
     "./package.json": "./package.json",

package/twilio/package.json

@@ -1,14 +1,14 @@
 {
   "name": "@dereekb/firebase-server/twilio",
-  "version": "13.13.0",
+  "version": "13.14.0",
   "peerDependencies": {
-    "@dereekb/date": "13.13.0",
-    "@dereekb/firebase": "13.13.0",
-    "@dereekb/firebase-server": "13.13.0",
-    "@dereekb/model": "13.13.0",
-    "@dereekb/nestjs": "13.13.0",
-    "@dereekb/rxjs": "13.13.0",
-    "@dereekb/util": "13.13.0"
+    "@dereekb/date": "13.14.0",
+    "@dereekb/firebase": "13.14.0",
+    "@dereekb/firebase-server": "13.14.0",
+    "@dereekb/model": "13.14.0",
+    "@dereekb/nestjs": "13.14.0",
+    "@dereekb/rxjs": "13.14.0",
+    "@dereekb/util": "13.14.0"
   },
   "exports": {
     "./package.json": "./package.json",

package/zoho/package.json

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