@aglyn/shared-util-email 1.0.0-beta.203 → 1.0.0-beta.205

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

@@ -0,0 +1,204 @@
+/**
+ * @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.
+ */
+/** Every kind of risk event the platform tells people about. */
+export declare const RISK_EVENT_KINDS: readonly ["email-held", "email-released", "email-rejected", "page-held", "page-released", "page-rejected", "page-flagged", "listing-held", "listing-released", "listing-rejected", "domain-flagged", "domain-cleared", "domain-rejected", "billing-payment-flagged", "link-blocked", "card-testing", "gift-card-hold", "sale-fraud-warning", "sale-payment-review", "sale-dispute", "seller-review", "marketplace-sale-review", "marketplace-sale-warning", "publisher-payouts-held", "publisher-payouts-standard", "review-cleared", "review-upheld", "workspace-locked", "workspace-unlocked", "site-locked", "site-unlocked", "domain-locked", "domain-unlocked", "account-locked", "account-unlocked", "feature-locked", "feature-unlocked", "subscription-canceled"];
+export type RiskEventKind = (typeof RISK_EVENT_KINDS)[number];
+/** How loud a notice is. `urgent` kinds are emailed and alert staff at once. */
+export type RiskNoticeSeverity = 'info' | 'warning' | 'urgent';
+/** The actions an OWNER or ADMIN is offered. None of them releases anything. */
+export declare const RISK_OWNER_ACTION_IDS: readonly ["view-details", "edit-and-resubmit", "request-review", "refund-order", "keep-order", "answer-dispute", "update-payment-method", "view-billing", "view-holds", "view-marketplace-sales", "release-gift-cards", "contact-support"];
+export type RiskOwnerActionId = (typeof RISK_OWNER_ACTION_IDS)[number];
+/** The actions STAFF are offered: the real controls, deep-linked. */
+export declare const RISK_STAFF_ACTION_IDS: readonly ["staff-open-row", "staff-release", "staff-reject", "staff-lock-workspace", "staff-lock-site", "staff-unlock", "staff-cancel-subscription", "staff-open-stripe", "staff-view-workspace"];
+export type RiskStaffActionId = (typeof RISK_STAFF_ACTION_IDS)[number];
+/**
+ * Where each action goes, as a console path TEMPLATE. `{name}` placeholders
+ * are filled by {@link resolveRiskActionHref} from the event; an action whose
+ * placeholder has no value is dropped rather than rendered dead.
+ *
+ * Owner paths are in the stored-notification shape the console's
+ * `normalizeNotificationLink` rewrites when followed: `/org/…` becomes the
+ * reader's `/{orgSlug}/…` and `/{hostId}/…` becomes `/{orgSlug}/hosts/{sub}/…`.
+ * `{itemPath}` is the held item's own page, supplied by the signal source.
+ *
+ * `risk-notice-routes.spec.ts` (console) resolves every template to a page
+ * that exists under `apps/console/app`.
+ */
+export interface RiskActionDefinition {
+    label: string;
+    /** What happens when it is followed, for the help page and a tooltip. */
+    hint: string;
+    href: string;
+}
+export declare const RISK_OWNER_ACTIONS: Record<RiskOwnerActionId, RiskActionDefinition>;
+export declare const RISK_STAFF_ACTIONS: Record<RiskStaffActionId, RiskActionDefinition>;
+/** One audience's half of a kind. */
+export interface RiskNoticeCopy {
+    /** Short and specific. Also the email subject. */
+    title: string;
+    /** What we saw, on what, and when. */
+    summary: string;
+    /** What it means for them. */
+    meaning: string;
+    /** What to do next, in order. */
+    steps: readonly string[];
+}
+export interface RiskNoticeDefinition {
+    kind: RiskEventKind;
+    severity: RiskNoticeSeverity;
+    /**
+     * Whether the owners and admins are emailed as well as notified in the
+     * console. The email is transactional account mail from the platform's own
+     * sender: it ignores notification preferences and marketing consent, and
+     * it reaches a locked workspace.
+     */
+    emailOwners: boolean;
+    /** Whether staff are alerted. False for events staff themselves caused. */
+    alertStaff: boolean;
+    /**
+     * Whether the notice always goes out, even while the workspace is over its
+     * burst allowance. Locks, lifts and cancellations are never folded into a
+     * digest: each one changes what the owner can do.
+     */
+    neverDigest: boolean;
+    /**
+     * An owner can ask for a review. Only kinds with an abuse-queue row to
+     * append to are reviewable.
+     */
+    reviewable: boolean;
+    /** The kinds staff decisions on this kind's row close it with. */
+    closesWith?: {
+        released: RiskEventKind;
+        rejected: RiskEventKind;
+    };
+    /** Also tell the managers of the site the event is on, not just the workspace's. */
+    includeSiteManagers: boolean;
+    /** The help page section that explains it. */
+    helpAnchor: string;
+    owner: RiskNoticeCopy & {
+        actions: readonly RiskOwnerActionId[];
+    };
+    staff: Pick<RiskNoticeCopy, 'title' | 'summary'> & {
+        actions: readonly RiskStaffActionId[];
+    };
+}
+/**
+ * The customer help page every notice links to. A path on the docs site;
+ * the server prefixes the docs origin.
+ */
+export declare const RISK_NOTICE_HELP_PATH = "/help/holds-and-reviews";
+/**
+ * Merge tokens a notice may use. The server fills each from the event; a
+ * token the event does not carry renders as the fallback noted here, never
+ * as a hole in a sentence.
+ */
+export declare const RISK_NOTICE_TOKENS: {
+    readonly 'workspace.name': "The workspace name, or \"your workspace\".";
+    readonly 'item.label': "What the notice is about, in the owner's words: the campaign \"Spring sale\", the page /pricing, order 1042.";
+    readonly 'item.url': "The absolute console link to the item.";
+    readonly occurredAt: "When it happened, in UTC.";
+    readonly reference: "The case reference staff know it by (HS-…, PF-…).";
+    readonly 'holds.url': "The workspace's Holds & reviews page.";
+    readonly 'help.url': "The help page for holds and reviews.";
+    readonly 'support.email': "The operator's support address.";
+    readonly 'lock.message': "The message staff wrote when they applied the lock.";
+    readonly 'lock.affected': "What the lock or pause covers: sites, sessions, billing.";
+    readonly amount: "The payment amount, when there is one.";
+    readonly 'evidence.dueBy': "The date dispute evidence is due, when Stripe gave one.";
+    readonly 'staff.evidence': "Staff only: what the screen or Stripe reported.";
+};
+export type RiskNoticeToken = keyof typeof RISK_NOTICE_TOKENS;
+export declare const RISK_NOTICE_CATALOG: Readonly<Record<RiskEventKind, RiskNoticeDefinition>>;
+/**
+ * The kinds whose email wears the WORKSPACE's brand: routine notices about
+ * the workspace's own customers' payments, which read as the workspace's own
+ * operations. Every other kind — a hold, a lock, a lift, a cancellation, a
+ * review — is the platform acting, and is sent in the platform's brand.
+ */
+export declare const RISK_NOTICE_WORKSPACE_BRANDED: ReadonlySet<RiskEventKind>;
+/**
+ * The kinds that CLOSE another: a release, a rejection, a review's end. A
+ * closing notice never re-stamps its row, so the row keeps naming the kind
+ * it was opened as — and a second decision closes it again correctly.
+ */
+export declare const RISK_NOTICE_CLOSING_KINDS: ReadonlySet<RiskEventKind>;
+/** The catalog entry for a kind. */
+export declare function riskNoticeDefinition(kind: RiskEventKind): RiskNoticeDefinition;
+export declare function isRiskEventKind(value: unknown): value is RiskEventKind;
+/** The values a notice is rendered with. Every value is optional. */
+export type RiskNoticeValues = Partial<Record<RiskNoticeToken | 'brand.productName', string | null | undefined>>;
+/** Fill `{{token}}`s from `values`, falling back to words, never to a hole. */
+export declare function renderRiskNoticeText(template: string, values: RiskNoticeValues): string;
+/** The values an action href may use. */
+export interface RiskActionParams {
+    itemPath?: string | null;
+    noticeId?: string | null;
+    reviewId?: string | null;
+    orgId?: string | null;
+    hostId?: string | null;
+    stripeUrl?: string | null;
+    lockScope?: string | null;
+    lockTargetId?: string | null;
+}
+/**
+ * An action's href with its placeholders filled, or null when one of them
+ * has no value — an action that would lead nowhere is not offered.
+ */
+export declare function resolveRiskActionHref(action: RiskActionDefinition, params: RiskActionParams): string | null;
+/** One action, ready to render. */
+export interface ResolvedRiskAction {
+    id: RiskOwnerActionId | RiskStaffActionId;
+    label: string;
+    hint: string;
+    href: string;
+}
+/** A kind's owner actions that lead somewhere, in catalog order. */
+export declare function resolveOwnerRiskActions(kind: RiskEventKind, params: RiskActionParams): ResolvedRiskAction[];
+/** A kind's staff actions that lead somewhere, in catalog order. */
+export declare function resolveStaffRiskActions(kind: RiskEventKind, params: RiskActionParams): ResolvedRiskAction[];
+/** An owner notice as plain text: title, summary, meaning, numbered steps. */
+export declare function renderOwnerRiskNotice(kind: RiskEventKind, values: RiskNoticeValues): {
+    title: string;
+    summary: string;
+    meaning: string;
+    steps: string[];
+};
+/** A staff alert as plain text. */
+export declare function renderStaffRiskNotice(kind: RiskEventKind, values: RiskNoticeValues): {
+    title: string;
+    summary: string;
+};
+/** The System emails catalog key a kind's owner email is designed under. */
+export declare function riskNoticeEmailKey(kind: RiskEventKind): string;
+/** The key the burst digest is designed under. */
+export declare const RISK_NOTICE_DIGEST_EMAIL_KEY = "risk-digest";
+/**
+ * The kind an abuse-queue row is about, so the staff queue renders the
+ * catalog's text for EVERY row a risk source filed — including rows filed
+ * before the row carried its notice. The stamp `notifyRiskEvent` writes
+ * (`riskNotice.kind`) wins; otherwise the row's own shape says it. Null for
+ * a row from the public report form, which is not a risk event.
+ */
+export declare function riskKindForAbuseRow(row: {
+    source?: unknown;
+    heldSend?: {
+        kind?: unknown;
+    } | null;
+    riskNotice?: {
+        kind?: unknown;
+    } | null;
+}): RiskEventKind | null;