@aglyn/plugins-crm 1.0.0-beta.143

package/src/lib/model/crm-import.d.ts

@@ -0,0 +1,244 @@
+/**
+ * @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 A SPREADSHEET OF PEOPLE INTO THE CRM — the pure half (AGL-2602).
+ *
+ * A merchant arriving from another CRM has a CSV: a header row naming
+ * columns in that product's vocabulary, and one person per line. Nothing
+ * about that file is in our shape. This module is every decision about the
+ * file that needs no Firestore and no React — which columns mean what, how a
+ * cell becomes a stored value, and what to say about a row that cannot be
+ * stored — so that the console drawer and the server route read the same
+ * rules rather than two copies of them.
+ *
+ * ## Three stages, and only the last one touches a record
+ *
+ *  1. {@link guessContactImportMapping} reads the header and proposes a
+ *     column → field mapping from a table of aliases. It is a PROPOSAL: the
+ *     drawer shows it and the operator corrects it, because an export's
+ *     "Company" column may hold a job title and no alias table can know.
+ *  2. {@link mapContactImportRow} applies the mapping to one line, producing
+ *     the raw row the browser posts. Strings only — the browser trims nothing
+ *     and validates nothing, so the server is the one place the file is
+ *     judged and a stale drawer cannot judge it differently.
+ *  3. {@link normalizeContactImportRow} turns a raw row into the values that
+ *     will be written, through the SAME normalizers every other door uses:
+ *     `normalizeContactEmail` for the dedupe key, `normalizePhone` for E.164,
+ *     `normalizeAddress` for the postal shape, `isContactLifecycleStage` for
+ *     the stage. An importer with its own idea of a valid phone number is how
+ *     one collection ends up storing a value three ways.
+ *
+ * ## A bad cell is dropped and named; a bad row is skipped and named
+ *
+ * The only thing that makes a row unstorable is an unusable address, because
+ * the address is the identity the shared row is keyed by. Everything else is
+ * a value on the row: a phone that cannot be read as a number is left off
+ * the contact and REPORTED under {@link ContactImportRow.dropped}, so the
+ * operator learns that forty rows had a phone in a format we could not read
+ * rather than discovering, weeks later, that the phone column silently went
+ * nowhere. `list-import.ts` applies the same rule to a line that is not an
+ * address: reported, never quietly discarded.
+ *
+ * ## Ceilings are on the work, never on the audience
+ *
+ * {@link CONTACT_IMPORT_MAX_ROWS} bounds one FILE, and the drawer says so
+ * before anything is sent. {@link CONTACT_IMPORT_CHUNK_SIZE} bounds one
+ * REQUEST, so a five-thousand-row file is twenty-five requests with a
+ * progress bar between them rather than one that times out halfway with no
+ * record of what it did. Neither one ever trims a person to fit: a row past
+ * the file ceiling is refused with the file, and a row is never dropped to
+ * make a chunk smaller. The audience band is enforced where every capture
+ * enforces it — inside `upsertHostContact` — and an import reports that
+ * refusal per row rather than pre-empting it with a count of its own.
+ */
+import type { AglynPostalAddress } from '@aglyn/aglyn/foundation/definitions/contact.types';
+import { type ImportChunkResult, type ImportDroppedValue } from '@aglyn/aglyn/app-utils/csv-import';
+import { type ContactCustomValue, type ContactFieldDefinition, type ContactLifecycleStage } from '@aglyn/aglyn/app-utils/crm';
+export { customImportTarget, customImportTargetKey } from '@aglyn/aglyn/app-utils/csv-import';
+/**
+ * The ceilings are the shared ones (`csv-import.ts`), under the names this
+ * file has always exported: one file, one request and one preview are
+ * bounded the same way for every collection, because the bounds are about
+ * the browser's memory and a request's budget rather than about people.
+ */
+export declare const CONTACT_IMPORT_MAX_ROWS = 5000;
+export declare const CONTACT_IMPORT_CHUNK_SIZE = 200;
+export declare const CONTACT_IMPORT_MAX_BODY_BYTES = 2000000;
+export declare const CONTACT_IMPORT_PREVIEW_ROWS = 10;
+/**
+ * The most tags one row may carry — the profile drawer's own cap, so an
+ * imported person cannot hold more tags than a hand-edited one.
+ */
+export declare const CONTACT_IMPORT_TAGS_MAX = 20;
+/**
+ * The standard fields a column may be mapped to, in the order the mapping
+ * menu lists them. A custom field is mapped by its key — see
+ * {@link ContactImportTargetId}.
+ */
+export declare const CONTACT_IMPORT_FIELDS: readonly ["email", "name", "phone", "jobTitle", "companyName", "addressLine1", "addressLine2", "addressCity", "addressState", "addressPostalCode", "addressCountry", "tags", "ownerEmail", "lifecycleStage", "marketingConsent"];
+export type ContactImportField = (typeof CONTACT_IMPORT_FIELDS)[number];
+/** How each field reads in the mapping menu. Typed so a field cannot ship unlabeled. */
+export declare const CONTACT_IMPORT_FIELD_LABELS: Record<ContactImportField, string>;
+/**
+ * What a column is mapped to: a standard field by name, or a custom field
+ * as `custom:<key>` — see `customImportTarget`.
+ */
+export type ContactImportTargetId = ContactImportField | `custom:${string}`;
+/** Column index → target. A column absent from the map is not imported. */
+export type ContactImportMapping = Record<number, ContactImportTargetId>;
+/**
+ * A proposed mapping from a file's header row — the shared matcher over the
+ * contact vocabulary. Custom fields win over standard aliases when a header
+ * matches a definition's label or key exactly: a merchant who defined a
+ * field called "Status" meant THEIR status, not our lifecycle stage.
+ */
+export declare function guessContactImportMapping(columns: readonly string[], fields?: readonly Pick<ContactFieldDefinition, 'key' | 'label'>[]): ContactImportMapping;
+/**
+ * What the browser posts for one line: the cells the mapping selected,
+ * under the field they were mapped to, verbatim.
+ *
+ * Values are `unknown` because the server reads this off an untrusted body;
+ * the mapper below only ever writes strings into it.
+ */
+export interface ContactImportRawRow {
+    email?: unknown;
+    name?: unknown;
+    phone?: unknown;
+    jobTitle?: unknown;
+    companyName?: unknown;
+    addressLine1?: unknown;
+    addressLine2?: unknown;
+    addressCity?: unknown;
+    addressState?: unknown;
+    addressPostalCode?: unknown;
+    addressCountry?: unknown;
+    tags?: unknown;
+    ownerEmail?: unknown;
+    lifecycleStage?: unknown;
+    marketingConsent?: unknown;
+    /** Custom values keyed by definition key. */
+    custom?: unknown;
+}
+/** One parsed line under the mapping. Empty cells are left absent. */
+export declare function mapContactImportRow(cells: readonly string[], mapping: ContactImportMapping): ContactImportRawRow;
+/** Why one row was not stored. */
+export type ContactImportSkipReason = 'invalid-email' | 'duplicate' | 'audience-band'
+/** The person was erased from this workspace at their request (AGL-2623). */
+ | 'erased' | 'write-failed';
+/** How a skip reason reads on screen and in the downloaded file. */
+export declare const CONTACT_IMPORT_SKIP_LABELS: Record<ContactImportSkipReason, string>;
+/** A cell the file carried that could not be read as the field it was mapped to. */
+export type ContactImportDroppedValue = ImportDroppedValue;
+/** One row, ready to be written. */
+export interface ContactImportRow {
+    email: string;
+    name?: string;
+    /** E.164. */
+    phone?: string;
+    jobTitle?: string;
+    companyName?: string;
+    address?: AglynPostalAddress;
+    /** Lowercased, deduplicated, capped at {@link CONTACT_IMPORT_TAGS_MAX}. */
+    tags: string[];
+    /** Normalized, for the server to resolve against the org's members. */
+    ownerEmail?: string;
+    lifecycleStage?: ContactLifecycleStage;
+    marketingConsent: boolean;
+    /** Only the keys whose definition the caller supplied and whose value read. */
+    custom: Record<string, ContactCustomValue>;
+    dropped: ContactImportDroppedValue[];
+}
+export type ContactImportRowVerdict = {
+    ok: true;
+    row: ContactImportRow;
+} | {
+    ok: false;
+    reason: 'invalid-email';
+    input: string;
+};
+/**
+ * A tag cell as the tags it names.
+ *
+ * `|` or `,` separated — the CSV export writes `|`, most other products
+ * write `,` — lowercased and trimmed like the profile drawer's own tag
+ * field, so an imported `VIP` and a typed `vip` are one tag and not two.
+ */
+export declare function parseContactImportTags(value: unknown): string[];
+/**
+ * A yes/no cell as a boolean, or `null` when it is neither.
+ *
+ * The affirmatives are the ones consent and checkbox columns actually
+ * carry; the negatives are listed so that an explicit `no` is a `false`
+ * rather than an unreadable value that gets reported as dropped.
+ */
+export declare function parseContactImportFlag(value: unknown): boolean | null;
+/**
+ * A stage cell as a stage, accepting the stored id (`sales-qualified`), its
+ * label ("Sales qualified") and the spellings between them
+ * (`Sales_Qualified`), or `null` when it names none of them.
+ */
+export declare function parseContactImportLifecycleStage(value: unknown): ContactLifecycleStage | null;
+/**
+ * A cell as the value a custom field of this type stores.
+ *
+ * `{ value }` when it read, `{ value: undefined }` for a blank cell (nothing
+ * to write and nothing to report), and `null` when the cell held something
+ * the type cannot hold — a word in a number field, a choice a select does
+ * not offer. A date is stored as epoch milliseconds, the shape every other
+ * timestamp on a CRM record takes (`dueAtMs`, `expectedCloseAtMs`).
+ */
+export declare function parseContactImportCustomValue(definition: Pick<ContactFieldDefinition, 'type' | 'options'>, value: unknown): {
+    value: ContactCustomValue | undefined;
+} | null;
+/**
+ * One raw row as the values that will be written, or the reason it cannot
+ * be.
+ *
+ * `fields` is the holder's live definitions: a custom value under a key
+ * with no definition is dropped and reported, because a value nobody
+ * defined a field for is a value no form will ever show.
+ */
+export declare function normalizeContactImportRow(raw: ContactImportRawRow, fields?: readonly Pick<ContactFieldDefinition, 'key' | 'type' | 'options'>[]): ContactImportRowVerdict;
+/** One row the server did not store, by its index in the request, named by address. */
+export interface ContactImportSkippedRow {
+    index: number;
+    email: string;
+    reason: ContactImportSkipReason;
+}
+/**
+ * What one request did — the shared tally plus how many companies the
+ * company column brought into being. The drawer sums these across a file.
+ */
+export interface ContactImportChunkResult extends ImportChunkResult<ContactImportSkippedRow> {
+    companiesCreated: number;
+}
+/** An empty tally, for the drawer to fold chunk results into. */
+export declare function emptyContactImportResult(): ContactImportChunkResult;
+/**
+ * Two results as one — the shared fold, with the company tally beside it.
+ * `offset` is where the chunk started in the file, so a skipped row's index
+ * comes back as its position in the FILE rather than in the request.
+ */
+export declare function mergeContactImportResults(total: ContactImportChunkResult, chunk: ContactImportChunkResult, offset?: number): ContactImportChunkResult;
+/**
+ * The skipped rows as a file the operator can fix and re-import: the
+ * original columns verbatim plus a trailing `Skipped because` column.
+ */
+export declare function contactImportSkippedCsv(columns: readonly string[], entries: readonly {
+    cells: readonly string[];
+    reason: ContactImportSkipReason;
+}[]): string;