@aglyn/plugins-email 1.0.0-beta.143

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

@@ -0,0 +1,199 @@
+/**
+ * @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.
+ */
+/**
+ * BRINGING AN EXISTING LIST IN — the four routes an import is made of.
+ *
+ * `docs/specs/email-competitive-gaps.md` G5: export works, import does not
+ * exist, and every customer arriving from another product has a list and no
+ * way to bring it. P4 is the condition attached to closing that: a bulk
+ * import is the fastest way to destroy a shared sending domain, so it ships
+ * WITH its controls.
+ *
+ * ## Every imported address goes through the checks a typed one does
+ *
+ * Not a similar set — the same functions. {@link resolveAddresses} is the
+ * resolution `email/list-members-preview` runs, `assignmentBasis` is the
+ * policy `email/list-members-add` applies, and `enrollListMember` is the one
+ * writer of the membership collection. A second bulk path with its own idea of
+ * suppression and its own idea of consent is exactly the defect class this
+ * register has a P1 entry for, and that entry is closed.
+ *
+ * What this module adds is everything ABOVE that gate: reading a file,
+ * screening it, holding the operator's attestation, and metering the work out
+ * over as many requests as it takes.
+ *
+ * ## Four routes, because an import is four separate acts
+ *
+ * - `email/list-import-preview` — reads the file and says what is in it.
+ *   Writes nothing, enrolls nobody, and resolves a BOUNDED SAMPLE through the
+ *   consent gate so the numbers the operator attests against are real numbers
+ *   from real records rather than a promise.
+ * - `email/list-import-start` — records the attestation and stages the
+ *   addresses. Still enrolls nobody: the act of saying "I have permission for
+ *   these people" is separated from the act of adding them so that the
+ *   attestation has a moment of its own.
+ * - `email/list-import-run` — enrolls up to {@link LIST_IMPORT_RUN_BUDGET}
+ *   addresses from the cursor and moves it. Called until it answers
+ *   `complete`.
+ * - `email/list-import-status` — the unfinished import on a list, if there is
+ *   one, so a merchant who closed the tab is not left with a half-added
+ *   audience and no way to see it.
+ *
+ * ## A budget and a cursor, not one request and not one transaction
+ *
+ * The shape `dynamic-list-materialize.ts` already uses: a per-run bound on
+ * work, a cursor recording where the run stopped, and a next run that resumes
+ * rather than restarts. A 50,000-address file is not a request that times out
+ * halfway with no record of what it did; it is 500 bounded requests over one
+ * durable job, and stopping in the middle of it leaves the addresses already
+ * enrolled enrolled and the rest staged.
+ *
+ * The run budget is deliberately {@link LIST_MEMBER_BATCH_MAX} — the same
+ * number of addresses one hand-typed add already resolves in one request — so
+ * an import run costs exactly what an add costs and no new cost profile is
+ * introduced to discover in production.
+ *
+ * ## ⛔ Nothing here is a capacity limit
+ *
+ * {@link LIST_IMPORT_MAX_ADDRESSES} refuses a FILE before anything is written.
+ * It never trims a staged import, never drops an address to fit, and never
+ * removes anybody already on the list. A ceiling in this product is enforced
+ * at the reduction, and the reduction here is refusing the upload — which the
+ * operator sees, can argue with, and can act on by splitting the file.
+ *
+ * ## Who the attester is, and why a resumer does not become one
+ *
+ * The attestation is one person's claim about where a file came from. It is
+ * recorded on the job with the account that made it, and every run reads the
+ * basis from THAT account, not from whoever pressed Resume. A colleague who
+ * finishes somebody else's import has asserted nothing, and the consent
+ * records the run writes must not say they did.
+ */
+import { type PluginApiHandler } from '@aglyn/aglyn/server';
+/** `source` stamped on every membership an import writes. */
+export declare const CONSOLE_IMPORT_SOURCE = "console:list-import";
+/** Where a list's import jobs live: `orgs/{orgId}/lists/{listId}/imports`. */
+export declare const LIST_IMPORTS_SUBCOLLECTION = "imports";
+/**
+ * Addresses one run enrolls before answering and handing back the cursor.
+ *
+ * The same number as {@link LIST_MEMBER_BATCH_MAX} on purpose — see the module
+ * note. It is a bound on WORK: it can never refuse a person, and the addresses
+ * it does not reach in this run are reached by the next one.
+ */
+export declare const LIST_IMPORT_RUN_BUDGET = 100;
+/**
+ * Staged addresses per chunk document.
+ *
+ * Comfortably inside Firestore's one-megabyte document limit at the widths a
+ * contact file actually carries, and a multiple of the run budget so a run
+ * reads exactly one chunk. Reading two would be the common case at any size
+ * that is not a multiple, which is a round trip paid on every run to save
+ * nothing.
+ */
+export declare const LIST_IMPORT_CHUNK_SIZE = 500;
+/**
+ * `POST email/list-import-preview` — what is in this file.
+ *
+ * Reads only. It answers three separate questions and keeps them separate,
+ * because collapsing them is how an import gets attested to on a number that
+ * is not the number:
+ *
+ *  - what the FILE contains: usable addresses, unusable lines, duplicates
+ *    collapsed, and the columns it carries;
+ *  - what the SCREENING found, which decides nothing and is shown anyway;
+ *  - what the CONSENT GATE says about a bounded sample of the addresses.
+ *
+ * The sample is the honest shape rather than a shortcut. Resolving fifty
+ * thousand addresses against the contacts collection and both suppression
+ * lists is the same scan the import itself performs, so a preview that did it
+ * would be the import minus the writes — twice the cost, and a request that
+ * times out on exactly the files this feature exists for. So the sample size
+ * is reported beside the total and the run reports the real figures as they
+ * become true, which is the same distinction `email/list-rule-preview` draws
+ * between `matched` and the batch it hands back.
+ */
+export declare const emailListImportPreviewHandler: PluginApiHandler;
+/**
+ * `POST email/list-import-start` — record the attestation, stage the file.
+ *
+ * Body: `{ hostId, listId, text, attestConsent }`. Enrolls nobody. It writes
+ * the job document that every subsequent run reads, and the chunks holding
+ * the addresses, and then stops — so the moment the operator makes their
+ * claim is a moment of its own, with a record of who made it and when, rather
+ * than a flag riding along on the request that also did the work.
+ *
+ * `attestConsent` is the operator STATING they have these people's
+ * permission. It is not a way to name a basis: the basis is derived per
+ * address at run time from that person's own record, exactly as the
+ * one-address add path derives it, and this flag can only ever produce the
+ * attributable kind.
+ */
+export declare const emailListImportStartHandler: PluginApiHandler;
+/**
+ * `POST email/list-import-run` — enroll the next batch.
+ *
+ * Body: `{ hostId, listId, importId }`. Answers `complete` when the cursor
+ * has reached the total, so the caller's loop is "call until complete" and
+ * nothing has to guess how many runs a file needs.
+ *
+ * ## The cursor moves for every address, enrolled or refused
+ *
+ * A refusal is a finished address. Advancing only on success would put a
+ * suppressed address at the head of the queue forever and turn the import
+ * into a loop that never terminates on exactly the files that most need to
+ * terminate.
+ *
+ * ## The counters are incremented, not recomputed
+ *
+ * `FieldValue.increment` rather than a read-modify-write, so two runs racing
+ * on one job — a merchant with the drawer open in two tabs — cannot lose a
+ * batch's worth of tally. The cursor is written as an absolute value because
+ * it is the position the NEXT run reads from, and two racing runs that both
+ * incremented it would skip a batch rather than repeat one; repeating is safe
+ * (`enrollListMember` is keyed by the person), skipping is not.
+ */
+export declare const emailListImportRunHandler: PluginApiHandler;
+/**
+ * `POST email/list-import-status` — the import on this list, if there is one.
+ *
+ * Reached when the import drawer opens, and at no other time. It exists
+ * because a browser is not a durable thing: a merchant who closed the tab
+ * during a large import has an audience that is part-way filled and, without
+ * this, no way to see that or to finish it. What they must never be offered
+ * instead is a fresh import of the same file, which would re-run the whole
+ * gate over addresses already enrolled.
+ *
+ * Ordered on `createdAt`, which every job document written by
+ * `email/list-import-start` carries — a `limit()` with no `orderBy` answers in
+ * document-id order, and the ids come from `createResourceUid()`, so the
+ * "latest" import would be an arbitrary one.
+ */
+export declare const emailListImportStatusHandler: PluginApiHandler;
+/**
+ * Import route registration.
+ *
+ * Reached by a person pressing a button in a browser, like the rest of the
+ * console half, so none of these is on the machine-path exemption list in
+ * `plugin-api-rate-limit.ts` — with one consequence worth stating: the RUN
+ * route is called repeatedly by design, once per {@link
+ * LIST_IMPORT_RUN_BUDGET} addresses, so the visitor limiter's per-(site, IP)
+ * budget is the ceiling on how fast a large import can proceed. That is the
+ * correct ceiling for a path that enrolls people into a marketing audience,
+ * and it degrades into a slower import rather than a failed one.
+ */
+export declare function registerEmailListImportApi(): void;