@aglyn/aglyn 1.0.0-beta.199 → 1.0.0-beta.201

package/src/lib/app-utils/email-search.d.ts

@@ -0,0 +1,36 @@
+/**
+ * @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.
+ */
+/**
+ * The `array-contains` search tokens for an address (AGL-3321).
+ *
+ * Every prefix, up to `NAME_TOKEN_MAX_PREFIX` characters, of each of: the
+ * whole address, the domain, the domain behind an `@`, and each piece of the
+ * local part and of the domain. So `jane.doe@mail.example.com` is found by
+ * `jane`, `doe`, `jane.doe@ma`, `example`, `mail.example` and `@mail`, and
+ * `dana@example.com` by `example.com`. A query becomes one token through
+ * `nameSearchToken`, which caps it at the same length, so a typed address
+ * longer than that narrows by its first twelve characters rather than
+ * matching nothing.
+ *
+ * Pure and SDK-free, so a browser list and a server writer stamp the same
+ * array: the staff suppressions list (`emailTokens`) and the commerce orders
+ * list (`customerEmailTokens`) both search an address through it. Each has a
+ * backfill that restates it for the documents written before its field —
+ * `tools/scripts/backfill-email-suppression-filters.mjs` and
+ * `tools/scripts/backfill-orders-list-fields.mjs` — held to shared fixtures.
+ */
+export declare function emailSearchTokens(email: string | null | undefined): string[];

package/src/lib/app-utils/email-search.js

@@ -0,0 +1,53 @@
+/**
+ * @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 { nameSearchTokens } from "./name-search.js";
+/**
+ * The `array-contains` search tokens for an address (AGL-3321).
+ *
+ * Every prefix, up to `NAME_TOKEN_MAX_PREFIX` characters, of each of: the
+ * whole address, the domain, the domain behind an `@`, and each piece of the
+ * local part and of the domain. So `jane.doe@mail.example.com` is found by
+ * `jane`, `doe`, `jane.doe@ma`, `example`, `mail.example` and `@mail`, and
+ * `dana@example.com` by `example.com`. A query becomes one token through
+ * `nameSearchToken`, which caps it at the same length, so a typed address
+ * longer than that narrows by its first twelve characters rather than
+ * matching nothing.
+ *
+ * Pure and SDK-free, so a browser list and a server writer stamp the same
+ * array: the staff suppressions list (`emailTokens`) and the commerce orders
+ * list (`customerEmailTokens`) both search an address through it. Each has a
+ * backfill that restates it for the documents written before its field —
+ * `tools/scripts/backfill-email-suppression-filters.mjs` and
+ * `tools/scripts/backfill-orders-list-fields.mjs` — held to shared fixtures.
+ */ export function emailSearchTokens(email) {
+    const address = String(email != null ? email : '').trim().toLowerCase();
+    if (!address) return [];
+    const at = address.lastIndexOf('@');
+    const local = at === -1 ? address : address.slice(0, at);
+    const domain = at === -1 ? '' : address.slice(at + 1);
+    const words = [
+        address,
+        ...domain ? [
+            domain,
+            `@${domain}`
+        ] : [],
+        ...local.split(/[._+-]+/),
+        ...domain.split('.')
+    ];
+    return nameSearchTokens(words.filter(Boolean).join(' '));
+}
+
+//# sourceMappingURL=email-search.js.map

package/src/lib/app-utils/email-search.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/email-search.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 { nameSearchTokens } from './name-search'\n\n/**\n * The `array-contains` search tokens for an address (AGL-3321).\n *\n * Every prefix, up to `NAME_TOKEN_MAX_PREFIX` characters, of each of: the\n * whole address, the domain, the domain behind an `@`, and each piece of the\n * local part and of the domain. So `jane.doe@mail.example.com` is found by\n * `jane`, `doe`, `jane.doe@ma`, `example`, `mail.example` and `@mail`, and\n * `dana@example.com` by `example.com`. A query becomes one token through\n * `nameSearchToken`, which caps it at the same length, so a typed address\n * longer than that narrows by its first twelve characters rather than\n * matching nothing.\n *\n * Pure and SDK-free, so a browser list and a server writer stamp the same\n * array: the staff suppressions list (`emailTokens`) and the commerce orders\n * list (`customerEmailTokens`) both search an address through it. Each has a\n * backfill that restates it for the documents written before its field —\n * `tools/scripts/backfill-email-suppression-filters.mjs` and\n * `tools/scripts/backfill-orders-list-fields.mjs` — held to shared fixtures.\n */\nexport function emailSearchTokens(email: string | null | undefined): string[] {\n  const address = String(email ?? '')\n    .trim()\n    .toLowerCase()\n  if (!address) return []\n  const at = address.lastIndexOf('@')\n  const local = at === -1 ? address : address.slice(0, at)\n  const domain = at === -1 ? '' : address.slice(at + 1)\n  const words = [\n    address,\n    ...(domain ? [domain, `@${domain}`] : []),\n    ...local.split(/[._+-]+/),\n    ...domain.split('.'),\n  ]\n  return nameSearchTokens(words.filter(Boolean).join(' '))\n}\n"],"names":["nameSearchTokens","emailSearchTokens","email","address","String","trim","toLowerCase","at","lastIndexOf","local","slice","domain","words","split","filter","Boolean","join"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED,SAASA,gBAAgB,QAAQ,mBAAe;AAEhD;;;;;;;;;;;;;;;;;;CAkBC,GACD,OAAO,SAASC,kBAAkBC,KAAgC;IAChE,MAAMC,UAAUC,OAAOF,gBAAAA,QAAS,IAC7BG,IAAI,GACJC,WAAW;IACd,IAAI,CAACH,SAAS,OAAO,EAAE;IACvB,MAAMI,KAAKJ,QAAQK,WAAW,CAAC;IAC/B,MAAMC,QAAQF,OAAO,CAAC,IAAIJ,UAAUA,QAAQO,KAAK,CAAC,GAAGH;IACrD,MAAMI,SAASJ,OAAO,CAAC,IAAI,KAAKJ,QAAQO,KAAK,CAACH,KAAK;IACnD,MAAMK,QAAQ;QACZT;WACIQ,SAAS;YAACA;YAAQ,CAAC,CAAC,EAAEA,QAAQ;SAAC,GAAG,EAAE;WACrCF,MAAMI,KAAK,CAAC;WACZF,OAAOE,KAAK,CAAC;KACjB;IACD,OAAOb,iBAAiBY,MAAME,MAAM,CAACC,SAASC,IAAI,CAAC;AACrD"}

package/src/lib/app-utils/email-state.d.ts

@@ -15,10 +15,14 @@
  * limitations under the License.
  */
 /** Every state, weakest first. */
-export declare const EMAIL_STATE_STATUSES: readonly ["ok", "bounced", "blocked", "unsubscribed", "complained", "do_not_contact"];
+export declare const EMAIL_STATE_STATUSES: readonly ["ok", "undeliverable", "bounced", "blocked", "unsubscribed", "complained", "do_not_contact"];
 export type EmailStateStatus = (typeof EMAIL_STATE_STATUSES)[number];
-/** Which sender's verdict it is. */
-export type EmailStateSource = 'sequence' | 'campaign' | 'member';
+/**
+ * Which sender's verdict it is. `check` is the deliverability check
+ * (AGL-3328), which reads the domain's DNS when the record is captured and
+ * before a send, and says what it found before anything bounces.
+ */
+export type EmailStateSource = 'sequence' | 'campaign' | 'member' | 'check';
 /** The field on the lead and the contact. */
 export declare const EMAIL_STATE_FIELD = "emailState";
 export interface EmailState {

package/src/lib/app-utils/email-state.js

@@ -37,15 +37,28 @@ import { _ as _extends } from "@swc/helpers/_/_extends";
  * overwrites a refusal on its own: the ranking below decides.
  *==========================================*/ /** Every state, weakest first. */ export const EMAIL_STATE_STATUSES = [
     /** The address may be emailed: released, or confirmed again. */ 'ok',
+    /**
+   * Mail to it WOULD bounce: its domain has no mail server, or publishes a
+   * null MX (AGL-3328). A prediction from DNS rather than a bounce, so the
+   * weakest refusal: any real verdict replaces it, and the check clears it
+   * when the domain starts taking mail.
+   */ 'undeliverable',
     /** Mail to it bounced for good: the mailbox does not exist. */ 'bounced',
     /** The recipient's mail gateway refused the sender on policy or reputation. */ 'blocked',
     /** The unsubscribe link or header was used. */ 'unsubscribed',
     /** A reply called the email spam, or the recipient reported it. */ 'complained',
     /** On the organization's do-not-contact list — a member's or the runtime's entry. */ 'do_not_contact'
 ];
+const EMAIL_STATE_SOURCES = [
+    'sequence',
+    'campaign',
+    'member',
+    'check'
+];
 /** The field on the lead and the contact. */ export const EMAIL_STATE_FIELD = 'emailState';
 /** How a state reads on the chip — typed so a state cannot ship unlabeled. */ export const EMAIL_STATE_LABELS = {
     ok: 'Email OK',
+    undeliverable: 'Would bounce',
     bounced: 'Bounced',
     blocked: 'Blocked by their mail gateway',
     unsubscribed: 'Unsubscribed',
@@ -60,11 +73,12 @@ import { _ as _extends } from "@swc/helpers/_/_extends";
  * over nothing — a release is written on purpose, by a path that forces it.
  */ const EMAIL_STATE_RANK = {
     ok: 0,
-    bounced: 1,
-    blocked: 2,
-    unsubscribed: 3,
-    complained: 4,
-    do_not_contact: 5
+    undeliverable: 1,
+    bounced: 2,
+    blocked: 3,
+    unsubscribed: 4,
+    complained: 5,
+    do_not_contact: 6
 };
 export function isEmailStateStatus(value) {
     return typeof value === 'string' && EMAIL_STATE_STATUSES.includes(value);
@@ -80,7 +94,7 @@ export function isEmailStateStatus(value) {
     return _extends({
         status: state['status'],
         atMs: Number.isFinite(atMs) && atMs > 0 ? atMs : 0,
-        source: source === 'sequence' || source === 'campaign' || source === 'member' ? source : 'campaign',
+        source: EMAIL_STATE_SOURCES.includes(source) ? source : 'campaign',
         detail: typeof state['detail'] === 'string' && state['detail'] ? state['detail'] : null
     }, enrollmentId ? {
         enrollmentId
@@ -118,6 +132,8 @@ export function isEmailStateStatus(value) {
     const since = when ? ` on ${when}` : '';
     const said = state.detail ? ` ${state.detail}` : '';
     switch(state.status){
+        case 'undeliverable':
+            return `Email to this address would bounce: its domain has no mail server${since ? ` (checked${since})` : ''}.${said}`;
         case 'bounced':
             return `Email to this address bounced${since}: the mailbox does not exist.${said}`;
         case 'blocked':

package/src/lib/app-utils/email-state.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/email-state.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\n/*==========================================\n * A RECORD'S EMAIL STATE (AGL-3245).\n *\n * The lists the senders consult — the platform suppression list, a site's\n * suppressions, an organization's do-not-contact list — are keyed by a\n * hash nobody can read. The record a person opens is the lead or the\n * contact, and until now it said nothing: an address that hard-bounced at\n * 10:30 still read as \"Sent\" at 12:30, and a member reading it would have\n * emailed the person again by hand.\n *\n * So the record carries `emailState`: what the last verdict on its address\n * was, when, from which sender, and in the sender's own words. It is\n * WRITTEN BY THE PLATFORM ONLY — the outreach runtime, the campaign\n * webhook, a member's do-not-contact mark — never by a form, an import or\n * the record's own editor, and the rules hold clients off the field. It\n * is a mirror of the lists, not a list: a send still asks the lists, and\n * the record says what they hold in words a person can act on.\n *\n * Absent means nothing is known. `ok` is a verdict too — a release, a\n * confirmed re-subscription — and it is the one state that never\n * overwrites a refusal on its own: the ranking below decides.\n *==========================================*/\n\n/** Every state, weakest first. */\nexport const EMAIL_STATE_STATUSES = [\n  /** The address may be emailed: released, or confirmed again. */\n  'ok',\n  /** Mail to it bounced for good: the mailbox does not exist. */\n  'bounced',\n  /** The recipient's mail gateway refused the sender on policy or reputation. */\n  'blocked',\n  /** The unsubscribe link or header was used. */\n  'unsubscribed',\n  /** A reply called the email spam, or the recipient reported it. */\n  'complained',\n  /** On the organization's do-not-contact list — a member's or the runtime's entry. */\n  'do_not_contact',\n] as const\n\nexport type EmailStateStatus = (typeof EMAIL_STATE_STATUSES)[number]\n\n/** Which sender's verdict it is. */\nexport type EmailStateSource = 'sequence' | 'campaign' | 'member'\n\n/** The field on the lead and the contact. */\nexport const EMAIL_STATE_FIELD = 'emailState'\n\nexport interface EmailState {\n  status: EmailStateStatus\n  /** When the verdict was given, epoch ms. */\n  atMs: number\n  source: EmailStateSource\n  /** The sender's own words: the bounce's diagnostic, a member's note. */\n  detail: string | null\n  /** The sequence enrollment it came from, when one did. */\n  enrollmentId?: string\n}\n\n/** How a state reads on the chip — typed so a state cannot ship unlabeled. */\nexport const EMAIL_STATE_LABELS: Record<EmailStateStatus, string> = {\n  ok: 'Email OK',\n  bounced: 'Bounced',\n  blocked: 'Blocked by their mail gateway',\n  unsubscribed: 'Unsubscribed',\n  complained: 'Marked as spam',\n  do_not_contact: 'Do not contact',\n}\n\n/**\n * The rank a later verdict must reach to replace an earlier one. A member's\n * do-not-contact mark stands over every automatic verdict; a complaint\n * over an unsubscribe, which is the person's own act over a server's; a\n * block over a bounce, since the block names the whole domain; and `ok`\n * over nothing — a release is written on purpose, by a path that forces it.\n */\nconst EMAIL_STATE_RANK: Record<EmailStateStatus, number> = {\n  ok: 0,\n  bounced: 1,\n  blocked: 2,\n  unsubscribed: 3,\n  complained: 4,\n  do_not_contact: 5,\n}\n\nexport function isEmailStateStatus(value: unknown): value is EmailStateStatus {\n  return typeof value === 'string' && (EMAIL_STATE_STATUSES as readonly string[]).includes(value)\n}\n\n/** The state a record holds, held to its shape, or `null` when it holds none. */\nexport function readEmailState(record: Record<string, unknown> | null | undefined): EmailState | null {\n  const raw = record?.[EMAIL_STATE_FIELD]\n  if (!raw || typeof raw !== 'object') return null\n  const state = raw as Record<string, unknown>\n  if (!isEmailStateStatus(state['status'])) return null\n  const atMs = Number(state['atMs'])\n  const source = state['source']\n  const enrollmentId = typeof state['enrollmentId'] === 'string' && state['enrollmentId'] ? state['enrollmentId'] : undefined\n  return {\n    status: state['status'],\n    atMs: Number.isFinite(atMs) && atMs > 0 ? atMs : 0,\n    source: source === 'sequence' || source === 'campaign' || source === 'member' ? source : 'campaign',\n    detail: typeof state['detail'] === 'string' && state['detail'] ? state['detail'] : null,\n    ...(enrollmentId ? { enrollmentId } : {}),\n  }\n}\n\n/** Whether the state means the address must not be emailed by hand. */\nexport function emailStateForbidsEmail(state: EmailState | null | undefined): boolean {\n  return Boolean(state) && state?.status !== 'ok'\n}\n\n/**\n * The state a record holds after one more verdict: the incoming one when it\n * ranks at least as high as the current — a fresh bounce replaces an old\n * one, a block replaces a bounce, a member's mark replaces anything — else\n * the current. `force` writes the incoming state whatever stands, which is\n * how a release lands.\n */\nexport function nextEmailState(\n  current: EmailState | null | undefined,\n  incoming: EmailState,\n  options: { force?: boolean } = {},\n): EmailState {\n  if (!current || options.force) return incoming\n  return EMAIL_STATE_RANK[incoming.status] >= EMAIL_STATE_RANK[current.status] ? incoming : current\n}\n\n/** When the verdict was given, as the chip's tooltip and the refusal say it. */\nexport function emailStateWhen(state: Pick<EmailState, 'atMs'>): string {\n  if (!state.atMs) return ''\n  try {\n    return new Intl.DateTimeFormat('en-US', { dateStyle: 'medium' }).format(state.atMs)\n  } catch {\n    return new Date(state.atMs).toDateString()\n  }\n}\n\n/**\n * Why the record must not be emailed, in one sentence a disabled button or\n * a refused enrollment can show — or `null` when it may be.\n */\nexport function emailStateRefusal(state: EmailState | null | undefined): string | null {\n  if (!state || !emailStateForbidsEmail(state)) return null\n  const when = emailStateWhen(state)\n  const since = when ? ` on ${when}` : ''\n  const said = state.detail ? ` ${state.detail}` : ''\n  switch (state.status) {\n    case 'bounced':\n      return `Email to this address bounced${since}: the mailbox does not exist.${said}`\n    case 'blocked':\n      return `Their mail gateway blocked email to this address${since}.${said}`\n    case 'unsubscribed':\n      return `They unsubscribed${since}.${said}`\n    case 'complained':\n      return `They marked an email as spam${since}.${said}`\n    case 'do_not_contact':\n      return `On the do-not-contact list${since}.${said}`\n    default:\n      return null\n  }\n}\n"],"names":["EMAIL_STATE_STATUSES","EMAIL_STATE_FIELD","EMAIL_STATE_LABELS","ok","bounced","blocked","unsubscribed","complained","do_not_contact","EMAIL_STATE_RANK","isEmailStateStatus","value","includes","readEmailState","record","raw","state","atMs","Number","source","enrollmentId","undefined","status","isFinite","detail","emailStateForbidsEmail","Boolean","nextEmailState","current","incoming","options","force","emailStateWhen","Intl","DateTimeFormat","dateStyle","format","Date","toDateString","emailStateRefusal","when","since","said"],"mappings":"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"}
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/email-state.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\n/*==========================================\n * A RECORD'S EMAIL STATE (AGL-3245).\n *\n * The lists the senders consult — the platform suppression list, a site's\n * suppressions, an organization's do-not-contact list — are keyed by a\n * hash nobody can read. The record a person opens is the lead or the\n * contact, and until now it said nothing: an address that hard-bounced at\n * 10:30 still read as \"Sent\" at 12:30, and a member reading it would have\n * emailed the person again by hand.\n *\n * So the record carries `emailState`: what the last verdict on its address\n * was, when, from which sender, and in the sender's own words. It is\n * WRITTEN BY THE PLATFORM ONLY — the outreach runtime, the campaign\n * webhook, a member's do-not-contact mark — never by a form, an import or\n * the record's own editor, and the rules hold clients off the field. It\n * is a mirror of the lists, not a list: a send still asks the lists, and\n * the record says what they hold in words a person can act on.\n *\n * Absent means nothing is known. `ok` is a verdict too — a release, a\n * confirmed re-subscription — and it is the one state that never\n * overwrites a refusal on its own: the ranking below decides.\n *==========================================*/\n\n/** Every state, weakest first. */\nexport const EMAIL_STATE_STATUSES = [\n  /** The address may be emailed: released, or confirmed again. */\n  'ok',\n  /**\n   * Mail to it WOULD bounce: its domain has no mail server, or publishes a\n   * null MX (AGL-3328). A prediction from DNS rather than a bounce, so the\n   * weakest refusal: any real verdict replaces it, and the check clears it\n   * when the domain starts taking mail.\n   */\n  'undeliverable',\n  /** Mail to it bounced for good: the mailbox does not exist. */\n  'bounced',\n  /** The recipient's mail gateway refused the sender on policy or reputation. */\n  'blocked',\n  /** The unsubscribe link or header was used. */\n  'unsubscribed',\n  /** A reply called the email spam, or the recipient reported it. */\n  'complained',\n  /** On the organization's do-not-contact list — a member's or the runtime's entry. */\n  'do_not_contact',\n] as const\n\nexport type EmailStateStatus = (typeof EMAIL_STATE_STATUSES)[number]\n\n/**\n * Which sender's verdict it is. `check` is the deliverability check\n * (AGL-3328), which reads the domain's DNS when the record is captured and\n * before a send, and says what it found before anything bounces.\n */\nexport type EmailStateSource = 'sequence' | 'campaign' | 'member' | 'check'\n\nconst EMAIL_STATE_SOURCES: readonly EmailStateSource[] = ['sequence', 'campaign', 'member', 'check']\n\n/** The field on the lead and the contact. */\nexport const EMAIL_STATE_FIELD = 'emailState'\n\nexport interface EmailState {\n  status: EmailStateStatus\n  /** When the verdict was given, epoch ms. */\n  atMs: number\n  source: EmailStateSource\n  /** The sender's own words: the bounce's diagnostic, a member's note. */\n  detail: string | null\n  /** The sequence enrollment it came from, when one did. */\n  enrollmentId?: string\n}\n\n/** How a state reads on the chip — typed so a state cannot ship unlabeled. */\nexport const EMAIL_STATE_LABELS: Record<EmailStateStatus, string> = {\n  ok: 'Email OK',\n  undeliverable: 'Would bounce',\n  bounced: 'Bounced',\n  blocked: 'Blocked by their mail gateway',\n  unsubscribed: 'Unsubscribed',\n  complained: 'Marked as spam',\n  do_not_contact: 'Do not contact',\n}\n\n/**\n * The rank a later verdict must reach to replace an earlier one. A member's\n * do-not-contact mark stands over every automatic verdict; a complaint\n * over an unsubscribe, which is the person's own act over a server's; a\n * block over a bounce, since the block names the whole domain; and `ok`\n * over nothing — a release is written on purpose, by a path that forces it.\n */\nconst EMAIL_STATE_RANK: Record<EmailStateStatus, number> = {\n  ok: 0,\n  undeliverable: 1,\n  bounced: 2,\n  blocked: 3,\n  unsubscribed: 4,\n  complained: 5,\n  do_not_contact: 6,\n}\n\nexport function isEmailStateStatus(value: unknown): value is EmailStateStatus {\n  return typeof value === 'string' && (EMAIL_STATE_STATUSES as readonly string[]).includes(value)\n}\n\n/** The state a record holds, held to its shape, or `null` when it holds none. */\nexport function readEmailState(record: Record<string, unknown> | null | undefined): EmailState | null {\n  const raw = record?.[EMAIL_STATE_FIELD]\n  if (!raw || typeof raw !== 'object') return null\n  const state = raw as Record<string, unknown>\n  if (!isEmailStateStatus(state['status'])) return null\n  const atMs = Number(state['atMs'])\n  const source = state['source']\n  const enrollmentId = typeof state['enrollmentId'] === 'string' && state['enrollmentId'] ? state['enrollmentId'] : undefined\n  return {\n    status: state['status'],\n    atMs: Number.isFinite(atMs) && atMs > 0 ? atMs : 0,\n    source: (EMAIL_STATE_SOURCES as readonly unknown[]).includes(source) ? (source as EmailStateSource) : 'campaign',\n    detail: typeof state['detail'] === 'string' && state['detail'] ? state['detail'] : null,\n    ...(enrollmentId ? { enrollmentId } : {}),\n  }\n}\n\n/** Whether the state means the address must not be emailed by hand. */\nexport function emailStateForbidsEmail(state: EmailState | null | undefined): boolean {\n  return Boolean(state) && state?.status !== 'ok'\n}\n\n/**\n * The state a record holds after one more verdict: the incoming one when it\n * ranks at least as high as the current — a fresh bounce replaces an old\n * one, a block replaces a bounce, a member's mark replaces anything — else\n * the current. `force` writes the incoming state whatever stands, which is\n * how a release lands.\n */\nexport function nextEmailState(\n  current: EmailState | null | undefined,\n  incoming: EmailState,\n  options: { force?: boolean } = {},\n): EmailState {\n  if (!current || options.force) return incoming\n  return EMAIL_STATE_RANK[incoming.status] >= EMAIL_STATE_RANK[current.status] ? incoming : current\n}\n\n/** When the verdict was given, as the chip's tooltip and the refusal say it. */\nexport function emailStateWhen(state: Pick<EmailState, 'atMs'>): string {\n  if (!state.atMs) return ''\n  try {\n    return new Intl.DateTimeFormat('en-US', { dateStyle: 'medium' }).format(state.atMs)\n  } catch {\n    return new Date(state.atMs).toDateString()\n  }\n}\n\n/**\n * Why the record must not be emailed, in one sentence a disabled button or\n * a refused enrollment can show — or `null` when it may be.\n */\nexport function emailStateRefusal(state: EmailState | null | undefined): string | null {\n  if (!state || !emailStateForbidsEmail(state)) return null\n  const when = emailStateWhen(state)\n  const since = when ? ` on ${when}` : ''\n  const said = state.detail ? ` ${state.detail}` : ''\n  switch (state.status) {\n    case 'undeliverable':\n      return `Email to this address would bounce: its domain has no mail server${since ? ` (checked${since})` : ''}.${said}`\n    case 'bounced':\n      return `Email to this address bounced${since}: the mailbox does not exist.${said}`\n    case 'blocked':\n      return `Their mail gateway blocked email to this address${since}.${said}`\n    case 'unsubscribed':\n      return `They unsubscribed${since}.${said}`\n    case 'complained':\n      return `They marked an email as spam${since}.${said}`\n    case 'do_not_contact':\n      return `On the do-not-contact list${since}.${said}`\n    default:\n      return null\n  }\n}\n"],"names":["EMAIL_STATE_STATUSES","EMAIL_STATE_SOURCES","EMAIL_STATE_FIELD","EMAIL_STATE_LABELS","ok","undeliverable","bounced","blocked","unsubscribed","complained","do_not_contact","EMAIL_STATE_RANK","isEmailStateStatus","value","includes","readEmailState","record","raw","state","atMs","Number","source","enrollmentId","undefined","status","isFinite","detail","emailStateForbidsEmail","Boolean","nextEmailState","current","incoming","options","force","emailStateWhen","Intl","DateTimeFormat","dateStyle","format","Date","toDateString","emailStateRefusal","when","since","said"],"mappings":";AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;;;;;;;;;;;;;4CAqB4C,GAE5C,gCAAgC,GAChC,OAAO,MAAMA,uBAAuB;IAClC,8DAA8D,GAC9D;IACA;;;;;GAKC,GACD;IACA,6DAA6D,GAC7D;IACA,6EAA6E,GAC7E;IACA,6CAA6C,GAC7C;IACA,iEAAiE,GACjE;IACA,mFAAmF,GACnF;CACD,CAAS;AAWV,MAAMC,sBAAmD;IAAC;IAAY;IAAY;IAAU;CAAQ;AAEpG,2CAA2C,GAC3C,OAAO,MAAMC,oBAAoB,aAAY;AAa7C,4EAA4E,GAC5E,OAAO,MAAMC,qBAAuD;IAClEC,IAAI;IACJC,eAAe;IACfC,SAAS;IACTC,SAAS;IACTC,cAAc;IACdC,YAAY;IACZC,gBAAgB;AAClB,EAAC;AAED;;;;;;CAMC,GACD,MAAMC,mBAAqD;IACzDP,IAAI;IACJC,eAAe;IACfC,SAAS;IACTC,SAAS;IACTC,cAAc;IACdC,YAAY;IACZC,gBAAgB;AAClB;AAEA,OAAO,SAASE,mBAAmBC,KAAc;IAC/C,OAAO,OAAOA,UAAU,YAAY,AAACb,qBAA2Cc,QAAQ,CAACD;AAC3F;AAEA,+EAA+E,GAC/E,OAAO,SAASE,eAAeC,MAAkD;IAC/E,MAAMC,MAAMD,0BAAAA,MAAQ,CAACd,kBAAkB;IACvC,IAAI,CAACe,OAAO,OAAOA,QAAQ,UAAU,OAAO;IAC5C,MAAMC,QAAQD;IACd,IAAI,CAACL,mBAAmBM,KAAK,CAAC,SAAS,GAAG,OAAO;IACjD,MAAMC,OAAOC,OAAOF,KAAK,CAAC,OAAO;IACjC,MAAMG,SAASH,KAAK,CAAC,SAAS;IAC9B,MAAMI,eAAe,OAAOJ,KAAK,CAAC,eAAe,KAAK,YAAYA,KAAK,CAAC,eAAe,GAAGA,KAAK,CAAC,eAAe,GAAGK;IAClH,OAAO;QACLC,QAAQN,KAAK,CAAC,SAAS;QACvBC,MAAMC,OAAOK,QAAQ,CAACN,SAASA,OAAO,IAAIA,OAAO;QACjDE,QAAQ,AAACpB,oBAA2Ca,QAAQ,CAACO,UAAWA,SAA8B;QACtGK,QAAQ,OAAOR,KAAK,CAAC,SAAS,KAAK,YAAYA,KAAK,CAAC,SAAS,GAAGA,KAAK,CAAC,SAAS,GAAG;OAC/EI,eAAe;QAAEA;IAAa,IAAI,CAAC;AAE3C;AAEA,qEAAqE,GACrE,OAAO,SAASK,uBAAuBT,KAAoC;IACzE,OAAOU,QAAQV,UAAUA,CAAAA,yBAAAA,MAAOM,MAAM,MAAK;AAC7C;AAEA;;;;;;CAMC,GACD,OAAO,SAASK,eACdC,OAAsC,EACtCC,QAAoB,EACpBC,UAA+B,CAAC,CAAC;IAEjC,IAAI,CAACF,WAAWE,QAAQC,KAAK,EAAE,OAAOF;IACtC,OAAOpB,gBAAgB,CAACoB,SAASP,MAAM,CAAC,IAAIb,gBAAgB,CAACmB,QAAQN,MAAM,CAAC,GAAGO,WAAWD;AAC5F;AAEA,8EAA8E,GAC9E,OAAO,SAASI,eAAehB,KAA+B;IAC5D,IAAI,CAACA,MAAMC,IAAI,EAAE,OAAO;IACxB,IAAI;QACF,OAAO,IAAIgB,KAAKC,cAAc,CAAC,SAAS;YAAEC,WAAW;QAAS,GAAGC,MAAM,CAACpB,MAAMC,IAAI;IACpF,EAAE,eAAM;QACN,OAAO,IAAIoB,KAAKrB,MAAMC,IAAI,EAAEqB,YAAY;IAC1C;AACF;AAEA;;;CAGC,GACD,OAAO,SAASC,kBAAkBvB,KAAoC;IACpE,IAAI,CAACA,SAAS,CAACS,uBAAuBT,QAAQ,OAAO;IACrD,MAAMwB,OAAOR,eAAehB;IAC5B,MAAMyB,QAAQD,OAAO,CAAC,IAAI,EAAEA,MAAM,GAAG;IACrC,MAAME,OAAO1B,MAAMQ,MAAM,GAAG,CAAC,CAAC,EAAER,MAAMQ,MAAM,EAAE,GAAG;IACjD,OAAQR,MAAMM,MAAM;QAClB,KAAK;YACH,OAAO,CAAC,iEAAiE,EAAEmB,QAAQ,CAAC,SAAS,EAAEA,MAAM,CAAC,CAAC,GAAG,GAAG,CAAC,EAAEC,MAAM;QACxH,KAAK;YACH,OAAO,CAAC,6BAA6B,EAAED,MAAM,6BAA6B,EAAEC,MAAM;QACpF,KAAK;YACH,OAAO,CAAC,gDAAgD,EAAED,MAAM,CAAC,EAAEC,MAAM;QAC3E,KAAK;YACH,OAAO,CAAC,iBAAiB,EAAED,MAAM,CAAC,EAAEC,MAAM;QAC5C,KAAK;YACH,OAAO,CAAC,4BAA4B,EAAED,MAAM,CAAC,EAAEC,MAAM;QACvD,KAAK;YACH,OAAO,CAAC,0BAA0B,EAAED,MAAM,CAAC,EAAEC,MAAM;QACrD;YACE,OAAO;IACX;AACF"}

package/src/lib/app-utils/forms.d.ts

@@ -170,6 +170,30 @@ export interface FormDocument<N = AglynNodeSchema> {
      * about presence rather than about what kind of clock wrote it.
      */
     archivedAt?: unknown;
+    /**
+     * Whether the form is retired, as a boolean the Forms list can QUERY
+     * (AGL-3330). {@link archivedAt} stays the fact every other reader asks,
+     * through {@link isFormArchived}; this mirrors it because Firestore cannot
+     * find a document by the absence of a field, and "in use" is an absence
+     * there. Written beside `archivedAt` by the one writer that retires a form,
+     * `false` on every create — see {@link newFormListFields}.
+     */
+    retired?: boolean;
+    /** The campaigns the form is filed under — see {@link formCampaignFields}. */
+    campaignIds?: string[];
+    /**
+     * Whether the form is in any campaign, as a boolean the Forms list can
+     * QUERY (AGL-3330): "in no campaign" is an empty array, and Firestore can
+     * neither find a document by an absent field nor ask an array for its
+     * length. Written beside `campaignIds` by every writer of it, through
+     * {@link formCampaignFields}.
+     */
+    inCampaign?: boolean;
+    /** The Forms list's search fields — see {@link formListFields}. */
+    nameLower?: string;
+    nameTokens?: string[];
+    nameReversed?: string;
+    searchTokens?: string[];
     rootId?: NodeId;
     nodes?: Record<NodeId, N>;
     /**
@@ -204,6 +228,150 @@ export interface FormDocument<N = AglynNodeSchema> {
  * must not re-derive this from a display flag; the field is the fact.
  */
 export declare function isFormArchived(form: Pick<FormDocument, 'archivedAt'> | null | undefined): boolean;
+/** The search fields the Forms list queries — see {@link formListFields}. */
+export interface FormListSearchFields {
+    nameLower: string;
+    nameTokens: string[];
+    nameReversed: string;
+    searchTokens: string[];
+}
+/**
+ * The fields the Forms list FILTERS AND SEARCHES BY ON THE QUERY (AGL-3330).
+ *
+ * The list pages a site's catalog, so a filter that matched the rows already
+ * read would answer "no such form" for one on a later page. Firestore has no
+ * case-insensitive or substring match, so the name travels with the keys
+ * every document named by `displayName` carries
+ * (`displayNameSearchFields`): `nameLower`, `nameTokens`, `nameReversed`.
+ * The Display name filter asks `nameTokens`.
+ *
+ * `searchTokens` is what the list's search box asks with one
+ * `array-contains`: the word prefixes of the name AND of the slug (its words
+ * are hyphen-joined) AND the lower-cased prefixes of the form's id, because
+ * the box finds a form by any of the three. A slug usually repeats its name's
+ * words, so the union mostly costs nothing; it earns its place on a form
+ * renamed after its slug was minted.
+ *
+ * `tools/scripts/lib/site-form-list-fields.mjs` is the script-side twin, and both
+ * answer `tools/scripts/lib/site-form-list-fields.fixtures.json`.
+ *
+ * ⚠️ Spread at EVERY write that sets `displayName` or `slug`, and at create.
+ * A rename that skips it leaves the keys naming the old name, and the form is
+ * then findable only by what it used to be called, while it still lists
+ * normally.
+ */
+export declare function formListFields(form: {
+    id: string;
+    displayName?: unknown;
+    slug?: unknown;
+}): FormListSearchFields;
+/**
+ * The campaign fields a form is written with, from the campaigns it is filed
+ * under (AGL-3330): the normalized ids, and `inCampaign`, the boolean the
+ * Forms list's "In a campaign" filter asks by equality.
+ *
+ * ⚠️ The ONE way to write a form's `campaignIds`. A writer that sets the ids
+ * without `inCampaign` leaves the form answering the filter by what it used
+ * to be filed under; `apps/console/specs/form-writers-use-the-helpers.spec.ts`
+ * refuses one. The campaign deletion pass removes an id with `arrayRemove`
+ * and restamps `inCampaign` from the form as it then stands.
+ */
+export declare function formCampaignFields(selected: unknown): {
+    campaignIds: string[];
+    inCampaign: boolean;
+};
+/**
+ * The `stats.leads` a form holds when nothing has been counted for it.
+ *
+ * A form that routes leads holds `0` until its first lead, so "Leads = 0"
+ * finds the lead surfaces that have produced nothing yet. A form that does
+ * not route leads holds `null`: it has no leads measurement, which is what
+ * "Leads is empty" asks. The recount and every writer of the switch agree
+ * through this and {@link formCountersFromSource}.
+ */
+export declare function formLeadsStatWhenUncounted(routesLeads: boolean): 0 | null;
+/**
+ * What a NEW form is written with so the Forms list can query every filter
+ * it offers (AGL-3330): its search keys, and an explicit value for each
+ * field a query would otherwise have to find by its absence.
+ *
+ *  - `retired: false`, the queryable mirror of an unset `archivedAt`.
+ *  - `routing.lead` as a boolean, `false` unless the form routes to leads, so
+ *    "Lead routing is off" is an equality rather than a missing field.
+ *  - `inCampaign`, from the campaigns the form is created in.
+ *  - `stats` with a NULL for each counter, except `leads` on a form that
+ *    routes leads, which starts at `0` (see {@link formLeadsStatWhenUncounted}).
+ *    Null, never zero, where nothing is measured: a zero would claim a
+ *    measurement. `/api/forms/submit` increments these, and an increment on
+ *    null starts from nothing, so it needs no change.
+ *
+ * `routing` keeps whatever else it carries (a dataset binding).
+ */
+export declare function newFormListFields(form: {
+    id: string;
+    displayName?: unknown;
+    slug?: unknown;
+    routing?: FormRouting | null;
+    campaignIds?: unknown;
+}): FormListSearchFields & {
+    retired: false;
+    routing: FormRouting;
+    inCampaign: boolean;
+    stats: {
+        submissions: null;
+        leads: 0 | null;
+        lastSubmissionAtMs: null;
+    };
+};
+/** The source a lead filed by a form carries in `sources`. */
+export declare const FORM_LEAD_SOURCE_PREFIX = "form:";
+/** `form:{formId}` — the lead source a form's capture writes. */
+export declare function formLeadSource(formId: string): string;
+/** The form ids a lead's `sources` name, in order, deduplicated. */
+export declare function formIdsOfLeadSources(sources: unknown): string[];
+/** The three counters the Forms list filters by. */
+export interface FormCounterStats {
+    submissions: number | null;
+    leads: number | null;
+    lastSubmissionAtMs: number | null;
+}
+/** The counter fields, in reading order. */
+export declare const FORM_COUNTER_FIELDS: readonly (keyof FormCounterStats)[];
+/**
+ * The counters a form should hold, from the rows counted.
+ *
+ * Zero submissions is `null`, the list's "none yet", matching a new form.
+ * Leads follow {@link formLeadsStatWhenUncounted} when there are none — and
+ * a form that stopped routing leads keeps the leads it did file, because
+ * those people are still on the list.
+ */
+export declare function formCountersFromSource(source: {
+    submissions: number;
+    leads: number;
+    newestSubmissionAtMs: number | null;
+    routesLeads: boolean;
+}): FormCounterStats;
+/**
+ * How far the stored `lastSubmissionAtMs` may sit from the newest
+ * submission's `createdAt` and still agree.
+ *
+ * The submit path stamps the counter from its own clock after it has written
+ * the submission, whose `createdAt` is the server's commit time, and a lead
+ * capture runs between the two — so a counter that is right reads a little
+ * after the row. Ten minutes is far past that gap and far short of two
+ * submissions a merchant would tell apart.
+ */
+export declare const FORM_LAST_SUBMISSION_TOLERANCE_MS: number;
+/**
+ * The counters on which `stored` disagrees with `recounted`, in reading
+ * order; empty when the form holds what its rows say.
+ *
+ * An ABSENT counter disagrees with a `null` one: "is empty" asks
+ * `== null`, which a missing field does not answer.
+ */
+export declare function formCounterDrift(stored: Record<string, unknown> | null | undefined, recounted: FormCounterStats): (keyof FormCounterStats)[];
+/** The dotted-path update that puts `recounted` on a form. */
+export declare function formCounterPatch(recounted: FormCounterStats): Record<string, number | null>;
 /**
  * One entry in a form's `versions` subcollection.
  *
@@ -226,12 +394,15 @@ export interface FormVersion<N = AglynNodeSchema> {
  * bound and is the one the customer is billed on; a console surface that
  * counted it on render would be the expensive-read shape this product has
  * created repeatedly. `hosts/{hostId}/overlays/{overlayId}.stats` is the same
- * pattern with the same reasoning.
+ * pattern with the same reasoning. What an increment cannot see — a deleted
+ * submission, an erased lead, a failed write — is put back by the RECOUNT
+ * ({@link formCountersFromSource}), which runs after a removal and over every
+ * form from `tools/scripts/recount-form-stats.mjs`; never on render.
  */
 export interface FormStats {
-    submissions?: number;
-    leads?: number;
-    lastSubmissionAtMs?: number;
+    submissions?: number | null;
+    leads?: number | null;
+    lastSubmissionAtMs?: number | null;
     /**
      * Form views, counted by the beacon at `/api/analytics/collect` — one per
      * rendered form on a live page, the same shape and the same cost as an
@@ -352,9 +523,10 @@ export declare function formPeriodKey(atMs: number | null | undefined): string |
  *
  * Every counter is `number | null` and the distinction is load-bearing. A
  * counter is `null` when nothing was recorded for it at all: `leads` is
- * incremented only by a form whose `routing.lead` is set, so a form that does
+ * counted only for a form whose `routing.lead` is set, so a form that does
  * not route leads has no leads measurement rather than a measured zero, and a
- * `0` in that slot states a result nobody took.
+ * `0` in that slot states a result nobody took. A form that routes leads and
+ * has filed none holds `0`, which is a measurement.
  */
 export interface FormStatsTotals {
     views: number | null;