@aglyn/plugins-outreach 1.0.0-beta.143

package/src/lib/engine/schedule.js

@@ -0,0 +1,115 @@
+/**
+ * @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.
+ */ /*==========================================
+ * WHEN A STEP COMES DUE (AGL-2979).
+ *
+ * A step waits a number of BUSINESS days after the one before it, counted on
+ * the mailbox's own calendar — the rep's Monday, not the server's — and then
+ * waits again, if it has to, for the sending window to open. So a follow-up
+ * two business days after a Friday 16:40 send is due Tuesday at about 16:40,
+ * and one that lands on a Saturday or after hours goes out at the next
+ * opening instead.
+ *
+ * ## Jitter
+ *
+ * Every due time moves by up to half of {@link OUTREACH_DUE_JITTER_MINUTES}
+ * either way, drawn from an injected random source, and never out of the
+ * window it was placed in. A person does not answer every follow-up at the
+ * same minute, and a mailbox whose mail leaves on the dot reads like the
+ * software it is. A time that had to be moved to an opening only moves later,
+ * so a morning's worth of follow-ups is spread over the first hour rather
+ * than stacked on the opening minute.
+ *
+ * The random source is a parameter so a test can pin it and so nothing here
+ * reads a clock or a global.
+ *==========================================*/ import { addZonedBusinessDays, isValidTimeZone, isWithinWeeklySchedule, nextWeeklyOpening } from "@aglyn/shared-util-timestamp/zoned-time";
+/** How far a due time may move, in total: half of it either way. */ export 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 const OUTREACH_AUTO_REPLY_POSTPONE_BUSINESS_DAYS = 5;
+const MINUTE_MS = 60000;
+/** A send window as the weekly schedule the zone math reads. */ export function outreachWindowSchedule(window) {
+    const schedule = {};
+    if (!window || !Array.isArray(window.days)) return schedule;
+    for (const day of window.days){
+        if (Number.isInteger(day) && day >= 0 && day <= 6) {
+            schedule[day] = [
+                {
+                    start: window.startMinute,
+                    end: window.endMinute
+                }
+            ];
+        }
+    }
+    return schedule;
+}
+/** The window a sequence's steps go out in: its own, or else its mailbox's. */ export function effectiveOutreachWindow(sequenceWindow, mailboxWindow) {
+    var _ref;
+    return (_ref = sequenceWindow != null ? sequenceWindow : mailboxWindow) != null ? _ref : null;
+}
+/** Whether `atMs` is inside the window, read in `timeZone`. */ export function isOutreachWindowOpen(atMs, window, timeZone) {
+    if (!isValidTimeZone(timeZone)) return false;
+    return isWithinWeeklySchedule(atMs, outreachWindowSchedule(window), timeZone);
+}
+function draw(random) {
+    const value = typeof random === 'function' ? random() : 0.5;
+    if (!Number.isFinite(value)) return 0.5;
+    return Math.min(Math.max(value, 0), 1 - Number.EPSILON);
+}
+/**
+ * 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 function scheduleOutreachDue(input) {
+    var _input_jitterMinutes;
+    const { fromMs, timeZone } = input;
+    if (!Number.isFinite(fromMs) || !isValidTimeZone(timeZone)) return null;
+    const delay = input.delayBusinessDays;
+    if (!Number.isInteger(delay) || delay < 0) return null;
+    const base = addZonedBusinessDays(fromMs, delay, timeZone);
+    const opening = nextWeeklyOpening(base, outreachWindowSchedule(input.window), timeZone);
+    if (!opening) return null;
+    const jitterMs = Math.max(0, (_input_jitterMinutes = input.jitterMinutes) != null ? _input_jitterMinutes : OUTREACH_DUE_JITTER_MINUTES) * MINUTE_MS;
+    const lastMs = opening.endMs - 1;
+    if (opening.startMs > base) {
+        const span = Math.min(jitterMs, lastMs - opening.startMs);
+        return opening.startMs + Math.floor(draw(input.random) * span);
+    }
+    const shifted = base + Math.round((draw(input.random) - 0.5) * jitterMs);
+    return Math.min(lastMs, Math.max(opening.startMs, shifted));
+}
+/**
+ * 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 function postponeOutreachForAutoReply(input) {
+    var _input_businessDays;
+    if (input.nextDueAtMs === null || !Number.isFinite(input.nextDueAtMs)) return null;
+    const postponed = scheduleOutreachDue({
+        fromMs: input.receivedAtMs,
+        delayBusinessDays: (_input_businessDays = input.businessDays) != null ? _input_businessDays : OUTREACH_AUTO_REPLY_POSTPONE_BUSINESS_DAYS,
+        timeZone: input.timeZone,
+        window: input.window,
+        random: input.random
+    });
+    return postponed === null ? input.nextDueAtMs : Math.max(input.nextDueAtMs, postponed);
+}
+
+//# sourceMappingURL=schedule.js.map

package/src/lib/engine/schedule.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/outreach/src/lib/engine/schedule.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 * WHEN A STEP COMES DUE (AGL-2979).\n *\n * A step waits a number of BUSINESS days after the one before it, counted on\n * the mailbox's own calendar — the rep's Monday, not the server's — and then\n * waits again, if it has to, for the sending window to open. So a follow-up\n * two business days after a Friday 16:40 send is due Tuesday at about 16:40,\n * and one that lands on a Saturday or after hours goes out at the next\n * opening instead.\n *\n * ## Jitter\n *\n * Every due time moves by up to half of {@link OUTREACH_DUE_JITTER_MINUTES}\n * either way, drawn from an injected random source, and never out of the\n * window it was placed in. A person does not answer every follow-up at the\n * same minute, and a mailbox whose mail leaves on the dot reads like the\n * software it is. A time that had to be moved to an opening only moves later,\n * so a morning's worth of follow-ups is spread over the first hour rather\n * than stacked on the opening minute.\n *\n * The random source is a parameter so a test can pin it and so nothing here\n * reads a clock or a global.\n *==========================================*/\n\nimport {\n  addZonedBusinessDays,\n  isValidTimeZone,\n  isWithinWeeklySchedule,\n  nextWeeklyOpening,\n  type WeeklySchedule,\n} from '@aglyn/shared-util-timestamp/zoned-time'\nimport type { OutreachSendWindow } from '../model/outreach.types'\n\n/** How far a due time may move, in total: half of it either way. */\nexport const OUTREACH_DUE_JITTER_MINUTES = 60\n\n/**\n * How long an out-of-office reply holds the next step back, in business\n * days — a working week, the usual length of an absence — measured from\n * when the reply arrived. A step already due later than that keeps its time.\n */\nexport const OUTREACH_AUTO_REPLY_POSTPONE_BUSINESS_DAYS = 5\n\n/** A source of numbers in `[0, 1)`, such as `Math.random`. */\nexport type OutreachRandom = () => number\n\nconst MINUTE_MS = 60_000\n\n/** A send window as the weekly schedule the zone math reads. */\nexport function outreachWindowSchedule(\n  window: OutreachSendWindow | null | undefined,\n): WeeklySchedule {\n  const schedule: Record<number, { start: number; end: number }[]> = {}\n  if (!window || !Array.isArray(window.days)) return schedule\n  for (const day of window.days) {\n    if (Number.isInteger(day) && day >= 0 && day <= 6) {\n      schedule[day] = [{ start: window.startMinute, end: window.endMinute }]\n    }\n  }\n  return schedule\n}\n\n/** The window a sequence's steps go out in: its own, or else its mailbox's. */\nexport function effectiveOutreachWindow(\n  sequenceWindow: OutreachSendWindow | null | undefined,\n  mailboxWindow: OutreachSendWindow | null | undefined,\n): OutreachSendWindow | null {\n  return sequenceWindow ?? mailboxWindow ?? null\n}\n\n/** Whether `atMs` is inside the window, read in `timeZone`. */\nexport function isOutreachWindowOpen(\n  atMs: number,\n  window: OutreachSendWindow | null | undefined,\n  timeZone: string,\n): boolean {\n  if (!isValidTimeZone(timeZone)) return false\n  return isWithinWeeklySchedule(atMs, outreachWindowSchedule(window), timeZone)\n}\n\nfunction draw(random: OutreachRandom | null | undefined): number {\n  const value = typeof random === 'function' ? random() : 0.5\n  if (!Number.isFinite(value)) return 0.5\n  return Math.min(Math.max(value, 0), 1 - Number.EPSILON)\n}\n\nexport interface OutreachDueInput {\n  /** The instant the wait is counted from: the last step's send, or the enrollment. */\n  fromMs: number\n  delayBusinessDays: number\n  /** The mailbox's IANA zone. */\n  timeZone: string\n  /** The window the step goes out in — {@link effectiveOutreachWindow}. */\n  window: OutreachSendWindow | null | undefined\n  random: OutreachRandom\n  /** Defaults to {@link OUTREACH_DUE_JITTER_MINUTES}; `0` places the time exactly. */\n  jitterMinutes?: number\n}\n\n/**\n * When a step comes due — see the module note — or `null` when it never\n * can: a zone `Intl` does not know, a delay that is not a whole number of\n * days, or a window that never opens.\n */\nexport function scheduleOutreachDue(input: OutreachDueInput): number | null {\n  const { fromMs, timeZone } = input\n  if (!Number.isFinite(fromMs) || !isValidTimeZone(timeZone)) return null\n  const delay = input.delayBusinessDays\n  if (!Number.isInteger(delay) || delay < 0) return null\n  const base = addZonedBusinessDays(fromMs, delay, timeZone)\n  const opening = nextWeeklyOpening(base, outreachWindowSchedule(input.window), timeZone)\n  if (!opening) return null\n  const jitterMs = Math.max(0, input.jitterMinutes ?? OUTREACH_DUE_JITTER_MINUTES) * MINUTE_MS\n  const lastMs = opening.endMs - 1\n  if (opening.startMs > base) {\n    const span = Math.min(jitterMs, lastMs - opening.startMs)\n    return opening.startMs + Math.floor(draw(input.random) * span)\n  }\n  const shifted = base + Math.round((draw(input.random) - 0.5) * jitterMs)\n  return Math.min(lastMs, Math.max(opening.startMs, shifted))\n}\n\nexport interface OutreachAutoReplyPostponeInput {\n  /** The enrollment's `nextDueAtMs`; `null` has nothing waiting to hold back. */\n  nextDueAtMs: number | null\n  /** When the automatic reply arrived. */\n  receivedAtMs: number\n  timeZone: string\n  window: OutreachSendWindow | null | undefined\n  random: OutreachRandom\n  businessDays?: number\n}\n\n/**\n * The due time after an out-of-office reply: at least\n * {@link OUTREACH_AUTO_REPLY_POSTPONE_BUSINESS_DAYS} business days after the\n * reply, never earlier than the step was already due. An automatic reply\n * says the person is away, not that they answered, so the enrollment waits\n * and does not stop.\n */\nexport function postponeOutreachForAutoReply(\n  input: OutreachAutoReplyPostponeInput,\n): number | null {\n  if (input.nextDueAtMs === null || !Number.isFinite(input.nextDueAtMs)) return null\n  const postponed = scheduleOutreachDue({\n    fromMs: input.receivedAtMs,\n    delayBusinessDays: input.businessDays ?? OUTREACH_AUTO_REPLY_POSTPONE_BUSINESS_DAYS,\n    timeZone: input.timeZone,\n    window: input.window,\n    random: input.random,\n  })\n  return postponed === null ? input.nextDueAtMs : Math.max(input.nextDueAtMs, postponed)\n}\n"],"names":["addZonedBusinessDays","isValidTimeZone","isWithinWeeklySchedule","nextWeeklyOpening","OUTREACH_DUE_JITTER_MINUTES","OUTREACH_AUTO_REPLY_POSTPONE_BUSINESS_DAYS","MINUTE_MS","outreachWindowSchedule","window","schedule","Array","isArray","days","day","Number","isInteger","start","startMinute","end","endMinute","effectiveOutreachWindow","sequenceWindow","mailboxWindow","isOutreachWindowOpen","atMs","timeZone","draw","random","value","isFinite","Math","min","max","EPSILON","scheduleOutreachDue","input","fromMs","delay","delayBusinessDays","base","opening","jitterMs","jitterMinutes","lastMs","endMs","startMs","span","floor","shifted","round","postponeOutreachForAutoReply","nextDueAtMs","postponed","receivedAtMs","businessDays"],"mappings":"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"}

package/src/lib/engine/sending-capacity.d.ts

@@ -0,0 +1,96 @@
+/**
+ * @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 { OutreachEnrollment, OutreachMailbox, OutreachSendWindow, OutreachSequence } from '../model/outreach.types';
+/** The ramp's daily caps: week one, week two, and every week after. */
+export declare const OUTREACH_RAMP_DAILY_CAPS: readonly number[];
+/** The most any mailbox sends in one day, whatever is configured. */
+export declare const OUTREACH_DAILY_CAP_MAX = 50;
+/** How often the sending runtime runs, in minutes. */
+export declare const OUTREACH_TICK_MINUTES = 15;
+/** The most one mailbox sends in one run. */
+export declare const OUTREACH_SENDS_PER_TICK_MAX = 5;
+/**
+ * The ramp's cap for the day `nowMs` falls in, or `null` when no ramp is
+ * running. Weeks are counted in calendar days of the mailbox's zone from the
+ * day the ramp began, which is day one of week one; a start in the future
+ * reads as week one.
+ */
+export declare function outreachRampCap(rampStartedAtMs: number | null | undefined, nowMs: number, timeZone: string): number | null;
+/** The day's cap: the least of the configured cap, the ramp and the ceiling. */
+export declare function outreachDailyCap(input: {
+    configuredCap: number;
+    rampStartedAtMs: number | null | undefined;
+    nowMs: number;
+    timeZone: string;
+}): number;
+/**
+ * How many emails the mailbox has sent today: its counter when the counter
+ * belongs to today in the mailbox's zone, and `0` when it belongs to an
+ * earlier day.
+ */
+export declare function outreachSentToday(health: Pick<OutreachMailbox['health'], 'sentToday' | 'sentOnDay'> | null | undefined, nowMs: number, timeZone: string): number;
+/** Why a mailbox may send nothing this run. */
+export type OutreachTickHold = 'mailbox_not_connected' | 'invalid_timezone' | 'daily_cap_reached';
+export interface OutreachTickAllowanceInput {
+    mailbox: Pick<OutreachMailbox, 'status' | 'dailyCap' | 'rampStartedAtMs' | 'timezone' | 'window' | 'health'>;
+    nowMs: number;
+    /**
+     * The window the day's sends are spread across. The mailbox's own by
+     * default; when it is closed but a sequence's own window is open, the
+     * remainder is not paced and only the per-run maximum holds.
+     */
+    paceWindow?: OutreachSendWindow | null;
+    tickMinutes?: number;
+    perTickMax?: number;
+}
+export interface OutreachTickAllowance {
+    /** How many emails this run may send from the mailbox. */
+    allowance: number;
+    dailyCap: number;
+    sentToday: number;
+    remainingToday: number;
+    /** Why the allowance is zero, when a rule rather than an empty queue made it so. */
+    hold: OutreachTickHold | null;
+}
+/** How many emails a mailbox may send in this run — see the module note. */
+export declare function outreachTickAllowance(input: OutreachTickAllowanceInput): OutreachTickAllowance;
+/** One due enrollment beside the sequence it runs through. */
+export interface OutreachDueCandidate {
+    enrollment: Pick<OutreachEnrollment, 'id' | 'status' | 'nextDueAtMs' | 'stepIndex' | 'email' | 'mailboxId' | 'sequenceId'>;
+    sequence: Pick<OutreachSequence, 'id' | 'status' | 'steps' | 'settings'>;
+}
+export interface OutreachDueSelection {
+    /** Email steps to send this run, in the order to send them. */
+    emails: OutreachDueCandidate[];
+    /** Task steps due now. Each becomes a CRM task; none spends the allowance. */
+    tasks: OutreachDueCandidate[];
+    /** Email steps that were due inside their window and did not fit this run. */
+    deferred: OutreachDueCandidate[];
+}
+export interface OutreachDueSelectionInput {
+    candidates: readonly OutreachDueCandidate[];
+    mailbox: Pick<OutreachMailbox, 'id' | 'timezone' | 'window'>;
+    nowMs: number;
+    /** {@link outreachTickAllowance}'s `allowance`. */
+    allowance: number;
+}
+/**
+ * The due enrollments one mailbox runs now, in order — see the module note.
+ * An enrollment is due when it and its sequence are active, it belongs to
+ * this mailbox, its time has come, and — for an email — its window is open.
+ */
+export declare function selectDueOutreachEnrollments(input: OutreachDueSelectionInput): OutreachDueSelection;

package/src/lib/engine/sending-capacity.js

@@ -0,0 +1,172 @@
+/**
+ * @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 MUCH A MAILBOX MAY SEND (AGL-2979).
+ *
+ * ## The daily cap
+ *
+ * A mailbox sends at most the least of three numbers in one of its own
+ * days: the cap its owner configured; the warm-up ramp — 10 a day in its
+ * first week, 20 in its second, 30 from its third — while a ramp is running;
+ * and {@link OUTREACH_DAILY_CAP_MAX}, which nothing lifts. Mailbox providers
+ * judge a new sender by how its volume grows, and a mailbox that goes from
+ * nothing to fifty on its first morning is judged accordingly.
+ *
+ * ## The tick
+ *
+ * The runtime runs every {@link OUTREACH_TICK_MINUTES} minutes. What is left
+ * of the day's cap is spread over the ticks left in the window, so thirty
+ * emails go out across the working day rather than in its first half hour,
+ * and no tick sends more than {@link OUTREACH_SENDS_PER_TICK_MAX}.
+ *
+ * ## Which due enrollments go first
+ *
+ * Follow-ups before first emails: a thread already started is a
+ * conversation a delay would break, and a first email can start tomorrow
+ * just as well. Then the longest-waiting, then the id, so two runs over the
+ * same enrollments agree. One email per address per tick, whatever the data
+ * says.
+ *==========================================*/ import { isValidTimeZone, nextWeeklyOpening, zonedCalendarDaysBetween, zonedDayKey } from "@aglyn/shared-util-timestamp/zoned-time";
+import { effectiveOutreachWindow, isOutreachWindowOpen, outreachWindowSchedule } from "./schedule.js";
+import { firstEmailStepIndex } from "./sequence-validation.js";
+/** The ramp's daily caps: week one, week two, and every week after. */ export const OUTREACH_RAMP_DAILY_CAPS = [
+    10,
+    20,
+    30
+];
+/** The most any mailbox sends in one day, whatever is configured. */ export const OUTREACH_DAILY_CAP_MAX = 50;
+/** How often the sending runtime runs, in minutes. */ export const OUTREACH_TICK_MINUTES = 15;
+/** The most one mailbox sends in one run. */ export const OUTREACH_SENDS_PER_TICK_MAX = 5;
+const MINUTE_MS = 60000;
+/**
+ * The ramp's cap for the day `nowMs` falls in, or `null` when no ramp is
+ * running. Weeks are counted in calendar days of the mailbox's zone from the
+ * day the ramp began, which is day one of week one; a start in the future
+ * reads as week one.
+ */ export function outreachRampCap(rampStartedAtMs, nowMs, timeZone) {
+    if (typeof rampStartedAtMs !== 'number' || !Number.isFinite(rampStartedAtMs)) return null;
+    const days = zonedCalendarDaysBetween(rampStartedAtMs, nowMs, timeZone);
+    const week = Math.max(0, Math.floor(days / 7));
+    return OUTREACH_RAMP_DAILY_CAPS[Math.min(week, OUTREACH_RAMP_DAILY_CAPS.length - 1)];
+}
+/** The day's cap: the least of the configured cap, the ramp and the ceiling. */ export function outreachDailyCap(input) {
+    const configured = Number.isFinite(input.configuredCap) ? Math.max(0, Math.floor(input.configuredCap)) : 0;
+    const ramp = outreachRampCap(input.rampStartedAtMs, input.nowMs, input.timeZone);
+    return Math.min(configured, ramp != null ? ramp : OUTREACH_DAILY_CAP_MAX, OUTREACH_DAILY_CAP_MAX);
+}
+/**
+ * How many emails the mailbox has sent today: its counter when the counter
+ * belongs to today in the mailbox's zone, and `0` when it belongs to an
+ * earlier day.
+ */ export function outreachSentToday(health, nowMs, timeZone) {
+    if (!health || health.sentOnDay !== zonedDayKey(nowMs, timeZone)) return 0;
+    const sent = Number(health.sentToday);
+    return Number.isFinite(sent) ? Math.max(0, Math.floor(sent)) : 0;
+}
+/** How many emails a mailbox may send in this run — see the module note. */ export function outreachTickAllowance(input) {
+    var _input_tickMinutes, _input_perTickMax;
+    const { mailbox, nowMs } = input;
+    const none = (hold, dailyCap = 0, sentToday = 0)=>({
+            allowance: 0,
+            dailyCap,
+            sentToday,
+            remainingToday: Math.max(0, dailyCap - sentToday),
+            hold
+        });
+    if ((mailbox == null ? void 0 : mailbox.status) !== 'connected') return none('mailbox_not_connected');
+    if (!isValidTimeZone(mailbox.timezone)) return none('invalid_timezone');
+    const dailyCap = outreachDailyCap({
+        configuredCap: mailbox.dailyCap,
+        rampStartedAtMs: mailbox.rampStartedAtMs,
+        nowMs,
+        timeZone: mailbox.timezone
+    });
+    const sentToday = outreachSentToday(mailbox.health, nowMs, mailbox.timezone);
+    const remainingToday = Math.max(0, dailyCap - sentToday);
+    if (remainingToday === 0) return none('daily_cap_reached', dailyCap, sentToday);
+    const tickMinutes = Math.max(1, (_input_tickMinutes = input.tickMinutes) != null ? _input_tickMinutes : OUTREACH_TICK_MINUTES);
+    const perTickMax = Math.max(0, Math.floor((_input_perTickMax = input.perTickMax) != null ? _input_perTickMax : OUTREACH_SENDS_PER_TICK_MAX));
+    const paceWindow = input.paceWindow === undefined ? mailbox.window : input.paceWindow;
+    const opening = nextWeeklyOpening(nowMs, outreachWindowSchedule(paceWindow), mailbox.timezone);
+    let paced = remainingToday;
+    if (opening && opening.startMs <= nowMs) {
+        const ticksLeft = Math.max(1, Math.ceil((opening.endMs - nowMs) / (tickMinutes * MINUTE_MS)));
+        paced = Math.ceil(remainingToday / ticksLeft);
+    }
+    return {
+        allowance: Math.min(remainingToday, paced, perTickMax),
+        dailyCap,
+        sentToday,
+        remainingToday,
+        hold: null
+    };
+}
+const byDueThenId = (a, b)=>{
+    var _a_enrollment_nextDueAtMs, _b_enrollment_nextDueAtMs;
+    return ((_a_enrollment_nextDueAtMs = a.enrollment.nextDueAtMs) != null ? _a_enrollment_nextDueAtMs : 0) - ((_b_enrollment_nextDueAtMs = b.enrollment.nextDueAtMs) != null ? _b_enrollment_nextDueAtMs : 0) || (a.enrollment.id < b.enrollment.id ? -1 : a.enrollment.id > b.enrollment.id ? 1 : 0);
+};
+/**
+ * The due enrollments one mailbox runs now, in order — see the module note.
+ * An enrollment is due when it and its sequence are active, it belongs to
+ * this mailbox, its time has come, and — for an email — its window is open.
+ */ export function selectDueOutreachEnrollments(input) {
+    var _input_candidates;
+    const { mailbox, nowMs } = input;
+    const emails = [];
+    const tasks = [];
+    for (const candidate of (_input_candidates = input.candidates) != null ? _input_candidates : []){
+        var _sequence_steps;
+        const { enrollment, sequence } = candidate != null ? candidate : {};
+        if ((enrollment == null ? void 0 : enrollment.status) !== 'active' || (sequence == null ? void 0 : sequence.status) !== 'active') continue;
+        if (enrollment.sequenceId !== sequence.id || enrollment.mailboxId !== mailbox.id) continue;
+        const due = enrollment.nextDueAtMs;
+        if (typeof due !== 'number' || !Number.isFinite(due) || due > nowMs) continue;
+        const step = (_sequence_steps = sequence.steps) == null ? void 0 : _sequence_steps[enrollment.stepIndex];
+        if ((step == null ? void 0 : step.kind) === 'task') {
+            tasks.push(candidate);
+        } else if ((step == null ? void 0 : step.kind) === 'email') {
+            var _sequence_settings;
+            const window = effectiveOutreachWindow((_sequence_settings = sequence.settings) == null ? void 0 : _sequence_settings.window, mailbox.window);
+            if (!isOutreachWindowOpen(nowMs, window, mailbox.timezone)) continue;
+            emails.push({
+                candidate,
+                followUp: enrollment.stepIndex > firstEmailStepIndex(sequence.steps)
+            });
+        }
+    }
+    emails.sort((a, b)=>Number(b.followUp) - Number(a.followUp) || byDueThenId(a.candidate, b.candidate));
+    const allowance = Math.max(0, Math.floor(Number(input.allowance) || 0));
+    const selected = [];
+    const deferred = [];
+    const addresses = new Set();
+    for (const { candidate } of emails){
+        var _candidate_enrollment_email;
+        const address = String((_candidate_enrollment_email = candidate.enrollment.email) != null ? _candidate_enrollment_email : '').trim().toLowerCase();
+        if (selected.length < allowance && !addresses.has(address)) {
+            selected.push(candidate);
+            addresses.add(address);
+        } else {
+            deferred.push(candidate);
+        }
+    }
+    return {
+        emails: selected,
+        tasks: tasks.sort(byDueThenId),
+        deferred
+    };
+}
+
+//# sourceMappingURL=sending-capacity.js.map

package/src/lib/engine/sending-capacity.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/outreach/src/lib/engine/sending-capacity.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 * HOW MUCH A MAILBOX MAY SEND (AGL-2979).\n *\n * ## The daily cap\n *\n * A mailbox sends at most the least of three numbers in one of its own\n * days: the cap its owner configured; the warm-up ramp — 10 a day in its\n * first week, 20 in its second, 30 from its third — while a ramp is running;\n * and {@link OUTREACH_DAILY_CAP_MAX}, which nothing lifts. Mailbox providers\n * judge a new sender by how its volume grows, and a mailbox that goes from\n * nothing to fifty on its first morning is judged accordingly.\n *\n * ## The tick\n *\n * The runtime runs every {@link OUTREACH_TICK_MINUTES} minutes. What is left\n * of the day's cap is spread over the ticks left in the window, so thirty\n * emails go out across the working day rather than in its first half hour,\n * and no tick sends more than {@link OUTREACH_SENDS_PER_TICK_MAX}.\n *\n * ## Which due enrollments go first\n *\n * Follow-ups before first emails: a thread already started is a\n * conversation a delay would break, and a first email can start tomorrow\n * just as well. Then the longest-waiting, then the id, so two runs over the\n * same enrollments agree. One email per address per tick, whatever the data\n * says.\n *==========================================*/\n\nimport {\n  isValidTimeZone,\n  nextWeeklyOpening,\n  zonedCalendarDaysBetween,\n  zonedDayKey,\n} from '@aglyn/shared-util-timestamp/zoned-time'\nimport type {\n  OutreachEnrollment,\n  OutreachMailbox,\n  OutreachSendWindow,\n  OutreachSequence,\n} from '../model/outreach.types'\nimport { effectiveOutreachWindow, isOutreachWindowOpen, outreachWindowSchedule } from './schedule'\nimport { firstEmailStepIndex } from './sequence-validation'\n\n/** The ramp's daily caps: week one, week two, and every week after. */\nexport const OUTREACH_RAMP_DAILY_CAPS: readonly number[] = [10, 20, 30]\n\n/** The most any mailbox sends in one day, whatever is configured. */\nexport const OUTREACH_DAILY_CAP_MAX = 50\n\n/** How often the sending runtime runs, in minutes. */\nexport const OUTREACH_TICK_MINUTES = 15\n\n/** The most one mailbox sends in one run. */\nexport const OUTREACH_SENDS_PER_TICK_MAX = 5\n\nconst MINUTE_MS = 60_000\n\n/**\n * The ramp's cap for the day `nowMs` falls in, or `null` when no ramp is\n * running. Weeks are counted in calendar days of the mailbox's zone from the\n * day the ramp began, which is day one of week one; a start in the future\n * reads as week one.\n */\nexport function outreachRampCap(\n  rampStartedAtMs: number | null | undefined,\n  nowMs: number,\n  timeZone: string,\n): number | null {\n  if (typeof rampStartedAtMs !== 'number' || !Number.isFinite(rampStartedAtMs)) return null\n  const days = zonedCalendarDaysBetween(rampStartedAtMs, nowMs, timeZone)\n  const week = Math.max(0, Math.floor(days / 7))\n  return OUTREACH_RAMP_DAILY_CAPS[Math.min(week, OUTREACH_RAMP_DAILY_CAPS.length - 1)]\n}\n\n/** The day's cap: the least of the configured cap, the ramp and the ceiling. */\nexport function outreachDailyCap(input: {\n  configuredCap: number\n  rampStartedAtMs: number | null | undefined\n  nowMs: number\n  timeZone: string\n}): number {\n  const configured = Number.isFinite(input.configuredCap)\n    ? Math.max(0, Math.floor(input.configuredCap))\n    : 0\n  const ramp = outreachRampCap(input.rampStartedAtMs, input.nowMs, input.timeZone)\n  return Math.min(configured, ramp ?? OUTREACH_DAILY_CAP_MAX, OUTREACH_DAILY_CAP_MAX)\n}\n\n/**\n * How many emails the mailbox has sent today: its counter when the counter\n * belongs to today in the mailbox's zone, and `0` when it belongs to an\n * earlier day.\n */\nexport function outreachSentToday(\n  health: Pick<OutreachMailbox['health'], 'sentToday' | 'sentOnDay'> | null | undefined,\n  nowMs: number,\n  timeZone: string,\n): number {\n  if (!health || health.sentOnDay !== zonedDayKey(nowMs, timeZone)) return 0\n  const sent = Number(health.sentToday)\n  return Number.isFinite(sent) ? Math.max(0, Math.floor(sent)) : 0\n}\n\n/** Why a mailbox may send nothing this run. */\nexport type OutreachTickHold = 'mailbox_not_connected' | 'invalid_timezone' | 'daily_cap_reached'\n\nexport interface OutreachTickAllowanceInput {\n  mailbox: Pick<\n    OutreachMailbox,\n    'status' | 'dailyCap' | 'rampStartedAtMs' | 'timezone' | 'window' | 'health'\n  >\n  nowMs: number\n  /**\n   * The window the day's sends are spread across. The mailbox's own by\n   * default; when it is closed but a sequence's own window is open, the\n   * remainder is not paced and only the per-run maximum holds.\n   */\n  paceWindow?: OutreachSendWindow | null\n  tickMinutes?: number\n  perTickMax?: number\n}\n\nexport interface OutreachTickAllowance {\n  /** How many emails this run may send from the mailbox. */\n  allowance: number\n  dailyCap: number\n  sentToday: number\n  remainingToday: number\n  /** Why the allowance is zero, when a rule rather than an empty queue made it so. */\n  hold: OutreachTickHold | null\n}\n\n/** How many emails a mailbox may send in this run — see the module note. */\nexport function outreachTickAllowance(input: OutreachTickAllowanceInput): OutreachTickAllowance {\n  const { mailbox, nowMs } = input\n  const none = (hold: OutreachTickHold, dailyCap = 0, sentToday = 0): OutreachTickAllowance => ({\n    allowance: 0,\n    dailyCap,\n    sentToday,\n    remainingToday: Math.max(0, dailyCap - sentToday),\n    hold,\n  })\n  if (mailbox?.status !== 'connected') return none('mailbox_not_connected')\n  if (!isValidTimeZone(mailbox.timezone)) return none('invalid_timezone')\n  const dailyCap = outreachDailyCap({\n    configuredCap: mailbox.dailyCap,\n    rampStartedAtMs: mailbox.rampStartedAtMs,\n    nowMs,\n    timeZone: mailbox.timezone,\n  })\n  const sentToday = outreachSentToday(mailbox.health, nowMs, mailbox.timezone)\n  const remainingToday = Math.max(0, dailyCap - sentToday)\n  if (remainingToday === 0) return none('daily_cap_reached', dailyCap, sentToday)\n  const tickMinutes = Math.max(1, input.tickMinutes ?? OUTREACH_TICK_MINUTES)\n  const perTickMax = Math.max(0, Math.floor(input.perTickMax ?? OUTREACH_SENDS_PER_TICK_MAX))\n  const paceWindow = input.paceWindow === undefined ? mailbox.window : input.paceWindow\n  const opening = nextWeeklyOpening(nowMs, outreachWindowSchedule(paceWindow), mailbox.timezone)\n  let paced = remainingToday\n  if (opening && opening.startMs <= nowMs) {\n    const ticksLeft = Math.max(1, Math.ceil((opening.endMs - nowMs) / (tickMinutes * MINUTE_MS)))\n    paced = Math.ceil(remainingToday / ticksLeft)\n  }\n  return {\n    allowance: Math.min(remainingToday, paced, perTickMax),\n    dailyCap,\n    sentToday,\n    remainingToday,\n    hold: null,\n  }\n}\n\n/** One due enrollment beside the sequence it runs through. */\nexport interface OutreachDueCandidate {\n  enrollment: Pick<\n    OutreachEnrollment,\n    'id' | 'status' | 'nextDueAtMs' | 'stepIndex' | 'email' | 'mailboxId' | 'sequenceId'\n  >\n  sequence: Pick<OutreachSequence, 'id' | 'status' | 'steps' | 'settings'>\n}\n\nexport interface OutreachDueSelection {\n  /** Email steps to send this run, in the order to send them. */\n  emails: OutreachDueCandidate[]\n  /** Task steps due now. Each becomes a CRM task; none spends the allowance. */\n  tasks: OutreachDueCandidate[]\n  /** Email steps that were due inside their window and did not fit this run. */\n  deferred: OutreachDueCandidate[]\n}\n\nexport interface OutreachDueSelectionInput {\n  candidates: readonly OutreachDueCandidate[]\n  mailbox: Pick<OutreachMailbox, 'id' | 'timezone' | 'window'>\n  nowMs: number\n  /** {@link outreachTickAllowance}'s `allowance`. */\n  allowance: number\n}\n\nconst byDueThenId = (a: OutreachDueCandidate, b: OutreachDueCandidate) =>\n  (a.enrollment.nextDueAtMs ?? 0) - (b.enrollment.nextDueAtMs ?? 0) ||\n  (a.enrollment.id < b.enrollment.id ? -1 : a.enrollment.id > b.enrollment.id ? 1 : 0)\n\n/**\n * The due enrollments one mailbox runs now, in order — see the module note.\n * An enrollment is due when it and its sequence are active, it belongs to\n * this mailbox, its time has come, and — for an email — its window is open.\n */\nexport function selectDueOutreachEnrollments(input: OutreachDueSelectionInput): OutreachDueSelection {\n  const { mailbox, nowMs } = input\n  const emails: Array<{ candidate: OutreachDueCandidate; followUp: boolean }> = []\n  const tasks: OutreachDueCandidate[] = []\n  for (const candidate of input.candidates ?? []) {\n    const { enrollment, sequence } = candidate ?? ({} as OutreachDueCandidate)\n    if (enrollment?.status !== 'active' || sequence?.status !== 'active') continue\n    if (enrollment.sequenceId !== sequence.id || enrollment.mailboxId !== mailbox.id) continue\n    const due = enrollment.nextDueAtMs\n    if (typeof due !== 'number' || !Number.isFinite(due) || due > nowMs) continue\n    const step = sequence.steps?.[enrollment.stepIndex]\n    if (step?.kind === 'task') {\n      tasks.push(candidate)\n    } else if (step?.kind === 'email') {\n      const window = effectiveOutreachWindow(sequence.settings?.window, mailbox.window)\n      if (!isOutreachWindowOpen(nowMs, window, mailbox.timezone)) continue\n      emails.push({\n        candidate,\n        followUp: enrollment.stepIndex > firstEmailStepIndex(sequence.steps),\n      })\n    }\n  }\n  emails.sort(\n    (a, b) => Number(b.followUp) - Number(a.followUp) || byDueThenId(a.candidate, b.candidate),\n  )\n  const allowance = Math.max(0, Math.floor(Number(input.allowance) || 0))\n  const selected: OutreachDueCandidate[] = []\n  const deferred: OutreachDueCandidate[] = []\n  const addresses = new Set<string>()\n  for (const { candidate } of emails) {\n    const address = String(candidate.enrollment.email ?? '').trim().toLowerCase()\n    if (selected.length < allowance && !addresses.has(address)) {\n      selected.push(candidate)\n      addresses.add(address)\n    } else {\n      deferred.push(candidate)\n    }\n  }\n  return { emails: selected, tasks: tasks.sort(byDueThenId), deferred }\n}\n"],"names":["isValidTimeZone","nextWeeklyOpening","zonedCalendarDaysBetween","zonedDayKey","effectiveOutreachWindow","isOutreachWindowOpen","outreachWindowSchedule","firstEmailStepIndex","OUTREACH_RAMP_DAILY_CAPS","OUTREACH_DAILY_CAP_MAX","OUTREACH_TICK_MINUTES","OUTREACH_SENDS_PER_TICK_MAX","MINUTE_MS","outreachRampCap","rampStartedAtMs","nowMs","timeZone","Number","isFinite","days","week","Math","max","floor","min","length","outreachDailyCap","input","configured","configuredCap","ramp","outreachSentToday","health","sentOnDay","sent","sentToday","outreachTickAllowance","mailbox","none","hold","dailyCap","allowance","remainingToday","status","timezone","tickMinutes","perTickMax","paceWindow","undefined","window","opening","paced","startMs","ticksLeft","ceil","endMs","byDueThenId","a","b","enrollment","nextDueAtMs","id","selectDueOutreachEnrollments","emails","tasks","candidate","candidates","sequence","sequenceId","mailboxId","due","step","steps","stepIndex","kind","push","settings","followUp","sort","selected","deferred","addresses","Set","address","String","email","trim","toLowerCase","has","add"],"mappings":"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"}

package/src/lib/engine/sequence-validation.d.ts

@@ -0,0 +1,90 @@
+/**
+ * @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 CrmMergeFieldGroup } from '@aglyn/aglyn/app-utils/crm-email-templates';
+import { type OutreachOrgSettings, type OutreachSendWindow, type OutreachSequence, type OutreachSequenceSettings, type OutreachSequenceStep } from '../model/outreach.types';
+/** The merge field the rep's signal sentence is written into a step with. */
+export declare const OUTREACH_PERSONAL_LINE_FIELD = "enrollment.personalLine";
+/** A merge field as the Outreach editor's picker offers it. */
+export interface OutreachMergeFieldDefinition {
+    key: string;
+    label: string;
+    group: CrmMergeFieldGroup | 'Enrollment';
+}
+/**
+ * Every field an Outreach step may use: the CRM's, which the composer fills
+ * through the CRM's own resolver, and the enrollment's.
+ */
+export declare const OUTREACH_MERGE_FIELDS: readonly OutreachMergeFieldDefinition[];
+/** The longest name a sequence carries. */
+export declare const OUTREACH_SEQUENCE_NAME_MAX = 120;
+/** The longest title a task step carries. */
+export declare const OUTREACH_TASK_TITLE_MAX = 200;
+export type OutreachValidationSeverity = 'error' | 'warning';
+export type OutreachValidationCode = 'name_required' | 'name_too_long' | 'mailbox_required' | 'steps_required' | 'too_many_steps' | 'too_many_email_steps' | 'step_id_required' | 'duplicate_step_id' | 'unknown_step_kind' | 'delay_invalid' | 'subject_required' | 'subject_too_long' | 'subject_reply_prefix' | 'body_required' | 'body_and_template' | 'body_too_long' | 'unknown_merge_field' | 'personal_line_unused' | 'task_kind_invalid' | 'task_title_required' | 'task_title_too_long' | 'window_days_invalid' | 'window_hours_invalid' | 'countries_required' | 'country_invalid' | 'legal_name_required' | 'postal_address_required';
+export interface OutreachValidationIssue {
+    /** The field, dotted: `name`, `steps.2.subject`, `settings.window`, `orgSettings.postalAddress`. */
+    path: string;
+    code: OutreachValidationCode;
+    message: string;
+    severity: OutreachValidationSeverity;
+}
+/** Whether any issue in the list stops a save or an activation. */
+export declare function hasOutreachValidationErrors(issues: readonly OutreachValidationIssue[]): boolean;
+/** The index of the first email step, or `-1` for a sequence with none. */
+export declare function firstEmailStepIndex(steps: readonly OutreachSequenceStep[] | null | undefined): number;
+/**
+ * Whether the email at `index` is sent as a reply in the thread an earlier
+ * email started: every email after the first unless it says otherwise. The
+ * first email starts the thread whatever its `replyInThread` says.
+ */
+export declare function isInThreadEmailStep(steps: readonly OutreachSequenceStep[] | null | undefined, index: number): boolean;
+/**
+ * Whether a subject opens with a reply or forward prefix — `Re:`, `Fwd:`,
+ * `AW:` — which on an email that answers nothing tells the recipient a
+ * conversation exists that does not. The prefixes are the CRM thread
+ * reader's, so the two agree on what one looks like.
+ */
+export declare function outreachSubjectHasReplyPrefix(subject: unknown): boolean;
+/** A sending window's shape: at least one weekday, and an opening before a close. */
+export declare function validateOutreachSendWindow(window: OutreachSendWindow | null | undefined, path?: string): OutreachValidationIssue[];
+/**
+ * The allowed countries, as stored or typed, reduced to unique uppercase
+ * alpha-2 codes in the order given. Anything that is not two letters is
+ * dropped, so a caller that needs to report it checks the raw value.
+ */
+export declare function normalizeOutreachAllowedCountries(value: unknown): string[];
+/**
+ * A stored settings map with the defaults applied: the United States alone,
+ * no customers, the mailbox's own window. A field a writer never set reads
+ * as its default rather than as a permission nobody gave.
+ */
+export declare function readOutreachSequenceSettings(raw: Partial<OutreachSequenceSettings> | Record<string, unknown> | null | undefined): OutreachSequenceSettings;
+export declare function validateOutreachSequenceSettings(settings: OutreachSequenceSettings | null | undefined, path?: string): OutreachValidationIssue[];
+/** The steps of a sequence: their count, their ids, and each one's own fields. */
+export declare function validateOutreachSteps(steps: readonly OutreachSequenceStep[] | null | undefined, path?: string): OutreachValidationIssue[];
+/** Everything a stored sequence has to be before it may be saved. */
+export declare function validateOutreachSequence(sequence: Pick<OutreachSequence, 'name' | 'mailboxId' | 'steps' | 'settings'> | null | undefined): OutreachValidationIssue[];
+/**
+ * The organization's footer fields: a legal name and a postal address, the
+ * two things the law requires every commercial email to carry.
+ */
+export declare function validateOutreachOrgSettings(settings: Pick<OutreachOrgSettings, 'legalName' | 'postalAddress'> | null | undefined, path?: string): OutreachValidationIssue[];
+/**
+ * What activating a sequence refuses on: every issue saving refuses on, and
+ * an organization whose footer cannot be written yet.
+ */
+export declare function validateOutreachSequenceActivation(sequence: Pick<OutreachSequence, 'name' | 'mailboxId' | 'steps' | 'settings'> | null | undefined, orgSettings: Pick<OutreachOrgSettings, 'legalName' | 'postalAddress'> | null | undefined): OutreachValidationIssue[];