@dereekb/firebase-server 13.12.9 → 13.14.0

package/mcp/package.json

@@ -1,17 +1,17 @@
 {
   "name": "@dereekb/firebase-server/mcp",
-  "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/zoho": "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",
+    "@dereekb/zoho": "13.14.0",
     "@modelcontextprotocol/sdk": "1.29.0",
     "@nestjs/common": "^11.1.19",
     "@nestjs/core": "^11.1.19",

package/mcp/src/lib/service/mcp.manifest.d.ts

@@ -18,6 +18,12 @@ export interface McpManifestToolEntry {
     readonly description?: string;
     readonly inputSchema?: object;
     readonly outputSchema?: object;
+    /**
+     * Name of the MCP-mapped result interface (from `@dbxModelApiMcpResult`) when the output schema was
+     * built from a mapped type. Used at boot to detect a `mapSuccessfulResult` handler whose `.api.ts`
+     * leaf was never annotated (the output schema would then describe the raw, un-mapped result).
+     */
+    readonly mcpResultTypeName?: string;
 }
 /**
  * One persisted field on a {@link McpManifestModelEntry}.
@@ -55,6 +61,13 @@ export interface McpManifestModelEntry {
     readonly sourcePackage: string;
     readonly sourceFile: string;
     readonly fields: readonly McpManifestModelField[];
+    /**
+     * Per-model override of the model segment used in generated MCP tool names (from
+     * `@dbxModelMcpToolNameSegment` on the model interface). When present it replaces the model type
+     * in tool names (e.g. the collection prefix), trading readability for shorter names. Absent when
+     * the model omits the tag — names then use the model type.
+     */
+    readonly mcpToolNameSegment?: string;
     /**
      * Read posture declared by `@dbxModelRead <level>` on the model interface (`system` /
      * `owner` / `admin-only` / `permissions`). Absent when the source model omits the tag.

package/mcp/src/lib/service/mcp.response-formatter.d.ts

@@ -13,20 +13,24 @@ export declare const DEFAULT_VOID_MCP_SUCCESS_VALUE: {
 /**
  * Resolves a dispatch result + handler API details into the MCP `CallToolResult` shape.
  *
+ * When `mcp.mapSuccessfulResult` is set, the raw result is first mapped (async-capable) to the value
+ * exposed via MCP; the tiers and the default path then operate on the mapped value. The tier
+ * callbacks receive `(value, context)` where `context` carries both the raw + mapped values + params.
+ *
  * Three-tier resolution as documented on {@link OnCallModelFunctionApiDetails.mcp}:
  *
  * - **Tier 3** — when `mcp.formatResponse` is set, its return value is used verbatim.
  * - **Tier 2** — when `mcp.summarizeResponse` is set, the summary string is wrapped into a
- *   single text content block with the raw `result` exposed as `structuredContent`.
- * - **Tier 1** — default: JSON-stringify `result` as a single text content block, also
- *   exposing the raw value as `structuredContent`.
+ *   single text content block with the (mapped) value exposed as `structuredContent`.
+ * - **Tier 1** — default: JSON-stringify the (mapped) value as a single text content block, also
+ *   exposing it as `structuredContent`.
  *
- * @param result - The handler's return value.
+ * @param result - The handler's raw return value.
  * @param params - The {@link OnCallTypedModelParams} that were dispatched.
- * @param details - The handler-level API details (carries Tier 2/3 formatters).
+ * @param details - The handler-level API details (carries the mapper + Tier 2/3 formatters).
  * @returns The MCP tool response content.
  */
-export declare function formatMcpToolResponse(result: unknown, params: OnCallTypedModelParams, details: OnCallModelFunctionApiDetails | undefined): McpToolResponseContent;
+export declare function formatMcpToolResponse(result: unknown, params: OnCallTypedModelParams, details: OnCallModelFunctionApiDetails | undefined): Promise<McpToolResponseContent>;
 /**
  * Converts an error thrown from the dispatch chain into the MCP error response shape.
  *

package/mcp/src/lib/service/mcp.server.factory.d.ts

@@ -53,6 +53,30 @@ export declare class McpServerFactoryService {
      * @returns The cached or freshly-generated tool generation result.
      */
     private _resolveToolDefinitions;
+    /**
+     * Builds the per-model tool-name segment overrides from the loaded manifest's `models` catalog.
+     *
+     * Sourcing the segments from the manifest (rather than runtime config) keeps the runtime in
+     * agreement with the build-time manifest validation, which reads the same `mcpToolNameSegment`.
+     *
+     * @returns Naming options carrying the segment map, or `undefined` when no model declares one.
+     */
+    private _resolveToolNamingOptions;
+    /**
+     * Logs one skipped tool at the appropriate level: name-cap and collision skips are errors (they
+     * would otherwise break or shadow tools on the wire), the rest are warnings.
+     *
+     * @param skip - The skipped-tool report to log.
+     */
+    private _logSkip;
+    /**
+     * Renders a human-readable boot-time warning for an MCP-result mapping inconsistency between a
+     * handler's `mapSuccessfulResult` and the build-time manifest.
+     *
+     * @param warning - The tool-generation warning to describe.
+     * @returns The log line to emit at startup.
+     */
+    private _describeToolGenerationWarning;
     /**
      * Builds the list of statically-registered (non-callModel) MCP tools.
      *

package/mcp/src/lib/service/mcp.tool-generator.d.ts

@@ -1,4 +1,5 @@
 import { type Maybe } from '@dereekb/util';
+import { type KnownOnCallFunctionType } from '@dereekb/firebase';
 import { type ModelApiDetailsResult, type OnCallModelFunctionApiDetails, type FirebaseServerAuthData, type McpToolDetailsBuilder } from '@dereekb/firebase-server';
 import { type Request } from 'express';
 import { type CallToolResult } from '@modelcontextprotocol/sdk/types.js';
@@ -24,12 +25,14 @@ export interface McpToolDefinition {
     /**
      * Tool name advertised on `tools/list`.
      *
-     * Format: `<modelType>-<callType>` for default (`_`) specifiers,
-     * `<modelType>-<callType>-<specifier>` for non-default specifiers.
+     * Format: `<modelSegment>-<callType>` for default (`_`) specifiers; named specifiers drop the
+     * call-type segment (`<modelSegment>-<specifier>`) to stay short. When two visible tools would
+     * resolve to the same name, both are disambiguated with the abbreviated call type
+     * (`<modelSegment>-<abbrev>-<specifier>`); see {@link buildDisambiguatedMcpToolName}.
      *
      * @example 'guestbook-create'
-     * @example 'profile-update-username'
-     * @example 'storageFile-invoke-recomputeChecksums'
+     * @example 'profile-username'
+     * @example 'profile-u-username'
      */
     readonly name: string;
     /**
@@ -144,8 +147,15 @@ export interface JsonSchemaGenerationOptions {
 export declare const DEFAULT_JSON_SCHEMA_GENERATION_OPTIONS: JsonSchemaGenerationOptions;
 /**
  * Reason a tool was skipped during generation.
+ *
+ * - `missing_input_type` — the handler has no `inputType` to build a schema from.
+ * - `schema_generation_failed` — `toJsonSchema()` threw for the handler's `inputType`.
+ * - `name_too_long` — the resolved name exceeds {@link MCP_TOOL_NAME_MAX_LENGTH}; advertising it
+ *   would make remote clients reject the whole `tools/list` payload, so it is dropped.
+ * - `duplicate_name` — another already-registered visible tool resolved to the same name (e.g. two
+ *   specifiers collide once the call-type segment is dropped); the later tool is dropped.
  */
-export type McpToolGenerationSkipReason = 'missing_input_type' | 'schema_generation_failed';
+export type McpToolGenerationSkipReason = 'missing_input_type' | 'schema_generation_failed' | 'name_too_long' | 'duplicate_name';
 /**
  * One tool that was skipped during generation.
  */
@@ -155,6 +165,35 @@ export interface McpToolGenerationSkip {
     readonly dispatch: McpToolDispatchTarget;
     readonly error?: Error;
 }
+/**
+ * Reason a generated tool's handler and build-time manifest disagree about MCP result mapping.
+ *
+ * - `mapper_without_mapped_manifest` — the handler declares `mcp.mapSuccessfulResult` but the
+ *   manifest entry was not built from a mapped result type, i.e. the `.api.ts` leaf is missing its
+ *   `@dbxModelApiMcpResult <TypeName>` annotation, so the advertised output schema describes the raw
+ *   (un-mapped) result.
+ * - `mapped_manifest_without_mapper` — the manifest entry is annotated for a mapped result but the
+ *   handler no longer declares `mapSuccessfulResult` (stale annotation).
+ *
+ * Both are runtime↔manifest consistency checks the build-time manifest renderer cannot perform on
+ * its own (it has the `.api.ts` annotation but not the handler's wired `mapSuccessfulResult`), so the
+ * runtime keeps them. Purely build-time-detectable conditions are deliberately *not* warned here to
+ * keep the server boot quiet:
+ * - Name length over the soft limit is surfaced by the manifest renderer, not at runtime (the hard
+ *   cap is still enforced as a `name_too_long` skip).
+ * - A preferred name that collided with another visible tool is re-derived with the abbreviated call
+ *   type ({@link buildDisambiguatedMcpToolName}) **silently** at runtime; the manifest renderer flags it.
+ */
+export type McpToolGenerationWarningReason = 'mapper_without_mapped_manifest' | 'mapped_manifest_without_mapper';
+/**
+ * One generated tool whose handler / manifest MCP-result mapping is inconsistent. The tool is still
+ * generated; the warning is surfaced so the caller can log the drift at startup.
+ */
+export interface McpToolGenerationWarning {
+    readonly toolName: string;
+    readonly reason: McpToolGenerationWarningReason;
+    readonly dispatch: McpToolDispatchTarget;
+}
 /**
  * Aggregated output of {@link generateMcpToolDefinitions}.
  */
@@ -174,6 +213,11 @@ export interface McpToolGenerationResult {
      * Surfaced so the caller can log them at startup.
      */
     readonly skipped: ReadonlyArray<McpToolGenerationSkip>;
+    /**
+     * Generated tools whose handler / manifest MCP-result mapping is inconsistent (only computed when a
+     * manifest is supplied). Surfaced so the caller can log the drift at startup.
+     */
+    readonly warnings: ReadonlyArray<McpToolGenerationWarning>;
 }
 interface BuildStaticWireEntryInput {
     readonly name: string;
@@ -196,17 +240,120 @@ export declare function buildStaticWireEntry(input: BuildStaticWireEntryInput):
  */
 export declare const DEFAULT_SPECIFIER_KEY = "_";
 /**
- * Builds the MCP tool name for a (modelType, callType, specifier) triple.
+ * Soft limit for an MCP tool name. Names longer than this still register, but the generator
+ * surfaces a `name_length_warning` so the drift toward the hard cap is visible at boot / build.
+ */
+export declare const MCP_TOOL_NAME_WARN_LENGTH = 55;
+/**
+ * Hard limit for an MCP tool name. Remote MCP clients reject a `tools/list` payload that contains
+ * any tool whose `name` exceeds this (`FrontendRemoteMcpToolDefinition.name: String should have at
+ * most 64 characters`), which fails the whole connection. Names over this are not registered.
+ */
+export declare const MCP_TOOL_NAME_MAX_LENGTH = 64;
+/**
+ * Severity of a tool name's length relative to {@link MCP_TOOL_NAME_WARN_LENGTH} /
+ * {@link MCP_TOOL_NAME_MAX_LENGTH}.
+ *
+ * - `error` — over the hard cap; the tool must not be advertised.
+ * - `warn` — over the soft limit but within the hard cap; advertised, but flagged.
+ * - `ok` — within the soft limit.
+ */
+export type McpToolNameLengthLevel = 'ok' | 'warn' | 'error';
+/**
+ * The outcome of validating a tool name's length.
+ */
+export interface McpToolNameValidation {
+    readonly name: string;
+    readonly length: number;
+    readonly level: McpToolNameLengthLevel;
+}
+/**
+ * Classifies a tool name's length against the soft/hard MCP name-length limits.
+ *
+ * Shared by the runtime generator and the build-time manifest renderer so both apply the
+ * same thresholds and never drift.
+ *
+ * @param name - The fully-resolved tool name (including any per-handler override).
+ * @returns The length classification — `error` over {@link MCP_TOOL_NAME_MAX_LENGTH}, `warn` over
+ *   {@link MCP_TOOL_NAME_WARN_LENGTH}, otherwise `ok`.
+ *
+ * @example
+ * ```ts
+ * validateMcpToolName('worker-create'); // { name: 'worker-create', length: 13, level: 'ok' }
+ * ```
+ */
+export declare function validateMcpToolName(name: string): McpToolNameValidation;
+/**
+ * Builds the MCP tool name for a (modelSegment, callType, specifier) triple.
  *
- * Apps can override the auto-generated name by setting
- * {@link OnCallModelFunctionApiDetails.mcp.name} on the handler.
+ * The call-type segment is only emitted for the default (`_`) specifier, where it carries the
+ * meaning (`worker-create`, `worker-update`). Named specifiers drop it — the specifier already
+ * disambiguates (`worker-syncCheckHqEmployee`), which keeps names short and within the MCP
+ * 64-character cap. Apps can override the whole name per handler via
+ * {@link OnCallModelFunctionApiDetails.mcp.name}.
  *
- * @param modelType - The Firestore model type (e.g., `storageFile`).
+ * This is the preferred (short) form. When two visible tools collide on it — two call types share a
+ * specifier once the call-type segment is dropped — the generator re-derives both names with
+ * {@link buildDisambiguatedMcpToolName} instead.
+ *
+ * @param modelSegment - The model segment of the name. Defaults to the model type, but may be a
+ *   shorter per-model override (e.g. the collection prefix) resolved by the caller.
  * @param callType - The call type (e.g., `invoke`).
  * @param specifier - The specifier key, or `_` / undefined for the default entry.
  * @returns The hyphen-joined tool name advertised on `tools/list`.
+ *
+ * @example
+ * ```ts
+ * buildMcpToolName('worker', 'create'); // 'worker-create'
+ * buildMcpToolName('worker', 'update', 'syncCheckHqEmployee'); // 'worker-syncCheckHqEmployee'
+ * ```
+ */
+export declare function buildMcpToolName(modelSegment: string, callType: string, specifier?: Maybe<string>): string;
+/**
+ * Single-character abbreviations for the standard CRUDQ + invoke call types, used to disambiguate
+ * colliding tool names without re-introducing the full call-type segment everywhere.
+ *
+ * @example
+ * ```ts
+ * MCP_CALL_TYPE_ABBREVIATIONS.update; // 'u'
+ * ```
+ */
+export declare const MCP_CALL_TYPE_ABBREVIATIONS: Readonly<Record<KnownOnCallFunctionType, string>>;
+/**
+ * Abbreviates a call type for use in a disambiguated tool name. Known CRUDQ + invoke types collapse
+ * to a single character; a custom call type is returned unchanged so the name stays unambiguous.
+ *
+ * @param callType - The call type / verb.
+ * @returns The single-character abbreviation, or the original string for a custom call type.
+ *
+ * @example
+ * ```ts
+ * abbreviateMcpCallType('update'); // 'u'
+ * abbreviateMcpCallType('recompute'); // 'recompute'
+ * ```
+ */
+export declare function abbreviateMcpCallType(callType: string): string;
+/**
+ * Builds the disambiguated MCP tool name for a (modelSegment, callType, specifier) triple — the form
+ * used only when the preferred {@link buildMcpToolName} output collides with another visible tool.
+ *
+ * Named specifiers re-insert the call type, abbreviated, between the segment and specifier
+ * (`worker-u-syncCheckHqEmployee`); since the two colliding tools differ only by call type, their
+ * abbreviations differ and the names no longer clash. Default (`_`) specifiers already carry the
+ * full call type, so they are returned in their {@link buildMcpToolName} form unchanged.
+ *
+ * @param modelSegment - The model segment of the name (model type, or a per-model override).
+ * @param callType - The call type / verb.
+ * @param specifier - The specifier key, or `_` / undefined for the default entry.
+ * @returns The hyphen-joined disambiguated tool name.
+ *
+ * @example
+ * ```ts
+ * buildDisambiguatedMcpToolName('worker', 'update', 'syncCheckHqEmployee'); // 'worker-u-syncCheckHqEmployee'
+ * buildDisambiguatedMcpToolName('worker', 'create'); // 'worker-create'
+ * ```
  */
-export declare function buildMcpToolName(modelType: string, callType: string, specifier?: Maybe<string>): string;
+export declare function buildDisambiguatedMcpToolName(modelSegment: string, callType: string, specifier?: Maybe<string>): string;
 /**
  * Builds the default description used when no build-time MCP manifest
  * entry is available for the (modelType, callType, specifier) tuple.
@@ -217,6 +364,32 @@ export declare function buildMcpToolName(modelType: string, callType: string, sp
  * @returns A human-readable fallback description for the tool.
  */
 export declare function buildDefaultMcpToolDescription(modelType: string, callType: string, specifier?: Maybe<string>): string;
+/**
+ * Optional naming inputs for {@link generateMcpToolDefinitions}.
+ */
+export interface McpToolGenerationNamingOptions {
+    /**
+     * Per-model override of the tool-name model segment, keyed by model type. When a model type is
+     * present, its segment (e.g. the collection prefix) replaces the model type in generated names;
+     * otherwise the model type is used.
+     */
+    readonly modelSegments?: ReadonlyMap<string, string>;
+}
+/**
+ * Optional build-time context for {@link generateMcpToolDefinitions}. Grouped into one object so the
+ * function stays at three parameters and new build-time inputs extend it rather than the arg list.
+ */
+export interface GenerateMcpToolDefinitionsContext {
+    /**
+     * Build-time manifest map supplying overrides for descriptions and input/output schemas, keyed by
+     * {@link mcpManifestKey}.
+     */
+    readonly manifest?: ReadonlyMap<string, McpManifestToolEntry>;
+    /**
+     * Per-model name segment overrides (e.g. collection prefixes).
+     */
+    readonly naming?: McpToolGenerationNamingOptions;
+}
 /**
  * Generates MCP tool definitions from a model-first API details tree.
  *
@@ -224,12 +397,20 @@ export declare function buildDefaultMcpToolDescription(modelType: string, callTy
  * `inputType.toJsonSchema(options)` for the schema, and applies any handler-level
  * MCP `name` override. Descriptions and input/output schemas are pulled from the
  * build-time manifest when supplied. Tools without an `inputType` are skipped and
- * reported so callers can log the gap at startup.
+ * reported so callers can log the gap at startup. Tools whose resolved name exceeds
+ * {@link MCP_TOOL_NAME_MAX_LENGTH} are skipped so the advertised `tools/list` stays valid.
+ *
+ * Generation runs in two passes so a name clash is known before any name is finalized: the first
+ * pass plans every candidate and counts how many visible auto-named tools share each preferred name;
+ * the second builds each tool, re-deriving the colliding ones with the abbreviated call type
+ * ({@link buildDisambiguatedMcpToolName}) so both survive instead of one shadowing the other. A
+ * residual collision that disambiguation cannot resolve (e.g. an `mcp.name` override matching an auto
+ * name) drops the later tool so the dispatch map stays unambiguous.
  *
  * @param apiDetails - The model-first API details tree returned by `getModelApiDetails(callModelFn)`.
  * @param options - Optional schema generation options forwarded to `toJsonSchema()`. Defaults to {@link DEFAULT_JSON_SCHEMA_GENERATION_OPTIONS}.
- * @param manifest - Optional build-time manifest map; supplies overrides for descriptions and input/output schemas keyed by {@link mcpManifestKey}.
+ * @param context - Optional build-time context (manifest overrides + per-model name segments).
  * @returns The list of generated tool definitions plus any skip reports.
  */
-export declare function generateMcpToolDefinitions(apiDetails: ModelApiDetailsResult, options?: JsonSchemaGenerationOptions, manifest?: ReadonlyMap<string, McpManifestToolEntry>): McpToolGenerationResult;
+export declare function generateMcpToolDefinitions(apiDetails: ModelApiDetailsResult, options?: JsonSchemaGenerationOptions, context?: GenerateMcpToolDefinitionsContext): McpToolGenerationResult;
 export {};

package/model/index.cjs.js

@@ -9425,6 +9425,8 @@ function _ts_generator$4(thisArg, body) {
         deleteStorageFile: deleteStorageFileFactory(context),
         downloadStorageFile: downloadStorageFileFactory(context),
         downloadMultipleStorageFiles: downloadMultipleStorageFilesFactory(context),
+        readStorageFileMetadata: readStorageFileMetadataFactory(context),
+        readMultipleStorageFilesMetadata: readMultipleStorageFilesMetadataFactory(context),
         createStorageFileGroup: createStorageFileGroupFactory(context),
         updateStorageFileGroup: updateStorageFileGroupFactory(context),
         syncStorageFileWithGroups: syncStorageFileWithGroupsFactory(context),
@@ -11027,6 +11029,210 @@ function _resolveSignedUploadUrlFilenameOrThrow(policy, filename) {
         })();
     });
 }
+/**
+ * Default maximum number of concurrent metadata read operations when batch-reading StorageFile metadata.
+ */ var DEFAULT_READ_MULTIPLE_STORAGE_FILES_METADATA_MAX_PARALLEL_TASKS = 5;
+/**
+ * Internal factory that reads the underlying Cloud Storage object metadata for one or more StorageFiles.
+ *
+ * Uses {@link performAsyncTasks} with concurrency limiting to avoid overwhelming Cloud Storage.
+ * When the underlying object does not exist, the item resolves with `exists: false` rather than failing.
+ * When `throwOnFirstError` is true, the first failure throws immediately (single-read behavior).
+ * When false, failures are collected in the errors array (batch behavior).
+ *
+ * @param context - The storage file server actions context.
+ * @returns An async function that processes a {@link ReadMultipleStorageFilesMetadataFactoryInput} and returns a {@link ReadMultipleStorageFilesMetadataResult}
+ */ function _readMultipleStorageFilesMetadataFactory(context) {
+    var storageService = context.storageService, storageFileCollection = context.storageFileCollection;
+    return function(input) {
+        return _async_to_generator$4(function() {
+            var items, throwOnFirstError, inputMaxParallelTasks, taskResult, success, errors;
+            return _ts_generator$4(this, function(_state) {
+                switch(_state.label){
+                    case 0:
+                        items = input.items, throwOnFirstError = input.throwOnFirstError, inputMaxParallelTasks = input.maxParallelTasks;
+                        return [
+                            4,
+                            util.performAsyncTasks(items, function(item) {
+                                return _async_to_generator$4(function() {
+                                    var _item_storageFileDocument, storageFileDocument, storageFile, fileAccessor, exists, result, metadata;
+                                    return _ts_generator$4(this, function(_state) {
+                                        switch(_state.label){
+                                            case 0:
+                                                // Load document from key if not provided
+                                                storageFileDocument = (_item_storageFileDocument = item.storageFileDocument) !== null && _item_storageFileDocument !== void 0 ? _item_storageFileDocument : storageFileCollection.documentAccessor().loadDocumentForKey(item.key);
+                                                return [
+                                                    4,
+                                                    firebaseServer.assertSnapshotData(storageFileDocument)
+                                                ];
+                                            case 1:
+                                                storageFile = _state.sent();
+                                                fileAccessor = storageService.file(storageFile);
+                                                return [
+                                                    4,
+                                                    fileAccessor.exists()
+                                                ];
+                                            case 2:
+                                                exists = _state.sent();
+                                                if (!exists) return [
+                                                    3,
+                                                    4
+                                                ];
+                                                return [
+                                                    4,
+                                                    fileAccessor.getMetadata()
+                                                ];
+                                            case 3:
+                                                metadata = _state.sent();
+                                                result = {
+                                                    key: item.key,
+                                                    exists: true,
+                                                    metadata: metadata
+                                                };
+                                                return [
+                                                    3,
+                                                    5
+                                                ];
+                                            case 4:
+                                                result = {
+                                                    key: item.key,
+                                                    exists: false
+                                                };
+                                                _state.label = 5;
+                                            case 5:
+                                                return [
+                                                    2,
+                                                    result
+                                                ];
+                                        }
+                                    });
+                                })();
+                            }, {
+                                throwError: throwOnFirstError !== null && throwOnFirstError !== void 0 ? throwOnFirstError : false,
+                                maxParallelTasks: inputMaxParallelTasks !== null && inputMaxParallelTasks !== void 0 ? inputMaxParallelTasks : DEFAULT_READ_MULTIPLE_STORAGE_FILES_METADATA_MAX_PARALLEL_TASKS
+                            })
+                        ];
+                    case 1:
+                        taskResult = _state.sent();
+                        success = taskResult.results.map(function(param) {
+                            var _param = _sliced_to_array(param, 2), result = _param[1];
+                            return result;
+                        });
+                        errors = taskResult.errors.map(function(param) {
+                            var _param = _sliced_to_array(param, 2), item = _param[0], error = _param[1];
+                            return {
+                                key: item.key,
+                                error: _instanceof(error, Error) ? error.message : 'Metadata read failed'
+                            };
+                        });
+                        return [
+                            2,
+                            {
+                                success: success,
+                                errors: errors
+                            }
+                        ];
+                }
+            });
+        })();
+    };
+}
+/**
+ * Factory for the `readStorageFileMetadata` action.
+ *
+ * Reads the underlying Cloud Storage object metadata for a single {@link StorageFile}.
+ * Delegates to {@link _readMultipleStorageFilesMetadataFactory} with a single item and `throwOnFirstError: true`.
+ *
+ * @param context - The storage file server actions context.
+ * @returns An async transform-and-validate function that reads a StorageFile's Cloud Storage metadata.
+ */ function readStorageFileMetadataFactory(context) {
+    var firebaseServerActionTransformFunctionFactory = context.firebaseServerActionTransformFunctionFactory;
+    var readMultipleStorageFilesMetadata = _readMultipleStorageFilesMetadataFactory(context);
+    return firebaseServerActionTransformFunctionFactory(firebase.readStorageFileMetadataParamsType, function(params) {
+        return _async_to_generator$4(function() {
+            var key;
+            return _ts_generator$4(this, function(_state) {
+                key = params.key;
+                return [
+                    2,
+                    function(storageFileDocument) {
+                        return _async_to_generator$4(function() {
+                            var result;
+                            return _ts_generator$4(this, function(_state) {
+                                switch(_state.label){
+                                    case 0:
+                                        return [
+                                            4,
+                                            readMultipleStorageFilesMetadata({
+                                                items: [
+                                                    {
+                                                        key: key,
+                                                        storageFileDocument: storageFileDocument
+                                                    }
+                                                ],
+                                                throwOnFirstError: true
+                                            })
+                                        ];
+                                    case 1:
+                                        result = _state.sent();
+                                        // success item structurally satisfies ReadStorageFileMetadataResult (extra `key` is ignored)
+                                        return [
+                                            2,
+                                            result.success[0]
+                                        ];
+                                }
+                            });
+                        })();
+                    }
+                ];
+            });
+        })();
+    });
+}
+/**
+ * Factory for the `readMultipleStorageFilesMetadata` action.
+ *
+ * Reads the underlying Cloud Storage object metadata for multiple {@link StorageFile} documents in a single call.
+ * By default, individual failures are collected in the errors array rather than failing the entire batch.
+ * Set `throwOnFirstError` in params to throw on the first failure instead.
+ *
+ * @param context - The storage file server actions context.
+ * @returns An async transform-and-validate function that reads Cloud Storage metadata for multiple files.
+ */ function readMultipleStorageFilesMetadataFactory(context) {
+    var firebaseServerActionTransformFunctionFactory = context.firebaseServerActionTransformFunctionFactory;
+    var readMultipleStorageFilesMetadata = _readMultipleStorageFilesMetadataFactory(context);
+    return firebaseServerActionTransformFunctionFactory(firebase.readMultipleStorageFilesMetadataParamsType, function(params) {
+        return _async_to_generator$4(function() {
+            var files, throwOnFirstError;
+            return _ts_generator$4(this, function(_state) {
+                files = params.files, throwOnFirstError = params.throwOnFirstError;
+                return [
+                    2,
+                    function(storageFileDocuments) {
+                        return _async_to_generator$4(function() {
+                            var items;
+                            return _ts_generator$4(this, function(_state) {
+                                items = files.map(function(file, i) {
+                                    return {
+                                        key: file.key,
+                                        storageFileDocument: storageFileDocuments === null || storageFileDocuments === void 0 ? void 0 : storageFileDocuments[i]
+                                    };
+                                });
+                                return [
+                                    2,
+                                    readMultipleStorageFilesMetadata({
+                                        items: items,
+                                        throwOnFirstError: throwOnFirstError !== null && throwOnFirstError !== void 0 ? throwOnFirstError : false
+                                    })
+                                ];
+                            });
+                        })();
+                    }
+                ];
+            });
+        })();
+    });
+}
 /**
  * Internal factory that creates a function for creating a {@link StorageFileGroup} document
  * within a Firestore transaction.
@@ -14050,6 +14256,7 @@ exports.DEFAULT_COMPRESS_PDF_IMAGE_QUALITY = DEFAULT_COMPRESS_PDF_IMAGE_QUALITY;
 exports.DEFAULT_COMPRESS_PDF_IMAGE_SIZE_THRESHOLD_BYTES = DEFAULT_COMPRESS_PDF_IMAGE_SIZE_THRESHOLD_BYTES;
 exports.DEFAULT_DOWNLOAD_MULTIPLE_STORAGE_FILES_MAX_PARALLEL_TASKS = DEFAULT_DOWNLOAD_MULTIPLE_STORAGE_FILES_MAX_PARALLEL_TASKS;
 exports.DEFAULT_MAILGUN_NOTIFICATION_EMAIL_SEND_SERVICE_MAX_BATCH_SIZE_PER_REQUEST = DEFAULT_MAILGUN_NOTIFICATION_EMAIL_SEND_SERVICE_MAX_BATCH_SIZE_PER_REQUEST;
+exports.DEFAULT_READ_MULTIPLE_STORAGE_FILES_METADATA_MAX_PARALLEL_TASKS = DEFAULT_READ_MULTIPLE_STORAGE_FILES_METADATA_MAX_PARALLEL_TASKS;
 exports.KNOWN_BUT_UNCONFIGURED_NOTIFICATION_TEMPLATE_TYPE_DELETE_AFTER_RETRY_ATTEMPTS = KNOWN_BUT_UNCONFIGURED_NOTIFICATION_TEMPLATE_TYPE_DELETE_AFTER_RETRY_ATTEMPTS;
 exports.KNOWN_BUT_UNCONFIGURED_NOTIFICATION_TEMPLATE_TYPE_HOURS_DELAY = KNOWN_BUT_UNCONFIGURED_NOTIFICATION_TEMPLATE_TYPE_HOURS_DELAY;
 exports.MAKE_TEMPLATE_FOR_NOTIFICATION_RELATED_MODEL_INITIALIZATION_FUNCTION_DELETE_RESPONSE = MAKE_TEMPLATE_FOR_NOTIFICATION_RELATED_MODEL_INITIALIZATION_FUNCTION_DELETE_RESPONSE;
@@ -14149,6 +14356,8 @@ exports.processAllQueuedStorageFilesFactory = processAllQueuedStorageFilesFactor
 exports.processStorageFileFactory = processStorageFileFactory;
 exports.provideMutableNotificationExpediteService = provideMutableNotificationExpediteService;
 exports.queryAndFlagStorageFilesForDelete = queryAndFlagStorageFilesForDelete;
+exports.readMultipleStorageFilesMetadataFactory = readMultipleStorageFilesMetadataFactory;
+exports.readStorageFileMetadataFactory = readStorageFileMetadataFactory;
 exports.regenerateAllFlaggedStorageFileGroupsContentFactory = regenerateAllFlaggedStorageFileGroupsContentFactory;
 exports.regenerateStorageFileGroupContentFactory = regenerateStorageFileGroupContentFactory;
 exports.resyncAllNotificationUsersFactory = resyncAllNotificationUsersFactory;