@aglyn/plugins-email 1.0.0-beta.218 → 1.0.0-beta.220

package/src/lib/components/use-org-email-topics.js

@@ -15,7 +15,8 @@
  * limitations under the License.
  */ 'use client';
 import { _ as _extends } from "@swc/helpers/_/_extends";
-import { EMAIL_TOPICS_COLLECTION, mergeEmailTopics, normalizeEmailTopic } from "@aglyn/aglyn";
+import { mergeSubscriptionTopics, normalizeSubscriptionTopic } from "@aglyn/aglyn";
+import { EMAIL_TOPICS_COLLECTION } from "../model/email-topic-catalog.js";
 import { collection, deleteField, doc, limit, orderBy, query, setDoc } from "firebase/firestore";
 import { useMemo } from "react";
 import { useFirestore, useFirestoreCollection, useOrgDataScope } from "@aglyn/tenant-feature-instance";
@@ -37,7 +38,7 @@ import { useFirestore, useFirestoreCollection, useOrgDataScope } from "@aglyn/te
  *
  * ## Why a built-in saves the same way
  *
- * `DEFAULT_EMAIL_TOPICS` is the FLOOR of the catalog, not its initial
+ * `DECLARED_SUBSCRIPTION_TOPICS` is the FLOOR of the catalog, not its initial
  * contents: the four built-ins have no stored document until somebody changes
  * one. `setDoc` at the built-in's own id is what creates the override, so the
  * same call serves a custom topic and a built-in being retired for the first
@@ -72,7 +73,7 @@ import { useFirestore, useFirestoreCollection, useOrgDataScope } from "@aglyn/te
  * different merge rules is how the composer comes to send a campaign under a
  * topic nobody can unsubscribe from.
  *
- * ORG-scoped, following `lists` (AGL-254) — see `email-topics.ts` for why the
+ * ORG-scoped, following `lists` (AGL-254) — see `subscription-topics.ts` for why the
  * definitions are org-shared while the recipient's opt-outs are per site.
  *
  * Ordered by the server rather than capped and re-sorted here (AGL-2501,
@@ -97,9 +98,9 @@ import { useFirestore, useFirestoreCollection, useOrgDataScope } from "@aglyn/te
     ], {
         idField: '$id'
     });
-    const topics = useMemo(()=>mergeEmailTopics((stored != null ? stored : []).map((doc)=>{
+    const topics = useMemo(()=>mergeSubscriptionTopics((stored != null ? stored : []).map((doc)=>{
             var _doc_$id;
-            return normalizeEmailTopic(String((_doc_$id = doc['$id']) != null ? _doc_$id : ''), doc);
+            return normalizeSubscriptionTopic(String((_doc_$id = doc['$id']) != null ? _doc_$id : ''), doc);
         }).filter((topic)=>!!topic)), [
         stored
     ]);

package/src/lib/components/use-org-email-topics.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../../../../../libs/plugins/email/src/lib/components/use-org-email-topics.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'use client'\n\nimport {\n  EMAIL_TOPICS_COLLECTION,\n  mergeEmailTopics,\n  normalizeEmailTopic,\n  type EmailTopic,\n} from '@aglyn/aglyn'\nimport type { Firestore } from 'firebase/firestore'\nimport {\n  collection,\n  deleteField,\n  doc,\n  limit,\n  orderBy,\n  query,\n  setDoc,\n} from 'firebase/firestore'\nimport { useMemo } from 'react'\nimport {\n  useFirestore,\n  useFirestoreCollection,\n  useOrgDataScope,\n} from '@aglyn/tenant-feature-instance'\n\n/**\n * Write one topic's document — the ONE writer of the topic catalog.\n *\n * Two surfaces change a topic: its own page, which edits the name and the\n * description, and the list card's row menu, which retires and restores. They\n * write the same document and have to agree about its shape, so the write\n * lives here rather than once in each.\n *\n * ## Why it is a complete statement and not a patch\n *\n * `archived` is written on every save rather than only when it changes. A\n * merge that omitted it would leave a restored topic carrying `archived: true`\n * from an earlier save — which reads on screen as restored and behaves as\n * retired, because the composer's picker and the recipient's preference page\n * both read the stored flag.\n *\n * ## Why a built-in saves the same way\n *\n * `DEFAULT_EMAIL_TOPICS` is the FLOOR of the catalog, not its initial\n * contents: the four built-ins have no stored document until somebody changes\n * one. `setDoc` at the built-in's own id is what creates the override, so the\n * same call serves a custom topic and a built-in being retired for the first\n * time.\n */\nexport async function writeEmailTopic(\n  firestore: Firestore,\n  scope: readonly [string, string],\n  topic: {\n    id: string\n    name: string\n    description: string\n    archived: boolean\n    /**\n     * Whether this stream needs a confirmation click, or `null`/omitted for\n     * \"whatever the site says\".\n     *\n     * The only field on this document with THREE states, which is why it is\n     * the only one written conditionally: `archived` is written on every save\n     * because a merge that omitted it would carry an old value forward, and a\n     * `doubleOptIn` written on every save could never be un-chosen back to\n     * the site default. `deleteField()` is what returns it, so clearing is a\n     * real act rather than a value that happens to look like an absence.\n     */\n    doubleOptIn?: boolean | null\n  },\n): Promise<void> {\n  await setDoc(\n    doc(firestore, scope[0], scope[1], EMAIL_TOPICS_COLLECTION, topic.id),\n    {\n      name: topic.name,\n      description: topic.description,\n      archived: topic.archived,\n      ...(topic.doubleOptIn === undefined\n        ? {}\n        : {\n            doubleOptIn:\n              topic.doubleOptIn === null ? deleteField() : topic.doubleOptIn,\n          }),\n    },\n    { merge: true },\n  )\n}\n\n/**\n * How many stored topics one read fetches.\n *\n * A ceiling on the READ, not on the catalog. A preference page stops being a\n * preference page somewhere well before two hundred checkboxes, so an org that\n * reaches this has a different problem than a truncated list — and the read is\n * ordered, so what a merchant past it loses is the tail of the alphabet rather\n * than an arbitrary sample.\n */\nconst TOPIC_READ_CEILING = 200\n\n/**\n * The org's email topic catalog, as both the console card and the composer's\n * picker read it.\n *\n * ONE hook for both surfaces, because they have to agree: a topic the composer\n * offers must be one the preference page can render, and a topic the card\n * archives must leave the picker. Two reads of the same collection with two\n * different merge rules is how the composer comes to send a campaign under a\n * topic nobody can unsubscribe from.\n *\n * ORG-scoped, following `lists` (AGL-254) — see `email-topics.ts` for why the\n * definitions are org-shared while the recipient's opt-outs are per site.\n *\n * Ordered by the server rather than capped and re-sorted here (AGL-2501,\n * AGL-2292). `name` is safe to order on because every writer of this\n * collection is the topics card, which refuses to save a nameless topic —\n * `orderBy` DROPS documents that lack the field rather than mis-sorting them,\n * so that claim is about the writers and not a preference.\n */\nexport function useOrgEmailTopics(\n  /** The site the catalog is read through, or `null` on the org page. */\n  hostId: string | null,\n  options?: {\n    /**\n     * Whether to read at all. Default true.\n     *\n     * For a caller whose only use of the catalog is a picker inside a control\n     * somebody has to open — a create drawer, an edit drawer — where reading\n     * on mount charges every reader of the list for a field none of them\n     * asked for. A `false` here opens no listener, exactly as a null query\n     * does, and the catalog reads as empty until it flips.\n     */\n    enabled?: boolean\n    /**\n     * The organization itself, for a caller mounted over the org rather than\n     * under one of its sites. It skips the site's org lookup, and it is the\n     * only way the catalog can be read with no site at all.\n     */\n    orgId?: string | null\n  },\n): {\n  topics: EmailTopic[]\n  /** `['orgs', orgId]`, or null until the org lookup settles. */\n  scope: readonly [string, string] | null\n} {\n  const firestore = useFirestore()\n  const enabled = options?.enabled ?? true\n  // The org lookup is async (AGL-1061): null until it settles, and null\n  // forever for a host with no owning org. An explicit org is ready at once.\n  const { scope } = useOrgDataScope({\n    hostId: hostId || undefined,\n    orgId: options?.orgId || undefined,\n  })\n  const { data: stored } = useFirestoreCollection<Record<string, unknown>>(\n    () =>\n      scope && enabled\n        ? query(\n            collection(firestore, scope[0], scope[1], EMAIL_TOPICS_COLLECTION),\n            orderBy('name'),\n            limit(TOPIC_READ_CEILING),\n          )\n        : null,\n    [firestore, scope, enabled],\n    { idField: '$id' },\n  )\n  const topics = useMemo(\n    () =>\n      mergeEmailTopics(\n        (stored ?? [])\n          .map((doc) => normalizeEmailTopic(String(doc['$id'] ?? ''), doc))\n          .filter((topic): topic is EmailTopic => !!topic),\n      ),\n    [stored],\n  )\n  return { topics, scope: scope as readonly [string, string] | null }\n}\n"],"names":["EMAIL_TOPICS_COLLECTION","mergeEmailTopics","normalizeEmailTopic","collection","deleteField","doc","limit","orderBy","query","setDoc","useMemo","useFirestore","useFirestoreCollection","useOrgDataScope","writeEmailTopic","firestore","scope","topic","id","name","description","archived","doubleOptIn","undefined","merge","TOPIC_READ_CEILING","useOrgEmailTopics","hostId","options","enabled","orgId","data","stored","idField","topics","map","String","filter"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GACD;;AAEA,SACEA,uBAAuB,EACvBC,gBAAgB,EAChBC,mBAAmB,QAEd,eAAc;AAErB,SACEC,UAAU,EACVC,WAAW,EACXC,GAAG,EACHC,KAAK,EACLC,OAAO,EACPC,KAAK,EACLC,MAAM,QACD,qBAAoB;AAC3B,SAASC,OAAO,QAAQ,QAAO;AAC/B,SACEC,YAAY,EACZC,sBAAsB,EACtBC,eAAe,QACV,iCAAgC;AAEvC;;;;;;;;;;;;;;;;;;;;;;;CAuBC,GACD,OAAO,eAAeC,gBACpBC,SAAoB,EACpBC,KAAgC,EAChCC,KAiBC;IAED,MAAMR,OACJJ,IAAIU,WAAWC,KAAK,CAAC,EAAE,EAAEA,KAAK,CAAC,EAAE,EAAEhB,yBAAyBiB,MAAMC,EAAE,GACpE;QACEC,MAAMF,MAAME,IAAI;QAChBC,aAAaH,MAAMG,WAAW;QAC9BC,UAAUJ,MAAMI,QAAQ;OACpBJ,MAAMK,WAAW,KAAKC,YACtB,CAAC,IACD;QACED,aACEL,MAAMK,WAAW,KAAK,OAAOlB,gBAAgBa,MAAMK,WAAW;IAClE,IAEN;QAAEE,OAAO;IAAK;AAElB;AAEA;;;;;;;;CAQC,GACD,MAAMC,qBAAqB;AAE3B;;;;;;;;;;;;;;;;;;CAkBC,GACD,OAAO,SAASC,kBACd,qEAAqE,GACrEC,MAAqB,EACrBC,OAiBC;;IAMD,MAAMb,YAAYJ;IAClB,MAAMkB,kBAAUD,2BAAAA,QAASC,OAAO,mBAAI;IACpC,sEAAsE;IACtE,2EAA2E;IAC3E,MAAM,EAAEb,KAAK,EAAE,GAAGH,gBAAgB;QAChCc,QAAQA,UAAUJ;QAClBO,OAAOF,CAAAA,2BAAAA,QAASE,KAAK,KAAIP;IAC3B;IACA,MAAM,EAAEQ,MAAMC,MAAM,EAAE,GAAGpB,uBACvB,IACEI,SAASa,UACLrB,MACEL,WAAWY,WAAWC,KAAK,CAAC,EAAE,EAAEA,KAAK,CAAC,EAAE,EAAEhB,0BAC1CO,QAAQ,SACRD,MAAMmB,uBAER,MACN;QAACV;QAAWC;QAAOa;KAAQ,EAC3B;QAAEI,SAAS;IAAM;IAEnB,MAAMC,SAASxB,QACb,IACET,iBACE,CAAC+B,iBAAAA,SAAU,EAAE,EACVG,GAAG,CAAC,CAAC9B;gBAAmCA;mBAA3BH,oBAAoBkC,QAAO/B,WAAAA,GAAG,CAAC,MAAM,YAAVA,WAAc,KAAKA;WAC3DgC,MAAM,CAAC,CAACpB,QAA+B,CAAC,CAACA,SAEhD;QAACe;KAAO;IAEV,OAAO;QAAEE;QAAQlB,OAAOA;IAA0C;AACpE"}
+{"version":3,"sources":["../../../../../../../libs/plugins/email/src/lib/components/use-org-email-topics.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'use client'\n\nimport {\n  mergeSubscriptionTopics,\n  normalizeSubscriptionTopic,\n  type SubscriptionTopic,\n} from '@aglyn/aglyn'\nimport { EMAIL_TOPICS_COLLECTION } from '../model/email-topic-catalog'\nimport type { Firestore } from 'firebase/firestore'\nimport {\n  collection,\n  deleteField,\n  doc,\n  limit,\n  orderBy,\n  query,\n  setDoc,\n} from 'firebase/firestore'\nimport { useMemo } from 'react'\nimport {\n  useFirestore,\n  useFirestoreCollection,\n  useOrgDataScope,\n} from '@aglyn/tenant-feature-instance'\n\n/**\n * Write one topic's document — the ONE writer of the topic catalog.\n *\n * Two surfaces change a topic: its own page, which edits the name and the\n * description, and the list card's row menu, which retires and restores. They\n * write the same document and have to agree about its shape, so the write\n * lives here rather than once in each.\n *\n * ## Why it is a complete statement and not a patch\n *\n * `archived` is written on every save rather than only when it changes. A\n * merge that omitted it would leave a restored topic carrying `archived: true`\n * from an earlier save — which reads on screen as restored and behaves as\n * retired, because the composer's picker and the recipient's preference page\n * both read the stored flag.\n *\n * ## Why a built-in saves the same way\n *\n * `DECLARED_SUBSCRIPTION_TOPICS` is the FLOOR of the catalog, not its initial\n * contents: the four built-ins have no stored document until somebody changes\n * one. `setDoc` at the built-in's own id is what creates the override, so the\n * same call serves a custom topic and a built-in being retired for the first\n * time.\n */\nexport async function writeEmailTopic(\n  firestore: Firestore,\n  scope: readonly [string, string],\n  topic: {\n    id: string\n    name: string\n    description: string\n    archived: boolean\n    /**\n     * Whether this stream needs a confirmation click, or `null`/omitted for\n     * \"whatever the site says\".\n     *\n     * The only field on this document with THREE states, which is why it is\n     * the only one written conditionally: `archived` is written on every save\n     * because a merge that omitted it would carry an old value forward, and a\n     * `doubleOptIn` written on every save could never be un-chosen back to\n     * the site default. `deleteField()` is what returns it, so clearing is a\n     * real act rather than a value that happens to look like an absence.\n     */\n    doubleOptIn?: boolean | null\n  },\n): Promise<void> {\n  await setDoc(\n    doc(firestore, scope[0], scope[1], EMAIL_TOPICS_COLLECTION, topic.id),\n    {\n      name: topic.name,\n      description: topic.description,\n      archived: topic.archived,\n      ...(topic.doubleOptIn === undefined\n        ? {}\n        : {\n            doubleOptIn:\n              topic.doubleOptIn === null ? deleteField() : topic.doubleOptIn,\n          }),\n    },\n    { merge: true },\n  )\n}\n\n/**\n * How many stored topics one read fetches.\n *\n * A ceiling on the READ, not on the catalog. A preference page stops being a\n * preference page somewhere well before two hundred checkboxes, so an org that\n * reaches this has a different problem than a truncated list — and the read is\n * ordered, so what a merchant past it loses is the tail of the alphabet rather\n * than an arbitrary sample.\n */\nconst TOPIC_READ_CEILING = 200\n\n/**\n * The org's email topic catalog, as both the console card and the composer's\n * picker read it.\n *\n * ONE hook for both surfaces, because they have to agree: a topic the composer\n * offers must be one the preference page can render, and a topic the card\n * archives must leave the picker. Two reads of the same collection with two\n * different merge rules is how the composer comes to send a campaign under a\n * topic nobody can unsubscribe from.\n *\n * ORG-scoped, following `lists` (AGL-254) — see `subscription-topics.ts` for why the\n * definitions are org-shared while the recipient's opt-outs are per site.\n *\n * Ordered by the server rather than capped and re-sorted here (AGL-2501,\n * AGL-2292). `name` is safe to order on because every writer of this\n * collection is the topics card, which refuses to save a nameless topic —\n * `orderBy` DROPS documents that lack the field rather than mis-sorting them,\n * so that claim is about the writers and not a preference.\n */\nexport function useOrgEmailTopics(\n  /** The site the catalog is read through, or `null` on the org page. */\n  hostId: string | null,\n  options?: {\n    /**\n     * Whether to read at all. Default true.\n     *\n     * For a caller whose only use of the catalog is a picker inside a control\n     * somebody has to open — a create drawer, an edit drawer — where reading\n     * on mount charges every reader of the list for a field none of them\n     * asked for. A `false` here opens no listener, exactly as a null query\n     * does, and the catalog reads as empty until it flips.\n     */\n    enabled?: boolean\n    /**\n     * The organization itself, for a caller mounted over the org rather than\n     * under one of its sites. It skips the site's org lookup, and it is the\n     * only way the catalog can be read with no site at all.\n     */\n    orgId?: string | null\n  },\n): {\n  topics: SubscriptionTopic[]\n  /** `['orgs', orgId]`, or null until the org lookup settles. */\n  scope: readonly [string, string] | null\n} {\n  const firestore = useFirestore()\n  const enabled = options?.enabled ?? true\n  // The org lookup is async (AGL-1061): null until it settles, and null\n  // forever for a host with no owning org. An explicit org is ready at once.\n  const { scope } = useOrgDataScope({\n    hostId: hostId || undefined,\n    orgId: options?.orgId || undefined,\n  })\n  const { data: stored } = useFirestoreCollection<Record<string, unknown>>(\n    () =>\n      scope && enabled\n        ? query(\n            collection(firestore, scope[0], scope[1], EMAIL_TOPICS_COLLECTION),\n            orderBy('name'),\n            limit(TOPIC_READ_CEILING),\n          )\n        : null,\n    [firestore, scope, enabled],\n    { idField: '$id' },\n  )\n  const topics = useMemo(\n    () =>\n      mergeSubscriptionTopics(\n        (stored ?? [])\n          .map((doc) => normalizeSubscriptionTopic(String(doc['$id'] ?? ''), doc))\n          .filter((topic): topic is SubscriptionTopic => !!topic),\n      ),\n    [stored],\n  )\n  return { topics, scope: scope as readonly [string, string] | null }\n}\n"],"names":["mergeSubscriptionTopics","normalizeSubscriptionTopic","EMAIL_TOPICS_COLLECTION","collection","deleteField","doc","limit","orderBy","query","setDoc","useMemo","useFirestore","useFirestoreCollection","useOrgDataScope","writeEmailTopic","firestore","scope","topic","id","name","description","archived","doubleOptIn","undefined","merge","TOPIC_READ_CEILING","useOrgEmailTopics","hostId","options","enabled","orgId","data","stored","idField","topics","map","String","filter"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GACD;;AAEA,SACEA,uBAAuB,EACvBC,0BAA0B,QAErB,eAAc;AACrB,SAASC,uBAAuB,QAAQ,kCAA8B;AAEtE,SACEC,UAAU,EACVC,WAAW,EACXC,GAAG,EACHC,KAAK,EACLC,OAAO,EACPC,KAAK,EACLC,MAAM,QACD,qBAAoB;AAC3B,SAASC,OAAO,QAAQ,QAAO;AAC/B,SACEC,YAAY,EACZC,sBAAsB,EACtBC,eAAe,QACV,iCAAgC;AAEvC;;;;;;;;;;;;;;;;;;;;;;;CAuBC,GACD,OAAO,eAAeC,gBACpBC,SAAoB,EACpBC,KAAgC,EAChCC,KAiBC;IAED,MAAMR,OACJJ,IAAIU,WAAWC,KAAK,CAAC,EAAE,EAAEA,KAAK,CAAC,EAAE,EAAEd,yBAAyBe,MAAMC,EAAE,GACpE;QACEC,MAAMF,MAAME,IAAI;QAChBC,aAAaH,MAAMG,WAAW;QAC9BC,UAAUJ,MAAMI,QAAQ;OACpBJ,MAAMK,WAAW,KAAKC,YACtB,CAAC,IACD;QACED,aACEL,MAAMK,WAAW,KAAK,OAAOlB,gBAAgBa,MAAMK,WAAW;IAClE,IAEN;QAAEE,OAAO;IAAK;AAElB;AAEA;;;;;;;;CAQC,GACD,MAAMC,qBAAqB;AAE3B;;;;;;;;;;;;;;;;;;CAkBC,GACD,OAAO,SAASC,kBACd,qEAAqE,GACrEC,MAAqB,EACrBC,OAiBC;;IAMD,MAAMb,YAAYJ;IAClB,MAAMkB,kBAAUD,2BAAAA,QAASC,OAAO,mBAAI;IACpC,sEAAsE;IACtE,2EAA2E;IAC3E,MAAM,EAAEb,KAAK,EAAE,GAAGH,gBAAgB;QAChCc,QAAQA,UAAUJ;QAClBO,OAAOF,CAAAA,2BAAAA,QAASE,KAAK,KAAIP;IAC3B;IACA,MAAM,EAAEQ,MAAMC,MAAM,EAAE,GAAGpB,uBACvB,IACEI,SAASa,UACLrB,MACEL,WAAWY,WAAWC,KAAK,CAAC,EAAE,EAAEA,KAAK,CAAC,EAAE,EAAEd,0BAC1CK,QAAQ,SACRD,MAAMmB,uBAER,MACN;QAACV;QAAWC;QAAOa;KAAQ,EAC3B;QAAEI,SAAS;IAAM;IAEnB,MAAMC,SAASxB,QACb,IACEV,wBACE,CAACgC,iBAAAA,SAAU,EAAE,EACVG,GAAG,CAAC,CAAC9B;gBAA0CA;mBAAlCJ,2BAA2BmC,QAAO/B,WAAAA,GAAG,CAAC,MAAM,YAAVA,WAAc,KAAKA;WAClEgC,MAAM,CAAC,CAACpB,QAAsC,CAAC,CAACA,SAEvD;QAACe;KAAO;IAEV,OAAO;QAAEE;QAAQlB,OAAOA;IAA0C;AACpE"}

package/src/lib/list-import.d.ts

@@ -0,0 +1,149 @@
+/**
+ * @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.
+ */
+/**
+ * The most addresses one uploaded file may name.
+ *
+ * A bound on the WORK an import represents, not a capacity limit: it refuses
+ * a FILE, before anything is written, and it can never drop a person already
+ * on a list or trim one to make room. A merchant with more than this splits
+ * the file, which is a nuisance; a merchant whose audience got silently
+ * truncated has an audience they cannot reason about.
+ *
+ * 50,000 is Klaviyo's shape rather than a number of our own — its only
+ * published hard import limit is a 50 MB CSV, which is the same statement in
+ * bytes. Above this the parse itself is the cost, and it happens in one
+ * request.
+ */
+export declare const LIST_IMPORT_MAX_ADDRESSES = 50000;
+/**
+ * Local parts that make an address a ROLE account.
+ *
+ * A mailbox several people read, or none. M3AAWG's Vetting BCP: their
+ * appearance on a customer list "may be indicative of poor acquisition
+ * practices" — a list built by scraping a website collects these, a list
+ * built from signups does not.
+ *
+ * Reported, never dropped. A merchant importing their own supplier contacts
+ * legitimately has `orders@`, and an importer that quietly removed addresses
+ * would be telling the operator a different number went on the list than did.
+ */
+export declare const ROLE_ACCOUNT_LOCAL_PARTS: readonly string[];
+/**
+ * Column names that say where the file came from, when the answer is "not
+ * from people who asked".
+ *
+ * M3AAWG names `jigsaw` and `append` specifically. The rest are the same tell
+ * in the vocabulary the data brokers actually use, and they are matched as
+ * substrings of a normalized header so `Appended Email` and `append_date`
+ * both hit.
+ *
+ * Every vendor surveyed prohibits purchased lists outright, Apple bans
+ * purchased, rented and appended lists, and M3AAWG calls appending "a direct
+ * violation of core M3AAWG values". This is not a policy we invented and the
+ * screening exists so that a merchant cannot attest their way past it without
+ * having been shown it.
+ */
+export declare const PURCHASE_TELL_COLUMNS: readonly string[];
+/** What the merchant's file says about one person. */
+export interface ListImportRow {
+    /** The source line, verbatim, so a bad one can be pointed at on screen. */
+    input: string;
+    /** The normalized address, or `null` when the line does not carry one. */
+    email: string | null;
+    /** A display name from the file, or `''`. */
+    name: string;
+    /**
+     * Where the file says this person opted in, or `''`.
+     *
+     * Evidence for the operator's assertion and never a basis of its own — see
+     * the module note.
+     */
+    declaredSource: string;
+    /** When the file says they opted in, or `''`, kept as written. */
+    declaredAt: string;
+}
+/** What one file turned out to be. */
+export interface ParsedListImport {
+    /** The header row's column names, or `[]` for a bare list of addresses. */
+    columns: string[];
+    /**
+     * One row per usable, first-seen address, plus one per unusable line.
+     *
+     * A repeat of an address already seen is collapsed and counted in
+     * {@link duplicates} rather than carried: the membership is keyed by the
+     * normalized address, so two lines would be one row and reporting them as
+     * two would tell the operator they are attesting for more people than they
+     * are. That is exactly the rule `resolveAddresses` applies to a paste.
+     */
+    rows: ListImportRow[];
+    /** Rows carrying a usable address. */
+    usable: number;
+    /** Lines that are not addresses. Reported, never dropped. */
+    unusable: number;
+    /** Repeat appearances of an address already counted. */
+    duplicates: number;
+    /** True when the file names more than {@link LIST_IMPORT_MAX_ADDRESSES}. */
+    overCeiling: boolean;
+}
+/** What the mechanical screening found. Signals, not verdicts. */
+export interface ListImportScreening {
+    /** Addresses at a shared or unattended mailbox. */
+    roleAccounts: string[];
+    /** Column names in the file that read as purchase or append tells. */
+    purchaseTellColumns: string[];
+    /** True when the file declares an opt-in source or date per row. */
+    declaresBasis: boolean;
+}
+/**
+ * Reads an uploaded or pasted file into rows.
+ *
+ * Handles the two shapes a merchant's list actually arrives in: a CSV with a
+ * header, and a bare column of addresses with no header at all. Both go
+ * through one parser — `parseCsv` — because a newline-separated list of
+ * addresses IS a single-column CSV, and a second code path for it would be a
+ * second place for the quoting rules to differ.
+ *
+ * ## Every line comes back, including the bad ones
+ *
+ * A file that silently discarded its malformed lines would tell an operator
+ * that 100 addresses went on the list when 94 did, and the six they never
+ * hear about are the six they typed wrong. This is the rule `resolveAddresses`
+ * already applies to a paste, restated for a file.
+ */
+export declare function parseListImport(text: string): ParsedListImport;
+/**
+ * The mechanical checks, over a parsed file.
+ *
+ * Cheap by construction: two substring passes and one set membership per
+ * address. It is deliberately not a deliverability service — Omnisend's own
+ * caveat on the one that exists is that "list cleaning confirms
+ * deliverability only and does not establish recipient consent", and consent
+ * is the only question this import actually turns on.
+ */
+export declare function screenListImport(parsed: Pick<ParsedListImport, 'columns' | 'rows'>): ListImportScreening;
+/**
+ * The sentence recorded as the REASON behind an imported person's basis.
+ *
+ * One line, built from what the file actually declared, so a compliance
+ * question about one address gets an answer about that address rather than
+ * "somebody ticked a box on an import once". Empty declarations produce the
+ * plain sentence rather than a sentence with holes in it.
+ */
+export declare function importedBasisReason(row: {
+    declaredSource: string;
+    declaredAt: string;
+}): string;

package/src/lib/list-import.js

@@ -0,0 +1,324 @@
+/**
+ * @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.
+ */ /**
+ * READING A MERCHANT'S CONTACT FILE, and saying what is in it.
+ *
+ * `docs/specs/email-competitive-gaps.md` G5 is the product gap — a customer
+ * arriving with a list has no way to bring it — and P4 is its condition: an
+ * importer is simultaneously the biggest onboarding blocker and the biggest
+ * abuse vector, so it ships WITH its controls or not at all. This module is
+ * the pure half of those controls. It parses, it de-duplicates, and it
+ * SCREENS. It decides nothing about consent and it enrolls nobody: the
+ * consent question belongs to `enrollment-basis`, which the one-address
+ * add path already asks, and an import that answered it a second way would be
+ * exactly the defect class the register has a P1 entry for.
+ *
+ * ## The screening reports, it never refuses
+ *
+ * M3AAWG's Vetting BCP supplies two cheap mechanical checks and both are
+ * signals rather than verdicts. A role account (`sales@`, `info@`) is, in
+ * M3AAWG's words, indicative of poor acquisition practice — it is not proof
+ * of one, and plenty of legitimate B2B lists carry a handful. A column named
+ * `jigsaw` or `append` is a purchase tell, and again a merchant may simply
+ * have named a column badly.
+ *
+ * So neither one drops an address. Both are put in front of the operator
+ * BEFORE they attest, because the attestation is the thing with teeth: an
+ * operator who states they have permission for a file whose headers say it
+ * was appended has made a claim their own console showed them the evidence
+ * against. That is what makes the record worth keeping.
+ *
+ * ## A declared basis per address, and why it is still an assertion
+ *
+ * P4 asks for "a declared basis per address, not one checkbox over the file".
+ * A file may carry an opt-in source and an opt-in date per row, and when it
+ * does they are read here and carried onto the import as evidence. They do
+ * NOT become the person's own opt-in. Nothing arriving in a spreadsheet is a
+ * checkbox somebody ticked; it is the merchant telling us about one, which is
+ * an operator assertion however many columns it arrives in. The basis stays
+ * `operator-attested` and the declared source rides along as the reason.
+ */ import { normalizeContactEmail } from "@aglyn/aglyn/app-utils/contacts";
+import { parseCsv } from "@aglyn/aglyn/app-utils/csv";
+/**
+ * The most addresses one uploaded file may name.
+ *
+ * A bound on the WORK an import represents, not a capacity limit: it refuses
+ * a FILE, before anything is written, and it can never drop a person already
+ * on a list or trim one to make room. A merchant with more than this splits
+ * the file, which is a nuisance; a merchant whose audience got silently
+ * truncated has an audience they cannot reason about.
+ *
+ * 50,000 is Klaviyo's shape rather than a number of our own — its only
+ * published hard import limit is a 50 MB CSV, which is the same statement in
+ * bytes. Above this the parse itself is the cost, and it happens in one
+ * request.
+ */ export const LIST_IMPORT_MAX_ADDRESSES = 50000;
+/**
+ * Local parts that make an address a ROLE account.
+ *
+ * A mailbox several people read, or none. M3AAWG's Vetting BCP: their
+ * appearance on a customer list "may be indicative of poor acquisition
+ * practices" — a list built by scraping a website collects these, a list
+ * built from signups does not.
+ *
+ * Reported, never dropped. A merchant importing their own supplier contacts
+ * legitimately has `orders@`, and an importer that quietly removed addresses
+ * would be telling the operator a different number went on the list than did.
+ */ export const ROLE_ACCOUNT_LOCAL_PARTS = [
+    'abuse',
+    'admin',
+    'billing',
+    'contact',
+    'enquiries',
+    'help',
+    'hello',
+    'hr',
+    'info',
+    'inquiries',
+    'mail',
+    'marketing',
+    'noreply',
+    'no-reply',
+    'office',
+    'orders',
+    'postmaster',
+    'sales',
+    'security',
+    'staff',
+    'support',
+    'team',
+    'webmaster'
+];
+/**
+ * Column names that say where the file came from, when the answer is "not
+ * from people who asked".
+ *
+ * M3AAWG names `jigsaw` and `append` specifically. The rest are the same tell
+ * in the vocabulary the data brokers actually use, and they are matched as
+ * substrings of a normalized header so `Appended Email` and `append_date`
+ * both hit.
+ *
+ * Every vendor surveyed prohibits purchased lists outright, Apple bans
+ * purchased, rented and appended lists, and M3AAWG calls appending "a direct
+ * violation of core M3AAWG values". This is not a policy we invented and the
+ * screening exists so that a merchant cannot attest their way past it without
+ * having been shown it.
+ */ export const PURCHASE_TELL_COLUMNS = [
+    'jigsaw',
+    'append',
+    'purchased',
+    'rented',
+    'databroker',
+    'data broker',
+    'leadgen',
+    'lead gen',
+    'scraped'
+];
+/** Header aliases that name the address column. */ const EMAIL_COLUMNS = [
+    'email',
+    'emailaddress',
+    'email address',
+    'e-mail',
+    'e-mail address',
+    'mail',
+    'contact email',
+    'primary email'
+];
+/** Header aliases that name a display name. */ const NAME_COLUMNS = [
+    'name',
+    'full name',
+    'fullname',
+    'display name',
+    'contact name',
+    'first name',
+    'firstname',
+    'given name'
+];
+/** Header aliases carrying the merchant's declared opt-in source. */ const OPT_IN_SOURCE_COLUMNS = [
+    'opt-in source',
+    'optin source',
+    'opt in source',
+    'consent source',
+    'signup source',
+    'subscription source',
+    'source'
+];
+/** Header aliases carrying the merchant's declared opt-in date. */ const OPT_IN_DATE_COLUMNS = [
+    'opt-in date',
+    'optin date',
+    'opt in date',
+    'consent date',
+    'signup date',
+    'subscribed at',
+    'date subscribed',
+    'confirmed at'
+];
+/** Normalizes a header cell for alias matching. */ function headerKey(value) {
+    return String(value != null ? value : '').trim().toLowerCase().replace(/[_]+/g, ' ').replace(/\s+/g, ' ');
+}
+/** The index of the first column matching one of `aliases`, or -1. */ function columnIndex(columns, aliases) {
+    const keys = columns.map(headerKey);
+    for (const alias of aliases){
+        const at = keys.indexOf(alias);
+        if (at !== -1) return at;
+    }
+    return -1;
+}
+/**
+ * Whether a parsed first row is a HEADER rather than a person.
+ *
+ * A header is a row with no address in it. That test rather than an alias
+ * match, because the common shape of a merchant's export is a header whose
+ * address column is called something we have never seen — and treating that
+ * file as headerless would import the word "Email Address" as a line that is
+ * not an address, and shift every subsequent column read by one.
+ *
+ * A one-column file of bare addresses therefore has no header, correctly:
+ * every row including the first carries an address.
+ */ function looksLikeHeader(cells) {
+    return !cells.some((cell)=>normalizeContactEmail(cell));
+}
+/**
+ * Reads an uploaded or pasted file into rows.
+ *
+ * Handles the two shapes a merchant's list actually arrives in: a CSV with a
+ * header, and a bare column of addresses with no header at all. Both go
+ * through one parser — `parseCsv` — because a newline-separated list of
+ * addresses IS a single-column CSV, and a second code path for it would be a
+ * second place for the quoting rules to differ.
+ *
+ * ## Every line comes back, including the bad ones
+ *
+ * A file that silently discarded its malformed lines would tell an operator
+ * that 100 addresses went on the list when 94 did, and the six they never
+ * hear about are the six they typed wrong. This is the rule `resolveAddresses`
+ * already applies to a paste, restated for a file.
+ */ export function parseListImport(text) {
+    const table = parseCsv(String(text != null ? text : ''));
+    if (!table.length) {
+        return {
+            columns: [],
+            rows: [],
+            usable: 0,
+            unusable: 0,
+            duplicates: 0,
+            overCeiling: false
+        };
+    }
+    const headed = table.length > 1 && looksLikeHeader(table[0]);
+    const columns = headed ? table[0].map((cell)=>String(cell != null ? cell : '').trim()) : [];
+    const body = headed ? table.slice(1) : table;
+    const emailAt = headed ? columnIndex(columns, EMAIL_COLUMNS) : 0;
+    const nameAt = headed ? columnIndex(columns, NAME_COLUMNS) : -1;
+    const sourceAt = headed ? columnIndex(columns, OPT_IN_SOURCE_COLUMNS) : -1;
+    const dateAt = headed ? columnIndex(columns, OPT_IN_DATE_COLUMNS) : -1;
+    const seen = new Set();
+    const rows = [];
+    let usable = 0;
+    let unusable = 0;
+    let duplicates = 0;
+    let overCeiling = false;
+    for (const cells of body){
+        var _cells_emailAt, _cells_find, _cells_nameAt, _cells_sourceAt, _cells_dateAt;
+        /*
+     * The named column when the header named one, and otherwise the first
+     * cell in the row that IS an address.
+     *
+     * The fallback is what makes an unrecognized header survivable: an
+     * export whose address column is called `Primary contact e-mail (work)`
+     * matches no alias, and refusing the whole file over a column name would
+     * be refusing the customer's migration over our vocabulary.
+     */ const raw = emailAt >= 0 && emailAt < cells.length ? String((_cells_emailAt = cells[emailAt]) != null ? _cells_emailAt : '') : (_cells_find = cells.find((cell)=>normalizeContactEmail(cell))) != null ? _cells_find : '';
+        const email = normalizeContactEmail(raw);
+        const input = String(raw != null ? raw : '').trim() || cells.join(', ').trim();
+        if (!email) {
+            unusable += 1;
+            rows.push({
+                input,
+                email: null,
+                name: '',
+                declaredSource: '',
+                declaredAt: ''
+            });
+            continue;
+        }
+        if (seen.has(email)) {
+            duplicates += 1;
+            continue;
+        }
+        if (seen.size >= LIST_IMPORT_MAX_ADDRESSES) {
+            overCeiling = true;
+            break;
+        }
+        seen.add(email);
+        usable += 1;
+        rows.push({
+            input,
+            email,
+            name: nameAt >= 0 ? String((_cells_nameAt = cells[nameAt]) != null ? _cells_nameAt : '').trim() : '',
+            declaredSource: sourceAt >= 0 ? String((_cells_sourceAt = cells[sourceAt]) != null ? _cells_sourceAt : '').trim() : '',
+            declaredAt: dateAt >= 0 ? String((_cells_dateAt = cells[dateAt]) != null ? _cells_dateAt : '').trim() : ''
+        });
+    }
+    return {
+        columns,
+        rows,
+        usable,
+        unusable,
+        duplicates,
+        overCeiling
+    };
+}
+/**
+ * The mechanical checks, over a parsed file.
+ *
+ * Cheap by construction: two substring passes and one set membership per
+ * address. It is deliberately not a deliverability service — Omnisend's own
+ * caveat on the one that exists is that "list cleaning confirms
+ * deliverability only and does not establish recipient consent", and consent
+ * is the only question this import actually turns on.
+ */ export function screenListImport(parsed) {
+    const roleAccounts = [];
+    for (const row of parsed.rows){
+        if (!row.email) continue;
+        const local = row.email.slice(0, row.email.indexOf('@'));
+        if (ROLE_ACCOUNT_LOCAL_PARTS.includes(local)) roleAccounts.push(row.email);
+    }
+    const purchaseTellColumns = parsed.columns.filter((column)=>{
+        const key = headerKey(column);
+        return PURCHASE_TELL_COLUMNS.some((tell)=>key.includes(tell));
+    });
+    return {
+        roleAccounts,
+        purchaseTellColumns,
+        declaresBasis: parsed.rows.some((row)=>!!row.declaredSource || !!row.declaredAt)
+    };
+}
+/**
+ * The sentence recorded as the REASON behind an imported person's basis.
+ *
+ * One line, built from what the file actually declared, so a compliance
+ * question about one address gets an answer about that address rather than
+ * "somebody ticked a box on an import once". Empty declarations produce the
+ * plain sentence rather than a sentence with holes in it.
+ */ export function importedBasisReason(row) {
+    const parts = [];
+    if (row.declaredSource) parts.push(`declared source: ${row.declaredSource}`);
+    if (row.declaredAt) parts.push(`declared opt-in: ${row.declaredAt}`);
+    return parts.length ? `Imported from a file, attested by the operator (${parts.join('; ')}).` : 'Imported from a file, attested by the operator.';
+}
+
+//# sourceMappingURL=list-import.js.map

package/src/lib/list-import.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/plugins/email/src/lib/list-import.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 * READING A MERCHANT'S CONTACT FILE, and saying what is in it.\n *\n * `docs/specs/email-competitive-gaps.md` G5 is the product gap — a customer\n * arriving with a list has no way to bring it — and P4 is its condition: an\n * importer is simultaneously the biggest onboarding blocker and the biggest\n * abuse vector, so it ships WITH its controls or not at all. This module is\n * the pure half of those controls. It parses, it de-duplicates, and it\n * SCREENS. It decides nothing about consent and it enrolls nobody: the\n * consent question belongs to `enrollment-basis`, which the one-address\n * add path already asks, and an import that answered it a second way would be\n * exactly the defect class the register has a P1 entry for.\n *\n * ## The screening reports, it never refuses\n *\n * M3AAWG's Vetting BCP supplies two cheap mechanical checks and both are\n * signals rather than verdicts. A role account (`sales@`, `info@`) is, in\n * M3AAWG's words, indicative of poor acquisition practice — it is not proof\n * of one, and plenty of legitimate B2B lists carry a handful. A column named\n * `jigsaw` or `append` is a purchase tell, and again a merchant may simply\n * have named a column badly.\n *\n * So neither one drops an address. Both are put in front of the operator\n * BEFORE they attest, because the attestation is the thing with teeth: an\n * operator who states they have permission for a file whose headers say it\n * was appended has made a claim their own console showed them the evidence\n * against. That is what makes the record worth keeping.\n *\n * ## A declared basis per address, and why it is still an assertion\n *\n * P4 asks for \"a declared basis per address, not one checkbox over the file\".\n * A file may carry an opt-in source and an opt-in date per row, and when it\n * does they are read here and carried onto the import as evidence. They do\n * NOT become the person's own opt-in. Nothing arriving in a spreadsheet is a\n * checkbox somebody ticked; it is the merchant telling us about one, which is\n * an operator assertion however many columns it arrives in. The basis stays\n * `operator-attested` and the declared source rides along as the reason.\n */\n\nimport { normalizeContactEmail } from '@aglyn/aglyn/app-utils/contacts'\nimport { parseCsv } from '@aglyn/aglyn/app-utils/csv'\n\n/**\n * The most addresses one uploaded file may name.\n *\n * A bound on the WORK an import represents, not a capacity limit: it refuses\n * a FILE, before anything is written, and it can never drop a person already\n * on a list or trim one to make room. A merchant with more than this splits\n * the file, which is a nuisance; a merchant whose audience got silently\n * truncated has an audience they cannot reason about.\n *\n * 50,000 is Klaviyo's shape rather than a number of our own — its only\n * published hard import limit is a 50 MB CSV, which is the same statement in\n * bytes. Above this the parse itself is the cost, and it happens in one\n * request.\n */\nexport const LIST_IMPORT_MAX_ADDRESSES = 50_000\n\n/**\n * Local parts that make an address a ROLE account.\n *\n * A mailbox several people read, or none. M3AAWG's Vetting BCP: their\n * appearance on a customer list \"may be indicative of poor acquisition\n * practices\" — a list built by scraping a website collects these, a list\n * built from signups does not.\n *\n * Reported, never dropped. A merchant importing their own supplier contacts\n * legitimately has `orders@`, and an importer that quietly removed addresses\n * would be telling the operator a different number went on the list than did.\n */\nexport const ROLE_ACCOUNT_LOCAL_PARTS: readonly string[] = [\n  'abuse',\n  'admin',\n  'billing',\n  'contact',\n  'enquiries',\n  'help',\n  'hello',\n  'hr',\n  'info',\n  'inquiries',\n  'mail',\n  'marketing',\n  'noreply',\n  'no-reply',\n  'office',\n  'orders',\n  'postmaster',\n  'sales',\n  'security',\n  'staff',\n  'support',\n  'team',\n  'webmaster',\n]\n\n/**\n * Column names that say where the file came from, when the answer is \"not\n * from people who asked\".\n *\n * M3AAWG names `jigsaw` and `append` specifically. The rest are the same tell\n * in the vocabulary the data brokers actually use, and they are matched as\n * substrings of a normalized header so `Appended Email` and `append_date`\n * both hit.\n *\n * Every vendor surveyed prohibits purchased lists outright, Apple bans\n * purchased, rented and appended lists, and M3AAWG calls appending \"a direct\n * violation of core M3AAWG values\". This is not a policy we invented and the\n * screening exists so that a merchant cannot attest their way past it without\n * having been shown it.\n */\nexport const PURCHASE_TELL_COLUMNS: readonly string[] = [\n  'jigsaw',\n  'append',\n  'purchased',\n  'rented',\n  'databroker',\n  'data broker',\n  'leadgen',\n  'lead gen',\n  'scraped',\n]\n\n/** Header aliases that name the address column. */\nconst EMAIL_COLUMNS = [\n  'email',\n  'emailaddress',\n  'email address',\n  'e-mail',\n  'e-mail address',\n  'mail',\n  'contact email',\n  'primary email',\n]\n\n/** Header aliases that name a display name. */\nconst NAME_COLUMNS = [\n  'name',\n  'full name',\n  'fullname',\n  'display name',\n  'contact name',\n  'first name',\n  'firstname',\n  'given name',\n]\n\n/** Header aliases carrying the merchant's declared opt-in source. */\nconst OPT_IN_SOURCE_COLUMNS = [\n  'opt-in source',\n  'optin source',\n  'opt in source',\n  'consent source',\n  'signup source',\n  'subscription source',\n  'source',\n]\n\n/** Header aliases carrying the merchant's declared opt-in date. */\nconst OPT_IN_DATE_COLUMNS = [\n  'opt-in date',\n  'optin date',\n  'opt in date',\n  'consent date',\n  'signup date',\n  'subscribed at',\n  'date subscribed',\n  'confirmed at',\n]\n\n/** What the merchant's file says about one person. */\nexport interface ListImportRow {\n  /** The source line, verbatim, so a bad one can be pointed at on screen. */\n  input: string\n  /** The normalized address, or `null` when the line does not carry one. */\n  email: string | null\n  /** A display name from the file, or `''`. */\n  name: string\n  /**\n   * Where the file says this person opted in, or `''`.\n   *\n   * Evidence for the operator's assertion and never a basis of its own — see\n   * the module note.\n   */\n  declaredSource: string\n  /** When the file says they opted in, or `''`, kept as written. */\n  declaredAt: string\n}\n\n/** What one file turned out to be. */\nexport interface ParsedListImport {\n  /** The header row's column names, or `[]` for a bare list of addresses. */\n  columns: string[]\n  /**\n   * One row per usable, first-seen address, plus one per unusable line.\n   *\n   * A repeat of an address already seen is collapsed and counted in\n   * {@link duplicates} rather than carried: the membership is keyed by the\n   * normalized address, so two lines would be one row and reporting them as\n   * two would tell the operator they are attesting for more people than they\n   * are. That is exactly the rule `resolveAddresses` applies to a paste.\n   */\n  rows: ListImportRow[]\n  /** Rows carrying a usable address. */\n  usable: number\n  /** Lines that are not addresses. Reported, never dropped. */\n  unusable: number\n  /** Repeat appearances of an address already counted. */\n  duplicates: number\n  /** True when the file names more than {@link LIST_IMPORT_MAX_ADDRESSES}. */\n  overCeiling: boolean\n}\n\n/** What the mechanical screening found. Signals, not verdicts. */\nexport interface ListImportScreening {\n  /** Addresses at a shared or unattended mailbox. */\n  roleAccounts: string[]\n  /** Column names in the file that read as purchase or append tells. */\n  purchaseTellColumns: string[]\n  /** True when the file declares an opt-in source or date per row. */\n  declaresBasis: boolean\n}\n\n/** Normalizes a header cell for alias matching. */\nfunction headerKey(value: string): string {\n  return String(value ?? '')\n    .trim()\n    .toLowerCase()\n    .replace(/[_]+/g, ' ')\n    .replace(/\\s+/g, ' ')\n}\n\n/** The index of the first column matching one of `aliases`, or -1. */\nfunction columnIndex(columns: string[], aliases: readonly string[]): number {\n  const keys = columns.map(headerKey)\n  for (const alias of aliases) {\n    const at = keys.indexOf(alias)\n    if (at !== -1) return at\n  }\n  return -1\n}\n\n/**\n * Whether a parsed first row is a HEADER rather than a person.\n *\n * A header is a row with no address in it. That test rather than an alias\n * match, because the common shape of a merchant's export is a header whose\n * address column is called something we have never seen — and treating that\n * file as headerless would import the word \"Email Address\" as a line that is\n * not an address, and shift every subsequent column read by one.\n *\n * A one-column file of bare addresses therefore has no header, correctly:\n * every row including the first carries an address.\n */\nfunction looksLikeHeader(cells: readonly string[]): boolean {\n  return !cells.some((cell) => normalizeContactEmail(cell))\n}\n\n/**\n * Reads an uploaded or pasted file into rows.\n *\n * Handles the two shapes a merchant's list actually arrives in: a CSV with a\n * header, and a bare column of addresses with no header at all. Both go\n * through one parser — `parseCsv` — because a newline-separated list of\n * addresses IS a single-column CSV, and a second code path for it would be a\n * second place for the quoting rules to differ.\n *\n * ## Every line comes back, including the bad ones\n *\n * A file that silently discarded its malformed lines would tell an operator\n * that 100 addresses went on the list when 94 did, and the six they never\n * hear about are the six they typed wrong. This is the rule `resolveAddresses`\n * already applies to a paste, restated for a file.\n */\nexport function parseListImport(text: string): ParsedListImport {\n  const table = parseCsv(String(text ?? ''))\n  if (!table.length) {\n    return {\n      columns: [],\n      rows: [],\n      usable: 0,\n      unusable: 0,\n      duplicates: 0,\n      overCeiling: false,\n    }\n  }\n  const headed = table.length > 1 && looksLikeHeader(table[0])\n  const columns = headed ? table[0].map((cell) => String(cell ?? '').trim()) : []\n  const body = headed ? table.slice(1) : table\n\n  const emailAt = headed ? columnIndex(columns, EMAIL_COLUMNS) : 0\n  const nameAt = headed ? columnIndex(columns, NAME_COLUMNS) : -1\n  const sourceAt = headed ? columnIndex(columns, OPT_IN_SOURCE_COLUMNS) : -1\n  const dateAt = headed ? columnIndex(columns, OPT_IN_DATE_COLUMNS) : -1\n\n  const seen = new Set<string>()\n  const rows: ListImportRow[] = []\n  let usable = 0\n  let unusable = 0\n  let duplicates = 0\n  let overCeiling = false\n\n  for (const cells of body) {\n    /*\n     * The named column when the header named one, and otherwise the first\n     * cell in the row that IS an address.\n     *\n     * The fallback is what makes an unrecognized header survivable: an\n     * export whose address column is called `Primary contact e-mail (work)`\n     * matches no alias, and refusing the whole file over a column name would\n     * be refusing the customer's migration over our vocabulary.\n     */\n    const raw =\n      emailAt >= 0 && emailAt < cells.length\n        ? String(cells[emailAt] ?? '')\n        : (cells.find((cell) => normalizeContactEmail(cell)) ?? '')\n    const email = normalizeContactEmail(raw)\n    const input = String(raw ?? '').trim() || cells.join(', ').trim()\n    if (!email) {\n      unusable += 1\n      rows.push({\n        input,\n        email: null,\n        name: '',\n        declaredSource: '',\n        declaredAt: '',\n      })\n      continue\n    }\n    if (seen.has(email)) {\n      duplicates += 1\n      continue\n    }\n    if (seen.size >= LIST_IMPORT_MAX_ADDRESSES) {\n      overCeiling = true\n      break\n    }\n    seen.add(email)\n    usable += 1\n    rows.push({\n      input,\n      email,\n      name: nameAt >= 0 ? String(cells[nameAt] ?? '').trim() : '',\n      declaredSource: sourceAt >= 0 ? String(cells[sourceAt] ?? '').trim() : '',\n      declaredAt: dateAt >= 0 ? String(cells[dateAt] ?? '').trim() : '',\n    })\n  }\n\n  return { columns, rows, usable, unusable, duplicates, overCeiling }\n}\n\n/**\n * The mechanical checks, over a parsed file.\n *\n * Cheap by construction: two substring passes and one set membership per\n * address. It is deliberately not a deliverability service — Omnisend's own\n * caveat on the one that exists is that \"list cleaning confirms\n * deliverability only and does not establish recipient consent\", and consent\n * is the only question this import actually turns on.\n */\nexport function screenListImport(\n  parsed: Pick<ParsedListImport, 'columns' | 'rows'>,\n): ListImportScreening {\n  const roleAccounts: string[] = []\n  for (const row of parsed.rows) {\n    if (!row.email) continue\n    const local = row.email.slice(0, row.email.indexOf('@'))\n    if (ROLE_ACCOUNT_LOCAL_PARTS.includes(local)) roleAccounts.push(row.email)\n  }\n  const purchaseTellColumns = parsed.columns.filter((column) => {\n    const key = headerKey(column)\n    return PURCHASE_TELL_COLUMNS.some((tell) => key.includes(tell))\n  })\n  return {\n    roleAccounts,\n    purchaseTellColumns,\n    declaresBasis: parsed.rows.some(\n      (row) => !!row.declaredSource || !!row.declaredAt,\n    ),\n  }\n}\n\n/**\n * The sentence recorded as the REASON behind an imported person's basis.\n *\n * One line, built from what the file actually declared, so a compliance\n * question about one address gets an answer about that address rather than\n * \"somebody ticked a box on an import once\". Empty declarations produce the\n * plain sentence rather than a sentence with holes in it.\n */\nexport function importedBasisReason(row: {\n  declaredSource: string\n  declaredAt: string\n}): string {\n  const parts: string[] = []\n  if (row.declaredSource) parts.push(`declared source: ${row.declaredSource}`)\n  if (row.declaredAt) parts.push(`declared opt-in: ${row.declaredAt}`)\n  return parts.length\n    ? `Imported from a file, attested by the operator (${parts.join('; ')}).`\n    : 'Imported from a file, attested by the operator.'\n}\n"],"names":["normalizeContactEmail","parseCsv","LIST_IMPORT_MAX_ADDRESSES","ROLE_ACCOUNT_LOCAL_PARTS","PURCHASE_TELL_COLUMNS","EMAIL_COLUMNS","NAME_COLUMNS","OPT_IN_SOURCE_COLUMNS","OPT_IN_DATE_COLUMNS","headerKey","value","String","trim","toLowerCase","replace","columnIndex","columns","aliases","keys","map","alias","at","indexOf","looksLikeHeader","cells","some","cell","parseListImport","text","table","length","rows","usable","unusable","duplicates","overCeiling","headed","body","slice","emailAt","nameAt","sourceAt","dateAt","seen","Set","raw","find","email","input","join","push","name","declaredSource","declaredAt","has","size","add","screenListImport","parsed","roleAccounts","row","local","includes","purchaseTellColumns","filter","column","key","tell","declaresBasis","importedBasisReason","parts"],"mappings":"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"}

package/src/lib/model/email-record-routes.d.ts

@@ -0,0 +1,22 @@
+/**
+ * @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.
+ */
+/**
+ * Called from the console registrar. The owner is named rather than read off
+ * the loader's marker, so the routes register the same way under a spec that
+ * calls the registrar directly.
+ */
+export declare function registerEmailRecordRoutes(): void;