@aglyn/plugins-outreach 1.0.0-beta.220 → 1.0.0-beta.222

package/src/lib/engine/open-source.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/outreach/src/lib/engine/open-source.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\nimport { outreachIpBlock, outreachIpInBlocks, type OutreachIpBlock } from './ip-range'\n\n/*==========================================\n * WHOSE NETWORK A FETCH OF THE TRACKING IMAGE CAME FROM (AGL-3488).\n *\n * A coarse hint, read from the fetch's address and stored on the open's\n * history row in place of the address itself: the address of a person\n * reading at home is theirs, and the only thing the judgement needs from it\n * is whether it is one of the few networks that fetch mail images on a\n * provider's behalf.\n *\n * The blocks are the published ones, collapsed to their aggregates and\n * checked on 2026-10-02:\n *\n * - **Google** — Google's own space from `gstatic.com/ipranges/goog.json`,\n *   none of it Google Cloud customer space (`cloud.json`): Gmail's image\n *   proxy and Google's mail scanning fetch from here, a stranger's VM on\n *   GCP does not.\n * - **Microsoft's mail filter** — Exchange Online Protection\n *   (`*.protection.outlook.com`, `*.mail.protection.outlook.com`) from the\n *   Microsoft 365 endpoints service: the filter every Microsoft 365 message\n *   passes through, and nothing a person reads mail on.\n * - **Microsoft** — the rest of Exchange Online (`outlook.office.com`,\n *   `outlook.office365.com`). Outlook on the web loads a message's images\n *   through Microsoft's servers when the reader opens it, so this is not a\n *   scanner by itself.\n * - **Apple** — `17.0.0.0/8`, and the relay egress Apple publishes in\n *   `mask-api.icloud.com/egress-ip-ranges.csv`, through which Mail Privacy\n *   Protection fetches: the Akamai, Cloudflare and Fastly blocks it\n *   collapses to.\n * - **Yahoo** — the ranges its mail proxy page lists\n *   (`senders.yahooinc.com/mail-proxy-servers`).\n *\n * A range that moves later costs a hint, never an image: every fetch is\n * answered the same either way.\n *==========================================*/\n\n/** The networks a fetch is told apart by; `other` is every address that is none of them. */\nexport type OutreachOpenSource = 'google' | 'microsoft_filter' | 'microsoft' | 'apple' | 'yahoo' | 'other'\n\nexport const OUTREACH_OPEN_SOURCES: readonly OutreachOpenSource[] = [\n  'google',\n  'microsoft_filter',\n  'microsoft',\n  'apple',\n  'yahoo',\n  'other',\n]\n\nconst blocks = (cidrs: readonly string[]): OutreachIpBlock[] => cidrs.map(outreachIpBlock)\n\nconst GOOGLE = blocks([\n  '64.233.160.0/19',\n  '66.102.0.0/20',\n  '66.249.64.0/19',\n  '72.14.192.0/18',\n  '74.125.0.0/16',\n  '108.170.192.0/18',\n  '108.177.0.0/17',\n  '142.250.0.0/15',\n  '172.217.0.0/16',\n  '172.253.0.0/16',\n  '173.194.0.0/16',\n  '209.85.128.0/17',\n  '216.58.192.0/19',\n  '216.239.32.0/19',\n  '2001:4860::/32',\n  '2404:6800::/32',\n  '2a00:1450::/32',\n])\n\nconst MICROSOFT_FILTER = blocks([\n  '40.92.0.0/15',\n  '40.107.0.0/16',\n  '52.100.0.0/14',\n  '104.47.0.0/17',\n  '2a01:111:f400::/48',\n  '2a01:111:f403::/48',\n])\n\nconst MICROSOFT = blocks([\n  '13.107.128.0/22',\n  '23.103.160.0/20',\n  '40.96.0.0/13',\n  '40.104.0.0/15',\n  '52.96.0.0/14',\n  '132.245.0.0/16',\n  '150.171.32.0/22',\n  '2603:1000::/24',\n  '2620:1ec:8f0::/46',\n  '2620:1ec:900::/46',\n])\n\nconst APPLE = blocks([\n  '17.0.0.0/8',\n  '104.28.0.0/16',\n  '140.248.0.0/16',\n  '146.75.0.0/16',\n  '172.224.0.0/15',\n  '172.226.0.0/16',\n  '2606:54c0::/32',\n  '2606:54c3::/32',\n  '2a02:26f7::/32',\n  '2a04:4e41::/32',\n  '2a09:bac2::/31',\n])\n\nconst YAHOO = blocks([\n  '27.123.32.0/19',\n  '67.195.0.0/16',\n  '69.147.64.0/18',\n  '87.248.96.0/19',\n  '98.138.0.0/15',\n  '106.10.128.0/17',\n  '115.178.0.0/20',\n  '119.161.0.0/19',\n  '200.152.160.0/20',\n  '202.43.192.0/19',\n  '209.73.160.0/19',\n  '212.82.96.0/19',\n  '216.115.96.0/20',\n  '2001:4998::/32',\n  '2406:2000::/32',\n  '2406:6e00::/32',\n  '2804:1bc::/32',\n  '2a00:1288::/32',\n])\n\n/** Checked in this order; the filter before the rest of Microsoft, which does not contain it. */\nconst SOURCES: ReadonlyArray<[OutreachOpenSource, readonly OutreachIpBlock[]]> = [\n  ['google', GOOGLE],\n  ['microsoft_filter', MICROSOFT_FILTER],\n  ['microsoft', MICROSOFT],\n  ['apple', APPLE],\n  ['yahoo', YAHOO],\n]\n\n/**\n * The network a fetch came from, or `null` when no address could be read —\n * which is \"unknown\", a different answer from `other`.\n */\nexport function outreachOpenSourceOf(address: string | null | undefined): OutreachOpenSource | null {\n  const text = String(address ?? '').trim()\n  if (!text) return null\n  for (const [source, ranges] of SOURCES) if (outreachIpInBlocks(text, ranges)) return source\n  return 'other'\n}\n"],"names":["outreachIpBlock","outreachIpInBlocks","OUTREACH_OPEN_SOURCES","blocks","cidrs","map","GOOGLE","MICROSOFT_FILTER","MICROSOFT","APPLE","YAHOO","SOURCES","outreachOpenSourceOf","address","text","String","trim","source","ranges"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED,SAASA,eAAe,EAAEC,kBAAkB,QAA8B,gBAAY;AAwCtF,OAAO,MAAMC,wBAAuD;IAClE;IACA;IACA;IACA;IACA;IACA;CACD,CAAA;AAED,MAAMC,SAAS,CAACC,QAAgDA,MAAMC,GAAG,CAACL;AAE1E,MAAMM,SAASH,OAAO;IACpB;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;CACD;AAED,MAAMI,mBAAmBJ,OAAO;IAC9B;IACA;IACA;IACA;IACA;IACA;CACD;AAED,MAAMK,YAAYL,OAAO;IACvB;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;CACD;AAED,MAAMM,QAAQN,OAAO;IACnB;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;CACD;AAED,MAAMO,QAAQP,OAAO;IACnB;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;CACD;AAED,+FAA+F,GAC/F,MAAMQ,UAA2E;IAC/E;QAAC;QAAUL;KAAO;IAClB;QAAC;QAAoBC;KAAiB;IACtC;QAAC;QAAaC;KAAU;IACxB;QAAC;QAASC;KAAM;IAChB;QAAC;QAASC;KAAM;CACjB;AAED;;;CAGC,GACD,OAAO,SAASE,qBAAqBC,OAAkC;IACrE,MAAMC,OAAOC,OAAOF,kBAAAA,UAAW,IAAIG,IAAI;IACvC,IAAI,CAACF,MAAM,OAAO;IAClB,KAAK,MAAM,CAACG,QAAQC,OAAO,IAAIP,QAAS,IAAIV,mBAAmBa,MAAMI,SAAS,OAAOD;IACrF,OAAO;AACT"}

package/src/lib/engine/open-tracking.d.ts

@@ -14,6 +14,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+import type { OutreachOpenSource } from './open-source';
 /** Text safe to place in HTML content or a double-quoted attribute. */
 export declare function escapeOutreachHtml(value: string): string;
 /**
@@ -34,8 +35,14 @@ export declare function outreachOpenTrackedHtml(text: string, pixelUrl: string):
  * email does not.
  */
 export declare const OUTREACH_OPEN_HUMAN_DELAY_MS = 30000;
-/** Why an open was read as a machine's. */
-export type OutreachOpenMachineReason = 'agent' | 'too_soon' | 'method' | 'image_proxy' | 'privacy_proxy';
+/** The longest agent kept on a history row: evidence, not a store for whatever a caller sends. */
+export declare const OUTREACH_OPEN_AGENT_MAX = 400;
+/**
+ * Why an open was read as a machine's. `scanner` (AGL-3488) is a mail
+ * provider's or a security product's fetch, known by where it came from;
+ * `agent` is one known by what it called itself.
+ */
+export type OutreachOpenMachineReason = 'agent' | 'too_soon' | 'method' | 'image_proxy' | 'privacy_proxy' | 'scanner';
 /** The reasons that are a mail provider's proxy rather than a scanner. */
 export declare const OUTREACH_PROXY_OPEN_REASONS: readonly OutreachOpenMachineReason[];
 /** What one fetch of a tracking image was. */
@@ -45,6 +52,8 @@ export interface OutreachOpenJudgement {
     /** Why it does not; `null` when it does. */
     machineReason: OutreachOpenMachineReason | null;
 }
+/** The agent as a history row keeps it: trimmed, on one line, and no longer than {@link OUTREACH_OPEN_AGENT_MAX}. */
+export declare function outreachOpenAgentEvidence(userAgent: string | null | undefined): string | null;
 /**
  * Whether one fetch of a tracking image is a person's open.
  *
@@ -53,9 +62,13 @@ export interface OutreachOpenJudgement {
  *
  * @param input.sinceSentMs Milliseconds between the send and this fetch, or
  *   `null` when the send it belongs to could not be found.
+ * @param input.source The network the fetch came from (`./open-source.ts`),
+ *   or `null` when no address was read — judged then by the agent alone,
+ *   as every fetch was before AGL-3488.
  */
 export declare function judgeOutreachOpen(input: {
     method: string;
     userAgent: string | null | undefined;
     sinceSentMs: number | null;
+    source?: OutreachOpenSource | null;
 }): OutreachOpenJudgement;

package/src/lib/engine/open-tracking.js

@@ -84,23 +84,37 @@
  * WHO OPENED: A PERSON, OR A MACHINE.
  *
  * The same judgement scanner clicks get (`./click-tracking.ts`), with the
- * machines that fetch images rather than links:
+ * machines that fetch images rather than links — told apart by what a fetch
+ * says it is AND where it came from (AGL-3488), because the agent alone
+ * cannot separate them:
  *
  * - **Apple Mail Privacy Protection** fetches every remote image of every
- *   message through Apple's proxy when the message arrives, whether or not
- *   anyone reads it. Its fetch names itself only as `Mozilla/5.0`.
+ *   message as it arrives, whether or not anyone reads it, naming itself
+ *   only as `Mozilla/5.0` — and from Apple's relay egress, never from
+ *   Google's or Microsoft's mail servers. The bare agent from anywhere else
+ *   is a scanner borrowing it, and is called one: a sequence mailing
+ *   Google Workspace addresses once read 128 such fetches as Apple's.
+ * - **Gmail's `GoogleImageProxy`** is NOT a machine here. Gmail fetches
+ *   through it when the reader opens the message, so outside the delivery
+ *   window its fetch is the reader's open, and setting it apart would leave
+ *   the rate blind to every Gmail and Workspace reader. The proxy caches the
+ *   image, so a reader's later opens may not arrive at all; the rate is
+ *   taken over first opens per person either way. Gmail's PREFETCH, which
+ *   fetches on delivery for some signed-in recipients, names a 2015 Edge
+ *   instead — no reader's browser — and is a scanner.
+ * - **Google's and Microsoft's mail scanning** fetches from their mail
+ *   networks with whatever agent it likes. Anything from Google's own
+ *   network that is not the image proxy is a scanner, and so is anything
+ *   from Exchange Online Protection, Microsoft's mail filter. The rest of
+ *   Microsoft's mail network is NOT judged by itself: Outlook on the web
+ *   loads images through it when the reader opens the message.
  * - **Yahoo's image proxy** fetches on the provider's behalf, and is set
  *   apart as a proxy.
+ * - **Gateways and scanners** that name themselves as the click scanners
+ *   do, or that arrive within seconds of delivery.
  *
- * Gmail's `GoogleImageProxy` is NOT a machine here. Gmail fetches through it
- * only when the reader opens the message — it does not prefetch on delivery
- * — so outside the delivery window its fetch is the reader's open, and
- * setting it apart would leave the rate blind to every Gmail and Workspace
- * reader. The proxy caches the image, so a reader's later opens may not
- * arrive at all; the rate is taken over first opens per person either way.
- * - **Gateways and scanners** that open the message to inspect it, which
- *   name themselves as the click scanners do, or arrive within seconds of
- *   delivery.
+ * Every fetch's agent and network are kept on its history row, so a
+ * judgement can be checked against what actually arrived.
  *
  * Counted apart, never dropped: `machineOpens` beside `opens`, as
  * `machineClicks` beside `clicks`.
@@ -121,15 +135,31 @@
     'googleimageproxy',
     'ggpht.com'
 ];
+/**
+ * Gmail's prefetch: Chrome 42 and Edge 12 in one agent, both from 2015,
+ * matched together so neither browser alone is ever read as a machine.
+ */ const GMAIL_PREFETCH_AGENT_PARTS = [
+    'chrome/42.0.2311.135',
+    'edge/12.246'
+];
 /**
  * The agent Apple's Mail Privacy Protection proxy sends: the bare product
  * token, with no platform after it — which no browser or mail client that
  * shows an image to a person sends.
- */ const APPLE_PRIVACY_AGENT = 'mozilla/5.0';
+ */ const BARE_AGENT = 'mozilla/5.0';
+/** The longest agent kept on a history row: evidence, not a store for whatever a caller sends. */ export const OUTREACH_OPEN_AGENT_MAX = 400;
 /** The reasons that are a mail provider's proxy rather than a scanner. */ export const OUTREACH_PROXY_OPEN_REASONS = [
     'image_proxy',
     'privacy_proxy'
 ];
+/** The agent as a history row keeps it: trimmed, on one line, and no longer than {@link OUTREACH_OPEN_AGENT_MAX}. */ export function outreachOpenAgentEvidence(userAgent) {
+    // Every control character, a line break included, read as a space.
+    const agent = Array.from(String(userAgent != null ? userAgent : ''), (character)=>{
+        const code = character.charCodeAt(0);
+        return code < 0x20 || code === 0x7f ? ' ' : character;
+    }).join('').replace(/ {2,}/g, ' ').trim();
+    return agent ? agent.slice(0, OUTREACH_OPEN_AGENT_MAX) : null;
+}
 /**
  * Whether one fetch of a tracking image is a person's open.
  *
@@ -138,19 +168,32 @@
  *
  * @param input.sinceSentMs Milliseconds between the send and this fetch, or
  *   `null` when the send it belongs to could not be found.
+ * @param input.source The network the fetch came from (`./open-source.ts`),
+ *   or `null` when no address was read — judged then by the agent alone,
+ *   as every fetch was before AGL-3488.
  */ export function judgeOutreachOpen(input) {
-    var _input_method, _input_userAgent;
+    var _input_source, _input_method, _input_userAgent;
     const machine = (machineReason)=>({
             human: false,
             machineReason
         });
+    const source = (_input_source = input.source) != null ? _input_source : null;
     if (String((_input_method = input.method) != null ? _input_method : '').toUpperCase() === 'HEAD') return machine('method');
     const agent = String((_input_userAgent = input.userAgent) != null ? _input_userAgent : '').trim().toLowerCase();
     if (!agent) return machine('agent');
-    if (IMAGE_PROXY_AGENTS.some((needle)=>agent.includes(needle))) return machine('image_proxy');
-    if (agent === APPLE_PRIVACY_AGENT) return machine('privacy_proxy');
+    if (source === 'yahoo' || IMAGE_PROXY_AGENTS.some((needle)=>agent.includes(needle))) return machine('image_proxy');
+    if (agent === BARE_AGENT) {
+        // Apple's agent from Apple's relay — or from nowhere we could read,
+        // which is how every such fetch was judged before the address was.
+        return machine(source === null || source === 'apple' ? 'privacy_proxy' : 'scanner');
+    }
+    if (GMAIL_PREFETCH_AGENT_PARTS.every((part)=>agent.includes(part))) return machine('scanner');
     const gmail = GMAIL_PROXY_AGENTS.some((needle)=>agent.includes(needle));
+    // Gmail's proxy fetches from Google's network; the same words from any
+    // other network that could be read are someone else's.
+    if (gmail && source !== null && source !== 'google') return machine('agent');
     if (!gmail && OUTREACH_MACHINE_AGENTS.some((needle)=>agent.includes(needle))) return machine('agent');
+    if (!gmail && (source === 'google' || source === 'microsoft_filter')) return machine('scanner');
     // A fetch before its send is two clocks disagreeing, and read as a person's.
     if (input.sinceSentMs !== null && input.sinceSentMs >= 0 && input.sinceSentMs < OUTREACH_OPEN_HUMAN_DELAY_MS) {
         return machine('too_soon');

package/src/lib/engine/open-tracking.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../../../../../libs/plugins/outreach/src/lib/engine/open-tracking.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\nimport { OUTREACH_MACHINE_AGENTS, outreachBodyLinks } from './click-tracking'\n\n/*==========================================\n * OPENS, WHEN A SEQUENCE ASKS FOR THEM (AGL-3395).\n *\n * A sequence email is plain text, and a plain-text email cannot report an\n * open: an open is a fetch of an image, and an image needs an HTML part\n * (`./click-tracking.ts` says why that is the default). A sequence that\n * turns on \"Count opens\" accepts the cost of one, for the sends it makes\n * from then on.\n *\n * ## What the HTML part is\n *\n * The plain-text part is sent exactly as it would have been. The HTML part\n * beside it is the SAME TEXT — escaped, its line breaks as `<br>`, its bare\n * links made into anchors to the same address — with a 1×1 image at the end.\n * No styling, no layout, no second copy of anything: a client that shows\n * the HTML part shows what the plain-text part says, in the reader's own\n * font, and the image is the only thing the text does not carry.\n *\n * The image is a short link (AGL-3297) on the same host the clicks use, so\n * the email names no address a click does not already name.\n *\n * ## What it costs\n *\n * A one-to-one email from a person has no HTML part; one with a remote\n * image reads, to a filter, as marketing. Some gateways score it. That is\n * why the setting is per sequence, off by default, and said in the editor\n * where it is turned on.\n *==========================================*/\n\n/** Every character HTML gives a meaning to, as the entity that does not. */\nconst HTML_ESCAPES: Record<string, string> = {\n  '&': '&amp;',\n  '<': '&lt;',\n  '>': '&gt;',\n  '\"': '&quot;',\n  \"'\": '&#39;',\n}\n\n/** Text safe to place in HTML content or a double-quoted attribute. */\nexport function escapeOutreachHtml(value: string): string {\n  return String(value ?? '').replace(/[&<>\"']/g, (character) => HTML_ESCAPES[character] ?? character)\n}\n\n/** One run of text, escaped, with its line breaks as `<br>`. */\nconst escapedLines = (text: string): string =>\n  escapeOutreachHtml(text).replace(/\\r\\n|\\r|\\n/g, '<br>\\n')\n\n/**\n * The HTML part for a plain-text email and its tracking image.\n *\n * @param text The plain-text body as it is sent, footer included — so the\n *   HTML part carries the organization's identification and the way out\n *   word for word, and any link click tracking already rewrote stays the\n *   rewritten link.\n * @param pixelUrl The image's address. Written into a quoted attribute\n *   after escaping, so no value can close the attribute.\n */\nexport function outreachOpenTrackedHtml(text: string, pixelUrl: string): string {\n  const body = String(text ?? '')\n  let html = ''\n  let cursor = 0\n  // Linked by the same reader click tracking rewrites by, so a link the\n  // plain text offers is exactly a link the HTML offers.\n  for (const link of outreachBodyLinks(body)) {\n    html += escapedLines(body.slice(cursor, link.start))\n    const href = escapeOutreachHtml(link.url)\n    html += `<a href=\"${href}\">${href}</a>`\n    cursor = link.end\n  }\n  html += escapedLines(body.slice(cursor))\n  const src = escapeOutreachHtml(pixelUrl)\n  return (\n    '<!DOCTYPE html>\\n<html>\\n<head><meta charset=\"utf-8\"></head>\\n<body>\\n' +\n    `<div dir=\"auto\">${html}</div>\\n` +\n    `<img src=\"${src}\" width=\"1\" height=\"1\" alt=\"\" style=\"display:block;width:1px;height:1px;border:0\">\\n` +\n    '</body>\\n</html>\\n'\n  )\n}\n\n/*==========================================\n * WHO OPENED: A PERSON, OR A MACHINE.\n *\n * The same judgement scanner clicks get (`./click-tracking.ts`), with the\n * machines that fetch images rather than links:\n *\n * - **Apple Mail Privacy Protection** fetches every remote image of every\n *   message through Apple's proxy when the message arrives, whether or not\n *   anyone reads it. Its fetch names itself only as `Mozilla/5.0`.\n * - **Yahoo's image proxy** fetches on the provider's behalf, and is set\n *   apart as a proxy.\n *\n * Gmail's `GoogleImageProxy` is NOT a machine here. Gmail fetches through it\n * only when the reader opens the message — it does not prefetch on delivery\n * — so outside the delivery window its fetch is the reader's open, and\n * setting it apart would leave the rate blind to every Gmail and Workspace\n * reader. The proxy caches the image, so a reader's later opens may not\n * arrive at all; the rate is taken over first opens per person either way.\n * - **Gateways and scanners** that open the message to inspect it, which\n *   name themselves as the click scanners do, or arrive within seconds of\n *   delivery.\n *\n * Counted apart, never dropped: `machineOpens` beside `opens`, as\n * `machineClicks` beside `clicks`.\n *==========================================*/\n\n/**\n * How soon after a send an open is a machine's however it identifies\n * itself — the click window's reasoning, for the same reason: a proxy or a\n * gateway fetches as the message is delivered, and a person reading a cold\n * email does not.\n */\nexport const OUTREACH_OPEN_HUMAN_DELAY_MS = 30_000\n\n/** Image proxies that fetch on a mail provider's behalf, matched as substrings of the agent. */\nconst IMAGE_PROXY_AGENTS = ['yahoomailproxy']\n\n/**\n * Gmail's image proxy, which fetches when the reader opens the message and\n * so counts as their open — see the note above. It names itself in an agent\n * the scanner list would otherwise match (`googleimageproxy`).\n */\nconst GMAIL_PROXY_AGENTS = ['googleimageproxy', 'ggpht.com']\n\n/**\n * The agent Apple's Mail Privacy Protection proxy sends: the bare product\n * token, with no platform after it — which no browser or mail client that\n * shows an image to a person sends.\n */\nconst APPLE_PRIVACY_AGENT = 'mozilla/5.0'\n\n/** Why an open was read as a machine's. */\nexport type OutreachOpenMachineReason = 'agent' | 'too_soon' | 'method' | 'image_proxy' | 'privacy_proxy'\n\n/** The reasons that are a mail provider's proxy rather than a scanner. */\nexport const OUTREACH_PROXY_OPEN_REASONS: readonly OutreachOpenMachineReason[] = ['image_proxy', 'privacy_proxy']\n\n/** What one fetch of a tracking image was. */\nexport interface OutreachOpenJudgement {\n  /** Whether it counts toward the open rate. */\n  human: boolean\n  /** Why it does not; `null` when it does. */\n  machineReason: OutreachOpenMachineReason | null\n}\n\n/**\n * Whether one fetch of a tracking image is a person's open.\n *\n * Read before the open is recorded, never before the image is answered:\n * every fetch gets the same image.\n *\n * @param input.sinceSentMs Milliseconds between the send and this fetch, or\n *   `null` when the send it belongs to could not be found.\n */\nexport function judgeOutreachOpen(input: {\n  method: string\n  userAgent: string | null | undefined\n  sinceSentMs: number | null\n}): OutreachOpenJudgement {\n  const machine = (machineReason: OutreachOpenMachineReason): OutreachOpenJudgement => ({\n    human: false,\n    machineReason,\n  })\n  if (String(input.method ?? '').toUpperCase() === 'HEAD') return machine('method')\n  const agent = String(input.userAgent ?? '').trim().toLowerCase()\n  if (!agent) return machine('agent')\n  if (IMAGE_PROXY_AGENTS.some((needle) => agent.includes(needle))) return machine('image_proxy')\n  if (agent === APPLE_PRIVACY_AGENT) return machine('privacy_proxy')\n  const gmail = GMAIL_PROXY_AGENTS.some((needle) => agent.includes(needle))\n  if (!gmail && OUTREACH_MACHINE_AGENTS.some((needle) => agent.includes(needle))) return machine('agent')\n  // A fetch before its send is two clocks disagreeing, and read as a person's.\n  if (input.sinceSentMs !== null && input.sinceSentMs >= 0 && input.sinceSentMs < OUTREACH_OPEN_HUMAN_DELAY_MS) {\n    return machine('too_soon')\n  }\n  return { human: true, machineReason: null }\n}\n"],"names":["OUTREACH_MACHINE_AGENTS","outreachBodyLinks","HTML_ESCAPES","escapeOutreachHtml","value","String","replace","character","escapedLines","text","outreachOpenTrackedHtml","pixelUrl","body","html","cursor","link","slice","start","href","url","end","src","OUTREACH_OPEN_HUMAN_DELAY_MS","IMAGE_PROXY_AGENTS","GMAIL_PROXY_AGENTS","APPLE_PRIVACY_AGENT","OUTREACH_PROXY_OPEN_REASONS","judgeOutreachOpen","input","machine","machineReason","human","method","toUpperCase","agent","userAgent","trim","toLowerCase","some","needle","includes","gmail","sinceSentMs"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED,SAASA,uBAAuB,EAAEC,iBAAiB,QAAQ,sBAAkB;AAE7E;;;;;;;;;;;;;;;;;;;;;;;;;;;4CA2B4C,GAE5C,0EAA0E,GAC1E,MAAMC,eAAuC;IAC3C,KAAK;IACL,KAAK;IACL,KAAK;IACL,KAAK;IACL,KAAK;AACP;AAEA,qEAAqE,GACrE,OAAO,SAASC,mBAAmBC,KAAa;IAC9C,OAAOC,OAAOD,gBAAAA,QAAS,IAAIE,OAAO,CAAC,YAAY,CAACC;YAAcL;gBAAAA,0BAAAA,YAAY,CAACK,UAAU,YAAvBL,0BAA2BK;;AAC3F;AAEA,8DAA8D,GAC9D,MAAMC,eAAe,CAACC,OACpBN,mBAAmBM,MAAMH,OAAO,CAAC,eAAe;AAElD;;;;;;;;;CASC,GACD,OAAO,SAASI,wBAAwBD,IAAY,EAAEE,QAAgB;IACpE,MAAMC,OAAOP,OAAOI,eAAAA,OAAQ;IAC5B,IAAII,OAAO;IACX,IAAIC,SAAS;IACb,sEAAsE;IACtE,uDAAuD;IACvD,KAAK,MAAMC,QAAQd,kBAAkBW,MAAO;QAC1CC,QAAQL,aAAaI,KAAKI,KAAK,CAACF,QAAQC,KAAKE,KAAK;QAClD,MAAMC,OAAOf,mBAAmBY,KAAKI,GAAG;QACxCN,QAAQ,CAAC,SAAS,EAAEK,KAAK,EAAE,EAAEA,KAAK,IAAI,CAAC;QACvCJ,SAASC,KAAKK,GAAG;IACnB;IACAP,QAAQL,aAAaI,KAAKI,KAAK,CAACF;IAChC,MAAMO,MAAMlB,mBAAmBQ;IAC/B,OACE,2EACA,CAAC,gBAAgB,EAAEE,KAAK,QAAQ,CAAC,GACjC,CAAC,UAAU,EAAEQ,IAAI,oFAAoF,CAAC,GACtG;AAEJ;AAEA;;;;;;;;;;;;;;;;;;;;;;;;4CAwB4C,GAE5C;;;;;CAKC,GACD,OAAO,MAAMC,+BAA+B,MAAM;AAElD,8FAA8F,GAC9F,MAAMC,qBAAqB;IAAC;CAAiB;AAE7C;;;;CAIC,GACD,MAAMC,qBAAqB;IAAC;IAAoB;CAAY;AAE5D;;;;CAIC,GACD,MAAMC,sBAAsB;AAK5B,wEAAwE,GACxE,OAAO,MAAMC,8BAAoE;IAAC;IAAe;CAAgB,CAAA;AAUjH;;;;;;;;CAQC,GACD,OAAO,SAASC,kBAAkBC,KAIjC;QAKYA,eACUA;IALrB,MAAMC,UAAU,CAACC,gBAAqE,CAAA;YACpFC,OAAO;YACPD;QACF,CAAA;IACA,IAAIzB,QAAOuB,gBAAAA,MAAMI,MAAM,YAAZJ,gBAAgB,IAAIK,WAAW,OAAO,QAAQ,OAAOJ,QAAQ;IACxE,MAAMK,QAAQ7B,QAAOuB,mBAAAA,MAAMO,SAAS,YAAfP,mBAAmB,IAAIQ,IAAI,GAAGC,WAAW;IAC9D,IAAI,CAACH,OAAO,OAAOL,QAAQ;IAC3B,IAAIN,mBAAmBe,IAAI,CAAC,CAACC,SAAWL,MAAMM,QAAQ,CAACD,UAAU,OAAOV,QAAQ;IAChF,IAAIK,UAAUT,qBAAqB,OAAOI,QAAQ;IAClD,MAAMY,QAAQjB,mBAAmBc,IAAI,CAAC,CAACC,SAAWL,MAAMM,QAAQ,CAACD;IACjE,IAAI,CAACE,SAASzC,wBAAwBsC,IAAI,CAAC,CAACC,SAAWL,MAAMM,QAAQ,CAACD,UAAU,OAAOV,QAAQ;IAC/F,6EAA6E;IAC7E,IAAID,MAAMc,WAAW,KAAK,QAAQd,MAAMc,WAAW,IAAI,KAAKd,MAAMc,WAAW,GAAGpB,8BAA8B;QAC5G,OAAOO,QAAQ;IACjB;IACA,OAAO;QAAEE,OAAO;QAAMD,eAAe;IAAK;AAC5C"}
+{"version":3,"sources":["../../../../../../../libs/plugins/outreach/src/lib/engine/open-tracking.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\nimport { OUTREACH_MACHINE_AGENTS, outreachBodyLinks } from './click-tracking'\nimport type { OutreachOpenSource } from './open-source'\n\n/*==========================================\n * OPENS, WHEN A SEQUENCE ASKS FOR THEM (AGL-3395).\n *\n * A sequence email is plain text, and a plain-text email cannot report an\n * open: an open is a fetch of an image, and an image needs an HTML part\n * (`./click-tracking.ts` says why that is the default). A sequence that\n * turns on \"Count opens\" accepts the cost of one, for the sends it makes\n * from then on.\n *\n * ## What the HTML part is\n *\n * The plain-text part is sent exactly as it would have been. The HTML part\n * beside it is the SAME TEXT — escaped, its line breaks as `<br>`, its bare\n * links made into anchors to the same address — with a 1×1 image at the end.\n * No styling, no layout, no second copy of anything: a client that shows\n * the HTML part shows what the plain-text part says, in the reader's own\n * font, and the image is the only thing the text does not carry.\n *\n * The image is a short link (AGL-3297) on the same host the clicks use, so\n * the email names no address a click does not already name.\n *\n * ## What it costs\n *\n * A one-to-one email from a person has no HTML part; one with a remote\n * image reads, to a filter, as marketing. Some gateways score it. That is\n * why the setting is per sequence, off by default, and said in the editor\n * where it is turned on.\n *==========================================*/\n\n/** Every character HTML gives a meaning to, as the entity that does not. */\nconst HTML_ESCAPES: Record<string, string> = {\n  '&': '&amp;',\n  '<': '&lt;',\n  '>': '&gt;',\n  '\"': '&quot;',\n  \"'\": '&#39;',\n}\n\n/** Text safe to place in HTML content or a double-quoted attribute. */\nexport function escapeOutreachHtml(value: string): string {\n  return String(value ?? '').replace(/[&<>\"']/g, (character) => HTML_ESCAPES[character] ?? character)\n}\n\n/** One run of text, escaped, with its line breaks as `<br>`. */\nconst escapedLines = (text: string): string =>\n  escapeOutreachHtml(text).replace(/\\r\\n|\\r|\\n/g, '<br>\\n')\n\n/**\n * The HTML part for a plain-text email and its tracking image.\n *\n * @param text The plain-text body as it is sent, footer included — so the\n *   HTML part carries the organization's identification and the way out\n *   word for word, and any link click tracking already rewrote stays the\n *   rewritten link.\n * @param pixelUrl The image's address. Written into a quoted attribute\n *   after escaping, so no value can close the attribute.\n */\nexport function outreachOpenTrackedHtml(text: string, pixelUrl: string): string {\n  const body = String(text ?? '')\n  let html = ''\n  let cursor = 0\n  // Linked by the same reader click tracking rewrites by, so a link the\n  // plain text offers is exactly a link the HTML offers.\n  for (const link of outreachBodyLinks(body)) {\n    html += escapedLines(body.slice(cursor, link.start))\n    const href = escapeOutreachHtml(link.url)\n    html += `<a href=\"${href}\">${href}</a>`\n    cursor = link.end\n  }\n  html += escapedLines(body.slice(cursor))\n  const src = escapeOutreachHtml(pixelUrl)\n  return (\n    '<!DOCTYPE html>\\n<html>\\n<head><meta charset=\"utf-8\"></head>\\n<body>\\n' +\n    `<div dir=\"auto\">${html}</div>\\n` +\n    `<img src=\"${src}\" width=\"1\" height=\"1\" alt=\"\" style=\"display:block;width:1px;height:1px;border:0\">\\n` +\n    '</body>\\n</html>\\n'\n  )\n}\n\n/*==========================================\n * WHO OPENED: A PERSON, OR A MACHINE.\n *\n * The same judgement scanner clicks get (`./click-tracking.ts`), with the\n * machines that fetch images rather than links — told apart by what a fetch\n * says it is AND where it came from (AGL-3488), because the agent alone\n * cannot separate them:\n *\n * - **Apple Mail Privacy Protection** fetches every remote image of every\n *   message as it arrives, whether or not anyone reads it, naming itself\n *   only as `Mozilla/5.0` — and from Apple's relay egress, never from\n *   Google's or Microsoft's mail servers. The bare agent from anywhere else\n *   is a scanner borrowing it, and is called one: a sequence mailing\n *   Google Workspace addresses once read 128 such fetches as Apple's.\n * - **Gmail's `GoogleImageProxy`** is NOT a machine here. Gmail fetches\n *   through it when the reader opens the message, so outside the delivery\n *   window its fetch is the reader's open, and setting it apart would leave\n *   the rate blind to every Gmail and Workspace reader. The proxy caches the\n *   image, so a reader's later opens may not arrive at all; the rate is\n *   taken over first opens per person either way. Gmail's PREFETCH, which\n *   fetches on delivery for some signed-in recipients, names a 2015 Edge\n *   instead — no reader's browser — and is a scanner.\n * - **Google's and Microsoft's mail scanning** fetches from their mail\n *   networks with whatever agent it likes. Anything from Google's own\n *   network that is not the image proxy is a scanner, and so is anything\n *   from Exchange Online Protection, Microsoft's mail filter. The rest of\n *   Microsoft's mail network is NOT judged by itself: Outlook on the web\n *   loads images through it when the reader opens the message.\n * - **Yahoo's image proxy** fetches on the provider's behalf, and is set\n *   apart as a proxy.\n * - **Gateways and scanners** that name themselves as the click scanners\n *   do, or that arrive within seconds of delivery.\n *\n * Every fetch's agent and network are kept on its history row, so a\n * judgement can be checked against what actually arrived.\n *\n * Counted apart, never dropped: `machineOpens` beside `opens`, as\n * `machineClicks` beside `clicks`.\n *==========================================*/\n\n/**\n * How soon after a send an open is a machine's however it identifies\n * itself — the click window's reasoning, for the same reason: a proxy or a\n * gateway fetches as the message is delivered, and a person reading a cold\n * email does not.\n */\nexport const OUTREACH_OPEN_HUMAN_DELAY_MS = 30_000\n\n/** Image proxies that fetch on a mail provider's behalf, matched as substrings of the agent. */\nconst IMAGE_PROXY_AGENTS = ['yahoomailproxy']\n\n/**\n * Gmail's image proxy, which fetches when the reader opens the message and\n * so counts as their open — see the note above. It names itself in an agent\n * the scanner list would otherwise match (`googleimageproxy`).\n */\nconst GMAIL_PROXY_AGENTS = ['googleimageproxy', 'ggpht.com']\n\n/**\n * Gmail's prefetch: Chrome 42 and Edge 12 in one agent, both from 2015,\n * matched together so neither browser alone is ever read as a machine.\n */\nconst GMAIL_PREFETCH_AGENT_PARTS = ['chrome/42.0.2311.135', 'edge/12.246']\n\n/**\n * The agent Apple's Mail Privacy Protection proxy sends: the bare product\n * token, with no platform after it — which no browser or mail client that\n * shows an image to a person sends.\n */\nconst BARE_AGENT = 'mozilla/5.0'\n\n/** The longest agent kept on a history row: evidence, not a store for whatever a caller sends. */\nexport const OUTREACH_OPEN_AGENT_MAX = 400\n\n/**\n * Why an open was read as a machine's. `scanner` (AGL-3488) is a mail\n * provider's or a security product's fetch, known by where it came from;\n * `agent` is one known by what it called itself.\n */\nexport type OutreachOpenMachineReason =\n  | 'agent'\n  | 'too_soon'\n  | 'method'\n  | 'image_proxy'\n  | 'privacy_proxy'\n  | 'scanner'\n\n/** The reasons that are a mail provider's proxy rather than a scanner. */\nexport const OUTREACH_PROXY_OPEN_REASONS: readonly OutreachOpenMachineReason[] = ['image_proxy', 'privacy_proxy']\n\n/** What one fetch of a tracking image was. */\nexport interface OutreachOpenJudgement {\n  /** Whether it counts toward the open rate. */\n  human: boolean\n  /** Why it does not; `null` when it does. */\n  machineReason: OutreachOpenMachineReason | null\n}\n\n/** The agent as a history row keeps it: trimmed, on one line, and no longer than {@link OUTREACH_OPEN_AGENT_MAX}. */\nexport function outreachOpenAgentEvidence(userAgent: string | null | undefined): string | null {\n  // Every control character, a line break included, read as a space.\n  const agent = Array.from(String(userAgent ?? ''), (character) => {\n    const code = character.charCodeAt(0)\n    return code < 0x20 || code === 0x7f ? ' ' : character\n  })\n    .join('')\n    .replace(/ {2,}/g, ' ')\n    .trim()\n  return agent ? agent.slice(0, OUTREACH_OPEN_AGENT_MAX) : null\n}\n\n/**\n * Whether one fetch of a tracking image is a person's open.\n *\n * Read before the open is recorded, never before the image is answered:\n * every fetch gets the same image.\n *\n * @param input.sinceSentMs Milliseconds between the send and this fetch, or\n *   `null` when the send it belongs to could not be found.\n * @param input.source The network the fetch came from (`./open-source.ts`),\n *   or `null` when no address was read — judged then by the agent alone,\n *   as every fetch was before AGL-3488.\n */\nexport function judgeOutreachOpen(input: {\n  method: string\n  userAgent: string | null | undefined\n  sinceSentMs: number | null\n  source?: OutreachOpenSource | null\n}): OutreachOpenJudgement {\n  const machine = (machineReason: OutreachOpenMachineReason): OutreachOpenJudgement => ({\n    human: false,\n    machineReason,\n  })\n  const source = input.source ?? null\n  if (String(input.method ?? '').toUpperCase() === 'HEAD') return machine('method')\n  const agent = String(input.userAgent ?? '').trim().toLowerCase()\n  if (!agent) return machine('agent')\n  if (source === 'yahoo' || IMAGE_PROXY_AGENTS.some((needle) => agent.includes(needle))) return machine('image_proxy')\n  if (agent === BARE_AGENT) {\n    // Apple's agent from Apple's relay — or from nowhere we could read,\n    // which is how every such fetch was judged before the address was.\n    return machine(source === null || source === 'apple' ? 'privacy_proxy' : 'scanner')\n  }\n  if (GMAIL_PREFETCH_AGENT_PARTS.every((part) => agent.includes(part))) return machine('scanner')\n  const gmail = GMAIL_PROXY_AGENTS.some((needle) => agent.includes(needle))\n  // Gmail's proxy fetches from Google's network; the same words from any\n  // other network that could be read are someone else's.\n  if (gmail && source !== null && source !== 'google') return machine('agent')\n  if (!gmail && OUTREACH_MACHINE_AGENTS.some((needle) => agent.includes(needle))) return machine('agent')\n  if (!gmail && (source === 'google' || source === 'microsoft_filter')) return machine('scanner')\n  // A fetch before its send is two clocks disagreeing, and read as a person's.\n  if (input.sinceSentMs !== null && input.sinceSentMs >= 0 && input.sinceSentMs < OUTREACH_OPEN_HUMAN_DELAY_MS) {\n    return machine('too_soon')\n  }\n  return { human: true, machineReason: null }\n}\n"],"names":["OUTREACH_MACHINE_AGENTS","outreachBodyLinks","HTML_ESCAPES","escapeOutreachHtml","value","String","replace","character","escapedLines","text","outreachOpenTrackedHtml","pixelUrl","body","html","cursor","link","slice","start","href","url","end","src","OUTREACH_OPEN_HUMAN_DELAY_MS","IMAGE_PROXY_AGENTS","GMAIL_PROXY_AGENTS","GMAIL_PREFETCH_AGENT_PARTS","BARE_AGENT","OUTREACH_OPEN_AGENT_MAX","OUTREACH_PROXY_OPEN_REASONS","outreachOpenAgentEvidence","userAgent","agent","Array","from","code","charCodeAt","join","trim","judgeOutreachOpen","input","machine","machineReason","human","source","method","toUpperCase","toLowerCase","some","needle","includes","every","part","gmail","sinceSentMs"],"mappings":"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"}

package/src/lib/engine/outreach-access.d.ts

@@ -0,0 +1,47 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * WHO MAY WORK SEQUENCES IN AN ORGANIZATION, as plain verdicts.
+ *
+ * The route gate (`routes/route-gate.ts`) answers an HTTP request with them;
+ * the do-not-contact transfer resource answers an import or an export with
+ * the same ones, so a member the Compliance page would refuse cannot reach
+ * the list through a file either. Nothing here reads a request or a token:
+ * the caller has already resolved the membership and read the organization.
+ */
+/** Why a member may not work Sequences in an organization. */
+export interface OutreachAccessRefusal {
+    status: 403;
+    code: 'not-a-member' | 'not-org-wide' | 'permission' | 'entitlement';
+    message: string;
+}
+/** The membership as the platform resolves it for one organization. */
+export interface OutreachMembership {
+    orgId: string | null;
+    /** `null` when the account is not on the organization's roster. */
+    role: string | null;
+    orgWide: boolean;
+    permissions: Partial<Record<string, boolean | undefined>>;
+}
+/**
+ * The member's refusal, or `null`: on the roster of THIS organization, with
+ * reach over all of it (Sequences covers the whole organization, so access to
+ * particular sites is not enough), and holding `outreach.use`.
+ */
+export declare function outreachMembershipRefusal(membership: OutreachMembership, orgId: string): OutreachAccessRefusal | null;
+/** The organization's refusal, or `null` when its plan or override includes Sequences. */
+export declare function outreachEntitlementRefusal(org: Record<string, unknown> | null | undefined): OutreachAccessRefusal | null;

package/src/lib/engine/outreach-access.js

@@ -0,0 +1,56 @@
+/**
+ * @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 { checkEntitlement } from "@aglyn/aglyn/app-utils/plan-entitlements";
+import { OUTREACH_USE_PERMISSION } from "../constants/bundle-common.js";
+/**
+ * The member's refusal, or `null`: on the roster of THIS organization, with
+ * reach over all of it (Sequences covers the whole organization, so access to
+ * particular sites is not enough), and holding `outreach.use`.
+ */ export function outreachMembershipRefusal(membership, orgId) {
+    // A targeted org the account is not on answers with that org's id and no
+    // role — as does a lookup that failed closed — so the role is the test.
+    if (!membership.role || membership.orgId !== orgId) {
+        return {
+            status: 403,
+            code: 'not-a-member',
+            message: 'You are not a member of that organization.'
+        };
+    }
+    if (!membership.orgWide) {
+        return {
+            status: 403,
+            code: 'not-org-wide',
+            message: 'Sequences covers the whole organization, and your access is to particular sites.'
+        };
+    }
+    if (membership.permissions[OUTREACH_USE_PERMISSION] !== true) {
+        return {
+            status: 403,
+            code: 'permission',
+            message: 'Your role does not include Use Sequences.'
+        };
+    }
+    return null;
+}
+/** The organization's refusal, or `null` when its plan or override includes Sequences. */ export function outreachEntitlementRefusal(org) {
+    return checkEntitlement(org != null ? org : {}, 'outreach') ? null : {
+        status: 403,
+        code: 'entitlement',
+        message: "Sequences isn't available to this workspace yet."
+    };
+}
+
+//# sourceMappingURL=outreach-access.js.map

package/src/lib/engine/outreach-access.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/outreach/src/lib/engine/outreach-access.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\nimport { checkEntitlement } from '@aglyn/aglyn/app-utils/plan-entitlements'\nimport { OUTREACH_USE_PERMISSION } from '../constants/bundle-common'\n\n/**\n * WHO MAY WORK SEQUENCES IN AN ORGANIZATION, as plain verdicts.\n *\n * The route gate (`routes/route-gate.ts`) answers an HTTP request with them;\n * the do-not-contact transfer resource answers an import or an export with\n * the same ones, so a member the Compliance page would refuse cannot reach\n * the list through a file either. Nothing here reads a request or a token:\n * the caller has already resolved the membership and read the organization.\n */\n\n/** Why a member may not work Sequences in an organization. */\nexport interface OutreachAccessRefusal {\n  status: 403\n  code: 'not-a-member' | 'not-org-wide' | 'permission' | 'entitlement'\n  message: string\n}\n\n/** The membership as the platform resolves it for one organization. */\nexport interface OutreachMembership {\n  orgId: string | null\n  /** `null` when the account is not on the organization's roster. */\n  role: string | null\n  orgWide: boolean\n  permissions: Partial<Record<string, boolean | undefined>>\n}\n\n/**\n * The member's refusal, or `null`: on the roster of THIS organization, with\n * reach over all of it (Sequences covers the whole organization, so access to\n * particular sites is not enough), and holding `outreach.use`.\n */\nexport function outreachMembershipRefusal(\n  membership: OutreachMembership,\n  orgId: string,\n): OutreachAccessRefusal | null {\n  // A targeted org the account is not on answers with that org's id and no\n  // role — as does a lookup that failed closed — so the role is the test.\n  if (!membership.role || membership.orgId !== orgId) {\n    return { status: 403, code: 'not-a-member', message: 'You are not a member of that organization.' }\n  }\n  if (!membership.orgWide) {\n    return {\n      status: 403,\n      code: 'not-org-wide',\n      message: 'Sequences covers the whole organization, and your access is to particular sites.',\n    }\n  }\n  if (membership.permissions[OUTREACH_USE_PERMISSION] !== true) {\n    return { status: 403, code: 'permission', message: 'Your role does not include Use Sequences.' }\n  }\n  return null\n}\n\n/** The organization's refusal, or `null` when its plan or override includes Sequences. */\nexport function outreachEntitlementRefusal(\n  org: Record<string, unknown> | null | undefined,\n): OutreachAccessRefusal | null {\n  return checkEntitlement(org ?? {}, 'outreach')\n    ? null\n    : { status: 403, code: 'entitlement', message: \"Sequences isn't available to this workspace yet.\" }\n}\n"],"names":["checkEntitlement","OUTREACH_USE_PERMISSION","outreachMembershipRefusal","membership","orgId","role","status","code","message","orgWide","permissions","outreachEntitlementRefusal","org"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED,SAASA,gBAAgB,QAAQ,2CAA0C;AAC3E,SAASC,uBAAuB,QAAQ,gCAA4B;AA4BpE;;;;CAIC,GACD,OAAO,SAASC,0BACdC,UAA8B,EAC9BC,KAAa;IAEb,yEAAyE;IACzE,wEAAwE;IACxE,IAAI,CAACD,WAAWE,IAAI,IAAIF,WAAWC,KAAK,KAAKA,OAAO;QAClD,OAAO;YAAEE,QAAQ;YAAKC,MAAM;YAAgBC,SAAS;QAA6C;IACpG;IACA,IAAI,CAACL,WAAWM,OAAO,EAAE;QACvB,OAAO;YACLH,QAAQ;YACRC,MAAM;YACNC,SAAS;QACX;IACF;IACA,IAAIL,WAAWO,WAAW,CAACT,wBAAwB,KAAK,MAAM;QAC5D,OAAO;YAAEK,QAAQ;YAAKC,MAAM;YAAcC,SAAS;QAA4C;IACjG;IACA,OAAO;AACT;AAEA,wFAAwF,GACxF,OAAO,SAASG,2BACdC,GAA+C;IAE/C,OAAOZ,iBAAiBY,cAAAA,MAAO,CAAC,GAAG,cAC/B,OACA;QAAEN,QAAQ;QAAKC,MAAM;QAAeC,SAAS;IAAmD;AACtG"}

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

@@ -17,7 +17,6 @@
 import { type OutreachGateHold, type OutreachGateLookups } from '../engine/gates';
 import { type OutreachAttestations, type OutreachSequenceSettings } from '../model/outreach.types';
 import type { OutreachEnrollBlock, OutreachEnrollPreviewPerson, OutreachPersonRef } from '../model/outreach-api';
-type Firestore = FirebaseFirestore.Firestore;
 /**
  * One person as the preview and the enroll read them: a contact, or a lead
  * the sequence's site holds (AGL-3234).
@@ -46,9 +45,9 @@ export interface OutreachEnrollCandidate {
     /** The lead's person key; `null` for a contact. */
     leadId: string | null;
     /**
-     * The contact document (`orgs/{orgId}/contacts/{id}`), or for a lead the
-     * contact-shaped view of it — see the module note. `null` when the record
-     * no longer exists.
+     * The contact as the record system keeps it (`plugin-person-records`), or
+     * for a lead the contact-shaped view of it — see the module note. `null`
+     * when the record no longer exists.
      */
     contact: Record<string, unknown> | null;
     /** The lead document as stored, for a lead; `null` for a contact. */
@@ -76,12 +75,14 @@ export interface OutreachEnrollCandidate {
 export declare function leadAsContact(lead: Record<string, unknown>, contactGroupId: string): Record<string, unknown>;
 /**
  * The people, as the sequence's site knows them, and the company each
- * contact is filed under there — batched reads for everyone: the contacts
- * and the leads by id, the companies once, and for each lead one address
- * lookup, because a lead the workspace already holds as a contact is that
- * contact's to enroll.
+ * contact is filed under there — asked of the plugin that keeps people
+ * (`plugin-person-records`, AGL-3080), never read off its storage: the
+ * contacts and the leads at once, the companies once each through its
+ * `company` record index, and for each lead one address lookup, because a
+ * lead the workspace already holds as a contact is that contact's to enroll.
+ * With no plugin keeping people, every person reads as gone.
  */
-export declare function readOutreachEnrollCandidates(firestore: Firestore, input: {
+export declare function readOutreachEnrollCandidates(input: {
     orgId: string;
     hostId: string;
     contactGroupId: string;
@@ -128,4 +129,3 @@ export declare function decideOutreachEnrollment(question: OutreachGateQuestion,
     uid: string;
     nowMs: number;
 }): OutreachEnrollDecision;
-export {};

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

@@ -50,7 +50,8 @@ import { _ as _object_without_properties_loose } from "@swc/helpers/_/_object_wi
  *==========================================*/ import { normalizeContactEmail, contactDisplayName, readContactFacet } from "@aglyn/aglyn/app-utils/contacts";
 import { crmLeadDisplayName, crmLeadStatus } from "@aglyn/aglyn/app-utils/crm";
 import { seenOnlyThroughGrant, visibleToHost } from "@aglyn/aglyn/app-utils/scope-tokens";
-import { findContactByEmail } from "@aglyn/tenant-data-admin/server/contact-email-index";
+import { findPluginPerson, readPluginPeople } from "@aglyn/aglyn/plugin-manager/plugin-person-records";
+import { pluginRecordIndex } from "@aglyn/aglyn/plugin-manager/plugin-record-index";
 import { evaluateOutreachGates } from "../engine/gates.js";
 import { outreachAttestationsFrom } from "../engine/enrollment-state.js";
 import { OUTREACH_ATTESTATION_KINDS } from "../model/outreach.types.js";
@@ -90,33 +91,33 @@ import { OUTREACH_ATTESTATION_KINDS } from "../model/outreach.types.js";
         }
     });
 }
-/** `getAll` takes this many references at most per call. */ const GET_ALL_CHUNK = 300;
-async function getAllChunked(firestore, refs) {
-    const snapshots = [];
-    for(let start = 0; start < refs.length; start += GET_ALL_CHUNK){
-        snapshots.push(...await firestore.getAll(...refs.slice(start, start + GET_ALL_CHUNK)));
-    }
-    return snapshots;
-}
 /**
  * The people, as the sequence's site knows them, and the company each
- * contact is filed under there — batched reads for everyone: the contacts
- * and the leads by id, the companies once, and for each lead one address
- * lookup, because a lead the workspace already holds as a contact is that
- * contact's to enroll.
- */ export async function readOutreachEnrollCandidates(firestore, input) {
+ * contact is filed under there — asked of the plugin that keeps people
+ * (`plugin-person-records`, AGL-3080), never read off its storage: the
+ * contacts and the leads at once, the companies once each through its
+ * `company` record index, and for each lead one address lookup, because a
+ * lead the workspace already holds as a contact is that contact's to enroll.
+ * With no plugin keeping people, every person reads as gone.
+ */ export async function readOutreachEnrollCandidates(input) {
+    var _ref;
     if (!input.people.length) return [];
-    const org = firestore.collection('orgs').doc(input.orgId);
-    // Beside the contacts, on the org (AGL-3275).
-    const leads = org.collection('leads');
-    const snapshots = await getAllChunked(firestore, input.people.map((person)=>person.kind === 'lead' ? leads.doc(person.id) : org.collection('contacts').doc(person.id)));
+    const records = (_ref = await readPluginPeople({
+        orgId: input.orgId,
+        records: input.people.map((person)=>({
+                kind: person.kind,
+                id: person.id
+            }))
+    })) != null ? _ref : input.people.map(()=>null);
     const read = await Promise.all(input.people.map(async (person, index)=>{
         var _readContactFacet_companyId;
-        var _snapshots_index;
-        const data = ((_snapshots_index = snapshots[index]) == null ? void 0 : _snapshots_index.exists) ? snapshots[index].data() : null;
+        const data = records[index] ? _extends({}, records[index].data) : null;
         if (person.kind === 'lead') {
             const email = data ? normalizeContactEmail(data['email']) : null;
-            const held = data && email ? await findContactByEmail(org.collection('contacts'), email) : null;
+            const held = data && email ? await findPluginPerson({
+                orgId: input.orgId,
+                email
+            }) : null;
             return {
                 personId: person.id,
                 target: 'lead',
@@ -154,10 +155,14 @@ async function getAllChunked(firestore, refs) {
         ...new Set(read.map((entry)=>entry.companyId).filter(Boolean))
     ];
     const companies = new Map();
-    if (companyIds.length) {
-        const found = await getAllChunked(firestore, companyIds.map((id)=>org.collection('companies').doc(id)));
-        found.forEach((snapshot, index)=>{
-            if (snapshot.exists) companies.set(companyIds[index], snapshot.data());
+    const companyIndex = companyIds.length ? pluginRecordIndex('company') : null;
+    if (companyIndex) {
+        const found = await Promise.all(companyIds.map((id)=>companyIndex.index.get({
+                orgId: input.orgId,
+                id
+            })));
+        found.forEach((company, index)=>{
+            if (company) companies.set(companyIds[index], _extends({}, company.facts));
         });
     }
     return read.map((_0)=>{