@dereekb/firebase 13.2.2 → 13.3.0

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

@@ -1,170 +1,258 @@
+/**
+ * @module notification.config
+ *
+ * Notification recipient configuration types and the bitwise encoding system for per-template channel preferences.
+ *
+ * Configuration follows a 3-level hierarchy (highest priority first):
+ * 1. {@link NotificationUser.gc} — Global config override (applies at send time, not synced to boxes)
+ * 2. {@link NotificationUserNotificationBoxRecipientConfig} — Per-box config on the user (synced to boxes)
+ * 3. {@link NotificationBoxRecipientTemplateConfig} — Template defaults from the system configuration
+ *
+ * Each level can enable/disable delivery per channel (email, text, push, summary) per template type.
+ * Configs are stored efficiently using bitwise encoding via {@link EncodedNotificationBoxRecipientTemplateConfig}.
+ */
 import { type Maybe, type EmailAddress, type E164PhoneNumber, type BitwiseEncodedSet, type IndexRef, type NeedsSyncBoolean } from '@dereekb/util';
 import { type NotificationBoxId, type NotificationSummaryId, type NotificationTemplateType } from './notification.id';
 import { type FirebaseAuthUserId, type SavedToFirestoreIfTrue } from '../../common';
 /**
- * Notification configuration state for a template.
+ * Per-template notification channel preferences for a recipient.
  *
- * Denotes which modes of message are enabled for the user to recieve.
+ * Controls which delivery channels are enabled for a specific {@link NotificationTemplateType}.
+ * Undefined values inherit from the parent level in the configuration hierarchy.
+ *
+ * Field abbreviations:
+ * - `sd` — send default (master toggle for all channels)
+ * - `se` — send email
+ * - `st` — send text/SMS
+ * - `sp` — send push notification
+ * - `sn` — send to notification summary
  */
 export interface NotificationBoxRecipientTemplateConfig {
     /**
-     * Send default is enabled/disabled for all types if not defined
+     * Master toggle. When set, acts as the default for all channels that aren't individually configured.
      */
     sd?: Maybe<boolean>;
     /**
-     * Email enabled / Send Email
+     * Email channel enabled/disabled.
      */
     se?: Maybe<boolean>;
     /**
-     * Phone enabled / Send Text
+     * Text/SMS channel enabled/disabled.
      */
     st?: Maybe<boolean>;
     /**
-     * Push notification enabled / Send Push Notification
+     * Push notification channel enabled/disabled.
      */
     sp?: Maybe<boolean>;
     /**
-     * Send to notification summary of the associate user, if applicable.
+     * In-app notification summary channel enabled/disabled.
      */
     sn?: Maybe<boolean>;
 }
+/**
+ * Merges two {@link NotificationBoxRecipientTemplateConfig} objects, preferring values from `a` over `b`.
+ *
+ * @example
+ * ```ts
+ * const merged = mergeNotificationBoxRecipientTemplateConfigs(
+ *   { se: true },       // user prefers email on
+ *   { se: false, st: true } // defaults
+ * );
+ * // merged === { se: true, st: true }
+ * ```
+ */
 export declare function mergeNotificationBoxRecipientTemplateConfigs(a?: Maybe<NotificationBoxRecipientTemplateConfig>, b?: Maybe<NotificationBoxRecipientTemplateConfig>): NotificationBoxRecipientTemplateConfig;
+/**
+ * Resolves a {@link NotificationBoxRecipientTemplateConfig} by filling in undefined channel flags with the `sd` (send default) value.
+ *
+ * This produces the "effective" configuration used at send time, where each channel has a definite boolean.
+ *
+ * @example
+ * ```ts
+ * const effective = effectiveNotificationBoxRecipientTemplateConfig({ sd: true, se: false });
+ * // effective === { sd: true, se: false, st: true, sp: true, sn: true }
+ * ```
+ */
 export declare function effectiveNotificationBoxRecipientTemplateConfig(a: NotificationBoxRecipientTemplateConfig): NotificationBoxRecipientTemplateConfig;
 /**
- * Recipient configuration for a notification
+ * Contact information for a notification recipient.
+ *
+ * When `uid` is set, the server resolves contact details (name, email, phone) from the user's profile.
+ * Override fields (`n`, `e`, `t`) take precedence over profile data when present.
+ *
+ * Field abbreviations:
+ * - `uid` — Firebase auth user ID
+ * - `n` — name override
+ * - `e` — email override
+ * - `t` — phone/text number override (E.164 format)
+ * - `s` — notification summary ID (ignored when `uid` is set)
  */
 export interface NotificationRecipient {
     /**
-     * User id for this config, if applicable.
-     *
-     * Is used to retrieve the contact's information when sending them information, as well as push notification details.
+     * Firebase auth UID. When set, contact info is resolved from the user's profile and push notification tokens.
      */
     uid?: Maybe<FirebaseAuthUserId>;
     /**
-     * User's name. Overrides any info in the user's Profile.
+     * Display name override. Takes precedence over the user's profile name.
      */
     n?: Maybe<string>;
     /**
-     * User's email address. Overrides any info in the user's Profile.
+     * Email address override. Takes precedence over the user's profile email.
      */
     e?: Maybe<EmailAddress>;
     /**
-     * User's phone number to send text messages to. Overrides any info in the user's Profile.
+     * Phone number override (E.164 format). Takes precedence over the user's profile phone.
      */
     t?: Maybe<E164PhoneNumber>;
     /**
-     * Notification summary id to send notifications to. Ignored and/or set null if uid is defined.
+     * Notification summary ID for in-app delivery. Automatically cleared when `uid` is set.
      */
     s?: Maybe<NotificationSummaryId>;
 }
+/**
+ * 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.
+ */
 export declare function updateNotificationRecipient(a: NotificationRecipient, b: Partial<NotificationRecipient>): NotificationRecipient;
+/**
+ * A {@link NotificationRecipient} combined with inline {@link NotificationBoxRecipientTemplateConfig} overrides.
+ *
+ * Used on individual {@link Notification} documents to attach per-notification recipient preferences
+ * that can override the box-level and user-level configurations.
+ */
 export interface NotificationRecipientWithConfig extends NotificationRecipient, NotificationBoxRecipientTemplateConfig {
 }
+/**
+ * Firestore sub-object converter for {@link NotificationRecipientWithConfig}.
+ */
 export declare const firestoreNotificationRecipientWithConfig: import("../..").FirestoreSubObjectFieldMapFunctionsConfig<NotificationRecipientWithConfig, Partial<import("@dereekb/util").ReplaceType<NotificationRecipientWithConfig, import("@dereekb/util").MaybeMap<object>, any>>>;
+/**
+ * Recipient-level opt-in/opt-out flag on a {@link NotificationBoxRecipient}.
+ *
+ * Non-zero values cause the recipient to be skipped during notification delivery.
+ */
 export declare enum NotificationBoxRecipientFlag {
     /**
-     * The recipient is enabled.
-     *
-     * This is a transient state that should not be stored.
+     * Recipient is active and will receive notifications. This is the default; not stored in Firestore.
      */
     ENABLED = 0,
     /**
-     * The recipient is not enabled to recieve notifications currently.
+     * Recipient is administratively disabled (e.g., by the box owner).
      */
     DISABLED = 1,
     /**
-     * Recipient opted themselves out from recieving notifications.
+     * Recipient opted themselves out from receiving notifications.
      */
     OPT_OUT = 2
 }
 /**
- * Settings related to recipients that recieve notifications.
+ * Recipient entry embedded in a {@link NotificationBox}. Combines contact info with per-template channel configs.
+ *
+ * When `uid` is set, contact details are resolved from the user's profile at send time.
+ * The `i` field (from {@link IndexRef}) tracks the recipient's position and is synced with
+ * the corresponding {@link NotificationUserNotificationBoxRecipientConfig} on the user side.
  *
- * If uid is set, then most other NotificationRecipient fields are ignored as those are pulled from auth.
+ * Field abbreviations:
+ * - `x` — excluded flag (set via {@link NotificationBoxSendExclusion})
+ * - `c` — per-template channel config record
+ * - `f` — opt-in/opt-out flag
+ * - `lk` — locked flag (prevents box-side updates; user can still update their own config)
  */
 export interface NotificationBoxRecipient extends NotificationRecipient, IndexRef {
     /**
-     * Whether or not this recipient has been marked as excluded.
-     *
-     * This can only be updated by removing the exclusion from the.
+     * Excluded flag. Set when the recipient is excluded via a {@link NotificationBoxSendExclusion} on their {@link NotificationUser}.
+     * Can only be cleared by removing the exclusion from the user's exclusion list.
      */
     x?: Maybe<SavedToFirestoreIfTrue>;
     /**
-     * Enabled config types
+     * Per-template channel configuration. Keys are {@link NotificationTemplateType} values.
      */
     c: NotificationBoxRecipientTemplateConfigRecord;
     /**
-     * Current opt in flag. Non-zero values are opt-out.
-     *
-     * TODO: Test updating the flag and syncing
+     * Opt-in/opt-out flag. Non-zero values prevent notification delivery to this recipient.
      */
     f?: Maybe<NotificationBoxRecipientFlag>;
     /**
-     * Locked state that corresponds to the user's configuration and is sync'd by NotificationUserNotificationBoxRecipientConfig.
-     *
-     * If locked, updating the NotificationBox recipient will throw an error. The user can update their settings without issue.
+     * Locked flag. When true, the box cannot modify this recipient's config — only the user can update via their {@link NotificationUser}.
      */
     lk?: Maybe<SavedToFirestoreIfTrue>;
 }
+/**
+ * Creates a new {@link NotificationBoxRecipient} for a user with an empty config record.
+ *
+ * @param uid - the user's Firebase auth UID
+ * @param i - the recipient's index position in the box's recipient array
+ */
 export declare function newNotificationBoxRecipientForUid(uid: FirebaseAuthUserId, i: number): NotificationBoxRecipient;
 /**
- * Default NotificationUserNotificationBoxRecipientConfig.
+ * Default/fallback notification config stored on a {@link NotificationUser}.
+ *
+ * Used as the base configuration for the user's direct/default config (`dc`) and global config override (`gc`).
+ * Omits per-recipient fields (index, name, summary ID, uid, exclusion) that only apply to box-level entries.
+ *
+ * Field abbreviations:
+ * - `lk` — locked flag (prevents box-side updates to this user's recipient entry)
+ * - `bk` — blocked flag (prevents the box from re-adding this user)
  */
 export interface NotificationUserDefaultNotificationBoxRecipientConfig extends Omit<NotificationBoxRecipient, 'i' | 'n' | 's' | 'uid' | 'x'> {
     /**
-     * Locked state.
-     *
-     * If locked, updating the NotificationBox recipient will throw an error. The user can update their settings without issue.
+     * Locked flag. Prevents the NotificationBox from modifying this user's recipient config.
      */
     lk?: Maybe<SavedToFirestoreIfTrue>;
     /**
-     * Blocked state.
-     *
-     * If blocked, this NotificationBox will not be able to add this user back.
+     * Blocked flag. Prevents the NotificationBox from re-adding this user as a recipient.
      */
     bk?: Maybe<SavedToFirestoreIfTrue>;
 }
+/**
+ * Merges two {@link NotificationUserDefaultNotificationBoxRecipientConfig} objects, preferring defined values from `a` over `b`.
+ */
 export declare function mergeNotificationUserDefaultNotificationBoxRecipientConfig(a: NotificationUserDefaultNotificationBoxRecipientConfig, b: NotificationUserDefaultNotificationBoxRecipientConfig): NotificationUserDefaultNotificationBoxRecipientConfig;
 /**
- * Used to reflect the NotificationBoxRecipient config back to a NotificationUser.
+ * Per-box notification config stored on a {@link NotificationUser}, mirroring the user's {@link NotificationBoxRecipient} entry.
  *
- * The index reflects the index the user is in the NotificationBox.
+ * The `i` field tracks the user's index in the box's recipient array. Changes here are synced
+ * bidirectionally with the corresponding {@link NotificationBox} during server-side sync.
+ *
+ * Field abbreviations:
+ * - `nb` — NotificationBox ID this config mirrors
+ * - `rm` — removed flag (user self-removed from the box)
+ * - `ns` — needs-sync flag
+ * - `lk` — locked flag (prevents box-side updates)
+ * - `bk` — blocked flag (prevents re-addition to the box)
  */
 export interface NotificationUserNotificationBoxRecipientConfig extends Omit<NotificationBoxRecipient, 'uid'> {
     /**
-     * NotificationBox this configuration reflects.
-     *
-     * The model can be derived from this id.
+     * ID of the {@link NotificationBox} this config mirrors. The related model key can be inferred via {@link inferNotificationBoxRelatedModelKey}.
      */
     nb: NotificationBoxId;
     /**
-     * Removed state.
-     *
-     * If flagged, then this user has flagged themselves to be removed from the NotificationBox or have already been removed.
-     *
-     * Only the NotificationBox can restore a user, so a if a user removes themselves the user cannot restore themselves.
-     * A user will typically prefer to utilize the "f" value (opt-out) flag to not recieve any notifications, rather than remove themselves.
+     * Self-removal flag. When set, the user has removed themselves from this box.
      *
-     * The config for this NotificationBox is retained on the NotificationUser, unless the user deletes the configuration themselves.
+     * Only the box owner can restore a removed user. Users typically prefer the `f` (opt-out) flag instead,
+     * which stops delivery without removing the subscription. The config is retained unless the user explicitly deletes it.
      */
     rm?: Maybe<SavedToFirestoreIfTrue>;
     /**
-     * Needs to be sync'd with the NotificationBox
+     * Whether this config needs to be synced with the corresponding {@link NotificationBox} recipient entry.
      */
     ns?: Maybe<NeedsSyncBoolean>;
     /**
-     * Locked state.
-     *
-     * If locked, updating the NotificationBox recipient will throw an error. The user can update their settings without issue.
+     * Locked flag. Prevents the box from modifying this user's recipient config.
      */
     lk?: Maybe<SavedToFirestoreIfTrue>;
     /**
-     * Blocked state.
-     *
-     * If blocked, this NotificationBox will not be able to add this user back.
+     * Blocked flag. Prevents the box from re-adding this user as a recipient.
      */
     bk?: Maybe<SavedToFirestoreIfTrue>;
 }
+/**
+ * Bit positions for encoding {@link NotificationBoxRecipientTemplateConfig} as a {@link BitwiseEncodedSet}.
+ *
+ * Each channel has an ON and OFF bit. If neither is set, the channel inherits from the parent config.
+ * This encoding allows compact storage of per-template preferences in Firestore.
+ */
 export declare enum NotificationBoxRecipientTemplateConfigBoolean {
     SEND_ALL_ON = 0,
     SEND_ALL_OFF = 1,
@@ -178,35 +266,76 @@ export declare enum NotificationBoxRecipientTemplateConfigBoolean {
     NOTIFICATION_SUMMARY_OFF = 9
 }
 /**
- * Encoded NotificationBoxRecipientTemplateConfig
+ * Bitwise-encoded form of {@link NotificationBoxRecipientTemplateConfig}, stored as a number in Firestore
+ * for space efficiency. Decoded via the internal `notificationBoxRecipientTemplateConfigDencoder`.
  */
 export type EncodedNotificationBoxRecipientTemplateConfig = BitwiseEncodedSet;
 /**
- * Map of template types to their configurations.
+ * Map of {@link NotificationTemplateType} to per-channel configuration for a recipient.
  *
- * Should not be saved with any template type entirely disabled.
+ * Stored on {@link NotificationBoxRecipient} and {@link NotificationUserNotificationBoxRecipientConfig}.
+ * Template types with all channels disabled should be omitted to save space.
  */
 export type NotificationBoxRecipientTemplateConfigRecord = Record<NotificationTemplateType, NotificationBoxRecipientTemplateConfig>;
+/**
+ * Merges two {@link NotificationBoxRecipientTemplateConfigRecord} objects, preferring defined values from `a`.
+ */
 export declare function mergeNotificationBoxRecipientTemplateConfigRecords(a: NotificationBoxRecipientTemplateConfigRecord, b: NotificationBoxRecipientTemplateConfigRecord): NotificationBoxRecipientTemplateConfigRecord;
 /**
- * Encoded NotificationBoxRecipientTemplateConfigRecord
+ * Bitwise-encoded form of {@link NotificationBoxRecipientTemplateConfigRecord}, with each template type
+ * mapped to its {@link EncodedNotificationBoxRecipientTemplateConfig} number.
  */
 export type EncodedNotificationBoxRecipientTemplateConfigRecord = Record<NotificationTemplateType, EncodedNotificationBoxRecipientTemplateConfig>;
+/**
+ * Creates a Firestore field converter for {@link NotificationBoxRecipientTemplateConfigRecord},
+ * using bitwise encoding for compact storage.
+ */
 export declare function firestoreNotificationBoxRecipientTemplateConfigRecord(): import("../..").FirestoreModelFieldMapFunctionsConfig<import("../..").FirestoreEncodedObjectMapFieldValueType<NotificationBoxRecipientTemplateConfig, string>, import("../..").FirestoreMapFieldType<number, string>>;
+/**
+ * Firestore sub-object converter for {@link NotificationBoxRecipient}.
+ */
 export declare const firestoreNotificationBoxRecipient: import("../..").FirestoreSubObjectFieldMapFunctionsConfig<NotificationBoxRecipient, Partial<import("@dereekb/util").ReplaceType<NotificationBoxRecipient, import("@dereekb/util").MaybeMap<object>, any>>>;
+/**
+ * Firestore sub-object converter for {@link NotificationUserDefaultNotificationBoxRecipientConfig}.
+ */
 export declare const firestoreNotificationUserDefaultNotificationBoxRecipientConfig: import("../..").FirestoreSubObjectFieldMapFunctionsConfig<NotificationUserDefaultNotificationBoxRecipientConfig, Partial<import("@dereekb/util").ReplaceType<NotificationUserDefaultNotificationBoxRecipientConfig, import("@dereekb/util").MaybeMap<object>, any>>>;
+/**
+ * Firestore sub-object converter for {@link NotificationUserNotificationBoxRecipientConfig}.
+ */
 export declare const firestoreNotificationUserNotificationBoxRecipientConfig: import("../..").FirestoreSubObjectFieldMapFunctionsConfig<NotificationUserNotificationBoxRecipientConfig, Partial<import("@dereekb/util").ReplaceType<NotificationUserNotificationBoxRecipientConfig, import("@dereekb/util").MaybeMap<object>, any>>>;
+/**
+ * Array-form entry of a {@link NotificationBoxRecipientTemplateConfig} with its template type key.
+ *
+ * Used for UI display where iterating over an array is more convenient than a record.
+ */
 export interface NotificationBoxRecipientTemplateConfigArrayEntry extends NotificationBoxRecipientTemplateConfig {
     /**
-     * Array entry template type
+     * The template type this config entry belongs to.
      */
     type: NotificationTemplateType;
 }
+/**
+ * Array form of {@link NotificationBoxRecipientTemplateConfigRecord} for UI consumption.
+ */
 export type NotificationBoxRecipientTemplateConfigArray = NotificationBoxRecipientTemplateConfigArrayEntry[];
+/**
+ * Converts a {@link NotificationBoxRecipientTemplateConfigRecord} to an array of entries with their type keys.
+ *
+ * @example
+ * ```ts
+ * const array = notificationBoxRecipientTemplateConfigRecordToArray({ 'comment': { se: true } });
+ * // array === [{ type: 'comment', se: true }]
+ * ```
+ */
 export declare function notificationBoxRecipientTemplateConfigRecordToArray(input: NotificationBoxRecipientTemplateConfigRecord): NotificationBoxRecipientTemplateConfigArray;
+/**
+ * Converts a {@link NotificationBoxRecipientTemplateConfigArray} back to a {@link NotificationBoxRecipientTemplateConfigRecord}.
+ */
 export declare function notificationBoxRecipientTemplateConfigArrayToRecord(input: NotificationBoxRecipientTemplateConfigArray): NotificationBoxRecipientTemplateConfigRecord;
 /**
- * Config object that may contain a boolean called sendNotification.
+ * Mixin interface for objects that can optionally trigger a notification on save/update.
+ *
+ * Used in API parameter types to let callers opt in or out of notification delivery for an action.
  */
 export interface SendNotificationRef {
     sendNotification?: Maybe<boolean>;

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

@@ -1,3 +1,11 @@
+/**
+ * @module notification.create
+ *
+ * Factory functions and template types for creating {@link Notification} documents.
+ *
+ * Provides a fluent input pattern ({@link CreateNotificationTemplateInput}) that maps friendly field names
+ * to the abbreviated Firestore fields, plus throttling support to avoid duplicate sends.
+ */
 import { type Maybe, type Milliseconds, type ModelKey } from '@dereekb/util';
 import { type Notification, type NotificationDocument, type NotificationFirestoreCollections, NotificationSendType } from './notification';
 import { type NotificationRecipientWithConfig } from './notification.config';
@@ -5,7 +13,8 @@ import { type NotificationTaskType, type NotificationTaskUniqueId, type Notifica
 import { type FirebaseAuthUserId, type FirestoreDocumentAccessor, type ReadFirestoreModelKeyInput, type Transaction } from '../../common';
 import { type NotificationItem } from './notification.item';
 /**
- * Template item for a new Notification
+ * Template for the embedded {@link NotificationItem} within a new notification.
+ * Omits auto-generated fields (`id`, `cat`) that are set during document creation.
  */
 export interface CreateNotificationTemplateItem extends Omit<NotificationItem, 'r' | 'id' | 'cat'> {
     /**
@@ -14,7 +23,9 @@ export interface CreateNotificationTemplateItem extends Omit<NotificationItem, '
     readonly cat?: Maybe<Date>;
 }
 /**
- * Template use for creating a new Notification
+ * Low-level template for creating a new {@link Notification} document. Uses Firestore field abbreviations directly.
+ *
+ * Prefer using {@link CreateNotificationTemplateInput} with {@link createNotificationTemplate} for a friendlier API.
  */
 export interface CreateNotificationTemplate extends Partial<Omit<Notification, 'n' | 'a' | 'd' | 'tsr' | 'esr'>> {
     /**
@@ -44,6 +55,22 @@ export interface CreateNotificationTemplate extends Partial<Omit<Notification, '
      */
     readonly overrideExistingTask?: Maybe<boolean>;
 }
+/**
+ * Friendly input type for creating notification templates. Maps readable field names to the abbreviated Firestore fields.
+ *
+ * Processed by {@link createNotificationTemplate} into a {@link CreateNotificationTemplate}.
+ *
+ * @example
+ * ```ts
+ * const template = createNotificationTemplate({
+ *   notificationModel: 'project/abc123',
+ *   type: 'comment',
+ *   subject: 'New comment',
+ *   message: 'Someone commented on your project',
+ *   createdBy: 'user-uid-123'
+ * });
+ * ```
+ */
 export interface CreateNotificationTemplateInput extends Partial<Omit<CreateNotificationTemplate, 'notificationModel'>>, Partial<Omit<CreateNotificationTemplateItem, 't' | 'cat'>> {
     /**
      * Model key input of the NotificationBox's target model (not the NotificationBox/key)
@@ -90,7 +117,20 @@ export interface CreateNotificationTemplateInput extends Partial<Omit<CreateNoti
      */
     readonly explicitOptInTextSmsSendOnly?: Maybe<boolean>;
 }
+/**
+ * Converts a {@link CreateNotificationTemplateInput} into a {@link CreateNotificationTemplate}
+ * ready for document creation.
+ *
+ * Maps friendly field names (`subject`, `message`, `createdBy`, etc.) to their Firestore abbreviations
+ * and filters out null/undefined metadata values.
+ */
 export declare function createNotificationTemplate(input: CreateNotificationTemplateInput): CreateNotificationTemplate;
+/**
+ * Input parameters controlling whether a notification should actually be created and sent.
+ *
+ * Supports both an explicit toggle (`sendNotification`) and time-based throttling
+ * to prevent duplicate sends within a configurable window.
+ */
 export interface ShouldSendCreatedNotificationInput {
     /**
      * Whether or not to actually create/save the notification. Defaults to true.
@@ -106,12 +146,15 @@ export interface ShouldSendCreatedNotificationInput {
     readonly sendNotificationThrottleTime?: Maybe<Milliseconds>;
 }
 /**
- * Returns true if the notification should be created/sent, given the input.
+ * Determines whether a notification should be created based on the explicit toggle and throttle settings.
  *
- * @param input
- * @returns
+ * Returns false if `sendNotification` is explicitly false, or if the throttle window hasn't elapsed.
  */
 export declare function shouldSendCreatedNotificationInput(input: ShouldSendCreatedNotificationInput): boolean;
+/**
+ * Full input for creating a {@link Notification} document, including the template, transaction context,
+ * and collection accessors.
+ */
 export interface CreateNotificationDocumentPairInput extends ShouldSendCreatedNotificationInput {
     /**
      * Now to use when creating the notification.
@@ -140,6 +183,9 @@ export interface CreateNotificationDocumentPairInput extends ShouldSendCreatedNo
      */
     readonly accessor?: FirestoreDocumentAccessor<Notification, NotificationDocument>;
 }
+/**
+ * Result of creating a notification document pair (document reference + data), before or after saving.
+ */
 export interface CreateNotificationDocumentPairResult extends Pick<CreateNotificationTemplate, 'overrideExistingTask'> {
     readonly notificationDocument: NotificationDocument;
     readonly notification: Notification;
@@ -153,11 +199,14 @@ export interface CreateNotificationDocumentPairResult extends Pick<CreateNotific
     readonly isNotificationTask: boolean;
 }
 /**
- * Creates a CreateNotificationDocumentPairResult from the input.
+ * Creates a notification document reference and builds the {@link Notification} data, but does NOT save to Firestore.
+ *
+ * Use {@link createNotificationDocument} to both create and save in one step.
  *
- * Only creates a pair. Used createNotificationDocument() to also save the document's data.
+ * For unique task notifications, generates a deterministic document ID from the target model and task type.
  *
- * @param template
+ * @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;
 /**
@@ -165,15 +214,15 @@ export declare function createNotificationDocumentPair(input: CreateNotification
  */
 export declare function _createNotificationDocumentFromPair(input: Pick<CreateNotificationDocumentPairInput, 'shouldCreateNotification' | keyof ShouldSendCreatedNotificationInput>, pair: CreateNotificationDocumentPairResult): Promise<CreateNotificationDocumentPairResult>;
 /**
- * Creates a new Notification and saves it to Firestore. Returns the pair.
+ * Creates a new {@link Notification} document and saves it to Firestore.
  *
- * @param input
+ * For unique tasks with `overrideExistingTask`, uses `set()` to replace existing documents.
+ * Otherwise uses `create()` which fails if the document already exists.
  */
 export declare function createNotificationDocument(input: CreateNotificationDocumentPairInput): Promise<CreateNotificationDocumentPairResult>;
 /**
- * Creates a new Notification and saves it to Firestore and returns the pair if sendNotification in the input is not false.
+ * Creates and saves a notification only if sending conditions are met (not throttled, not explicitly disabled).
  *
- * @param input
- * @returns
+ * Returns `undefined` if the notification was not created.
  */
 export declare function createNotificationDocumentIfSending(input: CreateNotificationDocumentPairInput): Promise<Maybe<CreateNotificationDocumentPairResult>>;

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

@@ -1,10 +1,22 @@
+/**
+ * @module notification.create.task
+ *
+ * Convenience factory for creating task-type notification templates.
+ * Wraps {@link createNotificationTemplate} with task-specific defaults.
+ */
 import { type Maybe } from '@dereekb/util';
 import { type NotificationTaskCheckpointString } from './notification';
 import { type CreateNotificationTemplate, type CreateNotificationTemplateInput } from './notification.create';
 /**
- * Template use for creating a new Notification task.
+ * Template for creating a task-type {@link Notification}. Alias for {@link CreateNotificationTemplate}.
  */
 export type CreateNotificationTaskTemplate = CreateNotificationTemplate;
+/**
+ * Simplified input for creating task notification templates. Omits fields not applicable to tasks
+ * (recipients, send type, recipient flags) and makes `notificationModel` optional.
+ *
+ * When `notificationModel` is omitted, defaults to {@link DEFAULT_NOTIFICATION_TASK_NOTIFICATION_MODEL_KEY}.
+ */
 export interface CreateNotificationTaskTemplateInput extends Omit<CreateNotificationTemplateInput, 'notificationModel' | 'st' | 'recipients' | 'r' | 'rf' | 'sendType' | 'st'>, Partial<Pick<CreateNotificationTemplateInput, 'notificationModel'>> {
     /**
      * Corresponds with the tpr field in the Notification.
@@ -14,9 +26,18 @@ export interface CreateNotificationTaskTemplateInput extends Omit<CreateNotifica
     readonly completedCheckpoints?: Maybe<NotificationTaskCheckpointString[]>;
 }
 /**
- * Creates a notification template for a Notification with the task type.
+ * Creates a {@link CreateNotificationTaskTemplate} with `TASK_NOTIFICATION` send type and no recipients.
+ *
+ * @throws {Error} When `unique=true` but no `notificationModel` or target model is specified.
  *
- * @param input
- * @returns
+ * @example
+ * ```ts
+ * const template = createNotificationTaskTemplate({
+ *   type: 'generate-report',
+ *   targetModel: 'project/abc123',
+ *   unique: true,
+ *   data: { reportType: 'monthly' }
+ * });
+ * ```
  */
 export declare function createNotificationTaskTemplate(input: CreateNotificationTaskTemplateInput): CreateNotificationTaskTemplate;