@aglyn/tenant-data-admin 1.0.0-beta.205 → 1.0.0-beta.207

package/src/lib/server/operator-alerts.d.ts

@@ -0,0 +1,215 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { type AglynNotificationType, type OperatorAlertContext, type OperatorAlertDefinition, type OperatorAlertSettings } from '@aglyn/aglyn/server';
+import { type SendEmailResult } from '@aglyn/shared-util-email';
+/**
+ * RAISING AN OPERATOR ALERT (AGL-3377): the one server entry point every
+ * alert in the registry goes through.
+ *
+ * In order, for one call:
+ *
+ * 1. The type is looked up in the registry (core's catalog plus what plugins
+ *    registered). A plugin may pass its definition itself, which registers
+ *    it in this process if its declarations have not loaded yet.
+ * 2. A `dedupeKey` is claimed against `operatorAlertState`, so a condition
+ *    that flaps inside the type's window is told once, and a type with
+ *    `minOccurrences` fires only once it has recurred that often.
+ * 3. The staff console notification is written for every staff member, as
+ *    `notifyStaff` always has.
+ * 4. Staff's switches (`platformSettings/operatorAlerts`, coded defaults
+ *    until changed) decide the rest: off is console only, `digest` queues it
+ *    for the once-a-day digest, `immediate` emails the operator now.
+ * 5. The email is the `operator-alert` system email, to
+ *    `resolveStaffAlertRecipients()`; the optional out-of-band webhook
+ *    (`OPERATOR_ALERT_WEBHOOK_URL`) gets the same alert beside it, so a mail
+ *    provider that is itself the outage still reaches somebody.
+ *
+ * Never throws: an alert is raised from inside the failure it reports, and a
+ * second failure there must not replace the first.
+ */
+/** Where staff's per-type switches live. */
+export declare const OPERATOR_ALERT_SETTINGS_COLLECTION = "platformSettings";
+export declare const OPERATOR_ALERT_SETTINGS_DOC = "operatorAlerts";
+/** One document per (type, dedupeKey): when it last fired, how often since. */
+export declare const OPERATOR_ALERT_STATE_COLLECTION = "operatorAlertState";
+/** Alerts waiting for the daily digest. */
+export declare const OPERATOR_ALERT_DIGEST_COLLECTION = "operatorAlertDigest";
+/** The hour, UTC, the digest goes out when staff have not chosen one. */
+export declare const OPERATOR_ALERT_DIGEST_DEFAULT_HOUR_UTC = 14;
+export interface OperatorAlertSettingsDoc extends OperatorAlertSettings {
+    /** The hour of the day, UTC, the digest is sent. */
+    digestHourUtc?: number;
+    updatedAtMs?: number;
+    updatedByEmail?: string | null;
+}
+export interface RaiseOperatorAlertOptions {
+    /**
+     * What makes two raises the SAME alert — a dispute id, an org and month, a
+     * check id. Absent never dedupes: every raise is told.
+     */
+    dedupeKey?: string;
+    /** Values for the definition's `{{tokens}}`. Never personal data. */
+    context?: OperatorAlertContext;
+    /** A console path or absolute URL; overrides the definition's link. */
+    url?: string;
+    /** The title as written by the caller; overrides the rendered one. */
+    subject?: string;
+    /** The body as written by the caller; overrides the rendered one. */
+    body?: string;
+    orgId?: string;
+    hostId?: string;
+}
+export type OperatorAlertOutcome = 'deduped' | 'below-threshold' | 'console-only' | 'queued' | 'delivered' | 'undelivered';
+export interface OperatorAlertResult {
+    outcome: OperatorAlertOutcome;
+    type: string;
+    email?: SendEmailResult;
+    webhook?: OperatorAlertWebhookResult;
+}
+export type OperatorAlertWebhookResult = {
+    posted: true;
+    status: number;
+} | {
+    posted: false;
+    reason: 'unconfigured' | 'refused' | 'network';
+    status?: number;
+};
+/** One alert, rendered, as it is delivered and queued. */
+export interface RenderedOperatorAlert {
+    type: string;
+    label: string;
+    tier: OperatorAlertDefinition['tier'];
+    category: OperatorAlertDefinition['category'];
+    title: string;
+    body: string;
+    /** Console path or absolute URL; `''` when there is none. */
+    link: string;
+    notificationType: AglynNotificationType;
+    orgId?: string;
+    hostId?: string;
+}
+/** Drop the in-process settings cache; the console calls it after a write. */
+export declare function invalidateOperatorAlertSettingsCache(): void;
+/** Clamps a stored settings document to what the pipeline understands. */
+export declare function normalizeOperatorAlertSettings(raw: unknown): OperatorAlertSettingsDoc;
+/**
+ * Staff's switches. An unreadable document is the coded defaults, uncached:
+ * an alert must still go out when the settings cannot be read.
+ */
+export declare function readOperatorAlertSettings(): Promise<OperatorAlertSettingsDoc>;
+export type OperatorAlertClaim = {
+    fire: true;
+    repeats: number;
+} | {
+    fire: false;
+    reason: 'deduped' | 'below-threshold';
+};
+/**
+ * Whether a raise with this key fires now. One transaction on the key's
+ * state document: inside the window after a fire it is counted and
+ * suppressed; before it reaches `minOccurrences` it is counted and held.
+ * A store that cannot be read FIRES — a duplicate beats a silence.
+ */
+export declare function claimOperatorAlert(definition: Pick<OperatorAlertDefinition, 'type' | 'dedupeWindowMinutes' | 'minOccurrences'>, dedupeKey: string, now?: number): Promise<OperatorAlertClaim>;
+/** The webhook URL, when one is configured and is http(s). */
+export declare function operatorAlertWebhookUrl(): string;
+/**
+ * The JSON the webhook receives. `text` is what a Slack-compatible incoming
+ * webhook renders on its own; `alert` carries the fields for anything that
+ * wants to route on them.
+ */
+export declare function operatorAlertWebhookPayload(alerts: readonly RenderedOperatorAlert[], options?: {
+    digest?: boolean;
+    now?: number;
+}): Record<string, unknown>;
+/**
+ * Posts alerts to `OPERATOR_ALERT_WEBHOOK_URL`, signed when
+ * `OPERATOR_ALERT_WEBHOOK_SECRET` is set: `x-operator-alert-timestamp` is the
+ * Unix time and `x-operator-alert-signature` is `sha256=` plus the hex HMAC
+ * of `{timestamp}.{body}`. Unset means email only. Never throws.
+ */
+export declare function postOperatorAlertWebhook(alerts: readonly RenderedOperatorAlert[], options?: {
+    digest?: boolean;
+    now?: number;
+}): Promise<OperatorAlertWebhookResult>;
+/** A console path as an inbox or webhook can follow it, or `''`. */
+export declare function operatorAlertAbsoluteLink(link: string | undefined | null): string;
+/** Resolves the definition a call names, registering a plugin's own. */
+export declare function resolveOperatorAlertDefinition(type: string | OperatorAlertDefinition): OperatorAlertDefinition;
+export declare function renderOperatorAlert(definition: OperatorAlertDefinition, options?: RaiseOperatorAlertOptions): RenderedOperatorAlert;
+/** See the module comment. Never throws. */
+export declare function raiseOperatorAlert(type: string | OperatorAlertDefinition, options?: RaiseOperatorAlertOptions): Promise<OperatorAlertResult>;
+/** At most this many alerts are listed in one digest; the rest are counted. */
+export declare const OPERATOR_DIGEST_MAX_LISTED = 50;
+export interface OperatorDigestResult {
+    /** Whether a digest went out (or, on a dry run, would). */
+    sent: boolean;
+    reason?: 'not-due' | 'already-sent' | 'empty' | 'dry-run' | 'unavailable';
+    count: number;
+    email?: SendEmailResult;
+    webhook?: OperatorAlertWebhookResult;
+}
+/** The state document that claims one UTC day's digest. */
+export declare function operatorDigestMarkerId(now: number): string;
+/** The digest's body: one paragraph per alert, newest last. */
+export declare function composeOperatorDigestBody(alerts: readonly RenderedOperatorAlert[], total?: number): string;
+/**
+ * Sends the day's digest once the configured hour has passed: every queued
+ * alert in one `operator-alert-digest` email and one webhook post, then
+ * clears what it sent. Once per UTC day, claimed by creating
+ * `operatorAlertState/digest-{day}`, so two ticks never both send it.
+ */
+export declare function sendOperatorAlertDigest(options?: {
+    now?: number;
+    dryRun?: boolean;
+    force?: boolean;
+}): Promise<OperatorDigestResult>;
+/** One registry entry as Staff → Operator alerts lists it. */
+export interface OperatorAlertCatalogRow {
+    type: string;
+    label: string;
+    description: string;
+    tier: OperatorAlertDefinition['tier'];
+    category: OperatorAlertDefinition['category'];
+    pluginId: string | null;
+    defaults: {
+        enabled: boolean;
+        delivery: OperatorAlertDefinition['delivery'];
+    };
+    effective: {
+        enabled: boolean;
+        delivery: OperatorAlertDefinition['delivery'];
+    };
+    /** Whether staff have answered for this type, rather than the default. */
+    overridden: boolean;
+}
+/** Every registered type with its default and its effective setting. */
+export declare function operatorAlertCatalogRows(definitions: readonly OperatorAlertDefinition[], settings: OperatorAlertSettingsDoc): OperatorAlertCatalogRow[];
+/**
+ * Sends one `[Test]` alert of a type straight to the operator's inbox and
+ * webhook, past dedupe and staff's switches, so an operator can prove the
+ * channels reach them. Writes no console notification.
+ */
+export declare function sendOperatorAlertTest(definition: OperatorAlertDefinition): Promise<{
+    email: SendEmailResult;
+    webhook: OperatorAlertWebhookResult;
+}>;
+/** Where operator mail goes, named but never listed, for the staff page. */
+export declare function describeOperatorAlertRecipients(): Promise<{
+    source: 'STAFF_ALERT_EMAIL' | 'NEXT_PUBLIC_OPERATOR_SUPPORT_EMAIL' | 'staff-accounts' | 'none';
+    count: number;
+}>;