@dereekb/firebase-server 13.12.9 → 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/index.cjs.js

@@ -4922,20 +4922,28 @@ function _ts_generator$1(thisArg, body) {
 }
 /**
  * Resolves the scopes string from config, or falls back to all registered scopes
- * from `OidcAccountService.allRegisteredScopes`.
+ * from the provider config — excluding any `adminOnlyScopes`.
+ *
+ * Admin-only scopes (e.g. `token.service`) are dropped from the default "all scopes" request because
+ * the provider hard-rejects them for non-admin users, and this default flow logs in an arbitrary
+ * (often non-admin) user. Tests that need an admin-only scope pass it explicitly via `config.scopes`.
  *
  * @param nestApp - Initialized NestJS application used to resolve {@link OidcAccountService} when no scopes override is given.
  * @param config - Optional flow config; when `config.scopes` is set, it is returned verbatim.
  * @returns The space-separated scope string to pass to the `/oidc/auth` endpoint.
  */ function resolveScopes(nestApp, config) {
     return _async_to_generator$1(function() {
-        var result, accountService;
+        var result, _providerConfig_adminOnlyScopes, accountService, providerConfig, adminOnlyScopes;
         return _ts_generator$1(this, function(_state) {
             if (config === null || config === void 0 ? void 0 : config.scopes) {
                 result = config.scopes;
             } else {
                 accountService = nestApp.get(oidc.OidcAccountService);
-                result = Object.keys(accountService.providerConfig.claims).join(' ');
+                providerConfig = accountService.providerConfig;
+                adminOnlyScopes = new Set((_providerConfig_adminOnlyScopes = providerConfig.adminOnlyScopes) !== null && _providerConfig_adminOnlyScopes !== void 0 ? _providerConfig_adminOnlyScopes : []);
+                result = Object.keys(providerConfig.claims).filter(function(scope) {
+                    return !adminOnlyScopes.has(scope);
+                }).join(' ');
             }
             return [
                 2,

package/test/index.esm.js

@@ -4921,20 +4921,28 @@ function _ts_generator$1(thisArg, body) {
 }
 /**
  * Resolves the scopes string from config, or falls back to all registered scopes
- * from `OidcAccountService.allRegisteredScopes`.
+ * from the provider config — excluding any `adminOnlyScopes`.
+ *
+ * Admin-only scopes (e.g. `token.service`) are dropped from the default "all scopes" request because
+ * the provider hard-rejects them for non-admin users, and this default flow logs in an arbitrary
+ * (often non-admin) user. Tests that need an admin-only scope pass it explicitly via `config.scopes`.
  *
  * @param nestApp - Initialized NestJS application used to resolve {@link OidcAccountService} when no scopes override is given.
  * @param config - Optional flow config; when `config.scopes` is set, it is returned verbatim.
  * @returns The space-separated scope string to pass to the `/oidc/auth` endpoint.
  */ function resolveScopes(nestApp, config) {
     return _async_to_generator$1(function() {
-        var result, accountService;
+        var result, _providerConfig_adminOnlyScopes, accountService, providerConfig, adminOnlyScopes;
         return _ts_generator$1(this, function(_state) {
             if (config === null || config === void 0 ? void 0 : config.scopes) {
                 result = config.scopes;
             } else {
                 accountService = nestApp.get(OidcAccountService);
-                result = Object.keys(accountService.providerConfig.claims).join(' ');
+                providerConfig = accountService.providerConfig;
+                adminOnlyScopes = new Set((_providerConfig_adminOnlyScopes = providerConfig.adminOnlyScopes) !== null && _providerConfig_adminOnlyScopes !== void 0 ? _providerConfig_adminOnlyScopes : []);
+                result = Object.keys(providerConfig.claims).filter(function(scope) {
+                    return !adminOnlyScopes.has(scope);
+                }).join(' ');
             }
             return [
                 2,

package/test/package.json

@@ -1,16 +1,16 @@
 {
   "name": "@dereekb/firebase-server/test",
-  "version": "13.12.9",
+  "version": "13.14.0",
   "peerDependencies": {
-    "@dereekb/analytics": "13.12.9",
-    "@dereekb/date": "13.12.9",
-    "@dereekb/firebase": "13.12.9",
-    "@dereekb/firebase-server": "13.12.9",
-    "@dereekb/firebase-server/oidc": "13.12.9",
-    "@dereekb/model": "13.12.9",
-    "@dereekb/nestjs": "13.12.9",
-    "@dereekb/rxjs": "13.12.9",
-    "@dereekb/util": "13.12.9",
+    "@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.12.9"
+    "@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.12.9",
+  "version": "13.14.0",
   "peerDependencies": {
-    "@dereekb/date": "13.12.9",
-    "@dereekb/firebase": "13.12.9",
-    "@dereekb/firebase-server": "13.12.9",
-    "@dereekb/model": "13.12.9",
-    "@dereekb/nestjs": "13.12.9",
-    "@dereekb/rxjs": "13.12.9",
-    "@dereekb/util": "13.12.9"
+    "@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.12.9",
+  "version": "13.14.0",
   "peerDependencies": {
-    "@dereekb/analytics": "13.12.9",
-    "@dereekb/date": "13.12.9",
-    "@dereekb/model": "13.12.9",
-    "@dereekb/nestjs": "13.12.9",
-    "@dereekb/rxjs": "13.12.9",
-    "@dereekb/firebase": "13.12.9",
-    "@dereekb/util": "13.12.9",
-    "@dereekb/zoho": "13.12.9"
+    "@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",