@dereekb/firebase 13.31.0 → 13.32.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dereekb/firebase",
-  "version": "13.31.0",
+  "version": "13.32.0",
   "sideEffects": false,
   "exports": {
     "./test": {
@@ -24,10 +24,10 @@
     }
   },
   "peerDependencies": {
-    "@dereekb/date": "13.31.0",
-    "@dereekb/model": "13.31.0",
-    "@dereekb/rxjs": "13.31.0",
-    "@dereekb/util": "13.31.0",
+    "@dereekb/date": "13.32.0",
+    "@dereekb/model": "13.32.0",
+    "@dereekb/rxjs": "13.32.0",
+    "@dereekb/util": "13.32.0",
     "@firebase/rules-unit-testing": "5.0.0",
     "@marcbachmann/cel-js": "^7.6.1",
     "@typescript-eslint/parser": "8.59.3",

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

@@ -9,6 +9,8 @@ export * from './notification.create.loggedevent';
 export * from './notification.loggedevent.loader';
 export * from './notification.create.task';
 export * from './notification.details';
+export * from './notification.healthcheck';
+export * from './notification.healthcheck.mailgun';
 export * from './notification.item';
 export * from './notification.id';
 export * from './notification.message';

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

@@ -13,6 +13,7 @@ import { type E164PhoneNumber, type EmailAddress, type IndexNumber, type Maybe }
 import { type NotificationTypes } from './notification';
 import { type NotificationUserDefaultNotificationBoxRecipientConfig, type NotificationBoxRecipientTemplateConfigArrayEntry, NotificationBoxRecipientFlag } from './notification.config';
 import { type NotificationBoxId, type NotificationSummaryId, type NotificationTemplateType } from './notification.id';
+import { type NotificationHealthCheck, NotificationDeliveryMethod } from './notification.healthcheck';
 import { type NotificationSendEmailMessagesResult, type NotificationSendTextMessagesResult, type NotificationSendNotificationSummaryMessagesResult } from './notification.send';
 import { type NotificationTaskServiceTaskHandlerCompletionType } from './notification.task';
 export declare const NOTIFICATION_RECIPIENT_NAME_MIN_LENGTH = 0;
@@ -95,6 +96,101 @@ export { targetModelParamsType as resyncNotificationUserParamsType } from '../..
 export interface ResyncNotificationUserResult {
     readonly notificationBoxesUpdated: number;
 }
+/**
+ * Used for running a notification delivery health check for a user.
+ *
+ * The check always inspects the user's configuration, their notification box subscriptions, and whatever
+ * read-only diagnostics each configured delivery method's send service offers. Actually dispatching a
+ * test message is opt-in via `sendProbe`, since that delivers real mail/SMS to the user.
+ */
+export interface NotificationUserHealthCheckParams extends TargetModelParams {
+    /**
+     * Restrict the check to these delivery methods. Defaults to every method the server has a send
+     * service configured for.
+     */
+    readonly methods?: Maybe<NotificationDeliveryMethod[]>;
+    /**
+     * Dispatch a real test message through each checked method that supports probing.
+     *
+     * Defaults to false. Delivery confirmation is asynchronous, so a dispatched probe is usually still
+     * pending when the check returns and is resolved by a later {@link verifyPendingProbesOnly} run.
+     */
+    readonly sendProbe?: Maybe<boolean>;
+    /**
+     * Only resolve probes left pending by the previous check, skipping the configuration, history, and
+     * provider diagnostics.
+     *
+     * Defaults to false. This is the POLL that settles an in-flight test message, and it is deliberately
+     * cheap enough to be called repeatedly: it consults a provider only for a method that actually has a
+     * probe in flight, and touches nothing else. It answers to its own short window rather than the run
+     * window, and advances the stored check's `vat` rather than its `at`, so polling a test message never
+     * consumes the user's allowance for running the check itself.
+     */
+    readonly verifyPendingProbesOnly?: Maybe<boolean>;
+    /**
+     * The notification template type to evaluate per-template configuration against.
+     *
+     * Defaults to the app's default template type.
+     */
+    readonly notificationTemplateType?: Maybe<NotificationTemplateType>;
+    /**
+     * Skip inspecting the user's notification box subscriptions.
+     *
+     * Defaults to false. Skipping avoids a document read per subscription, at the cost of not detecting
+     * a subscription that is broken, still being set up, or out of sync with the user's settings.
+     */
+    readonly skipSubscriptionChecks?: Maybe<boolean>;
+    /**
+     * Ignore the run and test message throttle windows.
+     *
+     * PRIVILEGED — admin only. The windows exist to stop a user from repeatedly hammering the delivery
+     * providers and their own inbox, so this must never be honoured for an ordinary caller. The action
+     * itself cannot tell who is calling, so the API layer that can is responsible for clearing this
+     * before the params reach it:
+     *
+     * ```ts
+     * const params = isAdminInRequest(request) ? data : { ...data, force: undefined };
+     * ```
+     *
+     * Defaults to false.
+     */
+    readonly force?: Maybe<boolean>;
+    /**
+     * Return the complete health check rather than just the part the call was about.
+     *
+     * A `sendProbe` call is about one delivery method's test message, so by default its result carries only
+     * the methods it actually probed — the caller already has the rest, and a client rendering the report
+     * reads it from the {@link NotificationUser} document instead. Set this to get the whole check back.
+     *
+     * Defaults to false. Has no effect on a plain run, which always returns everything, and never affects
+     * what is persisted: the stored check is always the complete picture.
+     */
+    readonly returnFullHealthCheck?: Maybe<boolean>;
+}
+export declare const notificationUserHealthCheckParamsType: Type<NotificationUserHealthCheckParams>;
+/**
+ * The result of a `healthCheck` invocation.
+ */
+export interface NotificationUserHealthCheckResult {
+    /**
+     * The health check that was produced.
+     *
+     * The COMPLETE check is always persisted to the {@link NotificationUser}'s `hc` field. What comes back
+     * here can be narrower: a `sendProbe` call is about one delivery method's test message, so unless
+     * `returnFullHealthCheck` was set its result carries only the methods that were actually probed, with
+     * `s` rolled up over just those and the account-wide findings left out. Read the document for the
+     * whole picture — see {@link NotificationUserHealthCheckParams.returnFullHealthCheck}.
+     */
+    readonly healthCheck: NotificationHealthCheck;
+    /**
+     * The number of probes dispatched by this run.
+     */
+    readonly probesDispatched: number;
+    /**
+     * The number of previously-pending probes this run resolved to a final status.
+     */
+    readonly probesResolved: number;
+}
 export interface ResyncAllNotificationUserParams {
 }
 export declare const resyncAllNotificationUserParamsType: Type<ResyncAllNotificationUserParams>;
@@ -310,6 +406,9 @@ export type NotificationBoxModelCrudFunctionsConfig = {
             _: UpdateNotificationUserParams;
             resync: [ResyncNotificationUserParams, ResyncNotificationUserResult];
         };
+        invoke: {
+            healthCheck: [NotificationUserHealthCheckParams, NotificationUserHealthCheckResult];
+        };
     };
     readonly notificationSummary: {
         update: {
@@ -344,6 +443,9 @@ export declare abstract class NotificationFunctions implements ModelFirebaseFunc
             update: ModelFirebaseCrudFunction<UpdateNotificationUserParams>;
             resync: ModelFirebaseCrudFunction<ResyncNotificationUserParams, ResyncNotificationUserResult>;
         };
+        invokeNotificationUser: {
+            healthCheck: ModelFirebaseCrudFunction<NotificationUserHealthCheckParams, NotificationUserHealthCheckResult>;
+        };
     };
     abstract notificationSummary: {
         updateNotificationSummary: {

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

@@ -40,3 +40,18 @@ export declare const NOTIFICATION_USER_BLOCKED_FROM_BEING_ADD_TO_RECIPIENTS_ERRO
  * Thrown when attempting to update a recipient config that is locked by the user.
  */
 export declare const NOTIFICATION_USER_LOCKED_CONFIG_FROM_BEING_UPDATED_ERROR_CODE = "NOTIFICATION_USER_LOCKED_CONFIG_FROM_BEING_UPDATED";
+/**
+ * Thrown when a NotificationUser health check is run again before its throttle window has passed.
+ */
+export declare const NOTIFICATION_USER_HEALTH_CHECK_THROTTLED_ERROR_CODE = "NOTIFICATION_USER_HEALTH_CHECK_THROTTLED";
+/**
+ * Thrown when a NotificationUser health check test message is dispatched again before its throttle
+ * window has passed. Tracked separately from the run throttle, since a probe sends a real message.
+ */
+export declare const NOTIFICATION_USER_HEALTH_CHECK_PROBE_THROTTLED_ERROR_CODE = "NOTIFICATION_USER_HEALTH_CHECK_PROBE_THROTTLED";
+/**
+ * Thrown when a NotificationUser health check's pending probes are verified again before its throttle
+ * window has passed. Tracked separately from the run throttle: verifying an in-flight test message is
+ * cheap and meant to be polled, so it neither answers to nor consumes the user's run allowance.
+ */
+export declare const NOTIFICATION_USER_HEALTH_CHECK_VERIFY_THROTTLED_ERROR_CODE = "NOTIFICATION_USER_HEALTH_CHECK_VERIFY_THROTTLED";

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

@@ -22,6 +22,7 @@ import { type NotificationBoxRecipient, type NotificationRecipientWithConfig, ty
 import { type YearWeekCode } from '@dereekb/date';
 import { type UserRelatedById, type UserRelated } from '../user';
 import { AbstractFirestoreDocument, AbstractFirestoreDocumentWithParent, type CollectionGroup, type CollectionReference, type FirestoreCollection, type FirestoreCollectionGroup, type FirestoreCollectionWithParent, type FirestoreContext, type FirestoreModelKey, type SavedToFirestoreIfTrue, type SavedToFirestoreIfFalse, type PagedItemConverter, type PagedItemFirestoreCollection, type PagedItemPageData } from '../../common';
+import { type NotificationHealthCheck } from './notification.healthcheck';
 import { type NotificationItem } from './notification.item';
 /**
  * Abstract class providing access to all notification-related Firestore collections.
@@ -142,6 +143,16 @@ export interface NotificationUser extends UserRelated, UserRelatedById {
      * @dbxModelVariable needsConfigSync
      */
     ns?: Maybe<NeedsSyncBoolean>;
+    /**
+     * The result of the most recent notification delivery health check run for this user.
+     *
+     * Persisted rather than returned-and-forgotten because delivery confirmation is asynchronous:
+     * a probe dispatched by one health check run is resolved by a later one. Absent until a check
+     * has been run at least once.
+     *
+     * @dbxModelVariable healthCheck
+     */
+    hc?: Maybe<NotificationHealthCheck>;
 }
 export type NotificationUserRoles = 'sync' | GrantedUpdateRole | GrantedReadRole;
 export declare class NotificationUserDocument extends AbstractFirestoreDocument<NotificationUser, NotificationUserDocument, typeof notificationUserIdentity> {