@dereekb/firebase 13.4.0 → 13.4.2

package/src/lib/common/storage/driver/list.d.ts

@@ -1,5 +1,17 @@
 import { type Maybe } from '@dereekb/util';
 import { type StorageListFilesPageToken, type FirebaseStorageAccessorFile, type FirebaseStorageAccessorFolder, type StorageListFilesOptions, type StorageListFilesResult, type StorageListItemResult } from './accessor';
+/**
+ * Input context for {@link StorageListFilesResultFactory} and related delegate methods.
+ *
+ * Bundles the storage instance, target folder, and listing options into a single parameter.
+ *
+ * @template S - the storage instance type (client or server SDK)
+ */
+export interface StorageListFilesResultFactoryInput<S> {
+    readonly storage: S;
+    readonly folder: FirebaseStorageAccessorFolder;
+    readonly options: Maybe<StorageListFilesOptions>;
+}
 /**
  * Delegate that adapts platform-specific list results into the generic {@link StorageListFilesResult} interface.
  *
@@ -13,7 +25,7 @@ export interface StorageListFilesResultFactoryDelegate<S, R> {
     hasItems(result: R): boolean;
     hasNext(result: R): boolean;
     nextPageTokenFromResult(result: R): Maybe<StorageListFilesPageToken>;
-    next(storage: S, options: Maybe<StorageListFilesOptions>, folder: FirebaseStorageAccessorFolder, result: R): Promise<StorageListFilesResult>;
+    next(input: StorageListFilesResultFactoryInput<S>, result: R): Promise<StorageListFilesResult>;
     file(storage: S, fileResult: StorageListItemResult): FirebaseStorageAccessorFile;
     folder(storage: S, folderResult: StorageListItemResult): FirebaseStorageAccessorFolder;
     filesFromResult(result: R, folder: FirebaseStorageAccessorFolder): StorageListItemResult[];
@@ -22,7 +34,7 @@ export interface StorageListFilesResultFactoryDelegate<S, R> {
 /**
  * Factory function that transforms a raw SDK list result into a normalized {@link StorageListFilesResult}.
  */
-export type StorageListFilesResultFactory<S, R> = (storage: S, folder: FirebaseStorageAccessorFolder, options: Maybe<StorageListFilesOptions>, result: R) => StorageListFilesResult;
+export type StorageListFilesResultFactory<S, R> = (input: StorageListFilesResultFactoryInput<S>, result: R) => StorageListFilesResult;
 /**
  * Creates a {@link StorageListFilesResultFactory} from a platform-specific delegate.
  *
@@ -30,16 +42,19 @@ export type StorageListFilesResultFactory<S, R> = (storage: S, folder: FirebaseS
  * provides cursor-based pagination through the `next()` method.
  *
  * @param delegate - platform-specific implementation for extracting results
+ * @returns a {@link StorageListFilesResultFactory} that normalizes raw SDK list results
  *
  * @example
  * ```ts
  * const factory = storageListFilesResultFactory(myDelegate);
- * const result = factory(storage, folder, { maxResults: 50 }, rawSdkResult);
+ * const result = factory({ storage, folder, options: { maxResults: 50 } }, rawSdkResult);
  * const files = result.files();
  * ```
  */
 export declare function storageListFilesResultFactory<S, R>(delegate: StorageListFilesResultFactoryDelegate<S, R>): StorageListFilesResultFactory<S, R>;
 /**
  * Creates an error thrown when `next()` is called on a list result that has no more pages.
+ *
+ * @returns an {@link Error} indicating there are no more pages to fetch
  */
 export declare function storageListFilesResultHasNoNextError(): Error;

package/src/lib/common/storage/storage.d.ts

@@ -41,6 +41,7 @@ export interface StoragePath extends StorageBucketIdRef, StorageSlashPathRef {
  * Useful when you need an independent reference that won't be affected by mutations to the original.
  *
  * @param path - the storage path to copy
+ * @returns a new {@link StoragePath} with the same `bucketId` and `pathString`
  *
  * @example
  * ```ts
@@ -74,6 +75,7 @@ export interface StoragePathFactoryConfig extends StorageBucketIdRef {
  * with a consistent bucket assignment.
  *
  * @param config - bucket and replacement behavior
+ * @returns a {@link StoragePathFactory} that normalizes path inputs with the configured bucket
  *
  * @example
  * ```ts
@@ -112,6 +114,7 @@ export type GoogleCloudStorageFilePath<P extends StorageSlashPath = StorageSlash
  * (implying the default bucket).
  *
  * @param path - the storage path to convert
+ * @returns a {@link GoogleCloudStorageFilePath} string (`gs://bucket/path` or a relative path)
  *
  * @example
  * ```ts
@@ -124,6 +127,7 @@ export declare function firebaseStorageFilePathFromStorageFilePath(path: Storage
  * Returns the `gs://` bucket prefix URI for the given bucket identifier or ref.
  *
  * @param storage - bucket ID string or a {@link StorageBucketIdRef}
+ * @returns the `gs://bucket` prefix URI as a {@link GoogleCloudStorageBucketPrefix}
  *
  * @example
  * ```ts

package/src/lib/common/storage/types.d.ts

@@ -165,16 +165,19 @@ export interface StorageUploadTask<R = unknown> {
     readonly taskRef: R;
     /**
      * Cancels a running task. Has no effect on a complete or failed task.
+     *
      * @returns True if the cancel had an effect.
      */
     cancel(): boolean;
     /**
      * Pauses a currently running task. Has no effect on a paused or failed task.
+     *
      * @returns True if the operation took effect, false if ignored.
      */
     pause(): boolean;
     /**
      * Resumes a paused task. Has no effect on a currently running or failed task.
+     *
      * @returns True if the operation took effect, false if ignored.
      */
     resume(): boolean;

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

@@ -4,21 +4,39 @@
  * Error code constants thrown by the notification server action service.
  * These codes are returned in Firebase function error responses for client-side handling.
  */
-/** Thrown when a notification creation request is missing a required ID. */
+/**
+ * Thrown when a notification creation request is missing a required ID.
+ */
 export declare const CREATE_NOTIFICATION_ID_REQUIRED_ERROR_CODE = "CREATE_NOTIFICATION_ID_REQUIRED";
-/** Thrown when attempting to initialize a NotificationBox or NotificationSummary that is already initialized. */
+/**
+ * Thrown when attempting to initialize a NotificationBox or NotificationSummary that is already initialized.
+ */
 export declare const NOTIFICATION_MODEL_ALREADY_INITIALIZED_ERROR_CODE = "NOTIFICATION_MODEL_ALREADY_INITIALIZED";
-/** Thrown when the target NotificationBox does not exist. */
+/**
+ * Thrown when the target NotificationBox does not exist.
+ */
 export declare const NOTIFICATION_BOX_DOES_NOT_EXIST_ERROR_CODE = "NOTIFICATION_BOX_DOES_NOT_EXIST";
-/** Thrown when attempting to create a NotificationBox for a model that already has one. */
+/**
+ * Thrown when attempting to create a NotificationBox for a model that already has one.
+ */
 export declare const NOTIFICATION_BOX_EXISTS_FOR_MODEL_ERROR_CODE = "NOTIFICATION_BOX_EXISTS_FOR_MODEL";
-/** Thrown when the target recipient does not exist in the NotificationBox. */
+/**
+ * Thrown when the target recipient does not exist in the NotificationBox.
+ */
 export declare const NOTIFICATION_BOX_RECIPIENT_DOES_NOT_EXIST_ERROR_CODE = "NOTIFICATION_BOX_RECIPIENT_DOES_NOT_EXIST";
-/** Thrown when an exclusion target is invalid (e.g., user not associated with the box). */
+/**
+ * Thrown when an exclusion target is invalid (e.g., user not associated with the box).
+ */
 export declare const NOTIFICATION_BOX_EXCLUSION_TARGET_INVALID_ERROR_CODE = "NOTIFICATION_BOX_EXCLUSION_TARGET_INVALID";
-/** Thrown when the UID provided for NotificationUser creation is invalid. */
+/**
+ * Thrown when the UID provided for NotificationUser creation is invalid.
+ */
 export declare const NOTIFICATION_USER_INVALID_UID_FOR_CREATE_ERROR_CODE = "NOTIFICATION_USER_INVALID_UID_FOR_CREATE";
-/** Thrown when attempting to add a user who has blocked themselves from being added as a recipient. */
+/**
+ * Thrown when attempting to add a user who has blocked themselves from being added as a recipient.
+ */
 export declare const NOTIFICATION_USER_BLOCKED_FROM_BEING_ADD_TO_RECIPIENTS_ERROR_CODE = "NOTIFICATION_USER_BLOCKED_FROM_BEING_ADD_TO_RECIPIENTS";
-/** Thrown when attempting to update a recipient config that is locked by the user. */
+/**
+ * Thrown when attempting to update a recipient config that is locked by the user.
+ */
 export declare const NOTIFICATION_USER_LOCKED_CONFIG_FROM_BEING_UPDATED_ERROR_CODE = "NOTIFICATION_USER_LOCKED_CONFIG_FROM_BEING_UPDATED";

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

@@ -16,6 +16,7 @@ import { type NotificationTemplateType } from './notification.id';
  * @param a - existing config record
  * @param b - array of update params to apply
  * @param limitToAllowedConfigTypes - when provided, filters the result to only include these template types
+ * @returns the updated config record, or undefined if no changes were made
  */
 export declare function updateNotificationBoxRecipientTemplateConfigRecord(a: NotificationBoxRecipientTemplateConfigRecord, b: NotificationBoxRecipientTemplateConfigArrayEntryParam[], limitToAllowedConfigTypes?: Maybe<Iterable<NotificationTemplateType>>): Maybe<NotificationBoxRecipientTemplateConfigRecord>;
 /**
@@ -25,6 +26,7 @@ export declare function updateNotificationBoxRecipientTemplateConfigRecord(a: No
  * @param a - existing config
  * @param b - update params to apply
  * @param limitToAllowedConfigTypes - when provided, filters config types to only allowed template types
+ * @returns the updated default recipient config
  */
 export declare function updateNotificationUserDefaultNotificationBoxRecipientConfig(a: NotificationUserDefaultNotificationBoxRecipientConfig, b: UpdateNotificationUserDefaultNotificationBoxRecipientConfigParams, limitToAllowedConfigTypes?: Maybe<Iterable<NotificationTemplateType>>): NotificationUserDefaultNotificationBoxRecipientConfig;
 /**
@@ -32,6 +34,11 @@ export declare function updateNotificationUserDefaultNotificationBoxRecipientCon
  * only if it actually changed. Returns `undefined` if no changes were detected.
  *
  * Automatically sets `ns = true` (needs sync) when changes are detected and the recipient has been indexed.
+ *
+ * @param a - existing per-box recipient config
+ * @param b - update params to apply
+ * @param limitToAllowedConfigTypes - when provided, filters template config types to only allowed types
+ * @returns the updated config if changes were detected, or undefined if no changes occurred
  */
 export declare function updateNotificationUserNotificationBoxRecipientConfigIfChanged(a: NotificationUserNotificationBoxRecipientConfig, b: UpdateNotificationUserNotificationBoxRecipientParams, limitToAllowedConfigTypes?: Maybe<Iterable<NotificationTemplateType>>): Maybe<NotificationUserNotificationBoxRecipientConfig>;
 /**
@@ -42,5 +49,10 @@ export declare function updateNotificationUserNotificationBoxRecipientConfigIfCh
  * through the optional {@link AppNotificationTemplateTypeInfoRecordService}.
  *
  * Returns `undefined` if no changes were made.
+ *
+ * @param a - existing per-box recipient config array
+ * @param b - array of update params to apply to matching boxes
+ * @param filterWithService - optional service used to filter template types to only those valid for each box's model
+ * @returns the updated config array if any changes occurred, or undefined if nothing changed
  */
 export declare function updateNotificationUserNotificationBoxRecipientConfigs(a: NotificationUserNotificationBoxRecipientConfig[], b: UpdateNotificationUserNotificationBoxRecipientParams[], filterWithService?: AppNotificationTemplateTypeInfoRecordService): Maybe<NotificationUserNotificationBoxRecipientConfig[]>;

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

@@ -52,6 +52,10 @@ export interface NotificationBoxRecipientTemplateConfig {
 /**
  * Merges two {@link NotificationBoxRecipientTemplateConfig} objects, preferring values from `a` over `b`.
  *
+ * @param a - primary config whose defined values take precedence
+ * @param b - fallback config supplying values when `a` fields are undefined
+ * @returns the merged template config with values from `a` preferred over `b`
+ *
  * @example
  * ```ts
  * const merged = mergeNotificationBoxRecipientTemplateConfigs(
@@ -67,6 +71,9 @@ export declare function mergeNotificationBoxRecipientTemplateConfigs(a?: Maybe<N
  *
  * This produces the "effective" configuration used at send time, where each channel has a definite boolean.
  *
+ * @param a - the template config to resolve
+ * @returns the effective config with each channel flag filled in using the send-default fallback
+ *
  * @example
  * ```ts
  * const effective = effectiveNotificationBoxRecipientTemplateConfig({ sd: true, se: false });
@@ -113,6 +120,10 @@ export interface NotificationRecipient {
  * Updates a {@link NotificationRecipient} with partial values, preserving existing fields where the update is undefined.
  *
  * Automatically clears the summary ID (`s`) when a `uid` is present.
+ *
+ * @param a - existing recipient to update
+ * @param b - partial values to apply on top of the existing recipient
+ * @returns the updated recipient with merged values
  */
 export declare function updateNotificationRecipient(a: NotificationRecipient, b: Partial<NotificationRecipient>): NotificationRecipient;
 /**
@@ -183,6 +194,7 @@ export interface NotificationBoxRecipient extends NotificationRecipient, IndexRe
  *
  * @param uid - the user's Firebase auth UID
  * @param i - the recipient's index position in the box's recipient array
+ * @returns a new recipient entry with the given uid and index and an empty template config record
  */
 export declare function newNotificationBoxRecipientForUid(uid: FirebaseAuthUserId, i: number): NotificationBoxRecipient;
 /**
@@ -207,6 +219,10 @@ export interface NotificationUserDefaultNotificationBoxRecipientConfig extends O
 }
 /**
  * Merges two {@link NotificationUserDefaultNotificationBoxRecipientConfig} objects, preferring defined values from `a` over `b`.
+ *
+ * @param a - primary config whose defined values take precedence
+ * @param b - fallback config supplying values when `a` fields are undefined
+ * @returns the merged config
  */
 export declare function mergeNotificationUserDefaultNotificationBoxRecipientConfig(a: NotificationUserDefaultNotificationBoxRecipientConfig, b: NotificationUserDefaultNotificationBoxRecipientConfig): NotificationUserDefaultNotificationBoxRecipientConfig;
 /**
@@ -279,6 +295,10 @@ export type EncodedNotificationBoxRecipientTemplateConfig = BitwiseEncodedSet;
 export type NotificationBoxRecipientTemplateConfigRecord = Record<NotificationTemplateType, NotificationBoxRecipientTemplateConfig>;
 /**
  * Merges two {@link NotificationBoxRecipientTemplateConfigRecord} objects, preferring defined values from `a`.
+ *
+ * @param a - primary record whose defined values take precedence
+ * @param b - fallback record supplying values when `a` entries are undefined
+ * @returns the merged template config record
  */
 export declare function mergeNotificationBoxRecipientTemplateConfigRecords(a: NotificationBoxRecipientTemplateConfigRecord, b: NotificationBoxRecipientTemplateConfigRecord): NotificationBoxRecipientTemplateConfigRecord;
 /**
@@ -289,6 +309,8 @@ export type EncodedNotificationBoxRecipientTemplateConfigRecord = Record<Notific
 /**
  * Creates a Firestore field converter for {@link NotificationBoxRecipientTemplateConfigRecord},
  * using bitwise encoding for compact storage.
+ *
+ * @returns a Firestore field converter that encodes and decodes template config records using bitwise encoding
  */
 export declare function firestoreNotificationBoxRecipientTemplateConfigRecord(): import("../..").FirestoreModelFieldMapFunctionsConfig<import("../..").FirestoreEncodedObjectMapFieldValueType<NotificationBoxRecipientTemplateConfig, string>, import("../..").FirestoreMapFieldType<number, string>>;
 /**
@@ -321,6 +343,9 @@ export type NotificationBoxRecipientTemplateConfigArray = NotificationBoxRecipie
 /**
  * Converts a {@link NotificationBoxRecipientTemplateConfigRecord} to an array of entries with their type keys.
  *
+ * @param input - the template config record to convert
+ * @returns an array of entries each containing a type key and the corresponding channel config
+ *
  * @example
  * ```ts
  * const array = notificationBoxRecipientTemplateConfigRecordToArray({ 'comment': { se: true } });
@@ -330,6 +355,9 @@ export type NotificationBoxRecipientTemplateConfigArray = NotificationBoxRecipie
 export declare function notificationBoxRecipientTemplateConfigRecordToArray(input: NotificationBoxRecipientTemplateConfigRecord): NotificationBoxRecipientTemplateConfigArray;
 /**
  * Converts a {@link NotificationBoxRecipientTemplateConfigArray} back to a {@link NotificationBoxRecipientTemplateConfigRecord}.
+ *
+ * @param input - the array of typed config entries to convert
+ * @returns a record keyed by template type
  */
 export declare function notificationBoxRecipientTemplateConfigArrayToRecord(input: NotificationBoxRecipientTemplateConfigArray): NotificationBoxRecipientTemplateConfigRecord;
 /**

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

@@ -123,6 +123,9 @@ export interface CreateNotificationTemplateInput extends Partial<Omit<CreateNoti
  *
  * Maps friendly field names (`subject`, `message`, `createdBy`, etc.) to their Firestore abbreviations
  * and filters out null/undefined metadata values.
+ *
+ * @param input - friendly input with readable field names
+ * @returns the low-level template using Firestore field abbreviations
  */
 export declare function createNotificationTemplate(input: CreateNotificationTemplateInput): CreateNotificationTemplate;
 /**
@@ -149,6 +152,9 @@ export interface ShouldSendCreatedNotificationInput {
  * Determines whether a notification should be created based on the explicit toggle and throttle settings.
  *
  * Returns false if `sendNotification` is explicitly false, or if the throttle window hasn't elapsed.
+ *
+ * @param input - the send control parameters including the toggle and throttle configuration
+ * @returns true if the notification should be created and sent
  */
 export declare function shouldSendCreatedNotificationInput(input: ShouldSendCreatedNotificationInput): boolean;
 /**
@@ -187,7 +193,13 @@ export interface CreateNotificationDocumentPairInput extends ShouldSendCreatedNo
  * Result of creating a notification document pair (document reference + data), before or after saving.
  */
 export interface CreateNotificationDocumentPairResult extends Pick<CreateNotificationTemplate, 'overrideExistingTask'> {
+    /**
+     * The notification document.
+     */
     readonly notificationDocument: NotificationDocument;
+    /**
+     * The notification data.
+     */
     readonly notification: Notification;
     /**
      * Whether or not the notification was created.
@@ -205,12 +217,18 @@ export interface CreateNotificationDocumentPairResult extends Pick<CreateNotific
  *
  * For unique task notifications, generates a deterministic document ID from the target model and task type.
  *
+ * @param input - the creation parameters including template, context, and accessor
+ * @returns the document reference and notification data pair, with `notificationCreated` set to false
  * @throws {Error} When neither an accessor nor sufficient context is provided
  * @throws {Error} When `unique=true` but no target model is specified
  */
 export declare function createNotificationDocumentPair(input: CreateNotificationDocumentPairInput): CreateNotificationDocumentPairResult;
 /**
  * Internal function used by createNotificationDocument().
+ *
+ * @param input - send control parameters (throttle settings, shouldCreateNotification flag)
+ * @param pair - the document pair created by {@link createNotificationDocumentPair}
+ * @returns the pair with `notificationCreated` updated to reflect whether the document was saved
  */
 export declare function _createNotificationDocumentFromPair(input: Pick<CreateNotificationDocumentPairInput, 'shouldCreateNotification' | keyof ShouldSendCreatedNotificationInput>, pair: CreateNotificationDocumentPairResult): Promise<CreateNotificationDocumentPairResult>;
 /**
@@ -218,11 +236,17 @@ export declare function _createNotificationDocumentFromPair(input: Pick<CreateNo
  *
  * For unique tasks with `overrideExistingTask`, uses `set()` to replace existing documents.
  * Otherwise uses `create()` which fails if the document already exists.
+ *
+ * @param input - the creation parameters including template, context, send control settings
+ * @returns the document pair with `notificationCreated` reflecting whether the document was saved
  */
 export declare function createNotificationDocument(input: CreateNotificationDocumentPairInput): Promise<CreateNotificationDocumentPairResult>;
 /**
  * Creates and saves a notification only if sending conditions are met (not throttled, not explicitly disabled).
  *
  * Returns `undefined` if the notification was not created.
+ *
+ * @param input - the creation parameters including template, context, and send control settings
+ * @returns the document pair if the notification was created, or undefined if it was skipped
  */
 export declare function createNotificationDocumentIfSending(input: CreateNotificationDocumentPairInput): Promise<Maybe<CreateNotificationDocumentPairResult>>;

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

@@ -28,6 +28,8 @@ export interface CreateNotificationTaskTemplateInput extends Omit<CreateNotifica
 /**
  * Creates a {@link CreateNotificationTaskTemplate} with `TASK_NOTIFICATION` send type and no recipients.
  *
+ * @param input - task template input parameters
+ * @returns the configured task notification template
  * @throws {Error} When `unique=true` but no `notificationModel` or target model is specified.
  *
  * @example

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

@@ -128,6 +128,9 @@ export declare class NotificationUserDocument extends AbstractFirestoreDocument<
 export declare const notificationUserConverter: import("../..").SnapshotConverterFunctions<NotificationUser, Partial<import("@dereekb/util").ReplaceType<NotificationUser, import("@dereekb/util").MaybeMap<object>, any>>>;
 /**
  * Creates a Firestore collection reference for {@link NotificationUser} documents.
+ *
+ * @param context - Firestore context to create the collection reference from
+ * @returns a typed collection reference for NotificationUser documents
  */
 export declare function notificationUserCollectionReference(context: FirestoreContext): CollectionReference<NotificationUser>;
 /**
@@ -136,6 +139,9 @@ export declare function notificationUserCollectionReference(context: FirestoreCo
 export type NotificationUserFirestoreCollection = FirestoreCollection<NotificationUser, NotificationUserDocument>;
 /**
  * Creates a typed {@link NotificationUserFirestoreCollection} bound to the given Firestore context.
+ *
+ * @param firestoreContext - Firestore context to bind the collection to
+ * @returns a typed Firestore collection for NotificationUser documents
  */
 export declare function notificationUserFirestoreCollection(firestoreContext: FirestoreContext): NotificationUserFirestoreCollection;
 /**
@@ -206,6 +212,9 @@ export declare class NotificationSummaryDocument extends AbstractFirestoreDocume
 export declare const notificationSummaryConverter: import("../..").SnapshotConverterFunctions<NotificationSummary, Partial<import("@dereekb/util").ReplaceType<NotificationSummary, import("@dereekb/util").MaybeMap<object>, any>>>;
 /**
  * Creates a Firestore collection reference for {@link NotificationSummary} documents.
+ *
+ * @param context - Firestore context to create the collection reference from
+ * @returns a typed collection reference for NotificationSummary documents
  */
 export declare function notificationSummaryCollectionReference(context: FirestoreContext): CollectionReference<NotificationSummary>;
 /**
@@ -214,6 +223,9 @@ export declare function notificationSummaryCollectionReference(context: Firestor
 export type NotificationSummaryFirestoreCollection = FirestoreCollection<NotificationSummary, NotificationSummaryDocument>;
 /**
  * Creates a typed {@link NotificationSummaryFirestoreCollection} bound to the given Firestore context.
+ *
+ * @param firestoreContext - Firestore context to bind the collection to
+ * @returns a typed Firestore collection for NotificationSummary documents
  */
 export declare function notificationSummaryFirestoreCollection(firestoreContext: FirestoreContext): NotificationSummaryFirestoreCollection;
 /**
@@ -287,6 +299,9 @@ export declare class NotificationBoxDocument extends AbstractFirestoreDocument<N
 export declare const notificationBoxConverter: import("../..").SnapshotConverterFunctions<NotificationBox, Partial<import("@dereekb/util").ReplaceType<NotificationBox, import("@dereekb/util").MaybeMap<object>, any>>>;
 /**
  * Creates a Firestore collection reference for {@link NotificationBox} documents.
+ *
+ * @param context - Firestore context to create the collection reference from
+ * @returns a typed collection reference for NotificationBox documents
  */
 export declare function notificationBoxCollectionReference(context: FirestoreContext): CollectionReference<NotificationBox>;
 /**
@@ -295,6 +310,9 @@ export declare function notificationBoxCollectionReference(context: FirestoreCon
 export type NotificationBoxFirestoreCollection = FirestoreCollection<NotificationBox, NotificationBoxDocument>;
 /**
  * Creates a typed {@link NotificationBoxFirestoreCollection} bound to the given Firestore context.
+ *
+ * @param firestoreContext - Firestore context to bind the collection to
+ * @returns a typed Firestore collection for NotificationBox documents
  */
 export declare function notificationBoxFirestoreCollection(firestoreContext: FirestoreContext): NotificationBoxFirestoreCollection;
 /**
@@ -544,6 +562,9 @@ export declare class NotificationDocument extends AbstractFirestoreDocumentWithP
 export declare const notificationConverter: import("../..").SnapshotConverterFunctions<Notification, Partial<import("@dereekb/util").ReplaceType<Notification, import("@dereekb/util").MaybeMap<object>, any>>>;
 /**
  * Creates a factory that produces {@link Notification} subcollection references for a given {@link NotificationBoxDocument} parent.
+ *
+ * @param context - Firestore context to create subcollection references from
+ * @returns a factory function that creates collection references for a given NotificationBox parent
  */
 export declare function notificationCollectionReferenceFactory(context: FirestoreContext): (notificationBox: NotificationBoxDocument) => CollectionReference<Notification>;
 /**
@@ -556,10 +577,16 @@ export type NotificationFirestoreCollection = FirestoreCollectionWithParent<Noti
 export type NotificationFirestoreCollectionFactory = (parent: NotificationBoxDocument) => NotificationFirestoreCollection;
 /**
  * Creates a {@link NotificationFirestoreCollectionFactory} bound to the given Firestore context.
+ *
+ * @param firestoreContext - Firestore context to bind the collection factory to
+ * @returns a factory that creates typed Firestore subcollections for Notification documents
  */
 export declare function notificationFirestoreCollectionFactory(firestoreContext: FirestoreContext): NotificationFirestoreCollectionFactory;
 /**
  * Creates a collection group reference for querying all {@link Notification} documents across all {@link NotificationBox} parents.
+ *
+ * @param context - Firestore context to create the collection group reference from
+ * @returns a typed collection group for querying Notification documents across all parents
  */
 export declare function notificationCollectionReference(context: FirestoreContext): CollectionGroup<Notification>;
 /**
@@ -568,6 +595,9 @@ export declare function notificationCollectionReference(context: FirestoreContex
 export type NotificationFirestoreCollectionGroup = FirestoreCollectionGroup<Notification, NotificationDocument>;
 /**
  * Creates a typed {@link NotificationFirestoreCollectionGroup} bound to the given Firestore context.
+ *
+ * @param firestoreContext - Firestore context to bind the collection group to
+ * @returns a typed Firestore collection group for querying Notification documents across all parents
  */
 export declare function notificationFirestoreCollectionGroup(firestoreContext: FirestoreContext): NotificationFirestoreCollectionGroup;
 /**
@@ -606,6 +636,9 @@ export declare class NotificationWeekDocument extends AbstractFirestoreDocumentW
 export declare const notificationWeekConverter: import("../..").SnapshotConverterFunctions<NotificationWeek, Partial<import("@dereekb/util").ReplaceType<NotificationWeek, import("@dereekb/util").MaybeMap<object>, any>>>;
 /**
  * Creates a factory that produces {@link NotificationWeek} subcollection references for a given {@link NotificationBoxDocument} parent.
+ *
+ * @param context - Firestore context to create subcollection references from
+ * @returns a factory function that creates collection references for a given NotificationBox parent
  */
 export declare function notificationWeekCollectionReferenceFactory(context: FirestoreContext): (notificationBox: NotificationBoxDocument) => CollectionReference<NotificationWeek>;
 /**
@@ -618,10 +651,16 @@ export type NotificationWeekFirestoreCollection = FirestoreCollectionWithParent<
 export type NotificationWeekFirestoreCollectionFactory = (parent: NotificationBoxDocument) => NotificationWeekFirestoreCollection;
 /**
  * Creates a {@link NotificationWeekFirestoreCollectionFactory} bound to the given Firestore context.
+ *
+ * @param firestoreContext - Firestore context to bind the collection factory to
+ * @returns a factory that creates typed Firestore subcollections for NotificationWeek documents
  */
 export declare function notificationWeekFirestoreCollectionFactory(firestoreContext: FirestoreContext): NotificationWeekFirestoreCollectionFactory;
 /**
  * Creates a collection group reference for querying all {@link NotificationWeek} documents across all {@link NotificationBox} parents.
+ *
+ * @param context - Firestore context to create the collection group reference from
+ * @returns a typed collection group for querying NotificationWeek documents across all parents
  */
 export declare function notificationWeekCollectionReference(context: FirestoreContext): CollectionGroup<NotificationWeek>;
 /**
@@ -630,5 +669,8 @@ export declare function notificationWeekCollectionReference(context: FirestoreCo
 export type NotificationWeekFirestoreCollectionGroup = FirestoreCollectionGroup<NotificationWeek, NotificationWeekDocument>;
 /**
  * Creates a typed {@link NotificationWeekFirestoreCollectionGroup} bound to the given Firestore context.
+ *
+ * @param firestoreContext - Firestore context to bind the collection group to
+ * @returns a typed Firestore collection group for querying NotificationWeek documents across all parents
  */
 export declare function notificationWeekFirestoreCollectionGroup(firestoreContext: FirestoreContext): NotificationWeekFirestoreCollectionGroup;

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

@@ -99,6 +99,8 @@ export type NotificationTemplateTypeInfoRecord = Record<NotificationTemplateType
 /**
  * Creates a {@link NotificationTemplateTypeInfoRecord} from an array of template type info entries.
  *
+ * @param infoArray - array of template type info entries to index
+ * @returns a record keyed by template type
  * @throws {Error} When duplicate template types are found in the input array.
  *
  * @example
@@ -186,6 +188,7 @@ export declare abstract class AppNotificationTemplateTypeInfoRecordService {
  * Handles alternative model identities defined in {@link NotificationTemplateTypeInfoIdentityInfoAlternativeModelIdentityPair}.
  *
  * @param appNotificationTemplateTypeInfoRecord - the complete template type registry for the application
+ * @returns a fully initialized service with indexed lookups for fast template type discovery
  *
  * @example
  * ```ts

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

@@ -98,6 +98,7 @@ export type NotificationSummaryIdForUidFunction = FactoryWithRequiredInput<Notif
  * by combining the given user model identity with the provided UID.
  *
  * @param userModelIdentity - the root identity for user models (e.g., `profileIdentity`)
+ * @returns a function that generates a {@link NotificationSummaryId} for a given user UID
  *
  * @example
  * ```ts
@@ -176,8 +177,8 @@ export interface NotificationTaskKeyRef {
 /**
  * Creates a NotificationTaskUniqueId from the input model id and task type.
  *
- * @param input model id input
- * @param taskType task type
- * @returns NotificationTaskUniqueId
+ * @param input - model id input
+ * @param taskType - task type
+ * @returns the unique notification task id combining the model id and task type
  */
 export declare function notificationTaskUniqueId(input: FirestoreModelIdInput, taskType: NotificationTaskType): NotificationTaskUniqueId;

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

@@ -99,6 +99,7 @@ export interface UnreadNotificationItemsResult<D extends NotificationItemMetadat
  *
  * @param items - notification items to classify
  * @param considerReadIfCreatedBefore - optional cutoff date; items created at or before this date are treated as read
+ * @returns an object containing both the read and unread item arrays along with the input cutoff date
  *
  * @example
  * ```ts
@@ -110,4 +111,4 @@ export declare function unreadNotificationItems<D extends NotificationItemMetada
 /**
  * Sort comparator for {@link NotificationItem} arrays. Sorts ascending by creation date (`cat`).
  */
-export declare const sortNotificationItemsFunction: import("@dereekb/date").SortByDateFunction<NotificationItem<any>>;
+export declare const sortNotificationItemsFunction: import("@dereekb/date").SortByDateFunction<NotificationItem<{}>>;

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

@@ -38,13 +38,13 @@ export type NotificationSendMessageTemplateName = string;
  *
  * This info is used by the sending service to configure the template, but is not passed directly to the template itself.
  */
-export type NotificationMessageTemplateConfiguration = Record<string, any>;
+export type NotificationMessageTemplateConfiguration = Record<string, unknown>;
 /**
  * Template variables for a notification message.
  *
  * These variables may be directly passed to the template.
  */
-export type NotificationMessageTemplateVariables = Record<string, any>;
+export type NotificationMessageTemplateVariables = Record<string, unknown>;
 /**
  * Generic notification message content.
  */
@@ -258,6 +258,7 @@ export type NotificationMessageFunction = NotificationMessageFunctionWithoutExtr
  *
  * @param fn - base function that generates message content per recipient
  * @param extras - optional delivery customization (global recipients, send callbacks)
+ * @returns a {@link NotificationMessageFunction} with the extras attached
  *
  * @example
  * ```ts
@@ -276,6 +277,8 @@ export declare function notificationMessageFunction(fn: NotificationMessageFunct
  *
  * Useful as a placeholder factory for template types that should not produce deliverable content.
  *
+ * @returns a factory that produces no-content message functions
+ *
  * @example
  * ```ts
  * const factory = noContentNotificationMessageFunctionFactory();
@@ -284,4 +287,4 @@ export declare function notificationMessageFunction(fn: NotificationMessageFunct
  * // msg.flag === NotificationMessageFlag.NO_CONTENT
  * ```
  */
-export declare function noContentNotificationMessageFunctionFactory<D extends NotificationItemMetadata = any>(): NotificationMessageFunctionFactory<D>;
+export declare function noContentNotificationMessageFunctionFactory<D extends NotificationItemMetadata = {}>(): NotificationMessageFunctionFactory<D>;

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

@@ -11,26 +11,35 @@ import { type ArrayOrValue } from '@dereekb/util';
  * Query constraints for finding {@link NotificationUser} documents that have pending config syncs (`ns == true`).
  *
  * Used by the server to discover users whose configs need to be synced to their NotificationBox recipients.
+ *
+ * @returns array of Firestore query constraints filtering for users needing sync
  */
 export declare function notificationUsersFlaggedForNeedsSyncQuery(): FirestoreQueryConstraint[];
 /**
  * Query constraints for finding {@link NotificationUser} documents that have any of the given exclusion IDs in their `x` array.
  *
  * @param exclusionId - one or more box IDs or collection name prefixes to match against
+ * @returns array of Firestore query constraints filtering for users with matching exclusions
  */
 export declare function notificationUserHasExclusionQuery(exclusionId: ArrayOrValue<NotificationBoxSendExclusion>): FirestoreQueryConstraint[];
 /**
  * Query constraints for finding {@link NotificationSummary} documents that need server-side initialization (`s == true`).
+ *
+ * @returns array of Firestore query constraints filtering for summaries needing initialization
  */
 export declare function notificationSummariesFlaggedForNeedsInitializationQuery(): FirestoreQueryConstraint[];
 /**
  * Query constraints for finding {@link NotificationBox} documents that need server-side initialization (`s == true`).
+ *
+ * @returns array of Firestore query constraints filtering for boxes needing initialization
  */
 export declare function notificationBoxesFlaggedForNeedsInitializationQuery(): FirestoreQueryConstraint[];
 /**
  * Query constraints for finding {@link NotificationBox} documents flagged as invalid (`fi == true`).
  *
  * Used by the server to clean up boxes that could not be initialized.
+ *
+ * @returns array of Firestore query constraints filtering for boxes flagged as invalid
  */
 export declare function notificationBoxesFlaggedInvalidQuery(): FirestoreQueryConstraint[];
 /**
@@ -40,10 +49,13 @@ export declare function notificationBoxesFlaggedInvalidQuery(): FirestoreQueryCo
  * This is the primary query used by the send queue processor.
  *
  * @param now - reference time for the `sat` comparison (defaults to current time)
+ * @returns array of Firestore query constraints filtering for notifications past their scheduled send time
  */
 export declare function notificationsPastSendAtTimeQuery(now?: Date): FirestoreQueryConstraint[];
 /**
  * Query constraints for finding {@link Notification} documents marked as done (`d == true`)
  * and ready to be archived to {@link NotificationWeek} and then deleted.
+ *
+ * @returns array of Firestore query constraints filtering for completed notifications ready to archive
  */
 export declare function notificationsReadyForCleanupQuery(): FirestoreQueryConstraint[];