@aglyn/plugins-outreach 1.0.0-beta.143

package/src/lib/engine/enrollment-state.js

@@ -0,0 +1,303 @@
+import { _ as _extends } from "@swc/helpers/_/_extends";
+/**
+ * @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 PERSON'S RUN THROUGH A SEQUENCE (AGL-2979).
+ *
+ * ## The state machine
+ *
+ *   active ──► paused ──► active
+ *     │          │
+ *     ├──────────┴──► replied · bounced · opted_out · stopped
+ *     └─► finished · failed
+ *
+ * An enrollment sends only while `active`. Everything that ends the sending
+ * records why (`stopReason`, `stopDetail`, when, and who). Ending the
+ * sending does not end what can still be learned from the thread: a reply,
+ * a bounce or an opt-out that arrives after the last step, after a member
+ * stopped it or after a send failed is still recorded, and a person who
+ * replied and then asked to be left alone moves on to `opted_out` — an
+ * opt-out is the one fact every later sequence has to be able to find.
+ * `bounced` and `opted_out` are final.
+ *
+ * Every function returns a PATCH — the fields to write — and never the
+ * whole document, so a writer applies it with its own SDK and its own
+ * timestamps.
+ *==========================================*/ import { OUTREACH_ATTESTATION_KINDS, OUTREACH_STOP_REASONS_BY_STATUS } from "../model/outreach.types.js";
+import { normalizeOutreachPersonalLine } from "./gates.js";
+import { effectiveOutreachWindow, scheduleOutreachDue } from "./schedule.js";
+import { isInThreadEmailStep } from "./sequence-validation.js";
+/** Where each status may go next. */ export const OUTREACH_ENROLLMENT_TRANSITIONS = {
+    active: [
+        'paused',
+        'finished',
+        'replied',
+        'bounced',
+        'opted_out',
+        'stopped',
+        'failed'
+    ],
+    paused: [
+        'active',
+        'replied',
+        'bounced',
+        'opted_out',
+        'stopped'
+    ],
+    finished: [
+        'replied',
+        'bounced',
+        'opted_out'
+    ],
+    stopped: [
+        'replied',
+        'bounced',
+        'opted_out'
+    ],
+    failed: [
+        'replied',
+        'bounced',
+        'opted_out'
+    ],
+    replied: [
+        'opted_out'
+    ],
+    bounced: [],
+    opted_out: []
+};
+export function canTransitionOutreachEnrollment(from, to) {
+    var _OUTREACH_ENROLLMENT_TRANSITIONS_from;
+    return ((_OUTREACH_ENROLLMENT_TRANSITIONS_from = OUTREACH_ENROLLMENT_TRANSITIONS[from]) == null ? void 0 : _OUTREACH_ENROLLMENT_TRANSITIONS_from.includes(to)) === true;
+}
+const STATUS_WORDS = {
+    active: 'is active',
+    paused: 'is paused',
+    finished: 'finished',
+    replied: 'got a reply',
+    bounced: 'bounced',
+    opted_out: 'opted out',
+    stopped: 'was stopped',
+    failed: 'failed'
+};
+const EVENT_TARGET = {
+    pause: 'paused',
+    resume: 'active',
+    stop: 'stopped',
+    reply: 'replied',
+    opt_out: 'opted_out',
+    bounce: 'bounced',
+    send_failed: 'failed'
+};
+const detailOf = (value)=>{
+    const text = typeof value === 'string' ? value.replace(/\s+/g, ' ').trim() : '';
+    return text ? text.slice(0, 500) : null;
+};
+/** What an event does to an enrollment's status — see the module note. */ export function applyOutreachEnrollmentEvent(enrollment, event) {
+    var _event_reason;
+    const from = enrollment.status;
+    const to = EVENT_TARGET[event.type];
+    if (!to) return {
+        patch: null,
+        error: 'That is not something that happens to an enrollment.'
+    };
+    if (from === to) return {
+        patch: null,
+        error: null
+    };
+    if (!canTransitionOutreachEnrollment(from, to)) {
+        return {
+            patch: null,
+            error: `This enrollment ${STATUS_WORDS[from]}, so it can't be marked as one that ${STATUS_WORDS[to]}.`
+        };
+    }
+    if (event.type === 'resume') {
+        return {
+            patch: {
+                status: 'active',
+                stopReason: null,
+                stopDetail: null,
+                stoppedAtMs: null,
+                stoppedByUid: null,
+                nextDueAtMs: enrollment.nextDueAtMs
+            },
+            error: null
+        };
+    }
+    const reason = event.type === 'pause' ? 'manual' : event.type === 'stop' ? (_event_reason = event.reason) != null ? _event_reason : 'manual' : event.type === 'reply' ? 'reply' : event.type === 'opt_out' ? event.reason : event.type === 'bounce' ? 'hard_bounce' : 'send_failed';
+    const allowed = OUTREACH_STOP_REASONS_BY_STATUS[to];
+    if (!(allowed == null ? void 0 : allowed.includes(reason))) {
+        return {
+            patch: null,
+            error: `"${reason}" isn't a reason an enrollment ${STATUS_WORDS[to]}.`
+        };
+    }
+    const byUid = 'byUid' in event && typeof event.byUid === 'string' && event.byUid ? event.byUid : null;
+    return {
+        patch: {
+            status: to,
+            stopReason: reason,
+            stopDetail: detailOf(event.detail),
+            stoppedAtMs: event.atMs,
+            stoppedByUid: byUid,
+            // A paused enrollment keeps its place, so resuming it picks up where it
+            // stopped; every other status has nothing left waiting.
+            nextDueAtMs: to === 'paused' ? enrollment.nextDueAtMs : null
+        },
+        error: null
+    };
+}
+/** When a new enrollment's first step comes due, or `null` when it cannot be placed. */ export function planOutreachFirstDue(input) {
+    var _input_sequence_steps, _input_sequence_settings;
+    const first = (_input_sequence_steps = input.sequence.steps) == null ? void 0 : _input_sequence_steps[0];
+    if (!first) return null;
+    return scheduleOutreachDue({
+        fromMs: input.enrolledAtMs,
+        delayBusinessDays: first.delayBusinessDays,
+        timeZone: input.mailbox.timezone,
+        window: effectiveOutreachWindow((_input_sequence_settings = input.sequence.settings) == null ? void 0 : _input_sequence_settings.window, input.mailbox.window),
+        random: input.random
+    });
+}
+/** Stamps the attestations a rep ticked with who ticked them and when; unknown kinds are dropped. */ export function outreachAttestationsFrom(kinds, uid, atMs) {
+    const attestations = {};
+    for (const kind of kinds != null ? kinds : []){
+        if (OUTREACH_ATTESTATION_KINDS.includes(kind)) {
+            attestations[kind] = {
+                uid,
+                atMs
+            };
+        }
+    }
+    return attestations;
+}
+/**
+ * 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 function buildOutreachEnrollment(draft) {
+    var _draft_contactName, _draft_email, _draft_attestations;
+    return {
+        id: draft.id,
+        sequenceId: draft.sequence.id,
+        contactId: draft.contactId,
+        contactName: String((_draft_contactName = draft.contactName) != null ? _draft_contactName : '').replace(/\s+/g, ' ').trim().slice(0, 200),
+        email: String((_draft_email = draft.email) != null ? _draft_email : '').trim().toLowerCase(),
+        hostId: draft.sequence.hostId,
+        mailboxId: draft.sequence.mailboxId,
+        stepIndex: 0,
+        nextDueAtMs: planOutreachFirstDue({
+            sequence: draft.sequence,
+            mailbox: draft.mailbox,
+            enrolledAtMs: draft.nowMs,
+            random: draft.random
+        }),
+        status: 'active',
+        stopReason: null,
+        stopDetail: null,
+        stoppedAtMs: null,
+        stoppedByUid: null,
+        personalLine: normalizeOutreachPersonalLine(draft.personalLine),
+        cold: draft.cold === true,
+        attestations: _extends({}, (_draft_attestations = draft.attestations) != null ? _draft_attestations : {}),
+        enrolledByUid: draft.enrolledByUid,
+        gmailThreadId: null,
+        gmailThreadIds: [],
+        threadSubject: null,
+        messageIds: [],
+        lastSentAtMs: null,
+        createdAtMs: draft.nowMs,
+        updatedAtMs: draft.nowMs
+    };
+}
+/**
+ * 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 function planOutreachStepCompletion(input) {
+    var _sequence_steps;
+    var _sequence_settings;
+    const { enrollment, sequence } = input;
+    if (enrollment.status !== 'active') {
+        return {
+            patch: null,
+            error: 'Only an active enrollment runs its steps.'
+        };
+    }
+    const steps = (_sequence_steps = sequence.steps) != null ? _sequence_steps : [];
+    const step = steps[enrollment.stepIndex];
+    if (!step) return {
+        patch: null,
+        error: 'This enrollment has no step at its position.'
+    };
+    const patch = {
+        status: 'active',
+        stepIndex: enrollment.stepIndex + 1,
+        nextDueAtMs: null,
+        lastSentAtMs: input.completedAtMs
+    };
+    if (step.kind === 'email') {
+        var _ref, _ref1, _enrollment_gmailThreadIds;
+        const sent = input.sent;
+        const messageId = String((_ref = sent == null ? void 0 : sent.messageId) != null ? _ref : '').trim();
+        const threadId = String((_ref1 = sent == null ? void 0 : sent.threadId) != null ? _ref1 : '').trim();
+        if (!messageId || !threadId) {
+            return {
+                patch: null,
+                error: 'An email step needs the sent message and thread ids.'
+            };
+        }
+        const threadIds = [
+            ...(_enrollment_gmailThreadIds = enrollment.gmailThreadIds) != null ? _enrollment_gmailThreadIds : []
+        ];
+        if (!threadIds.includes(threadId)) threadIds.push(threadId);
+        patch.gmailThreadId = threadId;
+        patch.gmailThreadIds = threadIds;
+        if (isInThreadEmailStep(steps, enrollment.stepIndex) && enrollment.threadSubject) {
+            var _enrollment_messageIds;
+            patch.messageIds = [
+                ...(_enrollment_messageIds = enrollment.messageIds) != null ? _enrollment_messageIds : [],
+                messageId
+            ];
+        } else {
+            var _sent_subject;
+            patch.threadSubject = String((_sent_subject = sent.subject) != null ? _sent_subject : '').trim();
+            patch.messageIds = [
+                messageId
+            ];
+        }
+    }
+    const next = steps[patch.stepIndex];
+    if (!next) {
+        patch.status = 'finished';
+        return {
+            patch,
+            error: null
+        };
+    }
+    patch.nextDueAtMs = scheduleOutreachDue({
+        fromMs: input.completedAtMs,
+        delayBusinessDays: next.delayBusinessDays,
+        timeZone: input.mailbox.timezone,
+        window: effectiveOutreachWindow((_sequence_settings = sequence.settings) == null ? void 0 : _sequence_settings.window, input.mailbox.window),
+        random: input.random
+    });
+    return {
+        patch,
+        error: patch.nextDueAtMs === null ? "The next step couldn't be scheduled: check the sending window and the mailbox's timezone." : null
+    };
+}
+
+//# sourceMappingURL=enrollment-state.js.map

package/src/lib/engine/enrollment-state.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/outreach/src/lib/engine/enrollment-state.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n/*==========================================\n * ONE PERSON'S RUN THROUGH A SEQUENCE (AGL-2979).\n *\n * ## The state machine\n *\n *   active ──► paused ──► active\n *     │          │\n *     ├──────────┴──► replied · bounced · opted_out · stopped\n *     └─► finished · failed\n *\n * An enrollment sends only while `active`. Everything that ends the sending\n * records why (`stopReason`, `stopDetail`, when, and who). Ending the\n * sending does not end what can still be learned from the thread: a reply,\n * a bounce or an opt-out that arrives after the last step, after a member\n * stopped it or after a send failed is still recorded, and a person who\n * replied and then asked to be left alone moves on to `opted_out` — an\n * opt-out is the one fact every later sequence has to be able to find.\n * `bounced` and `opted_out` are final.\n *\n * Every function returns a PATCH — the fields to write — and never the\n * whole document, so a writer applies it with its own SDK and its own\n * timestamps.\n *==========================================*/\n\nimport {\n  OUTREACH_ATTESTATION_KINDS,\n  OUTREACH_STOP_REASONS_BY_STATUS,\n  type OutreachAttestationKind,\n  type OutreachAttestations,\n  type OutreachEnrollment,\n  type OutreachEnrollmentStatus,\n  type OutreachMailbox,\n  type OutreachSequence,\n  type OutreachStopReason,\n} from '../model/outreach.types'\nimport { normalizeOutreachPersonalLine } from './gates'\nimport { effectiveOutreachWindow, type OutreachRandom, scheduleOutreachDue } from './schedule'\nimport { isInThreadEmailStep } from './sequence-validation'\n\n/** Where each status may go next. */\nexport const OUTREACH_ENROLLMENT_TRANSITIONS: Readonly<\n  Record<OutreachEnrollmentStatus, readonly OutreachEnrollmentStatus[]>\n> = {\n  active: ['paused', 'finished', 'replied', 'bounced', 'opted_out', 'stopped', 'failed'],\n  paused: ['active', 'replied', 'bounced', 'opted_out', 'stopped'],\n  finished: ['replied', 'bounced', 'opted_out'],\n  stopped: ['replied', 'bounced', 'opted_out'],\n  failed: ['replied', 'bounced', 'opted_out'],\n  replied: ['opted_out'],\n  bounced: [],\n  opted_out: [],\n}\n\nexport function canTransitionOutreachEnrollment(\n  from: OutreachEnrollmentStatus,\n  to: OutreachEnrollmentStatus,\n): boolean {\n  return OUTREACH_ENROLLMENT_TRANSITIONS[from]?.includes(to) === true\n}\n\n/** Something that happened to an enrollment. `atMs` is when it happened. */\nexport type OutreachEnrollmentEvent =\n  | { type: 'pause'; atMs: number; byUid: string | null; detail?: string | null }\n  | { type: 'resume'; atMs: number; byUid: string | null }\n  | {\n      type: 'stop'\n      atMs: number\n      byUid: string | null\n      reason?: Extract<OutreachStopReason, 'manual' | 'gate' | 'sequence_archived'>\n      detail?: string | null\n    }\n  | { type: 'reply'; atMs: number; detail?: string | null }\n  | {\n      type: 'opt_out'\n      atMs: number\n      reason: Extract<OutreachStopReason, 'opt_out_reply' | 'unsubscribe' | 'do_not_contact'>\n      detail?: string | null\n    }\n  | { type: 'bounce'; atMs: number; detail?: string | null }\n  | { type: 'send_failed'; atMs: number; detail?: string | null }\n\n/** The status fields an event writes. */\nexport interface OutreachEnrollmentStatusPatch {\n  status: OutreachEnrollmentStatus\n  stopReason: OutreachStopReason | null\n  stopDetail: string | null\n  stoppedAtMs: number | null\n  stoppedByUid: string | null\n  nextDueAtMs: number | null\n}\n\n/**\n * `patch` is what to write, or `null` when there is nothing to write — the\n * enrollment is already there, or the event is not allowed, in which case\n * `error` says why.\n */\nexport interface OutreachEnrollmentEventResult {\n  patch: OutreachEnrollmentStatusPatch | null\n  error: string | null\n}\n\nconst STATUS_WORDS: Record<OutreachEnrollmentStatus, string> = {\n  active: 'is active',\n  paused: 'is paused',\n  finished: 'finished',\n  replied: 'got a reply',\n  bounced: 'bounced',\n  opted_out: 'opted out',\n  stopped: 'was stopped',\n  failed: 'failed',\n}\n\nconst EVENT_TARGET: Record<OutreachEnrollmentEvent['type'], OutreachEnrollmentStatus> = {\n  pause: 'paused',\n  resume: 'active',\n  stop: 'stopped',\n  reply: 'replied',\n  opt_out: 'opted_out',\n  bounce: 'bounced',\n  send_failed: 'failed',\n}\n\nconst detailOf = (value: unknown): string | null => {\n  const text = typeof value === 'string' ? value.replace(/\\s+/g, ' ').trim() : ''\n  return text ? text.slice(0, 500) : null\n}\n\n/** What an event does to an enrollment's status — see the module note. */\nexport function applyOutreachEnrollmentEvent(\n  enrollment: Pick<OutreachEnrollment, 'status' | 'nextDueAtMs'>,\n  event: OutreachEnrollmentEvent,\n): OutreachEnrollmentEventResult {\n  const from = enrollment.status\n  const to = EVENT_TARGET[event.type]\n  if (!to) return { patch: null, error: 'That is not something that happens to an enrollment.' }\n  if (from === to) return { patch: null, error: null }\n  if (!canTransitionOutreachEnrollment(from, to)) {\n    return {\n      patch: null,\n      error: `This enrollment ${STATUS_WORDS[from]}, so it can't be marked as one that ${STATUS_WORDS[to]}.`,\n    }\n  }\n  if (event.type === 'resume') {\n    return {\n      patch: {\n        status: 'active',\n        stopReason: null,\n        stopDetail: null,\n        stoppedAtMs: null,\n        stoppedByUid: null,\n        nextDueAtMs: enrollment.nextDueAtMs,\n      },\n      error: null,\n    }\n  }\n  const reason: OutreachStopReason =\n    event.type === 'pause'\n      ? 'manual'\n      : event.type === 'stop'\n        ? (event.reason ?? 'manual')\n        : event.type === 'reply'\n          ? 'reply'\n          : event.type === 'opt_out'\n            ? event.reason\n            : event.type === 'bounce'\n              ? 'hard_bounce'\n              : 'send_failed'\n  const allowed = OUTREACH_STOP_REASONS_BY_STATUS[to as keyof typeof OUTREACH_STOP_REASONS_BY_STATUS]\n  if (!allowed?.includes(reason)) {\n    return { patch: null, error: `\"${reason}\" isn't a reason an enrollment ${STATUS_WORDS[to]}.` }\n  }\n  const byUid = 'byUid' in event && typeof event.byUid === 'string' && event.byUid ? event.byUid : null\n  return {\n    patch: {\n      status: to,\n      stopReason: reason,\n      stopDetail: detailOf(event.detail),\n      stoppedAtMs: event.atMs,\n      stoppedByUid: byUid,\n      // A paused enrollment keeps its place, so resuming it picks up where it\n      // stopped; every other status has nothing left waiting.\n      nextDueAtMs: to === 'paused' ? enrollment.nextDueAtMs : null,\n    },\n    error: null,\n  }\n}\n\ntype ScheduleMailbox = Pick<OutreachMailbox, 'timezone' | 'window'>\ntype ScheduleSequence = Pick<OutreachSequence, 'steps' | 'settings'>\n\n/** When a new enrollment's first step comes due, or `null` when it cannot be placed. */\nexport function planOutreachFirstDue(input: {\n  sequence: ScheduleSequence\n  mailbox: ScheduleMailbox\n  enrolledAtMs: number\n  random: OutreachRandom\n}): number | null {\n  const first = input.sequence.steps?.[0]\n  if (!first) return null\n  return scheduleOutreachDue({\n    fromMs: input.enrolledAtMs,\n    delayBusinessDays: first.delayBusinessDays,\n    timeZone: input.mailbox.timezone,\n    window: effectiveOutreachWindow(input.sequence.settings?.window, input.mailbox.window),\n    random: input.random,\n  })\n}\n\n/** Stamps the attestations a rep ticked with who ticked them and when; unknown kinds are dropped. */\nexport function outreachAttestationsFrom(\n  kinds: readonly unknown[],\n  uid: string,\n  atMs: number,\n): OutreachAttestations {\n  const attestations: OutreachAttestations = {}\n  for (const kind of kinds ?? []) {\n    if ((OUTREACH_ATTESTATION_KINDS as readonly unknown[]).includes(kind)) {\n      attestations[kind as OutreachAttestationKind] = { uid, atMs }\n    }\n  }\n  return attestations\n}\n\nexport interface OutreachEnrollmentDraft {\n  id: string\n  sequence: Pick<OutreachSequence, 'id' | 'hostId' | 'mailboxId' | 'steps' | 'settings'>\n  mailbox: ScheduleMailbox\n  contactId: string\n  /** The contact's name as the sending site knows it; `''` for none. */\n  contactName?: string | null\n  /** The address, as the gates normalized it. */\n  email: string\n  /** The gates' `cold`. */\n  cold: boolean\n  personalLine: string\n  attestations: OutreachAttestations\n  enrolledByUid: string\n  nowMs: number\n  random: OutreachRandom\n}\n\n/**\n * A new enrollment document, first step scheduled — one builder for every\n * door that enrolls, so an enrollment made from a contact and one made from\n * a list are the same shape. Call it after the gates allowed the person.\n */\nexport function buildOutreachEnrollment(draft: OutreachEnrollmentDraft): OutreachEnrollment {\n  return {\n    id: draft.id,\n    sequenceId: draft.sequence.id,\n    contactId: draft.contactId,\n    contactName: String(draft.contactName ?? '').replace(/\\s+/g, ' ').trim().slice(0, 200),\n    email: String(draft.email ?? '').trim().toLowerCase(),\n    hostId: draft.sequence.hostId,\n    mailboxId: draft.sequence.mailboxId,\n    stepIndex: 0,\n    nextDueAtMs: planOutreachFirstDue({\n      sequence: draft.sequence,\n      mailbox: draft.mailbox,\n      enrolledAtMs: draft.nowMs,\n      random: draft.random,\n    }),\n    status: 'active',\n    stopReason: null,\n    stopDetail: null,\n    stoppedAtMs: null,\n    stoppedByUid: null,\n    personalLine: normalizeOutreachPersonalLine(draft.personalLine),\n    cold: draft.cold === true,\n    attestations: { ...(draft.attestations ?? {}) },\n    enrolledByUid: draft.enrolledByUid,\n    gmailThreadId: null,\n    gmailThreadIds: [],\n    threadSubject: null,\n    messageIds: [],\n    lastSentAtMs: null,\n    createdAtMs: draft.nowMs,\n    updatedAtMs: draft.nowMs,\n  }\n}\n\n/** What the provider reported for an email step that was sent. */\nexport interface OutreachSentEmail {\n  /** The `Message-ID` header the message went out with, angle brackets included. */\n  messageId: string\n  /** The provider's thread id. */\n  threadId: string\n  /** The subject as sent. */\n  subject: string\n}\n\nexport interface OutreachStepCompletionInput {\n  enrollment: Pick<\n    OutreachEnrollment,\n    'status' | 'stepIndex' | 'gmailThreadId' | 'gmailThreadIds' | 'messageIds' | 'threadSubject'\n  >\n  sequence: ScheduleSequence\n  mailbox: ScheduleMailbox\n  /** When the step ran. */\n  completedAtMs: number\n  /** For an email step, what was sent; not read for a task. */\n  sent?: OutreachSentEmail | null\n  random: OutreachRandom\n}\n\n/** The fields a completed step writes. */\nexport interface OutreachStepCompletionPatch {\n  status: 'active' | 'finished'\n  stepIndex: number\n  nextDueAtMs: number | null\n  lastSentAtMs: number\n  gmailThreadId?: string\n  gmailThreadIds?: string[]\n  threadSubject?: string\n  messageIds?: string[]\n}\n\nexport interface OutreachStepCompletionResult {\n  patch: OutreachStepCompletionPatch | null\n  /**\n   * Why there is no patch, or — beside one — that the next step could not\n   * be placed on the calendar (a window that never opens, a zone `Intl` does\n   * not know), which leaves the enrollment with nothing due until a member\n   * fixes the window and resumes it.\n   */\n  error: string | null\n}\n\n/**\n * What running the current step writes: the send recorded on the thread\n * fields, and the next step scheduled — or the enrollment `finished` when\n * that was the last.\n */\nexport function planOutreachStepCompletion(\n  input: OutreachStepCompletionInput,\n): OutreachStepCompletionResult {\n  const { enrollment, sequence } = input\n  if (enrollment.status !== 'active') {\n    return { patch: null, error: 'Only an active enrollment runs its steps.' }\n  }\n  const steps = sequence.steps ?? []\n  const step = steps[enrollment.stepIndex]\n  if (!step) return { patch: null, error: 'This enrollment has no step at its position.' }\n  const patch: OutreachStepCompletionPatch = {\n    status: 'active',\n    stepIndex: enrollment.stepIndex + 1,\n    nextDueAtMs: null,\n    lastSentAtMs: input.completedAtMs,\n  }\n  if (step.kind === 'email') {\n    const sent = input.sent\n    const messageId = String(sent?.messageId ?? '').trim()\n    const threadId = String(sent?.threadId ?? '').trim()\n    if (!messageId || !threadId) {\n      return { patch: null, error: 'An email step needs the sent message and thread ids.' }\n    }\n    const threadIds = [...(enrollment.gmailThreadIds ?? [])]\n    if (!threadIds.includes(threadId)) threadIds.push(threadId)\n    patch.gmailThreadId = threadId\n    patch.gmailThreadIds = threadIds\n    if (isInThreadEmailStep(steps, enrollment.stepIndex) && enrollment.threadSubject) {\n      patch.messageIds = [...(enrollment.messageIds ?? []), messageId]\n    } else {\n      patch.threadSubject = String(sent.subject ?? '').trim()\n      patch.messageIds = [messageId]\n    }\n  }\n  const next = steps[patch.stepIndex]\n  if (!next) {\n    patch.status = 'finished'\n    return { patch, error: null }\n  }\n  patch.nextDueAtMs = scheduleOutreachDue({\n    fromMs: input.completedAtMs,\n    delayBusinessDays: next.delayBusinessDays,\n    timeZone: input.mailbox.timezone,\n    window: effectiveOutreachWindow(sequence.settings?.window, input.mailbox.window),\n    random: input.random,\n  })\n  return {\n    patch,\n    error:\n      patch.nextDueAtMs === null\n        ? \"The next step couldn't be scheduled: check the sending window and the mailbox's timezone.\"\n        : null,\n  }\n}\n"],"names":["OUTREACH_ATTESTATION_KINDS","OUTREACH_STOP_REASONS_BY_STATUS","normalizeOutreachPersonalLine","effectiveOutreachWindow","scheduleOutreachDue","isInThreadEmailStep","OUTREACH_ENROLLMENT_TRANSITIONS","active","paused","finished","stopped","failed","replied","bounced","opted_out","canTransitionOutreachEnrollment","from","to","includes","STATUS_WORDS","EVENT_TARGET","pause","resume","stop","reply","opt_out","bounce","send_failed","detailOf","value","text","replace","trim","slice","applyOutreachEnrollmentEvent","enrollment","event","status","type","patch","error","stopReason","stopDetail","stoppedAtMs","stoppedByUid","nextDueAtMs","reason","allowed","byUid","detail","atMs","planOutreachFirstDue","input","first","sequence","steps","fromMs","enrolledAtMs","delayBusinessDays","timeZone","mailbox","timezone","window","settings","random","outreachAttestationsFrom","kinds","uid","attestations","kind","buildOutreachEnrollment","draft","id","sequenceId","contactId","contactName","String","email","toLowerCase","hostId","mailboxId","stepIndex","nowMs","personalLine","cold","enrolledByUid","gmailThreadId","gmailThreadIds","threadSubject","messageIds","lastSentAtMs","createdAtMs","updatedAtMs","planOutreachStepCompletion","step","completedAtMs","sent","messageId","threadId","threadIds","push","subject","next"],"mappings":"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"}

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

@@ -0,0 +1,125 @@
+/**
+ * @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 ContactSource } from '@aglyn/aglyn/app-utils/contacts';
+import type { TopicSubscriptionState } from '@aglyn/aglyn/app-utils/email-topics';
+import { type MemberAddresses } from '@aglyn/aglyn/app-utils/member-email-aliases';
+import { type OutreachAttestationKind, type OutreachAttestations, type OutreachEnrollmentStatus, type OutreachSequenceSettings } from '../model/outreach.types';
+import { type OutreachRecipientCountry } from './recipient-country';
+/**
+ * The capture doors that mean a person came to the business: a form, a
+ * sign-up to the site or its newsletter, an order, a booking. `api`,
+ * `import` and `manual` are how a business adds people it found, which is
+ * exactly what cold means.
+ */
+export declare const OUTREACH_INBOUND_CONTACT_SOURCES: readonly ContactSource[];
+/** The enrollment statuses that hold a person: one sequence at a time. */
+export declare const OUTREACH_OPEN_ENROLLMENT_STATUSES: readonly OutreachEnrollmentStatus[];
+/**
+ * What the runtime looked up about the address before asking. Every field is
+ * `null` when its read failed, and a `null` refuses.
+ */
+export interface OutreachGateLookups {
+    /**
+     * `emailSuppressions/{key}` holds a record in force — a hard bounce or a
+     * spam complaint anywhere on the platform (`isEmailSuppressed`).
+     */
+    platformSuppressed: boolean | null;
+    /** `hosts/{hostId}/suppressions/{key}` exists for the sequence's site. */
+    hostSuppressed: boolean | null;
+    /**
+     * The address's standing on the site's `sales` topic —
+     * `readTopicSubscriptionState` of the `sales` entry in
+     * `hosts/{hostId}/topicOptOuts/{key}`. Only `opted-out` refuses: a pending
+     * confirmation is about a subscription, and a sales email does not rest on
+     * one.
+     */
+    salesTopicState: TopicSubscriptionState | null;
+    /** The address is on the organization's Outreach do-not-contact list. */
+    doNotContact: boolean | null;
+    /**
+     * The organization's roster: each member's sign-in address and confirmed
+     * aliases, as `crmInboundRoster` builds it.
+     */
+    workspaceMembers: readonly MemberAddresses[] | null;
+    /**
+     * The person's enrollments that are `active` or `paused`, found by contact
+     * id or by address. Other statuses are ignored, so passing every
+     * enrollment is safe too.
+     */
+    openEnrollments: ReadonlyArray<{
+        id: string;
+        sequenceId: string;
+        status: OutreachEnrollmentStatus;
+    }> | null;
+    /**
+     * An email the person wrote (`direction: 'inbound'`) is filed on the
+     * contact. `null` reads as `false`, which only makes the contact cold and
+     * the rules stricter.
+     */
+    hasInboundEmail: boolean | null;
+}
+export interface OutreachGateInput {
+    /** The address the steps go to. */
+    email: string;
+    /** The contact document as stored (`orgs/{orgId}/contacts/{id}`), or `null` when it is gone. */
+    contact: Record<string, unknown> | null | undefined;
+    /** The consent group of the sequence's site: whose facet holds stage, sources and address. */
+    contactGroupId: string;
+    /** The company document the contact is filed under, when there is one. */
+    company?: Record<string, unknown> | null;
+    /** The sequence's settings as stored; a missing field reads as its default. */
+    settings: Partial<OutreachSequenceSettings> | null | undefined;
+    /** The rep's signal sentence. */
+    personalLine: string | null | undefined;
+    attestations: OutreachAttestations | null | undefined;
+    /** The enrollment being re-checked before a send, so it does not count as another. */
+    enrollmentId?: string | null;
+    lookups: OutreachGateLookups;
+}
+export type OutreachGateCode = 'contact_missing' | 'invalid_email' | 'email_not_on_contact' | 'free_mail' | 'country_not_allowed' | 'country_unknown' | 'platform_suppressed' | 'host_suppressed' | 'sales_opted_out' | 'do_not_contact' | 'workspace_member' | 'customer' | 'already_enrolled' | 'attestations_missing' | 'personal_line_missing' | 'personal_line_too_long';
+export interface OutreachGateBlock {
+    code: OutreachGateCode;
+    /** A sentence a rep can act on. */
+    reason: string;
+}
+export interface OutreachGateResult {
+    allowed: boolean;
+    /** The address, normalized, or `null` when it is not one. */
+    email: string | null;
+    cold: boolean;
+    country: OutreachRecipientCountry;
+    /** Every gate that refuses, in gate order. */
+    blocks: OutreachGateBlock[];
+    /** The attestations a cold contact still needs, in the order they are asked. */
+    missingAttestations: OutreachAttestationKind[];
+}
+/**
+ * Whether a contact came to the sending site's business through no inbound
+ * door — see the module note.
+ */
+export declare function isColdOutreachContact(contact: Record<string, unknown> | null | undefined, contactGroupId: string, hasInboundEmail: boolean): boolean;
+/**
+ * Whether the sending site's business counts the contact as a customer: a
+ * `customer` stage, the `evangelist` stage past it, or an order on record.
+ */
+export declare function isOutreachCustomer(contact: Record<string, unknown> | null | undefined, contactGroupId: string): boolean;
+/** A confirmation counts only when it says who confirmed it and when. */
+export declare function outreachAttestationHolds(attestations: OutreachAttestations | null | undefined, kind: OutreachAttestationKind): boolean;
+/** The personal line as stored: one line, whitespace settled. */
+export declare function normalizeOutreachPersonalLine(value: unknown): string;
+/** Every gate an address and a contact must pass — see the module note. */
+export declare function evaluateOutreachGates(input: OutreachGateInput): OutreachGateResult;