@dereekb/firebase 12.3.11 → 12.3.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dereekb/firebase",
-  "version": "12.3.11",
+  "version": "12.3.13",
   "exports": {
     ".": {
       "types": "./src/index.d.ts",

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

@@ -211,6 +211,15 @@ export declare class UpdateNotificationBoxRecipientParams extends UpdateNotifica
      * Whether or not to remove the user if they exist. Defaults to false.
      */
     remove?: Maybe<boolean>;
+    /**
+     * If true, the target recipient will have this NotificationBox added to their exclusion list.
+     * If false, the target recipient will have this NotificationBox removed from their exclusion list.
+     *
+     * If set, the other functions are ignored.
+     *
+     * If targeting the user by the index, the NotificationBox must exist, and the user must have a uid, otherwise an error will be thrown.
+     */
+    setExclusion?: Maybe<boolean>;
 }
 export declare class NotificationRecipientParams {
     /**
@@ -258,6 +267,16 @@ export declare abstract class AbstractSubscribeOrUnsubscribeToNotificationBoxPar
      */
     unsubscribe?: Maybe<boolean>;
 }
+export interface SendNotificationResultOnSendCompleteResult<T = unknown> {
+    /**
+     * Value, if returned by the onSendSuccess callback.
+     */
+    readonly value?: T;
+    /**
+     * Error value if the onSendSuccess callback throws an error.
+     */
+    readonly error?: Maybe<unknown>;
+}
 export interface SendNotificationResult {
     /**
      * Attempted notification type
@@ -348,6 +367,14 @@ export interface SendNotificationResult {
      * Failed while attempting to build a message
      */
     readonly buildMessageFailure: boolean;
+    /**
+     * Result of the onSendAttempted callback, if called.
+     */
+    readonly onSendAttemptedResult?: Maybe<SendNotificationResultOnSendCompleteResult>;
+    /**
+     * Result of the onSendSuccess callback, if called.
+     */
+    readonly onSendSuccessResult?: Maybe<SendNotificationResultOnSendCompleteResult>;
 }
 /**
  * Used for sending queued notifications in the system.

package/src/lib/model/notification/notification.api.error.d.ts

@@ -3,6 +3,7 @@ export declare const NOTIFICATION_MODEL_ALREADY_INITIALIZED_ERROR_CODE = "NOTIFI
 export declare const NOTIFICATION_BOX_DOES_NOT_EXIST_ERROR_CODE = "NOTIFICATION_BOX_DOES_NOT_EXIST";
 export declare const NOTIFICATION_BOX_EXISTS_FOR_MODEL_ERROR_CODE = "NOTIFICATION_BOX_EXISTS_FOR_MODEL";
 export declare const NOTIFICATION_BOX_RECIPIENT_DOES_NOT_EXIST_ERROR_CODE = "NOTIFICATION_BOX_RECIPIENT_DOES_NOT_EXIST";
+export declare const NOTIFICATION_BOX_EXCLUSION_TARGET_INVALID_ERROR_CODE = "NOTIFICATION_BOX_EXCLUSION_TARGET_INVALID";
 export declare const NOTIFICATION_USER_INVALID_UID_FOR_CREATE_ERROR_CODE = "NOTIFICATION_USER_INVALID_UID_FOR_CREATE";
 export declare const NOTIFICATION_USER_BLOCKED_FROM_BEING_ADD_TO_RECIPIENTS_ERROR_CODE = "NOTIFICATION_USER_BLOCKED_FROM_BEING_ADD_TO_RECIPIENTS";
 export declare const NOTIFICATION_USER_LOCKED_CONFIG_FROM_BEING_UPDATED_ERROR_CODE = "NOTIFICATION_USER_LOCKED_CONFIG_FROM_BEING_UPDATED";

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

@@ -29,7 +29,7 @@ export interface NotificationBoxRecipientTemplateConfig {
     sn?: Maybe<boolean>;
 }
 export declare function mergeNotificationBoxRecipientTemplateConfigs(a?: Maybe<NotificationBoxRecipientTemplateConfig>, b?: Maybe<NotificationBoxRecipientTemplateConfig>): NotificationBoxRecipientTemplateConfig;
-export declare function effectiveNotificationBoxRecipientTemplateConfig(x: NotificationBoxRecipientTemplateConfig): NotificationBoxRecipientTemplateConfig;
+export declare function effectiveNotificationBoxRecipientTemplateConfig(a: NotificationBoxRecipientTemplateConfig): NotificationBoxRecipientTemplateConfig;
 /**
  * Recipient configuration for a notification
  */
@@ -83,6 +83,12 @@ export declare enum NotificationBoxRecipientFlag {
  * If uid is set, then most other NotificationRecipient fields are ignored as those are pulled from auth.
  */
 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.
+     */
+    x?: Maybe<SavedToFirestoreIfTrue>;
     /**
      * Enabled config types
      */
@@ -104,7 +110,7 @@ export declare function newNotificationBoxRecipientForUid(uid: FirebaseAuthUserI
 /**
  * Default NotificationUserNotificationBoxRecipientConfig.
  */
-export interface NotificationUserDefaultNotificationBoxRecipientConfig extends Omit<NotificationBoxRecipient, 'i' | 'n' | 's' | 'uid'> {
+export interface NotificationUserDefaultNotificationBoxRecipientConfig extends Omit<NotificationBoxRecipient, 'i' | 'n' | 's' | 'uid' | 'x'> {
     /**
      * Locked state.
      *

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

@@ -1,6 +1,6 @@
 import { type E164PhoneNumber, type EmailAddress, type Maybe, type NeedsSyncBoolean } from '@dereekb/util';
 import { type GrantedReadRole, type GrantedUpdateRole } from '@dereekb/model';
-import { type NotificationBoxId } from './notification.id';
+import { NotificationBoxSendExclusionList, type NotificationBoxId } from './notification.id';
 import { type NotificationBoxRecipient, type NotificationRecipientWithConfig, type NotificationUserNotificationBoxRecipientConfig, type NotificationUserDefaultNotificationBoxRecipientConfig } from './notification.config';
 import { type YearWeekCode } from '@dereekb/date';
 import { type UserRelatedById, type UserRelated } from '../user';
@@ -48,6 +48,18 @@ export interface NotificationUser extends UserRelated, UserRelatedById {
      * List of notification boxes this user is associated with. Cannot be changed directly.
      */
     b: NotificationBoxId[];
+    /**
+     * Notification box id exclusion list. This value is treated used to generated send opt-outs.
+     *
+     * This list is used to exclude a user from recieving notifications from the NotificationBoxes in this list.
+     *
+     * Values in this list are usually populated from functions from the model controlling the NotificationBox.
+     *
+     * The user must be associated with atleast one NotificationBoxId that matches items in this list, otherwise non-matching items are removed.
+     *
+     * The exclusions are sync'd to the corresponding bc values, which are then sync'd to the NotificationBoxes.
+     */
+    x: NotificationBoxSendExclusionList;
     /**
      * Global config override.
      *

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

@@ -1,10 +1,22 @@
 import { type FactoryWithRequiredInput } from '@dereekb/util';
-import { type FirestoreModelId, type FirestoreModelKey, type FlatFirestoreModelKey, twoWayFlatFirestoreModelKey, inferKeyFromTwoWayFlatFirestoreModelKey, type FirebaseAuthUserId, type RootFirestoreModelIdentity, FirestoreModelIdInput } from '../../common';
+import { type FirestoreModelId, type FirestoreModelKey, type FlatFirestoreModelKey, twoWayFlatFirestoreModelKey, inferKeyFromTwoWayFlatFirestoreModelKey, type FirebaseAuthUserId, type RootFirestoreModelIdentity, FirestoreModelIdInput, FirestoreCollectionName } from '../../common';
 /**
  * The NotificationBox's id is the two way flat firestore model key of the object that it represents.
  */
 export type NotificationBoxId = FlatFirestoreModelKey;
 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.
+ *
+ * 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.
+ *
+ * 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.
+ */
+export type NotificationBoxSendExclusion = FirestoreCollectionName | NotificationBoxId;
+/**
+ * List of notification box exclusions.
+ */
+export type NotificationBoxSendExclusionList = NotificationBoxSendExclusion[];
 /**
  * Creates a NotificationBoxId from the input FirestoreModelKey.
  *

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

@@ -1,8 +1,9 @@
-import { type Maybe, type WebsiteUrl } from '@dereekb/util';
+import { PromiseOrValue, type Maybe, type WebsiteUrl } from '@dereekb/util';
 import { type NotificationRecipient, type NotificationRecipientWithConfig } from './notification.config';
-import { type Notification, type NotificationBox } from './notification';
+import { NotificationSendFlags, type Notification, type NotificationBox } from './notification';
 import { type NotificationItem, type NotificationItemMetadata } from './notification.item';
 import { type DocumentDataWithIdAndKey } from '../../common';
+import { NotificationSendEmailMessagesResult, NotificationSendTextMessagesResult, NotificationSendNotificationSummaryMessagesResult } from './notification.send';
 /**
  * Contextual information when
  */
@@ -130,11 +131,27 @@ export interface NotificationMessageFunctionFactoryConfig<D extends Notification
  * Creates a NotificationMessageFunction from the input config.
  */
 export type NotificationMessageFunctionFactory<D extends NotificationItemMetadata = {}> = (config: NotificationMessageFunctionFactoryConfig<D>) => Promise<NotificationMessageFunction>;
+export interface NotificationMessageFunctionExtrasCallbackDetails {
+    readonly success: boolean;
+    readonly updatedSendFlags: NotificationSendFlags;
+    readonly sendEmailsResult?: Maybe<NotificationSendEmailMessagesResult>;
+    readonly sendTextsResult?: Maybe<NotificationSendTextMessagesResult>;
+    readonly sendNotificationSummaryResult?: Maybe<NotificationSendNotificationSummaryMessagesResult>;
+}
+export type NotificationMessageFunctionExtrasCallbackFunction = (callbackDetails: NotificationMessageFunctionExtrasCallbackDetails) => PromiseOrValue<unknown>;
 export interface NotificationMessageFunctionExtras {
     /**
      * Any global/additional recipient(s) that should be added to all Notifications associated with this NotificationMessageFunctionExtras.
      */
     readonly globalRecipients?: Maybe<NotificationRecipientWithConfig[]>;
+    /**
+     * Called each time the notification attempts to send something.
+     */
+    readonly onSendAttempted?: NotificationMessageFunctionExtrasCallbackFunction;
+    /**
+     * Called when the notification has is marked as done after sending to all recipients.
+     */
+    readonly onSendSuccess?: NotificationMessageFunctionExtrasCallbackFunction;
 }
 export type NotificationMessageFunctionWithoutExtras = (inputContext: NotificationMessageInputContext) => Promise<NotificationMessage>;
 /**

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

@@ -1,4 +1,6 @@
 import { type FirestoreQueryConstraint } from '../../common/firestore';
+import { NotificationBoxSendExclusion } from './notification.id';
+import { type ArrayOrValue } from '@dereekb/util';
 /**
  * Query for notificationUsers that are flagged for initialization.
  *
@@ -6,6 +8,13 @@ import { type FirestoreQueryConstraint } from '../../common/firestore';
  * @returns
  */
 export declare function notificationUsersFlaggedForNeedsSyncQuery(): FirestoreQueryConstraint[];
+/**
+ * Query for notificationUsers that have excluded any of the input notification box ids.
+ *
+ * @param now
+ * @returns
+ */
+export declare function notificationUserHasExclusionQuery(exclusionId: ArrayOrValue<NotificationBoxSendExclusion>): FirestoreQueryConstraint[];
 /**
  * Query for notificationSummaries that are flagged for initialization.
  *

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

@@ -1,8 +1,9 @@
-import { type Maybe } from '@dereekb/util';
-import { type Notification, type NotificationBox, type NotificationBoxDocument, NotificationRecipientSendFlag, type NotificationSendFlags, NotificationSendState } from './notification';
+import { ArrayOrValue, type Maybe } from '@dereekb/util';
+import { type Notification, type NotificationBox, type NotificationBoxDocument, NotificationRecipientSendFlag, type NotificationSendFlags, NotificationSendState, 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 { NotificationBoxId, NotificationId, NotificationBoxSendExclusionList, NotificationBoxSendExclusion } from './notification.id';
 export interface EffectiveNotificationBoxRecipientConfigInput {
     readonly uid: FirebaseAuthUserId;
     readonly m?: FirestoreModelKey;
@@ -12,6 +13,32 @@ export interface EffectiveNotificationBoxRecipientConfigInput {
     readonly recipient?: Maybe<NotificationBoxRecipient>;
 }
 export declare function effectiveNotificationBoxRecipientConfig(input: EffectiveNotificationBoxRecipientConfigInput): NotificationBoxRecipient;
+export interface UpdateNotificationUserNotificationSendExclusionsInput {
+    readonly notificationUser: Pick<NotificationUser, 'b' | 'x' | 'bc'>;
+    readonly addExclusions?: ArrayOrValue<NotificationBoxSendExclusion>;
+    readonly removeExclusions?: ArrayOrValue<NotificationBoxSendExclusion>;
+}
+export interface UpdateNotificationUserNotificationSendExclusionsResult {
+    readonly nextExclusions: NotificationBoxSendExclusionList;
+    readonly update: Pick<NotificationUser, 'x' | 'ns' | 'bc'>;
+}
+export declare function updateNotificationUserNotificationSendExclusions(input: UpdateNotificationUserNotificationSendExclusionsInput): UpdateNotificationUserNotificationSendExclusionsResult;
+export interface ApplyExclusionsToNotificationUserNotificationBoxRecipientConfigsParams {
+    readonly x?: NotificationBoxSendExclusionList;
+    readonly bc?: Maybe<NotificationUserNotificationBoxRecipientConfig[]>;
+    readonly notificationUser?: Pick<NotificationUser, 'bc' | 'x'>;
+    readonly recalculateNs?: boolean;
+}
+export type ApplyExclusionsToNotificationUserNotificationBoxRecipientConfigsResult = Pick<NotificationUser, 'bc' | 'ns'>;
+export declare function applyExclusionsToNotificationUserNotificationBoxRecipientConfigs(params: ApplyExclusionsToNotificationUserNotificationBoxRecipientConfigsParams): ApplyExclusionsToNotificationUserNotificationBoxRecipientConfigsResult;
+export declare function calculateNsForNotificationUserNotificationBoxRecipientConfigs(configs: NotificationUserNotificationBoxRecipientConfig[]): boolean;
+/**
+ * Function that returns true if the notification is not excluded from being sent.
+ */
+export type NotificationSendExclusionCanSendFunction = ((notification: NotificationId | NotificationBoxId) => boolean) & {
+    readonly _exclusions: NotificationBoxSendExclusionList;
+};
+export declare const notificationSendExclusionCanSendFunction: (exclusions: NotificationBoxSendExclusionList) => NotificationSendExclusionCanSendFunction;
 /**
  * Returns true if the notification's send types are all marked as sent.
  *

package/test/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 This file was generated using [@jscutlery/semver](https://github.com/jscutlery/semver).
 
+## [12.3.13](https://github.com/dereekb/dbx-components/compare/v12.3.12-dev...v12.3.13) (2025-08-22)
+
+
+
+## [12.3.12](https://github.com/dereekb/dbx-components/compare/v12.3.11-dev...v12.3.12) (2025-08-20)
+
+
+
 ## [12.3.11](https://github.com/dereekb/dbx-components/compare/v12.3.10-dev...v12.3.11) (2025-08-19)
 
 

package/test/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dereekb/firebase/test",
-  "version": "12.3.11",
+  "version": "12.3.13",
   "type": "commonjs",
   "peerDependencies": {
     "@dereekb/util": "*",