@aglyn/plugins-crm 1.0.0-beta.143

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

@@ -0,0 +1,154 @@
+/**
+ * @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 COMPANIES INTO THE CRM — the pure half
+ * (AGL-2621).
+ *
+ * The contact import's three stages (`crm-import.ts`) over the company
+ * vocabulary: a header row is matched to a proposed mapping, one line is
+ * mapped to a raw row of verbatim strings, and the server normalizes each
+ * row through the SAME functions the company drawer runs —
+ * `normalizeCompanyDomain` for the key, `normalizeCompanyWebsite` for the
+ * link, `normalizePhone` for E.164, `normalizeAddress` for the postal shape
+ * — so an imported company and a typed one are the same document.
+ *
+ * ## The name is the one thing a row must have
+ *
+ * A company is matched by its DOMAIN first and its name second, because a
+ * domain is a key and a name is a spelling: two files calling one business
+ * "Acme" and "Acme Inc" meet at `acme.com`. But a row with a domain and no
+ * name would create a record the list cannot caption, so the name is
+ * required and the domain optional — the opposite of the contact import,
+ * where the address is both the key and the caption.
+ *
+ * ## A bad cell is dropped and named; a bad row is skipped and named
+ *
+ * The contact import's rule, unchanged: a domain that is not a hostname, a
+ * phone that is not a number, a website that is not a URL, a country that
+ * is not a code — each is left off the record and REPORTED under
+ * {@link CompanyImportRow.dropped}, never silently discarded.
+ */
+import type { AglynPostalAddress } from '@aglyn/aglyn/foundation/definitions/contact.types';
+import { type ContactFieldDefinition, type CrmCustomValue } from '@aglyn/aglyn/app-utils/crm';
+import { type ImportChunkResult, type ImportDroppedValue } from '@aglyn/aglyn/app-utils/csv-import';
+/** The shared ceilings, under this collection's names. */
+export declare const COMPANY_IMPORT_MAX_ROWS = 5000;
+export declare const COMPANY_IMPORT_CHUNK_SIZE = 200;
+export declare const COMPANY_IMPORT_MAX_BODY_BYTES = 2000000;
+export declare const COMPANY_IMPORT_PREVIEW_ROWS = 10;
+/** The most tags one company may carry — the same cap a contact has. */
+export declare const COMPANY_IMPORT_TAGS_MAX = 20;
+/** The fields a column may be mapped to, in the order the mapping menu lists them. */
+export declare const COMPANY_IMPORT_FIELDS: readonly ["name", "domain", "website", "phone", "industry", "ownerEmail", "addressLine1", "addressLine2", "addressCity", "addressState", "addressPostalCode", "addressCountry", "tags", "notes"];
+export type CompanyImportField = (typeof COMPANY_IMPORT_FIELDS)[number];
+/** How each field reads in the mapping menu. Typed so a field cannot ship unlabeled. */
+export declare const COMPANY_IMPORT_FIELD_LABELS: Record<CompanyImportField, string>;
+/**
+ * Column index → field, or a company custom field as `custom:<key>` (AGL-2661).
+ * A column absent from the map is not imported.
+ */
+export type CompanyImportMapping = Record<number, CompanyImportField | `custom:${string}`>;
+/**
+ * A proposed mapping from a file's header row, each field taken at most
+ * once. `fields` is the org's COMPANY definitions (AGL-2661): a header
+ * matching one's label or key maps onto it, and wins over a standard
+ * alias, the contact import's rule.
+ */
+export declare function guessCompanyImportMapping(columns: readonly string[], fields?: readonly Pick<ContactFieldDefinition, 'key' | 'label'>[]): CompanyImportMapping;
+/**
+ * What the browser posts for one line: the cells the mapping selected,
+ * under the field they were mapped to, verbatim. `unknown` because the
+ * server reads this off an untrusted body.
+ */
+export type CompanyImportRawRow = Partial<Record<CompanyImportField, unknown>> & {
+    /** Custom values by definition key, verbatim — judged by `normalizeCompanyImportRow`. */
+    custom?: unknown;
+};
+/**
+ * One parsed line under the mapping. Empty cells are left absent; custom
+ * values are gathered under `custom` by definition key (AGL-2661).
+ */
+export declare function mapCompanyImportRow(cells: readonly string[], mapping: CompanyImportMapping): CompanyImportRawRow;
+/** Why one row was not stored. */
+export type CompanyImportSkipReason = 'missing-name' | 'duplicate' | 'records-band' | 'write-failed';
+/** How a skip reason reads on screen and in the downloaded file. */
+export declare const COMPANY_IMPORT_SKIP_LABELS: Record<CompanyImportSkipReason, string>;
+/** One row, ready to be written. */
+export interface CompanyImportRow {
+    name: string;
+    /** Lowercase hostname — the match key when present. */
+    domain?: string;
+    /** An absolute http(s) URL. */
+    website?: string;
+    /** E.164. */
+    phone?: string;
+    industry?: string;
+    /** Normalized, for the server to resolve against the org's members. */
+    ownerEmail?: string;
+    address?: AglynPostalAddress;
+    /** Lowercased, deduplicated, capped at {@link COMPANY_IMPORT_TAGS_MAX}. */
+    tags: string[];
+    notes?: string;
+    dropped: ImportDroppedValue[];
+    /**
+     * Custom values under the org's COMPANY definitions (AGL-2661), each
+     * coerced by its type the way a contact's are. Empty when the file
+     * mapped none, or none survived.
+     */
+    custom: Record<string, CrmCustomValue>;
+}
+export type CompanyImportRowVerdict = {
+    ok: true;
+    row: CompanyImportRow;
+} | {
+    ok: false;
+    reason: 'missing-name';
+    input: string;
+};
+/**
+ * One raw row as the values that will be written, or the reason it cannot
+ * be. Refused only for a missing name; every other unreadable cell is
+ * dropped and named.
+ */
+export declare function normalizeCompanyImportRow(raw: CompanyImportRawRow, 
+/**
+ * The org's live COMPANY definitions (AGL-2661): a value under a key
+ * with no definition is dropped and reported, because a value nobody
+ * defined a field for is a value no surface will ever show.
+ */
+fields?: readonly Pick<ContactFieldDefinition, 'key' | 'type' | 'options'>[]): CompanyImportRowVerdict;
+/**
+ * How two rows are recognized as one company: by domain when the row has
+ * one, else by the name's search key — the same `nameLower` the companies
+ * list searches on, so "Acme" and "ACME " are one key.
+ */
+export declare function companyImportMatchKey(row: Pick<CompanyImportRow, 'name' | 'domain'>): string;
+/** One row the server did not store, by its index in the request, named by the company. */
+export interface CompanyImportSkippedRow {
+    index: number;
+    name: string;
+    reason: CompanyImportSkipReason;
+}
+/** What one request did. The drawer sums these across a file. */
+export type CompanyImportChunkResult = ImportChunkResult<CompanyImportSkippedRow>;
+export declare function emptyCompanyImportResult(): CompanyImportChunkResult;
+export declare function mergeCompanyImportResults(total: CompanyImportChunkResult, chunk: CompanyImportChunkResult, offset?: number): CompanyImportChunkResult;
+/** The skipped rows as a file the operator can fix and re-import. */
+export declare function companyImportSkippedCsv(columns: readonly string[], entries: readonly {
+    cells: readonly string[];
+    reason: CompanyImportSkipReason;
+}[]): string;

package/src/lib/model/crm-company-import.js

@@ -0,0 +1,331 @@
+/**
+ * @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 COMPANIES INTO THE CRM — the pure half
+ * (AGL-2621).
+ *
+ * The contact import's three stages (`crm-import.ts`) over the company
+ * vocabulary: a header row is matched to a proposed mapping, one line is
+ * mapped to a raw row of verbatim strings, and the server normalizes each
+ * row through the SAME functions the company drawer runs —
+ * `normalizeCompanyDomain` for the key, `normalizeCompanyWebsite` for the
+ * link, `normalizePhone` for E.164, `normalizeAddress` for the postal shape
+ * — so an imported company and a typed one are the same document.
+ *
+ * ## The name is the one thing a row must have
+ *
+ * A company is matched by its DOMAIN first and its name second, because a
+ * domain is a key and a name is a spelling: two files calling one business
+ * "Acme" and "Acme Inc" meet at `acme.com`. But a row with a domain and no
+ * name would create a record the list cannot caption, so the name is
+ * required and the domain optional — the opposite of the contact import,
+ * where the address is both the key and the caption.
+ *
+ * ## A bad cell is dropped and named; a bad row is skipped and named
+ *
+ * The contact import's rule, unchanged: a domain that is not a hostname, a
+ * phone that is not a number, a website that is not a URL, a country that
+ * is not a code — each is left off the record and REPORTED under
+ * {@link CompanyImportRow.dropped}, never silently discarded.
+ */ import { normalizeAddress, normalizePhone } from "@aglyn/aglyn/foundation/definitions/contact.types";
+import { normalizeContactEmail } from "@aglyn/aglyn/app-utils/contacts";
+import { normalizeCompanyDomain, normalizeCompanyWebsite } from "@aglyn/aglyn/app-utils/crm";
+import { parseContactImportCustomValue } from "./crm-import.js";
+import { customImportTarget, CSV_IMPORT_CHUNK_SIZE, CSV_IMPORT_MAX_BODY_BYTES, CSV_IMPORT_MAX_ROWS, CSV_IMPORT_PREVIEW_ROWS, emptyImportResult, guessImportMapping, importAliasKeys, importSkippedCsv, importTextValue, mapImportRow, mergeImportResults, parseImportTags } from "@aglyn/aglyn/app-utils/csv-import";
+import { nameSearchKey } from "@aglyn/aglyn/app-utils/name-search";
+/** The shared ceilings, under this collection's names. */ export const COMPANY_IMPORT_MAX_ROWS = CSV_IMPORT_MAX_ROWS;
+export const COMPANY_IMPORT_CHUNK_SIZE = CSV_IMPORT_CHUNK_SIZE;
+export const COMPANY_IMPORT_MAX_BODY_BYTES = CSV_IMPORT_MAX_BODY_BYTES;
+export const COMPANY_IMPORT_PREVIEW_ROWS = CSV_IMPORT_PREVIEW_ROWS;
+/** The most tags one company may carry — the same cap a contact has. */ export const COMPANY_IMPORT_TAGS_MAX = 20;
+const NAME_MAX = 120;
+const INDUSTRY_MAX = 80;
+const NOTES_MAX = 4000;
+/** The fields a column may be mapped to, in the order the mapping menu lists them. */ export const COMPANY_IMPORT_FIELDS = [
+    'name',
+    'domain',
+    'website',
+    'phone',
+    'industry',
+    'ownerEmail',
+    'addressLine1',
+    'addressLine2',
+    'addressCity',
+    'addressState',
+    'addressPostalCode',
+    'addressCountry',
+    'tags',
+    'notes'
+];
+/** How each field reads in the mapping menu. Typed so a field cannot ship unlabeled. */ export const COMPANY_IMPORT_FIELD_LABELS = {
+    name: 'Company name (required)',
+    domain: 'Domain',
+    website: 'Website',
+    phone: 'Phone',
+    industry: 'Industry',
+    ownerEmail: 'Owner (team member email)',
+    addressLine1: 'Address line 1',
+    addressLine2: 'Address line 2',
+    addressCity: 'City',
+    addressState: 'State or region',
+    addressPostalCode: 'Postal code',
+    addressCountry: 'Country (two-letter code)',
+    tags: 'Tags (comma or | separated)',
+    notes: 'Notes'
+};
+/**
+ * Header aliases per field, matched after the shared header normalization.
+ *
+ * The vocabulary of the exports people arrive with, and — first in each
+ * list — the header this CRM's own companies export writes, so an export
+ * re-imports without a hand mapping.
+ */ const FIELD_ALIASES = {
+    name: [
+        'company',
+        'company name',
+        'name',
+        'organization',
+        'organisation',
+        'account',
+        'account name'
+    ],
+    domain: [
+        'domain',
+        'company domain',
+        'domain name',
+        'web domain',
+        'email domain'
+    ],
+    website: [
+        'website',
+        'web site',
+        'url',
+        'website url',
+        'homepage',
+        'web'
+    ],
+    phone: [
+        'phone',
+        'phone number',
+        'telephone',
+        'company phone',
+        'main phone'
+    ],
+    industry: [
+        'industry',
+        'sector',
+        'vertical',
+        'category'
+    ],
+    ownerEmail: [
+        'owner',
+        'owner email',
+        'company owner',
+        'account owner',
+        'assigned to'
+    ],
+    addressLine1: [
+        'address line 1',
+        'address',
+        'street',
+        'street address',
+        'address 1'
+    ],
+    addressLine2: [
+        'address line 2',
+        'address 2',
+        'street 2',
+        'suite'
+    ],
+    addressCity: [
+        'city',
+        'town',
+        'locality'
+    ],
+    addressState: [
+        'state',
+        'region',
+        'province',
+        'county',
+        'state/region'
+    ],
+    addressPostalCode: [
+        'postal code',
+        'postcode',
+        'zip',
+        'zip code',
+        'post code'
+    ],
+    addressCountry: [
+        'country',
+        'country code',
+        'country/region'
+    ],
+    tags: [
+        'tags',
+        'tag',
+        'labels',
+        'groups'
+    ],
+    notes: [
+        'notes',
+        'note',
+        'description',
+        'comments'
+    ]
+};
+const FIELD_ALIAS_KEYS = importAliasKeys(COMPANY_IMPORT_FIELDS, FIELD_ALIASES);
+/**
+ * A proposed mapping from a file's header row, each field taken at most
+ * once. `fields` is the org's COMPANY definitions (AGL-2661): a header
+ * matching one's label or key maps onto it, and wins over a standard
+ * alias, the contact import's rule.
+ */ export function guessCompanyImportMapping(columns, fields = []) {
+    return guessImportMapping(columns, COMPANY_IMPORT_FIELDS, FIELD_ALIAS_KEYS, fields);
+}
+/**
+ * One parsed line under the mapping. Empty cells are left absent; custom
+ * values are gathered under `custom` by definition key (AGL-2661).
+ */ export function mapCompanyImportRow(cells, mapping) {
+    return mapImportRow(cells, mapping);
+}
+/** How a skip reason reads on screen and in the downloaded file. */ export const COMPANY_IMPORT_SKIP_LABELS = {
+    'missing-name': 'No company name',
+    duplicate: 'Appears earlier in the file',
+    'records-band': 'CRM records limit reached',
+    'write-failed': 'Could not be saved'
+};
+/**
+ * One raw row as the values that will be written, or the reason it cannot
+ * be. Refused only for a missing name; every other unreadable cell is
+ * dropped and named.
+ */ export function normalizeCompanyImportRow(raw, /**
+   * The org's live COMPANY definitions (AGL-2661): a value under a key
+   * with no definition is dropped and reported, because a value nobody
+   * defined a field for is a value no surface will ever show.
+   */ fields = []) {
+    var _importTextValue;
+    const name = (_importTextValue = importTextValue(raw.name, NAME_MAX)) == null ? void 0 : _importTextValue.replace(/\s+/g, ' ');
+    if (!name) {
+        var _raw_domain;
+        return {
+            ok: false,
+            reason: 'missing-name',
+            input: String((_raw_domain = raw.domain) != null ? _raw_domain : '').trim()
+        };
+    }
+    const dropped = [];
+    const drop = (field, value)=>{
+        dropped.push({
+            field,
+            value: String(value != null ? value : '').trim()
+        });
+    };
+    const row = {
+        name,
+        tags: parseImportTags(raw.tags, COMPANY_IMPORT_TAGS_MAX),
+        dropped,
+        custom: {}
+    };
+    const domainText = importTextValue(raw.domain, 300);
+    if (domainText) {
+        const domain = normalizeCompanyDomain(domainText);
+        if (domain) row.domain = domain;
+        else drop('domain', domainText);
+    }
+    const websiteText = importTextValue(raw.website, 600);
+    if (websiteText) {
+        const website = normalizeCompanyWebsite(websiteText);
+        if (website) row.website = website;
+        else drop('website', websiteText);
+    }
+    const phoneText = importTextValue(raw.phone, 64);
+    if (phoneText) {
+        const phone = normalizePhone(phoneText);
+        if (phone) row.phone = phone;
+        else drop('phone', phoneText);
+    }
+    const industry = importTextValue(raw.industry, INDUSTRY_MAX);
+    if (industry) row.industry = industry;
+    const ownerText = importTextValue(raw.ownerEmail, 320);
+    if (ownerText) {
+        const owner = normalizeContactEmail(ownerText);
+        if (owner) row.ownerEmail = owner;
+        else drop('ownerEmail', ownerText);
+    }
+    const address = normalizeAddress({
+        line1: importTextValue(raw.addressLine1, 200),
+        line2: importTextValue(raw.addressLine2, 200),
+        city: importTextValue(raw.addressCity, 120),
+        state: importTextValue(raw.addressState, 120),
+        postalCode: importTextValue(raw.addressPostalCode, 32),
+        country: importTextValue(raw.addressCountry, 8)
+    });
+    if (address) row.address = address;
+    // The country is the one address part the normalizer drops silently — a
+    // typed name is not a code — so it is the one part the report has to name.
+    const countryText = importTextValue(raw.addressCountry, 64);
+    if (countryText && !(address == null ? void 0 : address.country)) drop('addressCountry', countryText);
+    const notes = importTextValue(raw.notes, NOTES_MAX);
+    if (notes) row.notes = notes;
+    // The contact import's custom rule, over the company's definitions.
+    const custom = raw.custom && typeof raw.custom === 'object' && !Array.isArray(raw.custom) ? raw.custom : {};
+    const definitions = new Map(fields.map((field)=>[
+            field.key,
+            field
+        ]));
+    for (const [key, value] of Object.entries(custom)){
+        const definition = definitions.get(key);
+        if (!definition) {
+            dropped.push({
+                field: customImportTarget(key),
+                value: String(value != null ? value : '').trim()
+            });
+            continue;
+        }
+        const parsed = parseContactImportCustomValue(definition, value);
+        if (!parsed) {
+            dropped.push({
+                field: customImportTarget(key),
+                value: String(value != null ? value : '').trim()
+            });
+        } else if (parsed.value !== undefined) {
+            row.custom[key] = parsed.value;
+        }
+    }
+    return {
+        ok: true,
+        row
+    };
+}
+/**
+ * How two rows are recognized as one company: by domain when the row has
+ * one, else by the name's search key — the same `nameLower` the companies
+ * list searches on, so "Acme" and "ACME " are one key.
+ */ export function companyImportMatchKey(row) {
+    return row.domain ? `domain:${row.domain}` : `name:${nameSearchKey(row.name)}`;
+}
+export function emptyCompanyImportResult() {
+    return emptyImportResult();
+}
+export function mergeCompanyImportResults(total, chunk, offset = 0) {
+    return mergeImportResults(total, chunk, offset);
+}
+/** The skipped rows as a file the operator can fix and re-import. */ export function companyImportSkippedCsv(columns, entries) {
+    return importSkippedCsv(columns, entries, COMPANY_IMPORT_SKIP_LABELS);
+}
+
+//# sourceMappingURL=crm-company-import.js.map

package/src/lib/model/crm-company-import.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/crm/src/lib/model/crm-company-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 * BRINGING A SPREADSHEET OF COMPANIES INTO THE CRM — the pure half\n * (AGL-2621).\n *\n * The contact import's three stages (`crm-import.ts`) over the company\n * vocabulary: a header row is matched to a proposed mapping, one line is\n * mapped to a raw row of verbatim strings, and the server normalizes each\n * row through the SAME functions the company drawer runs —\n * `normalizeCompanyDomain` for the key, `normalizeCompanyWebsite` for the\n * link, `normalizePhone` for E.164, `normalizeAddress` for the postal shape\n * — so an imported company and a typed one are the same document.\n *\n * ## The name is the one thing a row must have\n *\n * A company is matched by its DOMAIN first and its name second, because a\n * domain is a key and a name is a spelling: two files calling one business\n * \"Acme\" and \"Acme Inc\" meet at `acme.com`. But a row with a domain and no\n * name would create a record the list cannot caption, so the name is\n * required and the domain optional — the opposite of the contact import,\n * where the address is both the key and the caption.\n *\n * ## A bad cell is dropped and named; a bad row is skipped and named\n *\n * The contact import's rule, unchanged: a domain that is not a hostname, a\n * phone that is not a number, a website that is not a URL, a country that\n * is not a code — each is left off the record and REPORTED under\n * {@link CompanyImportRow.dropped}, never silently discarded.\n */\n\nimport type { AglynPostalAddress } from '@aglyn/aglyn/foundation/definitions/contact.types'\nimport { normalizeAddress, normalizePhone } from '@aglyn/aglyn/foundation/definitions/contact.types'\nimport { normalizeContactEmail } from '@aglyn/aglyn/app-utils/contacts'\nimport {\n  type ContactFieldDefinition,\n  type CrmCustomValue,\n  normalizeCompanyDomain,\n  normalizeCompanyWebsite,\n} from '@aglyn/aglyn/app-utils/crm'\nimport { parseContactImportCustomValue } from './crm-import'\nimport {\n  customImportTarget,\n  CSV_IMPORT_CHUNK_SIZE,\n  CSV_IMPORT_MAX_BODY_BYTES,\n  CSV_IMPORT_MAX_ROWS,\n  CSV_IMPORT_PREVIEW_ROWS,\n  emptyImportResult,\n  guessImportMapping,\n  importAliasKeys,\n  type ImportChunkResult,\n  type ImportDroppedValue,\n  importSkippedCsv,\n  importTextValue,\n  mapImportRow,\n  mergeImportResults,\n  parseImportTags,\n} from '@aglyn/aglyn/app-utils/csv-import'\nimport { nameSearchKey } from '@aglyn/aglyn/app-utils/name-search'\n\n/** The shared ceilings, under this collection's names. */\nexport const COMPANY_IMPORT_MAX_ROWS = CSV_IMPORT_MAX_ROWS\nexport const COMPANY_IMPORT_CHUNK_SIZE = CSV_IMPORT_CHUNK_SIZE\nexport const COMPANY_IMPORT_MAX_BODY_BYTES = CSV_IMPORT_MAX_BODY_BYTES\nexport const COMPANY_IMPORT_PREVIEW_ROWS = CSV_IMPORT_PREVIEW_ROWS\n\n/** The most tags one company may carry — the same cap a contact has. */\nexport const COMPANY_IMPORT_TAGS_MAX = 20\n\nconst NAME_MAX = 120\nconst INDUSTRY_MAX = 80\nconst NOTES_MAX = 4000\n\n/** The fields a column may be mapped to, in the order the mapping menu lists them. */\nexport const COMPANY_IMPORT_FIELDS = [\n  'name',\n  'domain',\n  'website',\n  'phone',\n  'industry',\n  'ownerEmail',\n  'addressLine1',\n  'addressLine2',\n  'addressCity',\n  'addressState',\n  'addressPostalCode',\n  'addressCountry',\n  'tags',\n  'notes',\n] as const\n\nexport type CompanyImportField = (typeof COMPANY_IMPORT_FIELDS)[number]\n\n/** How each field reads in the mapping menu. Typed so a field cannot ship unlabeled. */\nexport const COMPANY_IMPORT_FIELD_LABELS: Record<CompanyImportField, string> = {\n  name: 'Company name (required)',\n  domain: 'Domain',\n  website: 'Website',\n  phone: 'Phone',\n  industry: 'Industry',\n  ownerEmail: 'Owner (team member email)',\n  addressLine1: 'Address line 1',\n  addressLine2: 'Address line 2',\n  addressCity: 'City',\n  addressState: 'State or region',\n  addressPostalCode: 'Postal code',\n  addressCountry: 'Country (two-letter code)',\n  tags: 'Tags (comma or | separated)',\n  notes: 'Notes',\n}\n\n/**\n * Header aliases per field, matched after the shared header normalization.\n *\n * The vocabulary of the exports people arrive with, and — first in each\n * list — the header this CRM's own companies export writes, so an export\n * re-imports without a hand mapping.\n */\nconst FIELD_ALIASES: Record<CompanyImportField, readonly string[]> = {\n  name: ['company', 'company name', 'name', 'organization', 'organisation', 'account', 'account name'],\n  domain: ['domain', 'company domain', 'domain name', 'web domain', 'email domain'],\n  website: ['website', 'web site', 'url', 'website url', 'homepage', 'web'],\n  phone: ['phone', 'phone number', 'telephone', 'company phone', 'main phone'],\n  industry: ['industry', 'sector', 'vertical', 'category'],\n  ownerEmail: ['owner', 'owner email', 'company owner', 'account owner', 'assigned to'],\n  addressLine1: ['address line 1', 'address', 'street', 'street address', 'address 1'],\n  addressLine2: ['address line 2', 'address 2', 'street 2', 'suite'],\n  addressCity: ['city', 'town', 'locality'],\n  addressState: ['state', 'region', 'province', 'county', 'state/region'],\n  addressPostalCode: ['postal code', 'postcode', 'zip', 'zip code', 'post code'],\n  addressCountry: ['country', 'country code', 'country/region'],\n  tags: ['tags', 'tag', 'labels', 'groups'],\n  notes: ['notes', 'note', 'description', 'comments'],\n}\n\nconst FIELD_ALIAS_KEYS = importAliasKeys(COMPANY_IMPORT_FIELDS, FIELD_ALIASES)\n\n/**\n * Column index → field, or a company custom field as `custom:<key>` (AGL-2661).\n * A column absent from the map is not imported.\n */\nexport type CompanyImportMapping = Record<number, CompanyImportField | `custom:${string}`>\n\n/**\n * A proposed mapping from a file's header row, each field taken at most\n * once. `fields` is the org's COMPANY definitions (AGL-2661): a header\n * matching one's label or key maps onto it, and wins over a standard\n * alias, the contact import's rule.\n */\nexport function guessCompanyImportMapping(\n  columns: readonly string[],\n  fields: readonly Pick<ContactFieldDefinition, 'key' | 'label'>[] = [],\n): CompanyImportMapping {\n  return guessImportMapping(columns, COMPANY_IMPORT_FIELDS, FIELD_ALIAS_KEYS, fields)\n}\n\n/**\n * What the browser posts for one line: the cells the mapping selected,\n * under the field they were mapped to, verbatim. `unknown` because the\n * server reads this off an untrusted body.\n */\nexport type CompanyImportRawRow = Partial<Record<CompanyImportField, unknown>> & {\n  /** Custom values by definition key, verbatim — judged by `normalizeCompanyImportRow`. */\n  custom?: unknown\n}\n\n/**\n * One parsed line under the mapping. Empty cells are left absent; custom\n * values are gathered under `custom` by definition key (AGL-2661).\n */\nexport function mapCompanyImportRow(\n  cells: readonly string[],\n  mapping: CompanyImportMapping,\n): CompanyImportRawRow {\n  return mapImportRow(cells, mapping)\n}\n\n/** Why one row was not stored. */\nexport type CompanyImportSkipReason =\n  | 'missing-name'\n  | 'duplicate'\n  | 'records-band'\n  | 'write-failed'\n\n/** How a skip reason reads on screen and in the downloaded file. */\nexport const COMPANY_IMPORT_SKIP_LABELS: Record<CompanyImportSkipReason, string> = {\n  'missing-name': 'No company name',\n  duplicate: 'Appears earlier in the file',\n  'records-band': 'CRM records limit reached',\n  'write-failed': 'Could not be saved',\n}\n\n/** One row, ready to be written. */\nexport interface CompanyImportRow {\n  name: string\n  /** Lowercase hostname — the match key when present. */\n  domain?: string\n  /** An absolute http(s) URL. */\n  website?: string\n  /** E.164. */\n  phone?: string\n  industry?: string\n  /** Normalized, for the server to resolve against the org's members. */\n  ownerEmail?: string\n  address?: AglynPostalAddress\n  /** Lowercased, deduplicated, capped at {@link COMPANY_IMPORT_TAGS_MAX}. */\n  tags: string[]\n  notes?: string\n  dropped: ImportDroppedValue[]\n  /**\n   * Custom values under the org's COMPANY definitions (AGL-2661), each\n   * coerced by its type the way a contact's are. Empty when the file\n   * mapped none, or none survived.\n   */\n  custom: Record<string, CrmCustomValue>\n}\n\nexport type CompanyImportRowVerdict =\n  | { ok: true; row: CompanyImportRow }\n  | { ok: false; reason: 'missing-name'; input: string }\n\n/**\n * One raw row as the values that will be written, or the reason it cannot\n * be. Refused only for a missing name; every other unreadable cell is\n * dropped and named.\n */\nexport function normalizeCompanyImportRow(\n  raw: CompanyImportRawRow,\n  /**\n   * The org's live COMPANY definitions (AGL-2661): a value under a key\n   * with no definition is dropped and reported, because a value nobody\n   * defined a field for is a value no surface will ever show.\n   */\n  fields: readonly Pick<ContactFieldDefinition, 'key' | 'type' | 'options'>[] = [],\n): CompanyImportRowVerdict {\n  const name = importTextValue(raw.name, NAME_MAX)?.replace(/\\s+/g, ' ')\n  if (!name) {\n    return { ok: false, reason: 'missing-name', input: String(raw.domain ?? '').trim() }\n  }\n  const dropped: ImportDroppedValue[] = []\n  const drop = (field: CompanyImportField, value: unknown) => {\n    dropped.push({ field, value: String(value ?? '').trim() })\n  }\n  const row: CompanyImportRow = {\n    name,\n    tags: parseImportTags(raw.tags, COMPANY_IMPORT_TAGS_MAX),\n    dropped,\n    custom: {},\n  }\n\n  const domainText = importTextValue(raw.domain, 300)\n  if (domainText) {\n    const domain = normalizeCompanyDomain(domainText)\n    if (domain) row.domain = domain\n    else drop('domain', domainText)\n  }\n\n  const websiteText = importTextValue(raw.website, 600)\n  if (websiteText) {\n    const website = normalizeCompanyWebsite(websiteText)\n    if (website) row.website = website\n    else drop('website', websiteText)\n  }\n\n  const phoneText = importTextValue(raw.phone, 64)\n  if (phoneText) {\n    const phone = normalizePhone(phoneText)\n    if (phone) row.phone = phone\n    else drop('phone', phoneText)\n  }\n\n  const industry = importTextValue(raw.industry, INDUSTRY_MAX)\n  if (industry) row.industry = industry\n\n  const ownerText = importTextValue(raw.ownerEmail, 320)\n  if (ownerText) {\n    const owner = normalizeContactEmail(ownerText)\n    if (owner) row.ownerEmail = owner\n    else drop('ownerEmail', ownerText)\n  }\n\n  const address = normalizeAddress({\n    line1: importTextValue(raw.addressLine1, 200),\n    line2: importTextValue(raw.addressLine2, 200),\n    city: importTextValue(raw.addressCity, 120),\n    state: importTextValue(raw.addressState, 120),\n    postalCode: importTextValue(raw.addressPostalCode, 32),\n    country: importTextValue(raw.addressCountry, 8),\n  })\n  if (address) row.address = address\n  // The country is the one address part the normalizer drops silently — a\n  // typed name is not a code — so it is the one part the report has to name.\n  const countryText = importTextValue(raw.addressCountry, 64)\n  if (countryText && !address?.country) drop('addressCountry', countryText)\n\n  const notes = importTextValue(raw.notes, NOTES_MAX)\n  if (notes) row.notes = notes\n\n  // The contact import's custom rule, over the company's definitions.\n  const custom =\n    raw.custom && typeof raw.custom === 'object' && !Array.isArray(raw.custom)\n      ? (raw.custom as Record<string, unknown>)\n      : {}\n  const definitions = new Map(fields.map((field) => [field.key, field]))\n  for (const [key, value] of Object.entries(custom)) {\n    const definition = definitions.get(key)\n    if (!definition) {\n      dropped.push({ field: customImportTarget(key), value: String(value ?? '').trim() })\n      continue\n    }\n    const parsed = parseContactImportCustomValue(definition, value)\n    if (!parsed) {\n      dropped.push({ field: customImportTarget(key), value: String(value ?? '').trim() })\n    } else if (parsed.value !== undefined) {\n      row.custom[key] = parsed.value\n    }\n  }\n\n  return { ok: true, row }\n}\n\n/**\n * How two rows are recognized as one company: by domain when the row has\n * one, else by the name's search key — the same `nameLower` the companies\n * list searches on, so \"Acme\" and \"ACME \" are one key.\n */\nexport function companyImportMatchKey(\n  row: Pick<CompanyImportRow, 'name' | 'domain'>,\n): string {\n  return row.domain ? `domain:${row.domain}` : `name:${nameSearchKey(row.name)}`\n}\n\n/** One row the server did not store, by its index in the request, named by the company. */\nexport interface CompanyImportSkippedRow {\n  index: number\n  name: string\n  reason: CompanyImportSkipReason\n}\n\n/** What one request did. The drawer sums these across a file. */\nexport type CompanyImportChunkResult = ImportChunkResult<CompanyImportSkippedRow>\n\nexport function emptyCompanyImportResult(): CompanyImportChunkResult {\n  return emptyImportResult<CompanyImportSkippedRow>()\n}\n\nexport function mergeCompanyImportResults(\n  total: CompanyImportChunkResult,\n  chunk: CompanyImportChunkResult,\n  offset = 0,\n): CompanyImportChunkResult {\n  return mergeImportResults(total, chunk, offset)\n}\n\n/** The skipped rows as a file the operator can fix and re-import. */\nexport function companyImportSkippedCsv(\n  columns: readonly string[],\n  entries: readonly { cells: readonly string[]; reason: CompanyImportSkipReason }[],\n): string {\n  return importSkippedCsv(columns, entries, COMPANY_IMPORT_SKIP_LABELS)\n}\n"],"names":["normalizeAddress","normalizePhone","normalizeContactEmail","normalizeCompanyDomain","normalizeCompanyWebsite","parseContactImportCustomValue","customImportTarget","CSV_IMPORT_CHUNK_SIZE","CSV_IMPORT_MAX_BODY_BYTES","CSV_IMPORT_MAX_ROWS","CSV_IMPORT_PREVIEW_ROWS","emptyImportResult","guessImportMapping","importAliasKeys","importSkippedCsv","importTextValue","mapImportRow","mergeImportResults","parseImportTags","nameSearchKey","COMPANY_IMPORT_MAX_ROWS","COMPANY_IMPORT_CHUNK_SIZE","COMPANY_IMPORT_MAX_BODY_BYTES","COMPANY_IMPORT_PREVIEW_ROWS","COMPANY_IMPORT_TAGS_MAX","NAME_MAX","INDUSTRY_MAX","NOTES_MAX","COMPANY_IMPORT_FIELDS","COMPANY_IMPORT_FIELD_LABELS","name","domain","website","phone","industry","ownerEmail","addressLine1","addressLine2","addressCity","addressState","addressPostalCode","addressCountry","tags","notes","FIELD_ALIASES","FIELD_ALIAS_KEYS","guessCompanyImportMapping","columns","fields","mapCompanyImportRow","cells","mapping","COMPANY_IMPORT_SKIP_LABELS","duplicate","normalizeCompanyImportRow","raw","replace","ok","reason","input","String","trim","dropped","drop","field","value","push","row","custom","domainText","websiteText","phoneText","ownerText","owner","address","line1","line2","city","state","postalCode","country","countryText","Array","isArray","definitions","Map","map","key","Object","entries","definition","get","parsed","undefined","companyImportMatchKey","emptyCompanyImportResult","mergeCompanyImportResults","total","chunk","offset","companyImportSkippedCsv"],"mappings":"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"}

package/src/lib/model/crm-custom-draft.d.ts

@@ -0,0 +1,62 @@
+/**
+ * @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.
+ */
+import type { ContactFieldDefinition, CrmCustomValue } from '@aglyn/aglyn';
+/**
+ * A custom-field DRAFT: the keys a person touched, over what is stored
+ * (AGL-2661).
+ *
+ * Every surface that edits a `custom` map — the contact's card, the
+ * company's and the deal's drawers — holds the same two things: the map
+ * as it was read, and the keys the reader has changed since. What Save
+ * writes is the difference, key by key, because a `custom` map written
+ * whole would take every key the surface did not show out with it, and a
+ * write of every key would turn a one-field edit into a write of ten.
+ * Pure, so the three surfaces cannot drift on what "changed" means.
+ */
+export type CrmCustomDraft = Record<string, CrmCustomValue>;
+/** A stored `custom` map, as read — absent keys and `null` both read as nothing. */
+export type CrmCustomStored = Readonly<Record<string, CrmCustomValue | undefined>>;
+/** The value a key shows: the draft's where touched, else the stored one. */
+export declare function crmCustomDraftValue(stored: CrmCustomStored, draft: CrmCustomDraft, key: string): CrmCustomValue | undefined;
+/**
+ * The keys whose draft differs from what is stored, with the value to
+ * write — `null` for a cleared one, the explicit "nothing" that keeps the
+ * key present for a `where` clause to find.
+ */
+export declare function crmCustomDraftChanges(stored: CrmCustomStored, draft: CrmCustomDraft): Array<[key: string, value: CrmCustomValue]>;
+/**
+ * The changes as an `update()` payload: one dotted path per key, so the
+ * map is merged rather than replaced. Empty when nothing changed, so a
+ * caller can spread it into a larger write unconditionally.
+ */
+export declare function crmCustomDraftWrites(stored: CrmCustomStored, draft: CrmCustomDraft): Record<`custom.${string}`, CrmCustomValue>;
+/**
+ * The draft as the `custom` map a CREATE stores: every key with a value,
+ * `null` and absent both left out because a fresh document has nothing to
+ * clear. `undefined` when nothing would be stored, so a caller spreads
+ * `{ custom }` only when there is one.
+ */
+export declare function crmCustomDraftDocument(draft: CrmCustomDraft): Record<string, CrmCustomValue> | undefined;
+/**
+ * The required definitions the draft leaves empty — which Save refuses.
+ *
+ * On an EDIT only a key the reader cleared counts: a required field a
+ * record has always lacked is not this save's to demand, or a rename
+ * could be refused for a field added last week. On a CREATE every
+ * required field counts, because the record is being made whole.
+ */
+export declare function crmCustomDraftMissingRequired(definitions: readonly Pick<ContactFieldDefinition, 'key' | 'required' | 'label'>[], stored: CrmCustomStored, draft: CrmCustomDraft, mode: 'create' | 'edit'): string[];

package/src/lib/model/crm-custom-draft.js

@@ -0,0 +1,67 @@
+/**
+ * @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 value a key shows: the draft's where touched, else the stored one. */ export function crmCustomDraftValue(stored, draft, key) {
+    return key in draft ? draft[key] : stored[key];
+}
+/**
+ * The keys whose draft differs from what is stored, with the value to
+ * write — `null` for a cleared one, the explicit "nothing" that keeps the
+ * key present for a `where` clause to find.
+ */ export function crmCustomDraftChanges(stored, draft) {
+    return Object.entries(draft).filter(([key, value])=>{
+        var _stored_key;
+        return (value != null ? value : null) !== ((_stored_key = stored[key]) != null ? _stored_key : null);
+    }).map(([key, value])=>[
+            key,
+            value != null ? value : null
+        ]);
+}
+/**
+ * The changes as an `update()` payload: one dotted path per key, so the
+ * map is merged rather than replaced. Empty when nothing changed, so a
+ * caller can spread it into a larger write unconditionally.
+ */ export function crmCustomDraftWrites(stored, draft) {
+    return Object.fromEntries(crmCustomDraftChanges(stored, draft).map(([key, value])=>[
+            `custom.${key}`,
+            value
+        ]));
+}
+/**
+ * The draft as the `custom` map a CREATE stores: every key with a value,
+ * `null` and absent both left out because a fresh document has nothing to
+ * clear. `undefined` when nothing would be stored, so a caller spreads
+ * `{ custom }` only when there is one.
+ */ export function crmCustomDraftDocument(draft) {
+    const stored = Object.fromEntries(Object.entries(draft).filter(([, value])=>value !== null && value !== undefined));
+    return Object.keys(stored).length ? stored : undefined;
+}
+/**
+ * The required definitions the draft leaves empty — which Save refuses.
+ *
+ * On an EDIT only a key the reader cleared counts: a required field a
+ * record has always lacked is not this save's to demand, or a rename
+ * could be refused for a field added last week. On a CREATE every
+ * required field counts, because the record is being made whole.
+ */ export function crmCustomDraftMissingRequired(definitions, stored, draft, mode) {
+    return definitions.filter((definition)=>{
+        if (!definition.required) return false;
+        const value = crmCustomDraftValue(stored, draft, definition.key);
+        const empty = value === null || value === undefined || value === '';
+        return mode === 'create' ? empty : definition.key in draft && empty;
+    }).map((definition)=>definition.label || definition.key);
+}
+
+//# sourceMappingURL=crm-custom-draft.js.map