@dereekb/firebase 13.11.2 → 13.11.3

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

@@ -0,0 +1,82 @@
+import { type Maybe } from '@dereekb/util';
+import { type Transaction, type FirestoreDocumentSnapshotDataPair } from '../../common';
+import { type NotificationBoxDocument, type NotificationFirestoreCollections, type NotificationLoggedEventDayDocument } from './notification';
+import { type NotificationLoggedEventDayId, type NotificationTaskType, type NotificationTemplateType } from './notification.id';
+import { type NotificationItem } from './notification.item';
+/**
+ * Configuration for {@link notificationLoggedEventLoader}.
+ */
+export interface NotificationLoggedEventLoaderConfig {
+    readonly notificationFirestoreCollections: NotificationFirestoreCollections;
+    readonly notificationBox: NotificationBoxDocument;
+    readonly transaction?: Maybe<Transaction>;
+}
+/**
+ * Input for {@link NotificationLoggedEventLoader.getItemsForDayRange}.
+ */
+export interface NotificationLoggedEventLoaderItemsForDayRangeInput {
+    readonly from: Date;
+    readonly to: Date;
+    readonly type?: Maybe<NotificationTemplateType | NotificationTaskType>;
+}
+/**
+ * Per-day result yielded by {@link NotificationLoggedEventLoader.forEachDayInRange}.
+ */
+export interface NotificationLoggedEventLoaderDayResult {
+    readonly dayId: NotificationLoggedEventDayId;
+    readonly items: NotificationItem[];
+}
+/**
+ * Input for {@link NotificationLoggedEventLoader.forEachDayInRange}.
+ */
+export interface NotificationLoggedEventLoaderForEachDayInRangeInput {
+    readonly from: Date;
+    readonly to: Date;
+    readonly type?: Maybe<NotificationTemplateType | NotificationTaskType>;
+    readonly maxParallelTasks?: Maybe<number>;
+    readonly handler: (input: NotificationLoggedEventLoaderDayResult) => Promise<void> | void;
+}
+/**
+ * Cached, range-aware reader for the {@link NotificationLoggedEventDay} archive of a single
+ * {@link NotificationBoxDocument}. Mirrors the pattern of `regionalHeirarchyForRegionalObjectModelKeyLoader`
+ * — request-scoped, deduplicates reads via promise caching, and exposes both per-day and
+ * date-range methods.
+ */
+export interface NotificationLoggedEventLoader {
+    readonly notificationBox: NotificationBoxDocument;
+    /**
+     * Loads (and caches) the {@link NotificationLoggedEventDay} wrapper document for the given day.
+     */
+    getDay(dayId: NotificationLoggedEventDayId): Promise<FirestoreDocumentSnapshotDataPair<NotificationLoggedEventDayDocument>>;
+    /**
+     * Loads (and caches) every archived {@link NotificationItem} for the given day.
+     */
+    getItemsForDay(dayId: NotificationLoggedEventDayId): Promise<NotificationItem[]>;
+    /**
+     * Loads items for the given day, filtered to those whose `t` matches the given type.
+     * Reuses the underlying day cache; no extra Firestore reads.
+     */
+    getItemsForDayWithType(dayId: NotificationLoggedEventDayId, type: NotificationTemplateType | NotificationTaskType): Promise<NotificationItem[]>;
+    /**
+     * Loads items across all days in `[from, to]` (inclusive), optionally filtered by type.
+     * Days with no archive contribute zero items.
+     */
+    getItemsForDayRange(input: NotificationLoggedEventLoaderItemsForDayRangeInput): Promise<NotificationItem[]>;
+    /**
+     * Streams items per-day across `[from, to]` (inclusive). Each day is loaded via the same cache
+     * as the per-day getters and passed to `handler` exactly once. Concurrency is bounded by
+     * `maxParallelTasks` (defaults to unbounded — same as {@link performTasksFromFactoryInParallelFunction}).
+     */
+    forEachDayInRange(input: NotificationLoggedEventLoaderForEachDayInRangeInput): Promise<void>;
+}
+/**
+ * Creates a request-scoped {@link NotificationLoggedEventLoader} that caches both day wrapper
+ * snapshots (via {@link limitedFirestoreDocumentAccessorSnapshotCache}) and the per-day merged
+ * `NotificationItem[]` from the paged subcollection.
+ *
+ * Cache lifetime is the loader instance — create one per request/transaction; do not retain.
+ *
+ * @param config - notification collections, the parent {@link NotificationBoxDocument}, optional transaction.
+ * @returns the cached loader.
+ */
+export declare function notificationLoggedEventLoader(config: NotificationLoggedEventLoaderConfig): NotificationLoggedEventLoader;

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

@@ -280,6 +280,7 @@ export type NotificationMessageFunction = NotificationMessageFunctionWithoutExtr
  *   { globalRecipients: [adminRecipient] }
  * );
  * ```
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function notificationMessageFunction(fn: NotificationMessageFunctionWithoutExtras, extras?: NotificationMessageFunctionExtras): NotificationMessageFunction;
 /**
@@ -296,5 +297,6 @@ export declare function notificationMessageFunction(fn: NotificationMessageFunct
  * const msg = await msgFn(inputContext);
  * // msg.flag === NotificationMessageFlag.NO_CONTENT
  * ```
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function noContentNotificationMessageFunctionFactory<D extends NotificationItemMetadata = {}>(): NotificationMessageFunctionFactory<D>;

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

@@ -59,3 +59,20 @@ export declare function notificationsPastSendAtTimeQuery(now?: Date): FirestoreQ
  * @returns array of Firestore query constraints filtering for completed notifications ready to archive
  */
 export declare function notificationsReadyForCleanupQuery(): FirestoreQueryConstraint[];
+/**
+ * Query constraints for finding {@link NotificationLoggedEventDay} documents whose ISO day string
+ * is older than `now - retentionDays`.
+ *
+ * Intended for use against the {@link NotificationLoggedEventDayFirestoreCollectionGroup} during
+ * scheduled retention cleanup. Documents older than the cutoff (and their nested page subcollection
+ * contents) should be deleted.
+ *
+ * Uses the `d` field rather than document ID — Firestore collection-group queries cannot filter on
+ * `FieldPath.documentId()` with a bare day string (it requires a full path). The `d` field stores
+ * the same ISO 8601 day string as the document ID and supports a plain inequality.
+ *
+ * @param retentionDays - number of days of history to retain; days strictly older than `now - retentionDays` match
+ * @param now - reference time for the cutoff (defaults to current time)
+ * @returns array of Firestore query constraints filtering by the day string
+ */
+export declare function notificationLoggedEventDaysOlderThanQuery(retentionDays: number, now?: Date): FirestoreQueryConstraint[];

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

@@ -126,11 +126,22 @@ export interface AllowedNotificationRecipients {
  * @returns an object indicating which recipient groups are permitted for this notification
  */
 export declare function allowedNotificationRecipients(flag?: Maybe<NotificationRecipientSendFlag>): AllowedNotificationRecipients;
+/**
+ * Returns true if the given notification is a logged-event record (`st === LOGGED_EVENT`).
+ *
+ * Logged-event notifications bypass the normal send pipeline entirely and are archived to the
+ * day-keyed {@link NotificationLoggedEventDay} collection during cleanup.
+ *
+ * @param notification - the notification to check
+ * @returns true if the notification has the LOGGED_EVENT send type
+ */
+export declare function isLoggedEventNotification(notification: Pick<Notification, 'st'>): boolean;
 /**
  * Returns true if the notification should be archived to a {@link NotificationWeek} after delivery.
  *
  * Only notifications that can be sent to box recipients are archived (notifications restricted
- * to only explicit or only global recipients are not saved to the weekly archive).
+ * to only explicit or only global recipients are not saved to the weekly archive). Logged-event
+ * notifications are archived to {@link NotificationLoggedEventDay} instead and never to the weekly archive.
  *
  * @param notification - the notification to check
  * @returns true if the notification should be saved to the weekly archive after delivery

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

@@ -188,6 +188,7 @@ export type CreateStorageFileDocumentPairFactory = <M extends StorageFileMetadat
  *   context: collections
  * });
  * ```
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function createStorageFileDocumentPairFactory(config?: CreateStorageFileDocumentPairFactoryConfig): CreateStorageFileDocumentPairFactory;
 /**

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

@@ -82,6 +82,7 @@ export type StorageFileGroupCreateStorageFileKeyFactory<P extends StorageFileGro
  *
  * @param purpose The purpose of the StorageFileGroupCreatedStorageFileKey.
  * @returns A factory function that takes a StorageFileGroupId and returns a StorageFileGroupCreatedStorageFileKey.
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function storageFileGroupCreateStorageFileKeyFactory<P extends StorageFileGroupRelatedStorageFilePurpose>(purpose: P): StorageFileGroupCreateStorageFileKeyFactory<P>;
 /**

package/src/lib/model/storagefile/storagefile.file.d.ts

@@ -68,5 +68,6 @@ export interface StoredFileReader {
  * const reader = factory(storageAccessorFile);
  * const bytes = await reader.loadFileBytes();
  * ```
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function storedFileReaderFactory(): StoredFileReaderFactory;

package/src/lib/model/storagefile/storagefile.permission.d.ts

@@ -44,5 +44,6 @@ export type GrantStorageFileRolesForUserAuthFunction = (input: GrantStorageFileR
  *   rolesForStorageFileOwnershipKey: (key) => ({ read: true })
  * });
  * ```
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function grantStorageFileRolesForUserAuthFunction<T extends FirebaseModelContext>(config: GrantStorageFileRolesForUserAuthFunctionConfig<T>): GrantStorageFileRolesForUserAuthFunction;

package/src/lib/model/storagefile/storagefile.upload.d.ts

@@ -36,6 +36,7 @@ export type UserUploadsFolderSlashPathFactory = FactoryWithRequiredInput<SlashPa
  * const path = factory('user123');
  * // path === '/uploads/u/user123'
  * ```
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function userUploadsFolderSlashPathFactory(inputBasePath?: Maybe<string>): UserUploadsFolderSlashPathFactory;
 /**
@@ -63,6 +64,7 @@ export interface UserUploadsFolderStoragePathFactoryConfig {
  * const storagePath = factory('user123');
  * // storagePath === { pathString: '/uploads/u/user123', bucketId: 'my-bucket' }
  * ```
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function userUploadsFolderStoragePathFactory({ bucketId, basePath: inputBasePath }: UserUploadsFolderStoragePathFactoryConfig): UserUploadsFolderStoragePathFactory;
 /**

package/src/lib/model/storagefile/storagefile.upload.determiner.d.ts

@@ -276,6 +276,7 @@ export type DetermineUserByFolderDeterminerWrapperFunction = (determiner: Upload
  * });
  * const withUser = addUser(myDeterminer);
  * ```
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function determineUserByFolderWrapperFunction(config: DetermineUserByFolderWrapperFunctionConfig): DetermineUserByFolderDeterminerWrapperFunction;
 /**
@@ -289,6 +290,7 @@ export declare function determineUserByFolderWrapperFunction(config: DetermineUs
  * const addUser = determineUserByUserUploadsFolderWrapperFunction();
  * const withUser = addUser(myDeterminer);
  * ```
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function determineUserByUserUploadsFolderWrapperFunction(config?: Omit<DetermineUserByFolderWrapperFunctionConfig, 'rootFolder' | 'userFolderPrefix'>): DetermineUserByFolderDeterminerWrapperFunction;
 /**