@dereekb/firebase-server 13.31.0 → 13.33.0

package/model/package.json

@@ -1,19 +1,20 @@
 {
   "name": "@dereekb/firebase-server/model",
-  "version": "13.31.0",
+  "version": "13.33.0",
   "peerDependencies": {
-    "@dereekb/analytics": "13.31.0",
-    "@dereekb/date": "13.31.0",
-    "@dereekb/firebase": "13.31.0",
-    "@dereekb/firebase-server": "13.31.0",
-    "@dereekb/model": "13.31.0",
-    "@dereekb/nestjs": "13.31.0",
-    "@dereekb/rxjs": "13.31.0",
-    "@dereekb/util": "13.31.0",
+    "@dereekb/analytics": "13.33.0",
+    "@dereekb/date": "13.33.0",
+    "@dereekb/firebase": "13.33.0",
+    "@dereekb/firebase-server": "13.33.0",
+    "@dereekb/model": "13.33.0",
+    "@dereekb/nestjs": "13.33.0",
+    "@dereekb/rxjs": "13.33.0",
+    "@dereekb/util": "13.33.0",
     "@nestjs/common": "^11.1.19",
     "@nestjs/config": "^4.0.4",
     "archiver": "^7.0.1",
     "date-fns": "^4.1.0",
+    "express": "^5.2.1",
     "firebase-functions": "^7.2.5",
     "make-error": "^1.3.6",
     "@cantoo/pdf-lib": "^2.6.5",

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

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

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

@@ -1 +1,2 @@
+export * from './notification.healthcheck.mailgun';
 export * from './notification.send.service.mailgun';

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

@@ -0,0 +1,115 @@
+/**
+ * @module notification.healthcheck.mailgun
+ *
+ * Mailgun-backed diagnostics for the email delivery method.
+ *
+ * This is where "the user says they aren't getting emails" turns into an actual answer. In practice the
+ * cause is almost always one of:
+ *
+ * - the address is on the domain's **suppression list** (a past bounce or spam complaint), after which
+ *   Mailgun silently drops every subsequent message to it
+ * - recent messages to the address were **rejected or failed**, with a reason Mailgun recorded
+ * - nothing was ever sent to the address at all, which points upstream at configuration
+ * - the sending **domain** itself is not active
+ *
+ * All four are readable from Mailgun without sending anything. When that is not conclusive, an opt-in
+ * probe sends a real message and resolves its outcome from the Events API. Resolution is asynchronous —
+ * Mailgun records the outcome seconds after the send — so the probe is recorded as pending and settled
+ * by a later verification, which the client polls for automatically. Nothing here ever asks the user to
+ * come back and check for themselves.
+ */
+import { type Maybe, type Minutes, type PromiseOrValue } from '@dereekb/util';
+import { type FirebaseAuthUserId } from '@dereekb/firebase';
+import { type MailgunRecipient, type MailgunService, type MailgunTemplateEmailRequest } from '@dereekb/nestjs/mailgun';
+import { type NotificationEmailSendServiceHealthCheckService } from '../notification/notification.healthcheck.service';
+/**
+ * How long a dispatched probe may stay unresolved before it is reported as failed.
+ *
+ * Mailgun normally records a `delivered` or `failed` event within seconds; a probe with no event after
+ * this long is not going to arrive.
+ */
+export declare const DEFAULT_MAILGUN_HEALTH_CHECK_PROBE_TIMEOUT_MINUTES = 15;
+/**
+ * Input for building the test email dispatched as a delivery probe.
+ */
+export interface MailgunNotificationHealthCheckProbeBuilderInput {
+    /**
+     * The Mailgun service, for reading the configured sender and client url.
+     */
+    readonly mailgunService: MailgunService;
+    /**
+     * The recipient to send the probe to.
+     */
+    readonly recipient: MailgunRecipient;
+    /**
+     * The user the health check is running for.
+     */
+    readonly uid: FirebaseAuthUserId;
+}
+/**
+ * Builds the test email dispatched as a delivery probe.
+ *
+ * The message should be recognizable to whoever receives it — it lands in a real inbox, unannounced,
+ * because someone asked the system to check whether their email works.
+ */
+export type MailgunNotificationHealthCheckProbeBuilder = (input: MailgunNotificationHealthCheckProbeBuilderInput) => PromiseOrValue<MailgunTemplateEmailRequest>;
+/**
+ * Configuration for {@link mailgunNotificationEmailSendServiceHealthCheckService}.
+ */
+export interface MailgunNotificationEmailSendServiceHealthCheckServiceConfig {
+    /**
+     * The Mailgun service to diagnose against.
+     */
+    readonly mailgunService: MailgunService;
+    /**
+     * Builds the probe message. Probing is unavailable when this is not provided.
+     */
+    readonly probeBuilder?: Maybe<MailgunNotificationHealthCheckProbeBuilder>;
+    /**
+     * The maximum number of recent events to inspect per address.
+     */
+    readonly recentEventsLimit?: Maybe<number>;
+    /**
+     * How far back to look for recent events, in days.
+     */
+    readonly recentEventsWindowDays?: Maybe<number>;
+    /**
+     * Whether to run Mailgun address validation as part of the check.
+     *
+     * Off by default, because validation consumes a separate Mailgun quota.
+     */
+    readonly validateAddress?: Maybe<boolean>;
+    /**
+     * How long a dispatched probe may stay unresolved before it is reported as failed.
+     *
+     * Defaults to {@link DEFAULT_MAILGUN_HEALTH_CHECK_PROBE_TIMEOUT_MINUTES}.
+     */
+    readonly probeTimeoutMinutes?: Maybe<Minutes>;
+}
+/**
+ * Creates a {@link NotificationEmailSendServiceHealthCheckService} backed by the Mailgun API.
+ *
+ * Attach the result to a {@link NotificationEmailSendService} as its `healthCheckService` and the
+ * notification health check will pick it up automatically.
+ *
+ * @param config - The Mailgun service plus optional probe builder and inspection limits.
+ * @returns A health check service for the email delivery method.
+ *
+ * @example
+ * ```ts
+ * const emailSendService = mailgunNotificationEmailSendService({ mailgunService, messageBuilders });
+ *
+ * const sendServiceWithHealthCheck: NotificationEmailSendService = {
+ *   ...emailSendService,
+ *   healthCheckService: mailgunNotificationEmailSendServiceHealthCheckService({
+ *     mailgunService,
+ *     probeBuilder: ({ recipient }) => ({
+ *       to: recipient,
+ *       template: 'notificationtemplate',
+ *       subject: 'Email delivery test'
+ *     })
+ *   })
+ * };
+ * ```
+ */
+export declare function mailgunNotificationEmailSendServiceHealthCheckService(config: MailgunNotificationEmailSendServiceHealthCheckServiceConfig): NotificationEmailSendServiceHealthCheckService;

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

@@ -3,6 +3,8 @@ export * from './notification.action.server.init';
 export * from './notification.config.service';
 export * from './notification.config';
 export * from './notification.create.run';
+export * from './notification.healthcheck';
+export * from './notification.healthcheck.service';
 export * from './notification.module';
 export * from './notification.send.service.notificationsummary';
 export * from './notification.send.service.text';

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

@@ -1,7 +1,7 @@
-import { type AsyncNotificationSummaryCreateAction, type AsyncNotificationUserCreateAction, type AsyncNotificationUserUpdateAction, type CleanupSentNotificationsParams, type CleanupOldNotificationLoggedEventDaysParams, type CleanupOldNotificationLoggedEventDaysResult, type CreateNotificationBoxParams, type CreateNotificationSummaryParams, type CreateNotificationUserParams, type NotificationSummaryDocument, type NotificationUser, type NotificationUserDocument, type SendNotificationParams, type SendQueuedNotificationsParams, type UpdateNotificationBoxParams, type UpdateNotificationBoxRecipientParams, type UpdateNotificationUserParams, type AsyncNotificationBoxCreateAction, type AsyncNotificationBoxUpdateAction, type CleanupSentNotificationsResult, type FirestoreContextReference, type NotificationBox, type NotificationBoxDocument, type NotificationDocument, type NotificationFirestoreCollections, type SendNotificationResult, type SendQueuedNotificationsResult, type Transaction, type ResyncAllNotificationUserParams, type ResyncAllNotificationUsersResult, type ResyncNotificationUserResult, type ResyncNotificationUserParams, type AppNotificationTemplateTypeInfoRecordServiceRef, type AsyncNotificationSummaryUpdateAction, type UpdateNotificationSummaryParams, type NotificationBoxDocumentReferencePair } from '@dereekb/firebase';
+import { type AsyncNotificationSummaryCreateAction, type AsyncNotificationUserCreateAction, type AsyncNotificationUserUpdateAction, type CleanupSentNotificationsParams, type CleanupOldNotificationLoggedEventDaysParams, type CleanupOldNotificationLoggedEventDaysResult, type CreateNotificationBoxParams, type CreateNotificationSummaryParams, type CreateNotificationUserParams, type NotificationSummaryDocument, type NotificationUser, type NotificationUserDocument, type SendNotificationParams, type SendQueuedNotificationsParams, type UpdateNotificationBoxParams, type UpdateNotificationBoxRecipientParams, type NotificationUserHealthCheckParams, type NotificationUserHealthCheckResult, type UpdateNotificationUserParams, type AsyncNotificationBoxCreateAction, type AsyncNotificationBoxUpdateAction, type CleanupSentNotificationsResult, type FirestoreContextReference, type NotificationBox, type NotificationBoxDocument, type NotificationDocument, type NotificationFirestoreCollections, type SendNotificationResult, type SendQueuedNotificationsResult, type Transaction, type ResyncAllNotificationUserParams, type ResyncAllNotificationUsersResult, type ResyncNotificationUserResult, type ResyncNotificationUserParams, type AppNotificationTemplateTypeInfoRecordServiceRef, type AsyncNotificationSummaryUpdateAction, type UpdateNotificationSummaryParams, type NotificationBoxDocumentReferencePair } from '@dereekb/firebase';
 import { type FirebaseServerActionsContext, type FirebaseServerAuthServiceRef } from '@dereekb/firebase-server';
 import { type TransformAndValidateFunctionResult } from '@dereekb/model';
-import { type Maybe } from '@dereekb/util';
+import { type Maybe, type Minutes, type Seconds } from '@dereekb/util';
 import { type InjectionToken } from '@nestjs/common';
 import { type NotificationTemplateServiceRef } from './notification.config.service';
 import { type NotificationSendServiceRef } from './notification.send.service';
@@ -24,11 +24,49 @@ export declare const NOTIFICATION_SERVER_ACTION_CONTEXT_TOKEN: InjectionToken;
  */
 export interface BaseNotificationServerActionsContext extends FirebaseServerActionsContext, NotificationFirestoreCollections, FirebaseServerAuthServiceRef, FirestoreContextReference {
 }
+/**
+ * App-level tuning for the NotificationUser delivery health check.
+ *
+ * Both windows are enforced by the server and counted down by the client, so an app that overrides one
+ * must give the SAME value to its client (see the dbx-firebase health check config). Declaring the value
+ * once in a package both sides import is the way to keep them from drifting — otherwise the UI will
+ * offer a check or a test message that the server then rejects.
+ */
+export interface NotificationUserHealthCheckServerConfig {
+    /**
+     * How long a user must wait between test messages on a single delivery method.
+     *
+     * Defaults to {@link DEFAULT_NOTIFICATION_USER_HEALTH_CHECK_PROBE_THROTTLE_MINUTES}.
+     */
+    readonly probeThrottleMinutes?: Maybe<Minutes>;
+    /**
+     * How long a user must wait between health check runs.
+     *
+     * Defaults to {@link DEFAULT_NOTIFICATION_USER_HEALTH_CHECK_THROTTLE_MINUTES}.
+     */
+    readonly runThrottleMinutes?: Maybe<Minutes>;
+    /**
+     * How long a caller must wait between verifications of a check's pending probes.
+     *
+     * Defaults to {@link DEFAULT_NOTIFICATION_USER_HEALTH_CHECK_VERIFY_THROTTLE_SECONDS}. In seconds
+     * because a verification exists to be polled while the user watches for their test message to land.
+     */
+    readonly verifyThrottleSeconds?: Maybe<Seconds>;
+}
+/**
+ * Reference to a {@link NotificationUserHealthCheckServerConfig}.
+ */
+export interface NotificationUserHealthCheckServerConfigRef {
+    /**
+     * Tuning for the delivery health check. Every field falls back to the library default when absent.
+     */
+    readonly notificationUserHealthCheckConfig?: Maybe<NotificationUserHealthCheckServerConfig>;
+}
 /**
  * Full context for notification server actions, extending the base with template resolution,
  * send channel orchestration, task dispatch, and expedite services.
  */
-export interface NotificationServerActionsContext extends BaseNotificationServerActionsContext, AppNotificationTemplateTypeInfoRecordServiceRef, NotificationTemplateServiceRef, NotificationSendServiceRef, NotificationTaskServiceRef {
+export interface NotificationServerActionsContext extends BaseNotificationServerActionsContext, AppNotificationTemplateTypeInfoRecordServiceRef, NotificationTemplateServiceRef, NotificationSendServiceRef, NotificationTaskServiceRef, NotificationUserHealthCheckServerConfigRef {
 }
 /**
  * Abstract service class defining all server-side notification CRUD and delivery actions.
@@ -50,6 +88,7 @@ export declare abstract class NotificationServerActions {
     abstract updateNotificationUser(params: UpdateNotificationUserParams): AsyncNotificationUserUpdateAction<UpdateNotificationUserParams>;
     abstract resyncNotificationUser(params: ResyncNotificationUserParams): Promise<TransformAndValidateFunctionResult<ResyncNotificationUserParams, (notificationUserDocument: NotificationUserDocument) => Promise<ResyncNotificationUserResult>>>;
     abstract resyncAllNotificationUsers(params?: ResyncAllNotificationUserParams): Promise<ResyncAllNotificationUsersResult>;
+    abstract notificationUserHealthCheck(params: NotificationUserHealthCheckParams): Promise<TransformAndValidateFunctionResult<NotificationUserHealthCheckParams, (notificationUserDocument: NotificationUserDocument) => Promise<NotificationUserHealthCheckResult>>>;
     abstract createNotificationSummary(params: CreateNotificationSummaryParams): AsyncNotificationSummaryCreateAction<CreateNotificationSummaryParams>;
     abstract updateNotificationSummary(params: UpdateNotificationSummaryParams): AsyncNotificationSummaryUpdateAction<UpdateNotificationSummaryParams>;
     abstract createNotificationBox(params: CreateNotificationBoxParams): AsyncNotificationBoxCreateAction<CreateNotificationBoxParams>;

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

@@ -59,6 +59,37 @@ export declare function notificationBoxExistsForModelError(): import("firebase-f
  * @returns A precondition conflict error with the recipient-not-found error code.
  */
 export declare function notificationBoxRecipientDoesNotExistsError(): import("firebase-functions/https").HttpsError;
+/**
+ * Creates an error indicating that a health check was run again before its throttle window passed.
+ *
+ * Thrown by the {@link NotificationUser} health check when the stored check is too recent.
+ *
+ * @param nextRunAt - The time the next health check may be run.
+ * @returns A precondition conflict error with the health-check-throttled error code.
+ */
+export declare function notificationUserHealthCheckThrottledError(nextRunAt: Date): import("firebase-functions/https").HttpsError;
+/**
+ * Creates an error indicating that a test message was requested again before its throttle window passed.
+ *
+ * Thrown by the {@link NotificationUser} health check when a probe was dispatched too recently. Separate
+ * from {@link notificationUserHealthCheckThrottledError}: running the check does not consume the test
+ * message allowance.
+ *
+ * @param nextProbeAt - The time the next test message may be dispatched.
+ * @returns A precondition conflict error with the probe-throttled error code.
+ */
+export declare function notificationUserHealthCheckProbeThrottledError(nextProbeAt: Date): import("firebase-functions/https").HttpsError;
+/**
+ * Creates an error indicating that pending probes were verified again before their throttle window passed.
+ *
+ * Thrown by the {@link NotificationUser} health check on a `verifyPendingProbesOnly` run that arrives too
+ * soon after the last one. Separate from {@link notificationUserHealthCheckThrottledError}: verifying an
+ * in-flight test message is a poll, so it neither answers to nor consumes the user's run allowance.
+ *
+ * @param nextVerifyAt - The time the next verification may be run.
+ * @returns A precondition conflict error with the verify-throttled error code.
+ */
+export declare function notificationUserHealthCheckVerifyThrottledError(nextVerifyAt: Date): import("firebase-functions/https").HttpsError;
 /**
  * Creates an error indicating that the given UID does not correspond to an existing Firebase Auth user.
  *

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

@@ -0,0 +1,39 @@
+/**
+ * @module notification.healthcheck
+ *
+ * The `healthCheck` server action: a self-serve diagnosis of why a given user is or is not receiving
+ * notifications on each delivery method.
+ *
+ * The check runs in three passes:
+ *
+ * 1. **Configuration** — mirrors the gates {@link expandNotificationRecipients} applies at send time,
+ *    so a finding here corresponds to a real reason a message would be dropped.
+ * 2. **Subscriptions** — inspects the user's {@link NotificationBox} documents to confirm they exist,
+ *    are initialized, and carry a recipient entry matching the user's own configuration.
+ * 3. **Provider** — delegates to each delivery method's optional
+ *    {@link NotificationSendServiceHealthCheckService} for provider-specific diagnostics and for
+ *    dispatching/resolving a delivery probe.
+ *
+ * The result is persisted to the user's `hc` field, because delivery confirmation is asynchronous: a
+ * probe dispatched by one run is resolved by a later one. That later run is normally a
+ * `verifyPendingProbesOnly` VERIFICATION rather than anything the user does — a cheap poll that consults
+ * a provider only where a probe is actually in flight, answers to its own short window, and advances
+ * `vat` instead of `at` so that watching a test message never consumes the user's run allowance. The
+ * client reads the stored check live, so a resolved probe simply appears.
+ */
+import { type NotificationUserDocument, type NotificationUserHealthCheckParams, type NotificationUserHealthCheckResult } from '@dereekb/firebase';
+import { type NotificationServerActionsContext } from './notification.action.server';
+/**
+ * The maximum number of the user's notification boxes to inspect in a single health check.
+ *
+ * A user can be subscribed to an unbounded number of boxes; a health check is interactive, so it
+ * samples rather than walking all of them.
+ */
+export declare const DEFAULT_MAX_NOTIFICATION_BOXES_TO_INSPECT_PER_HEALTH_CHECK = 10;
+/**
+ * Factory for the `healthCheck` action on a {@link NotificationUser}.
+ *
+ * @param context - The notification server actions context.
+ * @returns A transform-and-validate function that runs a delivery health check for a notification user.
+ */
+export declare function notificationUserHealthCheckFactory(context: NotificationServerActionsContext): import("@dereekb/model").TransformAndValidateFunctionResultFunction<NotificationUserHealthCheckParams, (notificationUserDocument: NotificationUserDocument) => Promise<NotificationUserHealthCheckResult>, object, unknown>;

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

@@ -0,0 +1,118 @@
+/**
+ * @module notification.healthcheck.service
+ *
+ * The extension point that lets each delivery method contribute its own diagnostics to a
+ * notification delivery health check.
+ *
+ * The shared health check action can only inspect what it knows about: the user's configuration,
+ * their notification boxes, and the send queue. Everything beyond that is provider-specific — whether
+ * an address is on an email provider's suppression list, whether a carrier rejected an SMS, whether a
+ * test message actually arrived. A send service opts into contributing that knowledge by exposing a
+ * {@link NotificationSendServiceHealthCheckService}.
+ */
+import { type EmailAddress, type E164PhoneNumber, type Maybe } from '@dereekb/util';
+import { type FirebaseAuthUserId, type NotificationDeliveryMethod, type NotificationHealthCheckIssue, type NotificationHealthCheckProbe, type NotificationSummaryId, type NotificationTemplateType } from '@dereekb/firebase';
+/**
+ * Input to a {@link NotificationSendServiceHealthCheckService}.
+ *
+ * @template T - The delivery target type for the method (email address, phone number, summary id).
+ */
+export interface NotificationSendServiceHealthCheckRequest<T = unknown> {
+    /**
+     * The delivery method being diagnosed.
+     */
+    readonly method: NotificationDeliveryMethod;
+    /**
+     * The resolved delivery target to diagnose.
+     */
+    readonly target: T;
+    /**
+     * The user the check is being run for.
+     */
+    readonly uid: FirebaseAuthUserId;
+    /**
+     * Whether this run is permitted to dispatch a real probe message to the target.
+     *
+     * Always respect this — a probe sends real mail or SMS to a real person, and the caller has decided
+     * whether that is acceptable right now.
+     */
+    readonly sendProbe: boolean;
+    /**
+     * A probe dispatched by an earlier run that has not reached a final status yet.
+     *
+     * When present, the service should try to resolve it and return it (updated) as the response's probe.
+     */
+    readonly pendingProbe?: Maybe<NotificationHealthCheckProbe>;
+    /**
+     * The notification template type the check is being evaluated against, if the caller specified one.
+     */
+    readonly notificationTemplateType?: Maybe<NotificationTemplateType>;
+    /**
+     * The time the health check started. Use this rather than reading the clock so every finding in a
+     * single check shares one reference time.
+     */
+    readonly now: Date;
+}
+/**
+ * Output of a {@link NotificationSendServiceHealthCheckService}.
+ */
+export interface NotificationSendServiceHealthCheckResponse {
+    /**
+     * Provider-level findings. May be empty when the provider had nothing to report.
+     */
+    readonly issues: NotificationHealthCheckIssue[];
+    /**
+     * The probe for this delivery method — a newly dispatched one, a resolved pending one, or a pending
+     * one that still has no outcome.
+     */
+    readonly probe?: Maybe<NotificationHealthCheckProbe>;
+}
+/**
+ * Contributes provider-specific diagnostics for one delivery method.
+ *
+ * Implementations should be failure-tolerant: if a provider API is unreachable, report that as an
+ * {@link NotificationHealthCheckStatus.UNKNOWN} issue rather than throwing, so the rest of the health
+ * check still reaches the user.
+ *
+ * @template T - The delivery target type for the method.
+ *
+ * @example
+ * ```ts
+ * const healthCheckService: NotificationEmailSendServiceHealthCheckService = {
+ *   supportsProbe: true,
+ *   async runHealthCheck({ target, sendProbe }) {
+ *     const issues = await inspectSuppressionLists(target);
+ *     const probe = sendProbe ? await dispatchProbe(target) : undefined;
+ *     return { issues, probe };
+ *   }
+ * };
+ * ```
+ */
+export interface NotificationSendServiceHealthCheckService<T = unknown> {
+    /**
+     * Whether this service can dispatch a probe message.
+     *
+     * Reported to callers so a UI can hide the "send a test message" affordance for methods that do not
+     * support it. Defaults to false.
+     */
+    readonly supportsProbe?: Maybe<boolean>;
+    /**
+     * Runs the provider's diagnostics for a single delivery target.
+     *
+     * @param request - The target to diagnose and whether probing is permitted.
+     * @returns The provider's findings and probe state.
+     */
+    runHealthCheck(request: NotificationSendServiceHealthCheckRequest<T>): Promise<NotificationSendServiceHealthCheckResponse>;
+}
+/**
+ * A {@link NotificationSendServiceHealthCheckService} for the email delivery method.
+ */
+export type NotificationEmailSendServiceHealthCheckService = NotificationSendServiceHealthCheckService<EmailAddress>;
+/**
+ * A {@link NotificationSendServiceHealthCheckService} for the text/SMS delivery method.
+ */
+export type NotificationTextSendServiceHealthCheckService = NotificationSendServiceHealthCheckService<E164PhoneNumber>;
+/**
+ * A {@link NotificationSendServiceHealthCheckService} for the in-app notification summary delivery method.
+ */
+export type NotificationSummarySendServiceHealthCheckService = NotificationSendServiceHealthCheckService<NotificationSummaryId>;

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

@@ -1,5 +1,6 @@
 import { type NotificationSummaryIdForUidFunction, type NotificationMessage, type NotificationSendEmailMessagesResult, type NotificationSendNotificationSummaryMessagesResult, type NotificationSendTextMessagesResult } from '@dereekb/firebase';
 import { type NotificationSendMessagesInstance } from './notification.send';
+import { type NotificationEmailSendServiceHealthCheckService, type NotificationSummarySendServiceHealthCheckService, type NotificationTextSendServiceHealthCheckService } from './notification.healthcheck.service';
 import { type Maybe } from '@dereekb/util';
 /**
  * Provides a reference to a NotificationSendService instance.
@@ -46,6 +47,13 @@ export interface NotificationEmailSendService {
      * Can throw an error if the messages cannot be sent or generated properly due to a configuration error.
      */
     buildSendInstanceForEmailNotificationMessages(notificationMessages: NotificationMessage[]): Promise<NotificationSendMessagesInstance<NotificationSendEmailMessagesResult>>;
+    /**
+     * Optional. Contributes provider-specific diagnostics for the email channel to a notification
+     * delivery health check.
+     *
+     * When absent, a health check reports only what it can determine from configuration and send history.
+     */
+    readonly healthCheckService?: Maybe<NotificationEmailSendServiceHealthCheckService>;
 }
 /**
  * Service dedicated to sending notification text messages.
@@ -57,6 +65,13 @@ export interface NotificationTextSendService {
      * Can throw an error if the messages cannot be sent or generated properly due to a configuration error.
      */
     buildSendInstanceForTextNotificationMessages(notificationMessages: NotificationMessage[]): Promise<NotificationSendMessagesInstance<NotificationSendTextMessagesResult>>;
+    /**
+     * Optional. Contributes provider-specific diagnostics for the text/SMS channel to a notification
+     * delivery health check.
+     *
+     * When absent, a health check reports only what it can determine from configuration and send history.
+     */
+    readonly healthCheckService?: Maybe<NotificationTextSendServiceHealthCheckService>;
 }
 /**
  * Service dedicated to sending/updating NotificationSummary values in the system for the input messages.
@@ -68,4 +83,11 @@ export interface NotificationSummarySendService {
      * Can throw an error if the messages cannot be sent or generated properly due to a configuration error.
      */
     buildSendInstanceForNotificationSummaryMessages(notificationMessages: NotificationMessage[]): Promise<NotificationSendMessagesInstance<NotificationSendNotificationSummaryMessagesResult>>;
+    /**
+     * Optional. Contributes diagnostics for the in-app notification summary channel to a notification
+     * delivery health check.
+     *
+     * When absent, a health check reports only what it can determine from configuration and send history.
+     */
+    readonly healthCheckService?: Maybe<NotificationSummarySendServiceHealthCheckService>;
 }

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

@@ -0,0 +1,8 @@
+export * from './oauth';
+export * from './userexternalconnection.private';
+export * from './userexternalconnection.accessor.service';
+export * from './userexternalconnection.action.server';
+export * from './userexternalconnection.error';
+export * from './userexternalconnection.module';
+export * from './userexternalconnection.reader.service';
+export * from './userexternalconnection.refresh.service';

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

@@ -0,0 +1,7 @@
+export * from './userexternalconnection.oauth.config';
+export * from './userexternalconnection.oauth.controller';
+export * from './userexternalconnection.oauth.error';
+export * from './userexternalconnection.oauth.refresh';
+export * from './userexternalconnection.oauth.registry';
+export * from './userexternalconnection.oauth.service';
+export * from './userexternalconnection.oauth.state';

package/model/src/lib/userexternalconnection/oauth/userexternalconnection.oauth.config.d.ts

@@ -0,0 +1,110 @@
+import { type UserExternalConnectionProviderType } from '@dereekb/firebase';
+import { type FirebaseServerEnvService } from '@dereekb/firebase-server';
+import { type Maybe, type WebsiteUrl } from '@dereekb/util';
+/**
+ * Controller path a provider's external-connection OAuth endpoints are mounted at.
+ *
+ * Matches the Angular registry's `DEFAULT_EXTERNAL_CONNECTION_AUTHORIZE_PATH_FACTORY`, which builds
+ * `/oauth/<providerType>/authorize`.
+ *
+ * @param providerType - The provider to build a controller path for.
+ * @returns The controller path, without a leading slash.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function userExternalConnectionOAuthControllerPath(providerType: UserExternalConnectionProviderType): string;
+/**
+ * Routes to exclude from an app's global API route prefix so a provider's callback controller stays
+ * mounted at `/oauth/<providerType>/*`.
+ *
+ * Spread the result into the `exclude` list of the app's `globalApiRoutePrefix` config, alongside
+ * `FIREBASE_SERVER_OIDC_ROUTES_FOR_GLOBAL_ROUTE_EXCLUDE`. Without it an `/api` prefix moves the
+ * routes to `/api/oauth/<providerType>/*`, which no longer matches the redirect URI registered with
+ * the provider — and providers require a byte-identical match, so this is not something they
+ * tolerate.
+ *
+ * @param providerType - The provider whose routes should be excluded.
+ * @returns The route patterns to exclude.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function userExternalConnectionOAuthRoutesForGlobalRouteExclude(providerType: UserExternalConnectionProviderType): string[];
+export interface UserExternalConnectionOAuthRedirectUriInput {
+    /**
+     * The origin the OAuth endpoints are reachable at, e.g. `https://example.com`.
+     */
+    readonly origin: WebsiteUrl;
+    readonly providerType: UserExternalConnectionProviderType;
+}
+/**
+ * Builds the redirect URI to register with a provider.
+ *
+ * Derived from {@link userExternalConnectionOAuthControllerPath}, the same expression the controller
+ * mounts on, so the registered URI cannot drift from the route that serves it.
+ *
+ * @param input - The origin and the provider.
+ * @returns The redirect URI.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function userExternalConnectionOAuthRedirectUri(input: UserExternalConnectionOAuthRedirectUriInput): WebsiteUrl;
+export interface UserExternalConnectionOAuthApiConfig {
+    /**
+     * The provider this flow connects.
+     */
+    readonly providerType: UserExternalConnectionProviderType;
+    /**
+     * The redirect URI registered on the provider's OAuth client.
+     *
+     * Must match the registered value byte-for-byte, including the port, since it is sent on both the
+     * authorize redirect and the token exchange.
+     */
+    readonly redirectUri: WebsiteUrl;
+    /**
+     * Where the user is sent after a connection succeeds.
+     */
+    readonly successUrl: WebsiteUrl;
+    /**
+     * Where the user is sent after a connection fails. Defaults to the `successUrl`.
+     */
+    readonly failureUrl?: Maybe<WebsiteUrl>;
+}
+/**
+ * Configuration for an {@link AbstractUserExternalConnectionOAuthService}.
+ *
+ * Provided privately by each provider's module, so two registered providers never collide on this
+ * token.
+ */
+export declare abstract class UserExternalConnectionOAuthServiceConfig {
+    readonly userExternalConnectionOAuth: UserExternalConnectionOAuthApiConfig;
+    static assertValidConfig(config: UserExternalConnectionOAuthServiceConfig): void;
+}
+export interface UserExternalConnectionOAuthServiceConfigFactoryConfig {
+    /**
+     * Used to resolve the OAuth origin and the app URL. No part of this configuration is read from the
+     * environment as a value — only the origins the app is already configured with.
+     */
+    readonly envService: FirebaseServerEnvService;
+    readonly providerType: UserExternalConnectionProviderType;
+    /**
+     * Path on the app URL the user is returned to after a successful connect, e.g. `/app/settings`.
+     */
+    readonly successPath: string;
+    /**
+     * Path on the app URL the user is returned to after a failed connect. Defaults to `successPath`.
+     */
+    readonly failurePath?: Maybe<string>;
+}
+/**
+ * Builds a provider's OAuth configuration from the app's configured origins plus code-declared
+ * return paths.
+ *
+ * The redirect URI is derived rather than configured: it is the app's OAuth origin joined to the
+ * same controller path the callback mounts on. Registering a provider therefore requires no
+ * deployment configuration of its own.
+ *
+ * @param config - The env service, the provider, and the return paths.
+ * @returns The validated service configuration.
+ * @throws {Error} When no app URL is configured, or the derived URIs are inconsistent.
+ */
+export declare function userExternalConnectionOAuthServiceConfigFactory(config: UserExternalConnectionOAuthServiceConfigFactoryConfig): UserExternalConnectionOAuthServiceConfig;