@dereekb/firebase-server 13.16.0 → 13.18.0

package/mcp/src/lib/service/tools/mcp.tool.enum-info.d.ts

@@ -0,0 +1,70 @@
+import { type McpManifestEnum } from '../mcp.manifest';
+import { type McpToolDefinition } from '../mcp.tool-generator';
+/**
+ * Reserved tool name for the built-in `enum-info` static tool.
+ */
+export declare const ENUM_INFO_TOOL_NAME = "enum-info";
+/**
+ * Synthetic call type used in the tool's dispatch identity. Mirrors the `info` call shared with
+ * `model-info`.
+ */
+export declare const ENUM_INFO_DISPATCH_CALL = "info";
+/**
+ * Synthetic model type used in the tool's dispatch identity. Apps avoiding collisions should not
+ * register a real model literally named "enum".
+ */
+export declare const ENUM_INFO_DISPATCH_MODEL_TYPE = "enum";
+/**
+ * Constructor dependencies for {@link createEnumInfoTool}.
+ */
+export interface CreateEnumInfoToolDeps {
+    /**
+     * Frozen enum value tables keyed by enum name, sourced from the build-time manifest's `enums`
+     * block.
+     */
+    readonly enums: {
+        readonly [name: string]: McpManifestEnum;
+    };
+}
+/**
+ * Shape of the `enum-info` tool input.
+ */
+export interface EnumInfoToolInput {
+    /**
+     * One enum name (string) or several (string array), each matched exactly by declaration name.
+     */
+    readonly enum: string | ReadonlyArray<string>;
+}
+/**
+ * Output payload for the `enum-info` tool: the resolved value tables, with any unmatched names in
+ * `notFound`.
+ */
+export interface EnumInfoToolOutput {
+    readonly enums: ReadonlyArray<McpManifestEnum>;
+    readonly notFound?: ReadonlyArray<string>;
+}
+/**
+ * Builds the built-in `enum-info` MCP tool definition — the symmetric counterpart to `model-info`
+ * for raw enum decoding.
+ *
+ * Resolves each requested enum name against the manifest's `enums` block and returns the matching
+ * value→label tables; misses land in `notFound`. A bare string is treated as a one-element array.
+ *
+ * Output is delivered as both stringified JSON in `content[0].text` and `structuredContent` so MCP
+ * clients can consume either form.
+ *
+ * @param deps - The frozen enum value tables loaded at boot from the MCP manifest JSON.
+ * @returns A statically-registered {@link McpToolDefinition} ready to be appended to the MCP server
+ *   factory's tool registry.
+ */
+export declare function createEnumInfoTool(deps: CreateEnumInfoToolDeps): McpToolDefinition;
+/**
+ * Resolves each requested enum name against the registered value tables.
+ *
+ * @param names - The requested enum declaration names.
+ * @param enums - The registered enum value tables keyed by name.
+ * @returns The matched tables, with any unmatched names in `notFound`.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function resolveEnumInfoOutput(names: readonly string[], enums: CreateEnumInfoToolDeps['enums']): EnumInfoToolOutput;

package/mcp/src/lib/service/tools/mcp.tool.model-info.d.ts

@@ -1,4 +1,4 @@
-import { type McpManifestModelEntry } from '../mcp.manifest';
+import { type McpManifestEnum, type McpManifestModelEntry } from '../mcp.manifest';
 import { type McpToolDefinition } from '../mcp.tool-generator';
 /**
  * Reserved tool name for the built-in `model-info` static tool.
@@ -32,6 +32,15 @@ export interface CreateModelInfoToolDeps {
      * manifest JSON.
      */
     readonly manifest: readonly McpManifestModelEntry[];
+    /**
+     * Optional enum value tables, keyed by enum name, sourced from the build-time manifest's `enums`
+     * block. When present, the value→label table for every enum referenced (by `enumRef`) on a
+     * returned model's fields is attached as a top-level `enums` section — but only when full field
+     * detail is returned, so the default compact modes stay small.
+     */
+    readonly enums?: {
+        readonly [name: string]: McpManifestEnum;
+    };
 }
 /**
  * Public shape of the `model-info` tool input. Every field is optional; the combination selects
@@ -112,8 +121,12 @@ export interface ModelInfoNotFound {
  * - `list`: a summary (or, with `fields: true`, full) list — used by `modelGroup` and `all`.
  * - `single`: full detail for one `model` string.
  * - `multiple`: full detail per match for a `model` array, with misses in `notFound`.
+ *
+ * The orthogonal `enums` section is attached only when full field detail is returned and the
+ * returned models reference at least one enum present in the manifest — the default compact modes
+ * (`groups`, summary `list`) never carry it.
  */
-export type ModelInfoToolOutput = {
+export type ModelInfoToolOutput = ({
     readonly mode: 'groups';
     readonly groups: ReadonlyArray<ModelInfoGroupCount>;
     readonly totalModels: number;
@@ -129,6 +142,8 @@ export type ModelInfoToolOutput = {
     readonly mode: 'multiple';
     readonly models: ReadonlyArray<ModelInfoModelRow>;
     readonly notFound?: ReadonlyArray<ModelInfoNotFound>;
+}) & {
+    readonly enums?: ReadonlyArray<McpManifestEnum>;
 };
 /**
  * Builds the built-in `model-info` MCP tool definition.
@@ -162,3 +177,37 @@ export declare function createModelInfoTool(deps: CreateModelInfoToolDeps): McpT
  * @__NO_SIDE_EFFECTS__
  */
 export declare function findModelEntry(query: string, manifest: ReadonlyArray<McpManifestModelEntry>): McpManifestModelEntry | undefined;
+/**
+ * JSON-schema for one enum value→label table. Shared with the `enum-info` tool so both advertise the
+ * identical enum shape.
+ */
+export declare const ENUM_TABLE_SCHEMA: {
+    readonly type: "object";
+    readonly required: readonly ["name", "values"];
+    readonly properties: {
+        readonly name: {
+            readonly type: "string";
+        };
+        readonly description: {
+            readonly type: "string";
+        };
+        readonly values: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "object";
+                readonly required: readonly ["name", "value"];
+                readonly properties: {
+                    readonly name: {
+                        readonly type: "string";
+                    };
+                    readonly value: {
+                        readonly type: readonly ["string", "number"];
+                    };
+                    readonly description: {
+                        readonly type: "string";
+                    };
+                };
+            };
+        };
+    };
+};

package/mcp/src/lib/service/tools/mcp.tool.url-models.d.ts

@@ -0,0 +1,101 @@
+import { type FirestoreModelKey } from '@dereekb/firebase';
+import { type ModelAccessMultiReadResult } from '@dereekb/firebase-server';
+import { type McpToolDefinition } from '../mcp.tool-generator';
+import { type RouteManifest, type RouteManifestModelEntry } from '../mcp.route-manifest';
+import { type McpModelGetReadDocuments, type McpModelGetResolveIdentity } from './mcp.tool.model-get';
+/**
+ * Reserved tool name for the built-in `url-models` static tool.
+ */
+export declare const URL_MODELS_TOOL_NAME = "url-models";
+/**
+ * Synthetic call type used in the tool's dispatch identity.
+ */
+export declare const URL_MODELS_DISPATCH_CALL = "url-models";
+/**
+ * Synthetic model type used in the tool's dispatch identity. The tool isn't
+ * bound to a real model (the `url` is its input), so we use the literal "route".
+ */
+export declare const URL_MODELS_DISPATCH_MODEL_TYPE = "route";
+/**
+ * Why a model binding could not be resolved into a concrete key.
+ */
+export type UrlModelUnresolvedReason = 'missing-param' | 'subcollection-requires-key-template' | 'unknown-model-type' | 'auth-required';
+/**
+ * One resolved model binding for a matched page.
+ */
+export interface ResolvedRouteModel {
+    readonly modelType: string;
+    readonly kind: RouteManifestModelEntry['kind'];
+    readonly keyTemplate?: string;
+    readonly description?: string;
+    readonly from?: string;
+    /**
+     * The concrete FirestoreModelKey, when the binding resolved (`id`/`key` kinds).
+     */
+    readonly key?: FirestoreModelKey;
+    /**
+     * Present when the binding could not be turned into a key.
+     */
+    readonly unresolved?: {
+        readonly reason: UrlModelUnresolvedReason;
+        readonly message: string;
+    };
+}
+/**
+ * Documents loaded for one model type (when `load` is requested).
+ */
+export interface UrlModelLoadedGroup {
+    readonly modelType: string;
+    readonly results: ModelAccessMultiReadResult['results'];
+    readonly errors: ModelAccessMultiReadResult['errors'];
+}
+/**
+ * Constructor dependencies for {@link createUrlModelsTool}.
+ */
+export interface CreateUrlModelsToolDeps {
+    /**
+     * The pre-rendered route manifest used to match URLs to states.
+     */
+    readonly routeManifest: RouteManifest;
+    /**
+     * Reads a batch of model documents (shared with `model-get`).
+     */
+    readonly readDocuments: McpModelGetReadDocuments;
+    /**
+     * Resolves a model type's registered identity so `id` key templates can be
+     * promoted to `<collectionName>/<id>` (shared with `model-get`).
+     */
+    readonly resolveIdentity: McpModelGetResolveIdentity;
+}
+/**
+ * Shape of the `url-models` tool input.
+ */
+export interface UrlModelsToolInput {
+    readonly url: string;
+    readonly models?: ReadonlyArray<string>;
+    readonly keysOnly?: boolean;
+    readonly load?: boolean;
+    /**
+     * Overrides the uid used to fill `{authUid}` placeholders when resolving model
+     * keys (defaults to the authenticated caller). Use to preview the models
+     * another user would see on a page. Does not affect the document-load path —
+     * `load` still reads via the calling user's permissions.
+     */
+    readonly currentUserUid?: string;
+}
+/**
+ * Builds the built-in `url-models` MCP tool definition.
+ *
+ * Matches a pasted app URL against the build-time route manifest and returns the
+ * Firestore models the page renders — model types plus concrete keys with the
+ * route params and `{authUid}` substituted. Optionally filtered to specific
+ * `models`, reduced to keys-only, or loaded via the same permission-checked read
+ * path as `model-get`.
+ *
+ * A URL that matches no state returns a structured `{ matched: null, candidates }`
+ * (not an error) so the caller can suggest near-misses.
+ *
+ * @param deps - The route manifest plus the shared read-documents / identity callbacks.
+ * @returns A statically-registered {@link McpToolDefinition}.
+ */
+export declare function createUrlModelsTool(deps: CreateUrlModelsToolDeps): McpToolDefinition;

package/model/package.json

@@ -1,15 +1,15 @@
 {
   "name": "@dereekb/firebase-server/model",
-  "version": "13.16.0",
+  "version": "13.18.0",
   "peerDependencies": {
-    "@dereekb/analytics": "13.16.0",
-    "@dereekb/date": "13.16.0",
-    "@dereekb/firebase": "13.16.0",
-    "@dereekb/firebase-server": "13.16.0",
-    "@dereekb/model": "13.16.0",
-    "@dereekb/nestjs": "13.16.0",
-    "@dereekb/rxjs": "13.16.0",
-    "@dereekb/util": "13.16.0",
+    "@dereekb/analytics": "13.18.0",
+    "@dereekb/date": "13.18.0",
+    "@dereekb/firebase": "13.18.0",
+    "@dereekb/firebase-server": "13.18.0",
+    "@dereekb/model": "13.18.0",
+    "@dereekb/nestjs": "13.18.0",
+    "@dereekb/rxjs": "13.18.0",
+    "@dereekb/util": "13.18.0",
     "@nestjs/common": "^11.1.19",
     "@nestjs/config": "^4.0.4",
     "archiver": "^7.0.1",

package/oidc/package.json

@@ -1,16 +1,16 @@
 {
   "name": "@dereekb/firebase-server/oidc",
-  "version": "13.16.0",
+  "version": "13.18.0",
   "peerDependencies": {
-    "@dereekb/analytics": "13.16.0",
-    "@dereekb/date": "13.16.0",
-    "@dereekb/firebase": "13.16.0",
-    "@dereekb/firebase-server": "13.16.0",
-    "@dereekb/model": "13.16.0",
-    "@dereekb/nestjs": "13.16.0",
-    "@dereekb/rxjs": "13.16.0",
-    "@dereekb/util": "13.16.0",
-    "@dereekb/zoho": "13.16.0",
+    "@dereekb/analytics": "13.18.0",
+    "@dereekb/date": "13.18.0",
+    "@dereekb/firebase": "13.18.0",
+    "@dereekb/firebase-server": "13.18.0",
+    "@dereekb/model": "13.18.0",
+    "@dereekb/nestjs": "13.18.0",
+    "@dereekb/rxjs": "13.18.0",
+    "@dereekb/util": "13.18.0",
+    "@dereekb/zoho": "13.18.0",
     "@nestjs/common": "^11.1.19",
     "@nestjs/config": "^4.0.4",
     "express": "^5.2.1",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dereekb/firebase-server",
-  "version": "13.16.0",
+  "version": "13.18.0",
   "sideEffects": false,
   "exports": {
     "./test": {
@@ -57,15 +57,15 @@
   "types": "./src/index.d.ts",
   "peerDependencies": {
     "@cantoo/pdf-lib": "^2.6.5",
-    "@dereekb/analytics": "13.16.0",
-    "@dereekb/date": "13.16.0",
-    "@dereekb/dbx-core": "13.16.0",
-    "@dereekb/firebase": "13.16.0",
-    "@dereekb/model": "13.16.0",
-    "@dereekb/nestjs": "13.16.0",
-    "@dereekb/rxjs": "13.16.0",
-    "@dereekb/util": "13.16.0",
-    "@dereekb/zoho": "13.16.0",
+    "@dereekb/analytics": "13.18.0",
+    "@dereekb/date": "13.18.0",
+    "@dereekb/dbx-core": "13.18.0",
+    "@dereekb/firebase": "13.18.0",
+    "@dereekb/model": "13.18.0",
+    "@dereekb/nestjs": "13.18.0",
+    "@dereekb/rxjs": "13.18.0",
+    "@dereekb/util": "13.18.0",
+    "@dereekb/zoho": "13.18.0",
     "@google-cloud/firestore": "^7.11.6",
     "@google-cloud/storage": "^7.19.0",
     "@modelcontextprotocol/sdk": "1.29.0",

package/src/lib/nest/controller/model/model.api.get.service.d.ts

@@ -43,6 +43,11 @@ export interface ModelAccessUseMultipleModelsFailureEntry {
  * permission-denied / not-found errors surface a real message + code instead of the generic
  * `"Unknown error"` fallback the inline mapping used previously.
  *
+ * When no real message survives, the fallback is derived from the resolved error `code` so the two
+ * distinct outcomes stay distinguishable — a not-found read no longer reads as "permission denied"
+ * (and vice-versa). Only when neither a message nor a recognizable code is present does it fall back
+ * to a generic message.
+ *
  * @param entry - A failed-key entry from the underlying multi-read.
  * @returns A `{ key, message, code? }` triple safe to return to API/MCP callers.
  */

package/test/package.json

@@ -1,16 +1,16 @@
 {
   "name": "@dereekb/firebase-server/test",
-  "version": "13.16.0",
+  "version": "13.18.0",
   "peerDependencies": {
-    "@dereekb/analytics": "13.16.0",
-    "@dereekb/date": "13.16.0",
-    "@dereekb/firebase": "13.16.0",
-    "@dereekb/firebase-server": "13.16.0",
-    "@dereekb/firebase-server/oidc": "13.16.0",
-    "@dereekb/model": "13.16.0",
-    "@dereekb/nestjs": "13.16.0",
-    "@dereekb/rxjs": "13.16.0",
-    "@dereekb/util": "13.16.0",
+    "@dereekb/analytics": "13.18.0",
+    "@dereekb/date": "13.18.0",
+    "@dereekb/firebase": "13.18.0",
+    "@dereekb/firebase-server": "13.18.0",
+    "@dereekb/firebase-server/oidc": "13.18.0",
+    "@dereekb/model": "13.18.0",
+    "@dereekb/nestjs": "13.18.0",
+    "@dereekb/rxjs": "13.18.0",
+    "@dereekb/util": "13.18.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.16.0"
+    "@dereekb/nestjs": "13.18.0"
   },
   "exports": {
     "./package.json": "./package.json",

package/twilio/package.json

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

package/zoho/package.json

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