@aglyn/shared-util-email 1.0.0-beta.143

package/src/lib/marketing-send.js

@@ -0,0 +1,459 @@
+/**
+ * @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.
+ */ /**
+ * MARKETING MAIL — the policy half.
+ *
+ * A message is MARKETING when a merchant's audience receives it because the
+ * merchant decided to mail them, rather than because the recipient just did
+ * something. Campaigns are the obvious case; so are a member post, an
+ * abandoned-cart reminder, a back-in-stock alert and a merchant-authored
+ * workflow email.
+ *
+ * ## The three things marketing mail owes, and where they were
+ *
+ * Before this module they were owed by every bulk sender and discharged by
+ * exactly one of them:
+ *
+ *  1. **An unsubscribe mechanism.** `List-Unsubscribe` plus
+ *     `List-Unsubscribe-Post` is what Gmail's and Yahoo's bulk-sender rules
+ *     ask for, and a visible link is what CAN-SPAM asks for. The campaign
+ *     sender adds both; the shared `sendEmail` added neither, so four
+ *     merchant-triggered bulk paths mailed people with no way out.
+ *  2. **A suppression check.** An address that hard-bounced or pressed
+ *     "report spam" must not be mailed again. Those four paths consulted
+ *     neither list.
+ *  3. **A ceiling on how much one person receives.** There was none at any
+ *     scope, so a single recipient could take a campaign, a cart reminder, a
+ *     restock alert, a member post and a workflow email in one day.
+ *
+ * All three are the same shape — a question asked once, per recipient, at the
+ * moment a marketing message is about to leave — so they are one seam rather
+ * than three, and `sendEmail` asks it whenever a caller declares
+ * {@link MarketingSendContext}.
+ *
+ * ## Why the gate is injected rather than imported
+ *
+ * The same split as the send-rate governor beside it. Answering the question
+ * needs Firestore: two suppression collections and a per-recipient counter.
+ * The durable half therefore lives in `@aglyn/tenant-data-admin`, which is
+ * the only layer that may hold the Admin SDK — this library is `scope:shared`
+ * and the dependency edge already runs the other way. So the gate reaches
+ * `sendEmail` through {@link setMarketingSendGate}.
+ *
+ * Nothing installed means UNGATED, not refused: a unit test, a preview build
+ * and a self-host that never installs one all keep sending. A control that
+ * turns its own absence into an outage is worse than the burst it guards.
+ *
+ * ## Why this file holds no crypto and mints no URL
+ *
+ * The unsubscribe URL is an HMAC over the recipient's address, and
+ * `node:crypto` cannot ride into a browser bundle — console components import
+ * this library's barrel. The gate returns the minted URL instead, from the
+ * server layer that already signs one.
+ */ /*
+ * `send-rate.ts` imports nothing, so this cannot be half of a cycle — which
+ * matters, because this module is imported by `send-email.ts` alongside that
+ * one and a cycle between the two would resolve differently under swc and
+ * jest.
+ */ import { escapeEmailHtml } from "./email-render.js";
+import { resolveSendPriority } from "./send-rate.js";
+/**
+ * Whether a message is MARKETING, derived from what it already carries.
+ *
+ * ## Nothing new to remember, on purpose
+ *
+ * The obvious design is a `kind: 'marketing' | 'transactional'` option on
+ * `sendEmail`. It is rejected for the reason the `from` override was deleted
+ * and the `context` tag was derived rather than threaded: twenty call sites
+ * cannot each be relied on to set a field, and the twenty-first is the one that
+ * does not. The consequence of forgetting here is a merchant's campaign leaving
+ * on the pooled identity that carries every other site's password resets — a
+ * failure nobody sees until the pool stops delivering.
+ *
+ * So the answer is read off two things a marketing send is ALREADY obliged to
+ * carry, neither of which is optional and neither of which was added for this:
+ *
+ * 1. **`marketing`** — the context object. A message that declares it gets the
+ *    RFC 8058 header pair, the suppression check and the frequency cap, so a
+ *    marketing sender cannot omit it and still be correct; it would be shipping
+ *    mail with no unsubscribe link. Four of the five marketing senders in the
+ *    tree take this arm.
+ * 2. **`priority === 'campaign'`** — which `resolveSendPriority` derives from
+ *    `context: 'campaign'`. The campaign sender mints its own unsubscribe
+ *    headers upstream and so passes no `marketing` context, but it is the one
+ *    sender that cannot avoid this label: the hourly governor is allowed to
+ *    refuse a campaign, and a campaign that hid from the priority would be
+ *    hiding from that too.
+ *
+ * A sender would have to defeat BOTH — no unsubscribe context and no campaign
+ * priority — to reach the pool with promotional mail, and a message in that
+ * state is already broken in ways its author would notice.
+ *
+ * ## Polarity
+ *
+ * A message matching neither is transactional, which is the permissive answer,
+ * and that is deliberate — the same choice `resolveSendPriority` makes for the
+ * same reason. Enumerating what is RESTRICTED means a forgotten caller sends a
+ * receipt that goes out. Enumerating what is PERMITTED means a forgotten caller
+ * drops one, and a dropped password reset is the failure you learn about from a
+ * support ticket.
+ */ export function isMarketingMessage(options) {
+    var _ref;
+    if (options == null ? void 0 : options.marketing) return true;
+    // `context` is consulted only through the same rule the governor uses, so a
+    // context that stops meaning "campaign" cannot leave the two disagreeing.
+    return resolveSendPriority((_ref = options == null ? void 0 : options.context) != null ? _ref : undefined, (options == null ? void 0 : options.priority) || undefined) === 'campaign';
+}
+let installedGate = null;
+/** Installs the durable gate. Called once, from `@aglyn/tenant-data-admin`. */ export function setMarketingSendGate(gate) {
+    installedGate = gate;
+}
+/** The installed gate, or null when nothing has been installed. */ export function getMarketingSendGate() {
+    return installedGate;
+}
+/** Test seam: forget any installed gate. */ export function resetMarketingSendGateForTests() {
+    installedGate = null;
+}
+/**
+ * The rolling window a frequency cap counts over. One day, because that is
+ * the unit a recipient experiences ("this shop mailed me four times today")
+ * and the unit every published vendor cap is expressed in.
+ */ export const MARKETING_FREQUENCY_WINDOW_MS = 86400000;
+/**
+ * How many marketing messages one person may receive from one site inside the
+ * window, by default.
+ *
+ * **A runaway guard, not a marketing policy.** It is deliberately above what
+ * an ordinary merchant produces: the worst legitimate day is a campaign plus
+ * a cart reminder plus a restock alert plus a member post, which is four. Set
+ * lower and the first thing it would refuse is a real message somebody meant
+ * to send; set higher and it stops describing a ceiling at all. What it does
+ * remove is the unbounded case — a member post that mails 200 subscribers per
+ * click with no limit on clicks, and a workflow whose email step fires on
+ * every anonymous form submission.
+ *
+ * The same number for every plan. This is a deliverability control on a
+ * shared sending domain, so it protects every tenant from every other tenant
+ * and cannot be something one plan buys its way past.
+ */ export const MARKETING_FREQUENCY_DEFAULT_PER_WINDOW = 5;
+/** Floor and ceiling on a configured cap — a typo guard, not a policy. */ export const MARKETING_FREQUENCY_MIN_PER_WINDOW = 1;
+export const MARKETING_FREQUENCY_MAX_PER_WINDOW = 1000;
+/**
+ * The live cap.
+ *
+ * Read from the environment so a self-host operator can set their own —
+ * `docs/design` states that every dependency is configurable — and read per
+ * call rather than captured at module load, matching `getEmailConfig`: these
+ * run in serverless handlers where the module may be evaluated during a build.
+ *
+ * An unparseable or out-of-range value falls back to the default rather than
+ * throwing or disabling the cap. A control that a typo can switch off is not
+ * a control.
+ */ export function marketingFrequencyCap() {
+    const raw = Number(process.env.AGLYN_EMAIL_MARKETING_CAP_PER_DAY);
+    if (!Number.isFinite(raw)) return MARKETING_FREQUENCY_DEFAULT_PER_WINDOW;
+    const whole = Math.floor(raw);
+    if (whole < MARKETING_FREQUENCY_MIN_PER_WINDOW || whole > MARKETING_FREQUENCY_MAX_PER_WINDOW) {
+        return MARKETING_FREQUENCY_DEFAULT_PER_WINDOW;
+    }
+    return whole;
+}
+/**
+ * Whether one more message fits, given what this person has already received.
+ *
+ * Pure, so the decision is testable without a Firestore harness — the same
+ * split `emailSendRateVerdict` makes for the platform hour.
+ *
+ * @param recentSendsAtMs every marketing send to this person from this site,
+ *        newest or oldest first, in any order.
+ * @returns the verdict and the trimmed window, so the caller writes back only
+ *          what still counts instead of growing the record forever.
+ */ export function marketingFrequencyVerdict(recentSendsAtMs, nowMs, cap = marketingFrequencyCap()) {
+    const floor = nowMs - MARKETING_FREQUENCY_WINDOW_MS;
+    const inWindow = recentSendsAtMs.filter((at)=>Number.isFinite(at) && at > floor && at <= nowMs).sort((a, b)=>a - b)// Keep the NEWEST when a record has somehow grown past the cap. The
+    // oldest entries are the ones about to leave the window anyway, so
+    // dropping them loses the least information about when this person is
+    // mailable again.
+    .slice(-Math.max(cap, MARKETING_FREQUENCY_MIN_PER_WINDOW));
+    return {
+        allowed: inWindow.length < cap,
+        used: inWindow.length,
+        cap,
+        inWindow
+    };
+}
+/*==========================================
+ * ENGAGEMENT-BASED SUNSETTING.
+ *
+ * Stop mailing an address that has gone quiet. The whole design fits in one
+ * sentence and three refusals it must never become.
+ *
+ * ## ⛔ It refuses a SEND. It never reduces a person.
+ *
+ * `over-limit.ts` states the rule for capacity and this is the same
+ * instrument pointed at attention rather than at count. A sunset does NOT
+ * unsubscribe anybody, does NOT remove them from a list, does NOT delete a
+ * contact and does NOT write a suppression. Every one of those would be a
+ * ceiling performing a deletion, and every one of them is irreversible in a
+ * way the condition that triggered it is not.
+ *
+ * ## It is reversible without anybody doing anything
+ *
+ * The only state is two timestamps: when this site first mailed this person,
+ * and when this person last engaged with our mail. A person who opens or
+ * clicks anything moves the second one, and the very next send finds them
+ * inside the window and mailable. Nothing has to be undone, because nothing
+ * was done.
+ *
+ * ## The three ways it could refuse somebody it should not, and the guards
+ *
+ *  1. **A brand-new subscriber has no engagement yet.** So the window is
+ *     measured from when we STARTED mailing them, and somebody we have not
+ *     been mailing for longer than the window is never refused, however
+ *     little they have engaged.
+ *  2. **We might have no record at all.** An unknown `firstSentAtMs` refuses
+ *     nobody. Missing evidence is not evidence of absence, and the reading
+ *     that mails somebody once more is the recoverable one.
+ *  3. **A campaign is a reviewed act with its recipient count on screen.**
+ *     Sunsetting yields to it exactly as the frequency ceiling does, through
+ *     the same `capped` flag, so the number a merchant read before pressing
+ *     Send stays true. It governs the automated paths, which fire with no
+ *     human present.
+ *
+ * ## Opens are a weak signal and this leans on the broader one anyway
+ *
+ * The industry lesson is to sunset on clicks, because Apple's Mail Privacy
+ * Protection prefetches images and inflates opens. That argument is about
+ * choosing an audience. This is a refusal, and for a refusal the weaker,
+ * more generous signal is the correct one: counting an open as engagement
+ * refuses FEWER people. The audience rules
+ * (`DynamicListEngagement`) keep opens and clicks apart so a merchant
+ * segmenting on engagement can lean on clicks; this deliberately does not.
+ *=========================================*/ /** Floor and ceiling on a configured sunset window — a typo guard. */ export const MARKETING_SUNSET_MIN_DAYS = 30;
+export const MARKETING_SUNSET_MAX_DAYS = 3650;
+/**
+ * The window, in days, or 0 for OFF.
+ *
+ * **Off unless an operator turns it on**, and that default is the honest one:
+ * no compared vendor automates this, so a platform that silently stopped
+ * mailing a merchant's quiet subscribers would be doing something none of
+ * their previous tools did and none of their recipients asked for. The value
+ * is a number of days rather than a boolean because the only interesting
+ * question about a sunset is where it starts.
+ *
+ * Read per call rather than captured at module load, matching the frequency
+ * cap beside it: these run in serverless handlers where the module may be
+ * evaluated during a build.
+ *
+ * An unparseable or out-of-range value reads as OFF rather than falling back
+ * to a default. This is the opposite of {@link marketingFrequencyCap}'s
+ * handling and deliberately so — a typo there weakens a guard that is on by
+ * default, and a typo here would ENABLE a refusal nobody asked for.
+ */ export function marketingSunsetDays() {
+    const raw = Number(process.env.AGLYN_EMAIL_SUNSET_AFTER_DAYS);
+    if (!Number.isFinite(raw)) return 0;
+    const whole = Math.floor(raw);
+    if (whole < MARKETING_SUNSET_MIN_DAYS || whole > MARKETING_SUNSET_MAX_DAYS) {
+        return 0;
+    }
+    return whole;
+}
+/**
+ * Whether this person has gone quiet for longer than the window.
+ *
+ * Pure, so the decision is testable without a Firestore harness — the same
+ * split {@link marketingFrequencyVerdict} makes.
+ *
+ * @param days 0 disables the sunset entirely and this always allows.
+ */ export function marketingSunsetVerdict(facts, nowMs, days = marketingSunsetDays()) {
+    var _facts_firstSentAtMs, _facts_lastEngagedAtMs;
+    if (!days || days <= 0) {
+        return {
+            allowed: true,
+            days: 0,
+            quietForDays: null
+        };
+    }
+    const floor = nowMs - days * 86400000;
+    const first = Number((_facts_firstSentAtMs = facts.firstSentAtMs) != null ? _facts_firstSentAtMs : 0);
+    // Guard 1 and 2 together: no record, or a relationship younger than the
+    // window, allows. A person cannot have been quiet for longer than we have
+    // been mailing them.
+    if (!Number.isFinite(first) || first <= 0 || first >= floor) {
+        return {
+            allowed: true,
+            days,
+            quietForDays: null
+        };
+    }
+    const engaged = Number((_facts_lastEngagedAtMs = facts.lastEngagedAtMs) != null ? _facts_lastEngagedAtMs : 0);
+    if (Number.isFinite(engaged) && engaged > 0 && engaged >= floor) {
+        return {
+            allowed: true,
+            days,
+            quietForDays: null
+        };
+    }
+    const since = Number.isFinite(engaged) && engaged > 0 ? engaged : first;
+    return {
+        allowed: false,
+        days,
+        quietForDays: Math.floor((nowMs - since) / 86400000)
+    };
+}
+/** The default: no expressed preference, so only the platform ceiling binds. */ export const DEFAULT_MARKETING_CADENCE = 'all';
+/**
+ * The minimum gap each choice asks for, in millis.
+ *
+ * Calendar-naive on purpose. "At most one a week" is a promise about pace,
+ * and honoring it as seven days from the last message is both what the words
+ * say and what a recipient can check; anchoring it to a calendar week would
+ * let two messages land on a Sunday and a Monday and still be "one a week".
+ */ export const MARKETING_CADENCE_INTERVAL_MS = {
+    all: 0,
+    daily: 86400000,
+    weekly: 7 * 86400000,
+    monthly: 30 * 86400000
+};
+/** How each choice reads, wherever one is named to a person or an operator. */ export const MARKETING_CADENCE_LABELS = {
+    all: 'As they come',
+    daily: 'At most one a day',
+    weekly: 'At most one a week',
+    monthly: 'At most one a month'
+};
+/**
+ * Coerces a stored or submitted value to a cadence.
+ *
+ * Everything unrecognized becomes {@link DEFAULT_MARKETING_CADENCE}. The
+ * direction matters and is the opposite of the consent policy's: a malformed
+ * consent value must not become a way to switch enforcement off, because its
+ * failure mode is mail to somebody who declined. A malformed cadence falling
+ * to `'monthly'` would withhold mail from everybody whose record got
+ * corrupted, and nobody asked for that either — so an unreadable preference
+ * reads as no preference, and the person keeps whatever the ceiling allows.
+ */ export function normalizeMarketingCadence(value) {
+    return value === 'daily' || value === 'weekly' || value === 'monthly' ? value : DEFAULT_MARKETING_CADENCE;
+}
+/**
+ * Whether enough time has passed for one more message at this pace.
+ *
+ * Pure, so the rule can be asserted without a Firestore harness — the same
+ * split {@link marketingFrequencyVerdict} makes.
+ *
+ * @param lastSentAtMs when this site last sent this person marketing mail, or
+ *        `null` for somebody it has never mailed. Never mailed always allows:
+ *        a cadence is a gap between messages and there is no first gap.
+ * @returns the verdict and, on a refusal, the instant the next message may go
+ *          — so a caller that defers has something to defer UNTIL rather than
+ *          a retry loop that discovers the answer by asking again.
+ */ export function marketingCadenceVerdict(cadence, lastSentAtMs, nowMs) {
+    var _MARKETING_CADENCE_INTERVAL_MS_cadence;
+    const interval = (_MARKETING_CADENCE_INTERVAL_MS_cadence = MARKETING_CADENCE_INTERVAL_MS[cadence]) != null ? _MARKETING_CADENCE_INTERVAL_MS_cadence : 0;
+    const last = Number(lastSentAtMs);
+    if (!interval || !Number.isFinite(last) || last <= 0) {
+        return {
+            allowed: true,
+            cadence,
+            nextAllowedAtMs: nowMs
+        };
+    }
+    const nextAllowedAtMs = last + interval;
+    /*
+   * A stored instant in the FUTURE allows rather than refusing until it
+   * passes. Clocks disagree across processes and a record written a few
+   * seconds ahead would otherwise hold a recipient's mail for a whole
+   * interval, which is a much larger error than the one it would prevent.
+   */ if (last > nowMs) return {
+        allowed: true,
+        cadence,
+        nextAllowedAtMs: nowMs
+    };
+    return {
+        allowed: nowMs >= nextAllowedAtMs,
+        cadence,
+        nextAllowedAtMs
+    };
+}
+/**
+ * The RFC 8058 header pair.
+ *
+ * Both or neither: `List-Unsubscribe` alone does not satisfy the bulk-sender
+ * rules, and `List-Unsubscribe-Post` without a URL to post to advertises a
+ * verb nothing serves.
+ */ export function unsubscribeHeaders(unsubscribeUrl) {
+    if (!unsubscribeUrl) return {};
+    return {
+        'List-Unsubscribe': `<${unsubscribeUrl}>`,
+        'List-Unsubscribe-Post': 'List-Unsubscribe=One-Click'
+    };
+}
+/**
+ * What the visible opt-out is CALLED, in every part of every message.
+ *
+ * The link opens the preference page, where leaving one stream is a choice
+ * alongside leaving all of them — and a footer that says only "Unsubscribe"
+ * is the only place a recipient would have learned that, so it never gets
+ * said. The word "unsubscribe" stays in the line because that is what a
+ * recipient scans a footer for.
+ *
+ * Named once and shared with `renderRecipientEmail`, which writes this same
+ * line into a campaign's text part: two spellings of one sentence is how the
+ * idempotency checks below come to append a second footer to a message that
+ * already had one.
+ */ export const UNSUBSCRIBE_FOOTER_LABEL = 'Choose which emails you get, or unsubscribe';
+/**
+ * The visible opt-out, appended to the plain-text part.
+ *
+ * The headers are for the mailbox provider; this is for the person. CAN-SPAM
+ * asks for a mechanism the recipient can see and use, and a header is neither
+ * — most clients render no control for it at all unless the sender's domain
+ * reputation is high enough for the provider to offer one.
+ *
+ * Idempotent by URL: a body that already carries the link is returned
+ * untouched, so a sender that writes its own footer does not get two.
+ */ export function appendUnsubscribeText(text, unsubscribeUrl) {
+    if (!unsubscribeUrl || text && text.includes(unsubscribeUrl)) return text;
+    return `${text != null ? text : ''}\n\n—\n${UNSUBSCRIBE_FOOTER_LABEL}: ${unsubscribeUrl}`;
+}
+/**
+ * The same visible opt-out for the HTML part.
+ *
+ * Appended to whatever the sender produced rather than woven into it, because
+ * the HTML may be a merchant-designed template this module knows nothing
+ * about. A designed template that already renders `{{unsubscribeUrl}}`
+ * carries the URL, so the check below leaves it alone and the merchant's own
+ * placement wins.
+ *
+ * ⚠️ That check has to look for the ESCAPED URL as well. A signed opt-out
+ * link carries `&` between its query parameters, and a renderer putting it
+ * into an `href` escapes it — so `renderEmailHtml` emits `…&amp;sig=…` and a
+ * plain `includes` of the unescaped URL matches nothing. Every designed
+ * template in the product goes through that renderer, which means the
+ * merchants who DID place the token were the ones getting two footers.
+ *
+ * Styles are inline and literal because this is email HTML: mail clients
+ * strip `<style>` blocks and support no CSS variables, so a theme token
+ * cannot reach the wire.
+ */ export function appendUnsubscribeHtml(html, unsubscribeUrl) {
+    if (!unsubscribeUrl) return html;
+    if (html && (html.includes(unsubscribeUrl) || html.includes(escapeEmailHtml(unsubscribeUrl)))) {
+        return html;
+    }
+    const footer = '<div style="margin:24px auto 0;max-width:600px;padding:16px 24px;' + "font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto," + 'Helvetica,Arial,sans-serif;font-size:12px;line-height:1.5;' + 'color:#616161;text-align:center">' + `<a href="${escapeEmailHtml(unsubscribeUrl)}" style="color:#616161">` + `${UNSUBSCRIBE_FOOTER_LABEL}</a>` + '</div>';
+    return `${html != null ? html : ''}${footer}`;
+}
+
+//# sourceMappingURL=marketing-send.js.map

package/src/lib/marketing-send.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/shared/util/email/src/lib/marketing-send.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 * MARKETING MAIL — the policy half.\n *\n * A message is MARKETING when a merchant's audience receives it because the\n * merchant decided to mail them, rather than because the recipient just did\n * something. Campaigns are the obvious case; so are a member post, an\n * abandoned-cart reminder, a back-in-stock alert and a merchant-authored\n * workflow email.\n *\n * ## The three things marketing mail owes, and where they were\n *\n * Before this module they were owed by every bulk sender and discharged by\n * exactly one of them:\n *\n *  1. **An unsubscribe mechanism.** `List-Unsubscribe` plus\n *     `List-Unsubscribe-Post` is what Gmail's and Yahoo's bulk-sender rules\n *     ask for, and a visible link is what CAN-SPAM asks for. The campaign\n *     sender adds both; the shared `sendEmail` added neither, so four\n *     merchant-triggered bulk paths mailed people with no way out.\n *  2. **A suppression check.** An address that hard-bounced or pressed\n *     \"report spam\" must not be mailed again. Those four paths consulted\n *     neither list.\n *  3. **A ceiling on how much one person receives.** There was none at any\n *     scope, so a single recipient could take a campaign, a cart reminder, a\n *     restock alert, a member post and a workflow email in one day.\n *\n * All three are the same shape — a question asked once, per recipient, at the\n * moment a marketing message is about to leave — so they are one seam rather\n * than three, and `sendEmail` asks it whenever a caller declares\n * {@link MarketingSendContext}.\n *\n * ## Why the gate is injected rather than imported\n *\n * The same split as the send-rate governor beside it. Answering the question\n * needs Firestore: two suppression collections and a per-recipient counter.\n * The durable half therefore lives in `@aglyn/tenant-data-admin`, which is\n * the only layer that may hold the Admin SDK — this library is `scope:shared`\n * and the dependency edge already runs the other way. So the gate reaches\n * `sendEmail` through {@link setMarketingSendGate}.\n *\n * Nothing installed means UNGATED, not refused: a unit test, a preview build\n * and a self-host that never installs one all keep sending. A control that\n * turns its own absence into an outage is worse than the burst it guards.\n *\n * ## Why this file holds no crypto and mints no URL\n *\n * The unsubscribe URL is an HMAC over the recipient's address, and\n * `node:crypto` cannot ride into a browser bundle — console components import\n * this library's barrel. The gate returns the minted URL instead, from the\n * server layer that already signs one.\n */\n\n/*\n * `send-rate.ts` imports nothing, so this cannot be half of a cycle — which\n * matters, because this module is imported by `send-email.ts` alongside that\n * one and a cycle between the two would resolve differently under swc and\n * jest.\n */\nimport { escapeEmailHtml } from './email-render'\nimport { resolveSendPriority, type EmailSendPriority } from './send-rate'\n\n/** What a marketing send declares about itself. */\nexport interface MarketingSendContext {\n  /** The site whose audience this is. Both suppression lists key on it. */\n  hostId: string\n  /**\n   * The site's public origin, for the unsubscribe link.\n   *\n   * The CALLER resolves it — through `hostPublicOrigin`, from the host\n   * document — because the shared subdomain policy lives in the framework\n   * library and neither this module nor the gate may import it. Empty when a\n   * host has no custom domain and no subdomain, which is a site nobody can\n   * reach; the send then carries no unsubscribe URL and says so in the logs\n   * rather than minting a link that resolves to nothing.\n   */\n  siteBase: string\n  /**\n   * An unsubscribe URL the caller has already minted, and the campaign it\n   * belongs to.\n   *\n   * The campaign sender builds its own, because the same URL has to reach the\n   * designed template as an `{{unsubscribeUrl}}` merge value long before the\n   * message is handed over. Supplied, it is used verbatim and nothing is\n   * minted — one link per message, whoever made it.\n   */\n  unsubscribeUrl?: string\n  /**\n   * The `List-Unsubscribe` URL, when the caller minted its own pair.\n   *\n   * Separate from {@link unsubscribeUrl} because the two are read by\n   * different readers. This one is POSTed by a mailbox provider with nobody\n   * present, so it must name the route that writes on POST; the other is\n   * clicked by a person, so it names the preference page. Absent, the header\n   * falls back to `unsubscribeUrl` — which is right for a caller that minted\n   * only one link, and wrong only for one that minted a page and did not say\n   * so.\n   */\n  oneClickUrl?: string\n  /**\n   * Whether a frequency cap may refuse this message.\n   *\n   * `false` for a campaign. A campaign is a merchant's deliberate, reviewed\n   * act with a recipient count on screen before they press Send; a cap that\n   * silently removed people from it would make that number a lie, and a\n   * one-shot send has nowhere to hold the remainder for later. So a campaign\n   * COUNTS toward what a recipient has received — it is most of the load a\n   * person feels — and yields the refusal to the automated paths, which fire\n   * with no human present and are the ones that stack.\n   *\n   * Defaults to true: an unmarked caller is a machine.\n   */\n  capped?: boolean\n  /**\n   * The STREAM this message belongs to, so a recipient who left that stream\n   * is not mailed it.\n   *\n   * ## Absent refuses nobody, and that is the whole safety property\n   *\n   * A topic opt-out governs marketing STREAMS — \"Promotions and offers\",\n   * \"Newsletter\". It is not a thing anybody can untick off a receipt, a\n   * password reset or a booking confirmation, and a gate that refused those\n   * on a topic preference would be the failure mode this control is most\n   * capable of causing. Two guards make that unreachable rather than\n   * unlikely:\n   *\n   *  1. transactional mail declares no `marketing` context at all, so it\n   *     never reaches the gate; and\n   *  2. a marketing caller that names no stream gets no topic refusal here.\n   *     `filterTopicSendable` already reads an empty topic that way — there\n   *     is no stream to have left — and this preserves it rather than\n   *     defaulting to one.\n   *\n   * So the check binds exactly the senders that declare what they are, which\n   * is the same polarity `isMarketingMessage` chose: enumerate what is\n   * restricted, and a forgotten caller sends rather than silently drops.\n   *\n   * ## Why the gate asks it at all, when the consent split does not\n   *\n   * The two used to travel together in `email-flow-gate.ts`, and they are not\n   * the same kind of fact. The consent split is the ORG's policy over its own\n   * audience, which is why it stays a caller-side question. A topic opt-out\n   * is the RECIPIENT talking to the platform, recorded by the same preference\n   * page that records their cadence and reached by the same\n   * `List-Unsubscribe` link — so it belongs with the suppression and cadence\n   * checks, at the one chokepoint every marketing message crosses.\n   */\n  topicId?: string\n}\n\n/** What the gate is asked, once per marketing message. */\nexport interface MarketingSendGateRequest {\n  hostId: string\n  siteBase: string\n  /** The single recipient. A marketing message addresses exactly one person. */\n  email: string\n  /** The caller's `context` label, for the log line on a refusal. */\n  context?: string\n  /**\n   * The stream this message belongs to, or absent for a message that belongs\n   * to none. See {@link MarketingSendContext.topicId} — absent refuses\n   * nobody.\n   */\n  topicId?: string\n  /** Whether a frequency cap may refuse — see {@link MarketingSendContext}. */\n  capped: boolean\n}\n\n/** Why a marketing message was not sent, or `null` when it may go. */\nexport type MarketingSendRefusal =\n  /** On a suppression list: unsubscribed, hard-bounced, or a complaint. */\n  | 'suppressed'\n  /**\n   * They have left the STREAM this message belongs to.\n   *\n   * Kept apart from `suppressed` even though both are terminal for this\n   * message, because they describe different people: somebody on a\n   * suppression list has left the site, and somebody here has left one of its\n   * streams and still wants the others. A merchant reading why a send shrank\n   * has a different thing to do about each, and only one of them is a list\n   * that has to be rebuilt.\n   *\n   * NOT retryable — the condition clears when the person re-subscribes, not\n   * when time passes.\n   */\n  | 'topic-unsubscribed'\n  /** This person has already received their ceiling from this site. */\n  | 'frequency-capped'\n  /**\n   * The RECIPIENT asked for less than this, and it has not been long enough.\n   *\n   * Kept apart from `frequency-capped` even though both are refusals about\n   * pace, because they are refusals on behalf of different people: the\n   * ceiling protects a shared sending domain from a merchant, and this\n   * carries out a request the person on the other end made on the preference\n   * page. Reporting them as one would make \"why did this not send\" answerable\n   * only by guessing, and it is the merchant-facing half of a promise the\n   * product made to a recipient.\n   */\n  | 'cadence-limited'\n  /**\n   * This site has been mailing this person for longer than the sunset window\n   * and nothing in that window says they are still listening.\n   *\n   * NOT retryable by a sweep — the condition does not clear on a schedule,\n   * it clears when the person engages. See {@link marketingSunsetVerdict}.\n   */\n  | 'unengaged'\n\nexport interface MarketingSendGateVerdict {\n  allowed: boolean\n  /** Set when `allowed` is false. */\n  refusal?: MarketingSendRefusal\n  /** Human-readable, for the log and the `detail` on the result. */\n  detail?: string\n  /**\n   * The signed opt-out URL a PERSON clicks, when the gate could mint one.\n   * Points at the preference page, where the stream this message belongs to\n   * is one of the things they can stop instead of all of it. Absent leaves\n   * the message without unsubscribe headers, which is a misconfiguration to\n   * fix and not a reason to refuse mail.\n   */\n  unsubscribeUrl?: string\n  /**\n   * The same signature over the one-click route, for `List-Unsubscribe`.\n   *\n   * A mailbox provider POSTs that header with no human present and expects\n   * the act to have happened when it reads the 200, so it must never name a\n   * page of checkboxes somebody has to submit. Absent, the header falls back\n   * to {@link unsubscribeUrl}.\n   */\n  oneClickUrl?: string\n}\n\n/**\n * Whether a message is MARKETING, derived from what it already carries.\n *\n * ## Nothing new to remember, on purpose\n *\n * The obvious design is a `kind: 'marketing' | 'transactional'` option on\n * `sendEmail`. It is rejected for the reason the `from` override was deleted\n * and the `context` tag was derived rather than threaded: twenty call sites\n * cannot each be relied on to set a field, and the twenty-first is the one that\n * does not. The consequence of forgetting here is a merchant's campaign leaving\n * on the pooled identity that carries every other site's password resets — a\n * failure nobody sees until the pool stops delivering.\n *\n * So the answer is read off two things a marketing send is ALREADY obliged to\n * carry, neither of which is optional and neither of which was added for this:\n *\n * 1. **`marketing`** — the context object. A message that declares it gets the\n *    RFC 8058 header pair, the suppression check and the frequency cap, so a\n *    marketing sender cannot omit it and still be correct; it would be shipping\n *    mail with no unsubscribe link. Four of the five marketing senders in the\n *    tree take this arm.\n * 2. **`priority === 'campaign'`** — which `resolveSendPriority` derives from\n *    `context: 'campaign'`. The campaign sender mints its own unsubscribe\n *    headers upstream and so passes no `marketing` context, but it is the one\n *    sender that cannot avoid this label: the hourly governor is allowed to\n *    refuse a campaign, and a campaign that hid from the priority would be\n *    hiding from that too.\n *\n * A sender would have to defeat BOTH — no unsubscribe context and no campaign\n * priority — to reach the pool with promotional mail, and a message in that\n * state is already broken in ways its author would notice.\n *\n * ## Polarity\n *\n * A message matching neither is transactional, which is the permissive answer,\n * and that is deliberate — the same choice `resolveSendPriority` makes for the\n * same reason. Enumerating what is RESTRICTED means a forgotten caller sends a\n * receipt that goes out. Enumerating what is PERMITTED means a forgotten caller\n * drops one, and a dropped password reset is the failure you learn about from a\n * support ticket.\n */\nexport function isMarketingMessage(options: {\n  marketing?: unknown\n  priority?: string | null\n  context?: string | null\n}): boolean {\n  if (options?.marketing) return true\n  // `context` is consulted only through the same rule the governor uses, so a\n  // context that stops meaning \"campaign\" cannot leave the two disagreeing.\n  return resolveSendPriority(\n    options?.context ?? undefined,\n    (options?.priority as EmailSendPriority) || undefined,\n  ) === 'campaign'\n}\n\nexport type MarketingSendGate = (\n  request: MarketingSendGateRequest,\n) => Promise<MarketingSendGateVerdict>\n\nlet installedGate: MarketingSendGate | null = null\n\n/** Installs the durable gate. Called once, from `@aglyn/tenant-data-admin`. */\nexport function setMarketingSendGate(gate: MarketingSendGate | null): void {\n  installedGate = gate\n}\n\n/** The installed gate, or null when nothing has been installed. */\nexport function getMarketingSendGate(): MarketingSendGate | null {\n  return installedGate\n}\n\n/** Test seam: forget any installed gate. */\nexport function resetMarketingSendGateForTests(): void {\n  installedGate = null\n}\n\n/**\n * The rolling window a frequency cap counts over. One day, because that is\n * the unit a recipient experiences (\"this shop mailed me four times today\")\n * and the unit every published vendor cap is expressed in.\n */\nexport const MARKETING_FREQUENCY_WINDOW_MS = 86_400_000\n\n/**\n * How many marketing messages one person may receive from one site inside the\n * window, by default.\n *\n * **A runaway guard, not a marketing policy.** It is deliberately above what\n * an ordinary merchant produces: the worst legitimate day is a campaign plus\n * a cart reminder plus a restock alert plus a member post, which is four. Set\n * lower and the first thing it would refuse is a real message somebody meant\n * to send; set higher and it stops describing a ceiling at all. What it does\n * remove is the unbounded case — a member post that mails 200 subscribers per\n * click with no limit on clicks, and a workflow whose email step fires on\n * every anonymous form submission.\n *\n * The same number for every plan. This is a deliverability control on a\n * shared sending domain, so it protects every tenant from every other tenant\n * and cannot be something one plan buys its way past.\n */\nexport const MARKETING_FREQUENCY_DEFAULT_PER_WINDOW = 5\n\n/** Floor and ceiling on a configured cap — a typo guard, not a policy. */\nexport const MARKETING_FREQUENCY_MIN_PER_WINDOW = 1\nexport const MARKETING_FREQUENCY_MAX_PER_WINDOW = 1_000\n\n/**\n * The live cap.\n *\n * Read from the environment so a self-host operator can set their own —\n * `docs/design` states that every dependency is configurable — and read per\n * call rather than captured at module load, matching `getEmailConfig`: these\n * run in serverless handlers where the module may be evaluated during a build.\n *\n * An unparseable or out-of-range value falls back to the default rather than\n * throwing or disabling the cap. A control that a typo can switch off is not\n * a control.\n */\nexport function marketingFrequencyCap(): number {\n  const raw = Number(process.env.AGLYN_EMAIL_MARKETING_CAP_PER_DAY)\n  if (!Number.isFinite(raw)) return MARKETING_FREQUENCY_DEFAULT_PER_WINDOW\n  const whole = Math.floor(raw)\n  if (\n    whole < MARKETING_FREQUENCY_MIN_PER_WINDOW ||\n    whole > MARKETING_FREQUENCY_MAX_PER_WINDOW\n  ) {\n    return MARKETING_FREQUENCY_DEFAULT_PER_WINDOW\n  }\n  return whole\n}\n\n/**\n * Whether one more message fits, given what this person has already received.\n *\n * Pure, so the decision is testable without a Firestore harness — the same\n * split `emailSendRateVerdict` makes for the platform hour.\n *\n * @param recentSendsAtMs every marketing send to this person from this site,\n *        newest or oldest first, in any order.\n * @returns the verdict and the trimmed window, so the caller writes back only\n *          what still counts instead of growing the record forever.\n */\nexport function marketingFrequencyVerdict(\n  recentSendsAtMs: readonly number[],\n  nowMs: number,\n  cap: number = marketingFrequencyCap(),\n): { allowed: boolean; used: number; cap: number; inWindow: number[] } {\n  const floor = nowMs - MARKETING_FREQUENCY_WINDOW_MS\n  const inWindow = recentSendsAtMs\n    .filter((at) => Number.isFinite(at) && at > floor && at <= nowMs)\n    .sort((a, b) => a - b)\n    // Keep the NEWEST when a record has somehow grown past the cap. The\n    // oldest entries are the ones about to leave the window anyway, so\n    // dropping them loses the least information about when this person is\n    // mailable again.\n    .slice(-Math.max(cap, MARKETING_FREQUENCY_MIN_PER_WINDOW))\n  return {\n    allowed: inWindow.length < cap,\n    used: inWindow.length,\n    cap,\n    inWindow,\n  }\n}\n\n/*==========================================\n * ENGAGEMENT-BASED SUNSETTING.\n *\n * Stop mailing an address that has gone quiet. The whole design fits in one\n * sentence and three refusals it must never become.\n *\n * ## ⛔ It refuses a SEND. It never reduces a person.\n *\n * `over-limit.ts` states the rule for capacity and this is the same\n * instrument pointed at attention rather than at count. A sunset does NOT\n * unsubscribe anybody, does NOT remove them from a list, does NOT delete a\n * contact and does NOT write a suppression. Every one of those would be a\n * ceiling performing a deletion, and every one of them is irreversible in a\n * way the condition that triggered it is not.\n *\n * ## It is reversible without anybody doing anything\n *\n * The only state is two timestamps: when this site first mailed this person,\n * and when this person last engaged with our mail. A person who opens or\n * clicks anything moves the second one, and the very next send finds them\n * inside the window and mailable. Nothing has to be undone, because nothing\n * was done.\n *\n * ## The three ways it could refuse somebody it should not, and the guards\n *\n *  1. **A brand-new subscriber has no engagement yet.** So the window is\n *     measured from when we STARTED mailing them, and somebody we have not\n *     been mailing for longer than the window is never refused, however\n *     little they have engaged.\n *  2. **We might have no record at all.** An unknown `firstSentAtMs` refuses\n *     nobody. Missing evidence is not evidence of absence, and the reading\n *     that mails somebody once more is the recoverable one.\n *  3. **A campaign is a reviewed act with its recipient count on screen.**\n *     Sunsetting yields to it exactly as the frequency ceiling does, through\n *     the same `capped` flag, so the number a merchant read before pressing\n *     Send stays true. It governs the automated paths, which fire with no\n *     human present.\n *\n * ## Opens are a weak signal and this leans on the broader one anyway\n *\n * The industry lesson is to sunset on clicks, because Apple's Mail Privacy\n * Protection prefetches images and inflates opens. That argument is about\n * choosing an audience. This is a refusal, and for a refusal the weaker,\n * more generous signal is the correct one: counting an open as engagement\n * refuses FEWER people. The audience rules\n * (`DynamicListEngagement`) keep opens and clicks apart so a merchant\n * segmenting on engagement can lean on clicks; this deliberately does not.\n *=========================================*/\n\n/** Floor and ceiling on a configured sunset window — a typo guard. */\nexport const MARKETING_SUNSET_MIN_DAYS = 30\nexport const MARKETING_SUNSET_MAX_DAYS = 3_650\n\n/**\n * The window, in days, or 0 for OFF.\n *\n * **Off unless an operator turns it on**, and that default is the honest one:\n * no compared vendor automates this, so a platform that silently stopped\n * mailing a merchant's quiet subscribers would be doing something none of\n * their previous tools did and none of their recipients asked for. The value\n * is a number of days rather than a boolean because the only interesting\n * question about a sunset is where it starts.\n *\n * Read per call rather than captured at module load, matching the frequency\n * cap beside it: these run in serverless handlers where the module may be\n * evaluated during a build.\n *\n * An unparseable or out-of-range value reads as OFF rather than falling back\n * to a default. This is the opposite of {@link marketingFrequencyCap}'s\n * handling and deliberately so — a typo there weakens a guard that is on by\n * default, and a typo here would ENABLE a refusal nobody asked for.\n */\nexport function marketingSunsetDays(): number {\n  const raw = Number(process.env.AGLYN_EMAIL_SUNSET_AFTER_DAYS)\n  if (!Number.isFinite(raw)) return 0\n  const whole = Math.floor(raw)\n  if (whole < MARKETING_SUNSET_MIN_DAYS || whole > MARKETING_SUNSET_MAX_DAYS) {\n    return 0\n  }\n  return whole\n}\n\n/** What the sunset needs to know about one person. */\nexport interface MarketingSunsetFacts {\n  /**\n   * When this site first sent this person marketing mail, or null when we\n   * have no record. Null never refuses.\n   */\n  firstSentAtMs: number | null\n  /** When they last opened or clicked any of our mail, or null for never. */\n  lastEngagedAtMs: number | null\n}\n\n/**\n * Whether this person has gone quiet for longer than the window.\n *\n * Pure, so the decision is testable without a Firestore harness — the same\n * split {@link marketingFrequencyVerdict} makes.\n *\n * @param days 0 disables the sunset entirely and this always allows.\n */\nexport function marketingSunsetVerdict(\n  facts: MarketingSunsetFacts,\n  nowMs: number,\n  days: number = marketingSunsetDays(),\n): { allowed: boolean; days: number; quietForDays: number | null } {\n  if (!days || days <= 0) {\n    return { allowed: true, days: 0, quietForDays: null }\n  }\n  const floor = nowMs - days * 86_400_000\n  const first = Number(facts.firstSentAtMs ?? 0)\n  // Guard 1 and 2 together: no record, or a relationship younger than the\n  // window, allows. A person cannot have been quiet for longer than we have\n  // been mailing them.\n  if (!Number.isFinite(first) || first <= 0 || first >= floor) {\n    return { allowed: true, days, quietForDays: null }\n  }\n  const engaged = Number(facts.lastEngagedAtMs ?? 0)\n  if (Number.isFinite(engaged) && engaged > 0 && engaged >= floor) {\n    return { allowed: true, days, quietForDays: null }\n  }\n  const since = Number.isFinite(engaged) && engaged > 0 ? engaged : first\n  return {\n    allowed: false,\n    days,\n    quietForDays: Math.floor((nowMs - since) / 86_400_000),\n  }\n}\n\n/**\n * HOW OFTEN THE RECIPIENT ASKED TO HEAR FROM THIS SITE.\n *\n * `docs/specs/email-competitive-gaps.md` G10 shipped its cap half and left\n * this one: unsubscribe was all-or-nothing plus, since topics, per-stream —\n * and a recipient who wanted the same mail LESS OFTEN still had only two\n * levers, one of which is the spam button. On a shared sending domain under\n * `p=reject` that button is charged to every other tenant, which is what\n * makes \"monthly\" a platform control wearing a courtesy's clothes.\n *\n * ## A minimum interval, not a second rolling window\n *\n * {@link marketingFrequencyVerdict} counts messages inside a day because the\n * thing it guards against is a burst. This guards against a DRIP, and the\n * question a drip asks is \"how long since the last one\" — one stored instant,\n * not a window that would have to be kept for a month to answer a monthly\n * choice. Two instruments, because they are two different questions.\n *\n * ## New values, so the vocabulary is chosen rather than inherited\n *\n * `'all'` is the default and the absence: a record with no cadence, and every\n * record written before this existed, means the person has expressed no\n * preference — which is not the same as having asked for everything, but is\n * the only reading that does not silently withhold mail from people who never\n * chose.\n */\nexport type MarketingCadence = 'all' | 'daily' | 'weekly' | 'monthly'\n\n/** The default: no expressed preference, so only the platform ceiling binds. */\nexport const DEFAULT_MARKETING_CADENCE: MarketingCadence = 'all'\n\n/**\n * The minimum gap each choice asks for, in millis.\n *\n * Calendar-naive on purpose. \"At most one a week\" is a promise about pace,\n * and honoring it as seven days from the last message is both what the words\n * say and what a recipient can check; anchoring it to a calendar week would\n * let two messages land on a Sunday and a Monday and still be \"one a week\".\n */\nexport const MARKETING_CADENCE_INTERVAL_MS: Record<MarketingCadence, number> = {\n  all: 0,\n  daily: 86_400_000,\n  weekly: 7 * 86_400_000,\n  monthly: 30 * 86_400_000,\n}\n\n/** How each choice reads, wherever one is named to a person or an operator. */\nexport const MARKETING_CADENCE_LABELS: Record<MarketingCadence, string> = {\n  all: 'As they come',\n  daily: 'At most one a day',\n  weekly: 'At most one a week',\n  monthly: 'At most one a month',\n}\n\n/**\n * Coerces a stored or submitted value to a cadence.\n *\n * Everything unrecognized becomes {@link DEFAULT_MARKETING_CADENCE}. The\n * direction matters and is the opposite of the consent policy's: a malformed\n * consent value must not become a way to switch enforcement off, because its\n * failure mode is mail to somebody who declined. A malformed cadence falling\n * to `'monthly'` would withhold mail from everybody whose record got\n * corrupted, and nobody asked for that either — so an unreadable preference\n * reads as no preference, and the person keeps whatever the ceiling allows.\n */\nexport function normalizeMarketingCadence(value: unknown): MarketingCadence {\n  return value === 'daily' || value === 'weekly' || value === 'monthly'\n    ? value\n    : DEFAULT_MARKETING_CADENCE\n}\n\n/**\n * Whether enough time has passed for one more message at this pace.\n *\n * Pure, so the rule can be asserted without a Firestore harness — the same\n * split {@link marketingFrequencyVerdict} makes.\n *\n * @param lastSentAtMs when this site last sent this person marketing mail, or\n *        `null` for somebody it has never mailed. Never mailed always allows:\n *        a cadence is a gap between messages and there is no first gap.\n * @returns the verdict and, on a refusal, the instant the next message may go\n *          — so a caller that defers has something to defer UNTIL rather than\n *          a retry loop that discovers the answer by asking again.\n */\nexport function marketingCadenceVerdict(\n  cadence: MarketingCadence,\n  lastSentAtMs: number | null | undefined,\n  nowMs: number,\n): { allowed: boolean; cadence: MarketingCadence; nextAllowedAtMs: number } {\n  const interval = MARKETING_CADENCE_INTERVAL_MS[cadence] ?? 0\n  const last = Number(lastSentAtMs)\n  if (!interval || !Number.isFinite(last) || last <= 0) {\n    return { allowed: true, cadence, nextAllowedAtMs: nowMs }\n  }\n  const nextAllowedAtMs = last + interval\n  /*\n   * A stored instant in the FUTURE allows rather than refusing until it\n   * passes. Clocks disagree across processes and a record written a few\n   * seconds ahead would otherwise hold a recipient's mail for a whole\n   * interval, which is a much larger error than the one it would prevent.\n   */\n  if (last > nowMs) return { allowed: true, cadence, nextAllowedAtMs: nowMs }\n  return { allowed: nowMs >= nextAllowedAtMs, cadence, nextAllowedAtMs }\n}\n\n/**\n * The RFC 8058 header pair.\n *\n * Both or neither: `List-Unsubscribe` alone does not satisfy the bulk-sender\n * rules, and `List-Unsubscribe-Post` without a URL to post to advertises a\n * verb nothing serves.\n */\nexport function unsubscribeHeaders(\n  unsubscribeUrl: string,\n): Record<string, string> {\n  if (!unsubscribeUrl) return {}\n  return {\n    'List-Unsubscribe': `<${unsubscribeUrl}>`,\n    'List-Unsubscribe-Post': 'List-Unsubscribe=One-Click',\n  }\n}\n\n/**\n * What the visible opt-out is CALLED, in every part of every message.\n *\n * The link opens the preference page, where leaving one stream is a choice\n * alongside leaving all of them — and a footer that says only \"Unsubscribe\"\n * is the only place a recipient would have learned that, so it never gets\n * said. The word \"unsubscribe\" stays in the line because that is what a\n * recipient scans a footer for.\n *\n * Named once and shared with `renderRecipientEmail`, which writes this same\n * line into a campaign's text part: two spellings of one sentence is how the\n * idempotency checks below come to append a second footer to a message that\n * already had one.\n */\nexport const UNSUBSCRIBE_FOOTER_LABEL =\n  'Choose which emails you get, or unsubscribe'\n\n/**\n * The visible opt-out, appended to the plain-text part.\n *\n * The headers are for the mailbox provider; this is for the person. CAN-SPAM\n * asks for a mechanism the recipient can see and use, and a header is neither\n * — most clients render no control for it at all unless the sender's domain\n * reputation is high enough for the provider to offer one.\n *\n * Idempotent by URL: a body that already carries the link is returned\n * untouched, so a sender that writes its own footer does not get two.\n */\nexport function appendUnsubscribeText(\n  text: string,\n  unsubscribeUrl: string,\n): string {\n  if (!unsubscribeUrl || (text && text.includes(unsubscribeUrl))) return text\n  return `${text ?? ''}\\n\\n—\\n${UNSUBSCRIBE_FOOTER_LABEL}: ${unsubscribeUrl}`\n}\n\n/**\n * The same visible opt-out for the HTML part.\n *\n * Appended to whatever the sender produced rather than woven into it, because\n * the HTML may be a merchant-designed template this module knows nothing\n * about. A designed template that already renders `{{unsubscribeUrl}}`\n * carries the URL, so the check below leaves it alone and the merchant's own\n * placement wins.\n *\n * ⚠️ That check has to look for the ESCAPED URL as well. A signed opt-out\n * link carries `&` between its query parameters, and a renderer putting it\n * into an `href` escapes it — so `renderEmailHtml` emits `…&amp;sig=…` and a\n * plain `includes` of the unescaped URL matches nothing. Every designed\n * template in the product goes through that renderer, which means the\n * merchants who DID place the token were the ones getting two footers.\n *\n * Styles are inline and literal because this is email HTML: mail clients\n * strip `<style>` blocks and support no CSS variables, so a theme token\n * cannot reach the wire.\n */\nexport function appendUnsubscribeHtml(\n  html: string,\n  unsubscribeUrl: string,\n): string {\n  if (!unsubscribeUrl) return html\n  if (\n    html &&\n    (html.includes(unsubscribeUrl) ||\n      html.includes(escapeEmailHtml(unsubscribeUrl)))\n  ) {\n    return html\n  }\n  const footer =\n    '<div style=\"margin:24px auto 0;max-width:600px;padding:16px 24px;' +\n    \"font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,\" +\n    'Helvetica,Arial,sans-serif;font-size:12px;line-height:1.5;' +\n    'color:#616161;text-align:center\">' +\n    `<a href=\"${escapeEmailHtml(unsubscribeUrl)}\" style=\"color:#616161\">` +\n    `${UNSUBSCRIBE_FOOTER_LABEL}</a>` +\n    '</div>'\n  return `${html ?? ''}${footer}`\n}\n"],"names":["escapeEmailHtml","resolveSendPriority","isMarketingMessage","options","marketing","context","undefined","priority","installedGate","setMarketingSendGate","gate","getMarketingSendGate","resetMarketingSendGateForTests","MARKETING_FREQUENCY_WINDOW_MS","MARKETING_FREQUENCY_DEFAULT_PER_WINDOW","MARKETING_FREQUENCY_MIN_PER_WINDOW","MARKETING_FREQUENCY_MAX_PER_WINDOW","marketingFrequencyCap","raw","Number","process","env","AGLYN_EMAIL_MARKETING_CAP_PER_DAY","isFinite","whole","Math","floor","marketingFrequencyVerdict","recentSendsAtMs","nowMs","cap","inWindow","filter","at","sort","a","b","slice","max","allowed","length","used","MARKETING_SUNSET_MIN_DAYS","MARKETING_SUNSET_MAX_DAYS","marketingSunsetDays","AGLYN_EMAIL_SUNSET_AFTER_DAYS","marketingSunsetVerdict","facts","days","quietForDays","first","firstSentAtMs","engaged","lastEngagedAtMs","since","DEFAULT_MARKETING_CADENCE","MARKETING_CADENCE_INTERVAL_MS","all","daily","weekly","monthly","MARKETING_CADENCE_LABELS","normalizeMarketingCadence","value","marketingCadenceVerdict","cadence","lastSentAtMs","interval","last","nextAllowedAtMs","unsubscribeHeaders","unsubscribeUrl","UNSUBSCRIBE_FOOTER_LABEL","appendUnsubscribeText","text","includes","appendUnsubscribeHtml","html","footer"],"mappings":"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"}