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

package/src/lib/server/render-system-email.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../../../../../../libs/tenant/data/admin/src/lib/server/render-system-email.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport {\n  EMAIL_NODE_ROOT_ID,\n  SYSTEM_EMAIL_COLLECTION,\n  buildDefaultEmailNodeMap,\n  getSystemEmailTemplate,\n  renderEmailHtml,\n  substituteMergeTokens,\n  type SystemEmailTemplateDefinition,\n} from '@aglyn/shared-util-email'\nimport { firebaseAdmin } from './firebase-admin'\nimport { platformMarketingHostId } from './platform-marketing-consent'\nimport {\n  brandMergeTokens,\n  collectReferencedComponentIds,\n  composeReusableComponentNodes,\n  decodeStoredNodes,\n  resolveBrandingProfile,\n  sanitizeAuthorHtml,\n  type ReusableComponentTree,\n} from '@aglyn/aglyn/server'\nimport {\n  hostComponentReader,\n  loadReferencedComponents,\n  type ComponentStoreLike,\n} from '@aglyn/aglyn/app-utils/load-referenced-components'\nimport {\n  PLATFORM_BRAND_MERGE_TOKENS,\n  buildSystemEmailChrome,\n  isPlatformBrandedSend,\n  type SystemEmailBrandOptions,\n} from '@aglyn/aglyn/app-utils/system-email-chrome'\n\n// Defined beside the chrome they decide, and re-exported for the callers and\n// specs that reach them through this module.\nexport { isPlatformBrandedSend }\nexport type { SystemEmailBrandOptions }\n\n/**\n * Blanks any `{{token}}` the caller did not supply.\n *\n * `substituteMergeTokens` leaves unknown tokens untouched, which is right for\n * campaigns (an author wants to see the tag they mistyped) but wrong here —\n * a system email goes to a customer, and \"You've been invited to\n * {{org.name}}\" is worse than a gap. Applied only in this resolver so\n * campaign behaviour is unchanged.\n */\nfunction blankUnresolvedTokens(value: string): string {\n  return value.replace(/\\{\\{[^}]*\\}\\}/g, '')\n}\n\n/**\n * Origin a picked image in a system email is fetched from (AGL-1224).\n *\n * A system email is staff-designed and its media lives in the platform\n * library, which the CONSOLE's `/api/media/cdn` route serves — the tenant app\n * mounts the same route, but a recipient of an org invite has no site to\n * resolve against. Same expression `app/layout.tsx` uses for the console's\n * own canonical URL, so the two cannot drift per deploy.\n */\nconst CONSOLE_ORIGIN =\n  process.env.NEXT_PUBLIC_CONSOLE_URL ?? 'https://app.aglyn.com'\n\n/**\n * Which copy a system email carries: a design staff published, or the\n * catalog's built-in copy, which is what every key without a usable design\n * sends (AGL-3322).\n */\nexport type SystemEmailSource = 'designed' | 'default'\n\nexport interface RenderedSystemEmail {\n  subject: string\n  html: string\n  text: string\n  source: SystemEmailSource\n}\n\n/**\n * A system email loaded once, ready to render for any number of recipients\n * without touching Firestore again (AGL-768): the published staff design, or\n * the catalog's built-in copy when there is none.\n */\nexport interface LoadedSystemEmail {\n  definition: SystemEmailTemplateDefinition\n  /** The design as stored, each email block still a placement; or the built-in copy's node map. */\n  nodes: Record<string, unknown>\n  subjectTemplate: string\n  preheaderTemplate: string\n  source: SystemEmailSource\n  /**\n   * The published definitions of the email blocks `nodes` places, keyed by\n   * id, read from the platform marketing site ONCE with the template\n   * (AGL-3318), so a batch composes every recipient's copy without another\n   * read. Absent when the design places none, when the deployment names no\n   * marketing site, and when the read failed; each placement then renders as\n   * nothing.\n   */\n  components?: Record<string, ReusableComponentTree>\n}\n\n/**\n * The email blocks a platform email places, read from the site that owns\n * them (AGL-3318), or `undefined` when there is nothing to read or the read\n * failed.\n *\n * WHICH SITE. A block is a reusable component, and a component belongs to a\n * site; a platform email belongs to none. The header and footer Aglyn's own\n * mail wears are the ones on its marketing site, which the deployment names\n * in `PLATFORM_MARKETING_HOST_ID`, the setting product-email consent already\n * reads. An install that names none reads nothing, and a block placed in its\n * system emails renders as nothing.\n *\n * NEVER A REASON NOT TO SEND. A site's own email fails its whole load when a\n * component read fails, and falls back to its built-in copy. Here the copy is\n * staff's design and the blocks are another site's chrome, so a failed read\n * costs the blocks and nothing else: it is logged, and the design renders\n * inside the coded header and footer instead (see\n * {@link renderLoadedSystemEmail}) rather than being traded for the built-in\n * copy. A password reset whose header could not be read still carries its\n * link.\n */\nasync function loadPlatformEmailBlocks(\n  firestore: ComponentStoreLike,\n  templateKey: string,\n  nodes: Record<string, unknown>,\n): Promise<Record<string, ReusableComponentTree> | undefined> {\n  // A design that places nothing costs nothing: no setting read, no read.\n  if (!collectReferencedComponentIds(nodes as never).size) return undefined\n  const hostId = platformMarketingHostId()\n  if (!hostId) return undefined\n  try {\n    return await loadReferencedComponents(\n      nodes,\n      hostComponentReader(firestore, hostId),\n      {\n        onSkipped: (skipped) =>\n          console.warn(\n            JSON.stringify({\n              tag: 'AGL-3318:platform-email-blocks-skipped',\n              templateKey,\n              hostId,\n              skipped,\n            }),\n          ),\n      },\n    )\n  } catch (error) {\n    console.error(\n      `system email template ${templateKey}: its email blocks failed to load from ${hostId}`,\n      error,\n    )\n    return undefined\n  }\n}\n\n/**\n * Whether one send draws the design's email blocks: a send under the\n * platform's own brand (see {@link isPlatformBrandedSend}) of a design whose\n * blocks the load could read. Every other send renders the stored nodes, each\n * block a placement that draws nothing, inside the coded chrome.\n */\nfunction drawsPlatformBlocks(\n  loaded: LoadedSystemEmail,\n  merged: Readonly<Record<string, string>>,\n  options: SystemEmailBrandOptions,\n): loaded is LoadedSystemEmail & {\n  components: Record<string, ReusableComponentTree>\n} {\n  return (\n    Boolean(loaded.components && Object.keys(loaded.components).length) &&\n    isPlatformBrandedSend(merged, options)\n  )\n}\n\n/**\n * A key's built-in copy as a loaded email (AGL-3322): the node map the editor\n * seeds a first design with, and the catalog subject. What a key sends until\n * staff publish a design, and whenever the published one cannot be read.\n */\nfunction catalogDefault(\n  definition: SystemEmailTemplateDefinition,\n): LoadedSystemEmail {\n  return {\n    definition,\n    nodes: buildDefaultEmailNodeMap(definition),\n    subjectTemplate: definition.defaultSubject,\n    preheaderTemplate: '',\n    source: 'default',\n  }\n}\n\n/**\n * Loads what a key sends — ONE Firestore read — ready to render per\n * recipient: the published staff design, or the catalog's built-in copy\n * (AGL-3322) when there is none to use (no document, no published version,\n * an empty node map, or a read failure).\n *\n * `null` only for a key that is unknown or not Resend-delivered, which has\n * nothing here to render. Split out from {@link renderSystemEmail} so a batch\n * send resolves the template once and renders it per recipient, rather than\n * one read each (AGL-768): a Firestore read per invite is fine, one per\n * recipient in a usage-email batch is not.\n *\n * Reads through the Admin SDK, which bypasses the staff-only rules on the\n * collection — the send path runs as the server, not as a signed-in user.\n *\n * A design that places email blocks costs one more read per block, from the\n * platform marketing site, made here with the template so a batch pays it\n * once too (AGL-3318). Whether a recipient's copy expands them is decided per\n * send, by {@link renderLoadedSystemEmail}.\n */\nexport async function loadSystemEmail(\n  templateKey: string,\n): Promise<LoadedSystemEmail | null> {\n  const definition = getSystemEmailTemplate(templateKey)\n  if (!definition) return null\n  // A Firebase- or Stripe-delivered email is sent by that service from its\n  // own templates, so rendering one here would produce output nothing ever\n  // sends (AGL-767).\n  if (definition.deliveredBy !== 'resend') return null\n\n  try {\n    const firestore = firebaseAdmin.app().firestore()\n    const templateRef = firestore\n      .collection(SYSTEM_EMAIL_COLLECTION)\n      .doc(templateKey)\n    const templateSnapshot = await templateRef.get()\n    if (!templateSnapshot.exists) return catalogDefault(definition)\n\n    const versionId = templateSnapshot.get('versionId')\n    // Cleared by \"reset to default\", which nulls the pointer rather than\n    // deleting the document so the audit trail survives.\n    if (!versionId) return catalogDefault(definition)\n\n    const versionSnapshot = await templateRef\n      .collection('versions')\n      .doc(String(versionId))\n      .get()\n    // BOTH stored forms (AGL-1223). The email besigner compresses like every\n    // other besigner document, and versions written before it did are still\n    // plain maps — `decodeStoredNodes` returns those unchanged.\n    //\n    // Reading raw is the failure the guard below cannot catch: over a\n    // `Buffer`, `Object.keys` counts BYTE INDICES, so the emptiness test\n    // passes and a staff-authored email renders empty rather than falling\n    // back to its built-in copy.\n    const nodes = decodeStoredNodes<Record<string, unknown>>(\n      versionSnapshot.get('nodes'),\n    )\n    if (!nodes || !Object.keys(nodes).length) return catalogDefault(definition)\n\n    const components = await loadPlatformEmailBlocks(\n      firestore,\n      templateKey,\n      nodes,\n    )\n    return {\n      definition,\n      nodes,\n      subjectTemplate:\n        String(templateSnapshot.get('subject') ?? '') ||\n        definition.defaultSubject,\n      preheaderTemplate: String(templateSnapshot.get('preheader') ?? ''),\n      source: 'designed',\n      ...(components && { components }),\n    }\n  } catch (error) {\n    // Never let a template problem block the send, or strip it bare: the\n    // recipient gets the built-in copy, in the same header and footer.\n    console.error(\n      `system email template ${templateKey} failed to load; sending its built-in copy`,\n      error,\n    )\n    return catalogDefault(definition)\n  }\n}\n\n/**\n * Renders a loaded email for one recipient's merge values (AGL-768). No\n * Firestore access — call {@link loadSystemEmail} once, then this per\n * recipient. `null` only if the renderer produced no document at all.\n *\n * Which header and footer it wears is decided here, per send, because one\n * batch-loaded design goes to recipients of different brands:\n *\n * - A send under the platform's own brand of a design whose email blocks the\n *   load read draws those blocks (AGL-3318), and nothing else: they ARE its\n *   header and footer, and a second one around them would draw both.\n * - Every other send is drawn inside {@link buildSystemEmailChrome}'s chrome\n *   (AGL-3322): the built-in copy, which places no blocks; a design sent to a\n *   white-label org's people, whose blocks stay unexpanded and draw nothing,\n *   since they are the platform's; and a design on a deployment that names no\n *   marketing site, or whose blocks could not be read. The chrome is in the\n *   brand of the send — the org's email logo rides in its header, so a\n *   white-label mail carries exactly one logo.\n */\nexport function renderLoadedSystemEmail(\n  loaded: LoadedSystemEmail,\n  merge: Record<string, string> = {},\n  options: SystemEmailBrandOptions = {},\n): RenderedSystemEmail | null {\n  const merged = { ...PLATFORM_BRAND_MERGE_TOKENS, ...merge }\n  const blocks = drawsPlatformBlocks(loaded, merged, options)\n  const rendered = renderEmailHtml({\n    nodes: (blocks\n      ? composeReusableComponentNodes(loaded.nodes as never, loaded.components)\n      : loaded.nodes) as never,\n    // Besigner maps are rooted at '_@_', not renderEmailHtml's default\n    // 'root' — without this a designed template rendered empty and the send\n    // fell back to built-in copy, so designing did nothing (AGL-765).\n    rootId: EMAIL_NODE_ROOT_ID,\n    subject: substituteMergeTokens(loaded.subjectTemplate, merged),\n    preheader: substituteMergeTokens(loaded.preheaderTemplate, merged),\n    merge: merged,\n    // The same policy the console's own preview of these nodes applies —\n    // `sanitizeCustomHtml` in the email plugin delegates to this exact\n    // function, so what staff review and what the recipient receives are one\n    // function of one string rather than two that have to be kept in step.\n    sanitize: sanitizeAuthorHtml,\n    // Without this a staff-picked image resolves to a site-relative CDN path,\n    // which is a broken-image box in the recipient's inbox (AGL-1224). The\n    // chrome's logo resolves against it too.\n    mediaOrigin: CONSOLE_ORIGIN,\n    // No `brandLogoUrl`: the org's email logo (AGL-2139) is the chrome\n    // header's logo whenever there is one to draw, and a send that draws the\n    // platform's blocks is by definition one that carries none.\n    ...(blocks\n      ? {}\n      : {\n          chrome: buildSystemEmailChrome({\n            definition: loaded.definition,\n            merged,\n            brandLogoUrl: options.brandLogoUrl,\n            brandHomeUrl: options.brandHomeUrl,\n          }),\n        }),\n  })\n  if (!rendered?.html) return null\n  return {\n    subject: blankUnresolvedTokens(\n      substituteMergeTokens(loaded.subjectTemplate, merged),\n    ),\n    html: blankUnresolvedTokens(rendered.html),\n    text: blankUnresolvedTokens(rendered.text ?? ''),\n    source: loaded.source,\n  }\n}\n\n/**\n * Renders the system email a key sends to one recipient (AGL-750): the\n * published staff design, or the catalog's built-in copy (AGL-3322), in the\n * header and footer of the brand it is sent under.\n *\n * **`null` only for a key that is unknown or not Resend-delivered**, which\n * has nothing here to render. No template document, no published version, an\n * empty node map and a Firestore failure all render the built-in copy — the\n * same copy the editor seeds a first design with — so a missing, half-saved\n * or broken template can never mean a customer receives no email, or a bare\n * one. Every caller still keeps its own hard-coded copy behind this, as the\n * last resort for a render that produced nothing.\n *\n * A single-recipient convenience over {@link loadSystemEmail} +\n * {@link renderLoadedSystemEmail}; a batch should call those two directly so\n * it reads the template once.\n */\nexport async function renderSystemEmail(\n  templateKey: string,\n  merge: Record<string, string> = {},\n  options: SystemEmailBrandOptions = {},\n): Promise<RenderedSystemEmail | null> {\n  const loaded = await loadSystemEmail(templateKey)\n  return loaded ? renderLoadedSystemEmail(loaded, merge, options) : null\n}\n\n/**\n * The email a template sends right now, for the staff test-send endpoint\n * (AGL-766): exactly what a real send of it renders — the published design,\n * or the built-in copy, with the same header and footer — so a test shows\n * what recipients receive. `null` for an unknown or non-Resend key.\n */\nexport async function renderEffectiveSystemEmail(\n  templateKey: string,\n  merge: Record<string, string> = {},\n  options: SystemEmailBrandOptions = {},\n): Promise<RenderedSystemEmail | null> {\n  return renderSystemEmail(templateKey, merge, options)\n}\n\n/**\n * The brand one system email is sent under (AGL-3367): the merge tokens, the\n * chrome options and the sender name, from one place.\n *\n * `null` is the platform's own brand, and it is the answer for everything\n * the platform says on its own behalf: a staff alert, a legal receipt, an\n * enforcement notice. A workspace-context email passes the workspace's org\n * document, and `resolveBrandingProfile` decides from there: a white-label\n * org gets its own name, logo, home and support in the header and footer,\n * and every other org resolves to the platform profile, so the same call is\n * right for both.\n */\nexport interface SystemEmailBrand {\n  merge: Record<string, string>\n  options: SystemEmailBrandOptions\n  /** The display name to send under; absent sends under the platform's. */\n  fromName?: string\n  /** The org's own name, for the `{{org.name}}` its copy may use. */\n  orgName?: string\n}\n\n/** See {@link SystemEmailBrand}. */\nexport function systemEmailBrand(\n  org: Readonly<Record<string, unknown>> | null | undefined,\n): SystemEmailBrand {\n  if (!org) return { merge: {}, options: {} }\n  const branding = resolveBrandingProfile(org as never)\n  const orgName = typeof org['name'] === 'string' ? org['name'].trim() : ''\n  return {\n    ...(orgName ? { orgName } : {}),\n    merge: brandMergeTokens(branding),\n    options: {\n      brandLogoUrl: branding.emailLogoUrl,\n      brandHomeUrl: branding.homeUrl,\n    },\n    fromName: branding.fromName,\n  }\n}\n\n/**\n * {@link systemEmailBrand} for an org read by id, for a sender that holds\n * only the id. A failed or missing read is the platform's brand: the email\n * still goes, and a white-label org's people see the platform's chrome on\n * one message rather than no message.\n */\nexport async function orgSystemEmailBrand(\n  orgId: string | null | undefined,\n): Promise<SystemEmailBrand> {\n  if (!orgId) return systemEmailBrand(null)\n  try {\n    const snapshot = await firebaseAdmin\n      .app()\n      .firestore()\n      .collection('orgs')\n      .doc(orgId)\n      .get()\n    return systemEmailBrand(snapshot.exists ? (snapshot.data() ?? null) : null)\n  } catch (error) {\n    console.error(`system email brand for org ${orgId} failed to load`, error)\n    return systemEmailBrand(null)\n  }\n}\n\n/** What a send takes from a rendered system email. */\nexport interface SystemEmailContent {\n  subject: string\n  text: string\n  html?: string\n}\n\n/**\n * The subject, text and HTML to send, with the caller's own copy as the\n * last resort for a render that produced nothing: the shape every sender of\n * a system email repeats, written once.\n */\nexport function systemEmailContent(\n  rendered: RenderedSystemEmail | null,\n  fallback: { subject: string; text: string },\n): SystemEmailContent {\n  return {\n    subject: rendered?.subject || fallback.subject,\n    text: rendered?.text || fallback.text,\n    ...(rendered?.html ? { html: rendered.html } : {}),\n  }\n}\n\n/**\n * Renders a key for one recipient in a brand and returns what to send\n * (AGL-3367): {@link renderSystemEmail} and {@link systemEmailContent} in\n * one call, for the senders with one message to build. Never throws; a\n * render that fails sends the fallback copy, which is what it sent before.\n */\nexport async function renderSystemEmailContent(\n  templateKey: string,\n  merge: Record<string, string>,\n  brand: SystemEmailBrand,\n  fallback: { subject: string; text: string },\n): Promise<SystemEmailContent> {\n  const rendered = await renderSystemEmail(\n    templateKey,\n    { ...brand.merge, ...merge },\n    brand.options,\n  ).catch((error) => {\n    console.error(`system email ${templateKey} failed to render`, error)\n    return null\n  })\n  return systemEmailContent(rendered, fallback)\n}\n\nexport default renderSystemEmail\n"],"names":["process","EMAIL_NODE_ROOT_ID","SYSTEM_EMAIL_COLLECTION","buildDefaultEmailNodeMap","getSystemEmailTemplate","renderEmailHtml","substituteMergeTokens","firebaseAdmin","platformMarketingHostId","brandMergeTokens","collectReferencedComponentIds","composeReusableComponentNodes","decodeStoredNodes","resolveBrandingProfile","sanitizeAuthorHtml","hostComponentReader","loadReferencedComponents","PLATFORM_BRAND_MERGE_TOKENS","buildSystemEmailChrome","isPlatformBrandedSend","blankUnresolvedTokens","value","replace","CONSOLE_ORIGIN","env","NEXT_PUBLIC_CONSOLE_URL","loadPlatformEmailBlocks","firestore","templateKey","nodes","size","undefined","hostId","onSkipped","skipped","console","warn","JSON","stringify","tag","error","drawsPlatformBlocks","loaded","merged","options","Boolean","components","Object","keys","length","catalogDefault","definition","subjectTemplate","defaultSubject","preheaderTemplate","source","loadSystemEmail","deliveredBy","templateSnapshot","app","templateRef","collection","doc","get","exists","versionId","versionSnapshot","String","renderLoadedSystemEmail","merge","rendered","blocks","rootId","subject","preheader","sanitize","mediaOrigin","chrome","brandLogoUrl","brandHomeUrl","html","text","renderSystemEmail","renderEffectiveSystemEmail","systemEmailBrand","org","branding","orgName","trim","emailLogoUrl","homeUrl","fromName","orgSystemEmailBrand","orgId","snapshot","data","systemEmailContent","fallback","renderSystemEmailContent","brand","catch"],"mappings":"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"}
+{"version":3,"sources":["../../../../../../../../libs/tenant/data/admin/src/lib/server/render-system-email.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport {\n  EMAIL_NODE_ROOT_ID,\n  PLATFORM_EMAIL_PALETTE,\n  chromeForDesign,\n  SYSTEM_EMAIL_COLLECTION,\n  buildEmailPalette,\n  buildDefaultEmailNodeMap,\n  getSystemEmailTemplate,\n  renderEmailHtml,\n  substituteMergeTokens,\n  type EmailTheme,\n  type SystemEmailTemplateDefinition,\n} from '@aglyn/shared-util-email'\nimport { firebaseAdmin } from './firebase-admin'\nimport { platformMarketingHostId } from './platform-marketing-consent'\nimport {\n  brandMergeTokens,\n  collectReferencedComponentIds,\n  composeReusableComponentNodes,\n  decodeStoredNodes,\n  resolveBrandingProfile,\n  sanitizeAuthorHtml,\n  type ReusableComponentTree,\n} from '@aglyn/aglyn/server'\nimport {\n  hostComponentReader,\n  loadReferencedComponents,\n  type ComponentStoreLike,\n} from '@aglyn/aglyn/app-utils/load-referenced-components'\nimport {\n  PLATFORM_BRAND_MERGE_TOKENS,\n  buildSystemEmailChrome,\n  isPlatformBrandedSend,\n  type SystemEmailBrandOptions,\n} from '@aglyn/aglyn/app-utils/system-email-chrome'\n\n// Defined beside the chrome they decide, and re-exported for the callers and\n// specs that reach them through this module.\nexport { isPlatformBrandedSend }\nexport type { SystemEmailBrandOptions }\n\n/**\n * Blanks any `{{token}}` the caller did not supply.\n *\n * `substituteMergeTokens` leaves unknown tokens untouched, which is right for\n * campaigns (an author wants to see the tag they mistyped) but wrong here —\n * a system email goes to a customer, and \"You've been invited to\n * {{org.name}}\" is worse than a gap. Applied only in this resolver so\n * campaign behaviour is unchanged.\n */\nfunction blankUnresolvedTokens(value: string): string {\n  return value.replace(/\\{\\{[^}]*\\}\\}/g, '')\n}\n\n/**\n * Origin a picked image in a system email is fetched from (AGL-1224).\n *\n * A system email is staff-designed and its media lives in the platform\n * library, which the CONSOLE's `/api/media/cdn` route serves — the tenant app\n * mounts the same route, but a recipient of an org invite has no site to\n * resolve against. Same expression `app/layout.tsx` uses for the console's\n * own canonical URL, so the two cannot drift per deploy.\n */\nconst CONSOLE_ORIGIN =\n  process.env.NEXT_PUBLIC_CONSOLE_URL ?? 'https://app.aglyn.com'\n\n/**\n * Which copy a system email carries: a design staff published, or the\n * catalog's built-in copy, which is what every key without a usable design\n * sends (AGL-3322).\n */\nexport type SystemEmailSource = 'designed' | 'default'\n\nexport interface RenderedSystemEmail {\n  subject: string\n  html: string\n  text: string\n  source: SystemEmailSource\n}\n\n/**\n * A system email loaded once, ready to render for any number of recipients\n * without touching Firestore again (AGL-768): the published staff design, or\n * the catalog's built-in copy when there is none.\n */\nexport interface LoadedSystemEmail {\n  definition: SystemEmailTemplateDefinition\n  /** The design as stored, each email block still a placement; or the built-in copy's node map. */\n  nodes: Record<string, unknown>\n  subjectTemplate: string\n  preheaderTemplate: string\n  source: SystemEmailSource\n  /**\n   * The published definitions of the email blocks `nodes` places, keyed by\n   * id, read from the platform marketing site ONCE with the template\n   * (AGL-3318), so a batch composes every recipient's copy without another\n   * read. Absent when the design places none, when the deployment names no\n   * marketing site, and when the read failed; each placement then renders as\n   * nothing.\n   */\n  components?: Record<string, ReusableComponentTree>\n}\n\n/**\n * The email blocks a platform email places, read from the site that owns\n * them (AGL-3318), or `undefined` when there is nothing to read or the read\n * failed.\n *\n * WHICH SITE. A block is a reusable component, and a component belongs to a\n * site; a platform email belongs to none. The header and footer Aglyn's own\n * mail wears are the ones on its marketing site, which the deployment names\n * in `PLATFORM_MARKETING_HOST_ID`, the setting product-email consent already\n * reads. An install that names none reads nothing, and a block placed in its\n * system emails renders as nothing.\n *\n * NEVER A REASON NOT TO SEND. A site's own email fails its whole load when a\n * component read fails, and falls back to its built-in copy. Here the copy is\n * staff's design and the blocks are another site's chrome, so a failed read\n * costs the blocks and nothing else: it is logged, and the design renders\n * inside the coded header and footer instead (see\n * {@link renderLoadedSystemEmail}) rather than being traded for the built-in\n * copy. A password reset whose header could not be read still carries its\n * link.\n */\nasync function loadPlatformEmailBlocks(\n  firestore: ComponentStoreLike,\n  templateKey: string,\n  nodes: Record<string, unknown>,\n): Promise<Record<string, ReusableComponentTree> | undefined> {\n  // A design that places nothing costs nothing: no setting read, no read.\n  if (!collectReferencedComponentIds(nodes as never).size) return undefined\n  const hostId = platformMarketingHostId()\n  if (!hostId) return undefined\n  try {\n    return await loadReferencedComponents(\n      nodes,\n      hostComponentReader(firestore, hostId),\n      {\n        onSkipped: (skipped) =>\n          console.warn(\n            JSON.stringify({\n              tag: 'AGL-3318:platform-email-blocks-skipped',\n              templateKey,\n              hostId,\n              skipped,\n            }),\n          ),\n      },\n    )\n  } catch (error) {\n    console.error(\n      `system email template ${templateKey}: its email blocks failed to load from ${hostId}`,\n      error,\n    )\n    return undefined\n  }\n}\n\n/**\n * Whether one send draws the design's email blocks: a send under the\n * platform's own brand (see {@link isPlatformBrandedSend}) of a design whose\n * blocks the load could read. Every other send renders the stored nodes, each\n * block a placement that draws nothing, inside the coded chrome.\n */\nfunction drawsPlatformBlocks(\n  loaded: LoadedSystemEmail,\n  merged: Readonly<Record<string, string>>,\n  options: SystemEmailBrandOptions,\n): loaded is LoadedSystemEmail & {\n  components: Record<string, ReusableComponentTree>\n} {\n  return (\n    Boolean(loaded.components && Object.keys(loaded.components).length) &&\n    isPlatformBrandedSend(merged, options)\n  )\n}\n\n/**\n * A key's built-in copy as a loaded email (AGL-3322): the node map the editor\n * seeds a first design with, and the catalog subject. What a key sends until\n * staff publish a design, and whenever the published one cannot be read.\n */\nfunction catalogDefault(\n  definition: SystemEmailTemplateDefinition,\n): LoadedSystemEmail {\n  return {\n    definition,\n    nodes: buildDefaultEmailNodeMap(definition),\n    subjectTemplate: definition.defaultSubject,\n    preheaderTemplate: '',\n    source: 'default',\n  }\n}\n\n/**\n * Loads what a key sends — ONE Firestore read — ready to render per\n * recipient: the published staff design, or the catalog's built-in copy\n * (AGL-3322) when there is none to use (no document, no published version,\n * an empty node map, or a read failure).\n *\n * `null` only for a key that is unknown or not Resend-delivered, which has\n * nothing here to render. Split out from {@link renderSystemEmail} so a batch\n * send resolves the template once and renders it per recipient, rather than\n * one read each (AGL-768): a Firestore read per invite is fine, one per\n * recipient in a usage-email batch is not.\n *\n * Reads through the Admin SDK, which bypasses the staff-only rules on the\n * collection — the send path runs as the server, not as a signed-in user.\n *\n * A design that places email blocks costs one more read per block, from the\n * platform marketing site, made here with the template so a batch pays it\n * once too (AGL-3318). Whether a recipient's copy expands them is decided per\n * send, by {@link renderLoadedSystemEmail}.\n */\nexport async function loadSystemEmail(\n  templateKey: string,\n): Promise<LoadedSystemEmail | null> {\n  const definition = getSystemEmailTemplate(templateKey)\n  if (!definition) return null\n  // A Firebase- or Stripe-delivered email is sent by that service from its\n  // own templates, so rendering one here would produce output nothing ever\n  // sends (AGL-767).\n  if (definition.deliveredBy !== 'resend') return null\n\n  try {\n    const firestore = firebaseAdmin.app().firestore()\n    const templateRef = firestore\n      .collection(SYSTEM_EMAIL_COLLECTION)\n      .doc(templateKey)\n    const templateSnapshot = await templateRef.get()\n    if (!templateSnapshot.exists) return catalogDefault(definition)\n\n    const versionId = templateSnapshot.get('versionId')\n    // Cleared by \"reset to default\", which nulls the pointer rather than\n    // deleting the document so the audit trail survives.\n    if (!versionId) return catalogDefault(definition)\n\n    const versionSnapshot = await templateRef\n      .collection('versions')\n      .doc(String(versionId))\n      .get()\n    // BOTH stored forms (AGL-1223). The email besigner compresses like every\n    // other besigner document, and versions written before it did are still\n    // plain maps — `decodeStoredNodes` returns those unchanged.\n    //\n    // Reading raw is the failure the guard below cannot catch: over a\n    // `Buffer`, `Object.keys` counts BYTE INDICES, so the emptiness test\n    // passes and a staff-authored email renders empty rather than falling\n    // back to its built-in copy.\n    const nodes = decodeStoredNodes<Record<string, unknown>>(\n      versionSnapshot.get('nodes'),\n    )\n    if (!nodes || !Object.keys(nodes).length) return catalogDefault(definition)\n\n    const components = await loadPlatformEmailBlocks(\n      firestore,\n      templateKey,\n      nodes,\n    )\n    return {\n      definition,\n      nodes,\n      subjectTemplate:\n        String(templateSnapshot.get('subject') ?? '') ||\n        definition.defaultSubject,\n      preheaderTemplate: String(templateSnapshot.get('preheader') ?? ''),\n      source: 'designed',\n      ...(components && { components }),\n    }\n  } catch (error) {\n    // Never let a template problem block the send, or strip it bare: the\n    // recipient gets the built-in copy, in the same header and footer.\n    console.error(\n      `system email template ${templateKey} failed to load; sending its built-in copy`,\n      error,\n    )\n    return catalogDefault(definition)\n  }\n}\n\n/**\n * The theme a system email is drawn in (AGL-3370): the console's palette,\n * or, for a white-label org that set a brand color, the same palette with\n * that color as its primary. Buttons use the console's corner radius.\n */\nfunction systemEmailTheme(options: SystemEmailBrandOptions): EmailTheme {\n  const primaryColor = String(options.brandPrimaryColor ?? '').trim()\n  return {\n    palette: primaryColor\n      ? buildEmailPalette({ base: 'platform', primaryColor })\n      : PLATFORM_EMAIL_PALETTE,\n    buttonRadius: 4,\n  }\n}\n\n/**\n * Renders a loaded email for one recipient's merge values (AGL-768). No\n * Firestore access — call {@link loadSystemEmail} once, then this per\n * recipient. `null` only if the renderer produced no document at all.\n *\n * Which header and footer it wears is decided here, per send, because one\n * batch-loaded design goes to recipients of different brands:\n *\n * - A send under the platform's own brand of a design whose email blocks the\n *   load read draws those blocks (AGL-3318), and nothing else: they ARE its\n *   header and footer, and a second one around them would draw both.\n * - Every other send is drawn inside {@link buildSystemEmailChrome}'s chrome\n *   (AGL-3322): the built-in copy, which places no blocks; a design sent to a\n *   white-label org's people, whose blocks stay unexpanded and draw nothing,\n *   since they are the platform's; and a design on a deployment that names no\n *   marketing site, or whose blocks could not be read. The chrome is in the\n *   brand of the send — the org's email logo rides in its header, so a\n *   white-label mail carries exactly one logo.\n *\n * Either way, a band the design draws itself is left out of the chrome\n * (AGL-3372): a design that opens with its own Header gets the footer only.\n */\nexport function renderLoadedSystemEmail(\n  loaded: LoadedSystemEmail,\n  merge: Record<string, string> = {},\n  options: SystemEmailBrandOptions = {},\n): RenderedSystemEmail | null {\n  const merged = { ...PLATFORM_BRAND_MERGE_TOKENS, ...merge }\n  const blocks = drawsPlatformBlocks(loaded, merged, options)\n  const nodes = (\n    blocks\n      ? composeReusableComponentNodes(loaded.nodes as never, loaded.components)\n      : loaded.nodes\n  ) as Record<string, unknown>\n  // The brand's chrome around every copy, less any band the design draws\n  // itself (AGL-3372). Unexpanded placements draw nothing in this send, so\n  // they only count when the blocks are drawn.\n  const chrome = chromeForDesign({\n    stored: blocks ? loaded.nodes : null,\n    composed: nodes,\n    chrome: buildSystemEmailChrome({\n      definition: loaded.definition,\n      merged,\n      brandLogoUrl: options.brandLogoUrl,\n      brandHomeUrl: options.brandHomeUrl,\n    }),\n  })\n  const rendered = renderEmailHtml({\n    nodes: nodes as never,\n    // Besigner maps are rooted at '_@_', not renderEmailHtml's default\n    // 'root' — without this a designed template rendered empty and the send\n    // fell back to built-in copy, so designing did nothing (AGL-765).\n    rootId: EMAIL_NODE_ROOT_ID,\n    subject: substituteMergeTokens(loaded.subjectTemplate, merged),\n    preheader: substituteMergeTokens(loaded.preheaderTemplate, merged),\n    merge: merged,\n    // The same policy the console's own preview of these nodes applies —\n    // `sanitizeCustomHtml` in the email plugin delegates to this exact\n    // function, so what staff review and what the recipient receives are one\n    // function of one string rather than two that have to be kept in step.\n    sanitize: sanitizeAuthorHtml,\n    // Without this a staff-picked image resolves to a site-relative CDN path,\n    // which is a broken-image box in the recipient's inbox (AGL-1224). The\n    // chrome's logo resolves against it too.\n    mediaOrigin: CONSOLE_ORIGIN,\n    // In the console's theme (AGL-3370), under a white-label org's own color\n    // when it set one: a color staff picked in the Besigner is a palette\n    // token, and a button nobody colored wears the brand's accent.\n    ...systemEmailTheme(options),\n    // No `brandLogoUrl`: the org's email logo (AGL-2139) is the chrome\n    // header's logo whenever there is one to draw, and a send that draws the\n    // platform's blocks is by definition one that carries none.\n    ...(chrome ? { chrome } : {}),\n  })\n  if (!rendered?.html) return null\n  return {\n    subject: blankUnresolvedTokens(\n      substituteMergeTokens(loaded.subjectTemplate, merged),\n    ),\n    html: blankUnresolvedTokens(rendered.html),\n    text: blankUnresolvedTokens(rendered.text ?? ''),\n    source: loaded.source,\n  }\n}\n\n/**\n * Renders the system email a key sends to one recipient (AGL-750): the\n * published staff design, or the catalog's built-in copy (AGL-3322), in the\n * header and footer of the brand it is sent under.\n *\n * **`null` only for a key that is unknown or not Resend-delivered**, which\n * has nothing here to render. No template document, no published version, an\n * empty node map and a Firestore failure all render the built-in copy — the\n * same copy the editor seeds a first design with — so a missing, half-saved\n * or broken template can never mean a customer receives no email, or a bare\n * one. Every caller still keeps its own hard-coded copy behind this, as the\n * last resort for a render that produced nothing.\n *\n * A single-recipient convenience over {@link loadSystemEmail} +\n * {@link renderLoadedSystemEmail}; a batch should call those two directly so\n * it reads the template once.\n */\nexport async function renderSystemEmail(\n  templateKey: string,\n  merge: Record<string, string> = {},\n  options: SystemEmailBrandOptions = {},\n): Promise<RenderedSystemEmail | null> {\n  const loaded = await loadSystemEmail(templateKey)\n  return loaded ? renderLoadedSystemEmail(loaded, merge, options) : null\n}\n\n/**\n * The email a template sends right now, for the staff test-send endpoint\n * (AGL-766): exactly what a real send of it renders — the published design,\n * or the built-in copy, with the same header and footer — so a test shows\n * what recipients receive. `null` for an unknown or non-Resend key.\n */\nexport async function renderEffectiveSystemEmail(\n  templateKey: string,\n  merge: Record<string, string> = {},\n  options: SystemEmailBrandOptions = {},\n): Promise<RenderedSystemEmail | null> {\n  return renderSystemEmail(templateKey, merge, options)\n}\n\n/**\n * The brand one system email is sent under (AGL-3367): the merge tokens, the\n * chrome options and the sender name, from one place.\n *\n * `null` is the platform's own brand, and it is the answer for everything\n * the platform says on its own behalf: a staff alert, a legal receipt, an\n * enforcement notice. A workspace-context email passes the workspace's org\n * document, and `resolveBrandingProfile` decides from there: a white-label\n * org gets its own name, logo, home and support in the header and footer,\n * and every other org resolves to the platform profile, so the same call is\n * right for both.\n */\nexport interface SystemEmailBrand {\n  merge: Record<string, string>\n  options: SystemEmailBrandOptions\n  /** The display name to send under; absent sends under the platform's. */\n  fromName?: string\n  /** The org's own name, for the `{{org.name}}` its copy may use. */\n  orgName?: string\n}\n\n/** See {@link SystemEmailBrand}. */\nexport function systemEmailBrand(\n  org: Readonly<Record<string, unknown>> | null | undefined,\n): SystemEmailBrand {\n  if (!org) return { merge: {}, options: {} }\n  const branding = resolveBrandingProfile(org as never)\n  const orgName = typeof org['name'] === 'string' ? org['name'].trim() : ''\n  return {\n    ...(orgName ? { orgName } : {}),\n    merge: brandMergeTokens(branding),\n    options: {\n      brandLogoUrl: branding.emailLogoUrl,\n      brandHomeUrl: branding.homeUrl,\n      brandPrimaryColor: branding.primaryColor,\n    },\n    fromName: branding.fromName,\n  }\n}\n\n/**\n * {@link systemEmailBrand} for an org read by id, for a sender that holds\n * only the id. A failed or missing read is the platform's brand: the email\n * still goes, and a white-label org's people see the platform's chrome on\n * one message rather than no message.\n */\nexport async function orgSystemEmailBrand(\n  orgId: string | null | undefined,\n): Promise<SystemEmailBrand> {\n  if (!orgId) return systemEmailBrand(null)\n  try {\n    const snapshot = await firebaseAdmin\n      .app()\n      .firestore()\n      .collection('orgs')\n      .doc(orgId)\n      .get()\n    return systemEmailBrand(snapshot.exists ? (snapshot.data() ?? null) : null)\n  } catch (error) {\n    console.error(`system email brand for org ${orgId} failed to load`, error)\n    return systemEmailBrand(null)\n  }\n}\n\n/** What a send takes from a rendered system email. */\nexport interface SystemEmailContent {\n  subject: string\n  text: string\n  html?: string\n}\n\n/**\n * The subject, text and HTML to send, with the caller's own copy as the\n * last resort for a render that produced nothing: the shape every sender of\n * a system email repeats, written once.\n */\nexport function systemEmailContent(\n  rendered: RenderedSystemEmail | null,\n  fallback: { subject: string; text: string },\n): SystemEmailContent {\n  return {\n    subject: rendered?.subject || fallback.subject,\n    text: rendered?.text || fallback.text,\n    ...(rendered?.html ? { html: rendered.html } : {}),\n  }\n}\n\n/**\n * Renders a key for one recipient in a brand and returns what to send\n * (AGL-3367): {@link renderSystemEmail} and {@link systemEmailContent} in\n * one call, for the senders with one message to build. Never throws; a\n * render that fails sends the fallback copy, which is what it sent before.\n */\nexport async function renderSystemEmailContent(\n  templateKey: string,\n  merge: Record<string, string>,\n  brand: SystemEmailBrand,\n  fallback: { subject: string; text: string },\n): Promise<SystemEmailContent> {\n  const rendered = await renderSystemEmail(\n    templateKey,\n    { ...brand.merge, ...merge },\n    brand.options,\n  ).catch((error) => {\n    console.error(`system email ${templateKey} failed to render`, error)\n    return null\n  })\n  return systemEmailContent(rendered, fallback)\n}\n\nexport default renderSystemEmail\n"],"names":["process","EMAIL_NODE_ROOT_ID","PLATFORM_EMAIL_PALETTE","chromeForDesign","SYSTEM_EMAIL_COLLECTION","buildEmailPalette","buildDefaultEmailNodeMap","getSystemEmailTemplate","renderEmailHtml","substituteMergeTokens","firebaseAdmin","platformMarketingHostId","brandMergeTokens","collectReferencedComponentIds","composeReusableComponentNodes","decodeStoredNodes","resolveBrandingProfile","sanitizeAuthorHtml","hostComponentReader","loadReferencedComponents","PLATFORM_BRAND_MERGE_TOKENS","buildSystemEmailChrome","isPlatformBrandedSend","blankUnresolvedTokens","value","replace","CONSOLE_ORIGIN","env","NEXT_PUBLIC_CONSOLE_URL","loadPlatformEmailBlocks","firestore","templateKey","nodes","size","undefined","hostId","onSkipped","skipped","console","warn","JSON","stringify","tag","error","drawsPlatformBlocks","loaded","merged","options","Boolean","components","Object","keys","length","catalogDefault","definition","subjectTemplate","defaultSubject","preheaderTemplate","source","loadSystemEmail","deliveredBy","templateSnapshot","app","templateRef","collection","doc","get","exists","versionId","versionSnapshot","String","systemEmailTheme","primaryColor","brandPrimaryColor","trim","palette","base","buttonRadius","renderLoadedSystemEmail","merge","rendered","blocks","chrome","stored","composed","brandLogoUrl","brandHomeUrl","rootId","subject","preheader","sanitize","mediaOrigin","html","text","renderSystemEmail","renderEffectiveSystemEmail","systemEmailBrand","org","branding","orgName","emailLogoUrl","homeUrl","fromName","orgSystemEmailBrand","orgId","snapshot","data","systemEmailContent","fallback","renderSystemEmailContent","brand","catch"],"mappings":"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"}

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'];