@dereekb/firebase 13.30.0 → 13.32.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dereekb/firebase",
-  "version": "13.30.0",
+  "version": "13.32.0",
   "sideEffects": false,
   "exports": {
     "./test": {
@@ -24,10 +24,10 @@
     }
   },
   "peerDependencies": {
-    "@dereekb/date": "13.30.0",
-    "@dereekb/model": "13.30.0",
-    "@dereekb/rxjs": "13.30.0",
-    "@dereekb/util": "13.30.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/common/auth/oidc/oidc.profile.d.ts

@@ -63,11 +63,49 @@ export interface OidcProviderProfile<S extends OidcScope = OidcScope> {
      * Optional human-readable description, used in the admin profile picker.
      */
     readonly description?: string;
+    /**
+     * Whether this profile applies to a client that has NO profiles assigned (an empty or absent
+     * `dbx_provider_profiles`). Defaults to `false`.
+     *
+     * Lets an app make a coarse, broadly-available scope profile-gated — so the profile picker becomes
+     * the single control surface for scope grouping — without breaking every already-registered client.
+     * Multiple default profiles union.
+     *
+     * The fallback is exclusive: a client assigned ANY profile resolves to exactly its assigned
+     * profiles, so assigning a non-default profile does NOT additionally confer the default's scopes.
+     *
+     * Note a `require: 'required'` scope on a default profile is force-required for EVERY unassigned
+     * client — a default profile usually wants `require: 'none'`.
+     *
+     * @see oidcProviderProfilesForClient
+     */
+    readonly isDefault?: boolean;
+    /**
+     * Whether the scopes this profile unlocks may only be granted to admin users. Defaults to `false`.
+     *
+     * Equivalent to listing this profile's scopes in `OidcProviderConfig.adminOnlyScopes` — the two are
+     * unioned — but declared alongside the profile so the fact lives in one place rather than drifting
+     * between the shared registry and the server provider config.
+     *
+     * Combined with `require: 'required'`, this makes the whole client admin-only: the client always
+     * requests the scope, so a non-admin resolving its consent is always rejected with `access_denied`.
+     *
+     * Independent of {@link isDefault} and of the profile unlock gate — a scope may be subject to both
+     * gates.
+     *
+     * @see adminOnlyScopesForOidcProviderProfiles
+     */
+    readonly adminOnly?: boolean;
     /**
      * The scopes this profile unlocks, each with an optional require mode.
      */
     readonly scopes: readonly OidcProviderProfileScopeConfig<S>[];
 }
+/**
+ * Suffix appended to a default profile's description in {@link oidcProviderProfileDetails}, so an
+ * admin viewing the picker sees that leaving the field empty still grants that profile's scopes.
+ */
+export declare const OIDC_PROVIDER_PROFILE_DEFAULT_DESCRIPTION_SUFFIX = "Applied by default when no profiles are assigned.";
 /**
  * Profile picker entry (label + key + description), mirroring {@link OidcScopeDetails}.
  */
@@ -80,6 +118,31 @@ export type OidcProviderProfileDetails = LabeledValueWithDescription<OidcProvide
  * @returns The registry profiles whose key is in `keys`.
  */
 export declare function oidcProviderProfilesForKeys<S extends OidcScope = OidcScope>(profiles: readonly OidcProviderProfile<S>[], keys: readonly OidcProviderProfileKey[] | undefined): OidcProviderProfile<S>[];
+/**
+ * Filters the provider-profile registry to the profiles marked {@link OidcProviderProfile.isDefault}.
+ *
+ * @param profiles - The full provider-profile registry.
+ * @returns The registry profiles that apply to a client with no assigned profiles.
+ */
+export declare function defaultOidcProviderProfiles<S extends OidcScope = OidcScope>(profiles: readonly OidcProviderProfile<S>[]): OidcProviderProfile<S>[];
+/**
+ * Resolves the profiles that apply to a client: its assigned profiles, or — when it has NO profiles
+ * assigned — the registry's default profiles.
+ *
+ * The fallback is exclusive: a client with any assigned key resolves to exactly
+ * {@link oidcProviderProfilesForKeys}, so a non-default assignment never additionally confers the
+ * default profiles' scopes. A registry declaring no default behaves identically to
+ * {@link oidcProviderProfilesForKeys}.
+ *
+ * The fallback keys off the assigned key list being empty/absent rather than off the resolved set
+ * being empty, so a client whose assigned profile was later removed from the registry resolves to no
+ * profiles (fail-closed) rather than silently picking up the default.
+ *
+ * @param profiles - The full provider-profile registry.
+ * @param keys - The profile keys assigned to the client (its `dbx_provider_profiles`).
+ * @returns The client's assigned profiles, or the default profiles when none are assigned.
+ */
+export declare function oidcProviderProfilesForClient<S extends OidcScope = OidcScope>(profiles: readonly OidcProviderProfile<S>[], keys: readonly OidcProviderProfileKey[] | undefined): OidcProviderProfile<S>[];
 /**
  * Collects every scope referenced by the given profiles.
  *
@@ -87,6 +150,11 @@ export declare function oidcProviderProfilesForKeys<S extends OidcScope = OidcSc
  * obtain via a profile. Passed a client's assigned profiles, this is the set of scopes those
  * profiles unlock for that client.
  *
+ * Note a gated scope is not necessarily unavailable to an unassigned client: a scope unlocked by a
+ * default profile is gated yet reachable by every client. Use
+ * {@link assignmentOnlyScopesForOidcProviderProfiles} for the "requires an explicit assignment"
+ * subset (e.g. to exclude scopes from a general picker or from advertised scope metadata).
+ *
  * @param profiles - The profiles to collect scopes from.
  * @returns The union of every profile's scopes.
  */
@@ -98,9 +166,47 @@ export declare function scopesForOidcProviderProfiles<S extends OidcScope = Oidc
  * @returns The union of every profile's `required` scopes.
  */
 export declare function requiredScopesForOidcProviderProfiles<S extends OidcScope = OidcScope>(profiles: readonly OidcProviderProfile<S>[]): Set<S>;
+/**
+ * Collects the scopes unlocked by the registry's default profiles — the scopes every client can
+ * obtain, including one with no profiles assigned.
+ *
+ * @param profiles - The full provider-profile registry.
+ * @returns The union of every default profile's scopes. Empty when no profile is marked default.
+ */
+export declare function defaultUnlockedScopesForOidcProviderProfiles<S extends OidcScope = OidcScope>(profiles: readonly OidcProviderProfile<S>[]): Set<S>;
+/**
+ * Collects the gated scopes that are NOT unlocked by default — the scopes a client can only obtain
+ * via an explicit profile assignment.
+ *
+ * This is the set to exclude from a general scope picker or from advertised scope metadata (e.g. an
+ * MCP protected-resource document's `scopes_supported`). Prefer it over
+ * {@link scopesForOidcProviderProfiles} for that job: the full gated set would wrongly drop a
+ * default-unlocked scope that every client can in fact obtain. With no default declared the two are
+ * identical.
+ *
+ * @param profiles - The full provider-profile registry.
+ * @returns Every profile-gated scope minus the default-unlocked ones.
+ */
+export declare function assignmentOnlyScopesForOidcProviderProfiles<S extends OidcScope = OidcScope>(profiles: readonly OidcProviderProfile<S>[]): Set<S>;
+/**
+ * Collects the scopes of every profile marked {@link OidcProviderProfile.adminOnly}.
+ *
+ * Unioned with `OidcProviderConfig.adminOnlyScopes` by the consent admin-only gate: a consent
+ * requesting one of these scopes is hard-rejected with `access_denied` when the resolving user is
+ * not an admin.
+ *
+ * @param profiles - The full provider-profile registry.
+ * @returns The union of every admin-only profile's scopes. Empty when no profile is marked admin-only.
+ */
+export declare function adminOnlyScopesForOidcProviderProfiles<S extends OidcScope = OidcScope>(profiles: readonly OidcProviderProfile<S>[]): Set<S>;
 /**
  * Builds picker entries for the given provider profiles, suitable for an admin profile-selection field.
  *
+ * A default profile's description carries {@link OIDC_PROVIDER_PROFILE_DEFAULT_DESCRIPTION_SUFFIX} so
+ * an admin isn't surprised that an empty selection still grants scopes. Default profiles are
+ * deliberately not pre-selected — persisting the default as an explicit assignment would opt the
+ * client out of the fallback, so it would stop tracking the registry if the default later changed.
+ *
  * @param profiles - The provider-profile registry.
  * @returns One {@link OidcProviderProfileDetails} per profile.
  */

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