@dereekb/firebase 13.2.2 → 13.3.0

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

@@ -1,12 +1,21 @@
+/**
+ * @module notification.details
+ *
+ * Template type metadata for the notification system. Each {@link NotificationTemplateType} is described by a
+ * {@link NotificationTemplateTypeInfo} entry that maps it to model identities, display info, and delivery rules.
+ *
+ * The {@link AppNotificationTemplateTypeInfoRecordService} provides runtime lookup of template types by model,
+ * enabling the server to discover which notification types apply to a given Firestore model.
+ */
 import { type Maybe, type ArrayOrValue } from '@dereekb/util';
 import { type FirestoreModelIdentity, type ReadFirestoreModelKeyInput } from '../../common';
 import { type NotificationTemplateType } from './notification.id';
 /**
- * NotificationTemplateTypeInfoIdentityInfo alternative/derivative identity.
- *
- * For example, this model may be directly related to the identity in "notificationModelIdentity" but notifications are actually attached to the corresponding "altNotificationModelIdentity" or "altTargetModelIdentity".
+ * Alternative model identity pair for cases where notifications are attached to a different model
+ * than the one defined in {@link NotificationTemplateTypeInfoIdentityInfo.notificationModelIdentity}.
  *
- * The alternative model should always have a NotificationBox associated with it.
+ * For example, a notification may be defined for a "project" model but actually delivered via
+ * a "team" model's NotificationBox. The alternative model must always have a NotificationBox.
  */
 export interface NotificationTemplateTypeInfoIdentityInfoAlternativeModelIdentityPair {
     /**
@@ -19,7 +28,8 @@ export interface NotificationTemplateTypeInfoIdentityInfoAlternativeModelIdentit
     readonly altTargetModelIdentity?: Maybe<FirestoreModelIdentity>;
 }
 /**
- * NotificationTemplateTypeInfo identity info
+ * Model identity mapping for a notification template type. Defines which Firestore models
+ * are associated with this notification type and which one owns the NotificationBox.
  */
 export interface NotificationTemplateTypeInfoIdentityInfo {
     /**
@@ -48,31 +58,37 @@ export interface NotificationTemplateTypeInfoIdentityInfo {
     readonly sendToNotificationModelIdentity?: Maybe<boolean>;
 }
 /**
- * Template type identifier of the notification.
+ * Complete metadata for a notification template type. Defines display info, model associations,
+ * and delivery rules for a specific {@link NotificationTemplateType}.
  *
- * Provides default information for the notification.
- *
- * Types are generally intended to be handled case-insensitively by notification services.
+ * Registered in the application's {@link NotificationTemplateTypeInfoRecord} and accessed at runtime
+ * via the {@link AppNotificationTemplateTypeInfoRecordService}.
  */
 export interface NotificationTemplateTypeInfo extends NotificationTemplateTypeInfoIdentityInfo {
     /**
-     * Notification type
+     * Template type identifier (e.g., `'comment'`, `'invite'`). Should be short to minimize Firestore storage.
      */
     readonly type: NotificationTemplateType;
     /**
-     * The notification's name
+     * Human-readable name for display in notification preference UIs.
      */
     readonly name: string;
     /**
-     * Description of the notification's content.
+     * Description of what this notification type conveys, shown in preference management UIs.
      */
     readonly description: string;
     /**
-     * If true, this notification will only be sent to recipients that explicitly enable recieving via respective NotificationBoxRecipientTemplateConfig for this type.
+     * When true, only sends to recipients who have explicitly enabled this template type in their
+     * {@link NotificationBoxRecipientTemplateConfig}. Recipients without an explicit opt-in are skipped.
+     *
+     * Overridable per-notification via {@link Notification.ois}.
      */
     readonly onlySendToExplicitlyEnabledRecipients?: boolean;
     /**
-     * If false, this notification will send sms/texts to all recipients, even if they have not explicitly opted in to recieving sms/texts.
+     * When false, sends text/SMS to all recipients regardless of explicit opt-in status
+     * (still respects explicit opt-outs).
+     *
+     * Overridable per-notification via {@link Notification.ots}.
      */
     readonly onlyTextExplicitlyEnabledRecipients?: boolean;
 }
@@ -81,18 +97,34 @@ export interface NotificationTemplateTypeInfo extends NotificationTemplateTypeIn
  */
 export type NotificationTemplateTypeInfoRecord = Record<NotificationTemplateType, NotificationTemplateTypeInfo>;
 /**
- * Creates a NotificationTemplateTypeInfoRecord from the input info array.
+ * Creates a {@link NotificationTemplateTypeInfoRecord} from an array of template type info entries.
+ *
+ * @throws {Error} When duplicate template types are found in the input array.
  *
- * @param infoArray
- * @returns
+ * @example
+ * ```ts
+ * const record = notificationTemplateTypeInfoRecord([
+ *   { type: 'comment', name: 'Comment', description: 'New comment notifications', notificationModelIdentity: projectIdentity },
+ *   { type: 'invite', name: 'Invite', description: 'Team invite notifications', notificationModelIdentity: teamIdentity }
+ * ]);
+ * ```
  */
 export declare function notificationTemplateTypeInfoRecord(infoArray: NotificationTemplateTypeInfo[]): NotificationTemplateTypeInfoRecord;
 /**
- * Reference to a NotificationTemplateTypeInfoRecord that contains a AppNotificationTemplateTypeInfoRecordService
+ * Reference to an {@link AppNotificationTemplateTypeInfoRecordService} instance.
+ *
+ * Used for dependency injection in modules that need access to the template type registry.
  */
 export interface AppNotificationTemplateTypeInfoRecordServiceRef {
     readonly appNotificationTemplateTypeInfoRecordService: AppNotificationTemplateTypeInfoRecordService;
 }
+/**
+ * Runtime service for looking up {@link NotificationTemplateTypeInfo} by model identity or template type.
+ *
+ * Built from a {@link NotificationTemplateTypeInfoRecord} via {@link appNotificationTemplateTypeInfoRecordService}.
+ * Provides indexed lookups for the server-side notification pipeline to discover which template types
+ * apply to a given model.
+ */
 export declare abstract class AppNotificationTemplateTypeInfoRecordService {
     /**
      * All records for this app.
@@ -147,4 +179,20 @@ export declare abstract class AppNotificationTemplateTypeInfoRecordService {
      */
     abstract getTemplateTypeInfosForTargetModelIdentity(identity: FirestoreModelIdentity): NotificationTemplateTypeInfo[];
 }
+/**
+ * Creates an {@link AppNotificationTemplateTypeInfoRecordService} from the given template type record.
+ *
+ * Builds internal indexes for fast lookup by notification model identity and target model identity.
+ * Handles alternative model identities defined in {@link NotificationTemplateTypeInfoIdentityInfoAlternativeModelIdentityPair}.
+ *
+ * @param appNotificationTemplateTypeInfoRecord - the complete template type registry for the application
+ *
+ * @example
+ * ```ts
+ * const service = appNotificationTemplateTypeInfoRecordService(
+ *   notificationTemplateTypeInfoRecord([commentInfo, inviteInfo])
+ * );
+ * const types = service.getTemplateTypesForNotificationModel('project/abc123');
+ * ```
+ */
 export declare function appNotificationTemplateTypeInfoRecordService(appNotificationTemplateTypeInfoRecord: NotificationTemplateTypeInfoRecord): AppNotificationTemplateTypeInfoRecordService;

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

@@ -1,49 +1,127 @@
+/**
+ * @module notification.id
+ *
+ * ID types and generation functions for notification model documents.
+ *
+ * Notification documents use "two-way flat keys" as their document IDs. A two-way flat key
+ * encodes a hierarchical Firestore model key (e.g., `'collection/id'`) into a flat string
+ * (e.g., `'collection_id'`) that can be used as a document ID while remaining reversible
+ * back to the original key via {@link inferNotificationBoxRelatedModelKey}.
+ *
+ * This pattern allows {@link NotificationBox} and {@link NotificationSummary} documents
+ * to be stored in top-level collections while maintaining a bidirectional link to the
+ * model they represent.
+ */
 import { type FactoryWithRequiredInput } from '@dereekb/util';
 import { type FirestoreModelId, type FirestoreModelKey, type FlatFirestoreModelKey, twoWayFlatFirestoreModelKey, inferKeyFromTwoWayFlatFirestoreModelKey, type FirebaseAuthUserId, type RootFirestoreModelIdentity, type FirestoreModelIdInput, type FirestoreCollectionName } from '../../common';
 /**
- * The NotificationBox's id is the two way flat firestore model key of the object that it represents.
+ * Document ID for a {@link NotificationBox}. Encoded as a two-way flat key of the model it represents.
+ *
+ * @example
+ * ```ts
+ * const boxId: NotificationBoxId = notificationBoxIdForModel('project/abc123');
+ * // boxId === 'project_abc123'
+ * ```
  */
 export type NotificationBoxId = FlatFirestoreModelKey;
+/**
+ * Full Firestore model key path for a {@link NotificationBox} document (e.g., `'notificationBox/project_abc123'`).
+ */
 export type NotificationBoxKey = FirestoreModelKey;
 /**
- * A notification box id (or firestore collection name) that is used to exclude a user from receiving notifications from that box or any notification boxes that start with the same prefix.
+ * A box ID or collection name prefix used to exclude a user from receiving notifications.
  *
- * This is used in cases where a user might be removed from access temporarily and should not recieve any notifications from that box or any child boxes.
+ * Supports prefix matching: excluding `'ab_123'` also excludes child boxes like `'ab_123_cd_456'`.
+ * Used when a user temporarily loses access to a resource and should stop receiving its notifications.
  *
- * For example, if a box with id ab_123 is excluded, then any notifications to child boxes that start with ab_123 (e.g. ab_123_cd_456) will also be excluded.
+ * @see {@link NotificationUser.x} where exclusions are stored
  */
 export type NotificationBoxSendExclusion = FirestoreCollectionName | NotificationBoxId;
 /**
- * List of notification box exclusions.
+ * List of {@link NotificationBoxSendExclusion} entries for a user.
  */
 export type NotificationBoxSendExclusionList = NotificationBoxSendExclusion[];
 /**
- * Creates a NotificationBoxId from the input FirestoreModelKey.
+ * Converts a Firestore model key to a {@link NotificationBoxId} using two-way flat key encoding.
  *
- * @param modelKey
- * @returns
+ * @example
+ * ```ts
+ * const boxId = notificationBoxIdForModel('project/abc123');
+ * // boxId === 'project_abc123'
+ * ```
  */
 export declare const notificationBoxIdForModel: typeof twoWayFlatFirestoreModelKey;
+/**
+ * Reverses a {@link NotificationBoxId} back to the original Firestore model key.
+ *
+ * @example
+ * ```ts
+ * const modelKey = inferNotificationBoxRelatedModelKey('project_abc123');
+ * // modelKey === 'project/abc123'
+ * ```
+ */
 export declare const inferNotificationBoxRelatedModelKey: typeof inferKeyFromTwoWayFlatFirestoreModelKey;
+/**
+ * Document ID for a {@link NotificationUser}. Encoded as a flat key derived from the user's auth identity.
+ */
 export type NotificationUserId = FlatFirestoreModelKey;
+/**
+ * Full Firestore model key path for a {@link NotificationUser} document.
+ */
 export type NotificationUserKey = FirestoreModelKey;
+/**
+ * Document ID for a {@link NotificationSummary}. Encoded as a two-way flat key of the model it represents.
+ */
 export type NotificationSummaryId = FlatFirestoreModelKey;
+/**
+ * Full Firestore model key path for a {@link NotificationSummary} document.
+ */
 export type NotificationSummaryKey = FirestoreModelKey;
 /**
- * Creates a NotificationSummaryId from the input FirestoreModelKey.
+ * Converts a Firestore model key to a {@link NotificationSummaryId} using two-way flat key encoding.
  *
- * @param modelKey
- * @returns
+ * @example
+ * ```ts
+ * const summaryId = notificationSummaryIdForModel('project/abc123');
+ * // summaryId === 'project_abc123'
+ * ```
  */
 export declare const notificationSummaryIdForModel: typeof twoWayFlatFirestoreModelKey;
 /**
- * Function used to retrieve a NotificationSummaryId given the input FirestoreAuthUserId.
+ * Factory function that produces a {@link NotificationSummaryId} from a user's auth UID.
+ *
+ * Used to find the notification summary for a specific user's model identity.
  */
 export type NotificationSummaryIdForUidFunction = FactoryWithRequiredInput<NotificationSummaryId, FirebaseAuthUserId>;
+/**
+ * Creates a {@link NotificationSummaryIdForUidFunction} that generates summary IDs
+ * by combining the given user model identity with the provided UID.
+ *
+ * @param userModelIdentity - the root identity for user models (e.g., `profileIdentity`)
+ *
+ * @example
+ * ```ts
+ * const summaryIdForUid = notificationSummaryIdForUidFunctionForRootFirestoreModelIdentity(profileIdentity);
+ * const summaryId = summaryIdForUid('user-uid-123');
+ * // summaryId === 'profile_user-uid-123'
+ * ```
+ */
 export declare function notificationSummaryIdForUidFunctionForRootFirestoreModelIdentity(userModelIdentity: RootFirestoreModelIdentity): NotificationSummaryIdForUidFunction;
+/**
+ * Document ID for a {@link NotificationWeek} (a {@link YearWeekCode} string).
+ */
 export type NotificationWeekId = FirestoreModelId;
+/**
+ * Full Firestore model key path for a {@link NotificationWeek} document.
+ */
 export type NotificationWeekKey = FirestoreModelKey;
+/**
+ * Document ID for a {@link Notification}.
+ */
 export type NotificationId = FirestoreModelId;
+/**
+ * Full Firestore model key path for a {@link Notification} document.
+ */
 export type NotificationKey = FirestoreModelKey;
 /**
  * Equivalent to NotificationId, but can be used to more specifically refer to a Notification with a task type.

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

@@ -1,10 +1,21 @@
+/**
+ * @module notification.item
+ *
+ * Defines the {@link NotificationItem} embedded data structure that carries notification content
+ * across multiple document types ({@link Notification}, {@link NotificationWeek}, {@link NotificationSummary}).
+ */
 import { type Maybe } from '@dereekb/util';
 import { type FirebaseAuthUserId, type FirestoreModelKey, type SavedToFirestoreIfTrue } from '../../common';
 import { type NotificationTaskType, type NotificationId, type NotificationTemplateType } from './notification.id';
 /**
- * Arbitrary metadata for a job. Derived/managed by the concrete job type.
+ * Arbitrary metadata attached to a {@link NotificationItem}. Content is defined by the concrete notification/task type.
+ *
+ * Stored directly in Firestore, so values must be Firestore-compatible (no class instances, functions, etc.).
  */
 export type NotificationItemMetadata = Readonly<Record<string, any>>;
+/**
+ * Pairs a {@link NotificationItem} with its resolved subject and message strings for display.
+ */
 export interface NotificationItemSubjectMessagePair<D extends NotificationItemMetadata = {}> {
     readonly item: NotificationItem<D>;
     readonly subject: string;
@@ -12,51 +23,67 @@ export interface NotificationItemSubjectMessagePair<D extends NotificationItemMe
     readonly date: Date;
 }
 /**
- * A notification item.
+ * Embeddable notification content carried inside {@link Notification}, {@link NotificationWeek}, and {@link NotificationSummary} documents.
  *
- * Is embedded within a Notification, NotificationWeek, and NotificationSummary.
+ * Each item has a template/task type (`t`) that determines how the notification is rendered and delivered.
+ * The optional `s` (subject) and `g` (message) fields can override the template's defaults.
+ *
+ * Field abbreviations:
+ * - `cat` — created-at timestamp
+ * - `t` — template or task type identifier
+ * - `cb` — created-by user UID
+ * - `m` — target model key
+ * - `s` — subject override
+ * - `g` — message override
+ * - `d` — metadata payload
+ * - `v` — viewed/read flag
  */
 export interface NotificationItem<D extends NotificationItemMetadata = {}> {
     /**
-     * Unique identifier
+     * Unique notification item identifier.
      */
     id: NotificationId;
     /**
-     * Notification date/time
+     * Creation timestamp of this notification item.
      */
     cat: Date;
     /**
-     * Notification task/template type.
+     * Template type (for standard notifications) or task type (for task notifications).
+     * Determines how the notification is rendered and which handler processes it.
      */
     t: NotificationTemplateType | NotificationTaskType;
     /**
-     * User who created this notification, if applicable.
+     * UID of the user who triggered this notification, if applicable.
      */
     cb?: Maybe<FirebaseAuthUserId>;
     /**
-     * Model/object that this notification item is targeting.
+     * Model key of the target object this notification relates to.
      */
     m?: Maybe<FirestoreModelKey>;
     /**
-     * Subject. Used to overwrite the template's default subject.
+     * Subject text override. Replaces the template's default subject when present.
      */
     s?: Maybe<string>;
     /**
-     * Message. Used to overwrite the template's default message.
+     * Message text override. Replaces the template's default message when present.
      */
     g?: Maybe<string>;
     /**
-     * Arbitrary metadata attached to the notification item.
-     *
-     * This is stored directly into Firestore, so be cautious about what is stored.
+     * Arbitrary metadata payload. Stored directly in Firestore — keep values serializable and small.
      */
     d?: Maybe<D>;
     /**
-     * True if this notification item is marked as read/viewed.
+     * Read/viewed flag. True if the recipient has seen this notification item.
      */
     v?: Maybe<SavedToFirestoreIfTrue>;
 }
+/**
+ * Firestore sub-object converter for embedding {@link NotificationItem} within parent documents.
+ */
 export declare const firestoreNotificationItem: import("../..").FirestoreSubObjectFieldMapFunctionsConfig<NotificationItem<{}>, Partial<import("@dereekb/util").ReplaceType<NotificationItem<{}>, import("@dereekb/util").MaybeMap<object>, any>>>;
+/**
+ * Result of splitting {@link NotificationItem} entries into read and unread groups.
+ */
 export interface UnreadNotificationItemsResult<D extends NotificationItemMetadata = {}> {
     readonly items: NotificationItem<D>[];
     readonly considerReadIfCreatedBefore?: Maybe<Date>;
@@ -64,9 +91,23 @@ export interface UnreadNotificationItemsResult<D extends NotificationItemMetadat
     readonly unread: NotificationItem<D>[];
 }
 /**
- * Returns an object containing input notification items split up by their determined read/unread state.
+ * Separates notification items into read and unread groups based on the `v` (viewed) flag
+ * and an optional cutoff date.
+ *
+ * Items are considered read if their `v` flag is true OR if they were created before the `considerReadIfCreatedBefore` date.
+ * This is used with {@link NotificationSummary.rat} to mark all older items as read.
  *
- * @param items
+ * @param items - notification items to classify
+ * @param considerReadIfCreatedBefore - optional cutoff date; items created at or before this date are treated as read
+ *
+ * @example
+ * ```ts
+ * const result = unreadNotificationItems(summary.n, summary.rat);
+ * console.log(result.unread.length); // number of unread items
+ * ```
  */
 export declare function unreadNotificationItems<D extends NotificationItemMetadata = {}>(items: NotificationItem<D>[], considerReadIfCreatedBefore?: Maybe<Date>): UnreadNotificationItemsResult<D>;
+/**
+ * Sort comparator for {@link NotificationItem} arrays. Sorts ascending by creation date (`cat`).
+ */
 export declare const sortNotificationItemsFunction: import("@dereekb/date").SortByDateFunction<NotificationItem<any>>;

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

@@ -1,3 +1,13 @@
+/**
+ * @module notification.message
+ *
+ * Defines the message factory pattern for the notification system. A {@link NotificationMessageFunctionFactory}
+ * creates per-recipient {@link NotificationMessageFunction} instances that produce channel-specific content
+ * (email, text, push, summary) from a {@link NotificationItem}.
+ *
+ * The server's notification send pipeline calls these factories to expand each notification into concrete messages
+ * before dispatching them through the configured delivery channels.
+ */
 import { type PromiseOrValue, type Maybe, type WebsiteUrl, type NameEmailPair, type ArrayOrValue } from '@dereekb/util';
 import { type NotificationRecipient, type NotificationRecipientWithConfig } from './notification.config';
 import { type NotificationSendFlags, type Notification, type NotificationBox } from './notification';
@@ -5,7 +15,7 @@ import { type NotificationItem, type NotificationItemMetadata } from './notifica
 import { type DocumentDataWithIdAndKey } from '../../common';
 import { type NotificationSendEmailMessagesResult, type NotificationSendTextMessagesResult, type NotificationSendNotificationSummaryMessagesResult } from './notification.send';
 /**
- * Contextual information when
+ * Per-recipient context passed to a {@link NotificationMessageFunction} when generating message content.
  */
 export interface NotificationMessageInputContext {
     /**
@@ -116,26 +126,32 @@ export interface NotificationMessageEmailContent extends NotificationMessageCont
 }
 export interface NotificationMessageNotificationSummaryContent {
 }
+/**
+ * Flags controlling whether a generated {@link NotificationMessage} should be delivered.
+ */
 export declare enum NotificationMessageFlag {
     /**
-     * No flag
+     * Normal delivery — message has content and should be sent.
      */
     NONE = 0,
     /**
-     * Special flag to indicate there is no content. Should not be sent.
+     * Message factory produced no content for this recipient. Delivery is skipped.
      */
     NO_CONTENT = 1,
     /**
-     * Special flag to not send the notification.
+     * Explicitly suppress delivery. Used when the factory determines the notification should not be sent.
      */
     DO_NOT_SEND = 2
 }
 /**
- * A NotificationMessage is the final result of the expanded notification.
+ * Expanded notification content for a single recipient, produced by a {@link NotificationMessageFunction}.
+ *
+ * Contains the base content plus optional channel-specific overrides for email, text, and notification summary.
+ * The `flag` field can suppress delivery if the factory determined no content or opted out.
  */
 export interface NotificationMessage<D extends NotificationItemMetadata = {}> {
     /**
-     * Optional flag
+     * Delivery control flag. When set to `NO_CONTENT` or `DO_NOT_SEND`, this message is skipped.
      */
     readonly flag?: NotificationMessageFlag;
     /**
@@ -165,24 +181,34 @@ export interface NotificationMessage<D extends NotificationItemMetadata = {}> {
      */
     readonly notificationSummaryContent?: NotificationMessageNotificationSummaryContent;
 }
+/**
+ * Configuration input for a {@link NotificationMessageFunctionFactory}, providing the notification context
+ * needed to create a per-recipient message function.
+ */
 export interface NotificationMessageFunctionFactoryConfig<D extends NotificationItemMetadata = {}> {
     /**
-     * Notification item.
+     * The notification item containing content and metadata.
      */
     readonly item: NotificationItem<D>;
     /**
-     * NotificationBox details for this message.
+     * Parent NotificationBox context (model key for the box's associated model).
      */
     readonly notificationBox: Pick<NotificationBox, 'm'>;
     /**
-     * Full Notification for this message.
+     * Full Notification document data with its Firestore ID and key.
      */
     readonly notification: DocumentDataWithIdAndKey<Notification>;
 }
 /**
- * Creates a NotificationMessageFunction from the input config.
+ * Async factory that creates a {@link NotificationMessageFunction} for a specific notification.
+ *
+ * Registered per-template-type in the application's notification configuration. The server calls this
+ * factory once per notification, then invokes the returned function once per recipient.
  */
 export type NotificationMessageFunctionFactory<D extends NotificationItemMetadata = {}> = (config: NotificationMessageFunctionFactoryConfig<D>) => Promise<NotificationMessageFunction>;
+/**
+ * Details passed to {@link NotificationMessageFunctionExtras} lifecycle callbacks after a send attempt.
+ */
 export interface NotificationMessageFunctionExtrasCallbackDetails {
     readonly success: boolean;
     readonly updatedSendFlags: NotificationSendFlags;
@@ -190,32 +216,72 @@ export interface NotificationMessageFunctionExtrasCallbackDetails {
     readonly sendTextsResult?: Maybe<NotificationSendTextMessagesResult>;
     readonly sendNotificationSummaryResult?: Maybe<NotificationSendNotificationSummaryMessagesResult>;
 }
+/**
+ * Callback function invoked by the send pipeline with delivery results.
+ */
 export type NotificationMessageFunctionExtrasCallbackFunction = (callbackDetails: NotificationMessageFunctionExtrasCallbackDetails) => PromiseOrValue<unknown>;
+/**
+ * Optional extensions attached to a {@link NotificationMessageFunction} to customize delivery behavior.
+ *
+ * Allows message factories to inject additional recipients and hook into the send lifecycle
+ * for side effects like logging, analytics, or cascading updates.
+ */
 export interface NotificationMessageFunctionExtras {
     /**
-     * Any global/additional recipient(s) that should be added to all Notifications associated with this NotificationMessageFunctionExtras.
+     * Additional recipients appended to every notification using this message function.
+     * Useful for always-CC recipients like admin accounts or audit logs.
      */
     readonly globalRecipients?: Maybe<NotificationRecipientWithConfig[]>;
     /**
-     * Called each time the notification attempts to send something.
+     * Called after each send attempt (whether successful or not) with the delivery results.
      */
     readonly onSendAttempted?: NotificationMessageFunctionExtrasCallbackFunction;
     /**
-     * Called when the notification has is marked as done after sending to all recipients.
+     * Called when all channels have completed delivery and the notification is marked done.
      */
     readonly onSendSuccess?: NotificationMessageFunctionExtrasCallbackFunction;
 }
+/**
+ * Core message generation function that produces a {@link NotificationMessage} for a single recipient.
+ */
 export type NotificationMessageFunctionWithoutExtras = (inputContext: NotificationMessageInputContext) => Promise<NotificationMessage>;
 /**
- * Converts a NotificationMessageContext to a NotificationMessage.
+ * Combined message function type: a callable that generates per-recipient content,
+ * plus optional {@link NotificationMessageFunctionExtras} for delivery customization.
+ *
+ * Created by {@link notificationMessageFunction} or returned from a {@link NotificationMessageFunctionFactory}.
  */
 export type NotificationMessageFunction = NotificationMessageFunctionWithoutExtras & NotificationMessageFunctionExtras;
 /**
- * Creates a NotificationMessageFunction from the input.
+ * Creates a {@link NotificationMessageFunction} by attaching optional {@link NotificationMessageFunctionExtras}
+ * (global recipients, lifecycle callbacks) to a base message generation function.
+ *
+ * @param fn - base function that generates message content per recipient
+ * @param extras - optional delivery customization (global recipients, send callbacks)
  *
- * @param fn
- * @param extras
- * @returns
+ * @example
+ * ```ts
+ * const msgFn = notificationMessageFunction(
+ *   async (ctx) => ({
+ *     inputContext: ctx,
+ *     content: { title: 'New comment', openingMessage: 'Someone commented on your post' }
+ *   }),
+ *   { globalRecipients: [adminRecipient] }
+ * );
+ * ```
  */
 export declare function notificationMessageFunction(fn: NotificationMessageFunctionWithoutExtras, extras?: NotificationMessageFunctionExtras): NotificationMessageFunction;
+/**
+ * Creates a {@link NotificationMessageFunctionFactory} that always returns `NO_CONTENT` messages.
+ *
+ * Useful as a placeholder factory for template types that should not produce deliverable content.
+ *
+ * @example
+ * ```ts
+ * const factory = noContentNotificationMessageFunctionFactory();
+ * const msgFn = await factory(config);
+ * const msg = await msgFn(inputContext);
+ * // msg.flag === NotificationMessageFlag.NO_CONTENT
+ * ```
+ */
 export declare function noContentNotificationMessageFunctionFactory<D extends NotificationItemMetadata = any>(): NotificationMessageFunctionFactory<D>;