@dereekb/firebase-server 13.2.0 → 13.2.2

package/index.cjs.js

@@ -272,7 +272,34 @@ class FirebaseServerAuthNewUserSendSetupDetailsSendOnceError extends makeError.B
     }
 }
 
-const DEFAULT_FIREBASE_PASSWORD_NUMBER_GENERATOR = util.randomNumberFactory({ min: 100000, max: 1000000, round: 'floor' }); // 6 digits
+/**
+ * Generates a random 6-digit number for use as a temporary password or reset token.
+ *
+ * Used internally by {@link AbstractFirebaseServerAuthUserContext.beginResetPassword} and
+ * {@link AbstractFirebaseServerNewUserService.generateRandomSetupPassword} for one-time codes.
+ *
+ * @example
+ * ```typescript
+ * const pin = DEFAULT_FIREBASE_PASSWORD_NUMBER_GENERATOR(); // e.g. 482910
+ * ```
+ */
+const DEFAULT_FIREBASE_PASSWORD_NUMBER_GENERATOR = util.randomNumberFactory({ min: 100000, max: 1000000, round: 'floor' });
+/**
+ * Base implementation of {@link FirebaseServerAuthUserContext} that manages a single user's
+ * auth state (record, claims, roles, password) through the Firebase Admin Auth API.
+ *
+ * Caches the user record on first load and resets the cache automatically when claims are modified
+ * via {@link setClaims}. Subclass this to bind it to a specific {@link FirebaseServerAuthService} type.
+ *
+ * @example
+ * ```typescript
+ * export class MyAuthUserContext extends AbstractFirebaseServerAuthUserContext<MyAuthService> {}
+ *
+ * const ctx = new MyAuthUserContext(authService, 'some-uid');
+ * const roles = await ctx.loadRoles();
+ * await ctx.addRoles(AUTH_ADMIN_ROLE);
+ * ```
+ */
 class AbstractFirebaseServerAuthUserContext {
     _service;
     _uid;
@@ -296,6 +323,9 @@ class AbstractFirebaseServerAuthUserContext {
     loadDetails() {
         return this.loadRecord().then((record) => this.service.authDetailsForRecord(record));
     }
+    /**
+     * Generates a random numeric string for use as a temporary reset password.
+     */
     _generateResetPasswordKey() {
         return String(DEFAULT_FIREBASE_PASSWORD_NUMBER_GENERATOR());
     }
@@ -320,9 +350,6 @@ class AbstractFirebaseServerAuthUserContext {
             return undefined;
         }
     }
-    /**
-     * Sets the user's password.
-     */
     async setPassword(password) {
         const record = await this.updateUser({ password });
         // clear password reset claims
@@ -355,15 +382,19 @@ class AbstractFirebaseServerAuthUserContext {
         return this.updateClaims(claims);
     }
     /**
-     * Sets the claims using the input roles and roles set.
+     * Replaces all role-based claims with those derived from the given roles.
      *
-     * All other claims are cleared.
+     * All existing claims are cleared first. Use `claimsToRetain` to preserve non-role claims
+     * (e.g., setup or application-specific claims) through the replacement.
      *
-     * Use the claimsToRetain input to retain other claims that are outside of the roles.
+     * @param roles - The complete set of roles to assign.
+     * @param claimsToRetain - Additional claims to merge in alongside the role-derived claims.
      *
-     * @param roles
-     * @param claimsToRetain
-     * @returns
+     * @example
+     * ```typescript
+     * // Set roles while preserving a custom claim
+     * await userCtx.setRoles([AUTH_ADMIN_ROLE], { customFlag: 1 });
+     * ```
      */
     async setRoles(roles, claimsToRetain) {
         const claims = {
@@ -372,8 +403,11 @@ class AbstractFirebaseServerAuthUserContext {
         };
         return this.setClaims(claims);
     }
+    /**
+     * Converts roles to their corresponding claim keys, filtering out null/undefined entries
+     * that represent unrelated claims in the service's {@link FirebaseServerAuthService.claimsForRoles} output.
+     */
     _claimsForRolesChange(roles) {
-        // filter null/undefined since the claims will contain null values for claims that are not related.
         return util.filterNullAndUndefinedValues(this.service.claimsForRoles(util.asSet(roles)));
     }
     loadClaims() {
@@ -403,6 +437,15 @@ class AbstractFirebaseServerAuthUserContext {
         });
     }
 }
+/**
+ * Base implementation of {@link FirebaseServerAuthContext} with cached getters for roles, admin status,
+ * and ToS status to avoid redundant computation within a single request.
+ *
+ * @example
+ * ```typescript
+ * export class MyAuthContext extends AbstractFirebaseServerAuthContext<MyAuthContext, MyUserContext, MyAuthService> {}
+ * ```
+ */
 class AbstractFirebaseServerAuthContext {
     _service;
     _context;
@@ -444,15 +487,52 @@ class AbstractFirebaseServerAuthContext {
     }
 }
 /**
- * 1 hour
+ * Default throttle duration (1 hour) between setup content sends to prevent spam.
+ *
+ * Used by {@link AbstractFirebaseServerNewUserService.sendSetupContent} to rate-limit delivery.
  */
 const DEFAULT_SETUP_COM_THROTTLE_TIME = date.hoursToMs(1);
+/**
+ * Resolves a {@link UserContextOrUid} to a concrete user context instance.
+ *
+ * If a string UID is provided, creates a new user context via the auth service.
+ * If an existing context is provided, returns it as-is.
+ *
+ * @param authService - The auth service to create a context from if needed.
+ * @param userContextOrUid - A user context or UID string.
+ *
+ * @example
+ * ```typescript
+ * const ctx = userContextFromUid(authService, 'some-uid');
+ * const sameCtx = userContextFromUid(authService, ctx); // returns ctx unchanged
+ * ```
+ */
 function userContextFromUid(authService, userContextOrUid) {
     const userContext = typeof userContextOrUid === 'string' ? authService.userContext(userContextOrUid) : userContextOrUid;
     return userContext;
 }
+/**
+ * Base implementation of {@link FirebaseServerNewUserService} that handles user creation,
+ * setup claims management, throttled setup content delivery, and setup completion.
+ *
+ * Subclasses must implement {@link sendSetupContentToUser} to define how setup content
+ * (e.g., invitation email, SMS) is delivered to the user.
+ *
+ * @example
+ * ```typescript
+ * export class MyNewUserService extends AbstractFirebaseServerNewUserService<MyUserContext> {
+ *   protected async sendSetupContentToUser(details: FirebaseServerAuthNewUserSetupDetails<MyUserContext>): Promise<void> {
+ *     await this.emailService.sendInvite(details.userContext.uid, details.claims.setupPassword);
+ *   }
+ * }
+ * ```
+ */
 class AbstractFirebaseServerNewUserService {
     _authService;
+    /**
+     * Minimum time between setup content sends. Defaults to {@link DEFAULT_SETUP_COM_THROTTLE_TIME} (1 hour).
+     * Override in subclasses to customize the throttle window.
+     */
     setupThrottleTime = DEFAULT_SETUP_COM_THROTTLE_TIME;
     constructor(authService) {
         this._authService = authService;
@@ -564,19 +644,15 @@ class AbstractFirebaseServerNewUserService {
         }
         return details;
     }
+    /**
+     * Records the current timestamp as the last setup content communication date in the user's claims.
+     */
     async updateSetupContentSentTime(details) {
         const setupCommunicationAt = date.toISODateString(new Date());
         await details.userContext.updateClaims({
             setupCommunicationAt
         });
     }
-    /**
-     * Update a user's claims to clear any setup-related content.
-     *
-     * Returns true if a user was updated.
-     *
-     * @param uid
-     */
     async markUserSetupAsComplete(uid) {
         const userContext = this.authService.userContext(uid);
         const userExists = await userContext.exists();
@@ -585,6 +661,13 @@ class AbstractFirebaseServerNewUserService {
         }
         return userExists;
     }
+    /**
+     * Creates a new Firebase Auth user from the initialization input.
+     *
+     * Generates a random setup password if none is provided. Override to customize user creation behavior.
+     *
+     * @throws Throws if the Firebase Admin SDK rejects the user creation.
+     */
     async createNewUser(input) {
         const { uid, displayName, email, phone: phoneNumber, setupPassword: inputPassword } = input;
         const password = inputPassword ?? this.generateRandomSetupPassword();
@@ -603,6 +686,9 @@ class AbstractFirebaseServerNewUserService {
     generateRandomSetupPassword() {
         return `${DEFAULT_FIREBASE_PASSWORD_NUMBER_GENERATOR()}`;
     }
+    /**
+     * Clears setup-related claims (setup password and last communication date) from the user.
+     */
     async updateClaimsToClearUser(userContext) {
         await userContext.updateClaims({
             [firebase.FIREBASE_SERVER_AUTH_CLAIMS_SETUP_PASSWORD_KEY]: null,
@@ -610,18 +696,65 @@ class AbstractFirebaseServerNewUserService {
         });
     }
 }
+/**
+ * No-op implementation of {@link AbstractFirebaseServerNewUserService} that skips sending setup content.
+ *
+ * Used as the default {@link FirebaseServerNewUserService} when no custom delivery mechanism is configured.
+ */
 class NoSetupContentFirebaseServerNewUserService extends AbstractFirebaseServerNewUserService {
-    async sendSetupContentToUser(user) {
+    async sendSetupContentToUser(_details) {
         // send nothing.
     }
 }
 /**
- * FirebaseServer auth service that provides accessors to auth-related components.
+ * Abstract contract for a Firebase Server authentication service.
+ *
+ * Provides the core API for creating auth contexts from callable requests, managing user contexts,
+ * checking admin/ToS status, converting between roles and claims, and creating new users.
+ *
+ * Implement this by extending {@link AbstractFirebaseServerAuthService}, which provides default
+ * implementations for most methods and only requires `readRoles`, `claimsForRoles`,
+ * `userContext`, and `_context` to be defined.
+ *
+ * @example
+ * ```typescript
+ * class MyAuthService extends AbstractFirebaseServerAuthService<MyUserContext, MyAuthContext> {
+ *   readRoles(claims: AuthClaims): AuthRoleSet { ... }
+ *   claimsForRoles(roles: AuthRoleSet): AuthClaimsUpdate { ... }
+ *   userContext(uid: string): MyUserContext { ... }
+ *   protected _context(ctx: CallableContextWithAuthData): MyAuthContext { ... }
+ * }
+ * ```
  */
 class FirebaseServerAuthService {
 }
 /**
- * Abstract FirebaseServerAuthService implementation.
+ * Base implementation of {@link FirebaseServerAuthService} providing standard admin/ToS checks,
+ * auth context creation with assertion, and a default no-op new user service.
+ *
+ * Subclasses must implement:
+ * - {@link _context} - to create the concrete auth context type.
+ * - {@link userContext} - to create the concrete user context type.
+ * - {@link readRoles} - to define the claims-to-roles mapping.
+ * - {@link claimsForRoles} - to define the roles-to-claims mapping.
+ *
+ * @example
+ * ```typescript
+ * export class MyAuthService extends AbstractFirebaseServerAuthService<MyUserContext, MyAuthContext> {
+ *   protected _context(context: CallableContextWithAuthData): MyAuthContext {
+ *     return new MyAuthContext(this, context);
+ *   }
+ *   userContext(uid: string): MyUserContext {
+ *     return new MyUserContext(this, uid);
+ *   }
+ *   readRoles(claims: AuthClaims): AuthRoleSet {
+ *     return MY_CLAIMS_SERVICE.toRoles(claims);
+ *   }
+ *   claimsForRoles(roles: AuthRoleSet): AuthClaimsUpdate {
+ *     return MY_CLAIMS_SERVICE.toClaims(roles);
+ *   }
+ * }
+ * ```
  */
 class AbstractFirebaseServerAuthService {
     _auth;
@@ -2027,6 +2160,163 @@ exports.ConfigureFirebaseWebhookMiddlewareModule = __decorate([
     common.Module({})
 ], exports.ConfigureFirebaseWebhookMiddlewareModule);
 
+// MARK: Type Guards
+/**
+ * Whether the details are specifier-level (has specifiers map).
+ */
+function isOnCallSpecifierApiDetails(details) {
+    return details != null && 'specifiers' in details;
+}
+/**
+ * Whether the details are CRUD-model-level (has modelTypes map).
+ */
+function isOnCallCrudModelApiDetails(details) {
+    return details != null && 'modelTypes' in details;
+}
+/**
+ * Whether the details are handler-level (leaf node — no specifiers or modelTypes).
+ */
+function isOnCallHandlerApiDetails(details) {
+    return details != null && !('specifiers' in details) && !('modelTypes' in details);
+}
+/**
+ * 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) => { ... }
+ * });
+ * ```
+ */
+function withApiDetails(config) {
+    const { optionalAuth, fn, ...apiDetails } = config;
+    fn._apiDetails = apiDetails;
+    if (optionalAuth) {
+        fn._requireAuth = false;
+    }
+    return fn;
+}
+// MARK: Aggregation Utilities
+/**
+ * Reads _apiDetails from a function if present.
+ */
+function readApiDetails(fn) {
+    return fn?._apiDetails;
+}
+/**
+ * Aggregates _apiDetails from a specifier handler config object.
+ *
+ * Returns OnCallSpecifierApiDetails if any handlers have _apiDetails, otherwise undefined.
+ */
+function aggregateSpecifierApiDetails(config) {
+    const specifiers = {};
+    let hasAny = false;
+    for (const [key, handler] of Object.entries(config)) {
+        const details = readApiDetails(handler);
+        if (details != null) {
+            // At the specifier level, details should be handler-level (OnCallModelFunctionApiDetails)
+            specifiers[key] = details;
+            hasAny = true;
+        }
+    }
+    return hasAny ? { specifiers } : undefined;
+}
+/**
+ * Aggregates _apiDetails from a model type map (used by onCallCreateModel, etc.).
+ *
+ * Returns OnCallCrudModelApiDetails if any handlers have _apiDetails, otherwise undefined.
+ */
+function aggregateCrudModelApiDetails(map) {
+    const modelTypes = {};
+    let hasAny = false;
+    for (const [key, handler] of Object.entries(map)) {
+        const details = readApiDetails(handler);
+        if (details != null) {
+            modelTypes[key] = details;
+            hasAny = true;
+        }
+    }
+    return hasAny ? { modelTypes } : undefined;
+}
+/**
+ * Aggregates _apiDetails from the top-level call model map.
+ *
+ * Returns OnCallModelApiDetails if any CRUD handlers have _apiDetails, otherwise undefined.
+ */
+function aggregateModelApiDetails(map) {
+    const result = {};
+    let hasAny = false;
+    for (const [call, handler] of Object.entries(map)) {
+        const details = readApiDetails(handler);
+        if (details != null) {
+            result[call] = details;
+            hasAny = true;
+        }
+    }
+    return hasAny ? result : undefined;
+}
+/**
+ * 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: {...} } }
+ * ```
+ */
+function getModelApiDetails(callModelFn) {
+    const topDetails = readApiDetails(callModelFn);
+    if (topDetails == null) {
+        return undefined;
+    }
+    const models = {};
+    // Pivot: iterate CRUD types, then model types within each
+    for (const [callType, crudDetails] of Object.entries(topDetails)) {
+        if (crudDetails == null) {
+            continue;
+        }
+        for (const [modelType, modelDetails] of Object.entries(crudDetails.modelTypes)) {
+            if (modelDetails == null) {
+                continue;
+            }
+            if (!models[modelType]) {
+                models[modelType] = { calls: {} };
+            }
+            models[modelType].calls[callType] = modelDetails;
+        }
+    }
+    return Object.keys(models).length > 0 ? { models } : undefined;
+}
+
 const nestFirebaseDoesNotExistError = (firebaseContextGrantedModelRoles) => {
     return modelNotAvailableError({
         data: {
@@ -2059,6 +2349,11 @@ function onCallSpecifierHandler(config) {
         }
     };
     fn._requireAuth = false;
+    // Aggregate _apiDetails from handler functions in the config
+    const specifierApiDetails = aggregateSpecifierApiDetails(config);
+    if (specifierApiDetails != null) {
+        fn._apiDetails = specifierApiDetails;
+    }
     return fn;
 }
 function unknownModelCrudFunctionSpecifierError(specifier) {
@@ -2080,7 +2375,7 @@ function unknownModelCrudFunctionSpecifierError(specifier) {
  */
 function onCallModel(map, config = {}) {
     const { preAssert = () => undefined } = config;
-    return (request) => {
+    const fn = (request) => {
         const call = request.data?.call;
         if (call) {
             const callFn = map[call];
@@ -2097,6 +2392,12 @@ function onCallModel(map, config = {}) {
             throw onCallModelMissingCallTypeError();
         }
     };
+    // Aggregate _apiDetails from CRUD handlers in the map
+    const modelApiDetails = aggregateModelApiDetails(map);
+    if (modelApiDetails != null) {
+        fn._apiDetails = modelApiDetails;
+    }
+    return fn;
 }
 function onCallModelMissingCallTypeError() {
     return badRequestError(util.serverError({
@@ -2117,7 +2418,7 @@ function onCallModelUnknownCallTypeError(call) {
 }
 function _onCallWithCallTypeFunction(map, config) {
     const { callType, crudType, preAssert = () => undefined, throwOnUnknownModelType } = config;
-    return (request) => {
+    const fn = (request) => {
         const modelType = request.data?.modelType;
         const crudFn = map[modelType];
         if (crudFn) {
@@ -2134,6 +2435,12 @@ function _onCallWithCallTypeFunction(map, config) {
             throw throwOnUnknownModelType(modelType);
         }
     };
+    // Aggregate _apiDetails from model type handlers in the map
+    const crudModelApiDetails = aggregateCrudModelApiDetails(map);
+    if (crudModelApiDetails != null) {
+        fn._apiDetails = crudModelApiDetails;
+    }
+    return fn;
 }
 
 function onCallCreateModel(map, config = {}) {
@@ -2862,6 +3169,9 @@ exports.UNAVAILABLE_OR_DEACTIVATED_FUNCTION_ERROR_CODE = UNAVAILABLE_OR_DEACTIVA
 exports.UNKNOWN_SCHEDULED_FUNCTION_DEVELOPMENT_FUNCTION_NAME_CODE = UNKNOWN_SCHEDULED_FUNCTION_DEVELOPMENT_FUNCTION_NAME_CODE;
 exports.UNKNOWN_SCHEDULED_FUNCTION_DEVELOPMENT_FUNCTION_TYPE_CODE = UNKNOWN_SCHEDULED_FUNCTION_DEVELOPMENT_FUNCTION_TYPE_CODE;
 exports._onCallWithCallTypeFunction = _onCallWithCallTypeFunction;
+exports.aggregateCrudModelApiDetails = aggregateCrudModelApiDetails;
+exports.aggregateModelApiDetails = aggregateModelApiDetails;
+exports.aggregateSpecifierApiDetails = aggregateSpecifierApiDetails;
 exports.alreadyExistsError = alreadyExistsError;
 exports.appFirestoreModuleMetadata = appFirestoreModuleMetadata;
 exports.assertContextHasAuth = assertContextHasAuth;
@@ -2905,6 +3215,7 @@ exports.firestoreEncryptedField = firestoreEncryptedField;
 exports.firestoreServerIncrementUpdateToUpdateData = firestoreServerIncrementUpdateToUpdateData;
 exports.forbiddenError = forbiddenError;
 exports.getAuthUserOrUndefined = getAuthUserOrUndefined;
+exports.getModelApiDetails = getModelApiDetails;
 exports.googleCloudFileMetadataToStorageMetadata = googleCloudFileMetadataToStorageMetadata;
 exports.googleCloudFirebaseStorageContextFactory = googleCloudFirebaseStorageContextFactory;
 exports.googleCloudFirebaseStorageDrivers = googleCloudFirebaseStorageDrivers;
@@ -2933,6 +3244,9 @@ exports.isAdminOrTargetUserInRequestData = isAdminOrTargetUserInRequestData;
 exports.isContextWithAuthData = isContextWithAuthData;
 exports.isFirebaseError = isFirebaseError;
 exports.isFirebaseHttpsError = isFirebaseHttpsError;
+exports.isOnCallCrudModelApiDetails = isOnCallCrudModelApiDetails;
+exports.isOnCallHandlerApiDetails = isOnCallHandlerApiDetails;
+exports.isOnCallSpecifierApiDetails = isOnCallSpecifierApiDetails;
 exports.makeBlockingFunctionWithHandler = makeBlockingFunctionWithHandler;
 exports.makeOnScheduleHandlerWithNestApplicationRequest = makeOnScheduleHandlerWithNestApplicationRequest;
 exports.makeScheduledFunctionDevelopmentFunction = makeScheduledFunctionDevelopmentFunction;
@@ -2965,6 +3279,7 @@ exports.preconditionConflictError = preconditionConflictError;
 exports.provideAppFirestoreCollections = provideAppFirestoreCollections;
 exports.provideFirebaseServerAuthService = provideFirebaseServerAuthService;
 exports.provideFirebaseServerStorageService = provideFirebaseServerStorageService;
+exports.readApiDetails = readApiDetails;
 exports.readModelUnknownModelTypeError = readModelUnknownModelTypeError;
 exports.setNestContextOnRequest = setNestContextOnRequest;
 exports.setNestContextOnScheduleRequest = setNestContextOnScheduleRequest;
@@ -2980,4 +3295,5 @@ exports.unknownScheduledFunctionDevelopmentFunctionType = unknownScheduledFuncti
 exports.updateModelUnknownModelTypeError = updateModelUnknownModelTypeError;
 exports.userContextFromUid = userContextFromUid;
 exports.verifyAppCheckInRequest = verifyAppCheckInRequest;
+exports.withApiDetails = withApiDetails;
 //# sourceMappingURL=index.cjs.js.map