@aglyn/plugins-outreach 1.0.0-beta.143

package/src/lib/engine/opt-out-intent.js

@@ -0,0 +1,220 @@
+/**
+ * @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 REPLY THAT SAYS STOP (AGL-2979).
+ *
+ * Every Outreach email tells its reader to reply "no" to be left alone, so
+ * a reply has to be read for that. Any reply already stops its sequence;
+ * reading one as an OPT-OUT also puts the address on the organization's
+ * do-not-contact list, so no later sequence reaches it either. Both mistakes
+ * cost something: a missed opt-out lets another sequence write to somebody
+ * who said no, and a false one silently loses a prospect who said "no rush".
+ *
+ * ## Only the reply's own words
+ *
+ * A reply quotes the email it answers, and that email's footer says "Reply
+ * 'no'". So the quoted history is cut first — the CRM capture reader's
+ * `stripQuotedHistory` — along with a signature and any footer line a mail
+ * client quoted without marking it.
+ *
+ * ## What counts
+ *
+ * - A short reply that says nothing but no: "No.", "No thanks", "Nope",
+ *   "Pass", "Stop" — with a greeting and a sign-off allowed around it.
+ * - A request anywhere in the reply: unsubscribe, remove me, take me off
+ *   the list, stop emailing, don't contact me, opt out, no more emails —
+ *   unless it is negated ("please don't remove me").
+ * - "Not interested", unless it defers ("not interested yet", "not
+ *   interested right now, try me next quarter") or asks ("not interested?").
+ * - A reply that calls the email spam, which is also a COMPLAINT.
+ *
+ * "No rush", "no problem" and "no worries" are none of these: a "no" only
+ * counts when it is the whole answer.
+ *==========================================*/ import { stripQuotedHistory } from "@aglyn/aglyn/app-utils/crm-inbound";
+const NONE = {
+    optOut: false,
+    complaint: false,
+    matched: null
+};
+/** A line of the footer every Outreach email carries, however a client re-quoted it. */ const FOOTER_LINE = /reply\s+["“”'‘’]?no["“”'‘’]?\s+and\s+i\s+won['’]?t\s+email|business\s+solicitation\s+from/i;
+/**
+ * The words a reply adds to its thread: the text above the quoted history,
+ * with a signature and any quoted footer line removed.
+ */ export function outreachFreshReplyText(text) {
+    const body = stripQuotedHistory(String(text != null ? text : '').replace(/\r\n?/g, '\n').replace(/[\u00a0\u202f]/g, ' '));
+    const lines = body.split('\n');
+    const signature = lines.findIndex((line)=>/^--\s*$/.test(line));
+    return (signature >= 0 ? lines.slice(0, signature) : lines).filter((line)=>!FOOTER_LINE.test(line)).join('\n').trim();
+}
+/** Curly quotes straightened, case folded, whitespace settled. */ function fold(text) {
+    return text.replace(/[‘’]/g, "'").replace(/[“”]/g, '"').toLowerCase().replace(/\s+/g, ' ').trim();
+}
+const GREETING_LINE = /^(hi|hello|hey|dear|greetings|good (morning|afternoon|evening))\b[^\n]{0,40}$/i;
+const GREETING_LEAD = /^(hi|hello|hey|dear|greetings)(\s+[a-z'’-]+)?\s*[,!.:–—-]\s*/i;
+const SIGN_OFF = /^(thanks|thank you|thx|many thanks|cheers|regards|best|best regards|kind regards|warm regards|sincerely|all the best|sent from my\b.*|get outlook\b.*)[\s,.!]*$/i;
+const NAME = "[A-Z][a-z'’-]+( [A-Z][a-z'’-]+)?";
+/** Thanks, then a signed name: "No thanks, Jordan" or "No thanks — Jordan". */ const THANKS_THEN_NAME = new RegExp(`\\b(thanks|thank you|thx|cheers)[\\s,–—-]+${NAME}[.!]?\\s*$`, 'i');
+const NAME_LINE = new RegExp(`^${NAME}[.!]?$`);
+/**
+ * What is left of a reply once its greeting, its sign-off and a name signed
+ * after "thanks" are gone. A name is only taken off after a thank-you,
+ * because "No, WordPress." is an answer about a platform, not a signature.
+ */ function answerOnly(fresh) {
+    const lines = fresh.split('\n').map((line)=>line.trim()).filter(Boolean);
+    if (lines.length > 1 && GREETING_LINE.test(lines[0])) lines.shift();
+    const signOff = lines.findIndex((line, index)=>index > 0 && SIGN_OFF.test(line));
+    const kept = signOff >= 0 ? lines.slice(0, signOff) : lines;
+    if (kept.length > 1 && NAME_LINE.test(kept[kept.length - 1]) && /\b(thanks|thank you|thx|cheers)[\s,.!]*$/i.test(kept[kept.length - 2])) {
+        kept.pop();
+    }
+    return kept.join(' ').replace(GREETING_LEAD, '').replace(THANKS_THEN_NAME, '$1');
+}
+/** The only words a reply may hold to be read as a bare "no". */ const BARE_NO_WORDS = new Set([
+    'no',
+    'nope',
+    'nah',
+    'pass',
+    "i'll",
+    'ill',
+    'i',
+    'will',
+    'stop',
+    'unsubscribe',
+    'remove',
+    'me',
+    'us',
+    'please',
+    'thanks',
+    'thank',
+    'you',
+    'thx',
+    'sorry',
+    'but',
+    'not',
+    'for',
+    'interested'
+]);
+const BARE_NO_TRIGGERS = new Set([
+    'no',
+    'nope',
+    'nah',
+    'pass',
+    'stop',
+    'unsubscribe',
+    'remove'
+]);
+function bareNo(answer) {
+    const words = fold(answer).replace(/[^a-z' ]+/g, ' ').split(' ').filter(Boolean);
+    if (!words.length || words.length > 6) return null;
+    if (!words.every((word)=>BARE_NO_WORDS.has(word))) return null;
+    const said = words.join(' ');
+    if (words.some((word)=>BARE_NO_TRIGGERS.has(word)) || /\bnot interested\b|\bnot for (me|us)\b/.test(said)) {
+        return said;
+    }
+    return null;
+}
+/** Negations that turn a request around when they come just before it. */ const NEGATED = /\b(don't|dont|do not|didn't|didnt|did not|never|not|no need to|please don't|wouldn't|won't)\s+(\w+\s+){0,2}$/;
+const REQUESTS = [
+    /\bunsubscrib(e|ed|ing)\b/,
+    /\bopt(ed|ing)?[ -]?(me )?out\b/,
+    /\bremove (me|us|my (email|e-mail|address|name|details|info))\b/,
+    /\bremove\b[^.!?\n]{0,30}\bfrom (your|the|this|all) (list|lists|mailing list|emails?|database|system|sequence)\b/,
+    /\btake (me|us|my (email|e-mail|address|name)) off\b/,
+    /\btake\b[^.!?\n]{0,30}\boff (your|the|this|all) (list|lists|mailing list|emails?)\b/,
+    // Aimed at us: "stop emailing me", "stop sending these", "stop contacting." —
+    // not "we had to stop sending newsletters ourselves".
+    /\b(stop|quit) (emailing|e-mailing|mailing|contacting|messaging|writing|sending|reaching out)(?=\s*([.!,;]|$)|\s+(me|us|my|our|this|these|those|them|to (me|us)|emails?|e-mails?|messages?|mail)\b)/,
+    /\bplease stop\b/,
+    /^stop\b(?! (by|in|over|at|the|thinking|worrying))/,
+    /\b(do not|don't|dont|never) (email|e-mail|contact|message|write to|reach out to) (me|us)\b/,
+    /\bno (more|further) (emails?|e-mails?|messages|mail|contact)\b/,
+    /\b(don't|do not) want (to (hear|receive)|any more|these)\b[^.!?\n]{0,20}\b(emails?|messages|from you)\b/
+];
+const COMPLAINTS = [
+    /\b(this|that|it|you|your emails?|these emails?|this email)\s*(is|are|'s|'re)\s+(just\s+)?spam\b/,
+    /\b(stop|quit|don't|do not) spam(ming)?\b/,
+    /\bspamming (me|us|my|our)\b/,
+    /\b(i|we)('ve| have| just| will| am| are)?\s*(report(ed|ing)?|mark(ed|ing)?|flag(ged|ging)?)\b[^.!?\n]{0,30}\b(as|for) spam\b/
+];
+/** Words after "not interested" that put it off rather than rule it out. */ const DEFERRAL = /^[\s,]*(yet|right now|for now|now|at the moment|at this (time|moment|point|stage)|today|this (week|month|quarter|year)|until|in the (near )?future|but\b|however\b|though\b)/;
+function notInterested(text) {
+    const pattern = /\bnot (really |at all )?interested\b/g;
+    for(let match = pattern.exec(text); match; match = pattern.exec(text)){
+        const before = text.slice(0, match.index);
+        const after = text.slice(match.index + match[0].length);
+        const sentenceEnd = after.search(/[.!?\n]/);
+        const rest = sentenceEnd >= 0 ? after.slice(0, sentenceEnd + 1) : after;
+        if (rest.trimEnd().endsWith('?')) continue;
+        if (DEFERRAL.test(after)) continue;
+        if (/\b(if|unless|in case|are you|were you|you're|you are)\s+(\w+\s+){0,2}$/.test(before)) continue;
+        return match[0];
+    }
+    return null;
+}
+/**
+ * Whether a SUBJECT says nothing but stop — "Unsubscribe", "Remove me",
+ * "STOP" — as a message sent from an unsubscribe link, or typed fresh, does.
+ * Only a bare answer counts: a subject is a sender's headline, and "Stop
+ * losing leads" is one.
+ */ export function detectOutreachOptOutSubject(subject) {
+    const said = bareNo(String(subject != null ? subject : ''));
+    return said ? {
+        optOut: true,
+        complaint: false,
+        matched: said
+    } : NONE;
+}
+/**
+ * Whether a reply's text asks to be left alone — see the module note. Pass
+ * the reply's text as received; the quoted history is removed here.
+ */ export function detectOutreachOptOutIntent(text) {
+    const fresh = outreachFreshReplyText(text);
+    if (!fresh) return NONE;
+    const folded = fold(fresh);
+    for (const pattern of COMPLAINTS){
+        const match = pattern.exec(folded);
+        if (match) return {
+            optOut: true,
+            complaint: true,
+            matched: match[0]
+        };
+    }
+    const bare = bareNo(answerOnly(fresh));
+    if (bare) return {
+        optOut: true,
+        complaint: false,
+        matched: bare
+    };
+    for (const pattern of REQUESTS){
+        const match = pattern.exec(folded);
+        if (match && !NEGATED.test(folded.slice(0, match.index))) {
+            return {
+                optOut: true,
+                complaint: false,
+                matched: match[0]
+            };
+        }
+    }
+    const declined = notInterested(folded);
+    if (declined) return {
+        optOut: true,
+        complaint: false,
+        matched: declined
+    };
+    return NONE;
+}
+
+//# sourceMappingURL=opt-out-intent.js.map

package/src/lib/engine/opt-out-intent.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/outreach/src/lib/engine/opt-out-intent.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 REPLY THAT SAYS STOP (AGL-2979).\n *\n * Every Outreach email tells its reader to reply \"no\" to be left alone, so\n * a reply has to be read for that. Any reply already stops its sequence;\n * reading one as an OPT-OUT also puts the address on the organization's\n * do-not-contact list, so no later sequence reaches it either. Both mistakes\n * cost something: a missed opt-out lets another sequence write to somebody\n * who said no, and a false one silently loses a prospect who said \"no rush\".\n *\n * ## Only the reply's own words\n *\n * A reply quotes the email it answers, and that email's footer says \"Reply\n * 'no'\". So the quoted history is cut first — the CRM capture reader's\n * `stripQuotedHistory` — along with a signature and any footer line a mail\n * client quoted without marking it.\n *\n * ## What counts\n *\n * - A short reply that says nothing but no: \"No.\", \"No thanks\", \"Nope\",\n *   \"Pass\", \"Stop\" — with a greeting and a sign-off allowed around it.\n * - A request anywhere in the reply: unsubscribe, remove me, take me off\n *   the list, stop emailing, don't contact me, opt out, no more emails —\n *   unless it is negated (\"please don't remove me\").\n * - \"Not interested\", unless it defers (\"not interested yet\", \"not\n *   interested right now, try me next quarter\") or asks (\"not interested?\").\n * - A reply that calls the email spam, which is also a COMPLAINT.\n *\n * \"No rush\", \"no problem\" and \"no worries\" are none of these: a \"no\" only\n * counts when it is the whole answer.\n *==========================================*/\n\nimport { stripQuotedHistory } from '@aglyn/aglyn/app-utils/crm-inbound'\n\nexport interface OutreachOptOutIntent {\n  /** The reply asks not to be emailed again. */\n  optOut: boolean\n  /** The reply calls the email spam — an opt-out that also counts against the mailbox. */\n  complaint: boolean\n  /** The words that decided it, for the timeline and the log; `null` when nothing matched. */\n  matched: string | null\n}\n\nconst NONE: OutreachOptOutIntent = { optOut: false, complaint: false, matched: null }\n\n/** A line of the footer every Outreach email carries, however a client re-quoted it. */\nconst FOOTER_LINE = /reply\\s+[\"“”'‘’]?no[\"“”'‘’]?\\s+and\\s+i\\s+won['’]?t\\s+email|business\\s+solicitation\\s+from/i\n\n/**\n * The words a reply adds to its thread: the text above the quoted history,\n * with a signature and any quoted footer line removed.\n */\nexport function outreachFreshReplyText(text: unknown): string {\n  const body = stripQuotedHistory(\n    String(text ?? '')\n      .replace(/\\r\\n?/g, '\\n')\n      .replace(/[\\u00a0\\u202f]/g, ' '),\n  )\n  const lines = body.split('\\n')\n  const signature = lines.findIndex((line) => /^--\\s*$/.test(line))\n  return (signature >= 0 ? lines.slice(0, signature) : lines)\n    .filter((line) => !FOOTER_LINE.test(line))\n    .join('\\n')\n    .trim()\n}\n\n/** Curly quotes straightened, case folded, whitespace settled. */\nfunction fold(text: string): string {\n  return text\n    .replace(/[‘’]/g, \"'\")\n    .replace(/[“”]/g, '\"')\n    .toLowerCase()\n    .replace(/\\s+/g, ' ')\n    .trim()\n}\n\nconst GREETING_LINE = /^(hi|hello|hey|dear|greetings|good (morning|afternoon|evening))\\b[^\\n]{0,40}$/i\nconst GREETING_LEAD = /^(hi|hello|hey|dear|greetings)(\\s+[a-z'’-]+)?\\s*[,!.:–—-]\\s*/i\nconst SIGN_OFF =\n  /^(thanks|thank you|thx|many thanks|cheers|regards|best|best regards|kind regards|warm regards|sincerely|all the best|sent from my\\b.*|get outlook\\b.*)[\\s,.!]*$/i\nconst NAME = \"[A-Z][a-z'’-]+( [A-Z][a-z'’-]+)?\"\n/** Thanks, then a signed name: \"No thanks, Jordan\" or \"No thanks — Jordan\". */\nconst THANKS_THEN_NAME = new RegExp(`\\\\b(thanks|thank you|thx|cheers)[\\\\s,–—-]+${NAME}[.!]?\\\\s*$`, 'i')\nconst NAME_LINE = new RegExp(`^${NAME}[.!]?$`)\n\n/**\n * What is left of a reply once its greeting, its sign-off and a name signed\n * after \"thanks\" are gone. A name is only taken off after a thank-you,\n * because \"No, WordPress.\" is an answer about a platform, not a signature.\n */\nfunction answerOnly(fresh: string): string {\n  const lines = fresh\n    .split('\\n')\n    .map((line) => line.trim())\n    .filter(Boolean)\n  if (lines.length > 1 && GREETING_LINE.test(lines[0])) lines.shift()\n  const signOff = lines.findIndex((line, index) => index > 0 && SIGN_OFF.test(line))\n  const kept = signOff >= 0 ? lines.slice(0, signOff) : lines\n  if (\n    kept.length > 1 &&\n    NAME_LINE.test(kept[kept.length - 1]) &&\n    /\\b(thanks|thank you|thx|cheers)[\\s,.!]*$/i.test(kept[kept.length - 2])\n  ) {\n    kept.pop()\n  }\n  return kept\n    .join(' ')\n    .replace(GREETING_LEAD, '')\n    .replace(THANKS_THEN_NAME, '$1')\n}\n\n/** The only words a reply may hold to be read as a bare \"no\". */\nconst BARE_NO_WORDS = new Set([\n  'no',\n  'nope',\n  'nah',\n  'pass',\n  \"i'll\",\n  'ill',\n  'i',\n  'will',\n  'stop',\n  'unsubscribe',\n  'remove',\n  'me',\n  'us',\n  'please',\n  'thanks',\n  'thank',\n  'you',\n  'thx',\n  'sorry',\n  'but',\n  'not',\n  'for',\n  'interested',\n])\nconst BARE_NO_TRIGGERS = new Set(['no', 'nope', 'nah', 'pass', 'stop', 'unsubscribe', 'remove'])\n\nfunction bareNo(answer: string): string | null {\n  const words = fold(answer)\n    .replace(/[^a-z' ]+/g, ' ')\n    .split(' ')\n    .filter(Boolean)\n  if (!words.length || words.length > 6) return null\n  if (!words.every((word) => BARE_NO_WORDS.has(word))) return null\n  const said = words.join(' ')\n  if (\n    words.some((word) => BARE_NO_TRIGGERS.has(word)) ||\n    /\\bnot interested\\b|\\bnot for (me|us)\\b/.test(said)\n  ) {\n    return said\n  }\n  return null\n}\n\n/** Negations that turn a request around when they come just before it. */\nconst NEGATED = /\\b(don't|dont|do not|didn't|didnt|did not|never|not|no need to|please don't|wouldn't|won't)\\s+(\\w+\\s+){0,2}$/\n\nconst REQUESTS: readonly RegExp[] = [\n  /\\bunsubscrib(e|ed|ing)\\b/,\n  /\\bopt(ed|ing)?[ -]?(me )?out\\b/,\n  /\\bremove (me|us|my (email|e-mail|address|name|details|info))\\b/,\n  /\\bremove\\b[^.!?\\n]{0,30}\\bfrom (your|the|this|all) (list|lists|mailing list|emails?|database|system|sequence)\\b/,\n  /\\btake (me|us|my (email|e-mail|address|name)) off\\b/,\n  /\\btake\\b[^.!?\\n]{0,30}\\boff (your|the|this|all) (list|lists|mailing list|emails?)\\b/,\n  // Aimed at us: \"stop emailing me\", \"stop sending these\", \"stop contacting.\" —\n  // not \"we had to stop sending newsletters ourselves\".\n  /\\b(stop|quit) (emailing|e-mailing|mailing|contacting|messaging|writing|sending|reaching out)(?=\\s*([.!,;]|$)|\\s+(me|us|my|our|this|these|those|them|to (me|us)|emails?|e-mails?|messages?|mail)\\b)/,\n  /\\bplease stop\\b/,\n  /^stop\\b(?! (by|in|over|at|the|thinking|worrying))/,\n  /\\b(do not|don't|dont|never) (email|e-mail|contact|message|write to|reach out to) (me|us)\\b/,\n  /\\bno (more|further) (emails?|e-mails?|messages|mail|contact)\\b/,\n  /\\b(don't|do not) want (to (hear|receive)|any more|these)\\b[^.!?\\n]{0,20}\\b(emails?|messages|from you)\\b/,\n]\n\nconst COMPLAINTS: readonly RegExp[] = [\n  /\\b(this|that|it|you|your emails?|these emails?|this email)\\s*(is|are|'s|'re)\\s+(just\\s+)?spam\\b/,\n  /\\b(stop|quit|don't|do not) spam(ming)?\\b/,\n  /\\bspamming (me|us|my|our)\\b/,\n  /\\b(i|we)('ve| have| just| will| am| are)?\\s*(report(ed|ing)?|mark(ed|ing)?|flag(ged|ging)?)\\b[^.!?\\n]{0,30}\\b(as|for) spam\\b/,\n]\n\n/** Words after \"not interested\" that put it off rather than rule it out. */\nconst DEFERRAL =\n  /^[\\s,]*(yet|right now|for now|now|at the moment|at this (time|moment|point|stage)|today|this (week|month|quarter|year)|until|in the (near )?future|but\\b|however\\b|though\\b)/\n\nfunction notInterested(text: string): string | null {\n  const pattern = /\\bnot (really |at all )?interested\\b/g\n  for (let match = pattern.exec(text); match; match = pattern.exec(text)) {\n    const before = text.slice(0, match.index)\n    const after = text.slice(match.index + match[0].length)\n    const sentenceEnd = after.search(/[.!?\\n]/)\n    const rest = sentenceEnd >= 0 ? after.slice(0, sentenceEnd + 1) : after\n    if (rest.trimEnd().endsWith('?')) continue\n    if (DEFERRAL.test(after)) continue\n    if (/\\b(if|unless|in case|are you|were you|you're|you are)\\s+(\\w+\\s+){0,2}$/.test(before)) continue\n    return match[0]\n  }\n  return null\n}\n\n/**\n * Whether a SUBJECT says nothing but stop — \"Unsubscribe\", \"Remove me\",\n * \"STOP\" — as a message sent from an unsubscribe link, or typed fresh, does.\n * Only a bare answer counts: a subject is a sender's headline, and \"Stop\n * losing leads\" is one.\n */\nexport function detectOutreachOptOutSubject(subject: unknown): OutreachOptOutIntent {\n  const said = bareNo(String(subject ?? ''))\n  return said ? { optOut: true, complaint: false, matched: said } : NONE\n}\n\n/**\n * Whether a reply's text asks to be left alone — see the module note. Pass\n * the reply's text as received; the quoted history is removed here.\n */\nexport function detectOutreachOptOutIntent(text: unknown): OutreachOptOutIntent {\n  const fresh = outreachFreshReplyText(text)\n  if (!fresh) return NONE\n  const folded = fold(fresh)\n  for (const pattern of COMPLAINTS) {\n    const match = pattern.exec(folded)\n    if (match) return { optOut: true, complaint: true, matched: match[0] }\n  }\n  const bare = bareNo(answerOnly(fresh))\n  if (bare) return { optOut: true, complaint: false, matched: bare }\n  for (const pattern of REQUESTS) {\n    const match = pattern.exec(folded)\n    if (match && !NEGATED.test(folded.slice(0, match.index))) {\n      return { optOut: true, complaint: false, matched: match[0] }\n    }\n  }\n  const declined = notInterested(folded)\n  if (declined) return { optOut: true, complaint: false, matched: declined }\n  return NONE\n}\n"],"names":["stripQuotedHistory","NONE","optOut","complaint","matched","FOOTER_LINE","outreachFreshReplyText","text","body","String","replace","lines","split","signature","findIndex","line","test","slice","filter","join","trim","fold","toLowerCase","GREETING_LINE","GREETING_LEAD","SIGN_OFF","NAME","THANKS_THEN_NAME","RegExp","NAME_LINE","answerOnly","fresh","map","Boolean","length","shift","signOff","index","kept","pop","BARE_NO_WORDS","Set","BARE_NO_TRIGGERS","bareNo","answer","words","every","word","has","said","some","NEGATED","REQUESTS","COMPLAINTS","DEFERRAL","notInterested","pattern","match","exec","before","after","sentenceEnd","search","rest","trimEnd","endsWith","detectOutreachOptOutSubject","subject","detectOutreachOptOutIntent","folded","bare","declined"],"mappings":"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"}

package/src/lib/engine/recipient-country.d.ts

@@ -0,0 +1,41 @@
+/**
+ * @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.
+ */
+/** How the country was learned — which of the three sources answered. */
+export type OutreachCountrySource = 'contact' | 'company' | 'domain';
+export interface OutreachRecipientCountry {
+    /** ISO-3166-1 alpha-2, uppercase, or `null` when nothing names one. */
+    country: string | null;
+    source: OutreachCountrySource | null;
+}
+/** The country an address's domain names, or `null` for a generic one. */
+export declare function countryFromEmailDomain(email: unknown): string | null;
+/**
+ * The recipient's country from the best source that names one — see the
+ * module note for the order. `contactAddress` is the address on the sending
+ * group's facet of the contact; `companyAddress` is the one on the company
+ * the contact is filed under.
+ */
+export declare function resolveOutreachRecipientCountry(input: {
+    email: string;
+    contactAddress?: unknown;
+    companyAddress?: unknown;
+}): OutreachRecipientCountry;
+/**
+ * A country's English name as a sentence says it — "the United States",
+ * "Canada" — or the code itself where the runtime has no region names.
+ */
+export declare function outreachCountryName(code: string): string;

package/src/lib/engine/recipient-country.js

@@ -0,0 +1,171 @@
+/**
+ * @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.
+ */ /*==========================================
+ * WHERE A RECIPIENT IS (AGL-2979).
+ *
+ * A cold email's legality turns on the recipient's country: the United
+ * States allows one with an opt-out, while Canada, the United Kingdom and
+ * most of the EU want a consent basis a cold email does not have. The CRM
+ * rarely knows the country for certain, so the gate reads what it has in
+ * order of how much it is worth:
+ *
+ * 1. the country on the contact's own address, as the sending site's facet
+ *    records it;
+ * 2. the country on the company the contact is filed under;
+ * 3. the country an address's domain names — `.ca`, `.co.uk`, `.de` — which
+ *    is evidence against sending rather than for it: a `.de` address is
+ *    almost always in Germany, while a `.com` address says nothing at all.
+ *
+ * Only country-code domains that are used for their country are read.
+ * `.io`, `.co`, `.ai`, `.me` and the rest that are sold as generic names are
+ * not, because reading `.co` as Colombia would refuse half of the startups a
+ * rep writes to for the wrong reason.
+ *==========================================*/ import { normalizeAddress } from "@aglyn/aglyn/foundation/definitions/contact.types";
+/**
+ * Country-code top-level domains read as their country: the ones registries
+ * reserve for, or that are overwhelmingly used by, people and companies in
+ * that country. `.uk` is Great Britain's `GB`.
+ */ const COUNTRY_CODE_DOMAINS = {
+    us: 'US',
+    ca: 'CA',
+    mx: 'MX',
+    br: 'BR',
+    ar: 'AR',
+    cl: 'CL',
+    uk: 'GB',
+    ie: 'IE',
+    de: 'DE',
+    at: 'AT',
+    ch: 'CH',
+    fr: 'FR',
+    be: 'BE',
+    nl: 'NL',
+    lu: 'LU',
+    es: 'ES',
+    pt: 'PT',
+    it: 'IT',
+    gr: 'GR',
+    se: 'SE',
+    no: 'NO',
+    dk: 'DK',
+    fi: 'FI',
+    pl: 'PL',
+    cz: 'CZ',
+    sk: 'SK',
+    hu: 'HU',
+    ro: 'RO',
+    bg: 'BG',
+    hr: 'HR',
+    si: 'SI',
+    ee: 'EE',
+    lt: 'LT',
+    lv: 'LV',
+    mt: 'MT',
+    cy: 'CY',
+    ru: 'RU',
+    ua: 'UA',
+    tr: 'TR',
+    il: 'IL',
+    ae: 'AE',
+    za: 'ZA',
+    in: 'IN',
+    cn: 'CN',
+    jp: 'JP',
+    kr: 'KR',
+    sg: 'SG',
+    hk: 'HK',
+    au: 'AU',
+    nz: 'NZ'
+};
+/** The country an address's domain names, or `null` for a generic one. */ export function countryFromEmailDomain(email) {
+    var _COUNTRY_CODE_DOMAINS_tld;
+    const value = String(email != null ? email : '').trim().toLowerCase();
+    const domain = value.slice(value.lastIndexOf('@') + 1).replace(/\.+$/, '');
+    const tld = domain.slice(domain.lastIndexOf('.') + 1);
+    if (!domain.includes('.') || !tld) return null;
+    return (_COUNTRY_CODE_DOMAINS_tld = COUNTRY_CODE_DOMAINS[tld]) != null ? _COUNTRY_CODE_DOMAINS_tld : null;
+}
+function addressCountry(address) {
+    var _ref;
+    var _normalizeAddress;
+    if (!address || typeof address !== 'object') return null;
+    return (_ref = (_normalizeAddress = normalizeAddress(address)) == null ? void 0 : _normalizeAddress.country) != null ? _ref : null;
+}
+/**
+ * The recipient's country from the best source that names one — see the
+ * module note for the order. `contactAddress` is the address on the sending
+ * group's facet of the contact; `companyAddress` is the one on the company
+ * the contact is filed under.
+ */ export function resolveOutreachRecipientCountry(input) {
+    const fromContact = addressCountry(input.contactAddress);
+    if (fromContact) return {
+        country: fromContact,
+        source: 'contact'
+    };
+    const fromCompany = addressCountry(input.companyAddress);
+    if (fromCompany) return {
+        country: fromCompany,
+        source: 'company'
+    };
+    const fromDomain = countryFromEmailDomain(input.email);
+    if (fromDomain) return {
+        country: fromDomain,
+        source: 'domain'
+    };
+    return {
+        country: null,
+        source: null
+    };
+}
+/** Countries whose English name is read with "the": "the United States". */ const DEFINITE_ARTICLE = new Set([
+    'US',
+    'GB',
+    'NL',
+    'AE',
+    'PH',
+    'DO',
+    'BS',
+    'GM'
+]);
+let regionNames;
+/**
+ * A country's English name as a sentence says it — "the United States",
+ * "Canada" — or the code itself where the runtime has no region names.
+ */ export function outreachCountryName(code) {
+    const upper = String(code != null ? code : '').toUpperCase();
+    if (regionNames === undefined) {
+        try {
+            regionNames = new Intl.DisplayNames([
+                'en'
+            ], {
+                type: 'region'
+            });
+        } catch (unused) {
+            regionNames = null;
+        }
+    }
+    let name;
+    try {
+        var _ref;
+        name = (_ref = regionNames == null ? void 0 : regionNames.of(upper)) != null ? _ref : upper;
+    } catch (unused) {
+        // A code `Intl` rejects outright is printed as it came.
+        name = upper;
+    }
+    return DEFINITE_ARTICLE.has(upper) && name !== upper ? `the ${name}` : name;
+}
+
+//# sourceMappingURL=recipient-country.js.map

package/src/lib/engine/recipient-country.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/outreach/src/lib/engine/recipient-country.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 * WHERE A RECIPIENT IS (AGL-2979).\n *\n * A cold email's legality turns on the recipient's country: the United\n * States allows one with an opt-out, while Canada, the United Kingdom and\n * most of the EU want a consent basis a cold email does not have. The CRM\n * rarely knows the country for certain, so the gate reads what it has in\n * order of how much it is worth:\n *\n * 1. the country on the contact's own address, as the sending site's facet\n *    records it;\n * 2. the country on the company the contact is filed under;\n * 3. the country an address's domain names — `.ca`, `.co.uk`, `.de` — which\n *    is evidence against sending rather than for it: a `.de` address is\n *    almost always in Germany, while a `.com` address says nothing at all.\n *\n * Only country-code domains that are used for their country are read.\n * `.io`, `.co`, `.ai`, `.me` and the rest that are sold as generic names are\n * not, because reading `.co` as Colombia would refuse half of the startups a\n * rep writes to for the wrong reason.\n *==========================================*/\n\nimport {\n  type AglynPostalAddress,\n  normalizeAddress,\n} from '@aglyn/aglyn/foundation/definitions/contact.types'\n\n/** How the country was learned — which of the three sources answered. */\nexport type OutreachCountrySource = 'contact' | 'company' | 'domain'\n\nexport interface OutreachRecipientCountry {\n  /** ISO-3166-1 alpha-2, uppercase, or `null` when nothing names one. */\n  country: string | null\n  source: OutreachCountrySource | null\n}\n\n/**\n * Country-code top-level domains read as their country: the ones registries\n * reserve for, or that are overwhelmingly used by, people and companies in\n * that country. `.uk` is Great Britain's `GB`.\n */\nconst COUNTRY_CODE_DOMAINS: Readonly<Record<string, string>> = {\n  us: 'US',\n  ca: 'CA',\n  mx: 'MX',\n  br: 'BR',\n  ar: 'AR',\n  cl: 'CL',\n  uk: 'GB',\n  ie: 'IE',\n  de: 'DE',\n  at: 'AT',\n  ch: 'CH',\n  fr: 'FR',\n  be: 'BE',\n  nl: 'NL',\n  lu: 'LU',\n  es: 'ES',\n  pt: 'PT',\n  it: 'IT',\n  gr: 'GR',\n  se: 'SE',\n  no: 'NO',\n  dk: 'DK',\n  fi: 'FI',\n  pl: 'PL',\n  cz: 'CZ',\n  sk: 'SK',\n  hu: 'HU',\n  ro: 'RO',\n  bg: 'BG',\n  hr: 'HR',\n  si: 'SI',\n  ee: 'EE',\n  lt: 'LT',\n  lv: 'LV',\n  mt: 'MT',\n  cy: 'CY',\n  ru: 'RU',\n  ua: 'UA',\n  tr: 'TR',\n  il: 'IL',\n  ae: 'AE',\n  za: 'ZA',\n  in: 'IN',\n  cn: 'CN',\n  jp: 'JP',\n  kr: 'KR',\n  sg: 'SG',\n  hk: 'HK',\n  au: 'AU',\n  nz: 'NZ',\n}\n\n/** The country an address's domain names, or `null` for a generic one. */\nexport function countryFromEmailDomain(email: unknown): string | null {\n  const value = String(email ?? '').trim().toLowerCase()\n  const domain = value.slice(value.lastIndexOf('@') + 1).replace(/\\.+$/, '')\n  const tld = domain.slice(domain.lastIndexOf('.') + 1)\n  if (!domain.includes('.') || !tld) return null\n  return COUNTRY_CODE_DOMAINS[tld] ?? null\n}\n\nfunction addressCountry(address: unknown): string | null {\n  if (!address || typeof address !== 'object') return null\n  return normalizeAddress(address as AglynPostalAddress)?.country ?? null\n}\n\n/**\n * The recipient's country from the best source that names one — see the\n * module note for the order. `contactAddress` is the address on the sending\n * group's facet of the contact; `companyAddress` is the one on the company\n * the contact is filed under.\n */\nexport function resolveOutreachRecipientCountry(input: {\n  email: string\n  contactAddress?: unknown\n  companyAddress?: unknown\n}): OutreachRecipientCountry {\n  const fromContact = addressCountry(input.contactAddress)\n  if (fromContact) return { country: fromContact, source: 'contact' }\n  const fromCompany = addressCountry(input.companyAddress)\n  if (fromCompany) return { country: fromCompany, source: 'company' }\n  const fromDomain = countryFromEmailDomain(input.email)\n  if (fromDomain) return { country: fromDomain, source: 'domain' }\n  return { country: null, source: null }\n}\n\n/** Countries whose English name is read with \"the\": \"the United States\". */\nconst DEFINITE_ARTICLE = new Set(['US', 'GB', 'NL', 'AE', 'PH', 'DO', 'BS', 'GM'])\n\nlet regionNames: Intl.DisplayNames | null | undefined\n\n/**\n * A country's English name as a sentence says it — \"the United States\",\n * \"Canada\" — or the code itself where the runtime has no region names.\n */\nexport function outreachCountryName(code: string): string {\n  const upper = String(code ?? '').toUpperCase()\n  if (regionNames === undefined) {\n    try {\n      regionNames = new Intl.DisplayNames(['en'], { type: 'region' })\n    } catch {\n      regionNames = null\n    }\n  }\n  let name: string\n  try {\n    name = regionNames?.of(upper) ?? upper\n  } catch {\n    // A code `Intl` rejects outright is printed as it came.\n    name = upper\n  }\n  return DEFINITE_ARTICLE.has(upper) && name !== upper ? `the ${name}` : name\n}\n"],"names":["normalizeAddress","COUNTRY_CODE_DOMAINS","us","ca","mx","br","ar","cl","uk","ie","de","at","ch","fr","be","nl","lu","es","pt","it","gr","se","no","dk","fi","pl","cz","sk","hu","ro","bg","hr","si","ee","lt","lv","mt","cy","ru","ua","tr","il","ae","za","in","cn","jp","kr","sg","hk","au","nz","countryFromEmailDomain","email","value","String","trim","toLowerCase","domain","slice","lastIndexOf","replace","tld","includes","addressCountry","address","country","resolveOutreachRecipientCountry","input","fromContact","contactAddress","source","fromCompany","companyAddress","fromDomain","DEFINITE_ARTICLE","Set","regionNames","outreachCountryName","code","upper","toUpperCase","undefined","Intl","DisplayNames","type","name","of","has"],"mappings":"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"}

package/src/lib/engine/schedule.d.ts

@@ -0,0 +1,70 @@
+/**
+ * @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 WeeklySchedule } from '@aglyn/shared-util-timestamp/zoned-time';
+import type { OutreachSendWindow } from '../model/outreach.types';
+/** How far a due time may move, in total: half of it either way. */
+export declare const OUTREACH_DUE_JITTER_MINUTES = 60;
+/**
+ * How long an out-of-office reply holds the next step back, in business
+ * days — a working week, the usual length of an absence — measured from
+ * when the reply arrived. A step already due later than that keeps its time.
+ */
+export declare const OUTREACH_AUTO_REPLY_POSTPONE_BUSINESS_DAYS = 5;
+/** A source of numbers in `[0, 1)`, such as `Math.random`. */
+export type OutreachRandom = () => number;
+/** A send window as the weekly schedule the zone math reads. */
+export declare function outreachWindowSchedule(window: OutreachSendWindow | null | undefined): WeeklySchedule;
+/** The window a sequence's steps go out in: its own, or else its mailbox's. */
+export declare function effectiveOutreachWindow(sequenceWindow: OutreachSendWindow | null | undefined, mailboxWindow: OutreachSendWindow | null | undefined): OutreachSendWindow | null;
+/** Whether `atMs` is inside the window, read in `timeZone`. */
+export declare function isOutreachWindowOpen(atMs: number, window: OutreachSendWindow | null | undefined, timeZone: string): boolean;
+export interface OutreachDueInput {
+    /** The instant the wait is counted from: the last step's send, or the enrollment. */
+    fromMs: number;
+    delayBusinessDays: number;
+    /** The mailbox's IANA zone. */
+    timeZone: string;
+    /** The window the step goes out in — {@link effectiveOutreachWindow}. */
+    window: OutreachSendWindow | null | undefined;
+    random: OutreachRandom;
+    /** Defaults to {@link OUTREACH_DUE_JITTER_MINUTES}; `0` places the time exactly. */
+    jitterMinutes?: number;
+}
+/**
+ * When a step comes due — see the module note — or `null` when it never
+ * can: a zone `Intl` does not know, a delay that is not a whole number of
+ * days, or a window that never opens.
+ */
+export declare function scheduleOutreachDue(input: OutreachDueInput): number | null;
+export interface OutreachAutoReplyPostponeInput {
+    /** The enrollment's `nextDueAtMs`; `null` has nothing waiting to hold back. */
+    nextDueAtMs: number | null;
+    /** When the automatic reply arrived. */
+    receivedAtMs: number;
+    timeZone: string;
+    window: OutreachSendWindow | null | undefined;
+    random: OutreachRandom;
+    businessDays?: number;
+}
+/**
+ * The due time after an out-of-office reply: at least
+ * {@link OUTREACH_AUTO_REPLY_POSTPONE_BUSINESS_DAYS} business days after the
+ * reply, never earlier than the step was already due. An automatic reply
+ * says the person is away, not that they answered, so the enrollment waits
+ * and does not stop.
+ */
+export declare function postponeOutreachForAutoReply(input: OutreachAutoReplyPostponeInput): number | null;