@aglyn/aglyn 1.0.0-beta.143

package/src/lib/app-utils/dynamic-list-rule.d.ts

@@ -0,0 +1,471 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { type ContactSource } from './contacts';
+import { type ContactCustomValue, type ContactLifecycleStage, type CrmViewFilterClause } from './crm';
+/** The silos a dynamic list may draw people from. */
+export type DynamicListSource = 'contacts' | 'leads' | 'siteMembers'
+/**
+ * `hosts/{hostId}/formSubmissions`, which is what answers "everyone who
+ * submitted form X" — the form's NAME is on the submission and on nothing
+ * else. A contact captured by a form records only that some form produced
+ * it (`sources.form`), so `captureSources` cannot express the question.
+ */
+ | 'formSubmissions';
+/**
+ * The silos whose rows can be filed under a campaign.
+ *
+ * A contact carries the membership inside the holder's own facet and a form
+ * submission carries the membership its form had when it arrived. A lead and a
+ * site member carry none — nothing writes one — so the campaign dimension is
+ * SKIPPED for them rather than failed, which is the same discipline every
+ * silo-specific dimension here follows.
+ *
+ * Stated as a value because both the matcher and the materializer's enrichment
+ * decide off it, and two lists would drift into a rule that selects a silo the
+ * scan never reads the field for.
+ */
+export declare const CAMPAIGN_MEMBER_SILOS: DynamicListSource[];
+/** Purchase-history filters. Contacts only — no other silo stores RFM. */
+export interface DynamicListBehavior {
+    ordersCountAtLeast?: number;
+    ltvCentsAtLeast?: number;
+    lastPurchaseWithinDays?: number;
+    /**
+     * Lapsed customers. A person who has NEVER purchased does not match: the
+     * question is "bought once and stopped", and answering it with everybody
+     * who never bought would put the whole audience in a win-back campaign.
+     */
+    noPurchaseForDays?: number;
+}
+/**
+ * Engagement filters, read from the per-person rollup the delivery webhook
+ * maintains on `emailDeliveries/{personKey}`.
+ *
+ * ## Why the "for N days" arms count people with no record, and
+ * `noPurchaseForDays` beside them does not
+ *
+ * A purchase is an act the person performed, so "no purchase on file" is
+ * strong evidence they did not buy — and somebody who never bought is not a
+ * LAPSED customer. An open is not like that. We learn of one only if we
+ * mailed them, the message arrived, and their client loaded the tracking
+ * pixel, so "no open on file" and "did not open" rest on the same evidence.
+ * A merchant asking for people who are not engaging means the silent ones
+ * too, and the sentences the console reads back say which lean applies rather
+ * than leaving it to be inferred.
+ *
+ * ## Opens are the weaker signal, and the field names keep them apart
+ *
+ * Apple's Mail Privacy Protection prefetches images, so an open is partly a
+ * statement about a mail client; a click is a statement about a person. Both
+ * are offered because both are stored, and they are never merged into one
+ * "engaged" number that would hide which of the two a rule rests on.
+ */
+export interface DynamicListEngagement {
+    /** Opened any of our mail within the last N days. */
+    openedWithinDays?: number;
+    /** Clicked a link in any of our mail within the last N days. */
+    clickedWithinDays?: number;
+    /** No open on record for at least N days — never opened counts. */
+    notOpenedForDays?: number;
+    /** No click on record for at least N days — never clicked counts. */
+    notClickedForDays?: number;
+}
+/**
+ * How a custom-field clause compares the stored value to the one it names.
+ *
+ * Seven operators and no more, because each one has to be readable back as
+ * a sentence and each one has to state what it does with a BLANK value —
+ * see {@link customValueMatches} for the lean every operator takes.
+ */
+export declare const DYNAMIC_LIST_CUSTOM_OPS: readonly ["eq", "neq", "contains", "gt", "lt", "set", "unset"];
+export type DynamicListCustomOp = (typeof DYNAMIC_LIST_CUSTOM_OPS)[number];
+/**
+ * One condition on one custom contact field (AGL-2603).
+ *
+ * `key` is the {@link ContactFieldDefinition.key} the value is stored under
+ * in the holder's facet, `op` says how to compare and `value` is what to
+ * compare with — absent for `set` and `unset`, which ask about presence
+ * rather than content. Scalars only, because that is all a custom field may
+ * hold.
+ */
+export interface DynamicListCustomClause {
+    key: string;
+    op: DynamicListCustomOp;
+    value?: string | number | boolean;
+}
+/**
+ * The most custom-field clauses one block may carry.
+ *
+ * A bound on the predicate rather than on the audience — every clause is
+ * evaluated in memory against a candidate already read — kept small for the
+ * reason the branch cap is: the rule is merchant-authored and a stored array
+ * has no natural end.
+ */
+export declare const DYNAMIC_LIST_MAX_CUSTOM_CLAUSES = 20;
+/**
+ * One AND-block of filters.
+ *
+ * Everything except `sources` and `segmentId`, which stay on the rule itself
+ * — see {@link DynamicListRule.sources} for why the source list may not move
+ * into a branch and may not be negated.
+ */
+export interface DynamicListDimensions {
+    /** Contacts only: at least one of these tags. */
+    tags?: string[];
+    /** Contacts only: captured by at least one of these surfaces. */
+    captureSources?: ContactSource[];
+    /** `formSubmissions` only: at least one of these form names, case-insensitive. */
+    formNames?: string[];
+    /**
+     * {@link CAMPAIGN_MEMBER_SILOS} only: filed under at least one of these
+     * campaigns, by campaign id.
+     *
+     * ⚠️ NOT the campaign a person's browser was attributed TO. A campaign
+     * TOUCH says which ad or link brought somebody in and lives on the
+     * attribution record; this says which campaign the merchant FILED the
+     * record under. The two are different facts about different acts and a
+     * single dimension over both would answer neither question — see
+     * `campaign-attribution.ts` for the other one.
+     *
+     * ⛔ And membership is not consent. A person selected by this dimension has
+     * opted in to nothing: they are here because a merchant put a form in a
+     * campaign, which is the merchant's own act. The materializer enrolls with
+     * no basis at all, and this dimension does not change that.
+     */
+    campaignIds?: string[];
+    /** Any silo: the record was created at or after this instant. */
+    createdAfterMs?: number;
+    /** Any silo: the record was created strictly before this instant. */
+    createdBeforeMs?: number;
+    /** Contacts only. */
+    behavior?: DynamicListBehavior;
+    /** Any silo — engagement is a fact about an address, not about a silo row. */
+    engagement?: DynamicListEngagement;
+    /** Already a member of every one of these lists. */
+    inListIds?: string[];
+    /** A member of none of these lists — the "not in list X" every rival has. */
+    notInListIds?: string[];
+    /** Owned by any of these team members, by account uid. */
+    ownerUids?: string[];
+    /** In any of these lifecycle stages. */
+    lifecycleStages?: ContactLifecycleStage[];
+    /** At any of these companies, by `orgs/{orgId}/companies` id. */
+    companyIds?: string[];
+    /** Every clause must hold — AND within the dimension, unlike the lists above. */
+    custom?: DynamicListCustomClause[];
+    /**
+     * Opened or clicked a campaign sent by the sweeping holder's sites within
+     * the last N days (AGL-2616) — the re-engagement audience.
+     *
+     * Read from the holder's facet like the four above, and contacts only for
+     * the same reason. It is NOT the {@link engagement} block one field up:
+     * that reads the address-level rollup, which counts every sender's mail
+     * to the address — a receipt, an invite, a sibling business's newsletter —
+     * and a "win back our quiet readers" audience built on it would mail
+     * people who are reading somebody else. This reads what the delivery
+     * webhook stamped on OUR facet from OUR campaigns. A contact with no stamp
+     * does not match, the dated-window lean the CRM dimensions all take.
+     */
+    engagedWithinDays?: number;
+}
+/** One OR branch: an AND-block that may be inverted. */
+export interface DynamicListRuleGroup extends DynamicListDimensions {
+    /**
+     * Invert this branch.
+     *
+     * ⚠️ A branch whose dimensions do not apply to a candidate's silo matches
+     * VACUOUSLY — this rule language skips inapplicable dimensions rather than
+     * failing them — so negating such a branch excludes that silo entirely.
+     * That is the honest consequence of the skip rule rather than a special
+     * case bolted onto it, and every clause the console reads back names the
+     * silo its dimension applies to.
+     */
+    negate?: boolean;
+}
+/** The stored `rule` on a `kind: 'dynamic'` list document. */
+export interface DynamicListRule extends DynamicListDimensions {
+    /**
+     * Which silos to draw from. Empty is not "all" — it matches nobody.
+     *
+     * ⛔ NOT groupable and NOT negatable, and that is a materializer constraint
+     * rather than a modelling preference. `sources` is the SCAN PLAN: it
+     * decides which collections are paged and in what order, and it is what the
+     * resume cursor names when a sweep runs out of budget. A negated source
+     * would mean "every silo except", which is a scan of collections the rule
+     * does not name; a source inside an OR branch would mean two scan plans for
+     * one rule. Either breaks the budget, the cursor, or both.
+     */
+    sources: DynamicListSource[];
+    /** Reuse a saved contact segment's tags and sources. Contacts only. */
+    segmentId?: string;
+    /**
+     * Reuse a saved contacts VIEW's filters (AGL-2617). Contacts only.
+     *
+     * `orgs/{orgId}/crmViews/{viewId}`, a view over the Contacts section.
+     * Resolved once by the materializer into the dimensions this rule
+     * language already has — see {@link dynamicListDimensionsForCrmView} —
+     * and applied to the rule's top-level block the way a segment is: it
+     * always applies, and it is not folded into the OR branches. A view whose
+     * filters this language cannot express narrows to nobody, which is the
+     * same lean a deleted segment takes: a rule must not quietly select more
+     * than the view it reads as.
+     */
+    viewId?: string;
+    /**
+     * Invert the rule's own top-level block — "people who do NOT match these".
+     *
+     * Applies to the dimensions on this object and to the resolved segment. It
+     * does not touch `sources`, and it does not touch {@link any}, which is
+     * ANDed with it and carries its own per-branch negation.
+     */
+    negate?: boolean;
+    /**
+     * OR branches. A candidate must match at least one of them.
+     *
+     * ANDed with the top-level block, so a rule can say "drawn from contacts,
+     * tagged vip, AND (spent over $500 OR ordered at least three times)" — the
+     * shape a flat AND list cannot express and every compared product has.
+     * Absent or empty is no constraint at all, rather than a constraint nothing
+     * satisfies.
+     */
+    any?: DynamicListRuleGroup[];
+}
+/** One person as the materializer reads them out of a silo. */
+export interface DynamicListCandidate {
+    silo: DynamicListSource;
+    email: string;
+    name?: string;
+    createdAtMs?: number | null;
+    /** Contacts only. */
+    tags?: string[];
+    /** Contacts only — the `sources` map, not the rule's `captureSources`. */
+    sources?: Partial<Record<ContactSource, true>>;
+    ordersCount?: number;
+    ltvCents?: number;
+    lastPurchaseAtMs?: number | null;
+    /** `formSubmissions` only. */
+    formName?: string;
+    /**
+     * {@link CAMPAIGN_MEMBER_SILOS} only — the campaigns this row is filed
+     * under.
+     *
+     * Read from a different place in each of the two silos and normalized to one
+     * shape by the scan: a submission carries the field at the top of its
+     * document, a contact carries it inside the reading holder's facet, because
+     * a contact row is shared by every site in the org.
+     */
+    campaignIds?: string[];
+    lastOpenedAtMs?: number | null;
+    lastClickedAtMs?: number | null;
+    /** Lists this person is already a member of, by list id. */
+    listIds?: string[];
+    ownerUid?: string;
+    lifecycleStage?: ContactLifecycleStage;
+    companyId?: string;
+    /** The holder's custom values, keyed by field key. */
+    custom?: Record<string, ContactCustomValue>;
+    /**
+     * When the person last opened or clicked one of the holder's campaigns —
+     * the facet stamp, read the way the fields above are. Absent when the
+     * facet carries none, which the matcher reads as "does not match".
+     */
+    lastEmailEngagementAtMs?: number | null;
+}
+/** A saved segment's filters, resolved by the caller from `segmentId`. */
+export interface ResolvedSegmentFilters {
+    tags?: string[];
+    sources?: ContactSource[];
+}
+/**
+ * Coerces a stored rule to the shape the matcher expects.
+ *
+ * The rule is merchant-authored through the console and read back on a
+ * scheduled sweep, so it arrives as whatever Firestore held. Unknown source
+ * names are dropped rather than tolerated: a typo that fell through would
+ * read as a silo the materializer never scans, and the list would quietly
+ * materialize a smaller set than the rule appears to describe.
+ */
+/**
+ * The most OR branches one rule may carry.
+ *
+ * A bound on the PREDICATE, not on the audience — every branch is evaluated
+ * in memory against a candidate the sweep has already read, so this costs no
+ * Firestore work. It exists because the rule is merchant-authored and a
+ * stored array has no natural end: a thousand branches would be a thousand
+ * evaluations per candidate per sweep.
+ *
+ * ⚠️ Set ABOVE what the console form can produce, and that is a correctness
+ * requirement rather than headroom. The form's "any of these filters" mode
+ * puts each control in a branch of its own, so a reader who fills in every
+ * box authors nineteen, plus one branch per custom-field condition up to
+ * {@link DYNAMIC_LIST_MAX_CUSTOM_CLAUSES} — and dropping a branch NARROWS an
+ * OR, so a cap the form could reach would silently select fewer people than
+ * the sentences above the controls say. The rule editor's spec holds the sum
+ * under this number.
+ */
+export declare const DYNAMIC_LIST_MAX_GROUPS = 40;
+/**
+ * The most lists one dimension may name.
+ *
+ * This one DOES cost reads — a named list is a keyed lookup per candidate per
+ * page — so it is deliberately small, and it is the same number on both arms
+ * so that "in these" and "not in those" cannot be combined into a larger
+ * fan-out than either alone.
+ */
+export declare const DYNAMIC_LIST_MAX_LIST_REFERENCES = 5;
+export declare function normalizeDynamicListRule(stored: unknown): DynamicListRule;
+/**
+ * True when a rule can select nobody no matter what the data holds.
+ *
+ * Worth its own answer because the failure it prevents is silent: an empty
+ * `sources` materializes an empty list, and an empty list reads in the
+ * composer exactly like a rule that simply has not run yet.
+ */
+export declare function dynamicListRuleIsEmpty(rule: DynamicListRule): boolean;
+/**
+ * Does this person match the rule?
+ *
+ * AND across dimensions, OR within one — the same shape `contactMatchesSegment`
+ * uses, so a merchant who has built a segment already knows how this reads.
+ *
+ * On top of that flat block sit two operators, and the whole verdict is:
+ *
+ * ```
+ * silo is in sources
+ *   AND (negate ? NOT top-level block : top-level block)
+ *   AND (any branches ? at least one branch, each with its own negate : true)
+ * ```
+ *
+ * Which is nested AND/OR with negation, arranged so that the only part the
+ * materializer's scan plan depends on — `sources` — sits outside both
+ * operators and cannot be touched by either.
+ *
+ * Dimensions that do not apply to a candidate's silo are SKIPPED rather than
+ * failed. A rule of `sources: ['contacts','siteMembers'], tags: ['vip']` means
+ * "VIP contacts, and site members" — reading `tags` against a member document
+ * that cannot carry tags would make the second source contribute nobody, and
+ * a source that silently contributes nobody is the same defect as a dropped
+ * typo above.
+ *
+ * @param segment filters resolved from `rule.segmentId`, when it names one.
+ * @param view    the dimensions resolved from `rule.viewId`, when it names
+ *                one — see {@link dynamicListDimensionsForCrmView}.
+ * @param nowMs   evaluation instant, injected so a sweep is reproducible.
+ */
+export declare function candidateMatchesDynamicListRule(candidate: DynamicListCandidate, rule: DynamicListRule, options: {
+    segment?: ResolvedSegmentFilters | null;
+    view?: DynamicListDimensions | null;
+    nowMs: number;
+}): boolean;
+/**
+ * Does one stored custom value satisfy one clause?
+ *
+ * Exported because the comparison is the whole meaning of the dimension and
+ * a surface that previews a value against a clause must not carry a second
+ * copy of it. The leans, per operator, because each has to be readable back
+ * as a sentence the merchant can check against their intent:
+ *
+ *  - `eq` — the same value. Text compares case-insensitively and trimmed,
+ *    because a `select` option typed as `Enterprise` and stored as
+ *    `enterprise` is one option; a number and a boolean compare as
+ *    themselves, and a number stored as text still equals the number.
+ *  - `neq` — a value that is set AND differs. A blank does NOT count: a
+ *    merchant excluding one plan is not asking for everyone whose plan was
+ *    never recorded, and `unset` exists for that question.
+ *  - `contains` — text containment, case-insensitive; a blank contains
+ *    nothing.
+ *  - `gt` / `lt` — numeric when both sides parse as numbers, text otherwise.
+ *    Text ordering is what a `date` field stores (ISO dates order as text),
+ *    and a blank is neither greater nor less than anything.
+ *  - `set` / `unset` — presence. `false` and `0` are set; `null`, absent and
+ *    blank text are not.
+ */
+export declare function customValueMatches(value: ContactCustomValue | undefined, clause: DynamicListCustomClause): boolean;
+/**
+ * Does evaluating this rule need the sweeping holder's contact FACET?
+ *
+ * The campaign membership and the four CRM fields all live inside the facet,
+ * which is keyed by the consent group the materializer has to resolve with
+ * one org read. A rule that names none of them pays nothing — the same
+ * opt-in cost `dynamicListRuleNeedsCampaigns` already describes, widened to
+ * every dimension the facet holds so the materializer asks one question
+ * rather than five.
+ */
+export declare function dynamicListRuleNeedsContactFacet(rule: DynamicListRule): boolean;
+/**
+ * Does evaluating this rule need the per-person engagement rollup?
+ *
+ * Asked by the materializer before it spends a keyed read per candidate. A
+ * rule with no engagement clause anywhere pays nothing, which is what keeps
+ * the lookup an opt-in cost rather than a tax on every sweep.
+ */
+export declare function dynamicListRuleNeedsEngagement(rule: DynamicListRule): boolean;
+/**
+ * Does evaluating this rule need a contact's campaign membership?
+ *
+ * Asked by the materializer before it resolves the consent group the facet is
+ * keyed by — one org read, and only for a rule that names a campaign. A
+ * submission's membership is on the row the sweep already paged and costs
+ * nothing either way, so this answers about the CONTACTS silo's extra work.
+ */
+export declare function dynamicListRuleNeedsCampaigns(rule: DynamicListRule): boolean;
+/**
+ * The rule with one list id removed from both membership arms.
+ *
+ * ⛔ A dynamic list whose rule referred to ITSELF would oscillate, and the
+ * oscillation removes people. `notInListIds: [self]` matches everybody on the
+ * first sweep, which enrolls them; on the second sweep they are all members,
+ * so nobody matches, and reconciliation deletes every row the rule created.
+ * The third sweep enrolls them again. Membership would flip on every beat of
+ * the materializing sweep forever, and half of those beats are deletions.
+ *
+ * A self-reference also cannot mean anything useful — the answer depends on
+ * whether the sweep has run yet — so it is dropped rather than refused: a
+ * merchant who picks their own audience gets the rule without that clause,
+ * which is what it would have meant if it meant anything.
+ */
+export declare function dynamicListRuleWithoutListReference(rule: DynamicListRule, listId: string): DynamicListRule;
+/** Every list id this rule refers to, in either direction, de-duplicated. */
+export declare function dynamicListRuleListIds(rule: DynamicListRule): string[];
+/** What a view's filters became — see the section note. */
+export interface DynamicListViewTranslation {
+    dimensions: DynamicListDimensions;
+    /** The clauses this language has no dimension for. Empty means an audience. */
+    unsupported: CrmViewFilterClause[];
+}
+/**
+ * A view's filters as the dimensions of one AND-block, and the clauses
+ * that could not be.
+ *
+ * Every list operator keeps its own meaning across the translation:
+ * `isAnyOf` is the OR the dimension lists already are, an equality is a
+ * list of one, a `contains` on the tag array is one tag matched whole. The
+ * dates read the clause's value as an instant — a day, as the filter bar
+ * writes one — with `after` and `onOrBefore` stepping a day past it the
+ * way the list's own matcher does. A purchase threshold has a floor here
+ * and no ceiling, so `at least` and `over` carry and `under` cannot.
+ */
+export declare function dynamicListDimensionsForCrmView(filters: readonly CrmViewFilterClause[]): DynamicListViewTranslation;
+/**
+ * The rule the sweep PLANS with once a view is resolved: the rule itself
+ * with the view's block beside its branches, so the planners that read
+ * every block — does this need the contact facet, an engagement lookup, a
+ * list membership — see the view's dimensions too. For planning only; the
+ * matcher takes the view as its own option, because a branch is OR and a
+ * view is AND.
+ */
+export declare function dynamicListPlanningRule(rule: DynamicListRule, view: DynamicListDimensions | null): DynamicListRule;