@aglyn/plugins-outreach 1.0.0-beta.143

package/src/lib/engine/thread-classification.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/outreach/src/lib/engine/thread-classification.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 * WHAT CAME BACK (AGL-2979).\n *\n * The runtime reads each enrollment's threads and asks what the new\n * messages mean. Each message is one of:\n *\n * - `self` — the mailbox's own: a step, or the rep writing in the thread.\n * - `hard_bounce` / `soft_bounce` — a delivery report (`./delivery-status.ts`).\n * - `delivery_report` — a mail system's message that reports no failure.\n * - `auto_reply` — an out-of-office or an autoresponder. It POSTPONES the\n *   next step and does not stop the sequence: nobody answered.\n * - `opt_out` — a reply that asks to be left alone (`./opt-out-intent.ts`),\n *   or a message sent to the unsubscribe address.\n * - `reply` — any other message from anybody else.\n *\n * ## Automatic replies\n *\n * Read from the headers the standards give an autoresponder —\n * `Auto-Submitted` with any value but `no` (RFC 3834), `X-Autoreply`,\n * `X-Autorespond`, `Precedence: auto_reply`, `bulk` or `junk` — and, for\n * the servers that set none, from an out-of-office subject in the usual\n * languages.\n *\n * ## The thread's outcome\n *\n * `opted_out` outranks `replied`, which outranks `bounced`, which outranks\n * `postpone`: an opt-out is a reply that also has to reach the do-not-contact\n * list, a person who wrote back matters more than a report about an earlier\n * send, and an out-of-office only matters when nothing else happened. The\n * bounces that report this recipient are counted either way, because mailbox\n * health counts every one.\n *==========================================*/\n\nimport { normalizeContactEmail } from '@aglyn/aglyn/app-utils/contacts'\nimport { crmThreadSubject, emailAddressOf, htmlToPlainText } from '@aglyn/aglyn/app-utils/crm-inbound'\nimport { readOutreachDeliveryReport, isMailerDaemonMessage } from './delivery-status'\nimport { detectOutreachOptOutIntent, detectOutreachOptOutSubject } from './opt-out-intent'\nimport { outreachHeader, type OutreachThreadMessage } from './thread-message'\n\nexport type OutreachMessageKind =\n  | 'self'\n  | 'hard_bounce'\n  | 'soft_bounce'\n  | 'delivery_report'\n  | 'auto_reply'\n  | 'opt_out'\n  | 'reply'\n\nexport interface OutreachBounceDetail {\n  /** The addresses the report says failed; empty when it names none. */\n  recipients: string[]\n  status: string | null\n  diagnostic: string | null\n}\n\nexport interface OutreachMessageClassification {\n  messageId: string\n  atMs: number\n  kind: OutreachMessageKind\n  /** The sender's address, normalized, when the `From` carried one. */\n  from: string | null\n  /** Set on a bounce. */\n  bounce: OutreachBounceDetail | null\n  /** An opt-out that calls the email spam. */\n  complaint: boolean\n  /** What decided it, for the timeline and the log. */\n  evidence: string | null\n}\n\nexport interface OutreachMessageContext {\n  /** The mailbox's own addresses: the account's and every alias it sends as. */\n  selfAddresses: readonly string[]\n  /** The address a `List-Unsubscribe` mailto points at, when the runtime set one. */\n  unsubscribeAddress?: string | null\n  /** The subject the thread was started with, so a new subject can be read on its own. */\n  threadSubject?: string | null\n}\n\nconst AUTO_REPLY_SUBJECT = new RegExp(\n  [\n    '^\\\\s*\\\\[?\\\\s*(',\n    'auto(matic)?[\\\\s-]*(reply|response|responder|answer)',\n    '|out[\\\\s-]+of[\\\\s-]+(the[\\\\s-]+)?office',\n    '|ooo\\\\b',\n    \"|i('m| am) (currently )?(out of the office|away|on (vacation|leave|holiday))\",\n    '|(on )?(vacation|holiday|annual leave)[\\\\s-]*(reply|response|notice|message|autoreply)',\n    '|away from (the |my )?(office|desk)',\n    '|abwesenheitsnotiz|abwesenheit',\n    '|r[ée]ponse automatique|absence du bureau',\n    '|respuesta autom[áa]tica|fuera de la oficina',\n    '|risposta automatica|fuori ufficio',\n    '|automatisch antwoord|afwezigheidsbericht',\n    '|resposta autom[áa]tica|fora do escrit[óo]rio',\n    '|autosvar|automaattinen vastaus',\n    ')',\n  ].join(''),\n  'i',\n)\n\n/**\n * Why a message is an automatic reply, or `null` when it is not one — see\n * the module note for the headers and subjects read.\n */\nexport function outreachAutoReplyEvidence(\n  message: Pick<OutreachThreadMessage, 'headers' | 'subject'>,\n): string | null {\n  const autoSubmitted = outreachHeader(message, 'Auto-Submitted').split(';')[0].trim().toLowerCase()\n  if (autoSubmitted && autoSubmitted !== 'no') return `Auto-Submitted: ${autoSubmitted}`\n  for (const name of ['X-Autoreply', 'X-Autorespond']) {\n    const value = outreachHeader(message, name).trim()\n    if (value && value.toLowerCase() !== 'no') return `${name}: ${value}`\n  }\n  const precedence = outreachHeader(message, 'Precedence').trim().toLowerCase()\n  if (['auto_reply', 'bulk', 'junk'].includes(precedence)) return `Precedence: ${precedence}`\n  const subject = String(message?.subject ?? '').replace(/^\\s*(re|fwd?)\\s*:\\s*/i, '')\n  const match = AUTO_REPLY_SUBJECT.exec(subject)\n  return match ? `Subject: ${match[0].trim()}` : null\n}\n\nfunction addressesIn(header: string): string[] {\n  return header\n    .split(',')\n    .map((part) => emailAddressOf(part))\n    .filter((address): address is string => address !== null)\n}\n\nfunction readableText(message: OutreachThreadMessage): string {\n  if (message.textBody && message.textBody.trim()) return message.textBody\n  if (message.htmlBody && message.htmlBody.trim()) return htmlToPlainText(message.htmlBody)\n  return message.snippet ?? ''\n}\n\n/** What one message in an enrollment's thread is — see the module note. */\nexport function classifyOutreachMessage(\n  message: OutreachThreadMessage,\n  context: OutreachMessageContext,\n): OutreachMessageClassification {\n  const from = emailAddressOf(message.from)\n  const base = {\n    messageId: String(message.id ?? ''),\n    atMs: Number.isFinite(message.internalDateMs) ? message.internalDateMs : 0,\n    from,\n    bounce: null,\n    complaint: false,\n    evidence: null,\n  }\n\n  const report = readOutreachDeliveryReport(message)\n  if (report) {\n    if (!report.kind) return { ...base, kind: 'delivery_report', evidence: 'delivery report' }\n    return {\n      ...base,\n      kind: report.kind === 'hard' ? 'hard_bounce' : 'soft_bounce',\n      bounce: {\n        recipients: report.failedAddresses,\n        status: report.status,\n        diagnostic: report.diagnostic,\n      },\n      evidence: report.status ? `Status: ${report.status}` : 'delivery report',\n    }\n  }\n\n  const self = new Set(\n    (context.selfAddresses ?? [])\n      .map((address) => normalizeContactEmail(address))\n      .filter((address): address is string => address !== null),\n  )\n  if (from && self.has(from)) return { ...base, kind: 'self' }\n  if (isMailerDaemonMessage(message)) {\n    return { ...base, kind: 'delivery_report', evidence: 'mail system message' }\n  }\n\n  const unsubscribe = normalizeContactEmail(context.unsubscribeAddress)\n  if (unsubscribe && addressesIn(message.to ?? '').includes(unsubscribe)) {\n    return { ...base, kind: 'opt_out', evidence: `To: ${unsubscribe}` }\n  }\n\n  const autoReply = outreachAutoReplyEvidence(message)\n  if (autoReply) return { ...base, kind: 'auto_reply', evidence: autoReply }\n\n  const intent = detectOutreachOptOutIntent(readableText(message))\n  if (intent.optOut) {\n    return { ...base, kind: 'opt_out', complaint: intent.complaint, evidence: intent.matched }\n  }\n  // A subject is read only on a message that starts fresh — no `Re:`, and\n  // not the thread's own — and only when it says nothing but stop.\n  const subject = String(message.subject ?? '').replace(/\\s+/g, ' ').trim()\n  const fresh = crmThreadSubject(subject) === subject\n  if (subject && fresh && subject !== crmThreadSubject(context.threadSubject)) {\n    const subjectIntent = detectOutreachOptOutSubject(subject)\n    if (subjectIntent.optOut) {\n      return { ...base, kind: 'opt_out', evidence: `Subject: ${subjectIntent.matched}` }\n    }\n  }\n  return { ...base, kind: 'reply' }\n}\n\nexport type OutreachThreadOutcome = 'none' | 'postpone' | 'bounced' | 'replied' | 'opted_out'\n\nexport interface OutreachThreadDecisionInput extends OutreachMessageContext {\n  /** The thread's messages, in any order. */\n  messages: readonly OutreachThreadMessage[]\n  /** The enrollment's recipient. */\n  recipient: string\n  /** Messages received at or before this instant were handled by an earlier run. */\n  afterMs?: number | null\n  /** Ids of messages an earlier run handled. */\n  handledMessageIds?: readonly string[]\n}\n\nexport interface OutreachThreadDecision {\n  outcome: OutreachThreadOutcome\n  /** The message that decided the outcome; `null` for `none`. */\n  decidedBy: OutreachMessageClassification | null\n  /** Every new message, classified, oldest first. */\n  classifications: OutreachMessageClassification[]\n  /** A new reply called the email spam: the mailbox is paused as well. */\n  complaint: boolean\n  /** New hard bounces that report this recipient. */\n  hardBounces: number\n  /** New soft bounces that report this recipient. */\n  softBounces: number\n}\n\nconst RANK: Record<OutreachThreadOutcome, number> = {\n  none: 0,\n  postpone: 1,\n  bounced: 2,\n  replied: 3,\n  opted_out: 4,\n}\n\nconst OUTCOME_OF: Partial<Record<OutreachMessageKind, OutreachThreadOutcome>> = {\n  auto_reply: 'postpone',\n  hard_bounce: 'bounced',\n  reply: 'replied',\n  opt_out: 'opted_out',\n}\n\n/** What the new messages in an enrollment's thread mean for it — see the module note. */\nexport function decideOutreachThread(input: OutreachThreadDecisionInput): OutreachThreadDecision {\n  const recipient = normalizeContactEmail(input.recipient)\n  const handled = new Set(input.handledMessageIds ?? [])\n  const afterMs = typeof input.afterMs === 'number' ? input.afterMs : null\n  const fresh = [...(input.messages ?? [])]\n    .filter((message) => message && !handled.has(message.id))\n    .filter((message) => afterMs === null || message.internalDateMs > afterMs)\n    .sort((a, b) => a.internalDateMs - b.internalDateMs)\n\n  const decision: OutreachThreadDecision = {\n    outcome: 'none',\n    decidedBy: null,\n    classifications: [],\n    complaint: false,\n    hardBounces: 0,\n    softBounces: 0,\n  }\n  for (const message of fresh) {\n    const classification = classifyOutreachMessage(message, input)\n    decision.classifications.push(classification)\n    const bounce = classification.bounce\n    const aboutRecipient =\n      !bounce || !bounce.recipients.length || (recipient !== null && bounce.recipients.includes(recipient))\n    if (classification.kind === 'hard_bounce' && aboutRecipient) decision.hardBounces += 1\n    if (classification.kind === 'soft_bounce' && aboutRecipient) decision.softBounces += 1\n    if (classification.complaint) decision.complaint = true\n    const outcome = OUTCOME_OF[classification.kind]\n    if (!outcome || (classification.kind === 'hard_bounce' && !aboutRecipient)) continue\n    if (RANK[outcome] > RANK[decision.outcome]) {\n      decision.outcome = outcome\n      decision.decidedBy = classification\n    }\n  }\n  return decision\n}\n"],"names":["normalizeContactEmail","crmThreadSubject","emailAddressOf","htmlToPlainText","readOutreachDeliveryReport","isMailerDaemonMessage","detectOutreachOptOutIntent","detectOutreachOptOutSubject","outreachHeader","AUTO_REPLY_SUBJECT","RegExp","join","outreachAutoReplyEvidence","message","autoSubmitted","split","trim","toLowerCase","name","value","precedence","includes","subject","String","replace","match","exec","addressesIn","header","map","part","filter","address","readableText","textBody","htmlBody","snippet","classifyOutreachMessage","context","from","base","messageId","id","atMs","Number","isFinite","internalDateMs","bounce","complaint","evidence","report","kind","recipients","failedAddresses","status","diagnostic","self","Set","selfAddresses","has","unsubscribe","unsubscribeAddress","to","autoReply","intent","optOut","matched","fresh","threadSubject","subjectIntent","RANK","none","postpone","bounced","replied","opted_out","OUTCOME_OF","auto_reply","hard_bounce","reply","opt_out","decideOutreachThread","input","recipient","handled","handledMessageIds","afterMs","messages","sort","a","b","decision","outcome","decidedBy","classifications","hardBounces","softBounces","classification","push","aboutRecipient","length"],"mappings":"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"}

package/src/lib/engine/thread-message.d.ts

@@ -0,0 +1,80 @@
+/**
+ * @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.
+ */
+/** One MIME part: its media type, and its body as text when it is textual. */
+export interface OutreachThreadMessagePart {
+    /** Lowercase media type without parameters: `text/plain`, `message/delivery-status`. */
+    mimeType: string;
+    /** The decoded body, for a textual part whose body was delivered inline. */
+    text?: string;
+}
+export interface OutreachThreadMessage {
+    /** The provider's message id. */
+    id: string;
+    /** The provider's thread id. */
+    threadId?: string;
+    /** When the provider received the message, epoch ms — Gmail's `internalDate`. */
+    internalDateMs: number;
+    /** The raw `From` header value. */
+    from: string;
+    /** The raw `To` header value. */
+    to: string;
+    subject: string;
+    /** The top-level headers by name. Names are matched without regard to case. */
+    headers: Record<string, string>;
+    /** The provider's plain-text preview. */
+    snippet?: string;
+    labelIds?: string[];
+    /** The first `text/plain` body that is not an attachment, decoded. */
+    textBody?: string;
+    /** The first `text/html` body, decoded — read when there is no text body. */
+    htmlBody?: string;
+    /** Every part, depth first. */
+    parts?: OutreachThreadMessagePart[];
+}
+/** A header's value by name, matched without regard to case; `''` when absent. */
+export declare function outreachHeader(message: Pick<OutreachThreadMessage, 'headers'>, name: string): string;
+export interface GmailApiHeader {
+    name: string;
+    value: string;
+}
+export interface GmailApiMessagePart {
+    partId?: string;
+    mimeType?: string;
+    filename?: string;
+    headers?: GmailApiHeader[];
+    body?: {
+        size?: number;
+        data?: string;
+        attachmentId?: string;
+    };
+    parts?: GmailApiMessagePart[];
+}
+/** `users.messages.get` or a message of `users.threads.get`, with `format=full`. */
+export interface GmailApiMessage {
+    id: string;
+    threadId?: string;
+    labelIds?: string[];
+    snippet?: string;
+    /** Epoch milliseconds, as a string. */
+    internalDate?: string | number;
+    payload?: GmailApiMessagePart;
+}
+/**
+ * The classifier's shape for a Gmail API message. Never throws: a body that
+ * does not decode is left out, and a message with no payload has no text.
+ */
+export declare function outreachThreadMessageFromGmail(message: GmailApiMessage): OutreachThreadMessage;

package/src/lib/engine/thread-message.js

@@ -0,0 +1,143 @@
+/**
+ * @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.
+ */ /*==========================================
+ * A MESSAGE IN A THREAD, AS THE CLASSIFIER READS IT (AGL-2979).
+ *
+ * The runtime reads an enrollment's thread from the provider and hands each
+ * message over in this shape: the headers, the text, and — for a delivery
+ * report — the parts, because a bounce's recipient and status code live in
+ * its `message/delivery-status` part and not in any header.
+ *
+ * {@link outreachThreadMessageFromGmail} builds it from a Gmail API message
+ * resource fetched with `format=full`, so the base64url bodies, the nested
+ * multiparts and the character sets are decoded in one place.
+ *==========================================*/ /** One MIME part: its media type, and its body as text when it is textual. */ import { _ as _extends } from "@swc/helpers/_/_extends";
+/** A header's value by name, matched without regard to case; `''` when absent. */ export function outreachHeader(message, name) {
+    var _ref;
+    const wanted = name.toLowerCase();
+    for (const [key, value] of Object.entries((_ref = message == null ? void 0 : message.headers) != null ? _ref : {})){
+        if (key.toLowerCase() === wanted) return String(value != null ? value : '');
+    }
+    return '';
+}
+const TEXTUAL = /^(text\/|message\/(delivery-status|disposition-notification|global-delivery-status|global-headers|rfc822-headers)$)/;
+function headerOf(headers, name) {
+    var _ref;
+    var _headers_find;
+    const wanted = name.toLowerCase();
+    return (_ref = headers == null ? void 0 : (_headers_find = headers.find((header)=>{
+        var _header_name;
+        return (header == null ? void 0 : (_header_name = header.name) == null ? void 0 : _header_name.toLowerCase()) === wanted;
+    })) == null ? void 0 : _headers_find.value) != null ? _ref : '';
+}
+function charsetOf(contentType) {
+    const match = /charset\s*=\s*"?([^";\s]+)"?/i.exec(contentType);
+    return match ? match[1].toLowerCase() : 'utf-8';
+}
+/** A base64url body decoded to text in the part's own character set. */ function decodeBody(data, charset) {
+    const base64 = data.replace(/-/g, '+').replace(/_/g, '/').replace(/\s+/g, '');
+    const padded = base64 + '='.repeat((4 - base64.length % 4) % 4);
+    const binary = atob(padded);
+    const bytes = new Uint8Array(binary.length);
+    for(let index = 0; index < binary.length; index += 1)bytes[index] = binary.charCodeAt(index);
+    try {
+        return new TextDecoder(charset).decode(bytes);
+    } catch (unused) {
+        return new TextDecoder('utf-8').decode(bytes);
+    }
+}
+const ENTITIES = {
+    amp: '&',
+    lt: '<',
+    gt: '>',
+    quot: '"',
+    apos: "'",
+    nbsp: ' '
+};
+/** Gmail's snippet arrives HTML-escaped: `wasn&#39;t`. */ function unescapeSnippet(snippet) {
+    return snippet.replace(/&(#\d+|#x[0-9a-f]+|[a-z]+);/gi, (whole, code)=>{
+        var _ENTITIES_code_toLowerCase;
+        if (/^#x/i.test(code)) return String.fromCodePoint(parseInt(code.slice(2), 16));
+        if (code.startsWith('#')) return String.fromCodePoint(parseInt(code.slice(1), 10));
+        return (_ENTITIES_code_toLowerCase = ENTITIES[code.toLowerCase()]) != null ? _ENTITIES_code_toLowerCase : whole;
+    });
+}
+/**
+ * The classifier's shape for a Gmail API message. Never throws: a body that
+ * does not decode is left out, and a message with no payload has no text.
+ */ export function outreachThreadMessageFromGmail(message) {
+    var _ref, _payload_headers, _ref1;
+    const payload = (_ref = message == null ? void 0 : message.payload) != null ? _ref : {};
+    const headers = {};
+    for (const header of (_payload_headers = payload.headers) != null ? _payload_headers : []){
+        var _header_value;
+        if ((header == null ? void 0 : header.name) && !(header.name in headers)) headers[header.name] = String((_header_value = header.value) != null ? _header_value : '');
+    }
+    const parts = [];
+    let textBody;
+    let htmlBody;
+    const walk = (part)=>{
+        var _part_mimeType, _part_parts;
+        var _part_body;
+        if (!part) return;
+        const mimeType = String((_part_mimeType = part.mimeType) != null ? _part_mimeType : '').toLowerCase().split(';')[0].trim();
+        const entry = {
+            mimeType
+        };
+        const data = (_part_body = part.body) == null ? void 0 : _part_body.data;
+        if (data && TEXTUAL.test(mimeType)) {
+            try {
+                entry.text = decodeBody(data, charsetOf(headerOf(part.headers, 'Content-Type')));
+            } catch (unused) {
+            // A body that is not valid base64 is treated as absent.
+            }
+        }
+        parts.push(entry);
+        const attachment = Boolean(part.filename) || /^attachment/i.test(headerOf(part.headers, 'Content-Disposition'));
+        if (entry.text !== undefined && !attachment) {
+            if (mimeType === 'text/plain' && textBody === undefined) textBody = entry.text;
+            if (mimeType === 'text/html' && htmlBody === undefined) htmlBody = entry.text;
+        }
+        for (const child of (_part_parts = part.parts) != null ? _part_parts : [])walk(child);
+    };
+    walk(message == null ? void 0 : message.payload);
+    const internalDateMs = Number(message == null ? void 0 : message.internalDate);
+    return _extends({
+        id: String((_ref1 = message == null ? void 0 : message.id) != null ? _ref1 : '')
+    }, (message == null ? void 0 : message.threadId) ? {
+        threadId: message.threadId
+    } : {}, {
+        internalDateMs: Number.isFinite(internalDateMs) ? internalDateMs : 0,
+        from: headerOf(payload.headers, 'From'),
+        to: headerOf(payload.headers, 'To'),
+        subject: headerOf(payload.headers, 'Subject'),
+        headers
+    }, (message == null ? void 0 : message.snippet) ? {
+        snippet: unescapeSnippet(message.snippet)
+    } : {}, (message == null ? void 0 : message.labelIds) ? {
+        labelIds: [
+            ...message.labelIds
+        ]
+    } : {}, textBody !== undefined ? {
+        textBody
+    } : {}, htmlBody !== undefined ? {
+        htmlBody
+    } : {}, {
+        parts
+    });
+}
+
+//# sourceMappingURL=thread-message.js.map

package/src/lib/engine/thread-message.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/outreach/src/lib/engine/thread-message.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 MESSAGE IN A THREAD, AS THE CLASSIFIER READS IT (AGL-2979).\n *\n * The runtime reads an enrollment's thread from the provider and hands each\n * message over in this shape: the headers, the text, and — for a delivery\n * report — the parts, because a bounce's recipient and status code live in\n * its `message/delivery-status` part and not in any header.\n *\n * {@link outreachThreadMessageFromGmail} builds it from a Gmail API message\n * resource fetched with `format=full`, so the base64url bodies, the nested\n * multiparts and the character sets are decoded in one place.\n *==========================================*/\n\n/** One MIME part: its media type, and its body as text when it is textual. */\nexport interface OutreachThreadMessagePart {\n  /** Lowercase media type without parameters: `text/plain`, `message/delivery-status`. */\n  mimeType: string\n  /** The decoded body, for a textual part whose body was delivered inline. */\n  text?: string\n}\n\nexport interface OutreachThreadMessage {\n  /** The provider's message id. */\n  id: string\n  /** The provider's thread id. */\n  threadId?: string\n  /** When the provider received the message, epoch ms — Gmail's `internalDate`. */\n  internalDateMs: number\n  /** The raw `From` header value. */\n  from: string\n  /** The raw `To` header value. */\n  to: string\n  subject: string\n  /** The top-level headers by name. Names are matched without regard to case. */\n  headers: Record<string, string>\n  /** The provider's plain-text preview. */\n  snippet?: string\n  labelIds?: string[]\n  /** The first `text/plain` body that is not an attachment, decoded. */\n  textBody?: string\n  /** The first `text/html` body, decoded — read when there is no text body. */\n  htmlBody?: string\n  /** Every part, depth first. */\n  parts?: OutreachThreadMessagePart[]\n}\n\n/** A header's value by name, matched without regard to case; `''` when absent. */\nexport function outreachHeader(\n  message: Pick<OutreachThreadMessage, 'headers'>,\n  name: string,\n): string {\n  const wanted = name.toLowerCase()\n  for (const [key, value] of Object.entries(message?.headers ?? {})) {\n    if (key.toLowerCase() === wanted) return String(value ?? '')\n  }\n  return ''\n}\n\n/*==========================================\n * THE GMAIL API MESSAGE RESOURCE.\n *==========================================*/\n\nexport interface GmailApiHeader {\n  name: string\n  value: string\n}\n\nexport interface GmailApiMessagePart {\n  partId?: string\n  mimeType?: string\n  filename?: string\n  headers?: GmailApiHeader[]\n  body?: { size?: number; data?: string; attachmentId?: string }\n  parts?: GmailApiMessagePart[]\n}\n\n/** `users.messages.get` or a message of `users.threads.get`, with `format=full`. */\nexport interface GmailApiMessage {\n  id: string\n  threadId?: string\n  labelIds?: string[]\n  snippet?: string\n  /** Epoch milliseconds, as a string. */\n  internalDate?: string | number\n  payload?: GmailApiMessagePart\n}\n\nconst TEXTUAL = /^(text\\/|message\\/(delivery-status|disposition-notification|global-delivery-status|global-headers|rfc822-headers)$)/\n\nfunction headerOf(headers: readonly GmailApiHeader[] | undefined, name: string): string {\n  const wanted = name.toLowerCase()\n  return headers?.find((header) => header?.name?.toLowerCase() === wanted)?.value ?? ''\n}\n\nfunction charsetOf(contentType: string): string {\n  const match = /charset\\s*=\\s*\"?([^\";\\s]+)\"?/i.exec(contentType)\n  return match ? match[1].toLowerCase() : 'utf-8'\n}\n\n/** A base64url body decoded to text in the part's own character set. */\nfunction decodeBody(data: string, charset: string): string {\n  const base64 = data.replace(/-/g, '+').replace(/_/g, '/').replace(/\\s+/g, '')\n  const padded = base64 + '='.repeat((4 - (base64.length % 4)) % 4)\n  const binary = atob(padded)\n  const bytes = new Uint8Array(binary.length)\n  for (let index = 0; index < binary.length; index += 1) bytes[index] = binary.charCodeAt(index)\n  try {\n    return new TextDecoder(charset).decode(bytes)\n  } catch {\n    return new TextDecoder('utf-8').decode(bytes)\n  }\n}\n\nconst ENTITIES: Record<string, string> = { amp: '&', lt: '<', gt: '>', quot: '\"', apos: \"'\", nbsp: ' ' }\n\n/** Gmail's snippet arrives HTML-escaped: `wasn&#39;t`. */\nfunction unescapeSnippet(snippet: string): string {\n  return snippet.replace(/&(#\\d+|#x[0-9a-f]+|[a-z]+);/gi, (whole, code: string) => {\n    if (/^#x/i.test(code)) return String.fromCodePoint(parseInt(code.slice(2), 16))\n    if (code.startsWith('#')) return String.fromCodePoint(parseInt(code.slice(1), 10))\n    return ENTITIES[code.toLowerCase()] ?? whole\n  })\n}\n\n/**\n * The classifier's shape for a Gmail API message. Never throws: a body that\n * does not decode is left out, and a message with no payload has no text.\n */\nexport function outreachThreadMessageFromGmail(message: GmailApiMessage): OutreachThreadMessage {\n  const payload = message?.payload ?? {}\n  const headers: Record<string, string> = {}\n  for (const header of payload.headers ?? []) {\n    if (header?.name && !(header.name in headers)) headers[header.name] = String(header.value ?? '')\n  }\n  const parts: OutreachThreadMessagePart[] = []\n  let textBody: string | undefined\n  let htmlBody: string | undefined\n  const walk = (part: GmailApiMessagePart | undefined) => {\n    if (!part) return\n    const mimeType = String(part.mimeType ?? '').toLowerCase().split(';')[0].trim()\n    const entry: OutreachThreadMessagePart = { mimeType }\n    const data = part.body?.data\n    if (data && TEXTUAL.test(mimeType)) {\n      try {\n        entry.text = decodeBody(data, charsetOf(headerOf(part.headers, 'Content-Type')))\n      } catch {\n        // A body that is not valid base64 is treated as absent.\n      }\n    }\n    parts.push(entry)\n    const attachment = Boolean(part.filename) || /^attachment/i.test(headerOf(part.headers, 'Content-Disposition'))\n    if (entry.text !== undefined && !attachment) {\n      if (mimeType === 'text/plain' && textBody === undefined) textBody = entry.text\n      if (mimeType === 'text/html' && htmlBody === undefined) htmlBody = entry.text\n    }\n    for (const child of part.parts ?? []) walk(child)\n  }\n  walk(message?.payload)\n  const internalDateMs = Number(message?.internalDate)\n  return {\n    id: String(message?.id ?? ''),\n    ...(message?.threadId ? { threadId: message.threadId } : {}),\n    internalDateMs: Number.isFinite(internalDateMs) ? internalDateMs : 0,\n    from: headerOf(payload.headers, 'From'),\n    to: headerOf(payload.headers, 'To'),\n    subject: headerOf(payload.headers, 'Subject'),\n    headers,\n    ...(message?.snippet ? { snippet: unescapeSnippet(message.snippet) } : {}),\n    ...(message?.labelIds ? { labelIds: [...message.labelIds] } : {}),\n    ...(textBody !== undefined ? { textBody } : {}),\n    ...(htmlBody !== undefined ? { htmlBody } : {}),\n    parts,\n  }\n}\n"],"names":["outreachHeader","message","name","wanted","toLowerCase","key","value","Object","entries","headers","String","TEXTUAL","headerOf","find","header","charsetOf","contentType","match","exec","decodeBody","data","charset","base64","replace","padded","repeat","length","binary","atob","bytes","Uint8Array","index","charCodeAt","TextDecoder","decode","ENTITIES","amp","lt","gt","quot","apos","nbsp","unescapeSnippet","snippet","whole","code","test","fromCodePoint","parseInt","slice","startsWith","outreachThreadMessageFromGmail","payload","parts","textBody","htmlBody","walk","part","mimeType","split","trim","entry","body","text","push","attachment","Boolean","filename","undefined","child","internalDateMs","Number","internalDate","id","threadId","isFinite","from","to","subject","labelIds"],"mappings":"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"}

package/src/lib/enrollment/enroll-people.d.ts

@@ -0,0 +1,81 @@
+/**
+ * @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 OutreachGateLookups } from '../engine/gates';
+import { type OutreachAttestations, type OutreachSequenceSettings } from '../model/outreach.types';
+import type { OutreachEnrollBlock, OutreachEnrollPreviewPerson } from '../model/outreach-api';
+type Firestore = FirebaseFirestore.Firestore;
+/** One person as the preview and the enroll read them. */
+export interface OutreachEnrollCandidate {
+    contactId: string;
+    /** The contact document, or `null` when it no longer exists. */
+    contact: Record<string, unknown> | null;
+    /** Whether the sequence's site may see the contact. */
+    visible: boolean;
+    /** The name the sequence's site knows them by; `''` for none. */
+    name: string;
+    /** The primary address, normalized, or `null` when there is none. */
+    email: string | null;
+    /** The company the contact is filed under at that site, when there is one. */
+    company: Record<string, unknown> | null;
+}
+/**
+ * The contacts, as the sequence's site knows them, and the company each is
+ * filed under there — two batched reads for everyone.
+ */
+export declare function readOutreachEnrollCandidates(firestore: Firestore, input: {
+    orgId: string;
+    hostId: string;
+    contactGroupId: string;
+    contactIds: readonly string[];
+}): Promise<OutreachEnrollCandidate[]>;
+/** What stands in the way before the gates are asked anything. */
+export declare function outreachCandidateBlocks(candidate: OutreachEnrollCandidate, facts: {
+    siteName: string;
+    alreadyInSequence: boolean;
+}): OutreachEnrollBlock[];
+export interface OutreachGateQuestion {
+    candidate: OutreachEnrollCandidate;
+    lookups: OutreachGateLookups;
+    /** The sequence's settings, its countries already capped by the organization's. */
+    settings: OutreachSequenceSettings;
+    contactGroupId: string;
+}
+/** Where one person stands before the rep confirms anything — see the module note. */
+export declare function previewOutreachPerson(question: OutreachGateQuestion, facts: {
+    siteName: string;
+    alreadyInSequence: boolean;
+}): OutreachEnrollPreviewPerson;
+export interface OutreachEnrollDecision {
+    allowed: boolean;
+    blocks: OutreachEnrollBlock[];
+    cold: boolean;
+    /** The address as the gates normalized it. */
+    email: string | null;
+    /** What the rep confirmed, stamped with who and when. */
+    attestations: OutreachAttestations;
+}
+/** Confirm's answer for one person, with what the rep supplied — see the module note. */
+export declare function decideOutreachEnrollment(question: OutreachGateQuestion, facts: {
+    siteName: string;
+    alreadyInSequence: boolean;
+}, supplied: {
+    personalLine: string;
+    attestations: readonly unknown[];
+    uid: string;
+    nowMs: number;
+}): OutreachEnrollDecision;
+export {};

package/src/lib/enrollment/enroll-people.js

@@ -0,0 +1,250 @@
+import { _ as _extends } from "@swc/helpers/_/_extends";
+import { _ as _object_without_properties_loose } from "@swc/helpers/_/_object_without_properties_loose";
+/**
+ * @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.
+ */ /*==========================================
+ * WHO CAN BE ENROLLED, AND WHAT THE REP STILL OWES (AGL-2980).
+ *
+ * The enroll dialog shows every person a view or a search named, each
+ * marked eligible, blocked, or waiting on the rep; Confirm asks the same
+ * question again, on the server, with what the rep supplied. Both answers
+ * come from the engine's `evaluateOutreachGates` — this module only reads
+ * the people and asks it the right questions.
+ *
+ * ## Three questions of one pure function
+ *
+ * The gates refuse a cold contact until the rep writes a personal line and
+ * ticks the attestations, and refuse an address in an unknown country until
+ * the rep confirms it is a US business address. So a preview asks:
+ *
+ *   1. as the person stands, with nothing confirmed — allowed means
+ *      ELIGIBLE;
+ *   2. as if the rep confirmed everything they can — refused means BLOCKED,
+ *      for the reasons that remain, which no tick can clear;
+ *   3. otherwise the person is WAITING ON THE REP, for what (1) found
+ *      missing.
+ *
+ * The confirmation in (2) is hypothetical and never stored: Confirm stamps
+ * only what the rep ticked, with their uid and the time, and asks again.
+ *
+ * ## One enrollment per person per sequence, ever
+ *
+ * The enrollment's id is the sequence and the contact
+ * (`outreachEnrollmentId`), and it is written with `create()`. A person who
+ * finished, replied or was stopped is not sent the same emails a second
+ * time by being enrolled again, and two members confirming the same person
+ * at once write one enrollment.
+ *==========================================*/ import { normalizeContactEmail, contactDisplayName, readContactFacet } from "@aglyn/aglyn/app-utils/contacts";
+import { visibleToHost } from "@aglyn/aglyn/app-utils/scope-tokens";
+import { evaluateOutreachGates } from "../engine/gates.js";
+import { outreachAttestationsFrom } from "../engine/enrollment-state.js";
+import { OUTREACH_ATTESTATION_KINDS } from "../model/outreach.types.js";
+/** `getAll` takes this many references at most per call. */ const GET_ALL_CHUNK = 300;
+async function getAllChunked(firestore, refs) {
+    const snapshots = [];
+    for(let start = 0; start < refs.length; start += GET_ALL_CHUNK){
+        snapshots.push(...await firestore.getAll(...refs.slice(start, start + GET_ALL_CHUNK)));
+    }
+    return snapshots;
+}
+/**
+ * The contacts, as the sequence's site knows them, and the company each is
+ * filed under there — two batched reads for everyone.
+ */ export async function readOutreachEnrollCandidates(firestore, input) {
+    if (!input.contactIds.length) return [];
+    const org = firestore.collection('orgs').doc(input.orgId);
+    const snapshots = await getAllChunked(firestore, input.contactIds.map((id)=>org.collection('contacts').doc(id)));
+    const read = input.contactIds.map((contactId, index)=>{
+        var _readContactFacet_companyId;
+        var _snapshots_index;
+        const data = ((_snapshots_index = snapshots[index]) == null ? void 0 : _snapshots_index.exists) ? snapshots[index].data() : null;
+        return {
+            contactId,
+            contact: data,
+            visible: data ? visibleToHost(data['visibleTo'], input.hostId) : false,
+            name: data ? contactDisplayName(data, input.contactGroupId).trim() : '',
+            email: data ? normalizeContactEmail(data['email']) : null,
+            companyId: data ? String((_readContactFacet_companyId = readContactFacet(data, input.contactGroupId).companyId) != null ? _readContactFacet_companyId : '') : ''
+        };
+    });
+    const companyIds = [
+        ...new Set(read.map((entry)=>entry.companyId).filter(Boolean))
+    ];
+    const companies = new Map();
+    if (companyIds.length) {
+        const found = await getAllChunked(firestore, companyIds.map((id)=>org.collection('companies').doc(id)));
+        found.forEach((snapshot, index)=>{
+            if (snapshot.exists) companies.set(companyIds[index], snapshot.data());
+        });
+    }
+    return read.map((_0)=>{
+        let { companyId } = _0, candidate = _object_without_properties_loose(_0, [
+            "companyId"
+        ]);
+        var _companies_get;
+        return _extends({}, candidate, {
+            company: companyId ? (_companies_get = companies.get(companyId)) != null ? _companies_get : null : null
+        });
+    });
+}
+/** What stands in the way before the gates are asked anything. */ export function outreachCandidateBlocks(candidate, facts) {
+    if (!candidate.contact) {
+        return [
+            {
+                code: 'contact_missing',
+                reason: 'This contact no longer exists in the CRM.'
+            }
+        ];
+    }
+    const blocks = [];
+    if (!candidate.visible) {
+        blocks.push({
+            code: 'not_in_site',
+            reason: `This contact isn't in ${facts.siteName || "this sequence's site"}'s CRM.`
+        });
+    }
+    if (!candidate.email) {
+        blocks.push({
+            code: 'no_email',
+            reason: 'This contact has no email address.'
+        });
+    }
+    if (facts.alreadyInSequence) {
+        blocks.push({
+            code: 'already_in_sequence',
+            reason: "This person has already been in this sequence, so they won't be sent its emails again."
+        });
+    }
+    return blocks;
+}
+/** Every attestation, stamped for a hypothetical question only — never stored. */ const EVERYTHING_CONFIRMED = Object.fromEntries(OUTREACH_ATTESTATION_KINDS.map((kind)=>[
+        kind,
+        {
+            uid: 'preview',
+            atMs: 1
+        }
+    ]));
+const blocksOf = (blocks)=>blocks.map(({ code, reason })=>({
+            code,
+            reason
+        }));
+/** Where one person stands before the rep confirms anything — see the module note. */ export function previewOutreachPerson(question, facts) {
+    const { candidate } = question;
+    const person = {
+        contactId: candidate.contactId,
+        name: candidate.name,
+        email: candidate.email
+    };
+    const early = outreachCandidateBlocks(candidate, facts);
+    if (early.length) {
+        return _extends({}, person, {
+            cold: false,
+            country: null,
+            status: 'blocked',
+            blocks: early,
+            requires: {
+                personalLine: false,
+                attestations: []
+            }
+        });
+    }
+    const ask = (personalLine, attestations)=>{
+        var _candidate_email;
+        return evaluateOutreachGates({
+            email: (_candidate_email = candidate.email) != null ? _candidate_email : '',
+            contact: candidate.contact,
+            contactGroupId: question.contactGroupId,
+            company: candidate.company,
+            settings: question.settings,
+            personalLine,
+            attestations,
+            lookups: question.lookups
+        });
+    };
+    const asIs = ask('', {});
+    const known = {
+        cold: asIs.cold,
+        country: asIs.country.country
+    };
+    if (asIs.allowed) {
+        return _extends({}, person, known, {
+            status: 'eligible',
+            blocks: [],
+            requires: {
+                personalLine: false,
+                attestations: []
+            }
+        });
+    }
+    // The line is only checked for being present, so any sentence stands in.
+    const confirmed = ask('A personal line.', EVERYTHING_CONFIRMED);
+    if (!confirmed.allowed) {
+        return _extends({}, person, known, {
+            status: 'blocked',
+            blocks: blocksOf(confirmed.blocks),
+            requires: {
+                personalLine: false,
+                attestations: []
+            }
+        });
+    }
+    const attestations = asIs.cold ? [
+        ...asIs.missingAttestations
+    ] : asIs.blocks.some((block)=>block.code === 'country_unknown') ? [
+        'us_business_address'
+    ] : [];
+    return _extends({}, person, known, {
+        status: 'needs_confirmation',
+        blocks: [],
+        requires: {
+            personalLine: asIs.blocks.some((block)=>block.code === 'personal_line_missing'),
+            attestations
+        }
+    });
+}
+/** Confirm's answer for one person, with what the rep supplied — see the module note. */ export function decideOutreachEnrollment(question, facts, supplied) {
+    var _question_candidate_email;
+    const attestations = outreachAttestationsFrom(supplied.attestations, supplied.uid, supplied.nowMs);
+    const early = outreachCandidateBlocks(question.candidate, facts);
+    if (early.length) {
+        return {
+            allowed: false,
+            blocks: early,
+            cold: false,
+            email: question.candidate.email,
+            attestations
+        };
+    }
+    const result = evaluateOutreachGates({
+        email: (_question_candidate_email = question.candidate.email) != null ? _question_candidate_email : '',
+        contact: question.candidate.contact,
+        contactGroupId: question.contactGroupId,
+        company: question.candidate.company,
+        settings: question.settings,
+        personalLine: supplied.personalLine,
+        attestations,
+        lookups: question.lookups
+    });
+    return {
+        allowed: result.allowed,
+        blocks: blocksOf(result.blocks),
+        cold: result.cold,
+        email: result.email,
+        attestations
+    };
+}
+
+//# sourceMappingURL=enroll-people.js.map