@dereekb/firebase-server 13.2.1 → 13.3.0

package/model/package.json

@@ -1,14 +1,14 @@
 {
   "name": "@dereekb/firebase-server/model",
-  "version": "13.2.1",
+  "version": "13.3.0",
   "peerDependencies": {
-    "@dereekb/date": "13.2.1",
-    "@dereekb/firebase": "13.2.1",
-    "@dereekb/firebase-server": "13.2.1",
-    "@dereekb/model": "13.2.1",
-    "@dereekb/nestjs": "13.2.1",
-    "@dereekb/rxjs": "13.2.1",
-    "@dereekb/util": "13.2.1",
+    "@dereekb/date": "13.3.0",
+    "@dereekb/firebase": "13.3.0",
+    "@dereekb/firebase-server": "13.3.0",
+    "@dereekb/model": "13.3.0",
+    "@dereekb/nestjs": "13.3.0",
+    "@dereekb/rxjs": "13.3.0",
+    "@dereekb/util": "13.3.0",
     "@nestjs/common": "^11.0.0",
     "@nestjs/config": "^4.0.0",
     "archiver": "^7.0.0",

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

@@ -20,7 +20,7 @@ export interface MailgunNotificationEmailSendServiceTemplateBuilderInput {
     readonly messages: NotificationMessage[];
 }
 /**
- * Config for a mailgunNotificationEmailSendService()
+ * Configuration for creating a {@link MailgunNotificationEmailSendService} via {@link mailgunNotificationEmailSendService}.
  */
 export interface MailgunNotificationEmailSendServiceConfig {
     /**
@@ -47,5 +47,31 @@ export declare const MAILGUN_NOTIFICATION_EMAIL_SEND_SERVICE_DEFAULT_MAX_BATCH_S
  * Function that converts the input into zero or more MailgunTemplateEmailRequests.
  */
 export type MailgunNotificationEmailSendServiceTemplateBuilder = (input: MailgunNotificationEmailSendServiceTemplateBuilderInput) => PromiseOrValue<ArrayOrValue<MailgunTemplateEmailRequest>>;
+/**
+ * Mailgun-backed implementation of {@link NotificationEmailSendService}.
+ */
 export type MailgunNotificationEmailSendService = NotificationEmailSendService;
+/**
+ * Creates a {@link NotificationEmailSendService} that sends notification emails via Mailgun.
+ *
+ * Groups messages by their send template name, batches them (up to `maxBatchSizePerRequest`),
+ * converts each batch to a {@link MailgunTemplateEmailRequest} using the configured template builders,
+ * and dispatches them through the Mailgun API.
+ *
+ * @param config - service configuration including the Mailgun service, template builders, and batch size
+ *
+ * @example
+ * ```ts
+ * const emailService = mailgunNotificationEmailSendService({
+ *   mailgunService,
+ *   defaultSendTemplateName: 'notification',
+ *   messageBuilders: {
+ *     notification: buildNotificationTemplate
+ *   }
+ * });
+ *
+ * const sendInstance = await emailService.buildSendInstanceForEmailNotificationMessages(messages);
+ * const result = await sendInstance();
+ * ```
+ */
 export declare function mailgunNotificationEmailSendService(config: MailgunNotificationEmailSendServiceConfig): MailgunNotificationEmailSendService;

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

@@ -4,9 +4,15 @@ import { type Maybe } from '@dereekb/util';
 import { type TransformAndValidateFunctionResult } from '@dereekb/model';
 import { type InjectionToken } from '@nestjs/common';
 /**
- * Token to access/override the NotificationTemplateService's defaults records.
+ * NestJS injection token for the {@link NotificationInitServerActionsContextConfig},
+ * which provides the template functions used during {@link NotificationBox} and
+ * {@link NotificationSummary} initialization.
  */
 export declare const NOTIFICATION_INIT_SERVER_ACTIONS_CONTEXT_CONFIG_TOKEN: InjectionToken;
+/**
+ * Configuration providing the template functions that determine how notification models
+ * (boxes and summaries) are initialized for a given Firestore model.
+ */
 export interface NotificationInitServerActionsContextConfig {
     /**
      * MakeTemplateForNotificationBoxInitializationFunction used by the system for initializing the NotificationBoxes for models.
@@ -17,6 +23,10 @@ export interface NotificationInitServerActionsContextConfig {
      */
     readonly makeTemplateForNotificationSummaryInitialization: MakeTemplateForNotificationSummaryInitializationFunction;
 }
+/**
+ * Input passed to the template function during notification model initialization,
+ * providing the Firestore transaction context and the model identity being initialized.
+ */
 export interface MakeTemplateForNotificationRelatedModelInitializationFunctionInput {
     readonly transaction: Transaction;
     readonly flatModelKey: TwoWayFlatFirestoreModelKey;
@@ -38,15 +48,46 @@ export type MakeTemplateForNotificationRelatedModelInitializationFunctionResult<
 export type MakeTemplateForNotificationRelatedModelInitializationFunction<T> = (input: MakeTemplateForNotificationRelatedModelInitializationFunctionInput) => Promise<MakeTemplateForNotificationRelatedModelInitializationFunctionResult<T>>;
 export type MakeTemplateForNotificationBoxInitializationFunction = MakeTemplateForNotificationRelatedModelInitializationFunction<NotificationBox>;
 export type MakeTemplateForNotificationSummaryInitializationFunction = MakeTemplateForNotificationRelatedModelInitializationFunction<NotificationSummary>;
+/**
+ * Full context for notification initialization actions, combining Firebase infrastructure,
+ * notification Firestore collections, and the initialization template functions.
+ */
 export interface NotificationInitServerActionsContext extends FirebaseServerActionsContext, NotificationFirestoreCollections, FirestoreContextReference, NotificationInitServerActionsContextConfig {
 }
+/**
+ * Abstract service defining initialization actions for notification models.
+ *
+ * Provides methods to initialize individual {@link NotificationBox}/{@link NotificationSummary}
+ * documents or batch-process all uninitialized ones. Initialization uses the app-specific
+ * template functions from {@link NotificationInitServerActionsContextConfig} to determine
+ * the initial state for each model.
+ *
+ * @see {@link notificationInitServerActions} for the concrete implementation factory.
+ */
 export declare abstract class NotificationInitServerActions {
     abstract initializeNotificationBox(params: InitializeNotificationModelParams): AsyncNotificationBoxUpdateAction<InitializeNotificationModelParams>;
     abstract initializeAllApplicableNotificationBoxes(params: InitializeAllApplicableNotificationBoxesParams): Promise<TransformAndValidateFunctionResult<InitializeAllApplicableNotificationBoxesParams, () => Promise<InitializeAllApplicableNotificationBoxesResult>>>;
     abstract initializeNotificationSummary(params: InitializeNotificationModelParams): AsyncNotificationSummaryUpdateAction<InitializeNotificationModelParams>;
     abstract initializeAllApplicableNotificationSummaries(params: InitializeAllApplicableNotificationSummariesParams): Promise<TransformAndValidateFunctionResult<InitializeAllApplicableNotificationSummariesParams, () => Promise<InitializeAllApplicableNotificationSummariesResult>>>;
 }
+/**
+ * Creates a concrete {@link NotificationInitServerActions} implementation by wiring each
+ * initialization action to its factory function.
+ *
+ * @param context - the initialization context with template functions and Firestore access
+ *
+ * @example
+ * ```ts
+ * const initActions = notificationInitServerActions(context);
+ * const initBox = await initActions.initializeNotificationBox({ key: modelKey });
+ * await initBox(notificationBoxDocument);
+ * ```
+ */
 export declare function notificationInitServerActions(context: NotificationInitServerActionsContext): NotificationInitServerActions;
+/**
+ * Input for {@link initializeNotificationModelInTransaction}, providing the document,
+ * its current data, the template function, and the transaction context.
+ */
 export interface InitializeNotificationModelInTransactionInput<D extends FirestoreDocument<InitializedNotificationModel, any>> {
     readonly makeTemplateFunction: MakeTemplateForNotificationRelatedModelInitializationFunction<FirestoreDocumentData<D>>;
     readonly throwErrorIfAlreadyInitialized?: Maybe<boolean>;
@@ -54,19 +95,70 @@ export interface InitializeNotificationModelInTransactionInput<D extends Firesto
     readonly document: D;
     readonly data: FirestoreDocumentData<D>;
 }
+/**
+ * Initializes a notification model document (box or summary) 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
+ *
+ * Skips initialization if the model is already initialized, optionally throwing an error.
+ *
+ * @param input - the document, transaction, template function, and options
+ * @throws notificationModelAlreadyInitializedError when `throwErrorIfAlreadyInitialized` is true
+ */
 export declare function initializeNotificationModelInTransaction<D extends FirestoreDocument<InitializedNotificationModel, any>>(input: InitializeNotificationModelInTransactionInput<D>): Promise<{
     initialized: boolean;
     alreadyInitialized: boolean;
 }>;
+/**
+ * Factory for initializing a single {@link NotificationBox} within a Firestore transaction.
+ *
+ * Loads the box document in the transaction, reads its current data, and delegates
+ * to {@link initializeNotificationModelInTransaction} with the box-specific template function.
+ */
 export declare function initializeNotificationBoxInTransactionFactory(context: NotificationInitServerActionsContext): (params: InitializeNotificationModelParams, notificationBoxDocument: NotificationBoxDocument, transaction: Transaction) => Promise<{
     initialized: boolean;
     alreadyInitialized: boolean;
 }>;
+/**
+ * Factory for the `initializeNotificationBox` action.
+ *
+ * Wraps the in-transaction initialization in a Firestore transaction
+ * and follows the transform-and-validate pattern.
+ */
 export declare function initializeNotificationBoxFactory(context: NotificationInitServerActionsContext): import("@dereekb/model").TransformAndValidateFunctionResultFunction<InitializeNotificationModelParams, (notificationBoxDocument: NotificationBoxDocument) => Promise<NotificationBoxDocument>, object, unknown>;
+/**
+ * Factory for the `initializeAllApplicableNotificationBoxes` action.
+ *
+ * Batch-processes all {@link NotificationBox} documents flagged for initialization
+ * by querying for entries with `s=true` (setup needed), then initializing each in
+ * parallel (up to 5 concurrent tasks). Loops until no more flagged boxes are found.
+ */
 export declare function initializeAllApplicableNotificationBoxesFactory(context: NotificationInitServerActionsContext): import("@dereekb/model").TransformAndValidateFunctionResultFunction<InitializeAllApplicableNotificationBoxesParams, () => Promise<InitializeAllApplicableNotificationBoxesResult>, object, unknown>;
+/**
+ * Factory for initializing a single {@link NotificationSummary} within a Firestore transaction.
+ *
+ * Loads the summary document in the transaction, reads its current data, and delegates
+ * to {@link initializeNotificationModelInTransaction} with the summary-specific template function.
+ */
 export declare function initializeNotificationSummaryInTransactionFactory(context: NotificationInitServerActionsContext): (params: InitializeNotificationModelParams, notificationSummaryDocument: NotificationSummaryDocument, transaction: Transaction) => Promise<{
     initialized: boolean;
     alreadyInitialized: boolean;
 }>;
+/**
+ * Factory for the `initializeNotificationSummary` action.
+ *
+ * Wraps the in-transaction summary initialization in a Firestore transaction
+ * and follows the transform-and-validate pattern.
+ */
 export declare function initializeNotificationSummaryFactory(context: NotificationInitServerActionsContext): import("@dereekb/model").TransformAndValidateFunctionResultFunction<InitializeNotificationModelParams, (notificationSummaryDocument: NotificationSummaryDocument) => Promise<NotificationSummaryDocument>, object, unknown>;
+/**
+ * Factory for the `initializeAllApplicableNotificationSummaries` action.
+ *
+ * Batch-processes all {@link NotificationSummary} documents flagged for initialization
+ * by querying for entries with `s=true` (setup needed), then initializing each in
+ * parallel (up to 5 concurrent tasks). Loops until no more flagged summaries are found.
+ */
 export declare function initializeAllApplicableNotificationSummariesFactory(context: NotificationInitServerActionsContext): import("@dereekb/model").TransformAndValidateFunctionResultFunction<InitializeAllApplicableNotificationSummariesParams, () => Promise<InitializeAllApplicableNotificationSummariesResult>, object, unknown>;

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

@@ -7,17 +7,44 @@ import { type NotificationTemplateServiceRef } from './notification.config.servi
 import { type NotificationSendServiceRef } from './notification.send.service';
 import { type NotificationTaskServiceRef } from './notification.task.service';
 /**
- * Injection token for the BaseNotificationServerActionsContext
+ * NestJS injection token for the {@link BaseNotificationServerActionsContext}, which provides
+ * the foundational Firebase context, Firestore collections, and auth service needed by notification actions.
+ *
+ * The full {@link NotificationServerActionsContext} is assembled from this base plus additional services.
  */
 export declare const BASE_NOTIFICATION_SERVER_ACTION_CONTEXT_TOKEN: InjectionToken;
 /**
- * Injection token for the NotificationServerActionsContext
+ * NestJS injection token for the fully assembled {@link NotificationServerActionsContext},
+ * which adds template, send, task, and expedite services on top of the base context.
  */
 export declare const NOTIFICATION_SERVER_ACTION_CONTEXT_TOKEN: InjectionToken;
+/**
+ * Minimal context providing Firebase infrastructure, Firestore notification collections,
+ * auth service, and Firestore context needed by all notification server actions.
+ */
 export interface BaseNotificationServerActionsContext extends FirebaseServerActionsContext, NotificationFirestoreCollections, FirebaseServerAuthServiceRef, FirestoreContextReference {
 }
+/**
+ * Full context for notification server actions, extending the base with template resolution,
+ * send channel orchestration, task dispatch, and expedite services.
+ */
 export interface NotificationServerActionsContext extends BaseNotificationServerActionsContext, AppNotificationTemplateTypeInfoRecordServiceRef, NotificationTemplateServiceRef, NotificationSendServiceRef, NotificationTaskServiceRef {
 }
+/**
+ * Abstract service class defining all server-side notification CRUD and delivery actions.
+ *
+ * This is the central API surface for the notification system's backend. It provides:
+ *
+ * - **User management**: create/update {@link NotificationUser} records, resync user preferences
+ * - **Box management**: create/update {@link NotificationBox} containers and their recipients
+ * - **Summary management**: create/update {@link NotificationSummary} for in-app notification feeds
+ * - **Send pipeline**: send individual notifications, process queued notifications, and clean up sent ones
+ *
+ * Each method follows the transform-and-validate pattern: params are validated first,
+ * then a curried function is returned that operates on the target document.
+ *
+ * @see {@link notificationServerActions} for the concrete implementation factory.
+ */
 export declare abstract class NotificationServerActions {
     abstract createNotificationUser(params: CreateNotificationUserParams): AsyncNotificationUserCreateAction<CreateNotificationUserParams>;
     abstract updateNotificationUser(params: UpdateNotificationUserParams): AsyncNotificationUserUpdateAction<UpdateNotificationUserParams>;
@@ -32,12 +59,65 @@ export declare abstract class NotificationServerActions {
     abstract sendQueuedNotifications(params: SendQueuedNotificationsParams): Promise<TransformAndValidateFunctionResult<SendQueuedNotificationsParams, (sendQueuedNotificationsInput?: Maybe<SendQueuedNotificationsInput>) => Promise<SendQueuedNotificationsResult>>>;
     abstract cleanupSentNotifications(params: CleanupSentNotificationsParams): Promise<TransformAndValidateFunctionResult<CleanupSentNotificationsParams, () => Promise<CleanupSentNotificationsResult>>>;
 }
+/**
+ * Creates a concrete {@link NotificationServerActions} implementation by wiring each action
+ * to its factory function using the provided context.
+ *
+ * @param context - the fully assembled notification server actions context
+ *
+ * @example
+ * ```ts
+ * const actions = notificationServerActions(context);
+ * const sendFn = await actions.sendNotification({ key: notificationKey });
+ * const result = await sendFn(notificationDocument);
+ * ```
+ */
 export declare function notificationServerActions(context: NotificationServerActionsContext): NotificationServerActions;
+/**
+ * Factory for the `createNotificationUser` action.
+ *
+ * Validates the UID exists in Firebase Auth, then creates a new {@link NotificationUser} document
+ * with empty default and global configs. Throws if the UID is not found in Auth.
+ */
 export declare function createNotificationUserFactory(context: NotificationServerActionsContext): import("@dereekb/model").TransformAndValidateFunctionResultFunction<CreateNotificationUserParams, () => Promise<NotificationUserDocument>, object, unknown>;
+/**
+ * Factory for the `updateNotificationUser` action.
+ *
+ * Updates a {@link NotificationUser}'s default config (`dc`), global config (`gc`), and/or
+ * box configs (`bc`). When the global config changes, iterates all box configs to propagate
+ * effective recipient changes and marks affected entries for sync.
+ */
 export declare function updateNotificationUserFactory(context: NotificationServerActionsContext): import("@dereekb/model").TransformAndValidateFunctionResultFunction<UpdateNotificationUserParams, (notificationUserDocument: NotificationUserDocument) => Promise<NotificationUserDocument>, object, unknown>;
+/**
+ * Factory for the `resyncNotificationUser` action.
+ *
+ * Re-synchronizes a single {@link NotificationUser}'s box configs by iterating through
+ * entries flagged with `ns=true` (needs-sync), loading the corresponding {@link NotificationBox},
+ * and merging the user's preferences back into the box's recipient list. Handles removed entries
+ * and cleans up stale box references.
+ */
 export declare function resyncNotificationUserFactory(context: NotificationServerActionsContext): import("@dereekb/model").TransformAndValidateFunctionResultFunction<import("@dereekb/firebase").TargetModelParams, (notificationUserDocument: NotificationUserDocument) => Promise<ResyncNotificationUserResult>, object, unknown>;
+/**
+ * Factory for the `resyncAllNotificationUsers` action.
+ *
+ * Batch-processes all {@link NotificationUser} documents flagged for sync by querying
+ * for entries with `ns=true`, then calling the resync logic for each in parallel
+ * (up to 5 concurrent tasks). Loops until no more flagged users are found.
+ */
 export declare function resyncAllNotificationUsersFactory(context: NotificationServerActionsContext): () => Promise<ResyncAllNotificationUsersResult>;
+/**
+ * Factory for the `createNotificationSummary` action.
+ *
+ * Creates a new {@link NotificationSummary} document for a model, generating the summary ID
+ * from the model key and initializing it with a blank template.
+ */
 export declare function createNotificationSummaryFactory(context: NotificationServerActionsContext): import("@dereekb/model").TransformAndValidateFunctionResultFunction<CreateNotificationSummaryParams, () => Promise<NotificationSummaryDocument>, object, unknown>;
+/**
+ * Factory for the `updateNotificationSummary` action.
+ *
+ * Updates an existing {@link NotificationSummary} document's owner or setup flag.
+ * Runs within a Firestore transaction to ensure consistency.
+ */
 export declare function updateNotificationSummaryFactory(context: NotificationServerActionsContext): import("@dereekb/model").TransformAndValidateFunctionResultFunction<UpdateNotificationSummaryParams, (notificationSummaryDocument: NotificationSummaryDocument) => Promise<NotificationSummaryDocument>, object, unknown>;
 /**
  * Used for creating a new NotificationBox within a transaction.
@@ -54,10 +134,22 @@ export interface CreateNotificationBoxInTransactionInput extends NotificationBox
      */
     readonly skipCreate?: Maybe<boolean>;
 }
+/**
+ * Factory that creates a {@link NotificationBox} within a Firestore transaction.
+ *
+ * Checks for existing boxes and throws if one already exists for the model.
+ * Also syncs initial recipients with their corresponding {@link NotificationUser} documents.
+ */
 export declare function createNotificationBoxInTransactionFactory(context: BaseNotificationServerActionsContext): (params: CreateNotificationBoxInTransactionInput, transaction: Transaction) => Promise<{
     notificationBoxTemplate: NotificationBox;
     notificationBoxDocument: NotificationBoxDocument;
 }>;
+/**
+ * Factory for the `createNotificationBox` action.
+ *
+ * Wraps {@link createNotificationBoxInTransactionFactory} in a Firestore transaction
+ * and follows the transform-and-validate pattern.
+ */
 export declare function createNotificationBoxFactory(context: NotificationServerActionsContext): import("@dereekb/model").TransformAndValidateFunctionResultFunction<CreateNotificationBoxParams, () => Promise<NotificationBoxDocument>, object, unknown>;
 export declare function updateNotificationBoxFactory({ firebaseServerActionTransformFunctionFactory }: NotificationServerActionsContext): import("@dereekb/model").TransformAndValidateFunctionResultFunction<import("@dereekb/firebase").TargetModelParams, (notificationBoxDocument: NotificationBoxDocument) => Promise<NotificationBoxDocument>, object, unknown>;
 export interface UpdateNotificationBoxRecipientExclusionInTransactionInput extends NotificationBoxDocumentReferencePair {
@@ -66,6 +158,12 @@ export interface UpdateNotificationBoxRecipientExclusionInTransactionInput exten
 export interface UpdateNotificationBoxRecipientExclusionInTransactionResult {
     readonly notificationUserUpdate: Partial<NotificationUser>;
 }
+/**
+ * Factory that updates recipient send exclusions on a {@link NotificationBox} within a transaction.
+ *
+ * Manages the exclusion list (`x`) on both the box recipient and the corresponding
+ * {@link NotificationUser}'s send exclusion array, keeping them in sync.
+ */
 export declare function updateNotificationBoxRecipientExclusionInTransactionFactory(context: BaseNotificationServerActionsContext): (input: UpdateNotificationBoxRecipientExclusionInTransactionInput, transaction: Transaction) => Promise<Maybe<UpdateNotificationBoxRecipientExclusionInTransactionResult>>;
 export interface UpdateNotificationBoxRecipientInTransactionInput extends NotificationBoxDocumentReferencePair {
     /**
@@ -88,7 +186,20 @@ export interface UpdateNotificationBoxRecipientInTransactionResult {
     readonly updatedNotificationBox: NotificationBox;
     readonly notificationBoxDocument: NotificationBoxDocument;
 }
+/**
+ * Factory that updates a single recipient on a {@link NotificationBox} within a transaction.
+ *
+ * Handles inserting new recipients, updating existing ones, and removing recipients.
+ * Syncs changes with the recipient's {@link NotificationUser} document and manages
+ * recipient index assignment via a sorted-values free-index calculator.
+ */
 export declare function updateNotificationBoxRecipientInTransactionFactory(context: BaseNotificationServerActionsContext): (input: UpdateNotificationBoxRecipientInTransactionInput, transaction: Transaction) => Promise<Maybe<UpdateNotificationBoxRecipientInTransactionResult>>;
+/**
+ * Factory for the `updateNotificationBoxRecipient` action.
+ *
+ * Wraps the in-transaction recipient update logic, handling both recipient changes
+ * and send exclusion updates in a single Firestore transaction.
+ */
 export declare function updateNotificationBoxRecipientFactory(context: NotificationServerActionsContext): import("@dereekb/model").TransformAndValidateFunctionResultFunction<UpdateNotificationBoxRecipientParams, (notificationBoxDocument: NotificationBoxDocument) => Promise<NotificationBoxDocument>, object, unknown>;
 export declare const UNKNOWN_NOTIFICATION_TEMPLATE_TYPE_HOURS_DELAY = 8;
 export declare const UNKNOWN_NOTIFICATION_TEMPLATE_TYPE_DELETE_AFTER_RETRY_ATTEMPTS = 1;
@@ -105,11 +216,49 @@ export declare const NOTIFICATION_TASK_MINIMUM_SET_AT_THROTTLE_TIME_MINUTES = 1;
 export declare const NOTIFICATION_TASK_TYPE_MAX_SEND_ATTEMPTS = 5;
 export declare const NOTIFICATION_TASK_TYPE_FAILURE_DELAY_HOURS = 3;
 export declare const NOTIFICATION_TASK_TYPE_FAILURE_DELAY_MS: number;
+/**
+ * Factory for the `sendNotification` action — the core of the notification delivery pipeline.
+ *
+ * Given a {@link Notification} document, this action:
+ * 1. Loads the notification and its parent {@link NotificationBox}
+ * 2. Expands recipients across all channels (email, SMS, notification summary)
+ * 3. Resolves the message template via {@link NotificationTemplateService}
+ * 4. Builds message content for each recipient using the template's message function
+ * 5. Dispatches messages through each configured channel's send service
+ * 6. Handles task completion, week-based archival, and cleanup of the notification document
+ *
+ * Supports throttling via `sendAt` time, configurable send flags, and task-based
+ * async workflows for notifications that require multi-step processing.
+ */
 export declare function sendNotificationFactory(context: NotificationServerActionsContext): import("@dereekb/model").TransformAndValidateFunctionResultFunction<SendNotificationParams, (inputNotificationDocument: NotificationDocument) => Promise<SendNotificationResult>, object, unknown>;
+/**
+ * Warning threshold for the number of queued notifications. If exceeded, a warning is logged
+ * indicating the queue may be growing faster than it can be processed.
+ */
 export declare const SEND_QUEUE_NOTIFICATIONS_TASK_EXCESS_THRESHOLD = 5000;
+/**
+ * Optional input for the `sendQueuedNotifications` action, allowing callers to configure
+ * parallelism and observe individual send results.
+ */
 export interface SendQueuedNotificationsInput {
     readonly maxParellelSendTasks?: Maybe<number>;
     readonly onSendNotificationResult?: (result: SendNotificationResult, document: NotificationDocument) => void;
 }
+/**
+ * Factory for the `sendQueuedNotifications` action.
+ *
+ * Queries for {@link Notification} documents whose `sendAt` time has passed,
+ * then processes them in batches. Supports configurable batch sizes, time windows,
+ * and an optional {@link NotificationExpediteService} for immediate delivery.
+ * Continues processing batches until no more queued notifications are found
+ * or the time budget is exhausted.
+ */
 export declare function sendQueuedNotificationsFactory(context: NotificationServerActionsContext): import("@dereekb/model").TransformAndValidateFunctionResultFunction<SendQueuedNotificationsParams, (input?: Maybe<SendQueuedNotificationsInput>) => Promise<SendQueuedNotificationsResult>, object, unknown>;
+/**
+ * Factory for the `cleanupSentNotifications` action.
+ *
+ * Queries for {@link Notification} documents that are ready for cleanup (fully sent,
+ * past the retention window) and deletes them in batches. Continues until no more
+ * cleanup-eligible notifications are found.
+ */
 export declare function cleanupSentNotificationsFactory(context: NotificationServerActionsContext): import("@dereekb/model").TransformAndValidateFunctionResultFunction<CleanupSentNotificationsParams, () => Promise<CleanupSentNotificationsResult>, object, unknown>;

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

@@ -1,31 +1,43 @@
 import { type InjectionToken } from '@nestjs/common';
 import { type NotificationTemplateType, type NotificationMessageFunctionFactory } from '@dereekb/firebase';
 /**
- * Token to access/override the NotificationTemplateService's defaults records.
+ * NestJS injection token for overriding the default {@link NotificationMessageFunctionFactory} values
+ * used by {@link NotificationTemplateService} when no type-specific config is found.
+ *
+ * Provide a {@link NotificationTemplateServiceDefaultsRecord} at this token to set baseline
+ * message factories for each {@link NotificationTemplateType}.
  */
 export declare const NOTIFICATION_TEMPLATE_SERVICE_DEFAULTS_OVERRIDE_TOKEN: InjectionToken;
 /**
- * Token to access the NotificationTemplateService's type configs array.
+ * NestJS injection token for the array of type-specific template configurations
+ * consumed by {@link NotificationTemplateService}.
+ *
+ * Provide a {@link NotificationTemplateServiceTypeConfigArray} at this token to register
+ * message factories for individual {@link NotificationTemplateType} values.
  */
 export declare const NOTIFICATION_TEMPLATE_SERVICE_CONFIGS_ARRAY_TOKEN: InjectionToken;
 /**
- * Configuration object used by the NotificationTemplateService to describe how to respond to a NotificationTemplateType request for a NotificationMessageFunctionFactory.
+ * Maps a single {@link NotificationTemplateType} to its {@link NotificationMessageFunctionFactory},
+ * telling {@link NotificationTemplateService} how to build notification messages of that type.
  */
 export interface NotificationTemplateServiceTypeConfig {
     /**
-     * Type this config overrides.
+     * The notification template type this config handles.
      */
     readonly type: NotificationTemplateType;
     /**
-     * Factory for messages of this type.
+     * Factory that creates {@link NotificationMessageFunction} instances for this type.
      */
     readonly factory: NotificationMessageFunctionFactory<any>;
 }
 /**
- * Used by NotificationTemplateService for template configurations.
+ * Array of {@link NotificationTemplateServiceTypeConfig} entries registered
+ * via {@link NOTIFICATION_TEMPLATE_SERVICE_CONFIGS_ARRAY_TOKEN}.
  */
 export type NotificationTemplateServiceTypeConfigArray = NotificationTemplateServiceTypeConfig[];
 /**
- * A record of default NotificationMessageFunctionFactory valeus to use for specific NotificationTemplateType values.
+ * Record mapping each {@link NotificationTemplateType} to a default {@link NotificationMessageFunctionFactory}.
+ *
+ * Used as the fallback when no type-specific {@link NotificationTemplateServiceTypeConfig} is registered.
  */
 export type NotificationTemplateServiceDefaultsRecord = Record<NotificationTemplateType, NotificationMessageFunctionFactory>;

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

@@ -1,21 +1,49 @@
 import { type Maybe } from '@dereekb/util';
 import { type NotificationMessageFunction, type NotificationMessageFunctionFactory, type NotificationMessageFunctionFactoryConfig, type NotificationTemplateType } from '@dereekb/firebase';
 import { type NotificationTemplateServiceTypeConfig, type NotificationTemplateServiceTypeConfigArray, type NotificationTemplateServiceDefaultsRecord } from './notification.config';
+/**
+ * Provides a reference to a {@link NotificationTemplateService} instance.
+ */
 export interface NotificationTemplateServiceRef {
     readonly notificationTemplateService: NotificationTemplateService;
 }
 /**
- * Service dedicated to providing access to NotificationMessageFunctionFactory values for specific NotificationTemplateTypes.
+ * Resolves {@link NotificationMessageFunctionFactory} instances for a given {@link NotificationTemplateType}.
+ *
+ * Combines an optional defaults record (injected via {@link NOTIFICATION_TEMPLATE_SERVICE_DEFAULTS_OVERRIDE_TOKEN})
+ * with per-type configs (injected via {@link NOTIFICATION_TEMPLATE_SERVICE_CONFIGS_ARRAY_TOKEN}) to determine
+ * which factory to use. If a type has no registered config or default, a no-content fallback factory is used.
+ *
+ * @example
+ * ```ts
+ * const instance = notificationTemplateService.templateInstanceForType('welcome');
+ * const messageFn = await instance.loadMessageFunction({ notification, notificationBox });
+ * ```
  */
 export declare class NotificationTemplateService {
     private readonly _defaults;
     private readonly _config;
     constructor(_inputDefaults: NotificationTemplateServiceDefaultsRecord | undefined, _inputConfigs: NotificationTemplateServiceTypeConfigArray | undefined);
+    /**
+     * Returns the default factory and optional type-specific config for the given template type.
+     *
+     * @param type - the notification template type to look up
+     * @returns a tuple of [defaultFactory, typeConfig] where either may be undefined
+     */
     configPairForType(type: NotificationTemplateType): [NotificationMessageFunctionFactory, Maybe<NotificationTemplateServiceTypeConfig>];
+    /**
+     * Creates a {@link NotificationTemplateServiceInstance} scoped to a single template type,
+     * pre-wired with the resolved factory for that type.
+     *
+     * @param type - the notification template type
+     */
     templateInstanceForType(type: NotificationTemplateType): NotificationTemplateServiceInstance;
 }
 /**
- * Loads/creates a NotificationMessageFunction based on the input configuration.
+ * Loads or creates a {@link NotificationMessageFunction} for a specific notification,
+ * using the factory resolved by {@link NotificationTemplateService}.
+ *
+ * @param config - contextual data (notification, box, recipients) needed to build the message function
  */
 export type LoadNotificationMessageFunction = (config: NotificationMessageFunctionFactoryConfig) => Promise<NotificationMessageFunction>;
 /**
@@ -40,10 +68,20 @@ export interface NotificationTemplateServiceInstance {
     readonly loadMessageFunction: LoadNotificationMessageFunction;
 }
 /**
- * Creates a NotificationTemplateServiceInstance.
+ * Creates a {@link NotificationTemplateServiceInstance} bound to a specific template type.
+ *
+ * Resolves the factory from the service's type-specific config first, falling back to
+ * a no-content default factory when no config is registered for the type.
+ *
+ * @param service - the parent template service
+ * @param type - the template type to bind
  *
- * @param service
- * @param type
- * @returns
+ * @example
+ * ```ts
+ * const instance = notificationTemplateServiceInstance(service, 'order_update');
+ * if (instance.isConfiguredType) {
+ *   const messageFn = await instance.loadMessageFunction(config);
+ * }
+ * ```
  */
 export declare function notificationTemplateServiceInstance(service: NotificationTemplateService, type: NotificationTemplateType): NotificationTemplateServiceInstance;

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

@@ -2,7 +2,8 @@ import { type Maybe } from '@dereekb/util';
 import { type NotificationExpediteService, type NotificationExpediteServiceInstance, type NotificationExpediteServiceSendNotificationOptions } from './notification.expedite.service';
 import { type CreateNotificationDocumentPairInput, type CreateNotificationDocumentPairResult, type SendNotificationResult } from '@dereekb/firebase';
 /**
- * Options related to the run
+ * Input for {@link createOrRunUniqueNotificationDocument}, extending the standard notification document
+ * creation input with options for immediate execution or expedited delivery.
  */
 export interface CreateOrRunUniqueNotificationDocumentRunInput extends Omit<CreateNotificationDocumentPairInput, 'transaction'> {
     /**
@@ -36,6 +37,10 @@ export interface CreateOrRunUniqueNotificationDocumentRunInput extends Omit<Crea
      */
     readonly expediteInstance?: Maybe<NotificationExpediteServiceInstance>;
 }
+/**
+ * Result of {@link createOrRunUniqueNotificationDocument}, extending the pair result with
+ * optional send/enqueue outcomes.
+ */
 export interface CreateOrRunUniqueNotificationDocumentRunResult extends CreateNotificationDocumentPairResult {
     /**
      * Set if the notification was run.
@@ -47,11 +52,34 @@ export interface CreateOrRunUniqueNotificationDocumentRunResult extends CreateNo
     readonly runEnqueued?: Maybe<boolean>;
 }
 /**
- * Alternative version of createNotificationDocument() that checks if the document exists, and can run it if it does instead of recreated it.
+ * Creates a unique notification document if it doesn't exist, or triggers a send/expedite
+ * if the document already exists.
+ *
+ * This is the idempotent alternative to `createNotificationDocument()` for notifications
+ * flagged as unique (`ut=true`). The behavior varies based on whether the document exists:
+ *
+ * - **Document does not exist**: Creates it and optionally runs it immediately via `runImmediatelyIfCreated`.
+ * - **Document already exists**: Triggers the notification via the expedite service/instance,
+ *   or updates the `sat` (send-at time) if `updateNextRunAtTime` is set.
+ *
+ * Does not support Firestore transactions, as running should occur outside of a transaction.
+ *
+ * @param input - creation and run configuration
+ * @throws Error if the notification template is not flagged as unique
  *
- * Does not support the use of a Transaction, as running should occur outside of a transaction.
+ * @example
+ * ```ts
+ * const result = await createOrRunUniqueNotificationDocument({
+ *   ...createInput,
+ *   runImmediatelyIfCreated: true,
+ *   expediteService
+ * });
  *
- * @param input
- * @returns
+ * if (result.notificationCreated) {
+ *   // newly created
+ * } else if (result.runResult) {
+ *   // existing doc was re-sent
+ * }
+ * ```
  */
 export declare function createOrRunUniqueNotificationDocument(input: CreateOrRunUniqueNotificationDocumentRunInput): Promise<CreateOrRunUniqueNotificationDocumentRunResult>;