@aglyn/plugins-email 1.0.0-beta.221 → 1.0.0-beta.223

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

@@ -15,7 +15,52 @@
  * limitations under the License.
  */
 /**
- * The most addresses one uploaded file may name.
+ * WHAT A MERCHANT'S CONTACT FILE SAYS ABOUT ITSELF — the pure half of the
+ * list-member import's controls.
+ *
+ * `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. The import runs
+ * on the platform's transfer framework (AGL-3529), which reads the file,
+ * maps its columns, collapses repeated addresses and reports the lines that
+ * are not addresses; this module is what the framework cannot know: the
+ * header spellings that mean an address, a name or a declared opt-in, and
+ * the two 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 as
+ * warnings they acknowledge BEFORE the import writes, beside the statement of
+ * permission, 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 and carried onto the membership 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.
+ */
+/**
+ * The most rows one uploaded file may carry — the list-member resource's
+ * `limits.maxRows` in `plugins.config.json`, which the transfer engine
+ * enforces at the upload (`list-import.spec.ts` holds the two equal).
  *
  * 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
@@ -25,8 +70,7 @@
  *
  * 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.
+ * bytes.
  */
 export declare const LIST_IMPORT_MAX_ADDRESSES = 50000;
 /**
@@ -58,83 +102,28 @@ export declare const ROLE_ACCOUNT_LOCAL_PARTS: readonly string[];
  * 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;
-}
+/** Header spellings that name the address column. */
+export declare const LIST_IMPORT_EMAIL_COLUMNS: readonly string[];
 /**
- * Reads an uploaded or pasted file into rows.
+ * Header spellings that name the member's display name.
  *
- * 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.
+ * Not `First name`: a file that splits the name maps its parts to the
+ * contact record's first and last name, and the membership's name is
+ * composed from them when no column names it whole.
  */
-export declare function parseListImport(text: string): ParsedListImport;
+export declare const LIST_IMPORT_NAME_COLUMNS: readonly string[];
+/** Header spellings carrying the merchant's declared opt-in source. */
+export declare const LIST_IMPORT_OPT_IN_SOURCE_COLUMNS: readonly string[];
+/** Header spellings carrying the merchant's declared opt-in date. */
+export declare const LIST_IMPORT_OPT_IN_DATE_COLUMNS: readonly string[];
+/** Whether a normalized address is at a shared or unattended mailbox. */
+export declare function isRoleAccount(email: string | null | undefined): boolean;
 /**
- * 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.
+ * The file's column names that read as purchase or append tells — every
+ * column, mapped or not: a column the operator chose to ignore still says
+ * where the file came from.
  */
-export declare function screenListImport(parsed: Pick<ParsedListImport, 'columns' | 'rows'>): ListImportScreening;
+export declare function purchaseTellColumns(headers: readonly string[]): string[];
 /**
  * The sentence recorded as the REASON behind an imported person's basis.
  *

package/src/lib/list-import.js

@@ -14,15 +14,19 @@
  * 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.
+ * WHAT A MERCHANT'S CONTACT FILE SAYS ABOUT ITSELF — the pure half of the
+ * list-member import's controls.
  *
  * `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
+ * abuse vector, so it ships WITH its controls or not at all. The import runs
+ * on the platform's transfer framework (AGL-3529), which reads the file,
+ * maps its columns, collapses repeated addresses and reports the lines that
+ * are not addresses; this module is what the framework cannot know: the
+ * header spellings that mean an address, a name or a declared opt-in, and
+ * the two 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.
  *
@@ -35,25 +39,26 @@
  * `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.
+ * So neither one drops an address. Both are put in front of the operator as
+ * warnings they acknowledge BEFORE the import writes, beside the statement of
+ * permission, 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
+ * does they are read and carried onto the membership 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.
+ */ /**
+ * The most rows one uploaded file may carry — the list-member resource's
+ * `limits.maxRows` in `plugins.config.json`, which the transfer engine
+ * enforces at the upload (`list-import.spec.ts` holds the two equal).
  *
  * 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
@@ -63,8 +68,7 @@ import { parseCsv } from "@aglyn/aglyn/app-utils/csv";
  *
  * 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.
+ * bytes.
  */ export const LIST_IMPORT_MAX_ADDRESSES = 50000;
 /**
  * Local parts that make an address a ROLE account.
@@ -127,7 +131,7 @@ import { parseCsv } from "@aglyn/aglyn/app-utils/csv";
     'lead gen',
     'scraped'
 ];
-/** Header aliases that name the address column. */ const EMAIL_COLUMNS = [
+/** Header spellings that name the address column. */ export const LIST_IMPORT_EMAIL_COLUMNS = [
     'email',
     'emailaddress',
     'email address',
@@ -137,17 +141,20 @@ import { parseCsv } from "@aglyn/aglyn/app-utils/csv";
     'contact email',
     'primary email'
 ];
-/** Header aliases that name a display name. */ const NAME_COLUMNS = [
+/**
+ * Header spellings that name the member's display name.
+ *
+ * Not `First name`: a file that splits the name maps its parts to the
+ * contact record's first and last name, and the membership's name is
+ * composed from them when no column names it whole.
+ */ export const LIST_IMPORT_NAME_COLUMNS = [
     'name',
     'full name',
     'fullname',
     'display name',
-    'contact name',
-    'first name',
-    'firstname',
-    'given name'
+    'contact name'
 ];
-/** Header aliases carrying the merchant's declared opt-in source. */ const OPT_IN_SOURCE_COLUMNS = [
+/** Header spellings carrying the merchant's declared opt-in source. */ export const LIST_IMPORT_OPT_IN_SOURCE_COLUMNS = [
     'opt-in source',
     'optin source',
     'opt in source',
@@ -156,7 +163,7 @@ import { parseCsv } from "@aglyn/aglyn/app-utils/csv";
     'subscription source',
     'source'
 ];
-/** Header aliases carrying the merchant's declared opt-in date. */ const OPT_IN_DATE_COLUMNS = [
+/** Header spellings carrying the merchant's declared opt-in date. */ export const LIST_IMPORT_OPT_IN_DATE_COLUMNS = [
     'opt-in date',
     'optin date',
     'opt in date',
@@ -166,146 +173,24 @@ import { parseCsv } from "@aglyn/aglyn/app-utils/csv";
     'date subscribed',
     'confirmed at'
 ];
-/** Normalizes a header cell for alias matching. */ function headerKey(value) {
+/** Normalizes a header cell for the purchase-tell match. */ 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
-    };
+/** Whether a normalized address is at a shared or unattended mailbox. */ export function isRoleAccount(email) {
+    const address = String(email != null ? email : '');
+    const at = address.indexOf('@');
+    if (at <= 0) return false;
+    return ROLE_ACCOUNT_LOCAL_PARTS.includes(address.slice(0, at).toLowerCase());
 }
 /**
- * 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)=>{
+ * The file's column names that read as purchase or append tells — every
+ * column, mapped or not: a column the operator chose to ignore still says
+ * where the file came from.
+ */ export function purchaseTellColumns(headers) {
+    return headers.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.

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

@@ -1 +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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"}
+{"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 * WHAT A MERCHANT'S CONTACT FILE SAYS ABOUT ITSELF — the pure half of the\n * list-member import's controls.\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. The import runs\n * on the platform's transfer framework (AGL-3529), which reads the file,\n * maps its columns, collapses repeated addresses and reports the lines that\n * are not addresses; this module is what the framework cannot know: the\n * header spellings that mean an address, a name or a declared opt-in, and\n * the two SCREENS. It decides nothing about consent and it enrolls nobody:\n * the 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 as\n * warnings they acknowledge BEFORE the import writes, beside the statement of\n * permission, because the attestation is the thing with teeth: an operator who\n * states they have permission for a file whose headers say it was appended\n * has made a claim their own console showed them the evidence against. That\n * 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 and carried onto the membership 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\n/**\n * The most rows one uploaded file may carry — the list-member resource's\n * `limits.maxRows` in `plugins.config.json`, which the transfer engine\n * enforces at the upload (`list-import.spec.ts` holds the two equal).\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.\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 spellings that name the address column. */\nexport const LIST_IMPORT_EMAIL_COLUMNS: readonly string[] = [\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/**\n * Header spellings that name the member's display name.\n *\n * Not `First name`: a file that splits the name maps its parts to the\n * contact record's first and last name, and the membership's name is\n * composed from them when no column names it whole.\n */\nexport const LIST_IMPORT_NAME_COLUMNS: readonly string[] = [\n  'name',\n  'full name',\n  'fullname',\n  'display name',\n  'contact name',\n]\n\n/** Header spellings carrying the merchant's declared opt-in source. */\nexport const LIST_IMPORT_OPT_IN_SOURCE_COLUMNS: readonly string[] = [\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 spellings carrying the merchant's declared opt-in date. */\nexport const LIST_IMPORT_OPT_IN_DATE_COLUMNS: readonly string[] = [\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/** Normalizes a header cell for the purchase-tell match. */\nfunction headerKey(value: string): string {\n  return String(value ?? '')\n    .trim()\n    .toLowerCase()\n    .replace(/[_]+/g, ' ')\n    .replace(/\\s+/g, ' ')\n}\n\n/** Whether a normalized address is at a shared or unattended mailbox. */\nexport function isRoleAccount(email: string | null | undefined): boolean {\n  const address = String(email ?? '')\n  const at = address.indexOf('@')\n  if (at <= 0) return false\n  return ROLE_ACCOUNT_LOCAL_PARTS.includes(address.slice(0, at).toLowerCase())\n}\n\n/**\n * The file's column names that read as purchase or append tells — every\n * column, mapped or not: a column the operator chose to ignore still says\n * where the file came from.\n */\nexport function purchaseTellColumns(headers: readonly string[]): string[] {\n  return headers.filter((column) => {\n    const key = headerKey(column)\n    return PURCHASE_TELL_COLUMNS.some((tell) => key.includes(tell))\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":["LIST_IMPORT_MAX_ADDRESSES","ROLE_ACCOUNT_LOCAL_PARTS","PURCHASE_TELL_COLUMNS","LIST_IMPORT_EMAIL_COLUMNS","LIST_IMPORT_NAME_COLUMNS","LIST_IMPORT_OPT_IN_SOURCE_COLUMNS","LIST_IMPORT_OPT_IN_DATE_COLUMNS","headerKey","value","String","trim","toLowerCase","replace","isRoleAccount","email","address","at","indexOf","includes","slice","purchaseTellColumns","headers","filter","column","key","some","tell","importedBasisReason","row","parts","declaredSource","push","declaredAt","length","join"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA0CC,GAED;;;;;;;;;;;;;;CAcC,GACD,OAAO,MAAMA,4BAA4B,MAAM;AAE/C;;;;;;;;;;;CAWC,GACD,OAAO,MAAMC,2BAA8C;IACzD;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;CACD,CAAA;AAED;;;;;;;;;;;;;;CAcC,GACD,OAAO,MAAMC,wBAA2C;IACtD;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;CACD,CAAA;AAED,mDAAmD,GACnD,OAAO,MAAMC,4BAA+C;IAC1D;IACA;IACA;IACA;IACA;IACA;IACA;IACA;CACD,CAAA;AAED;;;;;;CAMC,GACD,OAAO,MAAMC,2BAA8C;IACzD;IACA;IACA;IACA;IACA;CACD,CAAA;AAED,qEAAqE,GACrE,OAAO,MAAMC,oCAAuD;IAClE;IACA;IACA;IACA;IACA;IACA;IACA;CACD,CAAA;AAED,mEAAmE,GACnE,OAAO,MAAMC,kCAAqD;IAChE;IACA;IACA;IACA;IACA;IACA;IACA;IACA;CACD,CAAA;AAED,0DAA0D,GAC1D,SAASC,UAAUC,KAAa;IAC9B,OAAOC,OAAOD,gBAAAA,QAAS,IACpBE,IAAI,GACJC,WAAW,GACXC,OAAO,CAAC,SAAS,KACjBA,OAAO,CAAC,QAAQ;AACrB;AAEA,uEAAuE,GACvE,OAAO,SAASC,cAAcC,KAAgC;IAC5D,MAAMC,UAAUN,OAAOK,gBAAAA,QAAS;IAChC,MAAME,KAAKD,QAAQE,OAAO,CAAC;IAC3B,IAAID,MAAM,GAAG,OAAO;IACpB,OAAOf,yBAAyBiB,QAAQ,CAACH,QAAQI,KAAK,CAAC,GAAGH,IAAIL,WAAW;AAC3E;AAEA;;;;CAIC,GACD,OAAO,SAASS,oBAAoBC,OAA0B;IAC5D,OAAOA,QAAQC,MAAM,CAAC,CAACC;QACrB,MAAMC,MAAMjB,UAAUgB;QACtB,OAAOrB,sBAAsBuB,IAAI,CAAC,CAACC,OAASF,IAAIN,QAAQ,CAACQ;IAC3D;AACF;AAEA;;;;;;;CAOC,GACD,OAAO,SAASC,oBAAoBC,GAGnC;IACC,MAAMC,QAAkB,EAAE;IAC1B,IAAID,IAAIE,cAAc,EAAED,MAAME,IAAI,CAAC,CAAC,iBAAiB,EAAEH,IAAIE,cAAc,EAAE;IAC3E,IAAIF,IAAII,UAAU,EAAEH,MAAME,IAAI,CAAC,CAAC,iBAAiB,EAAEH,IAAII,UAAU,EAAE;IACnE,OAAOH,MAAMI,MAAM,GACf,CAAC,gDAAgD,EAAEJ,MAAMK,IAAI,CAAC,MAAM,EAAE,CAAC,GACvE;AACN"}

package/src/lib/model/email-topic-catalog.d.ts

@@ -34,3 +34,27 @@ export declare function emailTopicsFromDocs(docs: ReadonlyArray<{
     id: string;
     data: () => Record<string, unknown> | undefined;
 }>): SubscriptionTopic[];
+/** What one topic's document says: the fields a person edits on the topic's page. */
+export interface EmailTopicFields {
+    name: string;
+    description: string;
+    archived: boolean;
+    /** `true`/`false` decides for this stream; `null` clears it back to the site's setting; omitted leaves it. */
+    doubleOptIn?: boolean | null;
+}
+/**
+ * The document every writer of the catalog stores — the console's topic
+ * page and list (`writeEmailTopic`) and a package import — so a topic
+ * written by either is the same document. Merged into what is stored.
+ *
+ * `archived` is written every time, because a merge that omitted it would
+ * carry an old retirement forward. `doubleOptIn` is the one field with three
+ * states, so it is written only when given, and `clear` (the SDK's
+ * `deleteField()`) is how `null` returns it to the site's setting.
+ */
+export declare function emailTopicDocument<Clear>(topic: EmailTopicFields, clear: Clear): {
+    name: string;
+    description: string;
+    archived: boolean;
+    doubleOptIn?: boolean | Clear;
+};

package/src/lib/model/email-topic-catalog.js

@@ -1,3 +1,4 @@
+import { _ as _extends } from "@swc/helpers/_/_extends";
 /**
  * @license
  * Copyright 2026 Aglyn LLC
@@ -32,5 +33,23 @@
         return normalizeSubscriptionTopic(doc.id, (_doc_data = doc.data()) != null ? _doc_data : null);
     }).filter((topic)=>!!topic);
 }
+/**
+ * The document every writer of the catalog stores — the console's topic
+ * page and list (`writeEmailTopic`) and a package import — so a topic
+ * written by either is the same document. Merged into what is stored.
+ *
+ * `archived` is written every time, because a merge that omitted it would
+ * carry an old retirement forward. `doubleOptIn` is the one field with three
+ * states, so it is written only when given, and `clear` (the SDK's
+ * `deleteField()`) is how `null` returns it to the site's setting.
+ */ export function emailTopicDocument(topic, clear) {
+    return _extends({
+        name: topic.name,
+        description: topic.description,
+        archived: topic.archived
+    }, topic.doubleOptIn === undefined ? {} : {
+        doubleOptIn: topic.doubleOptIn === null ? clear : topic.doubleOptIn
+    });
+}
 
 //# sourceMappingURL=email-topic-catalog.js.map

package/src/lib/model/email-topic-catalog.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../../../../../libs/plugins/email/src/lib/model/email-topic-catalog.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 {\n  normalizeSubscriptionTopic,\n  type SubscriptionTopic,\n} from '@aglyn/aglyn/app-utils/subscription-topics'\n\n/**\n * THE TOPIC CATALOG AN ORG AUTHORS — this plugin's storage.\n *\n * The streams themselves, what a recipient's opt-out means and how a send\n * honors it are the mail rail's (`app-utils/subscription-topics.ts`), and the\n * built-in streams are declared by the plugins that send under them. What an\n * org writes — a built-in renamed, re-described, archived or confirmed, and\n * the topics it adds of its own — is stored here, one document per topic, at\n * `orgs/{orgId}/emailTopics/{topicId}`, org-shared like `lists`. Another\n * plugin that needs an org's catalog asks the `subscriptionTopic` record\n * index this plugin publishes, never the collection.\n */\n\n/** `orgs/{orgId}/emailTopics` — the catalog, org-shared like `lists`. */\nexport const EMAIL_TOPICS_COLLECTION = 'emailTopics'\n\n/** The stored documents as topics, skipping any that is not one. */\nexport function emailTopicsFromDocs(\n  docs: ReadonlyArray<{ id: string; data: () => Record<string, unknown> | undefined }>,\n): SubscriptionTopic[] {\n  return docs\n    .map((doc) => normalizeSubscriptionTopic(doc.id, doc.data() ?? null))\n    .filter((topic): topic is SubscriptionTopic => !!topic)\n}\n"],"names":["normalizeSubscriptionTopic","EMAIL_TOPICS_COLLECTION","emailTopicsFromDocs","docs","map","doc","id","data","filter","topic"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED,SACEA,0BAA0B,QAErB,6CAA4C;AAEnD;;;;;;;;;;;CAWC,GAED,uEAAuE,GACvE,OAAO,MAAMC,0BAA0B,cAAa;AAEpD,kEAAkE,GAClE,OAAO,SAASC,oBACdC,IAAoF;IAEpF,OAAOA,KACJC,GAAG,CAAC,CAACC;YAA2CA;eAAnCL,2BAA2BK,IAAIC,EAAE,GAAED,YAAAA,IAAIE,IAAI,cAARF,YAAc;OAC9DG,MAAM,CAAC,CAACC,QAAsC,CAAC,CAACA;AACrD"}
+{"version":3,"sources":["../../../../../../../libs/plugins/email/src/lib/model/email-topic-catalog.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 {\n  normalizeSubscriptionTopic,\n  type SubscriptionTopic,\n} from '@aglyn/aglyn/app-utils/subscription-topics'\n\n/**\n * THE TOPIC CATALOG AN ORG AUTHORS — this plugin's storage.\n *\n * The streams themselves, what a recipient's opt-out means and how a send\n * honors it are the mail rail's (`app-utils/subscription-topics.ts`), and the\n * built-in streams are declared by the plugins that send under them. What an\n * org writes — a built-in renamed, re-described, archived or confirmed, and\n * the topics it adds of its own — is stored here, one document per topic, at\n * `orgs/{orgId}/emailTopics/{topicId}`, org-shared like `lists`. Another\n * plugin that needs an org's catalog asks the `subscriptionTopic` record\n * index this plugin publishes, never the collection.\n */\n\n/** `orgs/{orgId}/emailTopics` — the catalog, org-shared like `lists`. */\nexport const EMAIL_TOPICS_COLLECTION = 'emailTopics'\n\n/** The stored documents as topics, skipping any that is not one. */\nexport function emailTopicsFromDocs(\n  docs: ReadonlyArray<{ id: string; data: () => Record<string, unknown> | undefined }>,\n): SubscriptionTopic[] {\n  return docs\n    .map((doc) => normalizeSubscriptionTopic(doc.id, doc.data() ?? null))\n    .filter((topic): topic is SubscriptionTopic => !!topic)\n}\n\n/** What one topic's document says: the fields a person edits on the topic's page. */\nexport interface EmailTopicFields {\n  name: string\n  description: string\n  archived: boolean\n  /** `true`/`false` decides for this stream; `null` clears it back to the site's setting; omitted leaves it. */\n  doubleOptIn?: boolean | null\n}\n\n/**\n * The document every writer of the catalog stores — the console's topic\n * page and list (`writeEmailTopic`) and a package import — so a topic\n * written by either is the same document. Merged into what is stored.\n *\n * `archived` is written every time, because a merge that omitted it would\n * carry an old retirement forward. `doubleOptIn` is the one field with three\n * states, so it is written only when given, and `clear` (the SDK's\n * `deleteField()`) is how `null` returns it to the site's setting.\n */\nexport function emailTopicDocument<Clear>(\n  topic: EmailTopicFields,\n  clear: Clear,\n): { name: string; description: string; archived: boolean; doubleOptIn?: boolean | Clear } {\n  return {\n    name: topic.name,\n    description: topic.description,\n    archived: topic.archived,\n    ...(topic.doubleOptIn === undefined\n      ? {}\n      : { doubleOptIn: topic.doubleOptIn === null ? clear : topic.doubleOptIn }),\n  }\n}\n"],"names":["normalizeSubscriptionTopic","EMAIL_TOPICS_COLLECTION","emailTopicsFromDocs","docs","map","doc","id","data","filter","topic","emailTopicDocument","clear","name","description","archived","doubleOptIn","undefined"],"mappings":";AAAA;;;;;;;;;;;;;;;CAeC,GAED,SACEA,0BAA0B,QAErB,6CAA4C;AAEnD;;;;;;;;;;;CAWC,GAED,uEAAuE,GACvE,OAAO,MAAMC,0BAA0B,cAAa;AAEpD,kEAAkE,GAClE,OAAO,SAASC,oBACdC,IAAoF;IAEpF,OAAOA,KACJC,GAAG,CAAC,CAACC;YAA2CA;eAAnCL,2BAA2BK,IAAIC,EAAE,GAAED,YAAAA,IAAIE,IAAI,cAARF,YAAc;OAC9DG,MAAM,CAAC,CAACC,QAAsC,CAAC,CAACA;AACrD;AAWA;;;;;;;;;CASC,GACD,OAAO,SAASC,mBACdD,KAAuB,EACvBE,KAAY;IAEZ,OAAO;QACLC,MAAMH,MAAMG,IAAI;QAChBC,aAAaJ,MAAMI,WAAW;QAC9BC,UAAUL,MAAMK,QAAQ;OACpBL,MAAMM,WAAW,KAAKC,YACtB,CAAC,IACD;QAAED,aAAaN,MAAMM,WAAW,KAAK,OAAOJ,QAAQF,MAAMM,WAAW;IAAC;AAE9E"}

package/src/lib/model/index.d.ts

@@ -20,36 +20,11 @@
  * other plugins/apps via `@aglyn/plugins-email/model`.
  */
 export { renderEmailHtml, substituteMergeTokens, resolveMergeTags, type EmailRenderOptions, type EmailRenderProduct, type RenderedEmail, } from '@aglyn/shared-util-email';
-/**
- * Campaign reporting: the rate math, the populations the send recorded, and
- * the link rollup — pure, so every denominator is named once and provable
- * rather than chosen in JSX.
- */
-export * from '@aglyn/shared-ui-email-campaigns/model/campaign-report';
-/**
- * The same math taken across every message sent from one TEMPLATE. Separate
- * from `campaign-report` because a sum has a membership: which messages went
- * into it, and therefore which population the rate describes.
- */
-export * from './template-report';
-/** Reading one message record — its state, and when it went out. */
-export * from '@aglyn/shared-ui-email-campaigns/model/email-record';
 /**
  * Whose template this is: authored here, or installed from a marketplace
  * listing and versioned by somebody else.
  */
 export * from './template-provenance';
-/**
- * One campaign message, rendered. Shared by the send loop, the composer's
- * pre-send preview and any other surface that has to show what will be
- * mailed — a preview that renders the message a second way previews
- * something else.
- */
-/**
- * The campaign CONTAINER — its window, its lists, and the arithmetic that
- * rolls its sends into one set of figures.
- */
-export * from '@aglyn/shared-ui-email-campaigns/model/campaign-container';
 /**
  * How each sending-domain state reads, said once for the list and the
  * domain's own page — including why `inconclusive` is neither of them.