@dereekb/firebase 13.31.0 → 13.33.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dereekb/firebase",
-  "version": "13.31.0",
+  "version": "13.33.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.33.0",
+    "@dereekb/model": "13.33.0",
+    "@dereekb/rxjs": "13.33.0",
+    "@dereekb/util": "13.33.0",
     "@firebase/rules-unit-testing": "5.0.0",
     "@marcbachmann/cel-js": "^7.6.1",
     "@typescript-eslint/parser": "8.59.3",

package/src/lib/common/firestore/snapshot/snapshot.field.d.ts

@@ -23,7 +23,7 @@
  * - **Primitives**: `firestoreString`, `firestoreNumber`, `firestoreBoolean`, `firestoreEnum`
  * - **Dates**: `firestoreDate` (ISO8601), `firestoreDateNumber` (unix seconds)
  * - **Arrays**: `firestoreArray`, `firestoreUniqueArray`, `firestoreEnumArray`, `firestoreEncodedArray`
- * - **Maps**: `firestoreMap`, `firestoreEncodedObjectMap`, `firestoreArrayMap`
+ * - **Maps**: `firestoreMap`, `firestoreEncodedObjectMap`, `firestoreObjectMap`, `firestoreArrayMap`
  * - **Objects**: `firestoreSubObject`, `firestoreObjectArray`
  * - **Specialized**: `firestoreUID`, `firestoreLatLngString`, `firestoreWebsiteLink`,
  *   `firestoreDateCellRange`, `firestoreBitwiseSet`, `firestoreUnitedStatesAddress`
@@ -1361,9 +1361,11 @@ export type FirestoreSubObjectFieldMapFunctionsConfig<T extends object, O extend
  * // Nested address object with its own converters
  * const addressField = firestoreSubObject<Address>({
  *   objectField: {
- *     street: firestoreString(),
- *     city: firestoreString(),
- *     zip: firestoreString()
+ *     fields: {
+ *       street: firestoreString(),
+ *       city: firestoreString(),
+ *       zip: firestoreString()
+ *     }
  *   }
  * });
  * ```
@@ -1371,6 +1373,59 @@ export type FirestoreSubObjectFieldMapFunctionsConfig<T extends object, O extend
  * @__NO_SIDE_EFFECTS__
  */
 export declare function firestoreSubObject<T extends object, O extends object = FirestoreModelData<T>>(config: FirestoreSubObjectFieldConfig<T, O>): FirestoreSubObjectFieldMapFunctionsConfig<T, O>;
+/**
+ * A Firestore map type where each value is an object that is converted using its own set of field converters.
+ */
+export type FirestoreObjectMapFieldValueType<T extends object, S extends string = string> = Record<S, T>;
+/**
+ * firestoreObjectMap configuration
+ */
+export type FirestoreObjectMapFieldConfig<T extends object, O extends object = FirestoreModelData<T>, S extends string = string> = DefaultMapConfiguredFirestoreFieldConfig<FirestoreObjectMapFieldValueType<T, S>, FirestoreMapFieldType<O, S>> & (FirestoreObjectArrayFieldConfigObjectFieldInput<T, O> | FirestoreObjectArrayFieldConfigFirestoreFieldInput<T, O>) & {
+    /**
+     * Optional filter to apply when saving to data.
+     *
+     * By default filters all empty values from the map. Objects with no keys are considered empty.
+     */
+    readonly mapFilter?: FilterKeyValueTuplesInput<FirestoreMapFieldType<O, S>>;
+};
+/**
+ * Creates a field mapping configuration for a Firestore map whose values are complex objects.
+ *
+ * This is the map-keyed counterpart to {@link firestoreObjectArray}: each value in the map is
+ * converted using its own set of field converters (via `objectField` or `firestoreField`), so
+ * nested `Date`/enum/array fields round-trip properly.
+ *
+ * On write, null/undefined values are filtered from each object to match Firestore semantics, and
+ * empty values (including objects with no keys) are removed from the map entirely.
+ *
+ * NOTE: this exists instead of passing a sub-object's `mapFunctions.to`/`.from` directly to
+ * {@link firestoreEncodedObjectMap}. That encoder is invoked as `mapFn(value, key)` by
+ * `mapObjectMap()`, while a `ModelMapFunctions`' second parameter is the accumulator *target* — so
+ * the map key string would be used as the write target and the conversion would throw at runtime.
+ * The arity is wrapped here, once, rather than at each call site.
+ *
+ * @param config - Configuration including the per-value conversions and optional map filtering.
+ * @returns A field mapping configuration for object map values.
+ *
+ * @dbxModelSnapshotField
+ * @dbxModelSnapshotFieldCategory map
+ * @dbxModelSnapshotFieldTags map, record, dictionary, object, nested, embedded, structured, factory
+ * @dbxModelSnapshotFieldRelated firestore-sub-object, firestore-object-array
+ * @template T - The value model type
+ * @template O - The value Firestore data type (defaults to FirestoreModelData<T>)
+ * @template S - Key type (string, defaults to string)
+ *
+ * @example
+ * ```ts
+ * // Map of provider id -> connection entry
+ * const entriesField = firestoreObjectMap<UserExternalConnectionEntry, FirestoreModelData<UserExternalConnectionEntry>, UserExternalConnectionProviderType>({
+ *   objectField: { fields: userExternalConnectionEntryFields }
+ * });
+ * ```
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function firestoreObjectMap<T extends object, O extends object = FirestoreModelData<T>, S extends string = string>(config: FirestoreObjectMapFieldConfig<T, O, S>): FirestoreModelFieldMapFunctionsConfig<FirestoreEncodedObjectMapFieldValueType<T, S>, FirestoreMapFieldType<O, S>>;
 export interface FirestoreLatLngStringConfig extends DefaultMapConfiguredFirestoreFieldConfig<LatLngString, LatLngString> {
     readonly precision?: LatLngPrecision;
 }

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

@@ -4,3 +4,4 @@ export * from './notification';
 export * from './oidcmodel';
 export * from './storagefile';
 export * from './system';
+export * from './userexternalconnection';

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> {