@aglyn/aglyn 1.0.0-beta.143

package/src/lib/app-utils/list-import.js

@@ -0,0 +1,332 @@
+/**
+ * @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 `list-assignment-policy`, 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 { parseCsv } from "./dataset-csv.js";
+import { normalizeContactEmail } from "./contacts.js";
+/**
+ * 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;
+/**
+ * The most characters one uploaded file may carry.
+ *
+ * Checked before the parse rather than after, because the parse is what the
+ * ceiling is protecting: a 400 answered on the byte count costs nothing,
+ * where discovering the file was too big by materializing all of its cells
+ * has already spent the memory the limit exists to bound.
+ */ export const LIST_IMPORT_MAX_CHARACTERS = 8000000;
+/**
+ * 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/app-utils/list-import.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/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 `list-assignment-policy`, 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 { parseCsv } from './dataset-csv'\nimport { normalizeContactEmail } from './contacts'\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 * The most characters one uploaded file may carry.\n *\n * Checked before the parse rather than after, because the parse is what the\n * ceiling is protecting: a 400 answered on the byte count costs nothing,\n * where discovering the file was too big by materializing all of its cells\n * has already spent the memory the limit exists to bound.\n */\nexport const LIST_IMPORT_MAX_CHARACTERS = 8_000_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":["parseCsv","normalizeContactEmail","LIST_IMPORT_MAX_ADDRESSES","LIST_IMPORT_MAX_CHARACTERS","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/app-utils/llms-txt.d.ts

@@ -0,0 +1,104 @@
+/**
+ * @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.
+ */
+/**
+ * `/llms.txt` for a tenant site, in the llmstxt.org format (AGL-2716).
+ *
+ * The file an agent reads FIRST — before the sitemap, before the homepage — to
+ * decide whether this site can answer the question it is holding, and which
+ * URL to fetch if it can.
+ *
+ * ## The format, exactly
+ *
+ * llmstxt.org specifies, in this order: an H1 with the project name (the ONLY
+ * required part), an optional blockquote summary, zero or more non-heading
+ * markdown sections, then zero or more H2-delimited sections of "file lists" —
+ * markdown lists whose items are a required `[name](url)` link optionally
+ * followed by `:` and a note.
+ *
+ * Every H2 section this builder emits is a file list of that shape, INCLUDING
+ * the when-to-use section. That is the design decision worth keeping: guidance
+ * written as prose tells an agent what the site is about and leaves it to
+ * guess a URL, while guidance written as a link list answers "which address
+ * serves this job" in the same breath. It also keeps the file inside the
+ * format rather than beside it.
+ *
+ * ## What goes in it, and what does not
+ *
+ * NOT every URL — that is the sitemap's job, and this file links to it. A site
+ * with five hundred pages has an llms.txt of the same length as a site with
+ * five: identity, what it is for, the handful of entry points that lead
+ * everywhere else, and the machine-readable descriptions of its own surface.
+ *
+ * ## Why the derived guidance is factual and never promotional
+ *
+ * A site whose author writes nothing still gets a when-to-use section, built
+ * from what the site demonstrably HAS: the collections it publishes, the
+ * endpoints it answers, the entry counts. Marketing copy in this position is
+ * worse than an empty section — an agent scoring a dozen candidate sources
+ * discounts a claim it cannot check, and the whole point of the section is to
+ * be checkable.
+ */
+/** A content collection published by the site. */
+export interface LlmsTxtCollection {
+    /** Public slug — the path segment the list answers at. */
+    slug: string;
+    /** Display name, falling back to the slug. */
+    name?: string;
+    /** The collection's own description, when the author wrote one. */
+    description?: string;
+    /** Published entries, when the count is known and cheap to have. */
+    entryCount?: number;
+}
+/** One curated page link. */
+export interface LlmsTxtPage {
+    /** Route path, with or without its leading slash. */
+    path: string;
+    /** Link text; the path is used when a screen has no name. */
+    title?: string;
+    /** Optional note after the colon. */
+    note?: string;
+}
+/** Author-written agent guidance, as `host.seo.agent` stores it. */
+export interface LlmsTxtAgentGuidance {
+    /** "When to use this site" — the jobs it is the right answer to. */
+    whenToUse?: string;
+    /** How an agent should call it — endpoints, auth, rate limits, etiquette. */
+    howToUse?: string;
+}
+export interface LlmsTxtOptions {
+    /** The site's name — the H1, and the only required field in the format. */
+    siteName: string;
+    /** Absolute origin, no trailing slash. */
+    origin: string;
+    /** The summary blockquote. */
+    description?: string;
+    agent?: LlmsTxtAgentGuidance | null;
+    pages?: readonly LlmsTxtPage[];
+    collections?: readonly LlmsTxtCollection[];
+    /** Whether this site serves `/search`. */
+    hasSearch?: boolean;
+    /** Where a human is reached, when the site publishes one. */
+    contactEmail?: string;
+}
+/** Path of the agent-guidance file, at the site root, per llmstxt.org. */
+export declare const LLMS_TXT_PATH = "/llms.txt";
+/** Path of the machine-readable API description. */
+export declare const OPENAPI_PATH = "/openapi.json";
+/** Join an origin and a path into an absolute URL with exactly one slash. */
+export declare function absoluteSiteUrl(origin: string, path: string): string;
+/** Build the `/llms.txt` body. */
+export declare function buildLlmsTxt(options: LlmsTxtOptions): string;

package/src/lib/app-utils/llms-txt.js

@@ -0,0 +1,144 @@
+/**
+ * @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.
+ */ /**
+ * `/llms.txt` for a tenant site, in the llmstxt.org format (AGL-2716).
+ *
+ * The file an agent reads FIRST — before the sitemap, before the homepage — to
+ * decide whether this site can answer the question it is holding, and which
+ * URL to fetch if it can.
+ *
+ * ## The format, exactly
+ *
+ * llmstxt.org specifies, in this order: an H1 with the project name (the ONLY
+ * required part), an optional blockquote summary, zero or more non-heading
+ * markdown sections, then zero or more H2-delimited sections of "file lists" —
+ * markdown lists whose items are a required `[name](url)` link optionally
+ * followed by `:` and a note.
+ *
+ * Every H2 section this builder emits is a file list of that shape, INCLUDING
+ * the when-to-use section. That is the design decision worth keeping: guidance
+ * written as prose tells an agent what the site is about and leaves it to
+ * guess a URL, while guidance written as a link list answers "which address
+ * serves this job" in the same breath. It also keeps the file inside the
+ * format rather than beside it.
+ *
+ * ## What goes in it, and what does not
+ *
+ * NOT every URL — that is the sitemap's job, and this file links to it. A site
+ * with five hundred pages has an llms.txt of the same length as a site with
+ * five: identity, what it is for, the handful of entry points that lead
+ * everywhere else, and the machine-readable descriptions of its own surface.
+ *
+ * ## Why the derived guidance is factual and never promotional
+ *
+ * A site whose author writes nothing still gets a when-to-use section, built
+ * from what the site demonstrably HAS: the collections it publishes, the
+ * endpoints it answers, the entry counts. Marketing copy in this position is
+ * worse than an empty section — an agent scoring a dozen candidate sources
+ * discounts a claim it cannot check, and the whole point of the section is to
+ * be checkable.
+ */ /** A content collection published by the site. */ /** Path of the agent-guidance file, at the site root, per llmstxt.org. */ export const LLMS_TXT_PATH = '/llms.txt';
+/** Path of the machine-readable API description. */ export const OPENAPI_PATH = '/openapi.json';
+/** Join an origin and a path into an absolute URL with exactly one slash. */ export function absoluteSiteUrl(origin, path) {
+    const base = origin.replace(/\/+$/, '');
+    if (!path || path === '/') return `${base}/`;
+    return `${base}/${String(path).replace(/^\/+/, '')}`;
+}
+/**
+ * Markdown link text, escaped.
+ *
+ * Only `[` and `]` — the two characters that can close a link label early and
+ * turn the rest of the line into loose text. Escaping more would put
+ * backslashes in a page title for no benefit; this is a label, not a document.
+ */ const label = (value)=>String(value).replace(/\s+/g, ' ').trim().replace(/([[\]])/g, '\\$1');
+/** One file-list item: `- [name](url): note`. */ const item = (name, url, note)=>note ? `- [${label(name)}](${url}): ${note}` : `- [${label(name)}](${url})`;
+/** Title-case-ish display name for a slug with no name of its own. */ function nameForSlug(slug) {
+    const words = slug.replace(/[-_]+/g, ' ').trim();
+    return words ? words.charAt(0).toUpperCase() + words.slice(1) : slug;
+}
+/**
+ * The when-to-use items derived from what the site actually publishes.
+ *
+ * Each is a job an agent might hold, paired with the URL that answers it. The
+ * counts and names come from the site's own data, so nothing here is a claim
+ * the reader cannot verify by following the link.
+ */ function derivedGuidance(options) {
+    var _options_collections;
+    const { origin, siteName } = options;
+    const lines = [];
+    for (const collection of (_options_collections = options.collections) != null ? _options_collections : []){
+        const name = collection.name || nameForSlug(collection.slug);
+        const count = typeof collection.entryCount === 'number' && collection.entryCount > 0 ? `${collection.entryCount} published ${collection.entryCount === 1 ? 'entry' : 'entries'}` : 'the published entries';
+        lines.push(item(name, absoluteSiteUrl(origin, collection.slug), collection.description ? `${label(collection.description)} — ${count}, newest first` : `${count}, newest first. Read this when you need ${label(name.toLowerCase())} published by ${label(siteName)}`));
+    }
+    if (options.hasSearch) {
+        lines.push(item('Search this site', `${absoluteSiteUrl(origin, 'search')}?q=`, 'full-text search across this site’s pages and published entries; ' + 'append your query to `?q=`'));
+    }
+    lines.push(item('Sitemap index', absoluteSiteUrl(origin, 'sitemap.xml'), 'every indexable URL on this site, split into dated child sitemaps'));
+    lines.push(item('OpenAPI description', absoluteSiteUrl(origin, OPENAPI_PATH), 'every public endpoint this site serves, with typed parameters, ' + 'response schemas and a unique operationId per operation'));
+    if (options.contactEmail) {
+        lines.push(item('Contact a person', `mailto:${options.contactEmail}`, 'reach the people who publish this site when the answer is not on it'));
+    }
+    return lines;
+}
+/** Build the `/llms.txt` body. */ export function buildLlmsTxt(options) {
+    var _options_description, _ref, _ref1, _options_pages, _options_collections;
+    var _options_agent, _options_agent1;
+    const { origin } = options;
+    const sections = [];
+    sections.push(`# ${label(options.siteName || 'Site')}`);
+    const description = String((_options_description = options.description) != null ? _options_description : '').replace(/\s+/g, ' ').trim();
+    if (description) sections.push(`> ${description}`);
+    /*
+    The author's own guidance leads, in their words, because they know things
+    this file cannot derive — which questions the site is genuinely the best
+    source for, and which it is not.
+  */ const whenToUse = String((_ref = (_options_agent = options.agent) == null ? void 0 : _options_agent.whenToUse) != null ? _ref : '').trim();
+    if (whenToUse) sections.push(whenToUse);
+    /*
+    The negotiation contract, stated once. An agent that knows a Markdown
+    variant exists asks for it; one that does not, parses HTML it did not need.
+    Both spellings are given because the two conventions have different
+    audiences: `Accept` is acceptmarkdown.com, `.md` is llmstxt.org, and an
+    agent that only knows one of them still gets clean text.
+  */ sections.push('Every page on this site serves a Markdown representation of itself. ' + 'Send `Accept: text/markdown`, or append `.md` to any path — ' + `for example \`${absoluteSiteUrl(origin, 'about.md')}\`. ` + 'Responses vary on `Accept`, so a cache cannot hand you the wrong one.');
+    const howToUse = String((_ref1 = (_options_agent1 = options.agent) == null ? void 0 : _options_agent1.howToUse) != null ? _ref1 : '').trim();
+    if (howToUse) sections.push(howToUse);
+    const guidance = derivedGuidance(options);
+    if (guidance.length) {
+        sections.push([
+            '## When to use this site',
+            ...guidance
+        ].join('\n'));
+    }
+    const pages = (_options_pages = options.pages) != null ? _options_pages : [];
+    if (pages.length) {
+        sections.push([
+            '## Pages',
+            ...pages.map((entry)=>item(entry.title || nameForSlug(entry.path.replace(/^\/+/, '')) || 'Home', absoluteSiteUrl(origin, entry.path), entry.note))
+        ].join('\n'));
+    }
+    const collections = (_options_collections = options.collections) != null ? _options_collections : [];
+    if (collections.length) {
+        sections.push([
+            '## Feeds',
+            ...collections.map((collection)=>item(`${collection.name || nameForSlug(collection.slug)} (RSS)`, absoluteSiteUrl(origin, `${collection.slug}/rss.xml`), 'newest entries as RSS 2.0'))
+        ].join('\n'));
+    }
+    return `${sections.join('\n\n').trim()}\n`;
+}
+
+//# sourceMappingURL=llms-txt.js.map