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

package/src/lib/server/risk-notice.d.ts

@@ -0,0 +1,327 @@
+/**
+ * @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 ResolvedRiskAction, type RiskEventKind } from '@aglyn/shared-util-email/risk-notice-catalog';
+import { type SendEmailOptions, type SendEmailResult } from '@aglyn/shared-util-email';
+import { type HeldPageSubject, type HeldPageTarget, type PageHoldNoticeKind } from '@aglyn/shared-util-email/held-page';
+import { type NotificationPayload, type NotifyUsersOptions } from './notifications';
+import { type SystemEmailBrand } from './render-system-email';
+/** Admin-SDK only; no client rule opens it. One document per notice. */
+export declare const RISK_NOTICE_COLLECTION = "riskNotices";
+/** Admin-SDK only: each workspace's burst window and folded notices. */
+export declare const RISK_NOTICE_LEDGER_COLLECTION = "riskNoticeLedger";
+/** The in-app notification type every owner notice is written as. */
+export declare const RISK_NOTICE_NOTIFICATION_TYPE: "system.riskNotice";
+/**
+ * The burst allowance: how many notices one workspace's owners, and staff
+ * about one workspace, receive one by one in {@link RISK_NOTICE_BURST.windowMs}
+ * before the rest are folded into a digest.
+ */
+export declare const RISK_NOTICE_BURST: {
+    readonly owners: 5;
+    readonly staff: 10;
+    readonly windowMs: number;
+    /** How many folded notices a digest lists by name. */
+    readonly digestListMax: 25;
+};
+/** Longest review-request note stored. */
+export declare const RISK_REVIEW_NOTE_MAX = 2000;
+/** How many review requests one row keeps. */
+export declare const RISK_REVIEW_REQUESTS_MAX = 20;
+/** How soon the same workspace may ask again about the same row. */
+export declare const RISK_REVIEW_REQUEST_COOLDOWN_MS: number;
+/** What a source knows about the thing the notice is about. */
+export interface RiskEventItem {
+    /** In the owner's words: `the campaign "Spring sale"`, `order 1042`. */
+    label: string;
+    /**
+     * Its console page, in the stored-notification shape (`/org/…` or
+     * `/{hostId}/…`) the console rewrites when the link is followed.
+     */
+    path?: string | null;
+}
+export interface RiskEventInput {
+    kind: RiskEventKind;
+    orgId: string | null;
+    hostId?: string | null;
+    /** An account lock's person. */
+    userUid?: string | null;
+    /** The abuse-queue row, when the event has one. */
+    reviewId?: string | null;
+    reference?: string | null;
+    item?: RiskEventItem | null;
+    occurredAtMs?: number;
+    /** `$56.00 USD`. */
+    amount?: string | null;
+    evidenceDueByMs?: number | null;
+    /** Staff only: the Stripe Dashboard page for the charge, review or dispute. */
+    stripeUrl?: string | null;
+    lock?: {
+        /** The customer-facing message the lock stores, verbatim. */
+        message?: string | null;
+        /** What the lock or pause covers, in plain words. */
+        affected?: string | null;
+        scope?: string | null;
+        targetId?: string | null;
+    } | null;
+    /**
+     * A held or flagged page, described (AGL-3374). Stored on the notice so
+     * the console can put the hold on the page, template, layout or component
+     * it is about, and name it there. Owner-safe: no signal, no evidence.
+     */
+    page?: HeldPageSubject | null;
+    /** Staff only: what the screen or Stripe reported. Never shown to owners. */
+    staffEvidence?: string | null;
+    /** Overrides the default dedupe key. */
+    dedupeKey?: string | null;
+    /**
+     * `false` to send no owner EMAIL for this event (a lock placed under a
+     * legal hold). The in-app notice and the record are still written.
+     */
+    emailOwners?: boolean;
+    /**
+     * Exactly who the owner half goes to, in place of the workspace's owners
+     * and admins: a batch that already resolved its people and groups several
+     * events into one notice per person (the lockdown's "Resend owner
+     * notice").
+     */
+    recipients?: ReadonlyArray<{
+        uid: string;
+        email: string | null;
+    }>;
+}
+export interface RiskNoticeDelivery {
+    /** How many people the owner half was for. */
+    recipients: number;
+    /** In-app notifications written (before per-person mutes). */
+    inApp: number;
+    emailed: number;
+    emailFailed: number;
+    /** Why no email went, when none did. */
+    emailSkipped: string | null;
+    /** Folded into the next digest instead of delivered now. */
+    digested: boolean;
+}
+export interface RiskNoticeResult {
+    noticeId: string | null;
+    /** The same notice was already delivered: nothing was sent now. */
+    duplicate: boolean;
+    owners: RiskNoticeDelivery;
+    staff: {
+        alerted: boolean;
+        digested: boolean;
+    };
+    /** Set when the notice could not be processed at all. */
+    error: string | null;
+}
+/** Everything the seam touches, injectable for specs. */
+export interface RiskNoticeDeps {
+    firestore: FirebaseFirestore.Firestore;
+    sendEmail: (options: SendEmailOptions) => Promise<SendEmailResult>;
+    notifyUsers: (uids: Iterable<string>, payload: NotificationPayload, options?: NotifyUsersOptions) => Promise<void>;
+    notifyStaff: (payload: NotificationPayload) => Promise<void>;
+    listOwners: (orgId: string) => Promise<Array<{
+        uid: string;
+        email: string | null;
+    }>>;
+    lookupEmail: (uid: string) => Promise<string | null>;
+    nowMs: () => number;
+}
+/** The help page every notice links, on the docs site. */
+export declare function riskNoticeHelpUrl(anchor?: string): string;
+/** `Sep 28, 2026, 16:31 UTC` — one format for every notice. */
+export declare function formatRiskNoticeTime(ms: number): string;
+/** The id of the notice a dedupe key names: hex, like the abuse queue's. */
+export declare function riskNoticeId(dedupeKey: string): string;
+/** The default dedupe key: one notice per kind per row, else per event. */
+export declare function riskNoticeDedupeKey(input: RiskEventInput, occurredAtMs: number): string;
+/** The console path an owner's Holds & reviews page is at, in stored shape. */
+export declare function riskHoldsPath(noticeId?: string | null): string;
+/** A staff deep link to one abuse-queue row. */
+export declare function staffAbuseRowPath(reviewId: string): string;
+/**
+ * Stored-shape site paths (`/{hostId}/…`) as console routes, for a reader
+ * with no org context of its own — staff reading the abuse queue
+ * (AGL-3374). One read of the sites and one of their workspaces for the
+ * whole batch; a path that cannot be resolved is left out.
+ */
+export declare function resolveHostConsolePaths(firestore: FirebaseFirestore.Firestore, entries: ReadonlyArray<{
+    hostId: string;
+    orgId?: string | null;
+    path: string;
+}>): Promise<Map<string, string>>;
+/** What one notice email sends. */
+export interface RenderedRiskNoticeEmail {
+    key: string;
+    subject: string;
+    text: string;
+    html?: string;
+    /** The display name to send under; absent sends under the platform's. */
+    fromName?: string;
+}
+/**
+ * The brand a kind's email is sent in: the workspace's own for a routine
+ * notice about its customers' payments, the platform's for everything the
+ * platform does (holds, locks, lifts, cancellations, reviews).
+ */
+export declare function riskNoticeEmailBrand(kind: RiskEventKind | null, orgId: string | null): Promise<SystemEmailBrand>;
+/**
+ * Renders one notice email through the System emails seam (AGL-3367): the
+ * published design for the kind's own `risk-…` key, or its built-in copy,
+ * inside the header and footer every platform email wears. The plain-text
+ * composition below is the last resort for a render that produced nothing.
+ * ONE function, so every notice renders the same way.
+ */
+export declare function renderRiskNoticeEmail(key: string, merge: Record<string, string>, brand?: SystemEmailBrand): Promise<RenderedRiskNoticeEmail>;
+/**
+ * Tell the right people about one risk event. See the module header.
+ * Never throws.
+ */
+export declare function notifyRiskEvent(input: RiskEventInput, overrides?: Partial<RiskNoticeDeps>): Promise<RiskNoticeResult>;
+/**
+ * Send every digest whose hour has closed (the hourly cron). Returns how
+ * many went out. Never throws.
+ */
+export declare function flushRiskNoticeDigests(overrides?: Partial<RiskNoticeDeps>): Promise<{
+    flushed: number;
+    failed: number;
+}>;
+/**
+ * The closing notice for a row staff decided: the kind the row's opening
+ * notice names in `closesWith`, sent to the same people about the same item.
+ * Silent (returns null) for a row with no risk notice or a kind that does
+ * not close. Never throws.
+ */
+export declare function closeRiskNotice(input: {
+    reviewId: string;
+    decision: 'released' | 'rejected';
+}, overrides?: Partial<RiskNoticeDeps>): Promise<RiskNoticeResult | null>;
+/** A review request as it is stored on the abuse-queue row. */
+export interface RiskReviewRequest {
+    atMs: number;
+    uid: string;
+    email: string | null;
+    note: string;
+    noticeId: string;
+}
+export type RiskReviewRequestOutcome = {
+    ok: true;
+    reference: string | null;
+    requestedAtMs: number;
+} | {
+    ok: false;
+    status: 400 | 404 | 409 | 429;
+    error: string;
+};
+/**
+ * An owner or admin asks for a review of a held or flagged item.
+ *
+ * APPENDS to the item's existing abuse-queue row — never a new row, and
+ * never a decision: the row's `status` and its `heldSend` are not written
+ * here, so no request can release a hold or lift a lock. Staff see the
+ * request as a note on the row, and are notified with a link to it.
+ */
+export declare function requestRiskReview(input: {
+    orgId: string;
+    noticeId: string;
+    uid: string;
+    email: string | null;
+    note: string;
+}, overrides?: Partial<RiskNoticeDeps>): Promise<RiskReviewRequestOutcome>;
+/** One owner notice, as the Holds & reviews page renders it. */
+export interface OwnerRiskNoticeView {
+    noticeId: string;
+    kind: RiskEventKind;
+    severity: string;
+    title: string;
+    summary: string;
+    meaning: string;
+    steps: string[];
+    actions: ResolvedRiskAction[];
+    reference: string | null;
+    occurredAtMs: number;
+    helpUrl: string;
+    /** The review state, for a notice with a row. */
+    status: 'held' | 'in-review' | 'released' | 'rejected' | 'closed' | null;
+    reviewable: boolean;
+    reviewRequests: Array<{
+        atMs: number;
+        note: string;
+        mine: boolean;
+    }>;
+    /** A page notice: the page by name, where it lives, and what visitors see (AGL-3374). */
+    page: OwnerPageHoldFacts | null;
+}
+/** A page notice's facts, as every owner surface renders them (AGL-3374). */
+export interface OwnerPageHoldFacts {
+    /** `the "Video detail" template (/videos/:slug)`. */
+    label: string;
+    /** Where it was seen, and the layout or component the content lives in. */
+    details: string[];
+    /** What visitors receive meanwhile. */
+    visitorSentence: string;
+    /** The page, and the layout or component, the hold is shown on. */
+    targets: HeldPageTarget[];
+}
+/**
+ * A page notice's facts from its stored subject, or — for a notice written
+ * before notices carried one — from its label and item path. Pure.
+ */
+export declare function ownerPageHoldFacts(kind: string, notice: {
+    page?: unknown;
+    ownerValues?: unknown;
+    actionParams?: unknown;
+}): OwnerPageHoldFacts | null;
+/** One open page hold on a site, as the site's console surfaces show it (AGL-3374). */
+export interface PageHoldView extends OwnerPageHoldFacts {
+    noticeId: string;
+    kind: PageHoldNoticeKind;
+    status: OwnerRiskNoticeView['status'];
+    /** The status chip. Never paired with a release control. */
+    chip: {
+        label: string;
+        color: 'warning' | 'error' | 'info';
+    };
+    reference: string | null;
+    occurredAtMs: number;
+    /** Whether a review can be requested on it (the viewer's role decides the rest). */
+    reviewable: boolean;
+    /** When anyone on the workspace last asked for a review, if they did. */
+    reviewRequestedAtMs: number | null;
+}
+/**
+ * Every page on a site that is held, flagged or not approved (AGL-3374): the
+ * `riskNotices` of the two page kinds for this host, newest first — one
+ * query on (`hostId`, `kind`, `createdAtMs`), which
+ * `cloud/firebase-firestore.indexes.json` holds — and each notice's row for
+ * its state. A released or cleared page is not listed.
+ */
+export declare function listHostPageHolds(input: {
+    hostId: string;
+    limit?: number;
+}, overrides?: Partial<RiskNoticeDeps>): Promise<PageHoldView[]>;
+/**
+ * The workspace's notices, newest first, rendered for its owners: the
+ * catalog's owner half only, and the row's decision state — never its
+ * evidence, never its staff notes.
+ */
+export declare function listOwnerRiskNotices(input: {
+    orgId: string;
+    viewerUid: string;
+    limit?: number;
+}, overrides?: Partial<RiskNoticeDeps>): Promise<OwnerRiskNoticeView[]>;
+/** A row's state in the owner's words. Pure. */
+export declare function ownerRowStatus(row: Pick<FirebaseFirestore.DocumentSnapshot, 'get'>): OwnerRiskNoticeView['status'];