@dereekb/firebase-server 13.22.0 → 13.23.0

package/mailgun/package.json

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

package/mcp/index.cjs.js

@@ -4176,6 +4176,31 @@ function _ts_generator$4(thisArg, body) {
  * URL value is a whole two-way-flat FirestoreModelKey. Mirror of the build-time
  * `FLAT_KEY_TOKEN_RE` in `@dereekb/dbx-cli`'s route-model-tag parser.
  */ var FLAT_KEY_TEMPLATE_RE = RegExp("^\\{flatKey:([a-zA-Z_][a-zA-Z0-9_]*)\\}$", "u");
+/**
+ * Reads the impersonation uid from a URL's `?imp=<uid>` query parameter, if present.
+ *
+ * Impersonation ("view as another user") is conveyed by the {@link IMPERSONATION_URL_QUERY_PARAM} query
+ * param; when set, it overrides the uid used to fill `{authUid}` placeholders so a decoded URL reports the
+ * models the impersonated user's page renders. Handles both a full URL and a bare path (mirroring
+ * {@link parseUrlModelsPathname}, which discards the query when matching). Returns the trimmed non-empty
+ * uid, or `undefined` when absent.
+ *
+ * @param url - A full URL or bare path, optionally carrying `?imp=<uid>`.
+ * @returns The impersonated uid, or `undefined`.
+ */ function readUrlModelsImpersonationUid(url) {
+    var _get;
+    var trimmed = url.trim();
+    var search;
+    if (RegExp("^[a-z][a-z0-9+.-]*:\\/\\/", "iu").test(trimmed)) {
+        search = new URL(trimmed).search;
+    } else {
+        var hashStripped = trimmed.split('#', 1)[0];
+        var queryIndex = hashStripped.indexOf('?');
+        search = queryIndex >= 0 ? hashStripped.slice(queryIndex) : '';
+    }
+    var value = (_get = new URLSearchParams(search).get(util.IMPERSONATION_URL_QUERY_PARAM)) === null || _get === void 0 ? void 0 : _get.trim();
+    return value ? value : undefined;
+}
 // MARK: Factory
 /**
  * Builds the built-in `url-models` MCP tool definition.
@@ -4196,7 +4221,7 @@ function _ts_generator$4(thisArg, body) {
         return urlModelsToolHandler(args, ctx, deps);
     };
     var name = URL_MODELS_TOOL_NAME;
-    var description = 'Decode an app URL (or path) into the Firestore models its page renders. Pass a URL like `https://app.example.co/worker/abc/timesheets/list`; the tool matches it against the build-time route manifest and returns each model type plus the concrete key (route params + `{authUid}` substituted). Use `models` to filter to specific types, `keysOnly` for just the resolved keys, or `load: true` to fetch the documents via the same permission-checked path as `model-get` (cannot combine `load` with `keysOnly`).';
+    var description = 'Decode an app URL (or path) into the Firestore models its page renders. Pass a URL like `https://app.example.co/worker/abc/timesheets/list`; the tool matches it against the build-time route manifest and returns each model type plus the concrete key (route params + `{authUid}` substituted). A `?imp=<uid>` query param resolves `{authUid}` to that user (impersonation preview). Use `models` to filter to specific types, `keysOnly` for just the resolved keys, or `load: true` to fetch the documents via the same permission-checked path as `model-get` (cannot combine `load` with `keysOnly`).';
     return buildStaticToolDefinition({
         name: name,
         description: description,
@@ -4372,15 +4397,16 @@ function stateSummary(state) {
 }
 function buildMatchedPayload(args) {
     return _async_to_generator$4(function() {
-        var _input_currentUserUid, _ctx_auth, match, input, ctx, deps, uid, filtered, resolved, loaded, _tmp;
+        var _ref, _readUrlModelsImpersonationUid, _ctx_auth, match, input, ctx, deps, uid, filtered, resolved, loaded, _tmp;
         return _ts_generator$4(this, function(_state) {
             switch(_state.label){
                 case 0:
                     match = args.match, input = args.input, ctx = args.ctx, deps = args.deps;
-                    // `currentUserUid` (when supplied) overrides the uid used to fill `{authUid}` placeholders so a
-                    // caller can preview another user's page-models. The document-load path still uses `ctx.auth`, so
-                    // this is a key-substitution preview only — no privilege escalation on the actual reads.
-                    uid = (_input_currentUserUid = input.currentUserUid) !== null && _input_currentUserUid !== void 0 ? _input_currentUserUid : (_ctx_auth = ctx.auth) === null || _ctx_auth === void 0 ? void 0 : _ctx_auth.uid;
+                    // A `?imp=<uid>` query param on the URL (impersonation), then an explicit `currentUserUid`, override the
+                    // uid used to fill `{authUid}` placeholders so a caller can preview another user's page-models. The
+                    // document-load path still uses `ctx.auth`, so this is a key-substitution preview only — no privilege
+                    // escalation on the actual reads.
+                    uid = (_ref = (_readUrlModelsImpersonationUid = readUrlModelsImpersonationUid(input.url)) !== null && _readUrlModelsImpersonationUid !== void 0 ? _readUrlModelsImpersonationUid : input.currentUserUid) !== null && _ref !== void 0 ? _ref : (_ctx_auth = ctx.auth) === null || _ctx_auth === void 0 ? void 0 : _ctx_auth.uid;
                     filtered = input.models === undefined ? match.state.models : match.state.models.filter(function(m) {
                         var _input_models;
                         return (_input_models = input.models) === null || _input_models === void 0 ? void 0 : _input_models.includes(m.modelType);
@@ -4786,7 +4812,7 @@ var URL_MODELS_INPUT_SCHEMA = {
         url: {
             type: 'string',
             minLength: 1,
-            description: 'Full URL or pathname, e.g. "https://app.example.co/worker/abc/timesheets/list".'
+            description: 'Full URL or pathname, e.g. "https://app.example.co/worker/abc/timesheets/list". A `?imp=<uid>` query resolves `{authUid}` to that user (impersonation preview).'
         },
         models: {
             type: 'array',
@@ -4806,7 +4832,7 @@ var URL_MODELS_INPUT_SCHEMA = {
         currentUserUid: {
             type: 'string',
             minLength: 1,
-            description: "Override 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. `load` still reads via the calling user's permissions."
+            description: "Override 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. A `?imp=<uid>` query on the url takes precedence over this. `load` still reads via the calling user's permissions."
         }
     },
     additionalProperties: false
@@ -7899,6 +7925,7 @@ exports.mcpModuleMetadata = mcpModuleMetadata;
 exports.mcpSchemaDeclaresProperty = mcpSchemaDeclaresProperty;
 exports.noopMcpAnalyticsService = noopMcpAnalyticsService;
 exports.parseUrlModelsPathname = parseUrlModelsPathname;
+exports.readUrlModelsImpersonationUid = readUrlModelsImpersonationUid;
 exports.resolveEffectiveReadOnly = resolveEffectiveReadOnly;
 exports.resolveEnumInfoOutput = resolveEnumInfoOutput;
 exports.resolveMcpReasonParameterConfig = resolveMcpReasonParameterConfig;

package/mcp/index.esm.js

@@ -3,7 +3,7 @@ import { existsSync, readFileSync } from 'node:fs';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { ListToolsRequestSchema, CallToolRequestSchema } from '@modelcontextprotocol/sdk/types.js';
 import { getOidcScopesFromRequest } from '@dereekb/firebase-server/oidc';
-import { makeValuesGroupMap, performAsyncTasks, authRolesSetHasRoles } from '@dereekb/util';
+import { makeValuesGroupMap, IMPERSONATION_URL_QUERY_PARAM, performAsyncTasks, authRolesSetHasRoles } from '@dereekb/util';
 import { ModelApiCallModelDispatchService, ModelApiGetService, FirebaseServerStorageService, FirebaseServerEnvService, FirebaseServerAnalyticsService } from '@dereekb/firebase-server';
 import { inspect } from 'node:util';
 import { arktypeToJsonSchemaForExport } from '@dereekb/model';
@@ -4174,6 +4174,31 @@ function _ts_generator$4(thisArg, body) {
  * URL value is a whole two-way-flat FirestoreModelKey. Mirror of the build-time
  * `FLAT_KEY_TOKEN_RE` in `@dereekb/dbx-cli`'s route-model-tag parser.
  */ var FLAT_KEY_TEMPLATE_RE = RegExp("^\\{flatKey:([a-zA-Z_][a-zA-Z0-9_]*)\\}$", "u");
+/**
+ * Reads the impersonation uid from a URL's `?imp=<uid>` query parameter, if present.
+ *
+ * Impersonation ("view as another user") is conveyed by the {@link IMPERSONATION_URL_QUERY_PARAM} query
+ * param; when set, it overrides the uid used to fill `{authUid}` placeholders so a decoded URL reports the
+ * models the impersonated user's page renders. Handles both a full URL and a bare path (mirroring
+ * {@link parseUrlModelsPathname}, which discards the query when matching). Returns the trimmed non-empty
+ * uid, or `undefined` when absent.
+ *
+ * @param url - A full URL or bare path, optionally carrying `?imp=<uid>`.
+ * @returns The impersonated uid, or `undefined`.
+ */ function readUrlModelsImpersonationUid(url) {
+    var _get;
+    var trimmed = url.trim();
+    var search;
+    if (RegExp("^[a-z][a-z0-9+.-]*:\\/\\/", "iu").test(trimmed)) {
+        search = new URL(trimmed).search;
+    } else {
+        var hashStripped = trimmed.split('#', 1)[0];
+        var queryIndex = hashStripped.indexOf('?');
+        search = queryIndex >= 0 ? hashStripped.slice(queryIndex) : '';
+    }
+    var value = (_get = new URLSearchParams(search).get(IMPERSONATION_URL_QUERY_PARAM)) === null || _get === void 0 ? void 0 : _get.trim();
+    return value ? value : undefined;
+}
 // MARK: Factory
 /**
  * Builds the built-in `url-models` MCP tool definition.
@@ -4194,7 +4219,7 @@ function _ts_generator$4(thisArg, body) {
         return urlModelsToolHandler(args, ctx, deps);
     };
     var name = URL_MODELS_TOOL_NAME;
-    var description = 'Decode an app URL (or path) into the Firestore models its page renders. Pass a URL like `https://app.example.co/worker/abc/timesheets/list`; the tool matches it against the build-time route manifest and returns each model type plus the concrete key (route params + `{authUid}` substituted). Use `models` to filter to specific types, `keysOnly` for just the resolved keys, or `load: true` to fetch the documents via the same permission-checked path as `model-get` (cannot combine `load` with `keysOnly`).';
+    var description = 'Decode an app URL (or path) into the Firestore models its page renders. Pass a URL like `https://app.example.co/worker/abc/timesheets/list`; the tool matches it against the build-time route manifest and returns each model type plus the concrete key (route params + `{authUid}` substituted). A `?imp=<uid>` query param resolves `{authUid}` to that user (impersonation preview). Use `models` to filter to specific types, `keysOnly` for just the resolved keys, or `load: true` to fetch the documents via the same permission-checked path as `model-get` (cannot combine `load` with `keysOnly`).';
     return buildStaticToolDefinition({
         name: name,
         description: description,
@@ -4370,15 +4395,16 @@ function stateSummary(state) {
 }
 function buildMatchedPayload(args) {
     return _async_to_generator$4(function() {
-        var _input_currentUserUid, _ctx_auth, match, input, ctx, deps, uid, filtered, resolved, loaded, _tmp;
+        var _ref, _readUrlModelsImpersonationUid, _ctx_auth, match, input, ctx, deps, uid, filtered, resolved, loaded, _tmp;
         return _ts_generator$4(this, function(_state) {
             switch(_state.label){
                 case 0:
                     match = args.match, input = args.input, ctx = args.ctx, deps = args.deps;
-                    // `currentUserUid` (when supplied) overrides the uid used to fill `{authUid}` placeholders so a
-                    // caller can preview another user's page-models. The document-load path still uses `ctx.auth`, so
-                    // this is a key-substitution preview only — no privilege escalation on the actual reads.
-                    uid = (_input_currentUserUid = input.currentUserUid) !== null && _input_currentUserUid !== void 0 ? _input_currentUserUid : (_ctx_auth = ctx.auth) === null || _ctx_auth === void 0 ? void 0 : _ctx_auth.uid;
+                    // A `?imp=<uid>` query param on the URL (impersonation), then an explicit `currentUserUid`, override the
+                    // uid used to fill `{authUid}` placeholders so a caller can preview another user's page-models. The
+                    // document-load path still uses `ctx.auth`, so this is a key-substitution preview only — no privilege
+                    // escalation on the actual reads.
+                    uid = (_ref = (_readUrlModelsImpersonationUid = readUrlModelsImpersonationUid(input.url)) !== null && _readUrlModelsImpersonationUid !== void 0 ? _readUrlModelsImpersonationUid : input.currentUserUid) !== null && _ref !== void 0 ? _ref : (_ctx_auth = ctx.auth) === null || _ctx_auth === void 0 ? void 0 : _ctx_auth.uid;
                     filtered = input.models === undefined ? match.state.models : match.state.models.filter(function(m) {
                         var _input_models;
                         return (_input_models = input.models) === null || _input_models === void 0 ? void 0 : _input_models.includes(m.modelType);
@@ -4784,7 +4810,7 @@ var URL_MODELS_INPUT_SCHEMA = {
         url: {
             type: 'string',
             minLength: 1,
-            description: 'Full URL or pathname, e.g. "https://app.example.co/worker/abc/timesheets/list".'
+            description: 'Full URL or pathname, e.g. "https://app.example.co/worker/abc/timesheets/list". A `?imp=<uid>` query resolves `{authUid}` to that user (impersonation preview).'
         },
         models: {
             type: 'array',
@@ -4804,7 +4830,7 @@ var URL_MODELS_INPUT_SCHEMA = {
         currentUserUid: {
             type: 'string',
             minLength: 1,
-            description: "Override 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. `load` still reads via the calling user's permissions."
+            description: "Override 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. A `?imp=<uid>` query on the url takes precedence over this. `load` still reads via the calling user's permissions."
         }
     },
     additionalProperties: false
@@ -7819,4 +7845,4 @@ function _unsupported_iterable_to_array(o, minLen) {
     };
 }
 
-export { BATCH_EXECUTE_DISPATCH_CALL, BATCH_EXECUTE_DISPATCH_MODEL_TYPE, BATCH_EXECUTE_TOOL_NAME, DEFAULT_BATCH_EXECUTE_MAX_PARALLEL, DEFAULT_JSON_SCHEMA_GENERATION_OPTIONS, DEFAULT_MCP_ANALYTICS_EVENT_NAME, DEFAULT_MCP_PATH, DEFAULT_MCP_REASON_PARAMETER_DESCRIPTION, DEFAULT_MCP_REASON_PARAMETER_MAX_LENGTH, DEFAULT_MCP_REASON_PARAMETER_NAME, DEFAULT_MCP_REASON_PARAMETER_REQUIRED, DEFAULT_MCP_SERVER_INSTRUCTIONS, DEFAULT_MCP_SERVER_NAME, DEFAULT_SPECIFIER_KEY, DEFAULT_VOID_MCP_SUCCESS_VALUE, ENUM_INFO_DISPATCH_CALL, ENUM_INFO_DISPATCH_MODEL_TYPE, ENUM_INFO_TOOL_NAME, ENUM_TABLE_SCHEMA, FIREBASE_SERVER_MCP_ANALYTICS_CONFIG, FIREBASE_SERVER_MCP_ROUTES_FOR_GLOBAL_ROUTE_EXCLUDE, FirebaseServerMcpAnalyticsService, MAX_BATCH_EXECUTE_FILE_BYTES, MAX_BATCH_EXECUTE_OPERATIONS, MCP_ANALYTICS_SERVICE, MCP_AUTH_ROLE_READER, MCP_CALL_TYPE_ABBREVIATIONS, MCP_MANIFEST_VERSION, MCP_MODEL_GET_BATCH_SIZE, MCP_TOOL_NAME_MAX_LENGTH, MCP_TOOL_NAME_WARN_LENGTH, MCP_WRITE_TOOL_DESCRIPTION_PREFIX, MODEL_DECODE_DISPATCH_CALL, MODEL_DECODE_DISPATCH_MODEL_TYPE, MODEL_DECODE_TOOL_NAME, MODEL_GET_DISPATCH_CALL, MODEL_GET_DISPATCH_MODEL_TYPE, MODEL_GET_TOOL_NAME, MODEL_INFO_DISPATCH_CALL, MODEL_INFO_DISPATCH_MODEL_TYPE, MODEL_INFO_GROUPS_HINT, MODEL_INFO_TOOL_NAME, MODEL_INFO_UNGROUPED_LABEL, McpAnalyticsService, McpController, McpModuleConfig, McpServerFactoryService, McpWellKnownController, ROUTE_MANIFEST_VERSION, URL_MODELS_DISPATCH_CALL, URL_MODELS_DISPATCH_MODEL_TYPE, URL_MODELS_TOOL_NAME, abbreviateMcpCallType, appMcpAnalyticsModuleMetadata, applyMcpReasonParameterToSchema, applyWriteMarker, batchOperationCoordKey, buildDefaultMcpToolDescription, buildDisambiguatedMcpToolName, buildMcpToolName, buildStaticToolDefinition, buildStaticWireEntry, classifyVisibility, createBatchExecuteTool, createEnumInfoTool, createModelDecodeTool, createModelGetTool, createModelInfoTool, createUrlModelsTool, decodeFirestoreModelKey, extractMcpReasonFromArgs, findModelEntry, formatMcpToolErrorResponse, formatMcpToolResponse, generateMcpToolDefinitions, handleStreamableHttpMcpRequest, matchRouteManifestUrl, mcpManifestKey, mcpModuleMetadata, mcpSchemaDeclaresProperty, noopMcpAnalyticsService, parseUrlModelsPathname, resolveEffectiveReadOnly, resolveEnumInfoOutput, resolveMcpReasonParameterConfig, resolveMcpToolAnnotations, resolveRequiredScope, validateMcpToolName };
+export { BATCH_EXECUTE_DISPATCH_CALL, BATCH_EXECUTE_DISPATCH_MODEL_TYPE, BATCH_EXECUTE_TOOL_NAME, DEFAULT_BATCH_EXECUTE_MAX_PARALLEL, DEFAULT_JSON_SCHEMA_GENERATION_OPTIONS, DEFAULT_MCP_ANALYTICS_EVENT_NAME, DEFAULT_MCP_PATH, DEFAULT_MCP_REASON_PARAMETER_DESCRIPTION, DEFAULT_MCP_REASON_PARAMETER_MAX_LENGTH, DEFAULT_MCP_REASON_PARAMETER_NAME, DEFAULT_MCP_REASON_PARAMETER_REQUIRED, DEFAULT_MCP_SERVER_INSTRUCTIONS, DEFAULT_MCP_SERVER_NAME, DEFAULT_SPECIFIER_KEY, DEFAULT_VOID_MCP_SUCCESS_VALUE, ENUM_INFO_DISPATCH_CALL, ENUM_INFO_DISPATCH_MODEL_TYPE, ENUM_INFO_TOOL_NAME, ENUM_TABLE_SCHEMA, FIREBASE_SERVER_MCP_ANALYTICS_CONFIG, FIREBASE_SERVER_MCP_ROUTES_FOR_GLOBAL_ROUTE_EXCLUDE, FirebaseServerMcpAnalyticsService, MAX_BATCH_EXECUTE_FILE_BYTES, MAX_BATCH_EXECUTE_OPERATIONS, MCP_ANALYTICS_SERVICE, MCP_AUTH_ROLE_READER, MCP_CALL_TYPE_ABBREVIATIONS, MCP_MANIFEST_VERSION, MCP_MODEL_GET_BATCH_SIZE, MCP_TOOL_NAME_MAX_LENGTH, MCP_TOOL_NAME_WARN_LENGTH, MCP_WRITE_TOOL_DESCRIPTION_PREFIX, MODEL_DECODE_DISPATCH_CALL, MODEL_DECODE_DISPATCH_MODEL_TYPE, MODEL_DECODE_TOOL_NAME, MODEL_GET_DISPATCH_CALL, MODEL_GET_DISPATCH_MODEL_TYPE, MODEL_GET_TOOL_NAME, MODEL_INFO_DISPATCH_CALL, MODEL_INFO_DISPATCH_MODEL_TYPE, MODEL_INFO_GROUPS_HINT, MODEL_INFO_TOOL_NAME, MODEL_INFO_UNGROUPED_LABEL, McpAnalyticsService, McpController, McpModuleConfig, McpServerFactoryService, McpWellKnownController, ROUTE_MANIFEST_VERSION, URL_MODELS_DISPATCH_CALL, URL_MODELS_DISPATCH_MODEL_TYPE, URL_MODELS_TOOL_NAME, abbreviateMcpCallType, appMcpAnalyticsModuleMetadata, applyMcpReasonParameterToSchema, applyWriteMarker, batchOperationCoordKey, buildDefaultMcpToolDescription, buildDisambiguatedMcpToolName, buildMcpToolName, buildStaticToolDefinition, buildStaticWireEntry, classifyVisibility, createBatchExecuteTool, createEnumInfoTool, createModelDecodeTool, createModelGetTool, createModelInfoTool, createUrlModelsTool, decodeFirestoreModelKey, extractMcpReasonFromArgs, findModelEntry, formatMcpToolErrorResponse, formatMcpToolResponse, generateMcpToolDefinitions, handleStreamableHttpMcpRequest, matchRouteManifestUrl, mcpManifestKey, mcpModuleMetadata, mcpSchemaDeclaresProperty, noopMcpAnalyticsService, parseUrlModelsPathname, readUrlModelsImpersonationUid, resolveEffectiveReadOnly, resolveEnumInfoOutput, resolveMcpReasonParameterConfig, resolveMcpToolAnnotations, resolveRequiredScope, validateMcpToolName };

package/mcp/package.json

@@ -1,17 +1,17 @@
 {
   "name": "@dereekb/firebase-server/mcp",
-  "version": "13.22.0",
+  "version": "13.23.0",
   "peerDependencies": {
-    "@dereekb/analytics": "13.22.0",
-    "@dereekb/date": "13.22.0",
-    "@dereekb/firebase": "13.22.0",
-    "@dereekb/firebase-server": "13.22.0",
-    "@dereekb/firebase-server/oidc": "13.22.0",
-    "@dereekb/model": "13.22.0",
-    "@dereekb/nestjs": "13.22.0",
-    "@dereekb/rxjs": "13.22.0",
-    "@dereekb/util": "13.22.0",
-    "@dereekb/zoho": "13.22.0",
+    "@dereekb/analytics": "13.23.0",
+    "@dereekb/date": "13.23.0",
+    "@dereekb/firebase": "13.23.0",
+    "@dereekb/firebase-server": "13.23.0",
+    "@dereekb/firebase-server/oidc": "13.23.0",
+    "@dereekb/model": "13.23.0",
+    "@dereekb/nestjs": "13.23.0",
+    "@dereekb/rxjs": "13.23.0",
+    "@dereekb/util": "13.23.0",
+    "@dereekb/zoho": "13.23.0",
     "@modelcontextprotocol/sdk": "1.29.0",
     "@nestjs/common": "^11.1.19",
     "@nestjs/core": "^11.1.19",

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

@@ -1,3 +1,4 @@
+import { type Maybe } from '@dereekb/util';
 import { type FirestoreModelKey } from '@dereekb/firebase';
 import { type ModelAccessMultiReadResult } from '@dereekb/firebase-server';
 import { type McpToolDefinition } from '../mcp.tool-generator';
@@ -16,6 +17,19 @@ export declare const URL_MODELS_DISPATCH_CALL = "url-models";
  * 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";
+/**
+ * Reads the impersonation uid from a URL's `?imp=<uid>` query parameter, if present.
+ *
+ * Impersonation ("view as another user") is conveyed by the {@link IMPERSONATION_URL_QUERY_PARAM} query
+ * param; when set, it overrides the uid used to fill `{authUid}` placeholders so a decoded URL reports the
+ * models the impersonated user's page renders. Handles both a full URL and a bare path (mirroring
+ * {@link parseUrlModelsPathname}, which discards the query when matching). Returns the trimmed non-empty
+ * uid, or `undefined` when absent.
+ *
+ * @param url - A full URL or bare path, optionally carrying `?imp=<uid>`.
+ * @returns The impersonated uid, or `undefined`.
+ */
+export declare function readUrlModelsImpersonationUid(url: string): Maybe<string>;
 /**
  * Why a model binding could not be resolved into a concrete key.
  */
@@ -78,8 +92,9 @@ export interface UrlModelsToolInput {
     /**
      * 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.
+     * another user would see on a page. A `?imp=<uid>` (impersonation) query param
+     * on the `url` takes precedence over this. Does not affect the document-load
+     * path — `load` still reads via the calling user's permissions.
      */
     readonly currentUserUid?: string;
 }

package/model/package.json

@@ -1,15 +1,15 @@
 {
   "name": "@dereekb/firebase-server/model",
-  "version": "13.22.0",
+  "version": "13.23.0",
   "peerDependencies": {
-    "@dereekb/analytics": "13.22.0",
-    "@dereekb/date": "13.22.0",
-    "@dereekb/firebase": "13.22.0",
-    "@dereekb/firebase-server": "13.22.0",
-    "@dereekb/model": "13.22.0",
-    "@dereekb/nestjs": "13.22.0",
-    "@dereekb/rxjs": "13.22.0",
-    "@dereekb/util": "13.22.0",
+    "@dereekb/analytics": "13.23.0",
+    "@dereekb/date": "13.23.0",
+    "@dereekb/firebase": "13.23.0",
+    "@dereekb/firebase-server": "13.23.0",
+    "@dereekb/model": "13.23.0",
+    "@dereekb/nestjs": "13.23.0",
+    "@dereekb/rxjs": "13.23.0",
+    "@dereekb/util": "13.23.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.22.0",
+  "version": "13.23.0",
   "peerDependencies": {
-    "@dereekb/analytics": "13.22.0",
-    "@dereekb/date": "13.22.0",
-    "@dereekb/firebase": "13.22.0",
-    "@dereekb/firebase-server": "13.22.0",
-    "@dereekb/model": "13.22.0",
-    "@dereekb/nestjs": "13.22.0",
-    "@dereekb/rxjs": "13.22.0",
-    "@dereekb/util": "13.22.0",
-    "@dereekb/zoho": "13.22.0",
+    "@dereekb/analytics": "13.23.0",
+    "@dereekb/date": "13.23.0",
+    "@dereekb/firebase": "13.23.0",
+    "@dereekb/firebase-server": "13.23.0",
+    "@dereekb/model": "13.23.0",
+    "@dereekb/nestjs": "13.23.0",
+    "@dereekb/rxjs": "13.23.0",
+    "@dereekb/util": "13.23.0",
+    "@dereekb/zoho": "13.23.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.22.0",
+  "version": "13.23.0",
   "sideEffects": false,
   "exports": {
     "./test": {
@@ -57,15 +57,15 @@
   "types": "./src/index.d.ts",
   "peerDependencies": {
     "@cantoo/pdf-lib": "^2.6.5",
-    "@dereekb/analytics": "13.22.0",
-    "@dereekb/date": "13.22.0",
-    "@dereekb/dbx-core": "13.22.0",
-    "@dereekb/firebase": "13.22.0",
-    "@dereekb/model": "13.22.0",
-    "@dereekb/nestjs": "13.22.0",
-    "@dereekb/rxjs": "13.22.0",
-    "@dereekb/util": "13.22.0",
-    "@dereekb/zoho": "13.22.0",
+    "@dereekb/analytics": "13.23.0",
+    "@dereekb/date": "13.23.0",
+    "@dereekb/dbx-core": "13.23.0",
+    "@dereekb/firebase": "13.23.0",
+    "@dereekb/model": "13.23.0",
+    "@dereekb/nestjs": "13.23.0",
+    "@dereekb/rxjs": "13.23.0",
+    "@dereekb/util": "13.23.0",
+    "@dereekb/zoho": "13.23.0",
     "@google-cloud/firestore": "^7.11.6",
     "@google-cloud/storage": "^7.19.0",
     "@modelcontextprotocol/sdk": "1.29.0",

package/test/package.json

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

package/twilio/package.json

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

package/zoho/package.json

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