@aglyn/aglyn 1.0.0-beta.143

package/src/lib/app-utils/list-assignment-policy.d.ts

@@ -0,0 +1,169 @@
+/**
+ * @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.
+ */
+/**
+ * What basis lets somebody be put on a marketing list.
+ *
+ * Pure policy, no Firestore and no network, so the rule that decides whether
+ * somebody joins a marketing audience can be asserted without an enrollment
+ * path.
+ *
+ * ## Why it is here and not beside one of its callers
+ *
+ * There are two enrollment surfaces and neither can own this: the Inbox
+ * assignment route (`@aglyn/plugins-inbox`) enrolls the sender of a form
+ * submission, and the Emails console's audience card enrolls an address a
+ * merchant types or pastes. `plugins-inbox` already depends on
+ * `plugins-email`, so the second could not have imported the first, and a
+ * copy in each is the shape that ends with one surface honoring a stored
+ * refusal and the other not. The basis a membership carries has to be one
+ * rule with one set of words, so it lives in the framework both import.
+ *
+ * ## A reply is transactional; a list is marketing
+ *
+ * These are two acts and this module exists because they are constantly
+ * mistaken for one. Answering a form submission is the transaction the person
+ * started, so the Inbox's `reply-policy.ts` requires no consent record.
+ * Putting them on a list is a standing invitation to mail them about things
+ * they never asked about, and it requires a basis. Nothing in the reply path
+ * reaches this module and nothing here sends anything.
+ *
+ * ## An enrollment is not a license to send
+ *
+ * Passing this rule writes a membership and nothing else. It meters nothing,
+ * sends nothing, and is not a promise the person is still mailable when a
+ * campaign eventually runs — suppression is consulted again at send time, in
+ * `filterSendableForHost`, because an address can be suppressed the day after
+ * it is enrolled. `apps/console/specs/an-enrollment-is-not-a-license-to-send.spec.ts`
+ * holds the two halves together end to end.
+ *
+ * ## A basis is DECLARED, never inferred
+ *
+ * The act that produced the address is not a basis. Somebody who filled in a
+ * contact form asked to be answered; that is the whole of what they asked for,
+ * and an address a merchant has in a spreadsheet says less than that. Neither
+ * is writing to the merchant, buying, booking or holding an account — the
+ * shared `marketing-consent` module makes the same point for the send-time
+ * join, and this is the enrollment-time half of it. So there are exactly two
+ * ways in:
+ *
+ * 1. the person's own record already carries a stored opt-in, which is
+ *    carried across unchanged, timestamp and all; or
+ * 2. the merchant states that they have this person's permission, and THAT
+ *    STATEMENT IS ITSELF THE RECORDED BASIS — stored with the account that
+ *    made it and the moment they did.
+ *
+ * There is no third way and, in particular, no unattributed one. The absence
+ * of a record is reported to the merchant as an absence rather than resolved
+ * quietly in either direction.
+ *
+ * ## A stored refusal ends it
+ *
+ * `declined` is checked first and answers before anything else is considered,
+ * including an attestation. A merchant cannot attest their way past somebody
+ * who said no; that is the one thing an attestation must not be able to buy,
+ * because if it could there would be no difference between recording a
+ * refusal and discarding it.
+ */
+import { OPERATOR_ATTESTED_CONSENT_BASIS, type MarketingConsentRecord } from './marketing-consent';
+/**
+ * What is wrong with the ADDRESS, before anybody asks what is wrong with the
+ * consent.
+ *
+ * Four failures that are properties of the address rather than of the act, so
+ * every surface that touches an address shares them: a form with no email
+ * field has nobody to enroll for the same reason it has nobody to answer, and
+ * a bounced address is unmailable whichever route reached it. The Inbox's
+ * `ReplyRefusal` is this type — one union, aliased there — because a reply
+ * and an enrollment refuse an address for the same four reasons and a second
+ * copy would eventually list three.
+ */
+export type AddressRefusal = 
+/** No field the resolver recognizes as an email — nothing to enroll. */
+'no-address'
+/** The value is not a routable address. */
+ | 'unroutable-address'
+/** The address is on the platform-wide bounce/complaint list. */
+ | 'suppressed-platform'
+/** The address unsubscribed from, or bounced on, this site. */
+ | 'suppressed-host';
+/** Why an address cannot be put on a list. Each maps to one refusal message. */
+export type AssignmentRefusal = AddressRefusal
+/** A stored refusal. Never enrollable, and there is no override. */
+ | 'declined'
+/** No record either way, and the merchant asserted nothing. */
+ | 'no-basis';
+/** The basis an enrollment would carry, resolved server-side. */
+export interface AssignmentBasisDecision {
+    basis: 'contact-opt-in' | typeof OPERATOR_ATTESTED_CONSENT_BASIS;
+    /** When the basis was recorded — the person's own moment, or the merchant's. */
+    atMs: number;
+    /** The account answerable for an attestation; `null` for a pass-through. */
+    byUid: string | null;
+}
+/**
+ * Decides what basis, if any, an enrollment may carry.
+ *
+ * The client never names the basis. It says only whether the merchant is
+ * asserting one, and the pass-through is derived here from the person's own
+ * record — a caller that could claim `contact-opt-in` would be a caller that
+ * can manufacture an opt-in for anybody by naming it.
+ *
+ * @param stored   the person's consent facts, read off their own record.
+ * @param attested whether the merchant asserted permission in this request.
+ */
+export declare function assignmentBasis(input: {
+    stored: MarketingConsentRecord;
+    attested: boolean;
+    actingUid: string;
+    nowMs: number;
+}): AssignmentBasisDecision | {
+    refusal: AssignmentRefusal;
+};
+/** What the merchant is shown before they decide. */
+export interface AssignmentReadout {
+    /** Can this person be enrolled at all, by any answer the merchant gives? */
+    enrollable: boolean;
+    /**
+     * Must the merchant assert permission for the enrollment to proceed?
+     *
+     * False both when a stored opt-in already carries it and when nothing can
+     * carry it, so the UI reads this alone to decide whether to show the
+     * assertion control — a surface that showed it on a refusal would offer an
+     * override that does not exist.
+     */
+    requiresAttestation: boolean;
+    /** One sentence of consent facts, in the merchant's terms. */
+    summary: string;
+}
+/**
+ * The readout for one address, from the same inputs the decision uses.
+ *
+ * It lives here rather than in the component so the sentence on screen and
+ * the rule that runs on the server cannot drift: a UI that computed its own
+ * summary would eventually tell a merchant that somebody may be added and
+ * then refuse them, or — far worse — say a check was performed that was not.
+ *
+ * @param suppression a suppression refusal for the address, when there is
+ *                    one. It outranks consent in the readout because it is
+ *                    the answer regardless of what any consent record says.
+ */
+export declare function assignmentReadout(input: {
+    stored: MarketingConsentRecord;
+    suppression: AddressRefusal | null;
+}): AssignmentReadout;
+/** What a refusal says to the merchant. One line, naming the cause. */
+export declare const ASSIGNMENT_REFUSAL_MESSAGES: Record<AssignmentRefusal, string>;

package/src/lib/app-utils/list-assignment-policy.js

@@ -0,0 +1,170 @@
+/**
+ * @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.
+ */ /**
+ * What basis lets somebody be put on a marketing list.
+ *
+ * Pure policy, no Firestore and no network, so the rule that decides whether
+ * somebody joins a marketing audience can be asserted without an enrollment
+ * path.
+ *
+ * ## Why it is here and not beside one of its callers
+ *
+ * There are two enrollment surfaces and neither can own this: the Inbox
+ * assignment route (`@aglyn/plugins-inbox`) enrolls the sender of a form
+ * submission, and the Emails console's audience card enrolls an address a
+ * merchant types or pastes. `plugins-inbox` already depends on
+ * `plugins-email`, so the second could not have imported the first, and a
+ * copy in each is the shape that ends with one surface honoring a stored
+ * refusal and the other not. The basis a membership carries has to be one
+ * rule with one set of words, so it lives in the framework both import.
+ *
+ * ## A reply is transactional; a list is marketing
+ *
+ * These are two acts and this module exists because they are constantly
+ * mistaken for one. Answering a form submission is the transaction the person
+ * started, so the Inbox's `reply-policy.ts` requires no consent record.
+ * Putting them on a list is a standing invitation to mail them about things
+ * they never asked about, and it requires a basis. Nothing in the reply path
+ * reaches this module and nothing here sends anything.
+ *
+ * ## An enrollment is not a license to send
+ *
+ * Passing this rule writes a membership and nothing else. It meters nothing,
+ * sends nothing, and is not a promise the person is still mailable when a
+ * campaign eventually runs — suppression is consulted again at send time, in
+ * `filterSendableForHost`, because an address can be suppressed the day after
+ * it is enrolled. `apps/console/specs/an-enrollment-is-not-a-license-to-send.spec.ts`
+ * holds the two halves together end to end.
+ *
+ * ## A basis is DECLARED, never inferred
+ *
+ * The act that produced the address is not a basis. Somebody who filled in a
+ * contact form asked to be answered; that is the whole of what they asked for,
+ * and an address a merchant has in a spreadsheet says less than that. Neither
+ * is writing to the merchant, buying, booking or holding an account — the
+ * shared `marketing-consent` module makes the same point for the send-time
+ * join, and this is the enrollment-time half of it. So there are exactly two
+ * ways in:
+ *
+ * 1. the person's own record already carries a stored opt-in, which is
+ *    carried across unchanged, timestamp and all; or
+ * 2. the merchant states that they have this person's permission, and THAT
+ *    STATEMENT IS ITSELF THE RECORDED BASIS — stored with the account that
+ *    made it and the moment they did.
+ *
+ * There is no third way and, in particular, no unattributed one. The absence
+ * of a record is reported to the merchant as an absence rather than resolved
+ * quietly in either direction.
+ *
+ * ## A stored refusal ends it
+ *
+ * `declined` is checked first and answers before anything else is considered,
+ * including an attestation. A merchant cannot attest their way past somebody
+ * who said no; that is the one thing an attestation must not be able to buy,
+ * because if it could there would be no difference between recording a
+ * refusal and discarding it.
+ */ import { OPERATOR_ATTESTED_CONSENT_BASIS } from "./marketing-consent.js";
+/**
+ * Decides what basis, if any, an enrollment may carry.
+ *
+ * The client never names the basis. It says only whether the merchant is
+ * asserting one, and the pass-through is derived here from the person's own
+ * record — a caller that could claim `contact-opt-in` would be a caller that
+ * can manufacture an opt-in for anybody by naming it.
+ *
+ * @param stored   the person's consent facts, read off their own record.
+ * @param attested whether the merchant asserted permission in this request.
+ */ export function assignmentBasis(input) {
+    // First, and above the attestation on purpose. See the module note.
+    if (input.stored.basis === 'declined') return {
+        refusal: 'declined'
+    };
+    if (input.stored.basis === 'granted') {
+        var _input_stored_basisAtMs;
+        return {
+            basis: 'contact-opt-in',
+            /*
+       * The person's own timestamp, and `nowMs` only when their record
+       * carries none. A pass-through that restamped the moment would report
+       * every historical opt-in as having happened when a merchant pressed a
+       * button, which moves records across the enforcement cutoff the consent
+       * policy grandfathers on and makes the audit answer the wrong question.
+       */ atMs: (_input_stored_basisAtMs = input.stored.basisAtMs) != null ? _input_stored_basisAtMs : input.nowMs,
+            byUid: null
+        };
+    }
+    if (!input.attested) return {
+        refusal: 'no-basis'
+    };
+    return {
+        basis: OPERATOR_ATTESTED_CONSENT_BASIS,
+        atMs: input.nowMs,
+        // Never optional for this basis: an attestation nobody is named for is
+        // indistinguishable from an opt-in, which is the conflation the whole
+        // module exists to prevent.
+        byUid: input.actingUid
+    };
+}
+/**
+ * The readout for one address, from the same inputs the decision uses.
+ *
+ * It lives here rather than in the component so the sentence on screen and
+ * the rule that runs on the server cannot drift: a UI that computed its own
+ * summary would eventually tell a merchant that somebody may be added and
+ * then refuse them, or — far worse — say a check was performed that was not.
+ *
+ * @param suppression a suppression refusal for the address, when there is
+ *                    one. It outranks consent in the readout because it is
+ *                    the answer regardless of what any consent record says.
+ */ export function assignmentReadout(input) {
+    if (input.suppression) {
+        return {
+            enrollable: false,
+            requiresAttestation: false,
+            summary: ASSIGNMENT_REFUSAL_MESSAGES[input.suppression]
+        };
+    }
+    if (input.stored.basis === 'declined') {
+        return {
+            enrollable: false,
+            requiresAttestation: false,
+            summary: ASSIGNMENT_REFUSAL_MESSAGES['declined']
+        };
+    }
+    if (input.stored.basis === 'granted') {
+        const when = input.stored.basisAtMs ? ` on ${new Date(input.stored.basisAtMs).toLocaleDateString()}` : '';
+        return {
+            enrollable: true,
+            requiresAttestation: false,
+            summary: `This person opted in to marketing email${when}. Adding them carries that opt-in across.`
+        };
+    }
+    return {
+        enrollable: true,
+        requiresAttestation: true,
+        summary: 'There is no marketing opt-in on record for this person. Sending this ' + 'form does not create one. To add them you have to state that you have ' + 'their permission, and that statement is recorded against your account.'
+    };
+}
+/** What a refusal says to the merchant. One line, naming the cause. */ export const ASSIGNMENT_REFUSAL_MESSAGES = {
+    'no-address': 'This submission has no email field, so there is nobody to add to a list.',
+    'unroutable-address': 'The email address on this submission is not a valid address.',
+    'suppressed-platform': 'This address bounced or reported a message as spam, so it cannot be mailed or added to a list.',
+    'suppressed-host': 'This address unsubscribed from this site, so it cannot be mailed or added to a list.',
+    declined: 'This person declined marketing email. They cannot be added to a list, and there is no way to override that.',
+    'no-basis': 'This person has no marketing opt-in on record, so they can only be added if you state that you have their permission.'
+};
+
+//# sourceMappingURL=list-assignment-policy.js.map

package/src/lib/app-utils/list-assignment-policy.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/list-assignment-policy.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 basis lets somebody be put on a marketing list.\n *\n * Pure policy, no Firestore and no network, so the rule that decides whether\n * somebody joins a marketing audience can be asserted without an enrollment\n * path.\n *\n * ## Why it is here and not beside one of its callers\n *\n * There are two enrollment surfaces and neither can own this: the Inbox\n * assignment route (`@aglyn/plugins-inbox`) enrolls the sender of a form\n * submission, and the Emails console's audience card enrolls an address a\n * merchant types or pastes. `plugins-inbox` already depends on\n * `plugins-email`, so the second could not have imported the first, and a\n * copy in each is the shape that ends with one surface honoring a stored\n * refusal and the other not. The basis a membership carries has to be one\n * rule with one set of words, so it lives in the framework both import.\n *\n * ## A reply is transactional; a list is marketing\n *\n * These are two acts and this module exists because they are constantly\n * mistaken for one. Answering a form submission is the transaction the person\n * started, so the Inbox's `reply-policy.ts` requires no consent record.\n * Putting them on a list is a standing invitation to mail them about things\n * they never asked about, and it requires a basis. Nothing in the reply path\n * reaches this module and nothing here sends anything.\n *\n * ## An enrollment is not a license to send\n *\n * Passing this rule writes a membership and nothing else. It meters nothing,\n * sends nothing, and is not a promise the person is still mailable when a\n * campaign eventually runs — suppression is consulted again at send time, in\n * `filterSendableForHost`, because an address can be suppressed the day after\n * it is enrolled. `apps/console/specs/an-enrollment-is-not-a-license-to-send.spec.ts`\n * holds the two halves together end to end.\n *\n * ## A basis is DECLARED, never inferred\n *\n * The act that produced the address is not a basis. Somebody who filled in a\n * contact form asked to be answered; that is the whole of what they asked for,\n * and an address a merchant has in a spreadsheet says less than that. Neither\n * is writing to the merchant, buying, booking or holding an account — the\n * shared `marketing-consent` module makes the same point for the send-time\n * join, and this is the enrollment-time half of it. So there are exactly two\n * ways in:\n *\n * 1. the person's own record already carries a stored opt-in, which is\n *    carried across unchanged, timestamp and all; or\n * 2. the merchant states that they have this person's permission, and THAT\n *    STATEMENT IS ITSELF THE RECORDED BASIS — stored with the account that\n *    made it and the moment they did.\n *\n * There is no third way and, in particular, no unattributed one. The absence\n * of a record is reported to the merchant as an absence rather than resolved\n * quietly in either direction.\n *\n * ## A stored refusal ends it\n *\n * `declined` is checked first and answers before anything else is considered,\n * including an attestation. A merchant cannot attest their way past somebody\n * who said no; that is the one thing an attestation must not be able to buy,\n * because if it could there would be no difference between recording a\n * refusal and discarding it.\n */\n\nimport {\n  OPERATOR_ATTESTED_CONSENT_BASIS,\n  type MarketingConsentRecord,\n} from './marketing-consent'\n\n/**\n * What is wrong with the ADDRESS, before anybody asks what is wrong with the\n * consent.\n *\n * Four failures that are properties of the address rather than of the act, so\n * every surface that touches an address shares them: a form with no email\n * field has nobody to enroll for the same reason it has nobody to answer, and\n * a bounced address is unmailable whichever route reached it. The Inbox's\n * `ReplyRefusal` is this type — one union, aliased there — because a reply\n * and an enrollment refuse an address for the same four reasons and a second\n * copy would eventually list three.\n */\nexport type AddressRefusal =\n  /** No field the resolver recognizes as an email — nothing to enroll. */\n  | 'no-address'\n  /** The value is not a routable address. */\n  | 'unroutable-address'\n  /** The address is on the platform-wide bounce/complaint list. */\n  | 'suppressed-platform'\n  /** The address unsubscribed from, or bounced on, this site. */\n  | 'suppressed-host'\n\n/** Why an address cannot be put on a list. Each maps to one refusal message. */\nexport type AssignmentRefusal =\n  | AddressRefusal\n  /** A stored refusal. Never enrollable, and there is no override. */\n  | 'declined'\n  /** No record either way, and the merchant asserted nothing. */\n  | 'no-basis'\n\n/** The basis an enrollment would carry, resolved server-side. */\nexport interface AssignmentBasisDecision {\n  /*\n   * The attested value is the EXPORTED CONSTANT and not a literal spelled\n   * again here. `readMarketingBasis` recognizes an attestation by comparing\n   * the stored field against that constant, so a second spelling on the\n   * deciding side is a rename away from writing a basis the reader reports as\n   * the person's own act — the one conflation this whole area exists to stop.\n   */\n  basis: 'contact-opt-in' | typeof OPERATOR_ATTESTED_CONSENT_BASIS\n  /** When the basis was recorded — the person's own moment, or the merchant's. */\n  atMs: number\n  /** The account answerable for an attestation; `null` for a pass-through. */\n  byUid: string | null\n}\n\n/**\n * Decides what basis, if any, an enrollment may carry.\n *\n * The client never names the basis. It says only whether the merchant is\n * asserting one, and the pass-through is derived here from the person's own\n * record — a caller that could claim `contact-opt-in` would be a caller that\n * can manufacture an opt-in for anybody by naming it.\n *\n * @param stored   the person's consent facts, read off their own record.\n * @param attested whether the merchant asserted permission in this request.\n */\nexport function assignmentBasis(input: {\n  stored: MarketingConsentRecord\n  attested: boolean\n  actingUid: string\n  nowMs: number\n}): AssignmentBasisDecision | { refusal: AssignmentRefusal } {\n  // First, and above the attestation on purpose. See the module note.\n  if (input.stored.basis === 'declined') return { refusal: 'declined' }\n  if (input.stored.basis === 'granted') {\n    return {\n      basis: 'contact-opt-in',\n      /*\n       * The person's own timestamp, and `nowMs` only when their record\n       * carries none. A pass-through that restamped the moment would report\n       * every historical opt-in as having happened when a merchant pressed a\n       * button, which moves records across the enforcement cutoff the consent\n       * policy grandfathers on and makes the audit answer the wrong question.\n       */\n      atMs: input.stored.basisAtMs ?? input.nowMs,\n      byUid: null,\n    }\n  }\n  if (!input.attested) return { refusal: 'no-basis' }\n  return {\n    basis: OPERATOR_ATTESTED_CONSENT_BASIS,\n    atMs: input.nowMs,\n    // Never optional for this basis: an attestation nobody is named for is\n    // indistinguishable from an opt-in, which is the conflation the whole\n    // module exists to prevent.\n    byUid: input.actingUid,\n  }\n}\n\n/** What the merchant is shown before they decide. */\nexport interface AssignmentReadout {\n  /** Can this person be enrolled at all, by any answer the merchant gives? */\n  enrollable: boolean\n  /**\n   * Must the merchant assert permission for the enrollment to proceed?\n   *\n   * False both when a stored opt-in already carries it and when nothing can\n   * carry it, so the UI reads this alone to decide whether to show the\n   * assertion control — a surface that showed it on a refusal would offer an\n   * override that does not exist.\n   */\n  requiresAttestation: boolean\n  /** One sentence of consent facts, in the merchant's terms. */\n  summary: string\n}\n\n/**\n * The readout for one address, from the same inputs the decision uses.\n *\n * It lives here rather than in the component so the sentence on screen and\n * the rule that runs on the server cannot drift: a UI that computed its own\n * summary would eventually tell a merchant that somebody may be added and\n * then refuse them, or — far worse — say a check was performed that was not.\n *\n * @param suppression a suppression refusal for the address, when there is\n *                    one. It outranks consent in the readout because it is\n *                    the answer regardless of what any consent record says.\n */\nexport function assignmentReadout(input: {\n  stored: MarketingConsentRecord\n  suppression: AddressRefusal | null\n}): AssignmentReadout {\n  if (input.suppression) {\n    return {\n      enrollable: false,\n      requiresAttestation: false,\n      summary: ASSIGNMENT_REFUSAL_MESSAGES[input.suppression],\n    }\n  }\n  if (input.stored.basis === 'declined') {\n    return {\n      enrollable: false,\n      requiresAttestation: false,\n      summary: ASSIGNMENT_REFUSAL_MESSAGES['declined'],\n    }\n  }\n  if (input.stored.basis === 'granted') {\n    const when = input.stored.basisAtMs\n      ? ` on ${new Date(input.stored.basisAtMs).toLocaleDateString()}`\n      : ''\n    return {\n      enrollable: true,\n      requiresAttestation: false,\n      summary: `This person opted in to marketing email${when}. Adding them carries that opt-in across.`,\n    }\n  }\n  return {\n    enrollable: true,\n    requiresAttestation: true,\n    summary:\n      'There is no marketing opt-in on record for this person. Sending this ' +\n      'form does not create one. To add them you have to state that you have ' +\n      'their permission, and that statement is recorded against your account.',\n  }\n}\n\n/** What a refusal says to the merchant. One line, naming the cause. */\nexport const ASSIGNMENT_REFUSAL_MESSAGES: Record<AssignmentRefusal, string> = {\n  'no-address':\n    'This submission has no email field, so there is nobody to add to a list.',\n  'unroutable-address':\n    'The email address on this submission is not a valid address.',\n  'suppressed-platform':\n    'This address bounced or reported a message as spam, so it cannot be mailed or added to a list.',\n  'suppressed-host':\n    'This address unsubscribed from this site, so it cannot be mailed or added to a list.',\n  declined:\n    'This person declined marketing email. They cannot be added to a list, and there is no way to override that.',\n  'no-basis':\n    'This person has no marketing opt-in on record, so they can only be added if you state that you have their permission.',\n}\n"],"names":["OPERATOR_ATTESTED_CONSENT_BASIS","assignmentBasis","input","stored","basis","refusal","atMs","basisAtMs","nowMs","byUid","attested","actingUid","assignmentReadout","suppression","enrollable","requiresAttestation","summary","ASSIGNMENT_REFUSAL_MESSAGES","when","Date","toLocaleDateString","declined"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA+DC,GAED,SACEA,+BAA+B,QAE1B,yBAAqB;AAgD5B;;;;;;;;;;CAUC,GACD,OAAO,SAASC,gBAAgBC,KAK/B;IACC,oEAAoE;IACpE,IAAIA,MAAMC,MAAM,CAACC,KAAK,KAAK,YAAY,OAAO;QAAEC,SAAS;IAAW;IACpE,IAAIH,MAAMC,MAAM,CAACC,KAAK,KAAK,WAAW;YAU5BF;QATR,OAAO;YACLE,OAAO;YACP;;;;;;OAMC,GACDE,IAAI,GAAEJ,0BAAAA,MAAMC,MAAM,CAACI,SAAS,YAAtBL,0BAA0BA,MAAMM,KAAK;YAC3CC,OAAO;QACT;IACF;IACA,IAAI,CAACP,MAAMQ,QAAQ,EAAE,OAAO;QAAEL,SAAS;IAAW;IAClD,OAAO;QACLD,OAAOJ;QACPM,MAAMJ,MAAMM,KAAK;QACjB,uEAAuE;QACvE,sEAAsE;QACtE,4BAA4B;QAC5BC,OAAOP,MAAMS,SAAS;IACxB;AACF;AAmBA;;;;;;;;;;;CAWC,GACD,OAAO,SAASC,kBAAkBV,KAGjC;IACC,IAAIA,MAAMW,WAAW,EAAE;QACrB,OAAO;YACLC,YAAY;YACZC,qBAAqB;YACrBC,SAASC,2BAA2B,CAACf,MAAMW,WAAW,CAAC;QACzD;IACF;IACA,IAAIX,MAAMC,MAAM,CAACC,KAAK,KAAK,YAAY;QACrC,OAAO;YACLU,YAAY;YACZC,qBAAqB;YACrBC,SAASC,2BAA2B,CAAC,WAAW;QAClD;IACF;IACA,IAAIf,MAAMC,MAAM,CAACC,KAAK,KAAK,WAAW;QACpC,MAAMc,OAAOhB,MAAMC,MAAM,CAACI,SAAS,GAC/B,CAAC,IAAI,EAAE,IAAIY,KAAKjB,MAAMC,MAAM,CAACI,SAAS,EAAEa,kBAAkB,IAAI,GAC9D;QACJ,OAAO;YACLN,YAAY;YACZC,qBAAqB;YACrBC,SAAS,CAAC,uCAAuC,EAAEE,KAAK,yCAAyC,CAAC;QACpG;IACF;IACA,OAAO;QACLJ,YAAY;QACZC,qBAAqB;QACrBC,SACE,0EACA,2EACA;IACJ;AACF;AAEA,qEAAqE,GACrE,OAAO,MAAMC,8BAAiE;IAC5E,cACE;IACF,sBACE;IACF,uBACE;IACF,mBACE;IACFI,UACE;IACF,YACE;AACJ,EAAC"}

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

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