@dereekb/firebase-server 13.11.18 → 13.12.0

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

@@ -1,5 +1,6 @@
-import { type Maybe } from '@dereekb/util';
+import { type AuthRole, type Maybe } 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';
 /**
  * Reference to a type that can produce a JSON Schema representation.
@@ -39,6 +40,97 @@ export interface McpToolResponseContentBlock {
     readonly mimeType?: string;
     readonly data?: string;
 }
+/**
+ * Minimal dispatch coordinates surfaced to a dynamic visibility predicate so a
+ * shared function can branch by tool identity.
+ *
+ * Structurally satisfied by the MCP tool generator's `McpToolDispatchTarget`.
+ */
+export interface McpToolVisibilityDispatchTarget {
+    readonly call: string;
+    readonly modelType: string;
+    readonly specifier?: string;
+}
+/**
+ * Declarative visibility rule. Evaluated per-request without invoking user code.
+ */
+export interface McpVisibilityRule {
+    /**
+     * Caller must hold every role listed (AND-semantics). Empty array is vacuously true.
+     */
+    readonly requiredRoles?: ReadonlyArray<AuthRole>;
+    /**
+     * When true, the caller must be authenticated (`ctx.auth != null`).
+     */
+    readonly requireAuthenticated?: boolean;
+}
+/**
+ * Context passed to the dynamic visibility function form.
+ */
+export interface McpVisibilityContext {
+    /**
+     * The authenticated caller, when present. `undefined` for anonymous callers.
+     */
+    readonly auth?: FirebaseServerAuthData;
+    /**
+     * The caller's OIDC scopes, when the request was authenticated with a `scope`-bearing token.
+     * `undefined` for non-OIDC callers — treated the same as `oidcCallModelScopePreAssert` bypass.
+     */
+    readonly scopes?: ReadonlySet<string>;
+    /**
+     * Dispatch identity of the tool being evaluated. Lets a shared predicate branch by tool.
+     */
+    readonly tool: McpToolVisibilityDispatchTarget;
+}
+/**
+ * Per-handler MCP visibility, evaluated cheap-to-expensive at request time.
+ *
+ * - `boolean`: `true` means "always visible (subject to scope)"; `false` means "never visible".
+ * - {@link McpVisibilityRule}: declarative check (role / auth gate), no user code invoked.
+ * - Function: synchronous predicate invoked per request. MUST be synchronous — async checks
+ *   introduce unbounded `tools/list` latency. If the function throws, the framework treats the
+ *   result as `false` (fail-closed) and logs a warning.
+ *
+ * `visibility: true` does NOT bypass the OIDC scope filter — scope is the absolute first gate
+ * and `visibility` only narrows further.
+ */
+export type McpToolVisibility = boolean | McpVisibilityRule | ((context: McpVisibilityContext) => boolean);
+/**
+ * Input passed to a {@link McpToolDetailsBuilder}.
+ *
+ * `defaultDescription` and `defaultInputSchema` reflect the framework's boot-time resolved
+ * values (manifest entry if present, otherwise the auto-generated defaults). Builders can
+ * return them verbatim, mutate a copy, or replace them entirely.
+ *
+ * `auth` and `scopes` come from the same per-request context the MCP visibility predicate
+ * sees. `undefined` for anonymous / non-OIDC callers.
+ */
+export interface McpToolDetailsBuilderInput {
+    readonly dispatch: McpToolVisibilityDispatchTarget;
+    readonly defaultDescription: string;
+    readonly defaultInputSchema?: object;
+    readonly auth?: FirebaseServerAuthData;
+    readonly scopes?: ReadonlySet<string>;
+}
+/**
+ * Builder output. Either field can be omitted to keep the framework default;
+ * returning an empty object is a no-op.
+ */
+export interface McpToolDetailsBuilderResult {
+    readonly description?: string;
+    readonly inputSchema?: object;
+}
+/**
+ * Synchronous builder invoked once per `tools/list` request, after the visibility filter
+ * has accepted the tool.
+ *
+ * MUST be synchronous — async work would introduce unbounded `tools/list` latency, matching
+ * the visibility-predicate constraint.
+ *
+ * If the builder throws, the framework falls back to the defaults and logs a warning
+ * (fail-soft).
+ */
+export type McpToolDetailsBuilder = (input: McpToolDetailsBuilderInput) => McpToolDetailsBuilderResult;
 /**
  * MCP-specific customization for a model function.
  *
@@ -52,10 +144,6 @@ export interface McpToolResponseContentBlock {
  * Resolution order: formatResponse > summarizeResponse > auto-generated default.
  */
 export interface OnCallModelFunctionMcpDetails {
-    /**
-     * Custom tool description for the MCP tool.
-     */
-    readonly description?: string;
     /**
      * Custom tool name override.
      */
@@ -81,6 +169,29 @@ export interface OnCallModelFunctionMcpDetails {
      * @returns The full MCP tool response content.
      */
     readonly formatResponse?: (result: unknown, params: OnCallTypedModelParams) => McpToolResponseContent;
+    /**
+     * Controls whether this handler's tool is advertised on `tools/list` for a given request.
+     *
+     * See {@link McpToolVisibility} for the three accepted forms. Always applied after the
+     * OIDC scope filter and the module-level `readOnly` check.
+     */
+    readonly visibility?: McpToolVisibility;
+    /**
+     * Explicit override for the effective read-only classification of this handler.
+     *
+     * When unset, the framework infers from the call type: `read` and `query` → true,
+     * `create`/`update`/`delete` → false, anything else → undefined (treated as a write
+     * for fail-safe filtering when `McpModuleConfig.readOnly` is on).
+     */
+    readonly readOnly?: boolean;
+    /**
+     * Optional per-request builder that produces enriched tool description / inputSchema
+     * for `tools/list`. See {@link McpToolDetailsBuilder}.
+     *
+     * Tools without a builder reuse a precomputed wire entry, so this opt-in only adds
+     * overhead to the handlers that need it.
+     */
+    readonly toolDetails?: McpToolDetailsBuilder;
 }
 /**
  * API details metadata for a single model call handler function.

package/src/lib/nest/model/crud.assert.function.d.ts

@@ -7,7 +7,7 @@ import { type OnCallFunctionType, type FirestoreModelType } from '@dereekb/fireb
  * Used by {@link AssertModelCrudRequestFunction} to let assertions branch on operation type,
  * enabling cross-cutting rules like "block all deletes for archived models."
  */
-export type AssertModelCrudRequestFunctionContextCrudType = 'call' | 'create' | 'read' | 'update' | 'delete' | 'query';
+export type AssertModelCrudRequestFunctionContextCrudType = 'call' | 'create' | 'read' | 'update' | 'delete' | 'query' | 'invoke';
 /**
  * Context passed to a {@link AssertModelCrudRequestFunction} before a CRUD handler executes.
  *

package/src/lib/nest/model/index.d.ts

@@ -11,3 +11,4 @@ export * from './read.model.function';
 export * from './update.model.function';
 export * from './delete.model.function';
 export * from './query.model.function';
+export * from './invoke.model.function';

package/src/lib/nest/model/invoke.model.function.d.ts

@@ -0,0 +1,89 @@
+import { type PromiseOrValue } from '@dereekb/util';
+import { type FirestoreModelType, type FirestoreModelIdentity, type FirestoreModelTypes, type OnCallInvokeModelParams, type ModelFirebaseCrudFunctionSpecifierRef } from '@dereekb/firebase';
+import { type OnCallWithAuthAwareNestRequireAuthRef, type OnCallWithNestContext } from '../function/call';
+import { type NestContextCallableRequestWithAuth, type NestContextCallableRequestWithOptionalAuth } from '../function/nest';
+import { type AssertModelCrudRequestFunction } from './crud.assert.function';
+/**
+ * Request type for model invoke handlers that require authentication.
+ *
+ * Invoke is the sixth call type (alongside CRUDQ) for side-effecting RPC-style operations
+ * that don't map cleanly onto any CRUD verb — e.g. regenerate-thumbnails, resync-with-external,
+ * recompute-index. Each handler is bound to a model type; permission checks use `useModel()`
+ * exactly like an update handler.
+ *
+ * @typeParam N - The NestJS context type.
+ * @typeParam I - The input data type for the invoke operation.
+ */
+export type OnCallInvokeModelRequest<N, I = unknown> = NestContextCallableRequestWithAuth<N, I> & ModelFirebaseCrudFunctionSpecifierRef;
+/**
+ * A model invoke handler function that requires an authenticated caller.
+ */
+export type OnCallInvokeModelFunctionWithAuth<N, I = unknown, O = unknown> = ((request: OnCallInvokeModelRequest<N, I>) => PromiseOrValue<O>) & {
+    readonly _requiresAuth?: true;
+};
+/**
+ * Request type for model invoke handlers that allow unauthenticated callers.
+ */
+export type OnCallInvokeModelRequestWithOptionalAuth<N, I = unknown> = NestContextCallableRequestWithOptionalAuth<N, I> & ModelFirebaseCrudFunctionSpecifierRef;
+/**
+ * A model invoke handler function that does not require authentication.
+ */
+export type OnCallInvokeModelFunctionWithOptionalAuth<N, I = unknown, O = unknown> = ((request: OnCallInvokeModelRequestWithOptionalAuth<N, I>) => PromiseOrValue<O>) & {
+    readonly _requireAuth: false;
+};
+/**
+ * Standard model invoke handler requiring auth (the common case).
+ */
+export type OnCallInvokeModelFunction<N, I = unknown, O = unknown> = OnCallInvokeModelFunctionWithAuth<N, I, O> & OnCallWithAuthAwareNestRequireAuthRef;
+/**
+ * Union of auth-required and optional-auth invoke handlers.
+ */
+export type OnCallInvokeModelFunctionAuthAware<N, I = unknown, O = unknown> = OnCallInvokeModelFunction<N, I, O> | OnCallInvokeModelFunctionWithOptionalAuth<N, I, O>;
+/**
+ * Maps Firestore model type strings to their invoke handler functions.
+ *
+ * Pass this map to {@link onCallInvokeModel} to register all model types
+ * that support invoke RPCs through the call model system.
+ *
+ * @typeParam N - The NestJS context type.
+ * @typeParam T - The Firestore model identity constraining valid model type keys.
+ */
+export type OnCallInvokeModelMap<N, T extends FirestoreModelIdentity = FirestoreModelIdentity> = {
+    readonly [K in FirestoreModelTypes<T>]?: OnCallInvokeModelFunctionAuthAware<N, any, any>;
+};
+/**
+ * Configuration for {@link onCallInvokeModel}.
+ */
+export interface OnCallInvokeModelConfig<N> {
+    /**
+     * Optional assertion run before the invoke handler; throw to reject.
+     */
+    readonly preAssert?: AssertModelCrudRequestFunction<N, OnCallInvokeModelParams>;
+}
+/**
+ * Factory that creates a callable function handling model invokes for multiple model types.
+ *
+ * Dispatches to the correct handler based on the `modelType` field in the request,
+ * enforces auth requirements per handler, and aggregates API details for MCP introspection.
+ *
+ * @param map - Maps model type strings to their invoke handler functions.
+ * @param config - Optional configuration including a pre-assertion hook.
+ * @returns A callable function for the 'invoke' call operation.
+ *
+ * @example
+ * ```typescript
+ * const invokeHandler = onCallInvokeModel<DemoNestContext>({
+ *   guestbookEntry: onCallSpecifierHandler({
+ *     recomputeLikes: guestbookEntryRecomputeLikes
+ *   })
+ * });
+ * ```
+ */
+export declare function onCallInvokeModel<N>(map: OnCallInvokeModelMap<N>, config?: OnCallInvokeModelConfig<N>): OnCallWithNestContext<N, OnCallInvokeModelParams, unknown>;
+/**
+ * Creates a bad-request error indicating the requested model type is not valid for invoking.
+ *
+ * @param modelType - The unrecognized model type string.
+ * @returns A bad-request error with {@link UNKNOWN_MODEL_TYPE_ERROR_CODE} code.
+ */
+export declare function invokeModelUnknownModelTypeError(modelType: FirestoreModelType): import("firebase-functions/https").HttpsError;

package/test/package.json

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

package/twilio/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Hapier Creative LLC.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/twilio/index.cjs.default.js

@@ -0,0 +1 @@
+exports._default = require('./index.cjs.js').default;