@aglyn/aglyn 1.0.0-beta.143

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

@@ -0,0 +1,554 @@
+/**
+ * @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 v1 (AGL-197): one contact per normalized email per host,
+ * fed by the four existing capture silos (forms, members, orders,
+ * bookings). Pure data module — the admin-SDK upsert lives in
+ * `@aglyn/tenant-data-admin` (`upsertHostContact`) and the console reads
+ * client-side under the host-admin rules.
+ */
+import type { AglynPostalAddress } from '../foundation';
+import type { ContactCustomValue, ContactLifecycleStage } from './crm';
+import { type MarketingBasis } from './marketing-consent';
+export type ContactSource = 'form' | 'member' | 'order' | 'booking' | 'newsletter' | 'api' | 'manual' | 'import' | 'account';
+/**
+ * How a capture source reads on screen.
+ *
+ * Typed `Record<ContactSource, string>` so a source added to the union cannot
+ * ship without a label, and kept beside the union rather than in the console
+ * that first needed it: the contacts filter, the campaign audience and the
+ * dynamic-list rule editor all name the same six sources, and three copies of
+ * this map is three places for `order` to stop reading as "Customer".
+ */
+export declare const CONTACT_SOURCE_LABELS: Record<ContactSource, string>;
+export interface ContactInteraction {
+    type: ContactSource;
+    /** Source doc id (formSubmissions/siteMembers/orders/bookings). */
+    refId?: string;
+    /** Epoch millis — Timestamps don't serialize into arrays cleanly. */
+    atMs: number;
+    summary?: string;
+    /**
+     * WHICH SITE this interaction happened on.
+     *
+     * A contact document is shared by every site in the org — one human who
+     * touched two sites is one person, and splitting them into two rows would
+     * bill the org twice for the same address and lose the dedupe that makes a
+     * multi-brand account worth having. But the HISTORY on that shared row is
+     * not shared: a booking made on one client's site is that client's, and a
+     * timeline that cannot be split by site shows an agency's client the other
+     * clients' activity.
+     *
+     * Optional because a row written before this field existed carries none,
+     * and an interaction whose site is unknown must read as unattributed rather
+     * than be assigned to whoever is looking. Nothing may infer it from the
+     * contact's own capture attribution: `capturedByHostIds` says which sites
+     * met this person, not which of them produced any particular visit.
+     */
+    hostId?: string;
+    /**
+     * THE ENTRY POINT: the form this capture came in through.
+     *
+     * `sources` answers "what KIND of surface met this person" and is what the
+     * console's capture filter reads; it cannot answer "which form", because
+     * every form on the site sets the same `form` flag. The id rather than the
+     * name, for the reason the submission carries the id: a form's caption is
+     * editable and a stored name splits the moment somebody renames it.
+     *
+     * Beside {@link refId} rather than derived from it. The submission the
+     * interaction names does carry the form, but reading it back would be a
+     * document read per row of a timeline the console renders straight out of
+     * the contact.
+     */
+    formId?: string;
+    /**
+     * THE ENTRY POINT: the page the person was on when this happened.
+     *
+     * The same `path` the submission stores. It belongs on the interaction and
+     * not on the contact, because a person who came in through the pricing page
+     * and returned through a blog post has two entry points and one row —
+     * a single field at the top would keep whichever capture wrote last.
+     */
+    path?: string;
+}
+/** `orgs/{orgId}/contacts/{contactId}` doc shape. */
+export interface HostContact {
+    /** Normalized (trimmed, lowercased) email — the dedupe key. */
+    email: string;
+    name?: string;
+    sources: Partial<Record<ContactSource, true>>;
+    /** Newest-first, capped — the profile timeline. */
+    interactions: ContactInteraction[];
+    tags?: string[];
+    notes?: string;
+    /**
+     * Every site that has captured this person, in no order.
+     *
+     * An ARRAY and a top-level field, because this is the one attribution that
+     * has to survive being a QUERY: "everyone captured on A, B or C" is an
+     * audience, and `array-contains-any` is what answers it. The per-interaction
+     * host says which visit belonged to whom; this says which sites have a
+     * relationship at all, and only the second shape can be filtered on in
+     * Firestore.
+     *
+     * Grows by `arrayUnion` on every capture, including the ones that merge
+     * onto an existing row — which is exactly what the create-only `hostId`
+     * beside it could never do.
+     */
+    capturedByHostIds?: string[];
+    /**
+     * Every form this person has come in through, in no order (AGL-2612).
+     *
+     * The entry point proper is `interactions[].formId` inside the capturing
+     * holder's facet, and that stays the record: which form produced which
+     * visit is one holder's business. But Firestore cannot select documents
+     * by a field of an array ELEMENT, and a facet path is per group, so
+     * "everyone who filled in this form" — the question the form's own page
+     * asks of the Contacts list — has to be a top-level array an
+     * `array-contains` can hit, exactly as `capturedByHostIds` is for sites
+     * and `companyIds` is for companies. A form id is minted under one site,
+     * so a query on it is one site's captures by construction.
+     *
+     * Grows by `arrayUnion` on every form capture, create or merge, bounded at
+     * {@link CONTACT_FORM_IDS_CAP}: a person who has filled in more forms than
+     * that keeps the first twenty and the timeline keeps the rest. The facet is
+     * the truth and this is its index — a reader answering "which form" reads
+     * the interaction; only a QUERY reads this.
+     */
+    formIds?: string[];
+    /** E.164, mirrored from the last facet write that set one. */
+    phone?: string;
+    /** The company name as typed, mirrored the same way. */
+    companyName?: string;
+    /**
+     * The OTHER addresses this person answers to (AGL-2625).
+     *
+     * A contact is keyed on one email, so one human with a work address and a
+     * personal one is two documents until somebody merges them. The merge keeps
+     * the survivor's `email` as the identity and records the merged record's
+     * address here, so a later capture on it — a form filled in from the
+     * personal account — resolves to this row rather than minting the second
+     * document again. `emailIndex` (see {@link CONTACT_EMAIL_INDEX_COLLECTION})
+     * is the lookup; this array is the record of why an entry there points
+     * where it does, and what the record page shows as "also".
+     *
+     * Shared identity like `email`, not a facet field: which addresses are one
+     * person is a fact about the person, and a holder that did not perform the
+     * merge still needs its capture on the alternate address to land on the
+     * shared row. Bounded at {@link CONTACT_ALTERNATE_EMAILS_CAP}.
+     */
+    alternateEmails?: string[];
+    /**
+     * When the earliest OPEN task filed against this person is due, epoch
+     * ms, or `null` when none is (AGL-2661) — see `CrmDeal.nextTaskAtMs` in
+     * `crm.ts` for the rule. On the SHARED row rather than a facet, because a
+     * task lives at the organization level and names the contact, not a
+     * holder's view of them.
+     */
+    nextTaskAtMs?: number | null;
+}
+/** Timeline cap: keeps the doc small; older interactions age out. */
+export declare const CONTACT_INTERACTIONS_CAP = 50;
+/** The field holding {@link HostContact.alternateEmails}. */
+export declare const CONTACT_ALTERNATE_EMAILS_FIELD = "alternateEmails";
+/**
+ * The most alternate addresses one contact carries. Ten is past any real
+ * person's mailbox count, and it bounds the index writes one merge fans out.
+ */
+export declare const CONTACT_ALTERNATE_EMAILS_CAP = 10;
+/**
+ * `orgs/{orgId}/emailIndex/{personKey}` → `{ email, contactId }` (AGL-2625).
+ *
+ * The address-to-contact lookup the capture door consults BEFORE the
+ * per-document `email ==` query, so an address recorded as an alternate on a
+ * merged row resolves to the survivor. Keyed by `personKey` — the sha256 of
+ * the normalized address — so a document id never carries the address
+ * itself, the same derivation a lead and a list membership use.
+ *
+ * WRITTEN LAZILY, never backfilled: the query on `email` stays as the
+ * fallback, and a contact that has no entry gets one on the next write that
+ * finds it. A row the index has never seen therefore costs one extra read
+ * once, and nothing needs to run over the existing collection.
+ *
+ * Server-written only; the rules close it to every client.
+ */
+export declare const CONTACT_EMAIL_INDEX_COLLECTION = "emailIndex";
+/**
+ * Every address a contact answers to — the primary first, then the
+ * alternates — normalized and deduplicated, so an index writer and a lead
+ * lookup walk one list.
+ */
+export declare function contactEmails(contact: Record<string, unknown> | null | undefined): string[];
+/** The top-level field naming every form a contact came in through — see `HostContact.formIds`. */
+export declare const CONTACT_FORM_IDS_FIELD = "formIds";
+/**
+ * How many forms the {@link CONTACT_FORM_IDS_FIELD} mirror holds.
+ *
+ * The same figure as the tag cap: enough that no real person reaches it,
+ * small enough that the array never becomes the document. Past it the
+ * capture stops adding rather than dropping the oldest, because the mirror
+ * is an index of the facet's timeline and an index that silently forgets an
+ * entry the timeline still holds would answer a form's contact list wrongly
+ * in the one direction nobody would notice.
+ */
+export declare const CONTACT_FORM_IDS_CAP = 20;
+/** Normalized dedupe key, or null when the input isn't a usable email. */
+export declare function normalizeContactEmail(input: unknown): string | null;
+/**
+ * First usable email in a free-form form-submission fields map — forms
+ * don't guarantee a canonical email field, so prefer keys that look like
+ * email fields before falling back to any email-shaped value.
+ */
+export declare function extractEmailFromFields(fields: Record<string, unknown> | null | undefined): string | null;
+/**
+ * Merges a new interaction into a contact: source flag set, interaction
+ * prepended, timeline capped. Pure — the caller persists the result.
+ */
+export declare function mergeContactInteraction(existing: Pick<HostContact, 'sources' | 'interactions'> & {
+    name?: string;
+}, update: {
+    source: ContactSource;
+    interaction: ContactInteraction;
+    name?: string;
+}): Pick<HostContact, 'sources' | 'interactions'> & {
+    name?: string;
+};
+/**
+ * THE PER-HOLDER FACET on a shared contact document.
+ *
+ * ## What is shared and what is not
+ *
+ * One human who touched two sites is ONE document. That is not a compromise:
+ * it is the dedupe the shared address book exists for, it is what keeps a
+ * bounce and a suppression describing one person, and it is what makes a
+ * multi-brand account bill once for one human instead of once per site. A
+ * document per host would push an agency toward twelve separate accounts and
+ * throw the whole advantage away.
+ *
+ * But almost nothing ON that document is legitimately shared.
+ *
+ *  - **SHARED IDENTITY** — `email`, and the canonical `name`. One human, one
+ *    identity. This is the only part two unrelated businesses may both see,
+ *    and it is the minimum that makes them one row.
+ *  - **PER-HOLDER FACET** — everything in this interface. A note, a tag, a
+ *    call log and a lifetime value are the HOLDER's own business records.
+ *    Host A's note about a customer is Host A's; a competitor sharing the
+ *    platform must not read it, and while these lived at the top of the
+ *    document every site in the org could.
+ *  - **CONSENT AND VISIBILITY** — per declared group, decided by
+ *    `marketing-consent.ts` and by `visibleTo`.
+ *
+ * ## Keyed by GROUP, not by host
+ *
+ * A business that declared three sites to be one sender is one CRM: a note
+ * written on the shop belongs beside the booking made on the booking page,
+ * because one team keeps both. Across groups, never — and an undeclared site
+ * is a group of one, so the agency case is isolated with nothing configured.
+ *
+ * ## Commercial figures are per-facet, and that is not a billing change
+ *
+ * `ltvCents` and `ordersCount` answer "what is this person worth to ME". Two
+ * unrelated merchants who both sell to one person have two different answers
+ * and neither is entitled to the other's. Billing counts DOCUMENTS, and there
+ * is still one document, so a person held by two hosts stays one billable
+ * contact.
+ */
+export interface ContactFacet {
+    /**
+     * This holder's display name for the person, overriding the canonical one.
+     *
+     * The canonical `name` is shared and mutable, so without this a rename on
+     * one site changes what an unrelated business sees in its own CRM — two
+     * companies that do not know each other exist editing each other's records.
+     * The override is written by whoever edits the name from their own console;
+     * the canonical field stays as the identity of last resort, for a holder
+     * that has never set one.
+     */
+    name?: string;
+    /** Which capture surfaces THIS holder saw the person through. */
+    sources: Partial<Record<ContactSource, true>>;
+    /** THIS holder's timeline, newest-first and capped. */
+    interactions: ContactInteraction[];
+    /** THIS holder's tags. */
+    tags?: string[];
+    /** THIS holder's notes. */
+    notes?: string;
+    /**
+     * The campaigns THIS holder has filed the person under.
+     *
+     * A label on the CRM record, not an audience: who a campaign's mail reaches
+     * is decided by the campaign's lists and by each send's own picker, and
+     * nothing in the send path reads this. It answers "who did we put in the
+     * spring push", which is a question about the holder's own working set.
+     *
+     * Per-holder for the reason the notes are: two unrelated businesses sharing
+     * one row must not read each other's segmentation of a person they both
+     * know. See `campaign-membership.ts` for the field and the path.
+     */
+    campaignIds?: string[];
+    /** Gross of fees and refunds — see `upsertHostContact`. */
+    ltvCents?: number;
+    ordersCount?: number;
+    lastPurchaseAtMs?: number;
+    firstPurchaseAtMs?: number;
+    refundedCents?: number;
+    refundedOrdersCount?: number;
+    lastRefundAtMs?: number;
+    /** E.164 — `normalizePhone` before writing. */
+    phone?: string;
+    jobTitle?: string;
+    /** `orgs/{orgId}/companies/{companyId}`, in this holder's scope. */
+    companyId?: string;
+    /**
+     * The company's name as this holder knows it.
+     *
+     * Free text, so a person can be filed under a company before one exists
+     * as a record; the company picker that later sets `companyId` writes the
+     * picked company's name here too, so the row reads the same whether the
+     * link was made or the name typed. The top-level `companyName` on the
+     * document is the search echo of this value — see `HostContact`.
+     */
+    companyName?: string;
+    address?: AglynPostalAddress | null;
+    /** The team member responsible for the relationship. */
+    ownerUid?: string;
+    lifecycleStage?: ContactLifecycleStage;
+    /** Custom field values, keyed by `ContactFieldDefinition.key`. */
+    custom?: Record<string, ContactCustomValue>;
+    /**
+     * When this person last OPENED or CLICKED a campaign sent by one of this
+     * holder's sites, epoch ms (AGL-2616).
+     *
+     * Stamped by the delivery webhook, forward-only, on the first open and the
+     * first click of each message — the same bound the per-person rollup on
+     * `emailDeliveries/{key}` keeps, so a reader opening one newsletter six
+     * times is one write. Per-holder because it answers "is this person still
+     * reading OUR mail": the address-level rollup counts every sender's mail
+     * and a sibling business's, and a re-engagement audience built on that
+     * would mail people who are reading somebody else.
+     *
+     * Absent until the first engagement after the stamp shipped; a message
+     * opened before then advanced the address-level rollup and nothing here.
+     */
+    lastEmailEngagementAtMs?: number;
+    /**
+     * The org-library files THIS holder has attached to the person
+     * (AGL-2662), by media document id.
+     *
+     * Per-holder for the reason every other field here is: an agency running
+     * two client brands has one contact document between them, and a signed
+     * contract one client filed is not the other client's to see. Ids rather
+     * than URLs so a file moved between folders keeps its attachment, and so
+     * a private asset is still served through the signed CDN door.
+     */
+    mediaIds?: string[];
+}
+/** The map field holding the facets: `{ [groupId]: ContactFacet }`. */
+export declare const CONTACT_FACETS_FIELD = "facets";
+/**
+ * The facet one group holds, or an empty one.
+ *
+ * `map[groupId]` — a lookup, not a search, for the reason the consent map is
+ * shaped the same way: there is no expression of this form that returns
+ * another holder's notes.
+ *
+ * An absent facet reads EMPTY rather than falling back to the top-level
+ * fields. A fallback would hand every holder in the org the fields the
+ * pre-facet document carried at its top, which is the disclosure this shape
+ * exists to end; the migration moves them into the capturing group's facet
+ * instead.
+ */
+export declare function readContactFacet(contact: Record<string, unknown> | null | undefined, groupId: string): ContactFacet;
+/** The dotted Firestore path to one field of one holder's facet. */
+export declare function contactFacetPath(groupId: string, field: string): string;
+/**
+ * The name a given holder should SEE for this person.
+ *
+ * Their own override first, the canonical identity second. Nothing falls
+ * through to another holder's override: that would be one business's edit
+ * showing up in another's CRM, which is the thing the override exists to
+ * prevent.
+ */
+export declare function contactDisplayName(contact: Record<string, unknown> | null | undefined, groupId: string): string;
+/**
+ * Every group that holds this contact — the reference count behind a detach.
+ *
+ * Read from `visibleTo` rather than from the facet map, because `visibleTo`
+ * is what both enforcement layers actually evaluate: a holder that can still
+ * READ the row is still holding it whether or not they ever wrote a note. A
+ * count taken from the facets would drop a holder who has one and no facet
+ * and leave them able to see a document nothing believes they hold.
+ */
+export declare function contactHolderTokens(contact: Record<string, unknown> | null | undefined): string[];
+/** What a holder letting go of a contact should do to the document. */
+export type ContactDetach = {
+    /** Nobody else holds it. Delete the document. */
+    action: 'delete';
+} | {
+    /** Other holders remain. Drop this one's half. */
+    action: 'detach';
+    /**
+     * Field-level removals, as a patch. Dotted paths so the OTHER holders'
+     * facets and consent entries are untouched — a nested write would
+     * replace the whole map and take every other holder's records with it.
+     */
+    remove: string[];
+    /** Scope tokens to pull out of `visibleTo`. */
+    removeTokens: string[];
+    /** Host ids to pull out of the capture attribution. */
+    removeHostIds: string[];
+};
+/**
+ * DELETE IS A DETACH.
+ *
+ * One holder removing a contact from their own CRM must not destroy another
+ * holder's relationship with that person: they have their own notes, their
+ * own order history and their own consent, none of which the deleting holder
+ * ever had a claim on. So a delete drops the deleting group's facet, its
+ * consent entries, its capture attribution and its scope tokens — and the
+ * DOCUMENT dies only when the last holder lets go.
+ *
+ * ⛔ This is NOT the erasure path. A privacy erasure removes the person
+ * everywhere regardless of how many holders remain, and routing it through
+ * reference counting would turn a lawful erasure into a partial one — the same
+ * absent-versus-invisible defect this area keeps hitting, in the one place
+ * where getting it wrong is a legal failure rather than a bug. Erasure calls
+ * the document delete directly and must never consult this function.
+ *
+ * @param group the holder letting go, with every site it covers.
+ */
+export declare function planContactDetach(contact: Record<string, unknown> | null | undefined, group: {
+    groupId: string;
+    hostIds: readonly string[];
+}): ContactDetach;
+/**
+ * The interactions one group of sites may see on a shared contact.
+ *
+ * An interaction with NO host is shown to everyone: it predates the
+ * attribution, so hiding it would empty every existing timeline, and it is
+ * already visible to anyone who can read the row. An interaction that names a
+ * site is shown only to that site's own group — the agency case, where one
+ * client must not read another client's bookings off a person they both know.
+ */
+export declare function interactionsForGroup(interactions: readonly ContactInteraction[] | undefined, hostIds: readonly string[]): ContactInteraction[];
+/** `orgs/{orgId}/contactSegments/{id}` — a saved audience filter. */
+export interface ContactSegment {
+    name: string;
+    /** Match contacts sharing at least one tag (empty = any). */
+    tags?: string[];
+    /** Match contacts with at least one of these sources (empty = any). */
+    sources?: ContactSource[];
+}
+/** Segment matching (AGL-199): AND across filter kinds, OR within one. */
+export declare function contactMatchesSegment(contact: Pick<HostContact, 'tags' | 'sources'>, segment: Pick<ContactSegment, 'tags' | 'sources'>): boolean;
+/**
+ * Every field of a contact document the org view may read.
+ *
+ * Stated as a value so it can be asserted against — see the org-view spec,
+ * which seeds each facet field with a sentinel and proves none of them
+ * reaches a row.
+ */
+export declare const ORG_CONTACT_FIELDS: readonly ["email", "name", "capturedByHostIds", "marketingConsentByHost", "marketingConsent"];
+/**
+ * What one site's relationship with one person amounts to, at org level.
+ *
+ * Consent is per (contact, host-or-group) and there is no expression that
+ * returns another controller's grant, so a row cannot carry one consent
+ * verdict. It carries one PER CAPTURING SITE, each naming the controller it
+ * was read for — a bare "consented" with nobody attached would be exactly the
+ * confusion the per-brand model was built to prevent.
+ */
+export interface OrgContactHostConsent {
+    /** The site this verdict answers about, and no other. */
+    hostId: string;
+    /** The controller the basis runs to — the declared group, or the site. */
+    groupId: string;
+    /**
+     * The group's disclosed name, or `null` for a site that pools with nobody.
+     *
+     * `null` is not "unknown": it is the group of one, where the site's own
+     * name is the disclosure and inventing a second would put a label in front
+     * of a reader that nothing else uses.
+     */
+    groupName: string | null;
+    /** Whether the controller is a DECLARED group rather than the site alone. */
+    declared: boolean;
+    /** `granted` | `declined` | `unrecorded` — never collapsed to a boolean. */
+    basis: MarketingBasis;
+}
+/** One person, as the organization may see them across all of its sites. */
+export interface OrgContactRow {
+    $id: string;
+    /** The dedupe key, and the reason two captures are one row. */
+    email: string;
+    /** The SHARED identity. Never a holder's own override. */
+    name: string;
+    /** Every site that has captured this person, sorted for a stable render. */
+    capturedByHostIds: string[];
+    /** One verdict per capturing site, in the same order. */
+    consent: OrgContactHostConsent[];
+}
+/**
+ * Every site that has captured this person.
+ *
+ * Sorted, because the array is maintained by `arrayUnion` and therefore
+ * carries capture order, which is not an order anything should render: two
+ * readers of the same row would see the sites in different places on the
+ * screen depending on which site met the person first.
+ */
+export declare function contactCaptureHostIds(contact: Record<string, unknown> | null | undefined): string[];
+/**
+ * One contact document, projected to what an ORG may see.
+ *
+ * @param org - the org document — the only input that can resolve a declared
+ *   consent group, and required for that reason. Without it every site reads
+ *   as a group of one, which understates the disclosure a person was given
+ *   and is the safe direction to be wrong in.
+ */
+export declare function orgContactRow(contact: Record<string, unknown> | null | undefined, contactId: string, org: Record<string, unknown> | null | undefined): OrgContactRow;
+/**
+ * How a basis reads on screen.
+ *
+ * Three labels because there are three states. "Opted in" and "No record" are
+ * not opposites and must never collapse into one negative: absence is the
+ * commonest case by far — a record captured before the checkbox existed — and
+ * showing it as a refusal would tell a merchant they may not mail somebody
+ * who never said so.
+ */
+export declare const MARKETING_BASIS_LABELS: Record<MarketingBasis, string>;
+/**
+ * One consent verdict, WITH THE CONTROLLER IT RUNS TO, as one string.
+ *
+ * ⛔ There is no function here that returns a basis on its own, and that is
+ * the point. A basis is per (person, controller): the same person can be
+ * opted in to one brand in an org and opted out of another, so "consented"
+ * with nobody attached is not a shortened truth, it is a different and false
+ * claim — precisely the confusion the per-brand model was built to prevent.
+ * Joining the two into a single value is what stops a caller rendering half
+ * of it.
+ *
+ * The controller is the DECLARED GROUP when there is one, because that is who
+ * the person was told they would hear from, and the site otherwise. A group
+ * of one is named by the site, which is what the capture surface already
+ * showed them.
+ *
+ * @param siteName - how this site reads — the caller resolves it, since the
+ *   contact document holds ids and not names. An empty one falls back to the
+ *   id: a site whose name cannot be resolved must still be NAMED, because
+ *   dropping it would understate which brands hold a relationship.
+ */
+export declare function orgContactConsentLabel(entry: OrgContactHostConsent, siteName?: string): string;