@aglyn/plugins-outreach 1.0.0-beta.143

package/src/lib/engine/delivery-status.js

@@ -0,0 +1,184 @@
+/**
+ * @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.
+ */ /*==========================================
+ * BOUNCES (AGL-2979).
+ *
+ * A mail server that cannot deliver says so in a DELIVERY STATUS
+ * NOTIFICATION (RFC 3464): a `multipart/report; report-type=delivery-status`
+ * message, usually from `mailer-daemon@` or `postmaster@`, whose
+ * `message/delivery-status` part carries one block per recipient —
+ * `Final-Recipient`, `Action` and `Status`, an enhanced code like `5.1.1`.
+ * Gmail writes one into the sender's own thread when a message it relayed is
+ * refused, and a receiving server that accepted a message and then gave up
+ * sends one of its own.
+ *
+ * ## Hard and soft
+ *
+ * A `5.x.x` status on a `failed` action is HARD: the address does not
+ * exist, the domain refuses the sender, the mailbox is closed — trying again
+ * will not help, and the enrollment stops. A `4.x.x` status, or a `delayed`
+ * action, is SOFT: the server is busy or the mailbox is full, the sending
+ * server is still retrying, and nothing changes. A report whose action is
+ * `delivered`, `relayed` or `expanded` is not a bounce at all.
+ *
+ * ## Reports that are not standard
+ *
+ * Some servers send a bounce as plain prose. A message from a mailer daemon
+ * whose subject or text reads like one is read for the status code the prose
+ * quotes (`550 5.1.1`, `421 4.7.0`), and failing that for the words that say
+ * permanent or temporary — soft when it says it will retry, hard otherwise.
+ *==========================================*/ import { emailAddressOf } from "@aglyn/aglyn/app-utils/crm-inbound";
+import { outreachHeader } from "./thread-message.js";
+const DAEMON_LOCAL_PART = /^(mailer-daemon|postmaster|mail-daemon|maildaemon)$/i;
+const DAEMON_NAME = /\bmail delivery (subsystem|system|service)\b/i;
+const BOUNCE_WORDS = /undeliver|delivery status notification|delivery (has )?failed|delivery failure|failure notice|returned mail|mail delivery failed|could not be delivered|wasn't delivered|was not delivered|not delivered|address not found|message blocked/i;
+/** Whether a message comes from a mail system rather than from a person. */ export function isMailerDaemonMessage(message) {
+    var _ref;
+    const raw = String((_ref = message == null ? void 0 : message.from) != null ? _ref : '');
+    const address = emailAddressOf(raw);
+    const local = address ? address.slice(0, address.lastIndexOf('@')) : '';
+    return DAEMON_LOCAL_PART.test(local) || DAEMON_NAME.test(raw);
+}
+function isDeliveryStatusReport(message) {
+    var _message_parts;
+    const contentType = outreachHeader(message, 'Content-Type').toLowerCase();
+    if (contentType.includes('multipart/report') && /report-type\s*=\s*"?delivery-status"?/.test(contentType)) {
+        return true;
+    }
+    return ((_message_parts = message.parts) != null ? _message_parts : []).some((part)=>part.mimeType === 'message/delivery-status' || part.mimeType === 'message/global-delivery-status');
+}
+/** `Name: value` fields, continuation lines folded in, one list per blank-line block. */ function fieldBlocks(text) {
+    const blocks = [];
+    let current = {};
+    let last = null;
+    const close = ()=>{
+        if (Object.keys(current).length) blocks.push(current);
+        current = {};
+        last = null;
+    };
+    for (const line of text.replace(/\r\n?/g, '\n').split('\n')){
+        if (!line.trim()) {
+            close();
+            continue;
+        }
+        if (/^[ \t]/.test(line) && last) {
+            current[last] = `${current[last]} ${line.trim()}`;
+            continue;
+        }
+        const field = /^([A-Za-z][A-Za-z0-9-]*)\s*:\s*(.*)$/.exec(line);
+        if (field) {
+            last = field[1].toLowerCase();
+            if (!(last in current)) current[last] = field[2].trim();
+        }
+    }
+    close();
+    return blocks;
+}
+/** `rfc822; someone@example.com` → the address. */ function typedAddress(value) {
+    if (!value) return null;
+    const typed = /^[a-z0-9-]+\s*;\s*(.*)$/i.exec(value);
+    return emailAddressOf(typed ? typed[1] : value);
+}
+/** An enhanced status code, any class: what a `Status` field holds. */ const STATUS_CODE = /\b([245])\.(\d{1,3})\.(\d{1,3})\b/;
+/** A failure's enhanced status code, quoted somewhere in prose. */ const FAILURE_STATUS_CODE = /\b([45])\.(\d{1,3})\.(\d{1,3})\b/;
+/** A failure's basic SMTP reply code, as a transcript quotes it: `550-` or `421 `. */ const FAILURE_REPLY_CODE = /\b([45])[0-5]\d(?=[ -])/;
+function kindFor(action, status) {
+    if (action === 'delivered' || action === 'relayed' || action === 'expanded') return null;
+    const statusClass = status ? status.charAt(0) : null;
+    if (statusClass === '4' || action === 'delayed') return 'soft';
+    if (statusClass === '5') return action === null || action === 'failed' ? 'hard' : 'soft';
+    if (action === 'failed') return 'hard';
+    return null;
+}
+const SEVERITY = {
+    soft: 1,
+    hard: 2
+};
+function failedRecipientsHeader(message) {
+    return outreachHeader(message, 'X-Failed-Recipients').split(/[,\s]+/).map((value)=>emailAddressOf(value)).filter((value)=>value !== null);
+}
+function prose(message) {
+    return [
+        message.subject,
+        message.textBody,
+        message.snippet
+    ].filter((value)=>typeof value === 'string' && value).join('\n');
+}
+/**
+ * What a delivery report says, or `null` when the message is not one — see
+ * the module note for how a standard report and a prose bounce are read.
+ */ export function readOutreachDeliveryReport(message) {
+    var _message_parts, _ref, _ref1, _ref2;
+    const standard = isDeliveryStatusReport(message);
+    const daemon = isMailerDaemonMessage(message);
+    if (!standard && !(daemon && BOUNCE_WORDS.test(prose(message)))) return null;
+    const statusText = ((_message_parts = message.parts) != null ? _message_parts : []).filter((part)=>part.mimeType === 'message/delivery-status' || part.mimeType === 'message/global-delivery-status').map((part)=>{
+        var _part_text;
+        return (_part_text = part.text) != null ? _part_text : '';
+    }).join('\n\n');
+    // The first block describes the report itself (`Reporting-MTA`,
+    // `Arrival-Date`); each later one describes a recipient.
+    const recipients = fieldBlocks(statusText).filter((block)=>block['final-recipient'] || block['original-recipient'] || block['action'] || block['status']).map((block)=>{
+        var _block_status, _typedAddress;
+        const action = block['action'] ? block['action'].toLowerCase().split(/\s/)[0] : null;
+        const statusMatch = STATUS_CODE.exec((_block_status = block['status']) != null ? _block_status : '');
+        const status = statusMatch ? statusMatch[0] : null;
+        const diagnostic = block['diagnostic-code'] ? block['diagnostic-code'].replace(/^[a-z0-9-]+\s*;\s*/i, '') : null;
+        return {
+            address: (_typedAddress = typedAddress(block['final-recipient'])) != null ? _typedAddress : typedAddress(block['original-recipient']),
+            action,
+            status,
+            diagnostic,
+            kind: kindFor(action, status)
+        };
+    });
+    let worst = null;
+    for (const recipient of recipients){
+        if (recipient.kind && (!worst || SEVERITY[recipient.kind] > SEVERITY[worst.kind])) {
+            worst = recipient;
+        }
+    }
+    if (!worst && !recipients.length) {
+        var _ref3, _ref4;
+        // A report without readable blocks, or a bounce written as prose: the
+        // code the text quotes, else the words.
+        const text = prose(message);
+        const code = FAILURE_STATUS_CODE.exec(text);
+        const reply = FAILURE_REPLY_CODE.exec(text);
+        const statusClass = (_ref3 = (_ref4 = code == null ? void 0 : code[1]) != null ? _ref4 : reply == null ? void 0 : reply[1]) != null ? _ref3 : null;
+        const retrying = /\b(delay(ed)?|will (keep )?retry|not (been )?delivered yet|temporar(y|ily))\b/i.test(text);
+        const kind = statusClass === '5' ? 'hard' : statusClass === '4' || retrying ? 'soft' : 'hard';
+        return {
+            kind,
+            recipients: [],
+            failedAddresses: failedRecipientsHeader(message),
+            status: code ? code[0] : null,
+            diagnostic: null
+        };
+    }
+    // Only the addresses the report's own kind is about: a report that
+    // hard-bounced one recipient and delayed another does not bounce both.
+    const failedAddresses = worst ? recipients.filter((recipient)=>recipient.kind === worst.kind && recipient.address).map((recipient)=>recipient.address) : [];
+    return {
+        kind: (_ref = worst == null ? void 0 : worst.kind) != null ? _ref : null,
+        recipients,
+        failedAddresses: failedAddresses.length || !worst ? failedAddresses : failedRecipientsHeader(message),
+        status: (_ref1 = worst == null ? void 0 : worst.status) != null ? _ref1 : null,
+        diagnostic: (_ref2 = worst == null ? void 0 : worst.diagnostic) != null ? _ref2 : null
+    };
+}
+
+//# sourceMappingURL=delivery-status.js.map

package/src/lib/engine/delivery-status.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/outreach/src/lib/engine/delivery-status.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 * BOUNCES (AGL-2979).\n *\n * A mail server that cannot deliver says so in a DELIVERY STATUS\n * NOTIFICATION (RFC 3464): a `multipart/report; report-type=delivery-status`\n * message, usually from `mailer-daemon@` or `postmaster@`, whose\n * `message/delivery-status` part carries one block per recipient —\n * `Final-Recipient`, `Action` and `Status`, an enhanced code like `5.1.1`.\n * Gmail writes one into the sender's own thread when a message it relayed is\n * refused, and a receiving server that accepted a message and then gave up\n * sends one of its own.\n *\n * ## Hard and soft\n *\n * A `5.x.x` status on a `failed` action is HARD: the address does not\n * exist, the domain refuses the sender, the mailbox is closed — trying again\n * will not help, and the enrollment stops. A `4.x.x` status, or a `delayed`\n * action, is SOFT: the server is busy or the mailbox is full, the sending\n * server is still retrying, and nothing changes. A report whose action is\n * `delivered`, `relayed` or `expanded` is not a bounce at all.\n *\n * ## Reports that are not standard\n *\n * Some servers send a bounce as plain prose. A message from a mailer daemon\n * whose subject or text reads like one is read for the status code the prose\n * quotes (`550 5.1.1`, `421 4.7.0`), and failing that for the words that say\n * permanent or temporary — soft when it says it will retry, hard otherwise.\n *==========================================*/\n\nimport { emailAddressOf } from '@aglyn/aglyn/app-utils/crm-inbound'\nimport { outreachHeader, type OutreachThreadMessage } from './thread-message'\n\nexport type OutreachBounceKind = 'hard' | 'soft'\n\n/** What a delivery report says about one recipient. */\nexport interface OutreachDeliveryRecipient {\n  /** `Final-Recipient`, or `Original-Recipient` when that is all there is; normalized. */\n  address: string | null\n  /** `Action`, lowercased: `failed`, `delayed`, `delivered`, `relayed`, `expanded`. */\n  action: string | null\n  /** `Status`: the enhanced code, `5.1.1`. */\n  status: string | null\n  /** `Diagnostic-Code`, without its type prefix. */\n  diagnostic: string | null\n  /** `hard`, `soft`, or `null` for a block that reports no failure. */\n  kind: OutreachBounceKind | null\n}\n\nexport interface OutreachDeliveryReport {\n  /** The worst failure the report carries, or `null` when it reports none. */\n  kind: OutreachBounceKind | null\n  /** Every recipient the report names, in order. */\n  recipients: OutreachDeliveryRecipient[]\n  /**\n   * The addresses `kind` is about, normalized — `X-Failed-Recipients` when no\n   * block names one. Empty when nothing says which recipient failed.\n   */\n  failedAddresses: string[]\n  /** The status code of the worst failure, when one was found. */\n  status: string | null\n  /** The diagnostic of the worst failure, when one was given. */\n  diagnostic: string | null\n}\n\nconst DAEMON_LOCAL_PART = /^(mailer-daemon|postmaster|mail-daemon|maildaemon)$/i\nconst DAEMON_NAME = /\\bmail delivery (subsystem|system|service)\\b/i\nconst BOUNCE_WORDS =\n  /undeliver|delivery status notification|delivery (has )?failed|delivery failure|failure notice|returned mail|mail delivery failed|could not be delivered|wasn't delivered|was not delivered|not delivered|address not found|message blocked/i\n\n/** Whether a message comes from a mail system rather than from a person. */\nexport function isMailerDaemonMessage(message: Pick<OutreachThreadMessage, 'from'>): boolean {\n  const raw = String(message?.from ?? '')\n  const address = emailAddressOf(raw)\n  const local = address ? address.slice(0, address.lastIndexOf('@')) : ''\n  return DAEMON_LOCAL_PART.test(local) || DAEMON_NAME.test(raw)\n}\n\nfunction isDeliveryStatusReport(message: OutreachThreadMessage): boolean {\n  const contentType = outreachHeader(message, 'Content-Type').toLowerCase()\n  if (\n    contentType.includes('multipart/report') &&\n    /report-type\\s*=\\s*\"?delivery-status\"?/.test(contentType)\n  ) {\n    return true\n  }\n  return (message.parts ?? []).some(\n    (part) =>\n      part.mimeType === 'message/delivery-status' ||\n      part.mimeType === 'message/global-delivery-status',\n  )\n}\n\n/** `Name: value` fields, continuation lines folded in, one list per blank-line block. */\nfunction fieldBlocks(text: string): Array<Record<string, string>> {\n  const blocks: Array<Record<string, string>> = []\n  let current: Record<string, string> = {}\n  let last: string | null = null\n  const close = () => {\n    if (Object.keys(current).length) blocks.push(current)\n    current = {}\n    last = null\n  }\n  for (const line of text.replace(/\\r\\n?/g, '\\n').split('\\n')) {\n    if (!line.trim()) {\n      close()\n      continue\n    }\n    if (/^[ \\t]/.test(line) && last) {\n      current[last] = `${current[last]} ${line.trim()}`\n      continue\n    }\n    const field = /^([A-Za-z][A-Za-z0-9-]*)\\s*:\\s*(.*)$/.exec(line)\n    if (field) {\n      last = field[1].toLowerCase()\n      if (!(last in current)) current[last] = field[2].trim()\n    }\n  }\n  close()\n  return blocks\n}\n\n/** `rfc822; someone@example.com` → the address. */\nfunction typedAddress(value: string | undefined): string | null {\n  if (!value) return null\n  const typed = /^[a-z0-9-]+\\s*;\\s*(.*)$/i.exec(value)\n  return emailAddressOf(typed ? typed[1] : value)\n}\n\n/** An enhanced status code, any class: what a `Status` field holds. */\nconst STATUS_CODE = /\\b([245])\\.(\\d{1,3})\\.(\\d{1,3})\\b/\n/** A failure's enhanced status code, quoted somewhere in prose. */\nconst FAILURE_STATUS_CODE = /\\b([45])\\.(\\d{1,3})\\.(\\d{1,3})\\b/\n/** A failure's basic SMTP reply code, as a transcript quotes it: `550-` or `421 `. */\nconst FAILURE_REPLY_CODE = /\\b([45])[0-5]\\d(?=[ -])/\n\nfunction kindFor(action: string | null, status: string | null): OutreachBounceKind | null {\n  if (action === 'delivered' || action === 'relayed' || action === 'expanded') return null\n  const statusClass = status ? status.charAt(0) : null\n  if (statusClass === '4' || action === 'delayed') return 'soft'\n  if (statusClass === '5') return action === null || action === 'failed' ? 'hard' : 'soft'\n  if (action === 'failed') return 'hard'\n  return null\n}\n\nconst SEVERITY: Record<OutreachBounceKind, number> = { soft: 1, hard: 2 }\n\nfunction failedRecipientsHeader(message: OutreachThreadMessage): string[] {\n  return outreachHeader(message, 'X-Failed-Recipients')\n    .split(/[,\\s]+/)\n    .map((value) => emailAddressOf(value))\n    .filter((value): value is string => value !== null)\n}\n\nfunction prose(message: OutreachThreadMessage): string {\n  return [message.subject, message.textBody, message.snippet]\n    .filter((value) => typeof value === 'string' && value)\n    .join('\\n')\n}\n\n/**\n * What a delivery report says, or `null` when the message is not one — see\n * the module note for how a standard report and a prose bounce are read.\n */\nexport function readOutreachDeliveryReport(\n  message: OutreachThreadMessage,\n): OutreachDeliveryReport | null {\n  const standard = isDeliveryStatusReport(message)\n  const daemon = isMailerDaemonMessage(message)\n  if (!standard && !(daemon && BOUNCE_WORDS.test(prose(message)))) return null\n\n  const statusText = (message.parts ?? [])\n    .filter(\n      (part) =>\n        part.mimeType === 'message/delivery-status' ||\n        part.mimeType === 'message/global-delivery-status',\n    )\n    .map((part) => part.text ?? '')\n    .join('\\n\\n')\n  // The first block describes the report itself (`Reporting-MTA`,\n  // `Arrival-Date`); each later one describes a recipient.\n  const recipients: OutreachDeliveryRecipient[] = fieldBlocks(statusText)\n    .filter(\n      (block) =>\n        block['final-recipient'] || block['original-recipient'] || block['action'] || block['status'],\n    )\n    .map((block) => {\n      const action = block['action'] ? block['action'].toLowerCase().split(/\\s/)[0] : null\n      const statusMatch = STATUS_CODE.exec(block['status'] ?? '')\n      const status = statusMatch ? statusMatch[0] : null\n      const diagnostic = block['diagnostic-code']\n        ? block['diagnostic-code'].replace(/^[a-z0-9-]+\\s*;\\s*/i, '')\n        : null\n      return {\n        address: typedAddress(block['final-recipient']) ?? typedAddress(block['original-recipient']),\n        action,\n        status,\n        diagnostic,\n        kind: kindFor(action, status),\n      }\n    })\n\n  let worst: OutreachDeliveryRecipient | null = null\n  for (const recipient of recipients) {\n    if (recipient.kind && (!worst || SEVERITY[recipient.kind] > SEVERITY[worst.kind])) {\n      worst = recipient\n    }\n  }\n\n  if (!worst && !recipients.length) {\n    // A report without readable blocks, or a bounce written as prose: the\n    // code the text quotes, else the words.\n    const text = prose(message)\n    const code = FAILURE_STATUS_CODE.exec(text)\n    const reply = FAILURE_REPLY_CODE.exec(text)\n    const statusClass = code?.[1] ?? reply?.[1] ?? null\n    const retrying =\n      /\\b(delay(ed)?|will (keep )?retry|not (been )?delivered yet|temporar(y|ily))\\b/i.test(text)\n    const kind: OutreachBounceKind =\n      statusClass === '5' ? 'hard' : statusClass === '4' || retrying ? 'soft' : 'hard'\n    return {\n      kind,\n      recipients: [],\n      failedAddresses: failedRecipientsHeader(message),\n      status: code ? code[0] : null,\n      diagnostic: null,\n    }\n  }\n\n  // Only the addresses the report's own kind is about: a report that\n  // hard-bounced one recipient and delayed another does not bounce both.\n  const failedAddresses = worst\n    ? recipients\n        .filter((recipient) => recipient.kind === worst.kind && recipient.address)\n        .map((recipient) => recipient.address as string)\n    : []\n  return {\n    kind: worst?.kind ?? null,\n    recipients,\n    failedAddresses:\n      failedAddresses.length || !worst ? failedAddresses : failedRecipientsHeader(message),\n    status: worst?.status ?? null,\n    diagnostic: worst?.diagnostic ?? null,\n  }\n}\n"],"names":["emailAddressOf","outreachHeader","DAEMON_LOCAL_PART","DAEMON_NAME","BOUNCE_WORDS","isMailerDaemonMessage","message","raw","String","from","address","local","slice","lastIndexOf","test","isDeliveryStatusReport","contentType","toLowerCase","includes","parts","some","part","mimeType","fieldBlocks","text","blocks","current","last","close","Object","keys","length","push","line","replace","split","trim","field","exec","typedAddress","value","typed","STATUS_CODE","FAILURE_STATUS_CODE","FAILURE_REPLY_CODE","kindFor","action","status","statusClass","charAt","SEVERITY","soft","hard","failedRecipientsHeader","map","filter","prose","subject","textBody","snippet","join","readOutreachDeliveryReport","standard","daemon","statusText","recipients","block","statusMatch","diagnostic","kind","worst","recipient","code","reply","retrying","failedAddresses"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;;;;;;;;;;;;;;;;;;;4CA2B4C,GAE5C,SAASA,cAAc,QAAQ,qCAAoC;AACnE,SAASC,cAAc,QAAoC,sBAAkB;AAkC7E,MAAMC,oBAAoB;AAC1B,MAAMC,cAAc;AACpB,MAAMC,eACJ;AAEF,0EAA0E,GAC1E,OAAO,SAASC,sBAAsBC,OAA4C;;IAChF,MAAMC,MAAMC,eAAOF,2BAAAA,QAASG,IAAI,mBAAI;IACpC,MAAMC,UAAUV,eAAeO;IAC/B,MAAMI,QAAQD,UAAUA,QAAQE,KAAK,CAAC,GAAGF,QAAQG,WAAW,CAAC,QAAQ;IACrE,OAAOX,kBAAkBY,IAAI,CAACH,UAAUR,YAAYW,IAAI,CAACP;AAC3D;AAEA,SAASQ,uBAAuBT,OAA8B;QAQpDA;IAPR,MAAMU,cAAcf,eAAeK,SAAS,gBAAgBW,WAAW;IACvE,IACED,YAAYE,QAAQ,CAAC,uBACrB,wCAAwCJ,IAAI,CAACE,cAC7C;QACA,OAAO;IACT;IACA,OAAO,EAACV,iBAAAA,QAAQa,KAAK,YAAbb,iBAAiB,EAAE,EAAEc,IAAI,CAC/B,CAACC,OACCA,KAAKC,QAAQ,KAAK,6BAClBD,KAAKC,QAAQ,KAAK;AAExB;AAEA,uFAAuF,GACvF,SAASC,YAAYC,IAAY;IAC/B,MAAMC,SAAwC,EAAE;IAChD,IAAIC,UAAkC,CAAC;IACvC,IAAIC,OAAsB;IAC1B,MAAMC,QAAQ;QACZ,IAAIC,OAAOC,IAAI,CAACJ,SAASK,MAAM,EAAEN,OAAOO,IAAI,CAACN;QAC7CA,UAAU,CAAC;QACXC,OAAO;IACT;IACA,KAAK,MAAMM,QAAQT,KAAKU,OAAO,CAAC,UAAU,MAAMC,KAAK,CAAC,MAAO;QAC3D,IAAI,CAACF,KAAKG,IAAI,IAAI;YAChBR;YACA;QACF;QACA,IAAI,SAASd,IAAI,CAACmB,SAASN,MAAM;YAC/BD,OAAO,CAACC,KAAK,GAAG,GAAGD,OAAO,CAACC,KAAK,CAAC,CAAC,EAAEM,KAAKG,IAAI,IAAI;YACjD;QACF;QACA,MAAMC,QAAQ,uCAAuCC,IAAI,CAACL;QAC1D,IAAII,OAAO;YACTV,OAAOU,KAAK,CAAC,EAAE,CAACpB,WAAW;YAC3B,IAAI,CAAEU,CAAAA,QAAQD,OAAM,GAAIA,OAAO,CAACC,KAAK,GAAGU,KAAK,CAAC,EAAE,CAACD,IAAI;QACvD;IACF;IACAR;IACA,OAAOH;AACT;AAEA,iDAAiD,GACjD,SAASc,aAAaC,KAAyB;IAC7C,IAAI,CAACA,OAAO,OAAO;IACnB,MAAMC,QAAQ,2BAA2BH,IAAI,CAACE;IAC9C,OAAOxC,eAAeyC,QAAQA,KAAK,CAAC,EAAE,GAAGD;AAC3C;AAEA,qEAAqE,GACrE,MAAME,cAAc;AACpB,iEAAiE,GACjE,MAAMC,sBAAsB;AAC5B,oFAAoF,GACpF,MAAMC,qBAAqB;AAE3B,SAASC,QAAQC,MAAqB,EAAEC,MAAqB;IAC3D,IAAID,WAAW,eAAeA,WAAW,aAAaA,WAAW,YAAY,OAAO;IACpF,MAAME,cAAcD,SAASA,OAAOE,MAAM,CAAC,KAAK;IAChD,IAAID,gBAAgB,OAAOF,WAAW,WAAW,OAAO;IACxD,IAAIE,gBAAgB,KAAK,OAAOF,WAAW,QAAQA,WAAW,WAAW,SAAS;IAClF,IAAIA,WAAW,UAAU,OAAO;IAChC,OAAO;AACT;AAEA,MAAMI,WAA+C;IAAEC,MAAM;IAAGC,MAAM;AAAE;AAExE,SAASC,uBAAuB/C,OAA8B;IAC5D,OAAOL,eAAeK,SAAS,uBAC5B6B,KAAK,CAAC,UACNmB,GAAG,CAAC,CAACd,QAAUxC,eAAewC,QAC9Be,MAAM,CAAC,CAACf,QAA2BA,UAAU;AAClD;AAEA,SAASgB,MAAMlD,OAA8B;IAC3C,OAAO;QAACA,QAAQmD,OAAO;QAAEnD,QAAQoD,QAAQ;QAAEpD,QAAQqD,OAAO;KAAC,CACxDJ,MAAM,CAAC,CAACf,QAAU,OAAOA,UAAU,YAAYA,OAC/CoB,IAAI,CAAC;AACV;AAEA;;;CAGC,GACD,OAAO,SAASC,2BACdvD,OAA8B;QAMVA;IAJpB,MAAMwD,WAAW/C,uBAAuBT;IACxC,MAAMyD,SAAS1D,sBAAsBC;IACrC,IAAI,CAACwD,YAAY,CAAEC,CAAAA,UAAU3D,aAAaU,IAAI,CAAC0C,MAAMlD,SAAQ,GAAI,OAAO;IAExE,MAAM0D,aAAa,EAAC1D,iBAAAA,QAAQa,KAAK,YAAbb,iBAAiB,EAAE,EACpCiD,MAAM,CACL,CAAClC,OACCA,KAAKC,QAAQ,KAAK,6BAClBD,KAAKC,QAAQ,KAAK,kCAErBgC,GAAG,CAAC,CAACjC;YAASA;gBAAAA,aAAAA,KAAKG,IAAI,YAATH,aAAa;OAC3BuC,IAAI,CAAC;IACR,gEAAgE;IAChE,yDAAyD;IACzD,MAAMK,aAA0C1C,YAAYyC,YACzDT,MAAM,CACL,CAACW,QACCA,KAAK,CAAC,kBAAkB,IAAIA,KAAK,CAAC,qBAAqB,IAAIA,KAAK,CAAC,SAAS,IAAIA,KAAK,CAAC,SAAS,EAEhGZ,GAAG,CAAC,CAACY;YAEiCA,eAM1B3B;QAPX,MAAMO,SAASoB,KAAK,CAAC,SAAS,GAAGA,KAAK,CAAC,SAAS,CAACjD,WAAW,GAAGkB,KAAK,CAAC,KAAK,CAAC,EAAE,GAAG;QAChF,MAAMgC,cAAczB,YAAYJ,IAAI,EAAC4B,gBAAAA,KAAK,CAAC,SAAS,YAAfA,gBAAmB;QACxD,MAAMnB,SAASoB,cAAcA,WAAW,CAAC,EAAE,GAAG;QAC9C,MAAMC,aAAaF,KAAK,CAAC,kBAAkB,GACvCA,KAAK,CAAC,kBAAkB,CAAChC,OAAO,CAAC,uBAAuB,MACxD;QACJ,OAAO;YACLxB,OAAO,GAAE6B,gBAAAA,aAAa2B,KAAK,CAAC,kBAAkB,aAArC3B,gBAA0CA,aAAa2B,KAAK,CAAC,qBAAqB;YAC3FpB;YACAC;YACAqB;YACAC,MAAMxB,QAAQC,QAAQC;QACxB;IACF;IAEF,IAAIuB,QAA0C;IAC9C,KAAK,MAAMC,aAAaN,WAAY;QAClC,IAAIM,UAAUF,IAAI,IAAK,CAAA,CAACC,SAASpB,QAAQ,CAACqB,UAAUF,IAAI,CAAC,GAAGnB,QAAQ,CAACoB,MAAMD,IAAI,CAAC,AAAD,GAAI;YACjFC,QAAQC;QACV;IACF;IAEA,IAAI,CAACD,SAAS,CAACL,WAAWlC,MAAM,EAAE;YAMZyC;QALpB,sEAAsE;QACtE,wCAAwC;QACxC,MAAMhD,OAAOgC,MAAMlD;QACnB,MAAMkE,OAAO7B,oBAAoBL,IAAI,CAACd;QACtC,MAAMiD,QAAQ7B,mBAAmBN,IAAI,CAACd;QACtC,MAAMwB,eAAcwB,iBAAAA,wBAAAA,IAAM,CAAC,EAAE,oBAAIC,yBAAAA,KAAO,CAAC,EAAE,YAAvBD,QAA2B;QAC/C,MAAME,WACJ,iFAAiF5D,IAAI,CAACU;QACxF,MAAM6C,OACJrB,gBAAgB,MAAM,SAASA,gBAAgB,OAAO0B,WAAW,SAAS;QAC5E,OAAO;YACLL;YACAJ,YAAY,EAAE;YACdU,iBAAiBtB,uBAAuB/C;YACxCyC,QAAQyB,OAAOA,IAAI,CAAC,EAAE,GAAG;YACzBJ,YAAY;QACd;IACF;IAEA,mEAAmE;IACnE,uEAAuE;IACvE,MAAMO,kBAAkBL,QACpBL,WACGV,MAAM,CAAC,CAACgB,YAAcA,UAAUF,IAAI,KAAKC,MAAMD,IAAI,IAAIE,UAAU7D,OAAO,EACxE4C,GAAG,CAAC,CAACiB,YAAcA,UAAU7D,OAAO,IACvC,EAAE;IACN,OAAO;QACL2D,IAAI,UAAEC,yBAAAA,MAAOD,IAAI,mBAAI;QACrBJ;QACAU,iBACEA,gBAAgB5C,MAAM,IAAI,CAACuC,QAAQK,kBAAkBtB,uBAAuB/C;QAC9EyC,MAAM,WAAEuB,yBAAAA,MAAOvB,MAAM,oBAAI;QACzBqB,UAAU,WAAEE,yBAAAA,MAAOF,UAAU,oBAAI;IACnC;AACF"}

package/src/lib/engine/do-not-contact.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @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 key, or `null` for anything that is not a usable address. */
+export declare function outreachDoNotContactKey(email: unknown): string | null;

package/src/lib/engine/do-not-contact.js

@@ -0,0 +1,34 @@
+/**
+ * @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 document id of an address on the organization's Outreach
+ * do-not-contact list (AGL-2979).
+ *
+ * `personKey` — `sha256` of the normalized address, as full hex — which is
+ * exactly how `emailSuppressions/{key}`, `hosts/{hostId}/suppressions/{key}`
+ * and `hosts/{hostId}/topicOptOuts/{key}` are keyed, so the runtime reads all
+ * four lists for one person with one key and a document id never carries the
+ * address itself.
+ *
+ * SERVER ONLY, and so not in the engine's barrel: `personKey` hashes with
+ * `node:crypto`, which cannot ship to a browser. Import it by its own path,
+ * `@aglyn/plugins-outreach/engine/do-not-contact`.
+ */ import { personKey } from "@aglyn/aglyn/app-utils/person-key";
+/** The key, or `null` for anything that is not a usable address. */ export function outreachDoNotContactKey(email) {
+    return personKey(email);
+}
+
+//# sourceMappingURL=do-not-contact.js.map

package/src/lib/engine/do-not-contact.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/outreach/src/lib/engine/do-not-contact.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 * The document id of an address on the organization's Outreach\n * do-not-contact list (AGL-2979).\n *\n * `personKey` — `sha256` of the normalized address, as full hex — which is\n * exactly how `emailSuppressions/{key}`, `hosts/{hostId}/suppressions/{key}`\n * and `hosts/{hostId}/topicOptOuts/{key}` are keyed, so the runtime reads all\n * four lists for one person with one key and a document id never carries the\n * address itself.\n *\n * SERVER ONLY, and so not in the engine's barrel: `personKey` hashes with\n * `node:crypto`, which cannot ship to a browser. Import it by its own path,\n * `@aglyn/plugins-outreach/engine/do-not-contact`.\n */\n\nimport { personKey } from '@aglyn/aglyn/app-utils/person-key'\n\n/** The key, or `null` for anything that is not a usable address. */\nexport function outreachDoNotContactKey(email: unknown): string | null {\n  return personKey(email)\n}\n"],"names":["personKey","outreachDoNotContactKey","email"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;;;;;CAaC,GAED,SAASA,SAAS,QAAQ,oCAAmC;AAE7D,kEAAkE,GAClE,OAAO,SAASC,wBAAwBC,KAAc;IACpD,OAAOF,UAAUE;AACnB"}

package/src/lib/engine/enrollment-state.d.ts

@@ -0,0 +1,156 @@
+/**
+ * @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 OutreachAttestations, type OutreachEnrollment, type OutreachEnrollmentStatus, type OutreachMailbox, type OutreachSequence, type OutreachStopReason } from '../model/outreach.types';
+import { type OutreachRandom } from './schedule';
+/** Where each status may go next. */
+export declare const OUTREACH_ENROLLMENT_TRANSITIONS: Readonly<Record<OutreachEnrollmentStatus, readonly OutreachEnrollmentStatus[]>>;
+export declare function canTransitionOutreachEnrollment(from: OutreachEnrollmentStatus, to: OutreachEnrollmentStatus): boolean;
+/** Something that happened to an enrollment. `atMs` is when it happened. */
+export type OutreachEnrollmentEvent = {
+    type: 'pause';
+    atMs: number;
+    byUid: string | null;
+    detail?: string | null;
+} | {
+    type: 'resume';
+    atMs: number;
+    byUid: string | null;
+} | {
+    type: 'stop';
+    atMs: number;
+    byUid: string | null;
+    reason?: Extract<OutreachStopReason, 'manual' | 'gate' | 'sequence_archived'>;
+    detail?: string | null;
+} | {
+    type: 'reply';
+    atMs: number;
+    detail?: string | null;
+} | {
+    type: 'opt_out';
+    atMs: number;
+    reason: Extract<OutreachStopReason, 'opt_out_reply' | 'unsubscribe' | 'do_not_contact'>;
+    detail?: string | null;
+} | {
+    type: 'bounce';
+    atMs: number;
+    detail?: string | null;
+} | {
+    type: 'send_failed';
+    atMs: number;
+    detail?: string | null;
+};
+/** The status fields an event writes. */
+export interface OutreachEnrollmentStatusPatch {
+    status: OutreachEnrollmentStatus;
+    stopReason: OutreachStopReason | null;
+    stopDetail: string | null;
+    stoppedAtMs: number | null;
+    stoppedByUid: string | null;
+    nextDueAtMs: number | null;
+}
+/**
+ * `patch` is what to write, or `null` when there is nothing to write — the
+ * enrollment is already there, or the event is not allowed, in which case
+ * `error` says why.
+ */
+export interface OutreachEnrollmentEventResult {
+    patch: OutreachEnrollmentStatusPatch | null;
+    error: string | null;
+}
+/** What an event does to an enrollment's status — see the module note. */
+export declare function applyOutreachEnrollmentEvent(enrollment: Pick<OutreachEnrollment, 'status' | 'nextDueAtMs'>, event: OutreachEnrollmentEvent): OutreachEnrollmentEventResult;
+type ScheduleMailbox = Pick<OutreachMailbox, 'timezone' | 'window'>;
+type ScheduleSequence = Pick<OutreachSequence, 'steps' | 'settings'>;
+/** When a new enrollment's first step comes due, or `null` when it cannot be placed. */
+export declare function planOutreachFirstDue(input: {
+    sequence: ScheduleSequence;
+    mailbox: ScheduleMailbox;
+    enrolledAtMs: number;
+    random: OutreachRandom;
+}): number | null;
+/** Stamps the attestations a rep ticked with who ticked them and when; unknown kinds are dropped. */
+export declare function outreachAttestationsFrom(kinds: readonly unknown[], uid: string, atMs: number): OutreachAttestations;
+export interface OutreachEnrollmentDraft {
+    id: string;
+    sequence: Pick<OutreachSequence, 'id' | 'hostId' | 'mailboxId' | 'steps' | 'settings'>;
+    mailbox: ScheduleMailbox;
+    contactId: string;
+    /** The contact's name as the sending site knows it; `''` for none. */
+    contactName?: string | null;
+    /** The address, as the gates normalized it. */
+    email: string;
+    /** The gates' `cold`. */
+    cold: boolean;
+    personalLine: string;
+    attestations: OutreachAttestations;
+    enrolledByUid: string;
+    nowMs: number;
+    random: OutreachRandom;
+}
+/**
+ * A new enrollment document, first step scheduled — one builder for every
+ * door that enrolls, so an enrollment made from a contact and one made from
+ * a list are the same shape. Call it after the gates allowed the person.
+ */
+export declare function buildOutreachEnrollment(draft: OutreachEnrollmentDraft): OutreachEnrollment;
+/** What the provider reported for an email step that was sent. */
+export interface OutreachSentEmail {
+    /** The `Message-ID` header the message went out with, angle brackets included. */
+    messageId: string;
+    /** The provider's thread id. */
+    threadId: string;
+    /** The subject as sent. */
+    subject: string;
+}
+export interface OutreachStepCompletionInput {
+    enrollment: Pick<OutreachEnrollment, 'status' | 'stepIndex' | 'gmailThreadId' | 'gmailThreadIds' | 'messageIds' | 'threadSubject'>;
+    sequence: ScheduleSequence;
+    mailbox: ScheduleMailbox;
+    /** When the step ran. */
+    completedAtMs: number;
+    /** For an email step, what was sent; not read for a task. */
+    sent?: OutreachSentEmail | null;
+    random: OutreachRandom;
+}
+/** The fields a completed step writes. */
+export interface OutreachStepCompletionPatch {
+    status: 'active' | 'finished';
+    stepIndex: number;
+    nextDueAtMs: number | null;
+    lastSentAtMs: number;
+    gmailThreadId?: string;
+    gmailThreadIds?: string[];
+    threadSubject?: string;
+    messageIds?: string[];
+}
+export interface OutreachStepCompletionResult {
+    patch: OutreachStepCompletionPatch | null;
+    /**
+     * Why there is no patch, or — beside one — that the next step could not
+     * be placed on the calendar (a window that never opens, a zone `Intl` does
+     * not know), which leaves the enrollment with nothing due until a member
+     * fixes the window and resumes it.
+     */
+    error: string | null;
+}
+/**
+ * What running the current step writes: the send recorded on the thread
+ * fields, and the next step scheduled — or the enrollment `finished` when
+ * that was the last.
+ */
+export declare function planOutreachStepCompletion(input: OutreachStepCompletionInput): OutreachStepCompletionResult;
+export {};