@aglyn/plugins-crm 1.0.0-beta.220 → 1.0.0-beta.222

package/src/lib/transfer/common.js

@@ -0,0 +1,832 @@
+import { _ as _extends } from "@swc/helpers/_/_extends";
+/**
+ * @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 EVERY CRM TRANSFER RESOURCE SHARES (AGL-3527) — the server half.
+ *
+ * The CRM's records live under the organization, each stamped with the
+ * site that captured it and the `visibleTo` tokens that say who reads it.
+ * A transfer is opened from the CRM under a site, or at the organization
+ * level; the job engine hands every hook the workspace and that site
+ * (`ctx.hostId`), and this module turns the pair into what the CRM's own
+ * routes compute from a request: the org document, the site's consent
+ * group, the tokens a record must carry to be seen from the site, and the
+ * stamp a record created by the import carries.
+ *
+ * ## Refusals are the routes' refusals
+ *
+ * The transfer routes check `data.manage`, and the CRM's suite on the plan
+ * through each resource's `planGate` (AGL-3555). What is particular to the
+ * CRM — the suite again where a hook reads or writes, a site to file new
+ * records under — is checked here and thrown as the engine's own errors
+ * (`TransferPlanRefusedError` carrying `suite-gate.ts`'s answer, else
+ * `TransferEngineError`), so the wizard shows the sentence a CRM route
+ * would have answered.
+ *=========================================*/ import { checkCrmRecordsQuota, consentGroupForHost, CRM_COLLECTIONS, crmPicklistDefinition, crmReadTokens, crmScopeTokens, effectiveCrmPicklist, fieldDefinitionsForObject, isCrmPicklistId, newResourceScopeFields, normalizeCrmPicklist, ORG_SCOPE_TOKEN, readCrmCustomInput, visibleToTokens } from "@aglyn/aglyn/server";
+import { CONTACT_LIFECYCLE_STAGE_LABELS, CONTACT_LIFECYCLE_STAGES, CRM_FORECAST_CATEGORIES, CRM_FORECAST_CATEGORY_LABELS } from "@aglyn/aglyn/app-utils/crm";
+import { visibleToHost } from "@aglyn/aglyn/app-utils/scope-tokens";
+import { listOrgContainers } from "@aglyn/tenant-data-admin/server/org-containers";
+import { normalizeAddress } from "@aglyn/aglyn/foundation/definitions/contact.types";
+import { matchLookupKey, rankTransferLookupSuggestions, transferLookupKey } from "@aglyn/aglyn/data-transfer";
+import { crmRecordsQuotaForOrg, firebaseAdmin, listOrgMembers } from "@aglyn/tenant-data-admin";
+import { applyListQuery } from "@aglyn/tenant-data-admin/server/list-query";
+import { TransferEngineError, TransferPlanRefusedError } from "@aglyn/tenant-data-admin/server/transfer-jobs";
+import { FieldPath, FieldValue, Timestamp } from "firebase-admin/firestore";
+import { crmSuiteRefusal } from "../server/suite-gate.js";
+import { CRM_ADDRESS_PART_KEYS, CRM_ADDRESS_PARTS, CRM_CAMPAIGNS_PICKLIST, CRM_FORECAST_CATEGORY_PICKLIST, CRM_LIFECYCLE_STAGE_PICKLIST, crmCustomPicklistKey } from "./fields.js";
+/** The most values one Firestore `in` filter takes. */ export const IN_LIMIT = 30;
+/** Documents read per page of an export. */ export const EXPORT_PAGE = 500;
+/** Rows written at once by an apply. */ export const APPLY_CONCURRENCY = 8;
+/** A row is started only while this much of the chunk's budget is left. */ export const APPLY_ROW_BUDGET_MS = 3000;
+/** The org, the site and its tokens, for one hook call. */ export async function crmTransferEnv(ctx) {
+    var _snapshot_data;
+    const firestore = firebaseAdmin.app().firestore();
+    const orgRef = firestore.collection('orgs').doc(ctx.orgId);
+    const snapshot = await orgRef.get();
+    if (!snapshot.exists) throw new TransferEngineError('notFound', 404, 'No such workspace.');
+    const org = (_snapshot_data = snapshot.data()) != null ? _snapshot_data : {};
+    const group = ctx.hostId ? consentGroupForHost(org, ctx.hostId) : null;
+    return {
+        firestore,
+        orgRef,
+        org,
+        orgId: ctx.orgId,
+        hostId: ctx.hostId,
+        group,
+        siteTokens: group ? crmReadTokens(group) : null
+    };
+}
+/**
+ * Refuses an act the organization's plan does not include, in the CRM
+ * routes' own answer (`suite-gate.ts`). The transfer gate already asked
+ * (AGL-3555, each resource's `planGate`); a hook asks again where it reads
+ * or writes, so a caller that reaches it without the gate is refused alike.
+ */ export function requireCrmSuite(env, act) {
+    const refusal = crmSuiteRefusal(env.org, act);
+    if (refusal) throw new TransferPlanRefusedError(refusal);
+}
+/**
+ * Refuses reading the CRM's own records (not the people files) on a plan
+ * without the CRM: the export route's rule since AGL-2839.
+ */ export function requireCrmRecords(env, what) {
+    requireCrmSuite(env, `Exporting ${what}`);
+}
+/**
+ * The site new records are filed under, or the refusal: every CRM record is
+ * a fact some site met, so an import opened at the organization level must
+ * name one first.
+ */ export function requireSite(env, what) {
+    if (!env.hostId || !env.group) {
+        throw new TransferEngineError('invalid', 400, `Choose the site these ${what} are imported into.`);
+    }
+    return {
+        hostId: env.hostId,
+        group: env.group
+    };
+}
+/** The stamp a record the import creates carries: the site, and who reads it. */ export function creationScope(env, actorUid) {
+    const { hostId, group } = requireSite(env, 'records');
+    return _extends({
+        hostId,
+        visibleTo: crmScopeTokens(env.org, group)
+    }, actorUid ? {
+        createdByUid: actorUid
+    } : {}, {
+        createdAt: FieldValue.serverTimestamp(),
+        updatedAt: FieldValue.serverTimestamp()
+    });
+}
+/** Whether a stored record may be read in this transfer: the site's view, and a scoped reader's own tokens. */ export function visibleIn(env, visibleTo, scopeTokens) {
+    const tokens = Array.isArray(visibleTo) ? visibleTo : [];
+    if (env.siteTokens && !visibleToTokens(tokens, env.siteTokens)) return false;
+    if ((scopeTokens == null ? void 0 : scopeTokens.length) && !visibleToTokens(tokens, scopeTokens)) return false;
+    return true;
+}
+/*==========================================
+ * CUSTOM FIELDS AND PICKLISTS
+ *=========================================*/ /** The organization's live custom field definitions for one kind of record, as the site reads them. */ export async function crmCustomDefinitions(env, object) {
+    const snapshot = await env.orgRef.collection(CRM_COLLECTIONS.contactFields).limit(200).get();
+    return fieldDefinitionsForObject(snapshot.docs.map((doc)=>doc.data()), object).filter((field)=>Boolean(field.key) && !field.retiredAt && (!env.siteTokens || visibleToTokens(field.visibleTo, env.siteTokens)));
+}
+/** The lifecycle stages as a fixed list: matched onto, never added to. */ const LIFECYCLE_LIST = {
+    spec: {
+        restricted: true,
+        standardValues: CONTACT_LIFECYCLE_STAGES.map((id)=>({
+                id,
+                label: CONTACT_LIFECYCLE_STAGE_LABELS[id]
+            }))
+    },
+    set: {
+        values: CONTACT_LIFECYCLE_STAGES.map((id)=>({
+                id,
+                label: CONTACT_LIFECYCLE_STAGE_LABELS[id],
+                active: true
+            })),
+        defaultValueId: null
+    }
+};
+/** The forecast categories: a fixed set a forecast rolls up by, matched onto and never added to. */ const FORECAST_LIST = {
+    spec: {
+        restricted: true,
+        standardValues: CRM_FORECAST_CATEGORIES.map((id)=>({
+                id,
+                label: CRM_FORECAST_CATEGORY_LABELS[id]
+            }))
+    },
+    set: {
+        values: CRM_FORECAST_CATEGORIES.map((id)=>({
+                id,
+                label: CRM_FORECAST_CATEGORY_LABELS[id],
+                active: true
+            })),
+        defaultValueId: null
+    }
+};
+/**
+ * The lists behind the picklist fields a catalog names: the CRM's own
+ * (`crmPicklists`), the lifecycle stages, and each custom `select` field's
+ * options — a select is a fixed list the import maps onto.
+ */ export async function crmPicklistLists(env, picklistIds, customDefinitions) {
+    const lists = {};
+    const crmIds = picklistIds.filter(isCrmPicklistId);
+    const snapshots = crmIds.length ? await env.firestore.getAll(...crmIds.map((id)=>env.orgRef.collection(CRM_COLLECTIONS.picklists).doc(id))) : [];
+    crmIds.forEach((id, at)=>{
+        var _snapshots_at;
+        const definition = crmPicklistDefinition(id);
+        if (!definition) return;
+        lists[id] = {
+            spec: definition,
+            set: effectiveCrmPicklist(id, (_snapshots_at = snapshots[at]) == null ? void 0 : _snapshots_at.data())
+        };
+    });
+    for (const id of picklistIds){
+        var _definition_options;
+        if (id === CRM_LIFECYCLE_STAGE_PICKLIST) {
+            lists[id] = LIFECYCLE_LIST;
+            continue;
+        }
+        if (id === CRM_FORECAST_CATEGORY_PICKLIST) {
+            lists[id] = FORECAST_LIST;
+            continue;
+        }
+        if (id === CRM_CAMPAIGNS_PICKLIST) {
+            const { byName, names } = await campaignDirectory(env);
+            const live = [
+                ...new Set(byName.values())
+            ].map((campaign)=>{
+                var _names_get;
+                return {
+                    id: campaign,
+                    label: (_names_get = names.get(campaign)) != null ? _names_get : campaign
+                };
+            });
+            lists[id] = {
+                spec: {
+                    restricted: true,
+                    standardValues: live
+                },
+                set: {
+                    values: live.map((value)=>_extends({}, value, {
+                            active: true
+                        })),
+                    defaultValueId: null
+                }
+            };
+            continue;
+        }
+        const custom = crmCustomPicklistKey(id);
+        if (!custom) continue;
+        const definition = customDefinitions.find((entry)=>entry.key === custom.key);
+        if (!definition) continue;
+        const options = ((_definition_options = definition.options) != null ? _definition_options : []).map((option)=>String(option)).filter(Boolean);
+        lists[id] = {
+            spec: {
+                restricted: true,
+                standardValues: options.map((label, index)=>({
+                        id: `o${index}`,
+                        label
+                    }))
+            },
+            set: {
+                values: options.map((label, index)=>({
+                        id: `o${index}`,
+                        label,
+                        active: true
+                    })),
+                defaultValueId: null
+            }
+        };
+    }
+    return lists;
+}
+/**
+ * Adds the values the person chose to add to one of the CRM's picklists —
+ * in a transaction, so an admin editing the list at the same moment loses
+ * nothing — skipping an id or a label the list already holds, so a retried
+ * apply adds nothing twice. A value whose meaning only the platform sets
+ * (a lead Qualified by conversion) is never added. Fixed lists (the stages,
+ * a select's options) take nothing.
+ */ export async function addCrmPicklistValues(env, picklistId, values) {
+    if (!isCrmPicklistId(picklistId)) return;
+    const definition = crmPicklistDefinition(picklistId);
+    if (!definition) return;
+    const ref = env.orgRef.collection(CRM_COLLECTIONS.picklists).doc(picklistId);
+    await env.firestore.runTransaction(async (transaction)=>{
+        const snapshot = await transaction.get(ref);
+        const current = effectiveCrmPicklist(picklistId, snapshot.data());
+        const held = new Set(current.values.map((value)=>value.id));
+        const labels = new Set(current.values.map((value)=>value.label.toLowerCase()));
+        const added = values.filter((value)=>{
+            var _definition_reservedMeanings;
+            return !held.has(value.id) && !labels.has(value.label.toLowerCase()) && !(value.meaning && ((_definition_reservedMeanings = definition.reservedMeanings) == null ? void 0 : _definition_reservedMeanings.includes(value.meaning)));
+        });
+        if (!added.length) return;
+        const created = normalizeCrmPicklist(snapshot.data()) === null;
+        transaction.set(ref, _extends({
+            values: [
+                ...current.values,
+                ...added.map((value)=>_extends({}, value, {
+                        active: true
+                    }))
+            ],
+            defaultValueId: current.defaultValueId,
+            updatedAt: FieldValue.serverTimestamp()
+        }, created ? _extends({
+            hostId: env.hostId,
+            createdAt: FieldValue.serverTimestamp()
+        }, newResourceScopeFields([
+            ORG_SCOPE_TOKEN
+        ])) : {}), {
+            merge: true
+        });
+    });
+}
+/*==========================================
+ * CAMPAIGNS — named by a deal's and a lead's campaign columns
+ *=========================================*/ /** The most campaigns a file's names are resolved against — the lead import's own ceiling. */ const CAMPAIGN_CEILING = 200;
+/**
+ * The organization's live campaigns, by lowercased name and by id. A name
+ * two campaigns share resolves to the one placed on the transfer's site
+ * first, as the lead import resolved it.
+ */ export async function campaignDirectory(env) {
+    const byName = new Map();
+    const names = new Map();
+    const containers = await listOrgContainers(env.firestore, 'campaign', env.orgId, CAMPAIGN_CEILING).catch(()=>[]);
+    const live = containers.filter((container)=>container.live);
+    const placed = (visibleTo)=>env.hostId ? visibleToHost(visibleTo, env.hostId) : true;
+    for (const container of [
+        ...live.filter((entry)=>placed(entry.visibleTo)),
+        ...live.filter((entry)=>!placed(entry.visibleTo))
+    ]){
+        const key = container.name.toLowerCase();
+        if (key && !byName.has(key)) byName.set(key, container.id);
+    }
+    for (const container of containers)if (container.name) names.set(container.id, container.name);
+    return {
+        byName,
+        names
+    };
+}
+async function memberEntries(orgId) {
+    return (await listOrgMembers(orgId)).filter((member)=>member.$id && member.orgSuspended !== true).map((member)=>{
+        var _member_email, _member_displayName;
+        return {
+            id: String(member.$id),
+            email: String((_member_email = member.email) != null ? _member_email : '').trim().toLowerCase(),
+            name: String((_member_displayName = member.displayName) != null ? _member_displayName : '').trim()
+        };
+    });
+}
+/**
+ * The workspace's members as a lookup target: by id, email or display name,
+ * with names like an unresolved one offered — so a Salesforce report's
+ * "Contact Owner" (a full name) resolves as well as an address does.
+ */ export function crmMembersTarget() {
+    return {
+        matchKeys: [
+            {
+                fieldId: 'email',
+                normalizer: 'email'
+            },
+            {
+                fieldId: 'name',
+                normalizer: 'caseless'
+            }
+        ],
+        async lookup (ctx, requests) {
+            const members = await memberEntries(ctx.orgId);
+            const lookup = new Map();
+            const records = new Map();
+            for (const request of requests){
+                for (const value of request.values){
+                    const found = members.filter((member)=>request.fieldId === 'id' ? member.id === value : request.fieldId === 'email' ? member.email === value.toLowerCase() : member.name.toLowerCase() === value.toLowerCase());
+                    if (!found.length) continue;
+                    lookup.set(matchLookupKey(request.fieldId, value), found.map((member)=>member.id));
+                    for (const member of found)records.set(member.id, {
+                        name: member.name || member.email,
+                        email: member.email
+                    });
+                }
+            }
+            return {
+                lookup,
+                records
+            };
+        },
+        async suggest (ctx, request) {
+            const members = await memberEntries(ctx.orgId);
+            const candidates = members.flatMap((member)=>[
+                    {
+                        recordId: member.id,
+                        label: member.email
+                    },
+                    ...member.name ? [
+                        {
+                            recordId: member.id,
+                            label: member.name
+                        }
+                    ] : []
+                ]);
+            return Object.fromEntries(request.values.map((value)=>[
+                    value,
+                    rankTransferLookupSuggestions(value, candidates)
+                ]));
+        }
+    };
+}
+/** Member uid → email, for the owner columns of an export. */ export async function crmMemberEmails(orgId) {
+    return new Map((await memberEntries(orgId)).map((member)=>[
+            member.id,
+            member.email
+        ]));
+}
+const FILTER_OPS = new Set([
+    '<',
+    '<=',
+    '==',
+    '!=',
+    '>=',
+    '>',
+    'array-contains',
+    'in',
+    'not-in',
+    'array-contains-any'
+]);
+/** A filter value as the list sent it: a date travels as `{ $date }`. */ function filterValue(value) {
+    if (value && typeof value === 'object' && !Array.isArray(value) && typeof value.$date === 'string') {
+        return Timestamp.fromDate(new Date(value.$date));
+    }
+    return Array.isArray(value) ? value.map(filterValue) : value;
+}
+/** The list's filter, read from an untrusted body, or the refusal. */ export function readExportFilter(raw) {
+    if (!raw) return null;
+    const filters = Array.isArray(raw['filters']) ? raw['filters'] : null;
+    const orderBy = raw['orderBy'];
+    if (!filters || !orderBy || typeof orderBy.path !== 'string') {
+        throw new TransferEngineError('invalid', 400, 'The list’s filter could not be read; export everything or a selection.');
+    }
+    return {
+        filters: filters.map((entry)=>{
+            const filter = entry;
+            if (typeof filter.path !== 'string' || !FILTER_OPS.has(String(filter.op))) {
+                throw new TransferEngineError('invalid', 400, 'The list’s filter could not be read; export everything or a selection.');
+            }
+            return {
+                path: filter.path,
+                op: filter.op,
+                value: filterValue(filter.value)
+            };
+        }),
+        orderBy: {
+            path: orderBy.path,
+            direction: orderBy.direction === 'desc' ? 'desc' : 'asc'
+        }
+    };
+}
+/**
+ * The query an export reads: the list's filter, or every record the site
+ * (or the scoped reader) sees, in document order. A list filter already
+ * carries the reader's `visibleTo` clause when they are scoped, as the
+ * rules require of the list; a filter that lacks it gets one, when it has
+ * no other array clause, and is refused otherwise — so the count is exact
+ * and no record outside the reader's scope is ever read.
+ */ export function crmExportQuery(env, collection, options) {
+    var _options_scopeTokens;
+    const filter = readExportFilter(options == null ? void 0 : options.filter);
+    const tokens = (options == null ? void 0 : (_options_scopeTokens = options.scopeTokens) == null ? void 0 : _options_scopeTokens.length) ? [
+        ...options.scopeTokens
+    ] : env.siteTokens;
+    if (filter) {
+        const scoped = filter.filters.some((entry)=>entry.path === 'visibleTo');
+        const array = filter.filters.some((entry)=>entry.op === 'array-contains' || entry.op === 'array-contains-any');
+        if (tokens && !scoped) {
+            if (array) {
+                throw new TransferEngineError('invalid', 400, 'This filter cannot be exported from here; export everything or a selection.');
+            }
+            return applyListQuery(collection.where('visibleTo', 'array-contains-any', tokens), filter);
+        }
+        return applyListQuery(collection, filter);
+    }
+    const base = tokens ? collection.where('visibleTo', 'array-contains-any', tokens) : collection;
+    return base.orderBy(FieldPath.documentId());
+}
+/** How many records an export with these options reads. */ export async function countCrmExport(env, collection, options, visible) {
+    var _data_count;
+    if (options.ids) {
+        let count = 0;
+        for(let at = 0; at < options.ids.length; at += EXPORT_PAGE){
+            const refs = options.ids.slice(at, at + EXPORT_PAGE).filter((id)=>id && !id.includes('/')).map((id)=>collection.doc(id));
+            if (!refs.length) continue;
+            for (const snapshot of (await env.firestore.getAll(...refs))){
+                var _snapshot_data;
+                if (snapshot.exists && visible((_snapshot_data = snapshot.data()) != null ? _snapshot_data : {})) count += 1;
+            }
+        }
+        return count;
+    }
+    return Number((_data_count = (await crmExportQuery(env, collection, options).count().get()).data().count) != null ? _data_count : 0);
+}
+/**
+ * One page of an export: the selection by id (in the order given), or the
+ * query's next page after the cursor. Every document is checked against the
+ * site's and the reader's tokens before it becomes a row.
+ */ export async function readCrmExportPage(env, collection, cursor, options, visible, toRows) {
+    var _ref;
+    const size = Math.min((_ref = options == null ? void 0 : options.pageSize) != null ? _ref : EXPORT_PAGE, EXPORT_PAGE);
+    if (options == null ? void 0 : options.ids) {
+        const start = cursor ? Number(cursor) || 0 : 0;
+        const ids = options.ids.slice(start, start + size).filter((id)=>id && !id.includes('/'));
+        const snapshots = ids.length ? await env.firestore.getAll(...ids.map((id)=>collection.doc(id))) : [];
+        const docs = snapshots.filter((snapshot)=>{
+            var _snapshot_data;
+            return snapshot.exists && visible((_snapshot_data = snapshot.data()) != null ? _snapshot_data : {});
+        }).map((snapshot)=>{
+            var _snapshot_data;
+            return {
+                id: snapshot.id,
+                data: (_snapshot_data = snapshot.data()) != null ? _snapshot_data : {}
+            };
+        });
+        const next = start + size < options.ids.length ? String(start + size) : null;
+        return {
+            rows: await toRows(docs),
+            next
+        };
+    }
+    let query = crmExportQuery(env, collection, options).limit(size);
+    if (cursor) {
+        const after = await collection.doc(cursor).get();
+        if (after.exists) query = query.startAfter(after);
+    }
+    const snapshot = await query.get();
+    const docs = snapshot.docs.filter((doc)=>{
+        var _doc_data;
+        return visible((_doc_data = doc.data()) != null ? _doc_data : {});
+    }).map((doc)=>{
+        var _doc_data;
+        return {
+            id: doc.id,
+            data: (_doc_data = doc.data()) != null ? _doc_data : {}
+        };
+    });
+    const last = snapshot.docs[snapshot.docs.length - 1];
+    return {
+        rows: await toRows(docs),
+        next: snapshot.docs.length === size && last ? last.id : null
+    };
+}
+/**
+ * Records by each requested value of one stored field, thirty to an `in`
+ * query; `fold` turns a requested value into the stored one. The answer is
+ * filed under the value AS REQUESTED, which is the key the engine asks by.
+ */ export async function lookupByField(collection, request, storedField, fold, visible, into) {
+    const byStored = new Map();
+    for (const value of request.values){
+        var _byStored_get;
+        const stored = fold(value);
+        if (!stored) continue;
+        byStored.set(stored, [
+            ...(_byStored_get = byStored.get(stored)) != null ? _byStored_get : [],
+            value
+        ]);
+    }
+    const keys = [
+        ...byStored.keys()
+    ];
+    for(let at = 0; at < keys.length; at += IN_LIMIT){
+        const page = keys.slice(at, at + IN_LIMIT);
+        const snapshot = await collection.where(storedField, 'in', page).get();
+        for (const doc of snapshot.docs){
+            var _doc_data, _byStored_get1, _data_storedField;
+            const data = (_doc_data = doc.data()) != null ? _doc_data : {};
+            if (!visible(data)) continue;
+            into.docs.set(doc.id, data);
+            for (const value of (_byStored_get1 = byStored.get(String((_data_storedField = data[storedField]) != null ? _data_storedField : ''))) != null ? _byStored_get1 : []){
+                var _into_lookup_get;
+                const key = matchLookupKey(request.fieldId, value);
+                into.lookup.set(key, [
+                    ...new Set([
+                        ...(_into_lookup_get = into.lookup.get(key)) != null ? _into_lookup_get : [],
+                        doc.id
+                    ])
+                ]);
+            }
+        }
+    }
+}
+/** Records by id, the ones the transfer may read. */ export async function lookupById(env, collection, request, visible, into) {
+    const ids = request.values.filter((id)=>id && !id.includes('/'));
+    for(let at = 0; at < ids.length; at += EXPORT_PAGE){
+        const page = ids.slice(at, at + EXPORT_PAGE);
+        const snapshots = await env.firestore.getAll(...page.map((id)=>collection.doc(id)));
+        for (const snapshot of snapshots){
+            const data = snapshot.data();
+            if (!snapshot.exists || !data || !visible(data)) continue;
+            into.docs.set(snapshot.id, data);
+            into.lookup.set(matchLookupKey(request.fieldId, snapshot.id), [
+                snapshot.id
+            ]);
+        }
+    }
+}
+/** A lookup answer from the documents found, each read into values by `read`. */ export function lookupResult(found, read) {
+    const records = new Map();
+    for (const [id, data] of found.docs)records.set(id, read(id, data));
+    return {
+        lookup: found.lookup,
+        records
+    };
+}
+/*==========================================
+ * VALUES
+ *=========================================*/ /** Epoch milliseconds from a stored timestamp (a Firestore `Timestamp`, a `Date` or a number), or `null`. */ export function storedMs(value) {
+    var _value_toDate;
+    if (typeof value === 'number' && Number.isFinite(value)) return value;
+    if (value instanceof Date) return value.getTime();
+    const date = value == null ? void 0 : (_value_toDate = value.toDate) == null ? void 0 : _value_toDate.call(value);
+    return date ? date.getTime() : null;
+}
+/** An instant as the export writes it (ISO), or `null`. */ export function isoOf(value) {
+    const ms = storedMs(value);
+    return ms === null ? null : new Date(ms).toISOString();
+}
+/** A postal address as the six values `<prefix>Street` … `<prefix>Country`. */ export function addressValues(prefix, address) {
+    const stored = address && typeof address === 'object' ? address : {};
+    return Object.fromEntries(CRM_ADDRESS_PARTS.map((part)=>{
+        const value = stored[CRM_ADDRESS_PART_KEYS[part]];
+        return [
+            `${prefix}${part}`,
+            typeof value === 'string' && value ? value : null
+        ];
+    }));
+}
+/**
+ * The address a row's parts make, over the one the record holds: a part
+ * the row names (blank clears it) replaces the stored part. `undefined`
+ * when the row names no part; `null` when nothing of the address is left.
+ */ export function addressFromValues(prefix, values, stored) {
+    var _base_country, _base_line1, _base_line2, _base_city, _base_state, _base_postalCode;
+    const named = CRM_ADDRESS_PARTS.filter((part)=>`${prefix}${part}` in values);
+    if (!named.length) return undefined;
+    const base = stored && typeof stored === 'object' ? _extends({}, stored) : {};
+    for (const part of named){
+        const value = values[`${prefix}${part}`];
+        base[CRM_ADDRESS_PART_KEYS[part]] = typeof value === 'string' ? value.trim() : '';
+    }
+    const country = String((_base_country = base['country']) != null ? _base_country : '').trim();
+    return normalizeAddress({
+        line1: String((_base_line1 = base['line1']) != null ? _base_line1 : ''),
+        line2: String((_base_line2 = base['line2']) != null ? _base_line2 : ''),
+        city: String((_base_city = base['city']) != null ? _base_city : ''),
+        state: String((_base_state = base['state']) != null ? _base_state : ''),
+        postalCode: String((_base_postalCode = base['postalCode']) != null ? _base_postalCode : ''),
+        country: country.length === 2 ? country.toUpperCase() : country
+    });
+}
+/** A planned row's values: each changed field's new value. */ export function plannedValues(row) {
+    return Object.fromEntries(row.diff.map((change)=>[
+            change.fieldId,
+            change.after
+        ]));
+}
+/** Only `keys` of `values`, each present (a missing one as `null`). */ export function pickValues(values, keys) {
+    return Object.fromEntries([
+        ...keys
+    ].map((key)=>{
+        var _values_key;
+        return [
+            key,
+            (_values_key = values[key]) != null ? _values_key : null
+        ];
+    }));
+}
+/** A text value, trimmed, or `''`. */ export function textOf(value) {
+    return value === null || value === undefined ? '' : String(value).trim();
+}
+/** A lookup cell's display key, for caching records a chunk creates by name. */ export function nameKey(value) {
+    return transferLookupKey(value);
+}
+/*------------------------------------------
+ * Custom values
+ *-----------------------------------------*/ /** The custom key a `custom:<key>` field id names, or `null`. */ export function customKeyOf(fieldId) {
+    return fieldId.startsWith('custom:') ? fieldId.slice('custom:'.length) : null;
+}
+/**
+ * A stored custom value as the file reads it: a date (stored as epoch
+ * milliseconds) as its day, `YYYY-MM-DD`; anything else as stored.
+ */ export function customTransferValue(definition, value) {
+    if (value === null || value === undefined) return null;
+    if ((definition == null ? void 0 : definition.type) === 'date') {
+        const ms = storedMs(value);
+        return ms === null ? null : new Date(ms).toISOString().slice(0, 10);
+    }
+    return value;
+}
+/** Every custom field a record holds, as `custom:<key>` values. */ export function customTransferValues(definitions, stored) {
+    const custom = stored && typeof stored === 'object' ? stored : {};
+    return Object.fromEntries(definitions.map((definition)=>[
+            `custom:${definition.key}`,
+            customTransferValue(definition, custom[definition.key])
+        ]));
+}
+/**
+ * The custom values a row writes, judged by the CRM's own reader
+ * (`readCrmCustomInput`): a blank clears (`null`), a date is read from its
+ * day. Answers the values, or the first refusal.
+ */ export function customWriteValues(values, definitions, object) {
+    var _Object_values_;
+    const raw = {};
+    for (const [fieldId, value] of Object.entries(values)){
+        const key = customKeyOf(fieldId);
+        if (key) raw[key] = value === undefined || value === '' ? null : value;
+    }
+    if (!Object.keys(raw).length) return {
+        values: {}
+    };
+    const judged = readCrmCustomInput(raw, definitions, object);
+    if ('errors' in judged) return {
+        error: (_Object_values_ = Object.values(judged.errors)[0]) != null ? _Object_values_ : 'A custom value could not be saved.'
+    };
+    return {
+        values: judged.values
+    };
+}
+/*==========================================
+ * PLANS — values a plugin rule holds back
+ *=========================================*/ /**
+ * Removes the changes `decide` refuses from a plan, as a locked rule's: the
+ * field is listed in the row's `heldBack`, the row gains a `lockedRule`
+ * warning (acknowledged before Apply), and an update left with nothing to
+ * write becomes `unchanged`. For a rule no field policy can say — a stage
+ * that only moves forward, a flag a file may set and never clear.
+ */ export function holdBackChanges(plan, decide) {
+    const warnings = new Map(plan.warnings.map((warning)=>[
+            warning.class,
+            _extends({}, warning)
+        ]));
+    const rows = plan.rows.map((row)=>{
+        var _warnings_get;
+        if (row.verdict !== 'update' && row.verdict !== 'create') return row;
+        const held = [];
+        const diff = row.diff.filter((change)=>{
+            const reason = decide(row, change);
+            if (!reason) return true;
+            held.push({
+                fieldId: change.fieldId,
+                reason,
+                value: change.after
+            });
+            return false;
+        });
+        if (!held.length) return row;
+        const warning = (_warnings_get = warnings.get('lockedRule')) != null ? _warnings_get : {
+            class: 'lockedRule',
+            count: 0,
+            rows: 0,
+            fieldIds: [],
+            samples: [],
+            requiresAcknowledgement: true
+        };
+        warning.rows += 1;
+        for (const entry of held){
+            warning.count += 1;
+            if (!warning.fieldIds.includes(entry.fieldId)) warning.fieldIds = [
+                ...warning.fieldIds,
+                entry.fieldId
+            ];
+            if (warning.samples.length < 5) {
+                warning.samples = [
+                    ...warning.samples,
+                    {
+                        row: row.index,
+                        fieldId: entry.fieldId,
+                        value: textOf(entry.value),
+                        detail: entry.reason
+                    }
+                ];
+            }
+        }
+        warnings.set('lockedRule', warning);
+        const verdict = row.verdict === 'update' && !diff.length ? 'unchanged' : row.verdict;
+        return _extends({}, row, {
+            verdict,
+            diff,
+            heldBack: [
+                ...new Set([
+                    ...row.heldBack,
+                    ...held.map((entry)=>entry.fieldId)
+                ])
+            ],
+            warnings: [
+                ...new Set([
+                    ...row.warnings,
+                    'lockedRule'
+                ])
+            ]
+        });
+    });
+    const summary = {
+        create: 0,
+        update: 0,
+        unchanged: 0,
+        skip: 0,
+        fail: 0,
+        total: rows.length
+    };
+    for (const row of rows)summary[row.verdict] += 1;
+    const list = plan.warnings.map((warning)=>{
+        var _warnings_get;
+        return (_warnings_get = warnings.get(warning.class)) != null ? _warnings_get : warning;
+    });
+    const locked = warnings.get('lockedRule');
+    if (locked && !plan.warnings.some((warning)=>warning.class === 'lockedRule')) list.push(locked);
+    return {
+        rows,
+        summary,
+        warnings: list,
+        acknowledgementsRequired: [
+            ...new Set([
+                ...plan.acknowledgementsRequired,
+                ...locked ? [
+                    'lockedRule'
+                ] : []
+            ])
+        ]
+    };
+}
+/*==========================================
+ * WRITING
+ *=========================================*/ /**
+ * `write` over `items`, {@link APPLY_CONCURRENCY} at a time, starting an
+ * item only while the chunk's budget lasts — the engine resumes the chunk
+ * at the next call for whatever is left.
+ */ export async function eachWithinBudget(items, timeLeftMs, write) {
+    let next = 0;
+    const worker = async ()=>{
+        while(next < items.length){
+            if (timeLeftMs() < APPLY_ROW_BUDGET_MS) return;
+            const item = items[next];
+            next += 1;
+            await write(item);
+        }
+    };
+    await Promise.all(Array.from({
+        length: Math.min(APPLY_CONCURRENCY, items.length)
+    }, worker));
+}
+/**
+ * The CRM records band for the records one apply call creates beside the
+ * rows' own (a company a contact's company column names): counted once,
+ * then each create admitted from that tally. A plan with an overage rate
+ * always admits.
+ */ export function crmRecordsRoom(env) {
+    let counted = null;
+    let created = 0;
+    return async ()=>{
+        counted != null ? counted : counted = crmRecordsQuotaForOrg(env.org, env.orgRef);
+        const { crmRecordsCount } = await counted;
+        if (!checkCrmRecordsQuota(env.org, crmRecordsCount + created).allowed) return false;
+        created += 1;
+        return true;
+    };
+}
+/** A thrown write as the sentence a row's result carries. */ export function failureMessage(error) {
+    if (error instanceof TransferEngineError) return error.message;
+    return 'The record could not be saved.';
+}
+export { TransferEngineError };
+
+//# sourceMappingURL=common.js.map