@aglyn/aglyn 1.0.0-beta.143

package/src/lib/app-utils/crm.d.ts

@@ -0,0 +1,1546 @@
+/**
+ * @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.
+ */
+/**
+ * Contacts CRM v2 (AGL-2595): the records that sit BESIDE a contact.
+ *
+ * v1 is one collection — `contacts` — and everything a holder knows about a
+ * person lives in that holder's facet on the shared row. That shape is right
+ * for the person and wrong for everything a sales team keeps AROUND the
+ * person: a company is known by several contacts, a deal moves through
+ * stages on its own clock, a task is due whether or not anybody opens the
+ * contact it hangs off, and an activity log grows past anything a facet
+ * should carry. So each of those is a collection of its own under
+ * `orgs/{orgId}/`, pointing back at the contact by id.
+ *
+ * ## One scope model, not a second one
+ *
+ * Every collection here carries `visibleTo`, the same array `contacts`
+ * carries, and is stamped the same way — {@link crmScopeTokens} is the
+ * contact create path's expression, exported so that no creator computes its
+ * own. The rules gate all six on the contacts predicate (`canReadScopedPeople`,
+ * `data.manage`), because a deal or a call log is a fact about a person and
+ * discloses exactly what the contact row would.
+ *
+ * What these collections do NOT have is the facet map. A contact is shared
+ * across holders because one human is one row; a company, deal or task is
+ * one holder's record from the moment it is created, so `visibleTo` alone
+ * says who may see it and there is nothing to split per holder.
+ *
+ * Pure data module: types, constants and the small helpers every surface
+ * would otherwise write for itself. No Firestore, no React.
+ */
+import type { AglynPostalAddress, OrgCrmAssignmentRule } from '../foundation';
+import { type ConsentGroup } from './consent-groups';
+import { type ContactLifecycleStage, type CrmActivityKind, type CrmTaskKind } from './crm-kinds';
+import { type ContactInteraction, type ContactSegment, type ContactSource } from './contacts';
+import { type ScopeToken } from './scope-tokens';
+export * from './crm-kinds';
+/**
+ * The CRM's collections, every one under `orgs/{orgId}/`.
+ *
+ * Named here rather than spelled at each call site because the rules, the
+ * indexes and the console must agree on the string, and the three prefixed
+ * ones are prefixed on purpose: `tasks`, `activities` and `views` are words
+ * the org document will want for something else one day, and a collection
+ * name is persisted in every document path that uses it.
+ */
+export declare const CRM_COLLECTIONS: {
+    readonly companies: "companies";
+    readonly pipelines: "pipelines";
+    readonly deals: "deals";
+    readonly tasks: "crmTasks";
+    readonly activities: "crmActivities";
+    readonly contactFields: "contactFields";
+    readonly views: "crmViews";
+    readonly emailTemplates: "crmEmailTemplates";
+};
+export type CrmCollection = (typeof CRM_COLLECTIONS)[keyof typeof CRM_COLLECTIONS];
+/**
+ * The three collections the CRM RECORDS band counts (AGL-2611), in the order
+ * the billing caption lists them. `contacts` is not in `CRM_COLLECTIONS`
+ * because it predates the hub and is addressed through `orgDataCollection`,
+ * so the band's own list has to name all three itself. Tasks, pipelines,
+ * activities and field definitions are deliberately absent: a band that
+ * counted what a rep does every hour would price the team's effort, not the
+ * audience it holds.
+ */
+export declare const CRM_RECORD_COLLECTIONS: readonly ["contacts", "companies", "deals"];
+/**
+ * What a create says when the records band refused it, on every surface —
+ * the contacts list's alert, the company and deal drawers, the plugin's
+ * create routes and the lead conversion (AGL-2596, widened in AGL-2611).
+ *
+ * One sentence in one place, because a reader who is refused in the drawer
+ * and then reads the list must be told the same thing, and the remedy is the
+ * same wherever the refusal lands: a band refuses only on a plan that puts
+ * no overage rate past it, so "upgrade" is the whole of the answer.
+ */
+export declare const CRM_RECORDS_BAND_FULL_MESSAGE: string;
+/**
+ * The most logged activities ONE record may carry (AGL-2611) — a contact's,
+ * a company's or a deal's own log, counted on the link the activity was
+ * filed under.
+ *
+ * A platform ceiling and not a plan dimension, in the family of
+ * `WEBHOOK_MAX_PER_HOST` and `NON_PAGE_SCREEN_MAX_PER_HOST`: activities are
+ * not in the records band because they are bounded by human effort, and
+ * this is the bound. Five thousand is a call a day for fourteen years on one
+ * person, so nobody working a real relationship reaches it — what does is
+ * an automation logging on every event, or an import replaying a history,
+ * and either of those past this line is a document cost with no reader.
+ *
+ * Enforced where an activity is written: the console's log dialog, the
+ * `logCrmActivity` automation step and `POST /v1/activities`, each with one
+ * aggregate read on the record's link before the create. The timeline reads
+ * a hundred at a time and is untouched by the number.
+ */
+export declare const CRM_ACTIVITIES_PER_RECORD_CEILING = 5000;
+/**
+ * What every writer says when a record's log is full — the console's log
+ * dialog, the automation step's run history and `POST /v1/activities`.
+ */
+export declare const CRM_ACTIVITY_LOG_FULL_MESSAGE: string;
+/** The record an activity is filed under: its links, of which one leads. */
+export interface CrmActivityLink {
+    contactId?: string | null;
+    companyId?: string | null;
+    dealId?: string | null;
+    /**
+     * `hosts/{hostId}/leads/{leadId}` — a person not yet converted (AGL-2615).
+     * A lead is host-scoped by path and carries no `visibleTo` of its own, so
+     * an activity filed under one is stamped with the site's scope like any
+     * other record created from that site.
+     */
+    leadId?: string | null;
+}
+/**
+ * The field the per-record activity ceiling is counted on, or `null` for an
+ * activity that names no record at all.
+ *
+ * The contact leads, then the company, then the deal: an activity logged
+ * from a contact's page carries the company beside it (the automation step
+ * copies the facet's `companyId` onto every record it creates), and a
+ * ceiling counted on the company would let one busy account exhaust every
+ * contact filed under it. The record whose PAGE the log is read on is the
+ * one whose log has the limit. Shared by the client dialog and the two
+ * server writers so they count the same thing.
+ */
+export declare function crmActivityCeilingLink(link: CrmActivityLink): {
+    field: 'contactId' | 'companyId' | 'dealId' | 'leadId';
+    id: string;
+} | null;
+/**
+ * Whether ONE MORE activity fits under `CRM_ACTIVITIES_PER_RECORD_CEILING`.
+ * Both halves of the boundary live here so no writer re-derives `>=`.
+ */
+export declare function crmActivityLogHasRoom(existing: number): boolean;
+/** How a lifecycle stage reads on screen — typed so a stage cannot ship unlabeled. */
+export declare const CONTACT_LIFECYCLE_STAGE_LABELS: Record<ContactLifecycleStage, string>;
+/**
+ * The stage a person is in once a capture has happened that implies at least
+ * `floor` (AGL-2612).
+ *
+ * The one ordering rule every capture door shares: a door names the EARLIEST
+ * stage that describes what just happened — a form submission is a lead, a
+ * newsletter opt-in is a subscriber, a purchase is a customer — and the
+ * result is that stage for a person who had none or an earlier one, and the
+ * stage they already had otherwise. "Never downgrades" is the whole contract:
+ * a customer who fills in a contact form is still a customer, and `other` —
+ * the deliberate stage a business picked for a funnel step none of the names
+ * fit — sits after `customer` in the list precisely so no capture can
+ * overwrite it. A stored value that is not a stage at all reads as absent,
+ * because a capture door is not the place to preserve a typo.
+ *
+ * With no floor the answer is the current stage as it stands, or `undefined`
+ * for one that is absent or unusable — so a writer can apply this
+ * unconditionally and write only what comes back.
+ */
+export declare function advanceContactLifecycleStage(current: unknown, floor: ContactLifecycleStage | undefined): ContactLifecycleStage | undefined;
+/**
+ * The stage a person is in once they have BOUGHT something (AGL-2596).
+ *
+ * `customer` when they had no stage or an earlier one; whatever they already
+ * had otherwise — {@link advanceContactLifecycleStage} with `customer` as the
+ * floor, kept under its own name because "after a purchase" is the question
+ * the order paths and the reports ask.
+ */
+export declare function contactLifecycleStageAfterPurchase(current: unknown): ContactLifecycleStage;
+/**
+ * What a custom contact field may hold.
+ *
+ * Scalars only. A field is something a merchant filters and exports on, and
+ * a nested value is neither; `null` is the explicit "cleared" that a form
+ * writes so the key stays present for a `where` clause to find.
+ */
+export type ContactCustomValue = string | number | boolean | null;
+/**
+ * The same scalar, under the name the other objects use (AGL-2661).
+ *
+ * A company's and a deal's `custom` map hold exactly what a contact's
+ * does — one definition, one coercion rule, one stored shape — so the
+ * value type is one type with two names: the contact name it was born
+ * with, and this one for code that is not about contacts.
+ */
+export type CrmCustomValue = ContactCustomValue;
+/**
+ * The fields every CRM document carries.
+ *
+ * `visibleTo` is the scope both enforcement layers evaluate — see
+ * `scope-tokens.ts` for why an absent one is seen by NOBODY. `hostId` is
+ * provenance: the site whose console created the record, never rewritten,
+ * so a report can say where a deal came from after the scope has widened.
+ * The timestamps are `unknown` because a client write carries a `Date` and a
+ * read hands back a Firestore `Timestamp`; callers narrow at the edge.
+ */
+export interface CrmScoped {
+    visibleTo: string[];
+    /** The site that created it. */
+    hostId: string;
+    createdAt?: unknown;
+    updatedAt?: unknown;
+}
+/** `orgs/{orgId}/companies/{companyId}`. */
+export interface CrmCompany extends CrmScoped {
+    name: string;
+    /** `nameSearchFields` twins, for the prefix search the list runs. */
+    nameLower?: string;
+    nameTokens?: string[];
+    /** Lowercase hostname, no protocol — see {@link normalizeCompanyDomain}. */
+    domain?: string;
+    website?: string;
+    /** E.164 — `normalizePhone` before writing. */
+    phone?: string;
+    address?: AglynPostalAddress | null;
+    industry?: string;
+    ownerUid?: string;
+    notes?: string;
+    /**
+     * Lowercased, deduplicated, capped at twenty — the same shape a contact's
+     * tags take, so a bulk "Add tag" over companies and one over contacts
+     * write the same kind of value (AGL-2621).
+     */
+    tags?: string[];
+    createdByUid?: string;
+    /**
+     * How many contacts name this company in their {@link CONTACT_COMPANY_IDS_FIELD}
+     * mirror — see {@link COMPANY_CONTACTS_COUNT_FIELD}. Absent on a company
+     * nobody has linked since the counter existed, which reads as zero.
+     */
+    contactsCount?: number;
+    /**
+     * Custom field values, keyed by the key of a definition whose `object`
+     * is `company` — see {@link fieldDefinitionObject} (AGL-2661).
+     */
+    custom?: Record<string, CrmCustomValue>;
+    /**
+     * When the earliest OPEN task filed against this company is due, epoch
+     * ms, or `null` when none is — see {@link CrmDeal.nextTaskAtMs}.
+     */
+    nextTaskAtMs?: number | null;
+    /** Org-library files attached to the company (AGL-2662) — see {@link CRM_MEDIA_IDS_MAX}. */
+    mediaIds?: string[];
+}
+/** One step of a pipeline. */
+export interface CrmDealStage {
+    id: string;
+    name: string;
+    /** Position in the pipeline, ascending. */
+    order: number;
+    /** Chance of closing from here, 0–100 — what a weighted forecast multiplies by. */
+    probability: number;
+    /**
+     * Whether landing in this stage closes the deal. A pipeline has exactly one
+     * `won` and one `lost` stage in the default set; `open` is everything in
+     * between.
+     */
+    kind: 'open' | 'won' | 'lost';
+}
+/** `orgs/{orgId}/pipelines/{pipelineId}`. */
+export interface CrmPipeline extends CrmScoped {
+    name: string;
+    stages: CrmDealStage[];
+    /** The pipeline a new deal lands in when nobody picks one. */
+    isDefault?: boolean;
+    /**
+     * When the pipeline was retired, epoch ms. An archived pipeline takes no
+     * new deal and is offered by no picker, but it is never deleted: the deals
+     * it closed still name it, and a report that could not resolve their
+     * stages would forecast them as orphans. Absent or `null` while active.
+     */
+    archivedAt?: number | null;
+}
+/** Whether a pipeline has been retired — see {@link CrmPipeline.archivedAt}. */
+export declare function isPipelineArchived(pipeline: Pick<CrmPipeline, 'archivedAt'> | null | undefined): boolean;
+/**
+ * The stages a fresh pipeline starts with.
+ *
+ * Readonly on purpose: a pipeline document stores its own COPY (`[...]`), so
+ * a merchant editing their stages must not be editing the module's default,
+ * and a second pipeline seeded later must start from the original set.
+ */
+export declare const DEFAULT_DEAL_STAGES: readonly CrmDealStage[];
+export type CrmDealStatus = 'open' | 'won' | 'lost';
+/**
+ * One product on a deal — what is being sold, how many, at what.
+ *
+ * `productId` names a catalog product when the line came from one; a line
+ * typed by hand has none. The name is copied rather than joined, the way a
+ * deal copies its contact's name: a catalog product can be renamed or
+ * deleted after the deal was priced, and the deal has to keep saying what
+ * it was for. `currency` is the deal's — every line on a deal is in one
+ * currency, because their sum is the deal's amount and a sum across
+ * currencies is a number with no unit.
+ */
+export interface CrmDealLineItem {
+    productId?: string;
+    name: string;
+    /** A whole number of units, one or more. */
+    quantity: number;
+    /** Per unit, in the currency's minor unit, zero or more. */
+    unitAmountCents: number;
+    /** Lowercase ISO 4217. */
+    currency: string;
+}
+/** The most lines one deal carries — a quote, not a catalog. */
+export declare const DEAL_LINE_ITEMS_MAX = 50;
+export declare const DEAL_LINE_ITEM_NAME_MAX = 120;
+/** Units per line; past this the number is a data-entry slip. */
+export declare const DEAL_LINE_ITEM_QUANTITY_MAX = 1000000;
+/**
+ * `orgs/{orgId}/deals/{dealId}`.
+ *
+ * A WON DEAL MAKES ITS CONTACT A CUSTOMER (AGL-2641). A win is the same
+ * fact as a purchase — the business has decided this person bought — and an
+ * order already floors a contact's lifecycle stage at `customer` on
+ * capture. So every writer of `status` — the console's stage route at both
+ * levels and the REST resource — applies the same floor to the contact
+ * `contactId` names on the transition into `won`, in the facet of the site
+ * the deal was made on (`hostId`), with `advanceContactLifecycleStage`'s
+ * rule: an empty stage is filled, an earlier one advanced, and nobody is
+ * ever moved back. Behind no setting, because a won deal is a customer by
+ * definition; an automation on `dealWon` is for what happens NEXT.
+ */
+export interface CrmDeal extends CrmScoped {
+    title: string;
+    titleLower?: string;
+    pipelineId: string;
+    stageId: string;
+    /**
+     * Denormalized from the stage's `kind` at every stage move, because it is
+     * what the list filters and the indexes sort on — a query cannot join the
+     * pipeline to ask what the stage means.
+     */
+    status: CrmDealStatus;
+    /**
+     * What the deal is worth. Typed by hand on a deal with no line items;
+     * on a deal WITH them it is their sum, stored beside them by every
+     * writer (`lineItemsTotalCents`), because the board, the reports and the
+     * REST list all read this one field and none of them can afford to add
+     * up fifty lines per row. A deal with line items refuses a typed amount.
+     */
+    amountCents?: number;
+    /** Lowercase ISO 4217; `'usd'` when absent. */
+    currency?: string;
+    /** The products behind the amount — see {@link CrmDealLineItem}. */
+    lineItems?: CrmDealLineItem[];
+    expectedCloseAtMs?: number | null;
+    closedAtMs?: number | null;
+    /** When the deal last moved — what "stuck in stage" reports read. */
+    stageChangedAtMs?: number;
+    ownerUid?: string;
+    contactId?: string;
+    companyId?: string;
+    lostReason?: string;
+    notes?: string;
+    createdByUid?: string;
+    /**
+     * Custom field values, keyed by the key of a definition whose `object`
+     * is `deal` — see {@link fieldDefinitionObject} (AGL-2661).
+     */
+    custom?: Record<string, CrmCustomValue>;
+    /**
+     * When the earliest OPEN task filed against this deal is due, epoch ms,
+     * or `null` when no open task names it (AGL-2661).
+     *
+     * DENORMALIZED from `crmTasks`, because the question "which deals have
+     * nothing scheduled" is asked of a LIST — a column, a filter, a report
+     * tile — and a list cannot afford a task query per row. Every server
+     * writer of a task recomputes it for the records the task names
+     * (`recomputeCrmNextTaskAt` in the admin library), and a client-direct
+     * task write asks the console route to do the same; the Fields section
+     * offers a one-off recompute for the records written before the field
+     * existed. Absent on such a record, which every reader treats as `null`.
+     */
+    nextTaskAtMs?: number | null;
+    /** Org-library files attached to the deal (AGL-2662) — see {@link CRM_MEDIA_IDS_MAX}. */
+    mediaIds?: string[];
+}
+export declare const CRM_TASK_KIND_LABELS: Record<CrmTaskKind, string>;
+export type CrmTaskPriority = 'low' | 'normal' | 'high';
+export type CrmTaskStatus = 'open' | 'done';
+/**
+ * `orgs/{orgId}/crmTasks/{taskId}`.
+ *
+ * The one CRM record that may belong to NO site (AGL-2637): a task filed
+ * from the organization's own hub carries `hostId: null` and the org scope
+ * token alone, because a to-do owed by the organization — renew the
+ * insurance, chase the agency's own invoice — is not captured by any brand.
+ * Every other record is a fact about a person some site met, so
+ * `CrmScoped` keeps its site required.
+ */
+export interface CrmTask extends Omit<CrmScoped, 'hostId'> {
+    /** The site that created it, or `null` for the organization's own task. */
+    hostId: string | null;
+    title: string;
+    notes?: string;
+    kind: CrmTaskKind;
+    priority: CrmTaskPriority;
+    status: CrmTaskStatus;
+    dueAtMs?: number | null;
+    completedAtMs?: number | null;
+    /**
+     * Who ticked it off, which is not always the assignee: a manager closing
+     * out a departed teammate's list completes tasks that were never theirs.
+     * Stamped by the `crm/task-complete` route beside `completedAtMs`.
+     */
+    completedByUid?: string;
+    assigneeUid?: string;
+    /**
+     * The person who made it, or `''` when no person did.
+     *
+     * An automation has no uid, and inventing one — the action's id, a
+     * sentinel — would put a value into a field every reader resolves as a
+     * member. The empty string says "nobody", and {@link sourceActionId}
+     * beside it says what.
+     */
+    createdByUid: string;
+    /** The automation that created it (AGL-2605), when a person did not. */
+    sourceActionId?: string;
+    /**
+     * The plugin that filed it on the record-timeline seam (AGL-2981) — a
+     * sequence's call step, a reply to answer — when no person did.
+     */
+    sourcePluginId?: string;
+    contactId?: string;
+    companyId?: string;
+    dealId?: string;
+    /**
+     * When the assignee is reminded (AGL-2659): the due time unless a person
+     * moved it, `null` for no reminder. The hourly `/api/crm/task-reminders`
+     * runner reads every open task whose reminder has come due, so a task
+     * that should never remind carries `null` rather than no field — a
+     * missing key and a null both fall outside the range, but the null says
+     * it was decided.
+     */
+    remindAtMs?: number | null;
+    /**
+     * When the runner handled the reminder — sent it, or found nobody to
+     * send it to. Absent while the reminder is still owed, which is how a
+     * rerun over the same hour sends nothing twice; cleared again when the
+     * reminder moves, because a moved reminder is a new one.
+     */
+    reminderSentAtMs?: number;
+}
+/** How an activity kind reads on screen — typed so a kind cannot ship unlabeled. */
+export declare const CRM_ACTIVITY_KIND_LABELS: Record<CrmActivityKind, string>;
+/**
+ * Whether a kind takes an outcome and a duration.
+ *
+ * A call and a meeting are conversations: they end somewhere ("left a
+ * voicemail", "agreed to a trial") and they take a measurable amount of
+ * time, and both are what a manager reading the log wants to know. An email
+ * has neither in any useful sense, a note is not an event at all, and
+ * `other` is unknowable — so the dialog hides the two fields for those
+ * rather than offering boxes that mean nothing.
+ */
+export declare function activityKindHasOutcome(kind: CrmActivityKind): boolean;
+/**
+ * Where a one-to-one email got to (AGL-2615), in the order it normally
+ * happens — the vocabulary the delivery webhook maps its events onto an
+ * `email` activity in, and the chip the timeline shows beside the entry.
+ *
+ * The first four are a progression: a message is sent, then delivered, then
+ * opened, then clicked, and a later state implies the earlier ones. The last
+ * two are terminal failures. A message the mailbox provider bounced or that
+ * the recipient reported is never "opened" in any sense the timeline should
+ * report, whatever a tracking pixel says afterwards.
+ */
+export declare const CRM_EMAIL_DELIVERY_STATES: readonly ["sent", "delivered", "opened", "clicked", "bounced", "complained"];
+export type CrmEmailDeliveryState = (typeof CRM_EMAIL_DELIVERY_STATES)[number];
+/** How a delivery state reads on the chip — typed so a state cannot ship unlabeled. */
+export declare const CRM_EMAIL_DELIVERY_STATE_LABELS: Record<CrmEmailDeliveryState, string>;
+export declare function isCrmEmailDeliveryState(value: unknown): value is CrmEmailDeliveryState;
+/** The two states that mean the message did not land. */
+export declare function isCrmEmailDeliveryFailure(state: unknown): boolean;
+/**
+ * The state an activity holds after one more delivery event, from the state
+ * it held before.
+ *
+ * MONOTONIC. Provider events arrive at least once and in no promised order
+ * — an `opened` can reach the webhook before the `delivered` it implies, and
+ * a replay can hand back yesterday's `delivered` after today's `clicked` —
+ * so the row keeps whichever state is further along, and an event that says
+ * less than the row already knows changes nothing. A stored value the
+ * vocabulary does not name reads as nothing, so the incoming event stands.
+ */
+export declare function nextCrmEmailDeliveryState(current: unknown, incoming: CrmEmailDeliveryState): CrmEmailDeliveryState;
+/** The most a one-to-one email's subject may hold. */
+export declare const CRM_EMAIL_SUBJECT_MAX = 200;
+/** The most a one-to-one email's body may hold — a letter, not a document. */
+export declare const CRM_EMAIL_BODY_MAX = 10000;
+/**
+ * The `context` a one-to-one email is sent under, which `sendEmail` stamps
+ * as a provider tag on the message and the delivery log files it by.
+ */
+export declare const CRM_EMAIL_CONTEXT = "crm";
+/** The provider tag naming the activity row a one-to-one email belongs to. */
+export declare const CRM_EMAIL_ACTIVITY_TAG = "activityId";
+/** The provider tag naming the org whose `crmActivities` holds that row. */
+export declare const CRM_EMAIL_ORG_TAG = "orgId";
+/**
+ * The tags a one-to-one email carries so the delivery webhook can find its
+ * activity row (AGL-2615): the org, the activity, and the site for the
+ * per-site suppression list a bounce lands on.
+ *
+ * Every value is checked against the provider's alphabet rather than
+ * trusted, for the reason `contextTag` gives — a value the provider rejects
+ * fails the send, and a failed send is worse than an untracked one. The
+ * org and the activity are the pair the webhook needs, so an unusable
+ * value for EITHER yields no tags at all: a tag set that named a row it
+ * could not locate would be a promise the timeline cannot keep. The site
+ * is stamped when it can be and dropped alone when it cannot.
+ */
+export declare function crmEmailDeliveryTags(input: {
+    orgId: string;
+    hostId: string;
+    activityId: string;
+}): {
+    name: string;
+    value: string;
+}[];
+/**
+ * Which way an `email` activity's message traveled. `outbound` is every
+ * message the workspace wrote — sent by the platform, or copied to the
+ * capture address from a mailbox; `inbound` is one a correspondent wrote,
+ * which only the capture route files (AGL-2657).
+ */
+export type CrmEmailDirection = 'outbound' | 'inbound';
+/**
+ * `orgs/{orgId}/crmActivities/{activityId}` — one thing that happened.
+ *
+ * Distinct from a contact's `interactions`: those are what the PLATFORM
+ * recorded (a form, an order, a booking) and live capped on the row. An
+ * activity is what a PERSON logged — a call made, a meeting held — and can
+ * hang off a company or a deal with no contact at all.
+ */
+export interface CrmActivity extends CrmScoped {
+    kind: CrmActivityKind;
+    body: string;
+    /** When it happened, which is not when it was logged. */
+    atMs: number;
+    /** Who logged it, or `''` for an automation — see `CrmTask.createdByUid`. */
+    byUid: string;
+    /**
+     * The author's display name as it read when the activity was logged.
+     *
+     * Denormalized because there is no lookup that could answer it later: a
+     * member document is readable by its own subject and by org-wide members
+     * only, so a scoped editor reading a colleague's call log could not
+     * resolve the `byUid` beside it into a name. Stamped from the signed-in
+     * user's resolved name at log time and never rewritten, so it can drift
+     * from a later rename — the way a signed letter keeps the name it was
+     * signed with.
+     */
+    byName?: string;
+    /** The automation that logged it (AGL-2605), when a person did not. */
+    sourceActionId?: string;
+    /**
+     * The plugin that filed it on the record-timeline seam (AGL-2981) — an
+     * email a sequence sent, a reply it read.
+     */
+    sourcePluginId?: string;
+    contactId?: string;
+    companyId?: string;
+    dealId?: string;
+    /** The lead it was filed under (AGL-2615) — see {@link CrmActivityLink.leadId}. */
+    leadId?: string;
+    outcome?: string;
+    durationMinutes?: number;
+    /**
+     * An `email` the platform SENT (AGL-2615), as against one a person logged
+     * by hand: the subject line, who it went to, and where delivery got to.
+     * Absent on a hand-logged email, which has a body and nothing else.
+     */
+    subject?: string;
+    /** The address the message left for. */
+    to?: string;
+    /**
+     * `outbound` for a message the platform sent or a teammate copied to the
+     * capture address; `inbound` for one a correspondent wrote (AGL-2657).
+     */
+    direction?: CrmEmailDirection;
+    /** See {@link CrmEmailDeliveryState}; advanced by the delivery webhook. */
+    deliveryState?: CrmEmailDeliveryState;
+    /** When the delivery state last moved, epoch ms. */
+    deliveryAtMs?: number;
+    /**
+     * `hosts/{hostId}/bookings/{bookingId}` — the booking a `meeting` was
+     * filed from (AGL-2660), so a row the Bookings plugin wrote can be told
+     * from one a person logged, and a booking is never filed twice.
+     */
+    bookingId?: string;
+    /**
+     * An email CAPTURED from a mailbox (AGL-2657) — forwarded or copied to
+     * the workspace's capture address — as against one the platform sent:
+     * who wrote it, the provider's `Message-ID` the row is deduplicated by,
+     * the message it answered, and the subject with its reply and forward
+     * prefixes removed, which is what groups a thread. Absent on every other
+     * email row.
+     */
+    from?: string;
+    messageId?: string;
+    inReplyTo?: string;
+    threadSubject?: string;
+}
+/** An activity as a listener hands it back: the document plus its id. */
+export type CrmActivityRow = CrmActivity & {
+    $id: string;
+};
+/** What a sent one-to-one email is logged from — see {@link buildCrmEmailActivity}. */
+export interface CrmEmailActivityInput {
+    subject: string;
+    body: string;
+    /** The recipient, as the message was addressed. */
+    to: string;
+    /** When it was sent. */
+    atMs: number;
+    /** Who sent it, or `''` for an automation — see `CrmActivity.byUid`. */
+    byUid: string;
+    byName?: string;
+    sourceActionId?: string;
+    link: CrmActivityLink;
+    hostId: string;
+    visibleTo: string[];
+}
+/**
+ * The activity row a sent one-to-one email is logged as (AGL-2615).
+ *
+ * ONE builder for the two writers — the console's send route and the
+ * `sendEmail` automation step — so a message a rep wrote and a message a
+ * flow sent are the same kind of entry on the timeline: `kind: 'email'`,
+ * outbound, starting at `sent` for the delivery webhook to advance. A
+ * writer that assembled its own would be the one whose rows the chip did
+ * not know how to read. Timestamps are the writer's: a server stamps
+ * `serverTimestamp()` and this module has no Firestore.
+ */
+export declare function buildCrmEmailActivity(input: CrmEmailActivityInput): CrmActivity;
+/**
+ * One campaign email this person was sent, and what became of it (AGL-2616).
+ *
+ * The per-recipient delivery log — `emailDeliveries/{key}/messages` — keeps
+ * one document per MESSAGE with a timestamp per lifecycle state and a count
+ * of opens and clicks, and this is that document as a timeline reads it:
+ * which email, when it went out, and how far it got. A message that bounced
+ * or was complained about carries that state too, because "we mailed them
+ * and it bounced" is part of the history of a relationship and a timeline
+ * that showed only the successes would read as if nothing had been tried.
+ *
+ * The server answers with this shape, never the log record itself: the log
+ * carries the recipient's address, the provider and the links they followed,
+ * and none of that is the timeline's to show.
+ */
+export interface ContactCampaignEmail {
+    /** The provider's message id — distinct per send, and the entry's key. */
+    messageId: string;
+    /** The site the campaign went out from. */
+    hostId: string;
+    /** `hosts/{hostId}/campaigns/{campaignId}` — the email, whose report the entry links to. */
+    campaignId: string;
+    /**
+     * The email as the team named it in the Emails console — its display name,
+     * or its subject when it has none. `null` when the email has since been
+     * deleted, in which case the entry still has the subject it was sent with.
+     */
+    campaignName: string | null;
+    /** The subject line the person received. */
+    subject: string | null;
+    /** When it went out — the provider's `sent` instant, or the first event seen. */
+    sentAtMs: number;
+    deliveredAtMs?: number;
+    openedAtMs?: number;
+    clickedAtMs?: number;
+    bouncedAtMs?: number;
+    complainedAtMs?: number;
+    openCount: number;
+    clickCount: number;
+}
+/**
+ * One entry of a contact's timeline (AGL-2600): something the platform
+ * CAPTURED on the contact's facet, something a person LOGGED beside it, or
+ * — since AGL-2616 — a CAMPAIGN email the person was sent.
+ *
+ * A tagged union rather than a flattened row, because the three are
+ * different facts with different affordances — a captured interaction is
+ * read-only and names the door it came through, a logged activity has an
+ * author who may edit it, a campaign email is read-only and links to the
+ * campaign's report — and a surface drawing the stream has to say which is
+ * which. A logged activity of kind `email` and a campaign entry are two
+ * different things on purpose: the first is a message a person on the team
+ * sent or recorded, the second is a mailing the platform delivered, and the
+ * two must never share a kind id or a glyph.
+ */
+export type ContactTimelineEntry = {
+    kind: 'captured';
+    /** Distinct across the merged list, for a React key. */
+    key: string;
+    atMs: number;
+    interaction: ContactInteraction;
+} | {
+    kind: 'logged';
+    key: string;
+    atMs: number;
+    activity: CrmActivityRow;
+} | {
+    kind: 'campaign';
+    key: string;
+    atMs: number;
+    email: ContactCampaignEmail;
+};
+/**
+ * What became of one campaign email, as the words a timeline row prints
+ * after the email's name: `sent · delivered · opened ×2 · clicked`.
+ *
+ * In lifecycle order, and only the states that happened. `sent` is always
+ * first because the row exists; the counts appear only past one, because
+ * "opened ×1" says nothing "opened" does not. A bounce or a complaint is
+ * printed where it falls, after whatever succeeded before it — a message
+ * delivered and then complained about reads as both, which is what
+ * happened.
+ */
+export declare function campaignEmailSummary(email: ContactCampaignEmail): string[];
+/**
+ * ONE newest-first stream from a contact's two histories.
+ *
+ * The captured interactions live on the contact's facet and the logged
+ * activities in their own collection, and a page showing them as two lists
+ * asks the reader to do the interleaving in their head — "did the call come
+ * before or after the order?" is the question a timeline exists to answer.
+ *
+ * STABLE on purpose. The sort is on `atMs` alone, and at a tie the captured
+ * entries keep their place ahead of the logged ones, each in the order it
+ * arrived: a facet's interactions are already newest-first and a listener's
+ * rows are already ordered, so the merge must not reshuffle what its inputs
+ * settled. An entry with no usable time goes LAST, never first — a row that
+ * cannot say when it happened must not read as the most recent thing.
+ *
+ * The key is what a list renders by. A captured interaction has no id of its
+ * own, so its key is built from what it does carry; a logged activity's is
+ * its document id; a campaign email's is the provider's message id.
+ *
+ * A campaign email is placed at the instant it was SENT, not at its latest
+ * open. The row tells the whole story of that message in one line, and a
+ * message that moved up the stream every time its reader re-opened it would
+ * be a timeline that reorders itself under the reader.
+ */
+export declare function mergeContactTimeline(interactions: readonly ContactInteraction[] | null | undefined, activities: readonly CrmActivityRow[] | null | undefined, campaignEmails?: readonly ContactCampaignEmail[] | null): ContactTimelineEntry[];
+/**
+ * Which record an activity is ABOUT, for a surface that links to it, or
+ * `null` when it was filed against nothing.
+ *
+ * A contact outranks a deal outranks a company. An activity can name all
+ * three — a call with a person about a deal at their company — and the
+ * contact is the one a reader means when they ask "who was this with"; the
+ * deal is next because it is the thing with a clock on it; the company is
+ * the widest and so the last resort.
+ */
+export declare function crmActivityRecordLink(activity: Pick<CrmActivity, 'contactId' | 'companyId' | 'dealId' | 'leadId'>): {
+    record: 'contact' | 'deal' | 'company' | 'lead';
+    id: string;
+} | null;
+/**
+ * How long ago something happened, in the words a list row uses.
+ *
+ * Coarse on purpose. A row reads "3 days ago" and carries the full timestamp
+ * in its tooltip; the sentence exists so that a reader scanning a log can
+ * tell this week from last month without parsing dates. Past a week the
+ * relative form stops helping — "412 days ago" is a date the reader has to
+ * compute — so it becomes one. A time AHEAD of now is a date too: a call
+ * logged for tomorrow is a scheduling mistake the page should show plainly
+ * rather than dress as "in 14 hours". An unusable time reads as nothing.
+ *
+ * English rather than `Intl.RelativeTimeFormat` because the console is
+ * English-only, and the thresholds are what the spec pins.
+ */
+export declare function activityTimeLabel(atMs: number, nowMs: number): string;
+export type ContactFieldType = 'text' | 'number' | 'date' | 'select' | 'checkbox' | 'url';
+/**
+ * `orgs/{orgId}/contactFields/{fieldId}` — a custom field a holder defined.
+ *
+ * The `key` is the map key under a facet's `custom`, so it is IMMUTABLE once
+ * a value has been written under it; a rename is a new field and a retire.
+ * `retiredAt` rather than a delete for the same reason: values written under
+ * the key survive, and a retired field still has to be able to read them
+ * back on an export.
+ */
+export interface ContactFieldDefinition extends CrmScoped {
+    /** `^[a-z][a-z0-9_]{0,39}$` — see {@link normalizeContactFieldKey}. */
+    key: string;
+    label: string;
+    type: ContactFieldType;
+    /** The choices, for `select`. */
+    options?: string[];
+    required?: boolean;
+    /** Position in the form and the export, ascending. */
+    order: number;
+    retiredAt?: number | null;
+    /**
+     * Which record the field describes (AGL-2661). ABSENT means `contact`,
+     * because every definition written before companies and deals could carry
+     * custom fields described a contact, and a backfill that stamped them
+     * would touch every org for a fact the reader can infer. Read it through
+     * {@link fieldDefinitionObject}, never directly, so that inference lives
+     * in one place. Keys are unique PER OBJECT: a company field and a contact
+     * field may both be called `region`.
+     */
+    object?: CrmFieldObject;
+}
+/**
+ * The records a custom field may describe, in the order the Fields
+ * section tabs them (AGL-2661).
+ */
+export declare const CRM_FIELD_OBJECTS: readonly ["contact", "company", "deal"];
+export type CrmFieldObject = (typeof CRM_FIELD_OBJECTS)[number];
+/** How each object reads on the Fields section's tabs and in a refusal. */
+export declare const CRM_FIELD_OBJECT_LABELS: Record<CrmFieldObject, string>;
+export declare function isCrmFieldObject(value: unknown): value is CrmFieldObject;
+/**
+ * Which record a definition describes — `contact` when the document says
+ * nothing, or says something no reader understands.
+ *
+ * The one reader of {@link ContactFieldDefinition.object}. A stored value
+ * outside the list is read as `contact` rather than refused, for the
+ * reason an absent one is: the definition predates the field, or was
+ * written by something that never learned it, and either way the values
+ * under its key sit on contacts.
+ */
+export declare function fieldDefinitionObject(definition: Pick<ContactFieldDefinition, 'object'> | null | undefined): CrmFieldObject;
+/**
+ * The definition type under the name new code uses (AGL-2661). The type,
+ * the collection (`contactFields`) and the rules match keep the contact
+ * name: renaming them would ripple through the rules, the REST resources
+ * and the docs for no change in what is stored.
+ */
+export type CrmFieldDefinition = ContactFieldDefinition;
+/** What a stored field key must look like — a letter, then up to 39 of `[a-z0-9_]`. */
+export declare const CONTACT_FIELD_KEY_PATTERN: RegExp;
+/**
+ * A typed label, as the key it would be stored under, or `null` when nothing
+ * usable survives.
+ *
+ * Lowercased and snake-cased rather than refused, because the key is derived
+ * from the label a merchant typed ("Annual revenue" → `annual_revenue`) and
+ * they should not have to learn the grammar. Anything outside `[a-z0-9_]` is
+ * dropped after separators become underscores, runs collapse, and a leading
+ * run of digits or underscores goes — a key has to start with a letter so it
+ * can never collide with an array index or read as a number in a filter.
+ */
+export declare function normalizeContactFieldKey(input: unknown): string | null;
+/** The stage a deal is in, or `null` when the pipeline no longer has it. */
+export declare function dealStageById(pipeline: Pick<CrmPipeline, 'stages'> | null | undefined, stageId: string): CrmDealStage | null;
+/**
+ * What a deal is worth to a forecast, in cents.
+ *
+ * STATUS wins over the stage. A deal marked won is worth its full amount
+ * whatever stage it happens to sit in, and a lost one is worth nothing —
+ * the stage's probability is the odds of an OPEN deal, and applying it to a
+ * closed one would forecast a sale that has already happened as a fraction
+ * of itself. An open deal with no resolvable stage is worth nothing rather
+ * than everything: the pipeline lost the stage, and a forecast that filled
+ * the gap with 100% would be the most optimistic number available.
+ */
+export declare function weightedDealAmountCents(deal: Pick<CrmDeal, 'amountCents' | 'status'>, stage: Pick<CrmDealStage, 'probability'> | null | undefined): number;
+/** Whether a deal's amount is derived — it has at least one line item. */
+export declare function dealHasLineItems(deal: Pick<CrmDeal, 'lineItems'> | null | undefined): boolean;
+/**
+ * What a set of line items adds up to, in cents — the amount a deal with
+ * line items stores. Whole cents, never negative: a line's quantity and
+ * unit amount have both been through `readDealLineItems`, but a stored
+ * document from an older writer is trusted no further than that.
+ */
+export declare function lineItemsTotalCents(items: readonly Pick<CrmDealLineItem, 'quantity' | 'unitAmountCents'>[] | null | undefined): number;
+/**
+ * Line items as a client typed or sent them, validated into the stored
+ * shape, or the one reason they were refused.
+ *
+ * The one reader for both writers — the products card on a deal's page
+ * and `POST`/`PATCH /v1/deals` — so a line the console accepts is a line
+ * the API accepts and the other way round. The rules: at most
+ * {@link DEAL_LINE_ITEMS_MAX} lines; every line a name, a whole quantity
+ * of one or more, a whole unit amount of zero or more; every line in the
+ * DEAL's currency (`currency`), which a line may omit and may not
+ * contradict. An empty list is valid and means "no line items" — the
+ * amount goes back to being typed.
+ */
+export declare function readDealLineItems(input: unknown, currency: string): {
+    items: CrmDealLineItem[];
+} | {
+    error: string;
+};
+export type TaskDueState = 'overdue' | 'today' | 'upcoming' | 'none' | 'done';
+/**
+ * Where a task stands against the clock.
+ *
+ * `today` is decided on the LOCAL calendar day and beats `overdue`: a task
+ * due at nine this morning is today's work until midnight, not something the
+ * list should paint red at 9:01. Overdue is yesterday or earlier. `done`
+ * comes first because a completed task's due date is history whichever side
+ * of now it fell on.
+ */
+export declare function taskDueState(task: Pick<CrmTask, 'status' | 'dueAtMs'>, nowMs: number): TaskDueState;
+/**
+ * A typed or pasted domain, reduced to the bare lowercase hostname a company
+ * is keyed by, or `null` when what is left is not one.
+ *
+ * Strips what people paste along with a domain — the protocol, a `www.`, a
+ * path, a query, a port — because the value is a KEY: two contacts at
+ * `https://www.acme.com/about` and `acme.com` work for one company, and the
+ * match is only findable if both reduce to the same string. The last label
+ * has to be letters because a company's domain has a TLD; a bare IP address
+ * or a single word is not one and answers `null` rather than being stored as
+ * something a later match will never hit.
+ */
+export declare function normalizeCompanyDomain(input: unknown): string | null;
+/**
+ * The typed website, as a URL; `''` for a blank; `null` when it cannot be
+ * one.
+ *
+ * People type `acme.com` where a URL is asked for, and refusing that is
+ * pedantry — it becomes `https://acme.com`. What IS refused is anything the
+ * URL parser cannot read or a scheme other than http(s): a `javascript:` link
+ * on a record that renders as an anchor is not a website. One function for
+ * the company drawer and the companies import, so a website typed and a
+ * website imported are stored the same way.
+ */
+export declare function normalizeCompanyWebsite(input: unknown): string | null;
+/**
+ * Mailbox domains that belong to people rather than to a business: the
+ * providers anybody can sign up with, and the ones an internet provider
+ * hands its subscribers.
+ *
+ * Auto-associating a contact with a company by email domain is the whole
+ * reason {@link companyDomainForEmail} exists, and it is wrong for every
+ * address at a public mailbox: `gmail.com` is not a company, and a rule
+ * that treated it as one would file half of a consumer list under a single
+ * phantom account. It is also the fact a cold email has to know — an
+ * address here is a person's own, not their work address — which is why the
+ * list is exported with {@link isPublicMailboxDomain}: a second list kept
+ * for that question would drift from this one.
+ *
+ * Exact domains, not suffixes: a subscriber's regional host (`nc.rr.com`)
+ * is not listed, and neither is a company that happens to end in `mail.com`.
+ */
+export declare const PUBLIC_MAILBOX_DOMAINS: ReadonlySet<string>;
+/**
+ * Whether a domain — or the domain of an address — is one of the
+ * {@link PUBLIC_MAILBOX_DOMAINS}. Read the way a company domain is, so case,
+ * a trailing dot and a pasted `www.` do not hide one.
+ */
+export declare function isPublicMailboxDomain(domainOrEmail: unknown): boolean;
+/**
+ * The company domain an email address implies, or `null` when it implies
+ * none — a malformed address, or one at a public mailbox provider.
+ */
+export declare function companyDomainForEmail(email: unknown): string | null;
+/**
+ * The name a company minted from a domain starts with: the first label with
+ * a capital — `acme.com` → `Acme`, `initech.co.uk` → `Initech`.
+ *
+ * A starting point and not a claim about what the business is called: the
+ * lead-convert dialog offers it for editing, and a company the capture door
+ * creates on its own carries it until somebody renames the record. The
+ * domain itself would be an honest name too, but a list of companies that
+ * reads `acme.com`, `globex.example` looks like a list of websites, and the
+ * domain is on the row beside the name anyway.
+ */
+export declare function companyNameForDomain(domain: string): string;
+/**
+ * The top-level field on a CONTACT naming every company it is linked to.
+ *
+ * It carries the union of every holder's link, so removing an id from it is
+ * only correct when no other holder's facet still names that id — the rule
+ * the planner enforces, and the reason nothing writes this field without
+ * going through it. The facet is the truth and this is its index: a reader
+ * answering "which company is this person at" reads the facet; only a QUERY
+ * reads this.
+ */
+export declare const CONTACT_COMPANY_IDS_FIELD = "companyIds";
+/**
+ * The field on a COMPANY counting the contacts whose mirror names it.
+ *
+ * Denormalized because the honest figure is an aggregate over every contact
+ * in the org, which a list of two hundred companies cannot afford to take
+ * per row. Moved by `increment` in the same batch as the link that changes
+ * it, so the two cannot disagree by a failed second write; a company's own
+ * page still takes the live aggregate, which is what corrects a count that
+ * predates the counter.
+ */
+export declare const COMPANY_CONTACTS_COUNT_FIELD = "contactsCount";
+/** What the planner needs to know about a contact's links, and nothing else. */
+export interface ContactCompanyLinkState {
+    /** This holder's link, or `null` when the facet names no company. */
+    companyId: string | null;
+    /** The mirror as stored, in no order. */
+    companyIds: string[];
+    /**
+     * Ids named by OTHER holders' facets — what keeps an id in the mirror
+     * when this holder lets go of it.
+     */
+    heldElsewhere: string[];
+}
+/** The link state of a stored contact, read for one holder. */
+export declare function readContactCompanyLink(contact: Record<string, unknown> | null | undefined, groupId: string): ContactCompanyLinkState;
+/**
+ * Every holder whose facet names this company, in no order.
+ *
+ * What a company's DELETION clears. Unlike a link change, which is one
+ * holder's, a deletion takes the record away from every holder at once: a
+ * facet still naming it would be a link to nothing, on a surface its holder
+ * has no reason to revisit. Nothing else about another holder's facet is
+ * read.
+ */
+export declare function contactGroupsNamingCompany(contact: Record<string, unknown> | null | undefined, companyId: string): string[];
+/**
+ * How the mirror changes. Three shapes because Firestore takes ONE transform
+ * per field per write: an `arrayUnion` and an `arrayRemove` on the same
+ * field cannot share an update, so a move rewrites the array whole.
+ */
+export type ContactCompanyMirrorChange = {
+    op: 'union';
+    companyId: string;
+} | {
+    op: 'remove';
+    companyId: string;
+} | {
+    op: 'set';
+    companyIds: string[];
+};
+export interface ContactCompanyLinkPlan {
+    /** The facet's new value: the id, or `null` meaning delete the field. */
+    companyId: string | null;
+    /** What happens to the mirror, or `null` when it already carries the right ids. */
+    mirror: ContactCompanyMirrorChange | null;
+    /**
+     * Per company, how its contacts count moves. A company enters the list
+     * only when the mirror actually gains or loses it, so a link some other
+     * holder already made is not counted twice and a mirror that never carried
+     * an id is not decremented for it.
+     */
+    counts: Array<{
+        companyId: string;
+        delta: 1 | -1;
+    }>;
+}
+/**
+ * What linking a contact to a company FOR ONE HOLDER changes — or unlinking
+ * them, with `null`. `null` when the document already says what was asked.
+ *
+ * Three cases, and the mirror is handled differently in each because it is
+ * shared across holders while the facet is not:
+ *
+ *  - A first link `union`s the id in, which is safe against a concurrent
+ *    writer adding another holder's id.
+ *  - A MOVE from one company to another rewrites the mirror as a whole. The
+ *    old id is dropped only if no other holder's facet still names it.
+ *  - An unlink `remove`s the old id, on the same condition, and leaves the
+ *    mirror alone when another holder still needs it there.
+ *
+ * The counts follow the mirror, not the facet: the company's figure is "how
+ * many contacts name me in the mirror", and that is the quantity the
+ * company page's live aggregate measures.
+ */
+export declare function planContactCompanyLink(state: ContactCompanyLinkState, companyId: string | null): ContactCompanyLinkPlan | null;
+/** The org-document key the CRM's settings live under. */
+export declare const ORG_CRM_SETTINGS_FIELD = "crm";
+/** The dotted path an `update()` writes the auto-create switch by. */
+export declare const CRM_AUTO_CREATE_COMPANIES_PATH = "crm.autoCreateCompanies";
+/**
+ * Whether a capture from a work email domain no visible company carries
+ * should CREATE the company. Off unless the org document says `true`: a
+ * company minted from every domain that ever submitted a form is a list
+ * nobody asked for, so the default is the quiet one.
+ *
+ * Read off the raw document rather than a typed field, because the capture
+ * door holds a `Partial<AglynOrganization>` and the console a
+ * `Partial<AglynOrgBilling>`, and one reader has to answer both.
+ */
+export declare function orgAutoCreatesCompanies(orgDocument: Record<string, unknown> | null | undefined): boolean;
+/** Where the ordered rules live on the org document. */
+export declare const CRM_ASSIGNMENT_RULES_PATH = "crm.assignmentRules";
+/** The round-robin pool's member list, in rotation order. */
+export declare const CRM_ROUND_ROBIN_POOL_PATH = "crm.roundRobin.memberUids";
+/** The member handed the most recent round-robin record. */
+export declare const CRM_ROUND_ROBIN_LAST_ASSIGNED_PATH = "crm.roundRobin.lastAssignedUid";
+/**
+ * The most rules an org may keep. A first-match list longer than this is
+ * one nobody can reason about, and the section refuses the fifty-first
+ * rather than letting the document grow unbounded.
+ */
+export declare const CRM_ASSIGNMENT_RULES_MAX = 50;
+/** The most members a round-robin pool may hold. */
+export declare const CRM_ROUND_ROBIN_POOL_MAX = 50;
+/**
+ * The field-path SEGMENTS of a site's default owner on the org document.
+ *
+ * Segments rather than a dotted string, because the host id is a document
+ * id and a document id may contain a dot; joined with dots it would be read
+ * as two path elements and the write would land beside the setting rather
+ * than in it. A caller builds a `FieldPath` from these on either SDK.
+ */
+export declare function crmHostDefaultOwnerSegments(hostId: string): string[];
+/** The conditions a rule may name — every one present must hold. */
+export interface CrmAssignmentRuleWhen {
+    /** The capture door: `form`, `booking`, `order`, `manual`… */
+    source?: ContactSource;
+    /** The form the capture came through, by its document id. */
+    formId?: string;
+    /** The captured address's domain, lowercased, without a leading `@`. */
+    emailDomain?: string;
+    /** A tag the capture carries or the contact already wears. */
+    tag?: string;
+}
+/** How a matching rule assigns: one member, or the next in the pool. */
+export type CrmAssignmentTarget = {
+    memberUid: string;
+} | {
+    roundRobin: true;
+};
+/**
+ * One rule as the CRM reads it — `OrgCrmAssignmentRule` with the source
+ * narrowed to the capture vocabulary.
+ */
+export interface CrmAssignmentRule extends OrgCrmAssignmentRule {
+    when: CrmAssignmentRuleWhen;
+    assign: CrmAssignmentTarget;
+}
+/** The pool as the CRM reads it: never absent, possibly empty. */
+export interface CrmRoundRobinPool {
+    memberUids: string[];
+    lastAssignedUid: string | null;
+}
+/**
+ * The org's assignment settings, read tolerantly off the raw document.
+ *
+ * Every field is optional on the document and the section writes each on
+ * its own, so a reader that trusted the shape would throw on the first org
+ * that has set the pool but never a rule. Malformed entries are dropped
+ * rather than refused wholesale: one hand-edited rule must not stop the
+ * others from assigning.
+ */
+export interface CrmAssignmentSettings {
+    rules: CrmAssignmentRule[];
+    pool: CrmRoundRobinPool;
+    /** Site id → default owner uid, for the sites that set one. */
+    hostDefaultOwners: Record<string, string>;
+}
+/** A rule as the document holds it, or `null` for one that cannot assign. */
+export declare function readCrmAssignmentRule(raw: unknown): CrmAssignmentRule | null;
+export declare function readCrmAssignmentSettings(orgDocument: Record<string, unknown> | null | undefined): CrmAssignmentSettings;
+/** The member a site hands unclaimed captures to, or `null` for nobody. */
+export declare function crmHostDefaultOwner(orgDocument: Record<string, unknown> | null | undefined, hostId: string): string | null;
+/** What a rule is matched against: the capture, as its door described it. */
+export interface CrmAssignmentCapture {
+    source: ContactSource;
+    email: string;
+    formId?: string | null;
+    /** The capture's own tags and whatever the contact already wears. */
+    tags?: readonly string[];
+}
+/**
+ * The domain a rule's `emailDomain` is compared with — the address's own,
+ * lowercased. Not `companyDomainForEmail`, which answers `null` for a public
+ * mailbox: a team may well route every `gmail.com` sign-up to one rep, and
+ * a rule that could not name a consumer domain could not say so.
+ */
+export declare function assignmentEmailDomain(email: string): string | null;
+/**
+ * Whether every condition the rule names holds for this capture. A rule
+ * with no condition matches every capture — the catch-all.
+ */
+export declare function assignmentRuleMatches(when: CrmAssignmentRuleWhen, capture: CrmAssignmentCapture): boolean;
+/**
+ * The pool in the order the next record should try it: the member after
+ * the last recipient first, wrapping round, and the last recipient
+ * themselves at the end — so a pool of one still assigns, and a pointer
+ * naming somebody no longer in the pool starts from the top.
+ */
+export declare function roundRobinOrder(memberUids: readonly string[], lastAssignedUid: string | null | undefined): string[];
+/**
+ * How a rule reads in the settings list — its conditions in words and
+ * where it sends the record — so a reader can tell two rules apart without
+ * opening either. `memberLabel` turns a uid into a name; the section passes
+ * the roster's.
+ */
+export declare function describeAssignmentRule(rule: CrmAssignmentRule, memberLabel: (uid: string) => string): {
+    when: string;
+    assign: string;
+};
+/**
+ * A fresh rule id, unique among the ones the org already holds. Time and
+ * entropy rather than a counter, so two admins adding a rule in two tabs
+ * do not mint the same id and have one reorder clobber the other's rule.
+ */
+export declare function newAssignmentRuleId(existing: readonly string[]): string;
+/**
+ * The `visibleTo` every CRM creator stamps — client or server, whichever
+ * door the record comes in through.
+ *
+ * The contact create path's own expression (`upsertHostContact`), lifted
+ * here so that a company, a deal or a task created from a site's console
+ * lands in exactly the scope a contact captured on that site would: the
+ * whole org when the org has chosen `defaultResourceScope: 'org'`, and
+ * otherwise the sites that present as one sender — which, undeclared, is
+ * this site alone. That is the agency's isolation, arrived at with nothing
+ * configured, and the reason this is a function rather than a convention
+ * eight creators are asked to remember.
+ *
+ * Widening past the group is an ACT — an org-wide member editing the scope
+ * on the record — never a default. The rules refuse a scoped member creating
+ * a record outside their own tokens, so a creator that bypassed this could
+ * only make its record invisible to itself, never wider.
+ */
+export declare function crmScopeTokens(org: Record<string, unknown> | null | undefined, group: ConsentGroup): ScopeToken[];
+/**
+ * The `visibleTo` tokens a reader of this group may LIST, for the
+ * `array-contains-any` every CRM listener filters by.
+ *
+ * The other half of {@link crmScopeTokens}: that is what a creator stamps,
+ * this is what a reader asks for, and the two differ by exactly one token.
+ * `'org'` leads because an org-wide record is visible to every site — an org
+ * that widened its default deliberately still sees its own rows — and the
+ * group's sites follow. The contacts list computes this inline; every other
+ * CRM reader takes it from here so that none of them can drop the org token
+ * and lose the org-wide rows, or forget the cap and have Firestore refuse
+ * the query outright.
+ *
+ * Capped at {@link MAX_SCOPE_HOSTS}: a group wider than the operator's limit
+ * is listed as far as the limit reaches, which is the contacts list's
+ * behavior and the only one short of an error.
+ */
+export declare function crmReadTokens(group: ConsentGroup): ScopeToken[];
+/** One person on the team, as a picker lists them and a reference resolves to them. */
+export interface CrmMemberOption {
+    /** The account uid — what `ownerUid` and `assigneeUid` store. */
+    uid: string;
+    /** The name a colleague recognizes: display name, else address, else the uid. */
+    label: string;
+    /** The roster's address, when the member document carries one. */
+    email?: string;
+}
+/**
+ * How a step or a column names somebody on the team: an address when the
+ * text is one, otherwise a uid. `null` for a blank, which every caller
+ * treats as "nobody named" rather than as a member called "".
+ */
+export type CrmMemberRef = {
+    kind: 'uid';
+    uid: string;
+} | {
+    kind: 'email';
+    email: string;
+};
+export declare function parseCrmMemberRef(value: unknown): CrmMemberRef | null;
+/**
+ * A roster row as every CRM picker and column shows it.
+ *
+ * One mapping rather than four, because four is what the CRM had — and one
+ * of them dropped a member whose document had neither a display name nor an
+ * address, which is precisely the member the uid fallback exists for.
+ */
+export declare function crmMemberOption(member: Record<string, unknown>): CrmMemberOption | null;
+/**
+ * The member a stored reference names: by uid first — the stored shape —
+ * and by address second, so a record that carries an address where a uid
+ * belongs (an older import, a hand edit) still names the person the roster
+ * has under it. Undefined for nobody, which the caller renders honestly as
+ * "former member" or as the reference itself rather than as unassigned.
+ */
+export declare function findOrgMember<T extends {
+    uid: string;
+    email?: string | null;
+}>(members: readonly T[], ref: string | null | undefined): T | undefined;
+/**
+ * Where a lead stands, in the order a person works one.
+ *
+ * `qualified` is the CONVERTED state — a lead becomes a contact by being
+ * qualified, and the conversion stamps `convertedContactId` beside it — and
+ * `unqualified` is the closed-without-conversion state with its reason. A
+ * fixed list rather than free text for the reason the lifecycle stages are:
+ * the section filters on it and a report counts by it.
+ */
+export declare const CRM_LEAD_STATUSES: readonly ["new", "working", "qualified", "unqualified"];
+export type CrmLeadStatus = (typeof CRM_LEAD_STATUSES)[number];
+/** How a lead status reads on screen — typed so a status cannot ship unlabeled. */
+export declare const CRM_LEAD_STATUS_LABELS: Record<CrmLeadStatus, string>;
+/**
+ * The statuses a lead still needs somebody's attention in — what the Leads
+ * section shows by default, so the list opens on the work rather than on
+ * the history.
+ */
+export declare const CRM_LEAD_OPEN_STATUSES: readonly CrmLeadStatus[];
+/**
+ * The statuses that mean nobody needs to work the lead any more — the
+ * operand of the `in` clause an open-lead figure subtracts with. Subtracts,
+ * because an untouched lead carries no status field at all and Firestore
+ * cannot select on a field's absence; the closed statuses are always
+ * written, so they can be counted, and what remains is open. See
+ * `openLeadsFromCounts`.
+ */
+export declare const CRM_LEAD_CLOSED_STATUSES: readonly CrmLeadStatus[];
+export declare function isCrmLeadStatus(value: unknown): value is CrmLeadStatus;
+/**
+ * The working state the CRM writes onto a lead document, beside what the
+ * capture door wrote (`email`, `name`, `sources`, `submissionCount`,
+ * `firstSeenAtMs`, `lastSeenAtMs`, the consent map).
+ *
+ * The four `converted*`/`dealId`/`companyId` fields are stamped ONLY by the
+ * `crm/lead-convert` server route, in one write after the contact exists, so
+ * a lead that carries `convertedContactId` names a contact that was really
+ * created and a lead without it was never converted, whatever its status
+ * says. `unqualifiedReason` travels with `status: 'unqualified'` and is the
+ * one free-text field a report will want to read back.
+ */
+export interface CrmLeadFields {
+    status?: CrmLeadStatus;
+    /** The team member working the lead. */
+    ownerUid?: string;
+    notes?: string;
+    unqualifiedReason?: string;
+    /** `orgs/{orgId}/contacts/{contactId}` — the person this lead became. */
+    convertedContactId?: string;
+    convertedAtMs?: number;
+    /** The deal the conversion opened, when the converter asked for one. */
+    dealId?: string;
+    /** The company the conversion created or linked, when it named one. */
+    companyId?: string;
+}
+/**
+ * A lead's status as the list and the filter should read it.
+ *
+ * `new` for a lead that carries no status at all — every lead captured
+ * before the CRM existed, and every lead the capture door writes today,
+ * because `addHostLead` stamps none. Reading the absence as `new` is what
+ * lets the section open on the leads a site already holds rather than on an
+ * empty list until each one has been touched once. A stored value the union
+ * does not name also reads as `new`: it is a document some other writer
+ * produced, and refusing to list it would hide a person.
+ */
+export declare function crmLeadStatus(lead: Pick<CrmLeadFields, 'status'> | null | undefined): CrmLeadStatus;
+/** Whether a lead still needs working — see {@link CRM_LEAD_OPEN_STATUSES}. */
+export declare function isCrmLeadOpen(lead: Pick<CrmLeadFields, 'status'> | null | undefined): boolean;
+/** The lists a view can be saved for — every CRM section that has one. */
+export declare const CRM_VIEW_SECTIONS: readonly ["contacts", "companies", "deals", "tasks", "leads"];
+export type CrmViewSection = (typeof CRM_VIEW_SECTIONS)[number];
+export declare function isCrmViewSection(value: unknown): value is CrmViewSection;
+/**
+ * One filter a view carries: a field, an operator and a value, exactly as a
+ * list's own filter panel would send them to its query.
+ *
+ * `label` is the human reading of an OPAQUE value — a team member's name
+ * beside their uid, a company's name beside its id — kept on the clause so
+ * the chip that shows it can say "Owner is Dana" without a read. Display
+ * only: nothing matches on it, and a clause without one shows its value.
+ */
+export interface CrmViewFilterClause {
+    field: string;
+    op: string;
+    value: string;
+    label?: string;
+}
+/** The column a view orders by, and which way. */
+export interface CrmViewSort {
+    field: string;
+    direction: 'asc' | 'desc';
+}
+/**
+ * What a view holds about a list — the part a section reads and writes,
+ * without the name and the ownership around it.
+ *
+ * `columns` is the VISIBLE set, by column field, or empty for the list's
+ * own default; `sort` is one column or none, because a table sorts by one.
+ */
+export interface CrmViewState {
+    filters: CrmViewFilterClause[];
+    columns: string[];
+    sort: CrmViewSort | null;
+}
+/** `orgs/{orgId}/crmViews/{viewId}`. */
+export interface CrmSavedView extends CrmScoped, CrmViewState {
+    section: CrmViewSection;
+    name: string;
+    /** Whose working arrangement this is — the creator, and the one member the rules let change it. */
+    ownerUid: string;
+    createdByUid: string;
+    /** Listed for everybody who can read the section, rather than the owner alone. */
+    shared: boolean;
+}
+export declare const CRM_VIEW_NAME_MAX = 60;
+/**
+ * The most clauses one view carries. A bound on the predicate, not the
+ * audience: the list matches most of them in memory over a bounded window,
+ * and a stored array has no natural end.
+ */
+export declare const CRM_VIEW_MAX_FILTERS = 20;
+export declare const CRM_VIEW_MAX_COLUMNS = 60;
+export declare const EMPTY_CRM_VIEW_STATE: CrmViewState;
+/**
+ * A stored view's filters, held to the clause shape.
+ *
+ * Strict about what it keeps: a clause with no field or no operator is not
+ * a filter, and a valued operator with no value would read as a filter
+ * that matches nothing — so both are dropped rather than kept, for the same
+ * reason the dynamic-list rule drops an empty branch: a view must not
+ * quietly select a different population than the one it reads as.
+ */
+export declare function normalizeCrmViewFilters(value: unknown): CrmViewFilterClause[];
+export declare function normalizeCrmViewColumns(value: unknown): string[];
+export declare function normalizeCrmViewSort(value: unknown): CrmViewSort | null;
+/** A stored document's three list-facing fields, held to their shapes. */
+export declare function normalizeCrmViewState(value: unknown): CrmViewState;
+/**
+ * Whether two states describe the same list — what "unsaved changes" means.
+ *
+ * Clause order matters (a list applies them in order, and the first one the
+ * query can serve is the one it serves); the label on a clause does not,
+ * because nothing matches on it.
+ */
+export declare function crmViewStateEquals(a: CrmViewState, b: CrmViewState): boolean;
+/**
+ * Whether a view belongs in this reader's menu: their own, or one somebody
+ * shared. The rules admit the read either way — see the module note — so
+ * this is what keeps one person's private arrangement out of another's
+ * list.
+ */
+export declare function crmViewIsListed(view: Pick<CrmSavedView, 'shared' | 'ownerUid'>, uid: string | null | undefined): boolean;
+/**
+ * The Contacts list's filterable fields, by the names a view clause carries.
+ *
+ * A contract between three readers that cannot import one another: the
+ * list's own filter grammar (which declares these as its columns), a saved
+ * view (which stores them), and the dynamic-list translator below in
+ * `dynamic-list-rule.ts` (which turns them into audience dimensions). Named
+ * once so a rename on the list cannot silently stop an audience matching.
+ * `custom` is a PREFIX: a custom field's column is the prefix and its key.
+ */
+export declare const CRM_CONTACT_VIEW_FIELDS: {
+    readonly tags: "tags";
+    readonly source: "source";
+    readonly owner: "ownerUid";
+    readonly stage: "lifecycleStage";
+    readonly company: "companyId";
+    readonly createdAt: "createdAt";
+    readonly updatedAt: "updatedAt";
+    readonly orders: "ordersCount";
+    readonly ltv: "ltvCents";
+    readonly custom: "custom_";
+};
+/** The column a custom contact field filters and shows as. */
+export declare const crmContactCustomColumn: (key: string) => string;
+/** The field key a custom column stands for, or `null` for any other column. */
+export declare function crmContactCustomKey(column: string): string | null;
+/**
+ * A stored phone number as the `href` of a click-to-call link, or `null`
+ * when the value is not one (AGL-2661).
+ *
+ * The console stores E.164 (`normalizePhone` runs before every write), and
+ * a `tel:` URL wants exactly that: digits with a leading `+`, nothing else.
+ * Spaces, dots, dashes and parentheses are dropped rather than refused
+ * because a value written before normalization existed may carry them;
+ * anything that is not a run of digits after that — a word, an extension
+ * typed as `x123` — is refused, because a dialer handed it would ring
+ * nothing and the link would be a lie.
+ */
+export declare function crmTelHref(phone: unknown): string | null;
+/**
+ * A saved segment, as the filters of a contacts view.
+ *
+ * A segment is "any of these tags AND any of these sources", so each
+ * becomes one `isAnyOf` clause — OR within, AND across, which is the
+ * reading `contactMatchesSegment` gives it. A single tag is emitted as
+ * `contains` instead: that operator is the one the contacts query can serve
+ * from the index, so a one-tag segment opened as a view reaches the whole
+ * collection rather than the loaded window. The values are the segment's
+ * own, joined the way the grammar's `isAnyOf` splits them.
+ */
+export declare function crmViewFiltersFromSegment(segment: Pick<ContactSegment, 'tags' | 'sources'>): CrmViewFilterClause[];
+/**
+ * The other direction: the segment a view's filters describe, or `null`
+ * when the view carries no tag or source clause a segment could hold.
+ *
+ * Only the two dimensions a segment has are read, and only through the
+ * operators that mean "has one of these"; a `name startsWith` or an owner
+ * clause is not a segment's to keep. What comes back is what "Save as
+ * segment" writes, so a campaign audience built from it selects exactly the
+ * tags and sources the reader could see on the chips.
+ */
+export declare function crmViewSegmentFilters(filters: readonly CrmViewFilterClause[]): Pick<ContactSegment, 'tags' | 'sources'> | null;
+/**
+ * `users/{uid}.crmDefaultViews` — `{ [orgId]: { [section]: viewId } }`.
+ *
+ * On the reader's own profile document, beside `notificationPrefs`, because
+ * it is the same kind of fact: how one person wants their console to
+ * behave, owned and written by them alone. Keyed by org first because one
+ * account sits on several organizations and a view id is only meaningful
+ * inside the one that holds it.
+ */
+export declare const CRM_DEFAULT_VIEWS_FIELD = "crmDefaultViews";
+/** The view a section opens on for this reader in this org, or none. */
+export declare function crmDefaultViewId(profile: Record<string, unknown> | null | undefined, orgId: string | null | undefined, section: CrmViewSection): string | null;
+/**
+ * The merge patch that sets — or, with `null`, clears — one default.
+ *
+ * Shaped for a merged write so the other organizations' and sections'
+ * defaults on the same document survive it; `null` rather than a delete
+ * sentinel because this module carries no Firestore, and the reader above
+ * treats a null as no default.
+ */
+export declare function crmDefaultViewPatch(orgId: string, section: CrmViewSection, viewId: string | null): Record<string, unknown>;
+/** The field a record's attached files are stored under, on all three. */
+export declare const CRM_MEDIA_IDS_FIELD = "mediaIds";
+/**
+ * The most files one record may carry.
+ *
+ * A platform ceiling in the family of {@link CRM_ACTIVITIES_PER_RECORD_CEILING}
+ * rather than a plan dimension: attachments are bounded by human effort, and
+ * this is the bound. It is also what the Firestore rules can actually check
+ * — a rule can assert a list and its size, and cannot walk one — so the
+ * number is enforced rather than merely documented.
+ */
+export declare const CRM_MEDIA_IDS_MAX = 20;
+/**
+ * A stored or submitted attachment list, cleaned.
+ *
+ * Ids rather than URLs, deduplicated, trimmed, non-empty and capped. Written
+ * through by every path that sets the field — the console card, the REST
+ * write — so a record cannot hold a list one of them would refuse.
+ *
+ * An id is a media DOCUMENT id, resolved against the organization's library
+ * (`orgs/{orgId}/media/{mediaId}`) at read time. Storing the id and not the
+ * URL is what lets a file move between folders, and what keeps a private
+ * asset behind the signed CDN door rather than pinned to a raw storage URL
+ * that names its current location.
+ */
+export declare function normalizeCrmMediaIds(value: unknown): string[];