@dereekb/firebase-server 13.2.1 → 13.3.0

package/model/src/lib/notification/notification.error.d.ts

@@ -1,11 +1,74 @@
 import { type FirestoreModelKey, type FirebaseAuthUserId } from '@dereekb/firebase';
+/**
+ * Creates an error indicating that a required notification ID was missing during creation.
+ *
+ * Thrown when attempting to create a {@link Notification} document without providing the mandatory ID field.
+ */
 export declare function createNotificationIdRequiredError(): import("firebase-functions/https").HttpsError;
+/**
+ * Creates an error indicating that a notification model (box or summary) has already been initialized.
+ *
+ * Thrown during initialization when `throwErrorIfAlreadyInitialized` is true and the model's
+ * setup flag (`s`) indicates it was previously initialized.
+ */
 export declare function notificationModelAlreadyInitializedError(): import("firebase-functions/https").HttpsError;
+/**
+ * Creates an error indicating that a {@link NotificationBox} is associated with an unregistered model type.
+ *
+ * Thrown when the model key's collection name does not match any registered notification model type.
+ *
+ * @param key - the Firestore model key that has no registered notification model type
+ */
 export declare function notificationBoxUnregistredModelTypeInitializationError(key: FirestoreModelKey): import("firebase-functions/https").HttpsError;
+/**
+ * Creates an error indicating that no {@link NotificationBox} exists for the target model.
+ *
+ * Thrown when an operation requires a NotificationBox but none has been created for the given model key.
+ */
 export declare function notificationBoxDoesNotExist(): import("firebase-functions/https").HttpsError;
+/**
+ * Creates an error indicating that the exclusion target is invalid.
+ *
+ * Thrown when the target recipient on the {@link NotificationBox} does not exist on the box
+ * or does not have a UID, making it ineligible for exclusion.
+ */
 export declare function notificationBoxExclusionTargetInvalidError(): import("firebase-functions/https").HttpsError;
+/**
+ * Creates an error indicating that a {@link NotificationBox} already exists for this model.
+ *
+ * Thrown when attempting to create a duplicate NotificationBox for a model that already has one.
+ */
 export declare function notificationBoxExistsForModelError(): import("firebase-functions/https").HttpsError;
+/**
+ * Creates an error indicating that the target recipient does not exist on the {@link NotificationBox}.
+ *
+ * Thrown when attempting to update a recipient that is not registered on the box
+ * and `insert=true` was not passed to allow creating a new recipient entry.
+ */
 export declare function notificationBoxRecipientDoesNotExistsError(): import("firebase-functions/https").HttpsError;
+/**
+ * Creates an error indicating that the given UID does not correspond to an existing Firebase Auth user.
+ *
+ * Thrown during {@link NotificationUser} creation when the provided UID cannot be found in Firebase Auth.
+ *
+ * @param uid - the Firebase Auth user ID that was not found
+ */
 export declare function notificationUserInvalidUidForCreateError(uid: FirebaseAuthUserId): import("firebase-functions/https").HttpsError;
+/**
+ * Creates an error indicating that the user has blocked themselves from being added as a recipient.
+ *
+ * Thrown when a {@link NotificationUser} has the `bk` (blocked-from-add) flag set on their config
+ * and an operation attempts to insert them into a {@link NotificationBox}'s recipient list.
+ *
+ * @param uid - the Firebase Auth user ID of the blocked user
+ */
 export declare function notificationUserBlockedFromBeingAddedToRecipientsError(uid: FirebaseAuthUserId): import("firebase-functions/https").HttpsError;
+/**
+ * Creates an error indicating that the user has locked their notification configuration from external updates.
+ *
+ * Thrown when a {@link NotificationUser} has the `lk` (locked) flag set on their config
+ * and an operation attempts to modify their recipient settings on a {@link NotificationBox}.
+ *
+ * @param uid - the Firebase Auth user ID of the locked user
+ */
 export declare function notificationUserLockedConfigFromBeingUpdatedError(uid: FirebaseAuthUserId): import("firebase-functions/https").HttpsError;

package/model/src/lib/notification/notification.module.d.ts

@@ -6,6 +6,10 @@ import { type Maybe } from '@dereekb/util';
 import { NotificationSendService } from './notification.send.service';
 import { NotificationTaskService } from './notification.task.service';
 import { MutableNotificationExpediteService, NotificationExpediteService } from './notification.expedite.service';
+/**
+ * Factory that assembles the full {@link NotificationServerActionsContext} by combining
+ * the base context with the template, send, task, and expedite services.
+ */
 export declare function notificationServerActionsContextFactory(context: BaseNotificationServerActionsContext, notificationTemplateService: NotificationTemplateService, notificationSendService: NotificationSendService, notificationTaskService: NotificationTaskService, notificationsExpediteService: NotificationExpediteService): {
     notificationTemplateService: NotificationTemplateService;
     notificationSendService: NotificationSendService;
@@ -23,7 +27,14 @@ export declare function notificationServerActionsContextFactory(context: BaseNot
     authService: import("dist/packages/firebase-server/src").FirebaseServerAuthService<import("dist/packages/firebase-server/src").FirebaseServerAuthUserContext, import("dist/packages/firebase-server/src").FirebaseServerAuthContext<import("dist/packages/firebase-server/src").FirebaseServerAuthUserContext>>;
     firestoreContext: import("@dereekb/firebase").FirestoreContext<import("@dereekb/firebase").Firestore>;
 };
+/**
+ * Factory that creates a {@link NotificationServerActions} instance from the assembled context.
+ */
 export declare function notificationServerActionsFactory(context: NotificationServerActionsContext, mutableNotificationExpediteService: MutableNotificationExpediteService): NotificationServerActions;
+/**
+ * Factory that creates a {@link NotificationInitServerActions} instance by merging the
+ * server actions context with the init-specific configuration.
+ */
 export declare function notificationInitServerActionsFactory(context: NotificationServerActionsContext, notificationInitServerActionsContextConfig: NotificationInitServerActionsContextConfig): NotificationInitServerActions;
 export interface ProvideAppNotificationMetadataConfig extends Pick<ModuleMetadata, 'imports' | 'exports' | 'providers'> {
     /**

package/model/src/lib/notification/notification.send.d.ts

@@ -1,4 +1,11 @@
 /**
- * A function that is pre-configured to send the configured notification messages.
+ * A pre-configured function that sends notification messages through a specific channel (email, SMS, or summary)
+ * and returns the channel-specific result.
+ *
+ * Created by the `buildSendInstance*` methods on the various send services
+ * (e.g., {@link NotificationEmailSendService}, {@link NotificationTextSendService}).
+ * The messages and routing are captured at build time, so calling the instance simply triggers delivery.
+ *
+ * @template R - the channel-specific result type (e.g., {@link NotificationSendEmailMessagesResult})
  */
 export type NotificationSendMessagesInstance<R> = () => Promise<R>;

package/model/src/lib/notification/notification.send.service.d.ts

@@ -8,7 +8,13 @@ export interface NotificationSendServiceRef {
     readonly notificationSendService: NotificationSendService;
 }
 /**
- * Service dedicated to providing access to NotificationMessageFunctionFactory values for specific NotificationTemplateTypes.
+ * Abstract service that orchestrates notification delivery across multiple channels (email, SMS, notification summaries).
+ *
+ * Implementations provide the channel-specific send services and optionally a function to derive
+ * {@link NotificationSummaryId} values from UIDs for in-app notification storage.
+ *
+ * Used by {@link NotificationServerActions} during the `sendNotification` flow to build
+ * and dispatch messages to all applicable channels.
  */
 export declare abstract class NotificationSendService {
     /**

package/model/src/lib/notification/notification.send.service.notificationsummary.d.ts

@@ -2,17 +2,47 @@ import { type NotificationFirestoreCollections, type FirestoreContextReference,
 import { type FirebaseServerActionsContext } from '@dereekb/firebase-server';
 import { type NotificationSummarySendService } from './notification.send.service';
 import { type Maybe } from '@dereekb/util';
+/**
+ * Configuration for creating a {@link FirestoreNotificationSummarySendService}.
+ */
 export interface FirestoreNotificationSummarySendServiceConfig {
     /**
-     * Whether or not to allow the creation of new NotificationSummary objects if one does not exist for a message.
+     * Whether to allow creating new {@link NotificationSummary} documents when one does not exist for a recipient.
      *
      * Defaults to true.
      */
     readonly allowCreateNotificationSummaries?: Maybe<boolean>;
+    /**
+     * Server context providing Firestore access, notification collections, and template type info.
+     */
     readonly context: FirebaseServerActionsContext & NotificationFirestoreCollections & FirestoreContextReference & AppNotificationTemplateTypeInfoRecordServiceRef;
 }
 /**
- * Default NotificationSummarySendService implementation
+ * Firestore-backed implementation of {@link NotificationSummarySendService} that persists
+ * notification items to {@link NotificationSummary} documents in Firestore.
  */
 export type FirestoreNotificationSummarySendService = NotificationSummarySendService;
+/**
+ * Creates a {@link NotificationSummarySendService} that writes notification items to Firestore
+ * {@link NotificationSummary} documents.
+ *
+ * Groups messages by their target {@link NotificationSummaryId}, deduplicates against existing items,
+ * appends new items (capped at {@link NOTIFICATION_SUMMARY_ITEM_LIMIT}), and either updates the
+ * existing summary or creates a new one (if `allowCreateNotificationSummaries` is enabled).
+ *
+ * Each summary update runs in a Firestore transaction to prevent concurrent write conflicts.
+ *
+ * @param config - service configuration including Firestore context and collection references
+ *
+ * @example
+ * ```ts
+ * const sendService = firestoreNotificationSummarySendService({
+ *   context: serverActionsContext,
+ *   allowCreateNotificationSummaries: true
+ * });
+ *
+ * const sendInstance = await sendService.buildSendInstanceForNotificationSummaryMessages(messages);
+ * const result = await sendInstance();
+ * ```
+ */
 export declare function firestoreNotificationSummarySendService(config: FirestoreNotificationSummarySendServiceConfig): FirestoreNotificationSummarySendService;

package/model/src/lib/notification/notification.send.service.text.d.ts

@@ -1,9 +1,17 @@
 import { type NotificationTextSendService } from './notification.send.service';
 /**
- * NotificationTextSendService that ignores sending all messages.
+ * Creates a no-op {@link NotificationTextSendService} that marks all messages as ignored
+ * without actually sending any SMS.
  *
- * This is useful for cases where your app may eventually want to send text notifications and want the rest of your app configured like it currently does.
+ * Useful as a placeholder when your app's notification pipeline is fully wired for SMS
+ * but actual delivery is not yet enabled, avoiding the need for conditional logic elsewhere.
  *
- * @returns
+ * @example
+ * ```ts
+ * const textService = ignoreSendNotificationTextSendService();
+ * const sendInstance = await textService.buildSendInstanceForTextNotificationMessages(messages);
+ * const result = await sendInstance();
+ * // result.ignored contains all phone numbers; result.success and result.failed are empty
+ * ```
  */
 export declare function ignoreSendNotificationTextSendService(): NotificationTextSendService;

package/model/src/lib/notification/notification.task.service.d.ts

@@ -7,7 +7,13 @@ export interface NotificationTaskServiceRef {
     readonly notificationTaskService: NotificationTaskService;
 }
 /**
- * Service dedicated to providing access to NotificationMessageFunctionFactory values for specific NotificationTemplateTypes.
+ * Abstract service that dispatches {@link NotificationTask} instances to the appropriate
+ * {@link NotificationTaskServiceTaskHandler} based on the task's type.
+ *
+ * Implementations register handlers for each known {@link NotificationTaskType} and route
+ * incoming tasks during the notification send pipeline's task-processing phase.
+ *
+ * @see {@link notificationTaskService} for the default implementation.
  */
 export declare abstract class NotificationTaskService {
     /**
@@ -19,6 +25,12 @@ export declare abstract class NotificationTaskService {
      */
     abstract taskHandlerForNotificationTaskType(notificationTaskType: NotificationTaskType): Maybe<NotificationTaskServiceTaskHandler>;
 }
+/**
+ * Function that processes a single {@link NotificationTask} and returns a result describing
+ * the completion state, any checkpoint progress, and optional metadata updates.
+ *
+ * @template D - the task's metadata type
+ */
 export type NotificationTaskServiceTaskHandlerFunction<D extends NotificationItemMetadata = {}> = (notificationTask: NotificationTask<D>) => Promise<NotificationTaskServiceHandleNotificationTaskResult<D>>;
 /**
  * Service dedicated to handling NotificationTask values.

package/model/src/lib/notification/notification.task.service.handler.d.ts

@@ -26,17 +26,41 @@ export interface NotificationTaskServiceTaskHandlerConfig<D extends Notification
      */
     readonly allowRunMultipleParts?: boolean;
 }
+/**
+ * Configuration for creating a {@link NotificationTaskService} via {@link notificationTaskService}.
+ */
 export interface NotificationTaskServiceConfig {
     /**
-     * List of NotificationTaskTypes for the app. Used for verifying that all NotificationTaskTypes are handled.
+     * List of expected {@link NotificationTaskType} values, used to verify all types have registered handlers.
      */
     readonly validate?: NotificationTaskType[];
     /**
-     * List of handlers for NotificationTaskTypes.
+     * Handler configurations that define the checkpoint-based flow for each task type.
      */
     readonly handlers: NotificationTaskServiceTaskHandlerConfig<any, any>[];
 }
 /**
- * A basic NotificationTaskService implementation.
+ * Creates a {@link NotificationTaskService} from the provided handler configurations.
+ *
+ * Each handler defines a checkpoint-based flow: when a task is dispatched, the service
+ * finds the next uncompleted checkpoint in the flow and executes its handler function.
+ * If all checkpoints are complete, the task is marked as done.
+ *
+ * @param config - handler configurations and optional validation list
+ *
+ * @example
+ * ```ts
+ * const taskService = notificationTaskService({
+ *   handlers: [
+ *     {
+ *       type: 'process_file',
+ *       flow: [
+ *         { checkpoint: 'validate', fn: validateTask },
+ *         { checkpoint: 'execute', fn: executeTask }
+ *       ]
+ *     }
+ *   ]
+ * });
+ * ```
  */
 export declare function notificationTaskService(config: NotificationTaskServiceConfig): NotificationTaskService;

package/model/src/lib/notification/notification.task.service.util.d.ts

@@ -1,9 +1,21 @@
 import { type NotificationTaskCheckpointString, type NotificationTaskServiceHandleNotificationTaskResult } from '@dereekb/firebase';
 /**
- * Removes the completed checkpoints from the inputCompletions array based on the handleTaskResult.
+ * Removes checkpoints from the completions array based on the task handler result's removal instructions.
  *
- * @param inputCompletions
- * @param handleTaskResult
- * @returns
+ * If `removeAllCompletedCheckpoints` is true, returns an empty array (resets all progress).
+ * If `removeFromCompletedCheckpoints` is set, removes only those specific checkpoints.
+ * Otherwise, returns the original array unchanged.
+ *
+ * @param inputCompletions - the current list of completed checkpoint strings
+ * @param handleTaskResult - the handler result containing removal instructions
+ *
+ * @example
+ * ```ts
+ * const remaining = removeFromCompletionsArrayWithTaskResult(
+ *   ['validate', 'process', 'cleanup'],
+ *   { removeFromCompletedCheckpoints: ['process'] }
+ * );
+ * // remaining === ['validate', 'cleanup']
+ * ```
  */
 export declare function removeFromCompletionsArrayWithTaskResult<S extends NotificationTaskCheckpointString = NotificationTaskCheckpointString>(inputCompletions: S[], handleTaskResult: Pick<NotificationTaskServiceHandleNotificationTaskResult<any, S>, 'removeAllCompletedCheckpoints' | 'removeFromCompletedCheckpoints'>): S[];

package/model/src/lib/notification/notification.task.subtask.handler.d.ts

@@ -205,7 +205,37 @@ export interface NotificationTaskSubtaskNotificationTaskHandlerConfig<I extends
     readonly defaultAllowRunMultipleParts?: Maybe<boolean>;
 }
 /**
- * Creates a NotificationTaskSubtaskNotificationTaskHandlerFactory.
+ * Creates a reusable factory for building {@link NotificationTaskServiceTaskHandlerConfig} entries
+ * that implement the subtask processing pattern.
+ *
+ * The returned factory accepts a {@link NotificationTaskSubtaskNotificationTaskHandlerConfig}
+ * (per-app processors and their flows) and produces a handler config with two built-in checkpoints:
+ *
+ * 1. **Processing** — dispatches to the target-specific processor's subtask flow, advancing through
+ *    subtask checkpoints until all are complete.
+ * 2. **Cleanup** — runs the cleanup function, with retry logic if cleanup fails (up to `maxCleanupRetryAttempts`).
+ *
+ * This is the primary entry point for building complex, multi-step notification task handlers
+ * such as storage file processing or other async workflows.
+ *
+ * @param factoryConfig - shared configuration including the input function, cleanup logic, and task type
+ *
+ * @example
+ * ```ts
+ * const createHandler = notificationTaskSubtaskNotificationTaskHandlerFactory({
+ *   taskType: 'process_upload',
+ *   subtaskHandlerFunctionName: 'processUploadHandler',
+ *   inputFunction: buildInputFromTask,
+ *   defaultCleanup: defaultCleanupFn,
+ *   cleanupFunction: cleanupFn
+ * });
+ *
+ * const handlerConfig = createHandler({
+ *   processors: [
+ *     { target: 'image', flow: [{ subtask: 'resize', fn: resizeImage }] }
+ *   ]
+ * });
+ * ```
  */
 export declare function notificationTaskSubtaskNotificationTaskHandlerFactory<I extends NotificationTaskSubtaskInput<D, M, S>, CUI extends NotificationTaskSubtaskCleanupInstructions, D extends NotificationTaskSubtaskData<M, S>, M extends NotificationTaskSubtaskMetadata = any, S extends NotificationTaskSubtaskCheckpointString = NotificationTaskSubtaskCheckpointString>(factoryConfig: NotificationTaskSubtaskNotificationTaskHandlerFactoryConfig<I, CUI, D, M, S>): NotificationTaskSubtaskNotificationTaskHandlerFactory<I, CUI, D, M, S>;
 /**

package/model/src/lib/notification/notification.util.d.ts

@@ -1,7 +1,25 @@
 import { type Notification, type NotificationBox, type NotificationBoxRecipient, type NotificationBoxRecipientTemplateConfig, NotificationRecipientSendFlag, type NotificationRecipientWithConfig, type FirebaseAuthDetails, type FirebaseAuthUserId, type NotificationSummaryId, type NotificationBoxId, type NotificationUser, type NotificationUserNotificationBoxRecipientConfig, type NotificationUserId, type FirestoreDocumentAccessor, type NotificationUserDocument, type NotificationUserDefaultNotificationBoxRecipientConfig, type NotificationSummaryIdForUidFunction, type NotificationSummary, type DocumentDataWithIdAndKey } from '@dereekb/firebase';
 import { type FirebaseServerAuthService } from '@dereekb/firebase-server';
 import { type E164PhoneNumber, type EmailAddress, type Maybe, type PhoneNumber, type ModelKey } from '@dereekb/util';
+/**
+ * Creates a blank {@link NotificationSummary} template for a newly initialized model.
+ *
+ * Sets the creation timestamp to now, associates the summary with the given model key,
+ * and initializes with an empty notifications array.
+ *
+ * @param model - the model key to associate the summary with
+ *
+ * @example
+ * ```ts
+ * const template = makeNewNotificationSummaryTemplate('projects/abc');
+ * // template.m === 'projects/abc', template.n === []
+ * ```
+ */
 export declare function makeNewNotificationSummaryTemplate(model: ModelKey): NotificationSummary;
+/**
+ * Input for {@link expandNotificationRecipients}, providing the notification, its associated box,
+ * auth service for user lookup, and configuration for recipient filtering.
+ */
 export interface ExpandNotificationRecipientsInput {
     readonly notification: Notification;
     readonly notificationBox?: Maybe<DocumentDataWithIdAndKey<NotificationBox>>;
@@ -37,10 +55,17 @@ export interface ExpandNotificationRecipientsInput {
      */
     readonly onlyTextExplicitlyEnabledRecipients?: Maybe<boolean>;
 }
+/**
+ * A resolved recipient paired with their effective template configuration for a specific notification type.
+ */
 export interface ExpandedNotificationRecipientConfig {
     readonly recipient: Omit<NotificationBoxRecipient, 'i'>;
     readonly effectiveTemplateConfig?: Maybe<NotificationBoxRecipientTemplateConfig>;
 }
+/**
+ * Base shape for an expanded recipient, containing all resolved contact details
+ * and their source (box recipient, other user, or explicit/global recipient).
+ */
 export interface ExpandedNotificationRecipientBase {
     readonly name?: Maybe<string>;
     readonly emailAddress?: Maybe<EmailAddress>;
@@ -58,16 +83,32 @@ export interface ExpandedNotificationRecipientBase {
      */
     readonly otherRecipient?: NotificationRecipientWithConfig;
 }
+/**
+ * An expanded recipient that has a resolved email address for email channel delivery.
+ */
 export interface ExpandedNotificationRecipientEmail extends ExpandedNotificationRecipientBase {
     readonly emailAddress: EmailAddress;
 }
+/**
+ * An expanded recipient that has a resolved E.164 phone number for SMS/text channel delivery.
+ */
 export interface ExpandedNotificationRecipientPhone extends ExpandedNotificationRecipientBase {
     readonly phoneNumber: E164PhoneNumber;
 }
+/**
+ * Alias for text/SMS recipients, identical to phone recipients.
+ */
 export type ExpandedNotificationRecipientText = ExpandedNotificationRecipientPhone;
+/**
+ * An expanded recipient that has a resolved {@link NotificationSummaryId} for in-app notification summary delivery.
+ */
 export interface ExpandedNotificationNotificationSummaryRecipient extends Pick<ExpandedNotificationRecipientBase, 'name' | 'boxRecipient' | 'otherRecipient'> {
     readonly notificationSummaryId: NotificationSummaryId;
 }
+/**
+ * Internal state built during recipient expansion, exposed for debugging and downstream processing.
+ * Contains the user detail map, recipient groupings, opt-out sets, and exclusion tracking.
+ */
 export interface ExpandNotificationRecipientsInternal {
     readonly userDetailsMap: Map<string, FirebaseAuthDetails | undefined>;
     readonly explicitRecipients: NotificationRecipientWithConfig[];
@@ -84,6 +125,10 @@ export interface ExpandNotificationRecipientsInternal {
     readonly nonNotificationBoxUidRecipientConfigs: Map<FirebaseAuthUserId, NotificationRecipientWithConfig>;
     readonly notificationUserRecipientConfigs: Map<NotificationUserId, NotificationUserDefaultNotificationBoxRecipientConfig>;
 }
+/**
+ * Result of {@link expandNotificationRecipients}, containing channel-specific recipient lists
+ * (email, text, notification summary) ready for delivery.
+ */
 export interface ExpandNotificationRecipientsResult {
     readonly _internal: ExpandNotificationRecipientsInternal;
     readonly emails: ExpandedNotificationRecipientEmail[];
@@ -101,6 +146,12 @@ export interface ExpandNotificationRecipientsResult {
  * @returns
  */
 export declare function expandNotificationRecipients(input: ExpandNotificationRecipientsInput): Promise<ExpandNotificationRecipientsResult>;
+/**
+ * Input for {@link updateNotificationUserNotificationBoxRecipientConfig}.
+ *
+ * Describes the current state of a recipient's relationship between a {@link NotificationUser}
+ * and a specific {@link NotificationBox}, plus the intended change (insert, remove, or update).
+ */
 export interface UpdateNotificationUserNotificationBoxRecipientConfigInput {
     readonly notificationBoxId: NotificationBoxId;
     readonly notificationBoxAssociatedModelKey: ModelKey;
@@ -122,6 +173,9 @@ export interface UpdateNotificationUserNotificationBoxRecipientConfigInput {
      */
     readonly notificationBoxRecipient: Maybe<NotificationBoxRecipient>;
 }
+/**
+ * Result of {@link updateNotificationUserNotificationBoxRecipientConfig}.
+ */
 export interface UpdateNotificationUserNotificationBoxRecipientConfigResult {
     /**
      * New configs array, if changes occured.
@@ -132,4 +186,20 @@ export interface UpdateNotificationUserNotificationBoxRecipientConfigResult {
      */
     readonly updatedNotificationBoxRecipient: Maybe<NotificationBoxRecipient>;
 }
+/**
+ * Updates a {@link NotificationUser}'s box-specific recipient configuration (`bc` array)
+ * based on the current state of their relationship with a {@link NotificationBox}.
+ *
+ * Handles three scenarios:
+ * - **Remove**: marks the user's box config entry with `rm=true` and clears the index.
+ * - **Insert**: merges the incoming recipient data with any existing user preferences, respecting
+ *   the user's `bk` (blocked-from-add) and `lk` (locked) flags.
+ * - **Update**: merges changes from the box recipient, respecting `lk` (locked) and `ns` (needs-sync) flags.
+ *
+ * Also re-applies send exclusions to the updated config array.
+ *
+ * @param input - the current state and intended change
+ * @throws notificationUserBlockedFromBeingAddedToRecipientsError when inserting a blocked user
+ * @throws notificationUserLockedConfigFromBeingUpdatedError when updating a locked user's config
+ */
 export declare function updateNotificationUserNotificationBoxRecipientConfig(input: UpdateNotificationUserNotificationBoxRecipientConfigInput): UpdateNotificationUserNotificationBoxRecipientConfigResult;

package/model/src/lib/storagefile/storagefile.action.init.service.d.ts

@@ -4,15 +4,24 @@ import { type Maybe } from '@dereekb/util';
 import { type TransformAndValidateFunctionResult } from '@dereekb/model';
 import { type InjectionToken } from '@nestjs/common';
 /**
- * Token to access/override the StorageFileTemplateService's defaults records.
+ * NestJS injection token for the {@link StorageFileInitServerActionsContextConfig},
+ * which provides the template function used during {@link StorageFileGroup} initialization.
  */
 export declare const STORAGE_FILE_INIT_SERVER_ACTIONS_CONTEXT_CONFIG_TOKEN: InjectionToken;
+/**
+ * Configuration providing the template function that determines how {@link StorageFileGroup}
+ * documents are initialized for a given Firestore model.
+ */
 export interface StorageFileInitServerActionsContextConfig {
     /**
      * MakeTemplateForStorageFileGroupInitializationFunction used by the system for initializing the StorageFileGroups for models.
      */
     readonly makeTemplateForStorageFileGroupInitialization: MakeTemplateForStorageFileGroupInitializationFunction;
 }
+/**
+ * Input passed to the template function during storage file model initialization,
+ * providing the Firestore transaction context and the model identity being initialized.
+ */
 export interface MakeTemplateForStorageFileRelatedModelInitializationFunctionInput {
     readonly transaction: Transaction;
     readonly flatModelKey: TwoWayFlatFirestoreModelKey;
@@ -36,13 +45,35 @@ export type MakeTemplateForStorageFileRelatedModelInitializationFunction<T> = (i
  * Used for initializing a StorageFileGroup.
  */
 export type MakeTemplateForStorageFileGroupInitializationFunction = MakeTemplateForStorageFileRelatedModelInitializationFunction<Pick<StorageFileGroup, 'o'> & StorageFileGroupContentFlagsData>;
+/**
+ * Full context for storage file initialization actions, combining Firebase infrastructure,
+ * storage file Firestore collections, and the initialization template function.
+ */
 export interface StorageFileInitServerActionsContext extends FirebaseServerActionsContext, StorageFileFirestoreCollections, FirestoreContextReference, StorageFileInitServerActionsContextConfig {
 }
+/**
+ * Abstract service defining initialization actions for storage file models.
+ *
+ * Provides methods to initialize individual {@link StorageFileGroup} documents
+ * or batch-process all uninitialized groups.
+ *
+ * @see {@link storageFileInitServerActions} for the concrete implementation factory.
+ */
 export declare abstract class StorageFileInitServerActions {
     abstract initializeStorageFileGroup(params: InitializeStorageFileModelParams): AsyncStorageFileGroupUpdateAction<InitializeStorageFileModelParams>;
     abstract initializeAllApplicableStorageFileGroups(params: InitializeAllApplicableStorageFileGroupsParams): Promise<TransformAndValidateFunctionResult<InitializeAllApplicableStorageFileGroupsParams, () => Promise<InitializeAllApplicableStorageFileGroupsResult>>>;
 }
+/**
+ * Creates a concrete {@link StorageFileInitServerActions} implementation by wiring each
+ * initialization action to its factory function.
+ *
+ * @param context - the initialization context with template function and Firestore access
+ */
 export declare function storageFileInitServerActions(context: StorageFileInitServerActionsContext): StorageFileInitServerActions;
+/**
+ * Input for {@link initializeStorageFileModelInTransaction}, providing the document,
+ * its current data, the template function, and the transaction context.
+ */
 export interface InitializeStorageFileModelInTransactionInput<D extends FirestoreDocument<InitializedStorageFileModel, any>> {
     readonly makeTemplateFunction: MakeTemplateForStorageFileRelatedModelInitializationFunction<FirestoreDocumentData<D>>;
     readonly throwErrorIfAlreadyInitialized?: Maybe<boolean>;
@@ -50,13 +81,43 @@ export interface InitializeStorageFileModelInTransactionInput<D extends Firestor
     readonly document: D;
     readonly data: FirestoreDocumentData<D>;
 }
+/**
+ * Initializes a storage file model document (group) within a Firestore transaction.
+ *
+ * Uses the provided template function to determine the initial state:
+ * - Returns a partial template → applies it and marks as initialized (`s=null`)
+ * - Returns `null`/`undefined` → marks the model as invalid (`fi=true`)
+ * - Returns `false` → deletes the document entirely
+ *
+ * @param input - the document, transaction, template function, and options
+ * @throws storageFileModelAlreadyInitializedError when `throwErrorIfAlreadyInitialized` is true
+ */
 export declare function initializeStorageFileModelInTransaction<D extends FirestoreDocument<InitializedStorageFileModel, any>>(input: InitializeStorageFileModelInTransactionInput<D>): Promise<{
     initialized: boolean;
     alreadyInitialized: boolean;
 }>;
+/**
+ * Factory for initializing a single {@link StorageFileGroup} within a Firestore transaction.
+ *
+ * Applies the app-specific template function, restricting the template to only the `o` (owner)
+ * and content flag properties, and always flags the group for content regeneration.
+ */
 export declare function initializeStorageFileGroupInTransactionFactory(context: StorageFileInitServerActionsContext): (params: InitializeStorageFileModelParams, storageFileGroupDocument: StorageFileGroupDocument, transaction: Transaction) => Promise<{
     initialized: boolean;
     alreadyInitialized: boolean;
 }>;
+/**
+ * Factory for the `initializeStorageFileGroup` action.
+ *
+ * Wraps the in-transaction group initialization in a Firestore transaction
+ * and follows the transform-and-validate pattern.
+ */
 export declare function initializeStorageFileGroupFactory(context: StorageFileInitServerActionsContext): import("@dereekb/model").TransformAndValidateFunctionResultFunction<InitializeStorageFileModelParams, (storageFileGroupDocument: StorageFileGroupDocument) => Promise<StorageFileGroupDocument>, object, unknown>;
+/**
+ * Factory for the `initializeAllApplicableStorageFileGroups` action.
+ *
+ * Batch-processes all {@link StorageFileGroup} documents flagged for initialization,
+ * initializing each in parallel (up to 5 concurrent tasks). Loops until no more
+ * flagged groups are found.
+ */
 export declare function initializeAllApplicableStorageFileGroupsFactory(context: StorageFileInitServerActionsContext): import("@dereekb/model").TransformAndValidateFunctionResultFunction<InitializeAllApplicableStorageFileGroupsParams, () => Promise<InitializeAllApplicableStorageFileGroupsResult>, object, unknown>;