@dereekb/firebase-server 13.1.0 → 13.2.1

package/src/lib/firestore/index.d.ts

@@ -3,3 +3,4 @@ export * from './driver.accessor';
 export * from './driver.query';
 export * from './firestore';
 export * from './increment';
+export * from './snapshot';

package/src/lib/firestore/snapshot/index.d.ts

@@ -0,0 +1 @@
+export * from './snapshot.field';

package/src/lib/firestore/snapshot/snapshot.field.d.ts

@@ -0,0 +1,80 @@
+import { type Maybe, type Getter, type GetterOrValue } from '@dereekb/util';
+import { type FirestoreModelFieldMapFunctionsConfig } from '@dereekb/firebase';
+/**
+ * The source for the encryption secret.
+ *
+ * - If a string, it is used directly as the hex-encoded key (64 hex chars = 32 bytes).
+ * - If a Getter, it is called each time to retrieve the key (useful for rotation or lazy loading).
+ * - If an object with `env`, the key is read from the specified environment variable.
+ */
+export type FirestoreEncryptedFieldSecretSource = string | Getter<string> | {
+    env: string;
+};
+/**
+ * Configuration for encrypted Firestore fields.
+ *
+ * @template T - The JSON-serializable value type stored in the model.
+ */
+export interface FirestoreEncryptedFieldConfig<T> {
+    /**
+     * The encryption secret source.
+     *
+     * Expects a 64-character hex string representing a 32-byte AES-256 key.
+     */
+    readonly secret: FirestoreEncryptedFieldSecretSource;
+    /**
+     * Default model value when the Firestore data is null/undefined.
+     */
+    readonly default?: GetterOrValue<T>;
+}
+/**
+ * Configuration for optional encrypted Firestore fields.
+ *
+ * @template T - The JSON-serializable value type stored in the model.
+ */
+export interface OptionalFirestoreEncryptedFieldConfig<T> {
+    /**
+     * The encryption secret source.
+     *
+     * Expects a 64-character hex string representing a 32-byte AES-256 key.
+     */
+    readonly secret: FirestoreEncryptedFieldSecretSource;
+}
+/**
+ * Creates a Firestore field mapping that encrypts/decrypts a JSON-serializable value
+ * using AES-256-GCM. The value is stored in Firestore as a base64-encoded string.
+ *
+ * The encryption key is resolved from the configured secret source on each read/write,
+ * allowing for key rotation via environment variable changes.
+ *
+ * @example
+ * ```typescript
+ * const jwksField = firestoreEncryptedField<JWKSet>({
+ *   secret: { env: 'FIRESTORE_ENCRYPTION_KEY' },
+ *   default: () => ({ keys: [] })
+ * });
+ * ```
+ *
+ * @template T - The JSON-serializable value type.
+ * @param config - Encryption field configuration.
+ * @returns A field mapping configuration for encrypted values.
+ */
+export declare function firestoreEncryptedField<T>(config: FirestoreEncryptedFieldConfig<T>): FirestoreModelFieldMapFunctionsConfig<T, string>;
+/**
+ * Creates a Firestore field mapping for an optional encrypted field.
+ *
+ * When the value is null/undefined, it is stored/read as null. When present, it is
+ * encrypted/decrypted using AES-256-GCM.
+ *
+ * @example
+ * ```typescript
+ * const optionalSecretField = optionalFirestoreEncryptedField<OAuthClientSecret>({
+ *   secret: { env: 'FIRESTORE_ENCRYPTION_KEY' }
+ * });
+ * ```
+ *
+ * @template T - The JSON-serializable value type.
+ * @param config - Encryption field configuration.
+ * @returns A field mapping configuration for optional encrypted values.
+ */
+export declare function optionalFirestoreEncryptedField<T>(config: OptionalFirestoreEncryptedFieldConfig<T>): FirestoreModelFieldMapFunctionsConfig<Maybe<T>, Maybe<string>>;

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

@@ -0,0 +1,249 @@
+import { type Maybe } from '@dereekb/util';
+/**
+ * Reference to a type that can produce a JSON Schema representation.
+ *
+ * Compatible with ArkType's Type.toJsonSchema() and any other schema library.
+ * The optional `options` parameter allows callers to pass configuration (e.g.,
+ * ArkType's fallback handlers for predicates that can't be represented in JSON Schema).
+ */
+export interface JsonSchemaRef {
+    toJsonSchema(options?: object): object;
+}
+/**
+ * MCP-specific customization for a model function.
+ *
+ * When omitted, defaults are auto-generated from the handler's position in the call model tree.
+ */
+export interface OnCallModelFunctionMcpDetails {
+    /**
+     * Custom tool description for the MCP tool.
+     */
+    readonly description?: string;
+    /**
+     * Custom tool name override.
+     */
+    readonly name?: string;
+}
+/**
+ * API details metadata for a single model call handler function.
+ *
+ * Carries schema info (input/output types) and MCP-specific customization.
+ * Attached to handler functions via withApiDetails().
+ */
+export interface OnCallModelFunctionApiDetails {
+    /**
+     * The input parameter type. Must implement toJsonSchema() for MCP tool input schema generation.
+     */
+    readonly inputType?: JsonSchemaRef;
+    /**
+     * The output result type. Optional — many handlers return void or generic results.
+     */
+    readonly outputType?: JsonSchemaRef;
+    /**
+     * MCP-specific customization. Auto-generated if omitted.
+     */
+    readonly mcp?: OnCallModelFunctionMcpDetails;
+}
+/**
+ * Ref interface for objects (functions) that carry handler-level _apiDetails.
+ */
+export interface OnCallModelFunctionApiDetailsRef {
+    readonly _apiDetails?: OnCallModelFunctionApiDetails;
+}
+/**
+ * API details aggregated at the specifier level.
+ *
+ * Produced by onCallSpecifierHandler when its handlers carry _apiDetails.
+ * Maps specifier keys (e.g., '_', 'username', 'fromUpload') to handler-level details.
+ */
+export interface OnCallSpecifierApiDetails {
+    readonly specifiers: {
+        readonly [key: string]: OnCallModelFunctionApiDetails | undefined;
+    };
+}
+/**
+ * API details aggregated at the CRUD model level.
+ *
+ * Produced by onCallCreateModel/onCallReadModel/etc.
+ * Maps model type strings (e.g., 'profile', 'guestbook') to either handler-level
+ * details (for direct handlers) or specifier-level details (for specifier handlers).
+ */
+export interface OnCallCrudModelApiDetails {
+    readonly modelTypes: {
+        readonly [key: string]: OnCallModelFunctionApiDetails | OnCallSpecifierApiDetails | undefined;
+    };
+}
+/**
+ * API details aggregated at the top call model level.
+ *
+ * Produced by onCallModel. Maps CRUD operation strings to their model-level details.
+ */
+export interface OnCallModelApiDetails {
+    readonly create?: OnCallCrudModelApiDetails;
+    readonly read?: OnCallCrudModelApiDetails;
+    readonly update?: OnCallCrudModelApiDetails;
+    readonly delete?: OnCallCrudModelApiDetails;
+    readonly [call: string]: OnCallCrudModelApiDetails | undefined;
+}
+/**
+ * Union of all API details types at any aggregation level.
+ */
+export type OnCallApiDetails = OnCallModelFunctionApiDetails | OnCallSpecifierApiDetails | OnCallCrudModelApiDetails | OnCallModelApiDetails;
+/**
+ * Ref interface for functions at any level of the call model tree.
+ */
+export interface OnCallApiDetailsRef {
+    readonly _apiDetails?: OnCallApiDetails;
+}
+/**
+ * Whether the details are specifier-level (has specifiers map).
+ */
+export declare function isOnCallSpecifierApiDetails(details: OnCallApiDetails): details is OnCallSpecifierApiDetails;
+/**
+ * Whether the details are CRUD-model-level (has modelTypes map).
+ */
+export declare function isOnCallCrudModelApiDetails(details: OnCallApiDetails): details is OnCallCrudModelApiDetails;
+/**
+ * Whether the details are handler-level (leaf node — no specifiers or modelTypes).
+ */
+export declare function isOnCallHandlerApiDetails(details: OnCallApiDetails): details is OnCallModelFunctionApiDetails;
+/**
+ * Configuration for withApiDetails().
+ *
+ * Combines API metadata, auth configuration, and the handler function into a single config object.
+ */
+export interface WithApiDetailsConfig<F extends (...args: any[]) => any> extends OnCallModelFunctionApiDetails {
+    /**
+     * When true, marks the handler as not requiring auth (equivalent to optionalAuthContext).
+     * Sets `_requireAuth = false` on the function, allowing it to be called without auth data.
+     *
+     * This replaces the need to compose withApiDetails + optionalAuthContext separately,
+     * which would lose _apiDetails since optionalAuthContext creates a new wrapper function.
+     */
+    readonly optionalAuth?: boolean;
+    /**
+     * The handler function.
+     */
+    readonly fn: F;
+}
+/**
+ * Attaches API details metadata to a handler function.
+ *
+ * The handler function is provided in the config object alongside its metadata.
+ * The function is returned unchanged but with the _apiDetails property set.
+ * Compatible with all handler types (create, read, update, delete, specifier).
+ *
+ * When `optionalAuth: true` is set, also marks the function as not requiring auth
+ * (same effect as optionalAuthContext). This avoids the composition issue where
+ * optionalAuthContext(withApiDetails(...)) would lose the _apiDetails.
+ *
+ * @example
+ * ```typescript
+ * // Handler with api details (auth required by default)
+ * export const createGuestbook: DemoCreateModelFunction<CreateGuestbookParams> = withApiDetails({
+ *   inputType: createGuestbookParamsType,
+ *   fn: async (request) => {
+ *     const { nest, auth, data } = request;
+ *     const result = await nest.guestbookActions.createGuestbook(data);
+ *     return onCallCreateModelResultWithDocs(await result());
+ *   }
+ * });
+ *
+ * // Handler with optional auth
+ * export const profileCreate: DemoCreateModelFunction<{}> = withApiDetails({
+ *   optionalAuth: true,
+ *   fn: async (request) => { ... }
+ * });
+ * ```
+ */
+export declare function withApiDetails<F extends (...args: any[]) => any>(config: WithApiDetailsConfig<F>): F & OnCallModelFunctionApiDetailsRef;
+/**
+ * Reads _apiDetails from a function if present.
+ */
+export declare function readApiDetails(fn: Maybe<OnCallApiDetailsRef>): OnCallApiDetails | undefined;
+/**
+ * Aggregates _apiDetails from a specifier handler config object.
+ *
+ * Returns OnCallSpecifierApiDetails if any handlers have _apiDetails, otherwise undefined.
+ */
+export declare function aggregateSpecifierApiDetails(config: {
+    readonly [key: string]: Maybe<OnCallApiDetailsRef>;
+}): OnCallSpecifierApiDetails | undefined;
+/**
+ * Aggregates _apiDetails from a model type map (used by onCallCreateModel, etc.).
+ *
+ * Returns OnCallCrudModelApiDetails if any handlers have _apiDetails, otherwise undefined.
+ */
+export declare function aggregateCrudModelApiDetails(map: {
+    readonly [key: string]: Maybe<OnCallApiDetailsRef>;
+}): OnCallCrudModelApiDetails | undefined;
+/**
+ * Aggregates _apiDetails from the top-level call model map.
+ *
+ * Returns OnCallModelApiDetails if any CRUD handlers have _apiDetails, otherwise undefined.
+ */
+export declare function aggregateModelApiDetails(map: {
+    readonly [key: string]: Maybe<OnCallApiDetailsRef>;
+}): OnCallModelApiDetails | undefined;
+/**
+ * Handler or specifier-level details for a single CRUD call on a model type.
+ */
+export type ModelCallApiDetails = OnCallModelFunctionApiDetails | OnCallSpecifierApiDetails;
+/**
+ * CRUD calls available for a single model type.
+ *
+ * Keyed by call type ('create', 'read', 'update', 'delete').
+ * Each value is either handler-level details (direct handler) or specifier-level details.
+ */
+export interface ModelCallsApiDetails {
+    readonly create?: ModelCallApiDetails;
+    readonly read?: ModelCallApiDetails;
+    readonly update?: ModelCallApiDetails;
+    readonly delete?: ModelCallApiDetails;
+    readonly [call: string]: ModelCallApiDetails | undefined;
+}
+/**
+ * API details organized by model type first, then by CRUD call type.
+ *
+ * This is the consumer-friendly view of the call model tree — models are the top-level
+ * grouping, with their available CRUD operations nested underneath.
+ *
+ * @example
+ * ```typescript
+ * const details = getModelApiDetails(callModelFn);
+ * const storageFileGroupCalls = details.models['storageFileGroup'].calls;
+ * // => { update: { specifiers: { _: {...}, regenerateContent: {...} } } }
+ * ```
+ */
+export interface ModelApiDetailsResult {
+    readonly models: {
+        readonly [modelType: string]: ModelApiDetailsModelEntry;
+    };
+}
+/**
+ * API details for a single model type.
+ */
+export interface ModelApiDetailsModelEntry {
+    /**
+     * The CRUD calls available for this model type.
+     */
+    readonly calls: ModelCallsApiDetails;
+}
+/**
+ * Extracts and pivots API details from a call model function into a model-first view.
+ *
+ * The internal aggregation tree is organized as CRUD → modelType. This function
+ * pivots it to modelType → CRUD, which is the natural shape for MCP tool generation
+ * and schema introspection.
+ *
+ * @param callModelFn The function returned by onCallModel(), or any object with _apiDetails.
+ * @returns Model-first API details, or undefined if no _apiDetails are present.
+ *
+ * @example
+ * ```typescript
+ * const details = getModelApiDetails(demoCallModel);
+ * // details.models['guestbook'].calls.create => { inputType: createGuestbookParamsType }
+ * // details.models['profile'].calls.update => { specifiers: { _: {...}, username: {...} } }
+ * ```
+ */
+export declare function getModelApiDetails(callModelFn: Maybe<OnCallApiDetailsRef>): ModelApiDetailsResult | undefined;

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

@@ -3,6 +3,7 @@ import { type FirestoreModelIdentity, type FirestoreModelType, type FirestoreMod
 import { type OnCallWithAuthAwareNestContext, type OnCallWithAuthAwareNestRequireAuthRef, type OnCallWithNestContext } from '../function/call';
 import { type AssertModelCrudRequestFunctionContextCrudType, type AssertModelCrudRequestFunction } from './crud.assert.function';
 import { type NestContextCallableRequest } from '../function/nest';
+import { type OnCallApiDetailsRef } from './api.details';
 export type OnCallModelMap = {
     readonly [call: OnCallFunctionType]: OnCallWithNestContext<any, OnCallTypedModelParams>;
 };
@@ -15,7 +16,7 @@ export interface OnCallModelConfig {
  * @param map
  * @returns
  */
-export declare function onCallModel(map: OnCallModelMap, config?: OnCallModelConfig): OnCallWithNestContext<unknown, OnCallTypedModelParams>;
+export declare function onCallModel(map: OnCallModelMap, config?: OnCallModelConfig): OnCallWithNestContext<unknown, OnCallTypedModelParams> & OnCallApiDetailsRef;
 export declare function onCallModelMissingCallTypeError(): import("firebase-functions/https").HttpsError;
 export declare function onCallModelUnknownCallTypeError(call: OnCallFunctionType): import("firebase-functions/https").HttpsError;
 export type OnCallWithCallTypeModelMap<N, T extends FirestoreModelIdentity = FirestoreModelIdentity> = {
@@ -27,4 +28,4 @@ export interface OnCallWithCallTypeModelConfig<N> {
     readonly preAssert?: AssertModelCrudRequestFunction<N, OnCallTypedModelParams>;
     readonly throwOnUnknownModelType: (modelType: FirestoreModelType) => Error;
 }
-export declare function _onCallWithCallTypeFunction<N>(map: OnCallWithCallTypeModelMap<N>, config: OnCallWithCallTypeModelConfig<N>): OnCallWithAuthAwareNestContext<N, OnCallTypedModelParams, unknown>;
+export declare function _onCallWithCallTypeFunction<N>(map: OnCallWithCallTypeModelMap<N>, config: OnCallWithCallTypeModelConfig<N>): OnCallWithAuthAwareNestContext<N, OnCallTypedModelParams, unknown> & OnCallApiDetailsRef;

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

@@ -1,3 +1,4 @@
+export * from './api.details';
 export * from './permission.error';
 export * from './specifier.function';
 export * from './call.model.function';

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

@@ -2,6 +2,7 @@ import { type ModelFirebaseCrudFunctionSpecifier, type ModelFirebaseCrudFunction
 import { type Maybe, type PromiseOrValue } from '@dereekb/util';
 import { type NestContextCallableRequestWithOptionalAuth, type NestContextCallableRequestWithAuth } from '../function/nest';
 import { type OnCallWithAuthAwareNestRequireAuthRef, type OnCallWithNestContext } from '../function/call';
+import { type OnCallApiDetailsRef } from './api.details';
 export type OnCallSpecifierHandlerNestContextRequest<N, I = unknown> = NestContextCallableRequestWithAuth<N, I> & ModelFirebaseCrudFunctionSpecifierRef;
 export type OnCallSpecifierHandlerFunctionWithAuth<N, I = unknown, O = unknown> = ((request: OnCallSpecifierHandlerNestContextRequest<N, I>) => PromiseOrValue<O>) & {
     readonly _requiresAuth?: true;
@@ -18,5 +19,5 @@ export type OnCallSpecifierHandlerConfig<N> = {
     readonly _?: Maybe<OnCallSpecifierHandlerFunction<N, any, any>>;
     readonly [key: string]: Maybe<OnCallSpecifierHandlerFunction<N, any, any>>;
 };
-export declare function onCallSpecifierHandler<N, I = any, O = any>(config: OnCallSpecifierHandlerConfig<N>): OnCallWithNestContext<N, I, O> & OnCallWithAuthAwareNestRequireAuthRef;
+export declare function onCallSpecifierHandler<N, I = any, O = any>(config: OnCallSpecifierHandlerConfig<N>): OnCallWithNestContext<N, I, O> & OnCallWithAuthAwareNestRequireAuthRef & OnCallApiDetailsRef;
 export declare function unknownModelCrudFunctionSpecifierError(specifier: ModelFirebaseCrudFunctionSpecifier): import("firebase-functions/https").HttpsError;

package/test/package.json

@@ -1,14 +1,14 @@
 {
   "name": "@dereekb/firebase-server/test",
-  "version": "13.1.0",
+  "version": "13.2.1",
   "peerDependencies": {
-    "@dereekb/date": "13.1.0",
-    "@dereekb/firebase": "13.1.0",
-    "@dereekb/firebase-server": "13.1.0",
-    "@dereekb/model": "13.1.0",
-    "@dereekb/nestjs": "13.1.0",
-    "@dereekb/rxjs": "13.1.0",
-    "@dereekb/util": "13.1.0",
+    "@dereekb/date": "13.2.1",
+    "@dereekb/firebase": "13.2.1",
+    "@dereekb/firebase-server": "13.2.1",
+    "@dereekb/model": "13.2.1",
+    "@dereekb/nestjs": "13.2.1",
+    "@dereekb/rxjs": "13.2.1",
+    "@dereekb/util": "13.2.1",
     "@google-cloud/firestore": "^7.11.6",
     "@google-cloud/storage": "^7.19.0",
     "@nestjs/common": "^11.0.0",

package/zoho/package.json

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