@dereekb/firebase 13.2.2 → 13.3.1

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

@@ -1,52 +1,49 @@
+/**
+ * @module notification.query
+ *
+ * Firestore query constraint builders for notification model documents.
+ * Used by the server-side action service to find documents that need processing.
+ */
 import { type FirestoreQueryConstraint } from '../../common/firestore';
 import { type NotificationBoxSendExclusion } from './notification.id';
 import { type ArrayOrValue } from '@dereekb/util';
 /**
- * Query for notificationUsers that are flagged for initialization.
+ * Query constraints for finding {@link NotificationUser} documents that have pending config syncs (`ns == true`).
  *
- * @param now
- * @returns
+ * Used by the server to discover users whose configs need to be synced to their NotificationBox recipients.
  */
 export declare function notificationUsersFlaggedForNeedsSyncQuery(): FirestoreQueryConstraint[];
 /**
- * Query for notificationUsers that have excluded any of the input notification box ids.
+ * Query constraints for finding {@link NotificationUser} documents that have any of the given exclusion IDs in their `x` array.
  *
- * @param now
- * @returns
+ * @param exclusionId - one or more box IDs or collection name prefixes to match against
  */
 export declare function notificationUserHasExclusionQuery(exclusionId: ArrayOrValue<NotificationBoxSendExclusion>): FirestoreQueryConstraint[];
 /**
- * Query for notificationSummaries that are flagged for initialization.
- *
- * @param now
- * @returns
+ * Query constraints for finding {@link NotificationSummary} documents that need server-side initialization (`s == true`).
  */
 export declare function notificationSummariesFlaggedForNeedsInitializationQuery(): FirestoreQueryConstraint[];
 /**
- * Query for notificationBoxes that are flagged for initialization.
- *
- * @param now
- * @returns
+ * Query constraints for finding {@link NotificationBox} documents that need server-side initialization (`s == true`).
  */
 export declare function notificationBoxesFlaggedForNeedsInitializationQuery(): FirestoreQueryConstraint[];
 /**
- * Query for notificationBoxes that are flagged as invalid.
+ * Query constraints for finding {@link NotificationBox} documents flagged as invalid (`fi == true`).
  *
- * @param now
- * @returns
+ * Used by the server to clean up boxes that could not be initialized.
  */
 export declare function notificationBoxesFlaggedInvalidQuery(): FirestoreQueryConstraint[];
 /**
- * Query for notifications that are not done and the send at time is in the past.
+ * Query constraints for finding {@link Notification} documents that are ready to be sent
+ * (not done and `sat` is in the past).
+ *
+ * This is the primary query used by the send queue processor.
  *
- * @param now
- * @returns
+ * @param now - reference time for the `sat` comparison (defaults to current time)
  */
 export declare function notificationsPastSendAtTimeQuery(now?: Date): FirestoreQueryConstraint[];
 /**
- * Query for notifications that are marked ready for cleanup/deletion.
- *
- * @param now
- * @returns
+ * Query constraints for finding {@link Notification} documents marked as done (`d == true`)
+ * and ready to be archived to {@link NotificationWeek} and then deleted.
  */
 export declare function notificationsReadyForCleanupQuery(): FirestoreQueryConstraint[];

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

@@ -1,22 +1,55 @@
+/**
+ * @module notification.send
+ *
+ * Result types for notification delivery across each channel (email, text/SMS, in-app summary).
+ * These types are returned by the server's send pipeline and used to update {@link NotificationSendCheckpoints}
+ * for idempotent retry tracking.
+ */
 import { type Maybe, type EmailAddress, type E164PhoneNumber } from '@dereekb/util';
 import { type NotificationSummaryId } from './notification.id';
+/**
+ * Per-channel delivery result tracking which recipients succeeded, failed, or were ignored.
+ *
+ * - `success` — delivery confirmed for these recipients
+ * - `failed` — temporary failure; these recipients should be retried on the next send attempt
+ * - `ignored` — recipients that were skipped (e.g., invalid address, duplicate, opted out)
+ *
+ * @template K - recipient identifier type (email address, phone number, or summary ID)
+ */
 export interface NotificationSendMessagesResult<K> {
     /**
-     * Set of all successful recipients.
+     * Recipients where delivery succeeded.
      */
     readonly success: K[];
     /**
-     * Set of all failed recipients.
-     *
-     * A failed recipient is a valid recipient that failed due to a temporary error and should be retried again it the future.
+     * Recipients where delivery failed due to a temporary error. Will be retried on subsequent attempts.
      */
     readonly failed: K[];
     /**
-     * Set of all ignored recipients, if applicable..
+     * Recipients that were skipped (invalid, duplicate, or opted out).
      */
     readonly ignored: K[];
 }
+/**
+ * Merges two {@link NotificationSendMessagesResult} objects by concatenating their recipient lists.
+ *
+ * Used when combining results from multiple send batches within the same channel.
+ *
+ * @example
+ * ```ts
+ * const combined = mergeNotificationSendMessagesResult(firstBatchResult, secondBatchResult);
+ * ```
+ */
 export declare function mergeNotificationSendMessagesResult<K>(a: Maybe<NotificationSendMessagesResult<K>>, b: Maybe<NotificationSendMessagesResult<K>>): NotificationSendMessagesResult<K>;
+/**
+ * Email channel delivery result, keyed by recipient email address.
+ */
 export type NotificationSendEmailMessagesResult = NotificationSendMessagesResult<EmailAddress>;
+/**
+ * Text/SMS channel delivery result, keyed by recipient phone number in E.164 format.
+ */
 export type NotificationSendTextMessagesResult = NotificationSendMessagesResult<E164PhoneNumber>;
+/**
+ * In-app notification summary channel delivery result, keyed by {@link NotificationSummaryId}.
+ */
 export type NotificationSendNotificationSummaryMessagesResult = NotificationSendMessagesResult<NotificationSummaryId>;

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

@@ -1,9 +1,26 @@
+/**
+ * @module notification.task
+ *
+ * Checkpoint-based async task system built on top of the notification infrastructure.
+ *
+ * Task notifications use `NotificationSendType.TASK_NOTIFICATION` and run server-side async workflows
+ * with progress tracked via checkpoint strings. Each task handler returns a {@link NotificationTaskServiceHandleNotificationTaskResult}
+ * that tells the server whether the task is complete, partially done, failed, or should be delayed.
+ *
+ * Task lifecycle:
+ * 1. Task notification is created with a task type and optional checkpoint strings
+ * 2. Server picks it up via the send queue and routes to the registered handler
+ * 3. Handler returns a result indicating completion, partial progress, delay, or failure
+ * 4. Server updates the notification document accordingly and re-queues if not done
+ * 5. On completion (`true`), the notification document is deleted
+ */
 import { type NotificationItem, type NotificationItemMetadata } from './notification.item';
 import { type NotificationTaskType } from './notification.id';
 import { type NotificationDocument, type NotificationTaskCheckpointString } from './notification';
 import { type ArrayOrValue, type Maybe, type Milliseconds } from '@dereekb/util';
 /**
- * A NotificationTask is the final result of the expanded notification with a task type.
+ * Expanded task context passed to a task handler. Provides the notification document, item,
+ * and current checkpoint progress for the handler to make decisions.
  */
 export interface NotificationTask<D extends NotificationItemMetadata = {}> {
     /**
@@ -56,33 +73,84 @@ export interface NotificationTask<D extends NotificationItemMetadata = {}> {
     readonly unique: boolean;
 }
 /**
- * Returns an empty array, which is used to signal that the task did not fail but has not complete the current checkpoint.
+ * Returns an empty checkpoint array, signaling the task is not done but hasn't failed.
+ *
+ * Use this when the handler needs more time but doesn't want to increment the failure counter.
+ * The task will be re-queued without counting as an error attempt.
+ *
+ * @example
+ * ```ts
+ * // Waiting for an external process — delay without failing
+ * return { completion: delayCompletion(), delayUntil: 60000 };
+ * ```
  */
 export declare function delayCompletion<S extends NotificationTaskCheckpointString = NotificationTaskCheckpointString>(): NotificationTaskServiceTaskHandlerCompletionType<S>;
 /**
- * Convenience function for returning a NotificationTaskServiceHandleNotificationTaskResult that says the task should be retried after the specified delay.
+ * Returns a result that re-queues the task after a delay without incrementing the error counter.
+ *
+ * Use when the task needs to wait (e.g., for an external API to complete) but hasn't failed.
  *
- * This does not affect the failure/retry count for a notification task.
+ * @param delayUntil - absolute date or relative milliseconds from the task's run start time
+ * @param updateMetadata - optional metadata updates to merge into the notification item
+ *
+ * @example
+ * ```ts
+ * // Poll again in 30 seconds
+ * return notificationTaskDelayRetry(30000, { pollCount: task.data?.pollCount + 1 });
+ * ```
  */
 export declare function notificationTaskDelayRetry<D extends NotificationItemMetadata = {}, S extends NotificationTaskCheckpointString = NotificationTaskCheckpointString>(delayUntil: Date | Milliseconds, updateMetadata?: Maybe<Partial<D>>): NotificationTaskServiceHandleNotificationTaskResult<D, S>;
 /**
- * Convenience function for returning a NotificationTaskServiceHandleNotificationTaskResult that says the task was partially completed, and to process the next part in the future.
+ * Returns a result indicating one or more checkpoints completed, with more work remaining.
+ *
+ * The completed checkpoint strings are added to the notification's `tpr` set. The task is re-queued
+ * for the next checkpoint.
+ *
+ * @param completedParts - checkpoint string(s) that were just completed
+ * @param updateMetadata - optional metadata updates to merge into the notification item
+ *
+ * @example
+ * ```ts
+ * // Mark 'validate' checkpoint done, continue to 'process'
+ * return notificationTaskPartiallyComplete('validate');
+ * ```
  */
 export declare function notificationTaskPartiallyComplete<D extends NotificationItemMetadata = {}, S extends NotificationTaskCheckpointString = NotificationTaskCheckpointString>(completedParts: ArrayOrValue<S>, updateMetadata?: Maybe<Partial<D>>): NotificationTaskServiceHandleNotificationTaskResult<D, S>;
 /**
- * Convenience function for returning a NotificationTaskServiceHandleNotificationTaskResult that says the task was completed successfully.
+ * Returns a result indicating the task completed successfully. The notification document will be deleted.
+ *
+ * @param updateMetadata - optional final metadata update (applied before deletion if subtasks need it)
+ *
+ * @example
+ * ```ts
+ * // All done
+ * return notificationTaskComplete();
+ * ```
  */
 export declare function notificationTaskComplete<D extends NotificationItemMetadata = {}, S extends NotificationTaskCheckpointString = NotificationTaskCheckpointString>(updateMetadata?: Maybe<Partial<D>>): NotificationTaskServiceHandleNotificationTaskResult<D, S>;
 /**
- * Convenience function for returning a NotificationTaskServiceHandleNotificationTaskResult that says the task failed.
+ * Returns a result indicating the task failed. Increments the error attempt counter.
+ *
+ * After exceeding the maximum retry attempts, the task will be permanently deleted.
+ *
+ * @param updateMetadata - optional metadata updates
+ * @param removeFromCompletedCheckpoints - checkpoint(s) to remove from the completed set (e.g., to retry a checkpoint)
+ *
+ * @example
+ * ```ts
+ * // Task failed, retry with rolled-back checkpoint
+ * return notificationTaskFailed(undefined, 'process');
+ * ```
  */
 export declare function notificationTaskFailed<D extends NotificationItemMetadata = {}, S extends NotificationTaskCheckpointString = NotificationTaskCheckpointString>(updateMetadata?: Maybe<Partial<D>>, removeFromCompletedCheckpoints?: Maybe<ArrayOrValue<S>>): NotificationTaskServiceHandleNotificationTaskResult<D, S>;
 /**
- * Wraps an existing NotificationTaskServiceHandleNotificationTaskResult<D> and sets canRunNextCheckpoint to true if it is undefined.
+ * Wraps a task result to allow immediate execution of the next checkpoint within the same run.
  *
- * @param result The result to use as a template.
- * @param force If true, then canRunNextCheckpoint will be set to true even if it is already defined.
- * @returns A new result.
+ * By default, only sets `canRunNextCheckpoint` if it isn't already defined.
+ * Use `force: true` to override an existing value.
+ *
+ * @param result - the task result to wrap
+ * @param force - when true, overrides any existing `canRunNextCheckpoint` value
  */
 export declare function notificationTaskCanRunNextCheckpoint<D extends NotificationItemMetadata = {}, S extends NotificationTaskCheckpointString = NotificationTaskCheckpointString>(result: NotificationTaskServiceHandleNotificationTaskResult<D, S>, force?: Maybe<boolean>): NotificationTaskServiceHandleNotificationTaskResult<D, S>;
 /**
@@ -90,15 +158,18 @@ export declare function notificationTaskCanRunNextCheckpoint<D extends Notificat
  */
 export type NotificationTaskServiceTaskHandlerCompletionTypeCheckpoint<S extends NotificationTaskCheckpointString = NotificationTaskCheckpointString> = ArrayOrValue<S>;
 /**
- * Result type of a NotificationTaskServiceTaskHandler.handleNotificationTask() call.
+ * Completion status returned by a task handler:
  *
- * true: The task was completed successfully and can now be discarded.
- * false: The task was not completed successfully and should be retried again in the future. Note there are a maximum number of retry attempts before the task is deleted. Use delayCompletion() to avoid increasing the attempt count.
- * NotificationTaskCheckpointString(s): The task has successfully completed this/these particular checkpoint(s) but is not complete and should be continued again in the future. Return an empty array to signal that the task did not fail but has not reached the next checkpoint.
+ * - `true` — task completed successfully; notification document will be deleted
+ * - `false` — task failed; error counter incremented, re-queued for retry (up to max attempts)
+ * - `string | string[]` — checkpoint(s) completed; added to `tpr` set, task continues
+ * - `[]` (empty array) — task is in progress but no checkpoint reached; re-queued without error increment
  */
 export type NotificationTaskServiceTaskHandlerCompletionType<S extends NotificationTaskCheckpointString = NotificationTaskCheckpointString> = true | false | NotificationTaskServiceTaskHandlerCompletionTypeCheckpoint<S>;
 /**
- * Result of a NotificationTaskServiceTaskHandler.handleNotificationTask() call.
+ * Full result object returned by a task handler to the server-side task runner.
+ *
+ * Combines the completion status with optional metadata updates, delay scheduling, and checkpoint management.
  */
 export interface NotificationTaskServiceHandleNotificationTaskResult<D extends NotificationItemMetadata = {}, S extends NotificationTaskCheckpointString = NotificationTaskCheckpointString> {
     /**

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

@@ -1,37 +1,54 @@
+/**
+ * @module notification.task.subtask
+ *
+ * Subtask system for breaking complex notification tasks into "processing" and "cleanup" phases.
+ *
+ * A subtask wraps a notification task with two ordered checkpoints:
+ * 1. `'processing'` — the main work (e.g., external API calls, file generation)
+ * 2. `'cleanup'` — post-processing cleanup (e.g., updating related documents, deleting temporary files)
+ *
+ * Each subtask maintains its own checkpoint progress and metadata within the parent task's data payload.
+ */
 import { type Maybe } from '@dereekb/util';
 import { type NotificationTaskCheckpointString } from './notification';
 import { type NotificationItemMetadata } from './notification.item';
 import { type NotificationTaskServiceHandleNotificationTaskResult } from './notification.task';
 /**
- * Used as a descriminator to determine which processing configuration to run for the input value.
+ * Discriminator string that routes the subtask to the correct processing configuration.
  */
 export type NotificationTaskSubtaskTarget = string;
 /**
- * A subtask checkpoint.
- *
- * It is similar to NotificationTaskCheckpointString, but is stored within the subtask data.
+ * Checkpoint string for subtask-level progress, stored within the {@link NotificationTaskSubtaskData}.
  */
 export type NotificationTaskSubtaskCheckpointString = NotificationTaskCheckpointString;
 /**
- * Metadata for a subtask.
- *
- * It is similar to NotificationItemMetadata, but is stored within the subtask data.
+ * Metadata type for subtask-level state, stored within the {@link NotificationTaskSubtaskData}.
  */
 export type NotificationTaskSubtaskMetadata = NotificationItemMetadata;
 /**
- * A base NotificationTask's subtask data structure.
+ * Data structure embedded in the parent task's {@link NotificationItem} metadata to track subtask progress.
+ *
+ * Field abbreviations:
+ * - `sfps` — subtask finished processing steps (completed checkpoint strings)
+ * - `sd` — subtask data (arbitrary metadata for the subtask handler)
  */
 export interface NotificationTaskSubtaskData<M extends NotificationTaskSubtaskMetadata = NotificationTaskSubtaskMetadata, S extends NotificationTaskSubtaskCheckpointString = NotificationTaskSubtaskCheckpointString> {
     /**
-     * The steps of the underlying subtask that have already been completed.
+     * Completed subtask checkpoint strings.
      */
     readonly sfps?: Maybe<S[]>;
     /**
-     * Arbitrary metadata that is stored by the underlying subtask.
+     * Arbitrary metadata managed by the subtask handler.
      */
     readonly sd?: Maybe<M>;
 }
+/**
+ * Checkpoint string for the main processing phase of a subtask.
+ */
 export declare const NOTIFICATION_TASK_SUBTASK_CHECKPOINT_PROCESSING: NotificationTaskCheckpointString;
+/**
+ * Checkpoint string for the cleanup phase that runs after processing completes.
+ */
 export declare const NOTIFICATION_TASK_SUBTASK_CHECKPOINT_CLEANUP: NotificationTaskCheckpointString;
 /**
  * The maximum number of times to delay the cleanup step of a StorageFileProcessingNotificationTask.
@@ -51,12 +68,24 @@ export declare const DEFAULT_NOTIFICATION_TASK_SUBTASK_CLEANUP_RETRY_DELAY: numb
  */
 export type NotificationTaskSubtaskCheckpoint = typeof NOTIFICATION_TASK_SUBTASK_CHECKPOINT_PROCESSING | typeof NOTIFICATION_TASK_SUBTASK_CHECKPOINT_CLEANUP;
 /**
- * Returned by a subtask to complete the processing step and schedule the cleanup step.
+ * Internal helper that marks the `'processing'` checkpoint complete and schedules the `'cleanup'` phase.
  *
- * This is used internally in subtask running. Do not use this directly. Use of notificationSubtaskComplete() is preferred.
+ * Prefer using {@link notificationSubtaskComplete} in subtask handlers instead of calling this directly.
  */
 export declare function completeSubtaskProcessingAndScheduleCleanupTaskResult<D extends NotificationTaskSubtaskData>(): NotificationTaskServiceHandleNotificationTaskResult<D, NotificationTaskSubtaskCheckpoint>;
 /**
- * Similar to notificationTaskComplete, but is customized for a subtask with the intent of running the cleanup checkpoint.
+ * Returns a completion result for a subtask that has finished its processing.
+ *
+ * Unlike {@link notificationTaskComplete}, this signals that the cleanup checkpoint should still run.
+ * Use `canRunNextCheckpoint: true` in options to run cleanup immediately in the same execution.
+ *
+ * @example
+ * ```ts
+ * // Processing done, schedule cleanup for next run
+ * return notificationSubtaskComplete();
+ *
+ * // Processing done, run cleanup immediately
+ * return notificationSubtaskComplete({ canRunNextCheckpoint: true });
+ * ```
  */
 export declare function notificationSubtaskComplete<D extends NotificationTaskSubtaskData>(options?: Maybe<Pick<NotificationTaskServiceHandleNotificationTaskResult<D, NotificationTaskSubtaskCheckpoint>, 'updateMetadata' | 'canRunNextCheckpoint'>>): NotificationTaskServiceHandleNotificationTaskResult<D, NotificationTaskSubtaskCheckpoint>;

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

@@ -1,9 +1,19 @@
+/**
+ * @module notification.util
+ *
+ * Server-side utility functions for notification config resolution, exclusion management,
+ * send state evaluation, and recipient merging.
+ */
 import { type ArrayOrValue, type Maybe } from '@dereekb/util';
 import { type Notification, type NotificationBox, type NotificationBoxDocument, NotificationRecipientSendFlag, type NotificationSendFlags, NotificationSendState, type NotificationUser } from './notification';
 import { type NotificationUserNotificationBoxRecipientConfig, type NotificationBoxRecipient, type NotificationUserDefaultNotificationBoxRecipientConfig } from './notification.config';
 import { type AppNotificationTemplateTypeInfoRecordService } from './notification.details';
 import { type FirebaseAuthUserId, type FirestoreDocumentAccessor, type FirestoreModelKey } from '../../common';
 import { type NotificationBoxId, type NotificationId, type NotificationBoxSendExclusionList, type NotificationBoxSendExclusion } from './notification.id';
+/**
+ * Input for computing the effective {@link NotificationBoxRecipient} by merging the 3-level config hierarchy:
+ * recipient entry → user's per-box config → user's global config.
+ */
 export interface EffectiveNotificationBoxRecipientConfigInput {
     readonly uid: FirebaseAuthUserId;
     readonly m?: FirestoreModelKey;
@@ -12,7 +22,17 @@ export interface EffectiveNotificationBoxRecipientConfigInput {
     readonly boxConfig: NotificationUserNotificationBoxRecipientConfig;
     readonly recipient?: Maybe<NotificationBoxRecipient>;
 }
+/**
+ * Computes the effective {@link NotificationBoxRecipient} by merging configs from highest to lowest priority:
+ * global config (`gc`) → per-box user config (`boxConfig`) → existing box recipient.
+ *
+ * Filters template configs to only include types applicable to the notification box's model.
+ * Used during the server-side sync process to update box recipient entries from user configs.
+ */
 export declare function effectiveNotificationBoxRecipientConfig(input: EffectiveNotificationBoxRecipientConfigInput): NotificationBoxRecipient;
+/**
+ * Input for adding/removing send exclusions on a {@link NotificationUser}.
+ */
 export interface UpdateNotificationUserNotificationSendExclusionsInput {
     readonly notificationUser: Pick<NotificationUser, 'b' | 'x' | 'bc'>;
     readonly addExclusions?: ArrayOrValue<NotificationBoxSendExclusion>;
@@ -22,7 +42,16 @@ export interface UpdateNotificationUserNotificationSendExclusionsResult {
     readonly nextExclusions: NotificationBoxSendExclusionList;
     readonly update: Pick<NotificationUser, 'x' | 'ns' | 'bc'>;
 }
+/**
+ * Adds and/or removes send exclusions from a {@link NotificationUser}, validates them against associated boxes,
+ * and propagates exclusion flags to the per-box configs.
+ *
+ * Exclusions not matching any associated notification box are automatically filtered out.
+ */
 export declare function updateNotificationUserNotificationSendExclusions(input: UpdateNotificationUserNotificationSendExclusionsInput): UpdateNotificationUserNotificationSendExclusionsResult;
+/**
+ * Input for applying exclusion flags to per-box configs, updating the `x` and `ns` fields on each config.
+ */
 export interface ApplyExclusionsToNotificationUserNotificationBoxRecipientConfigsParams {
     readonly x?: NotificationBoxSendExclusionList;
     readonly bc?: Maybe<NotificationUserNotificationBoxRecipientConfig[]>;
@@ -30,52 +59,68 @@ export interface ApplyExclusionsToNotificationUserNotificationBoxRecipientConfig
     readonly recalculateNs?: boolean;
 }
 export type ApplyExclusionsToNotificationUserNotificationBoxRecipientConfigsResult = Pick<NotificationUser, 'bc' | 'ns'>;
+/**
+ * Applies the current exclusion list to per-box configs, setting/clearing the `x` flag and marking
+ * changed configs as needing sync (`ns = true`).
+ */
 export declare function applyExclusionsToNotificationUserNotificationBoxRecipientConfigs(params: ApplyExclusionsToNotificationUserNotificationBoxRecipientConfigsParams): ApplyExclusionsToNotificationUserNotificationBoxRecipientConfigsResult;
+/**
+ * Returns true if any of the per-box configs need syncing (`ns == true`).
+ */
 export declare function calculateNsForNotificationUserNotificationBoxRecipientConfigs(configs: NotificationUserNotificationBoxRecipientConfig[]): boolean;
 /**
- * Function that returns true if the notification is not excluded from being sent.
+ * Predicate function that returns true if the given notification/box ID is NOT excluded from delivery.
+ * Uses prefix matching against the exclusion list.
  */
 export type NotificationSendExclusionCanSendFunction = ((notification: NotificationId | NotificationBoxId) => boolean) & {
     readonly _exclusions: NotificationBoxSendExclusionList;
 };
+/**
+ * Creates a {@link NotificationSendExclusionCanSendFunction} from the given exclusion list.
+ * Returns true for IDs that don't match any exclusion prefix.
+ */
 export declare const notificationSendExclusionCanSendFunction: (exclusions: NotificationBoxSendExclusionList) => NotificationSendExclusionCanSendFunction;
 /**
- * Returns true if the notification's send types are all marked as sent.
- *
- * @param input
- * @returns
+ * Returns true if all channels on the notification have reached a terminal state
+ * (NONE, NO_TRY, SENT, or SKIPPED). Used to determine if the notification can be marked done.
  */
 export declare function notificationSendFlagsImplyIsComplete(input: NotificationSendFlags): boolean;
 /**
- * Returns true if the state implies completion of sending (not necessarily success, but that attempts to send are done)
- *
- * @param input
- * @returns
+ * Returns true if the given send state is terminal — no further send attempts will be made.
+ * Terminal states: NONE, NO_TRY, SENT, SKIPPED.
  */
 export declare function isCompleteNotificationSendState(input: NotificationSendState): boolean;
+/**
+ * Resolved recipient group flags based on a {@link NotificationRecipientSendFlag}.
+ */
 export interface AllowedNotificationRecipients {
     readonly canSendToGlobalRecipients: boolean;
     readonly canSendToBoxRecipients: boolean;
     readonly canSendToExplicitRecipients: boolean;
 }
 /**
- * Returns a AllowedNotificationRecipients from the input NotificationRecipientSendFlag.
- *
- * @param flag
- * @returns
+ * Resolves which recipient groups (global, box, explicit) are allowed based on the {@link NotificationRecipientSendFlag}.
  */
 export declare function allowedNotificationRecipients(flag?: Maybe<NotificationRecipientSendFlag>): AllowedNotificationRecipients;
 /**
- * Whether or not the Notification should be saved to the NotificationWeek.
- *
- * A Notification should only be saved when the notification can be sent to box recipients.
+ * Returns true if the notification should be archived to a {@link NotificationWeek} after delivery.
  *
- * @param notification
- * @returns
+ * Only notifications that can be sent to box recipients are archived (notifications restricted
+ * to only explicit or only global recipients are not saved to the weekly archive).
  */
 export declare function shouldSaveNotificationToNotificationWeek(notification: Notification): boolean;
+/**
+ * Merges a partial update into a {@link NotificationUserNotificationBoxRecipientConfig},
+ * preserving user-controlled fields (`nb`, `rm`, `ns`, `lk`, `bk`) and respecting OPT_OUT state.
+ */
 export declare function mergeNotificationUserNotificationBoxRecipientConfigs(a: NotificationUserNotificationBoxRecipientConfig, b: Partial<NotificationUserNotificationBoxRecipientConfig>): NotificationUserNotificationBoxRecipientConfig;
+/**
+ * Merges a partial update into a {@link NotificationBoxRecipient}, deeply merging the `c` (config record) field.
+ */
 export declare function mergeNotificationBoxRecipients<T extends NotificationBoxRecipient>(a: T, b: Partial<T>): T;
+/**
+ * Input for resolving a {@link NotificationBoxDocument}, either directly or by computing its ID from a model key.
+ */
 export interface NotificationBoxDocumentReferencePair {
     /**
      * NotificationBoxDocument to update.
@@ -88,4 +133,9 @@ export interface NotificationBoxDocumentReferencePair {
      */
     readonly notificationBoxRelatedModelKey?: Maybe<FirestoreModelKey>;
 }
+/**
+ * Resolves a {@link NotificationBoxDocument} from a reference pair, loading by model key if no document is provided directly.
+ *
+ * @throws {Error} When neither a document nor a model key is provided.
+ */
 export declare function loadNotificationBoxDocumentForReferencePair(input: NotificationBoxDocumentReferencePair, accessor: FirestoreDocumentAccessor<NotificationBox, NotificationBoxDocument>): NotificationBoxDocument;

package/src/lib/model/oidcmodel/index.d.ts

@@ -0,0 +1,8 @@
+export * from './oidcmodel';
+export * from './oidcmodel.id';
+export * from './oidcmodel.query';
+export * from './oidcmodel.api';
+export * from './oidcmodel.action';
+export * from './oidcmodel.data';
+export * from './oidcmodel.interaction';
+export * from './oidcmodel.interaction.oauth';

package/src/lib/model/oidcmodel/oidcmodel.action.d.ts

@@ -0,0 +1,37 @@
+import { type AsyncFirebaseFunctionDeleteAction, type FirebaseFunctionDeleteAction, type AsyncFirebaseFunctionCreateAction, type AsyncFirebaseFunctionUpdateAction, type FirebaseFunctionCreateAction, type FirebaseFunctionUpdateAction } from '../../common';
+import { type OidcEntryDocument } from './oidcmodel';
+/**
+ * @module oidcmodel.action
+ *
+ * Type aliases for OidcEntry server action functions.
+ *
+ * These connect API parameter types to their target document types, following the same
+ * pattern as storagefile actions. See `@dereekb/firebase-server/oidc` for the
+ * server-side action service implementations.
+ *
+ * @template P - the API parameter type for the action
+ */
+/**
+ * Synchronous create action targeting an {@link OidcEntryDocument}.
+ */
+export type OidcEntryCreateAction<P extends object> = FirebaseFunctionCreateAction<P, OidcEntryDocument>;
+/**
+ * Async create action targeting an {@link OidcEntryDocument}.
+ */
+export type AsyncOidcEntryCreateAction<P extends object> = AsyncFirebaseFunctionCreateAction<P, OidcEntryDocument>;
+/**
+ * Synchronous update action targeting an {@link OidcEntryDocument}.
+ */
+export type OidcEntryUpdateAction<P extends object> = FirebaseFunctionUpdateAction<P, OidcEntryDocument>;
+/**
+ * Async update action targeting an {@link OidcEntryDocument}.
+ */
+export type AsyncOidcEntryUpdateAction<P extends object> = AsyncFirebaseFunctionUpdateAction<P, OidcEntryDocument>;
+/**
+ * Synchronous delete action targeting an {@link OidcEntryDocument}.
+ */
+export type OidcEntryDeleteAction<P extends object> = FirebaseFunctionDeleteAction<P, OidcEntryDocument>;
+/**
+ * Async delete action targeting an {@link OidcEntryDocument}.
+ */
+export type AsyncOidcEntryDeleteAction<P extends object> = AsyncFirebaseFunctionDeleteAction<P, OidcEntryDocument>;