@aglyn/plugins-crm 1.0.0-beta.198 → 1.0.0-beta.200

package/src/lib/constants/contact-filters.js

@@ -1,3 +1,4 @@
+import { _ as _extends } from "@swc/helpers/_/_extends";
 /**
  * @license
  * Copyright 2026 Aglyn LLC
@@ -13,154 +14,179 @@
  * 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 { CRM_CONTACT_VIEW_FIELDS, crmContactCustomColumn } from "@aglyn/aglyn";
-/*
- * Contacts (`orgs/{orgId}/contacts`, read scoped to a host).
+ */ import { CRM_CONTACT_VIEW_FIELDS, CRM_FACET_KEY_ANY_GROUP, crmContactCustomColumn, crmFacetKey, crmFacetKeyValue, EMAIL_STATE_STATUSES } from "@aglyn/aglyn";
+import { CRM_LIST_SEARCH, crmAnyOf, crmClauseValues } from "../model/crm-list-query.js";
+/*==========================================
+ * CONTACTS (`orgs/{orgId}/contacts`, read scoped to a host) — WHAT THE
+ * PANEL OFFERS, AND WHAT THE QUERY ASKS (AGL-3321).
  *
- * The card's listener is `limit(1000)` and stays that way — nobody needs
- * forty thousand rows streamed into a table. What that cap must NOT do is
- * decide what a search can find, and it did: an org with 40,000 contacts
- * searched 1,000 of them and answered "no contacts match" for the rest. The
- * head-count already learned this lesson (AGL-1706, a server aggregate); the
- * search is the same mistake one field over.
+ * Every clause and the search word are on the list's one Firestore query,
+ * newest change first, paged by it. A contact is one row shared by every
+ * holder, and most of what a holder filters by — the owner, the stage, the
+ * sources, the company, the tags, a custom value, whether the person has
+ * bought — lives on that holder's FACET, a path per holder no index can
+ * reach. So every writer stamps `facetKeys` (`crmContactFacetKeys` in
+ * `@aglyn/aglyn`): `{group}:{field}={value}` for each holder's value,
+ * `{group}:{field}` for "has one", and the same under `*` for any holder.
+ * Under a site a facet clause asks the viewing holder's key; at the
+ * organization level, any holder's.
  *
- * ⛔ `marketingConsent`, `ordersCount` and `ltvCents` are written only when
- * they apply, so a `false`/`0` filter would return nothing rather than
- * everyone else. `isNotEmpty` is exact on them and is what the menu offers.
- */ export const CONTACT_LIST_FILTER_FIELDS = [
-    {
-        column: 'name',
-        kind: 'text',
-        path: 'name',
-        lowerPath: 'nameLower',
-        tokensPath: 'nameTokens',
-        reversedPath: 'nameReversed'
-    },
-    {
-        // `normalizeContactEmail` lower-cases before every write, so the stored
-        // value IS its own normalized key.
-        column: 'email',
-        kind: 'text',
-        path: 'email',
-        lowerPath: 'email',
-        presence: 'always'
-    },
+ * What one query holds decides the rest:
+ *
+ *   - ONE array clause. The scope clause (`visibleTo array-contains-any`),
+ *     the search (`searchTokens`), a name word (`nameTokens`), a form
+ *     (`formIds`) and a facet clause (`facetKeys`) all are one. The search
+ *     folds into the scope clause for a reader who may drop it; a facet or
+ *     form clause stands in the scope clause's place for that reader, since
+ *     only a record the viewing holder keeps carries its key. Two of them
+ *     at once is refused by name.
+ *   - ONE range. `updatedAt`, the field the list is ordered by, composes
+ *     with anything; Created and a name or address prefix order the list by
+ *     their own field and so stand alone beside the scope clause
+ *     (`contactSoloClause`), served by the `(visibleTo, field)` composites.
+ *   - equalities (the address, the site, the verdict, "No next activity")
+ *     compose freely, one `(field, updatedAt DESC)` composite each.
+ *
+ * The per-holder FIGURES (orders, lifetime value) live on each holder's
+ * facet, where no range reaches — a top-level `ordersCount` was never
+ * written — so they offer "is not empty" alone: "has bought".
+ *
+ * A collaborator's search is the start of the name (`CONTACT_PREFIX_SEARCH`).
+ *=========================================*/ /**
+ * A word of the canonical name (`nameTokens`), the whole of it, or its start
+ * or end — `nameLower`, which every contact carries, and `nameReversed`.
+ */ const NAME_FIELD = {
+    column: 'name',
+    kind: 'text',
+    path: 'name',
+    lowerPath: 'nameLower',
+    tokensPath: 'nameTokens',
+    reversedPath: 'nameReversed',
+    operators: [
+        'contains',
+        'equals',
+        'startsWith',
+        'endsWith'
+    ]
+};
+/**
+ * The address. `normalizeContactEmail` lower-cases before every write, so the
+ * stored value IS its own normalized key.
+ */ const EMAIL_FIELD = {
+    column: 'email',
+    kind: 'text',
+    path: 'email',
+    lowerPath: 'email',
+    presence: 'always',
+    operators: [
+        'equals',
+        'startsWith'
+    ]
+};
+/** When the person was first captured — a range the list is then ordered by. */ const CREATED_FIELD = {
+    column: CRM_CONTACT_VIEW_FIELDS.createdAt,
+    kind: 'date',
+    path: 'createdAt',
+    presence: 'always',
+    operators: [
+        'is',
+        'after',
+        'onOrAfter',
+        'before',
+        'onOrBefore'
+    ]
+};
+/**
+ * The forms a person came in through — the top-level `formIds` mirror of the
+ * interactions' `formId` (AGL-2612), matched whole and as typed because a
+ * form id is minted with mixed case. The form's own page links here with its
+ * id; nobody types one.
+ */ const FORM_FIELD = {
+    column: 'formIds',
+    kind: 'text',
+    path: 'formIds',
+    tokensPath: 'formIds',
+    verbatimTokens: true,
+    operators: [
+        'contains'
+    ]
+};
+/** What the Filters panel offers on a contact, in the grid's grammar. */ export const CONTACT_LIST_FILTER_FIELDS = [
+    NAME_FIELD,
+    EMAIL_FIELD,
     {
-        /*
-     * Already an array of lower-cased tags, so `contains` is a plain
-     * `array-contains` — the one place the word-level caveat does not apply,
-     * because a tag is matched whole rather than by word prefix.
-     */ column: 'tags',
-        kind: 'text',
+        // A holder's tags, matched whole and case-insensitively.
+        column: CRM_CONTACT_VIEW_FIELDS.tags,
+        kind: 'exact',
         path: 'tags',
-        tokensPath: 'tags',
-        // Ordered by the timestamp the list already sorts on, not by the tag
-        // array — `orderBy` on the same field an `array-contains` matches is a
-        // composite index nobody wants to explain.
-        containsOrderBy: 'updatedAt',
-        // Newest first, as the unfiltered list, which is the composite declared
-        // for it (AGL-3321).
-        containsOrderDirection: 'desc',
-        // `isAnyOf` is a saved segment's "any of these tags" (AGL-2617). The
-        // query cannot serve it — `array-contains-any` is the scope clause's
-        // — so the translator refuses it and the list matches it over the
-        // window, which the caption says.
         operators: [
             'contains',
             'isAnyOf',
             'isNotEmpty'
         ]
     },
-    {
-        /*
-     * The forms a person came in through — the top-level `formIds` mirror
-     * of the interactions' `formId` (AGL-2612), matched whole and as typed
-     * because a form id is minted with mixed case. The form's own page links
-     * here with its id; nobody types one. Ordered by the list's own
-     * timestamp for the reason `tags` is, served by the
-     * `(formIds CONTAINS, updatedAt DESC)` index.
-     *
-     * ⚠️ An `array-contains` on the mirror cannot share a query with the
-     * `visibleTo` scope clause, so the list drops that clause for this one
-     * filter and the rules admit the read to an org-wide member only — the
-     * caveat the company contacts card states, stated again on the list.
-     */ column: 'formIds',
-        kind: 'text',
-        path: 'formIds',
-        tokensPath: 'formIds',
-        verbatimTokens: true,
-        containsOrderBy: 'updatedAt',
-        // Newest first, as the unfiltered list, which is the composite declared
-        // for it (AGL-3321).
-        containsOrderDirection: 'desc',
-        operators: [
-            'contains'
-        ]
-    },
+    FORM_FIELD,
     {
         column: 'hostId',
         kind: 'exact',
         path: 'hostId',
         presence: 'always'
     },
+    // Per-holder figures: "has bought", never a range across holders.
     {
-        column: 'ordersCount',
+        column: CRM_CONTACT_VIEW_FIELDS.orders,
         kind: 'number',
-        path: 'ordersCount'
+        path: 'ordersCount',
+        operators: [
+            'isNotEmpty'
+        ]
     },
     {
-        column: 'ltvCents',
+        column: CRM_CONTACT_VIEW_FIELDS.ltv,
         kind: 'number',
-        path: 'ltvCents'
-    },
-    {
-        column: 'createdAt',
-        kind: 'date',
-        path: 'createdAt',
-        presence: 'always'
+        path: 'ltvCents',
+        operators: [
+            'isNotEmpty'
+        ]
     },
+    CREATED_FIELD,
     {
-        column: 'updatedAt',
+        column: CRM_CONTACT_VIEW_FIELDS.updatedAt,
         kind: 'date',
         path: 'updatedAt',
-        presence: 'always'
+        presence: 'always',
+        operators: [
+            'is',
+            'after',
+            'onOrAfter',
+            'before',
+            'onOrBefore'
+        ]
     },
     /*
-   * When the earliest open task is due (AGL-2661) — window-only, because
-   * the value is on the SHARED row but a record written before the field
-   * existed has none, and Firestore cannot query for absence. `nullable`
-   * is honest: the writer stores `null` for nothing scheduled, and the
-   * matcher reads absent the same way, so "is empty" is the "No next
-   * activity" filter over the loaded window.
+   * "No next activity" (AGL-2661): `nextTaskAtMs == null`, which every
+   * contact carries from its creation until a task is scheduled against it.
    */ {
         column: 'nextTaskAtMs',
         kind: 'date',
         path: 'nextTaskAtMs',
-        windowOnly: true,
-        presence: 'nullable'
+        presence: 'nullable',
+        storedAs: 'millis',
+        operators: [
+            'isEmpty'
+        ]
     },
     /*
-   * THE FACET FIELDS (AGL-2617) — window-only, every one of them.
-   *
-   * An owner, a stage, a company and the capture sources live on the
-   * viewing group's facet of the shared contact row, and a facet path is
-   * per group: a `where` on it would need an index per group, and the
-   * translator would send a scoped member a query the rules deny. So these
-   * are declared for the menu and for a saved view, matched over the loaded
-   * window against the flattened row (`ContactRecord` carries each at the
-   * top), and never put on a query — `windowOnly` is what holds that line.
-   * The paths are the ROW'S, which is what the matcher reads.
-   *
-   * The values are picked, not typed — a uid from the roster, a stage from
-   * the fixed list, a source from its labels, a company from the picker —
-   * so `equals` and `isAnyOf` are what they offer; the section supplies
-   * the choices. The column names are the contract `CRM_CONTACT_VIEW_FIELDS`
-   * states, because the dynamic-list translator reads a view by them.
+   * THE FACET FIELDS (AGL-2617). The values are picked, not typed — a uid
+   * from the roster, a stage from the fixed list, a source from its labels,
+   * a company from the picker — so `equals` and `isAnyOf` are what they
+   * offer; the section supplies the choices. The column names are the
+   * contract `CRM_CONTACT_VIEW_FIELDS` states, because the dynamic-list
+   * translator reads a view by them. The paths are the flattened ROW'S.
    */ {
         column: CRM_CONTACT_VIEW_FIELDS.owner,
         kind: 'exact',
         path: 'ownerUid',
-        windowOnly: true,
         operators: [
             'equals',
             'isAnyOf',
@@ -171,7 +197,6 @@
         column: CRM_CONTACT_VIEW_FIELDS.stage,
         kind: 'exact',
         path: 'lifecycleStage',
-        windowOnly: true,
         operators: [
             'equals',
             'isAnyOf',
@@ -184,7 +209,6 @@
         kind: 'exact',
         path: 'sources',
         keysOf: true,
-        windowOnly: true,
         operators: [
             'equals',
             'isAnyOf'
@@ -194,21 +218,19 @@
         column: CRM_CONTACT_VIEW_FIELDS.company,
         kind: 'exact',
         path: 'companyId',
-        windowOnly: true,
         operators: [
             'equals',
             'isNotEmpty'
         ]
     },
     /*
-   * The verdict on the address (AGL-3245) — window-only, on the shared row,
-   * and `nullable` because most records carry none: "is empty" is the
-   * filter for people nothing has been said about.
+   * The verdict on the address (AGL-3245), asked through `emailStatus` —
+   * `none` for a person nothing has been said about, which is what "is
+   * empty" asks.
    */ {
         column: 'emailState',
         kind: 'exact',
         path: 'emailState.status',
-        windowOnly: true,
         presence: 'nullable',
         operators: [
             'equals',
@@ -219,15 +241,11 @@
     }
 ];
 /**
- * One filter field per active custom contact field (AGL-2617).
- *
- * A custom value lives under the facet's `custom` map, so every one is
- * window-only for the reason the facet fields above are, and its column is
- * the one the table shows it under — `crmContactCustomColumn(key)` — so a
- * clause and a column agree on the name and a saved view's columns and
- * filters name the same thing. The kind follows the definition's type, and
- * `nullable` is how a cleared value is stored, which is what makes both
- * empty operators honest here.
+ * One filter field per active custom contact field (AGL-2617). A custom
+ * value lives under the holder's `custom` map, so it is asked through the
+ * holder's facet key: equality on a picked, typed or ticked value, and
+ * "is not empty". Its column is the one the table shows it under —
+ * `crmContactCustomColumn(key)` — so a clause and a column agree on the name.
  */ export function contactCustomFilterFields(definitions) {
     return definitions.filter((definition)=>!definition.retiredAt).map((definition)=>{
         const column = crmContactCustomColumn(definition.key);
@@ -238,35 +256,34 @@
                     column,
                     kind: 'number',
                     path,
-                    windowOnly: true,
-                    presence: 'nullable'
+                    operators: [
+                        '=',
+                        'isNotEmpty'
+                    ]
                 };
             case 'date':
                 return {
                     column,
                     kind: 'date',
                     path,
-                    windowOnly: true,
-                    presence: 'nullable'
+                    operators: [
+                        'isNotEmpty'
+                    ]
                 };
             case 'checkbox':
                 return {
                     column,
                     kind: 'boolean',
-                    path,
-                    windowOnly: true
+                    path
                 };
             case 'select':
                 return {
                     column,
                     kind: 'exact',
                     path,
-                    windowOnly: true,
-                    presence: 'nullable',
                     operators: [
                         'equals',
                         'isAnyOf',
-                        'isEmpty',
                         'isNotEmpty'
                     ]
                 };
@@ -275,13 +292,9 @@
                     column,
                     kind: 'text',
                     path,
-                    windowOnly: true,
-                    presence: 'nullable',
+                    lowerPath: path,
                     operators: [
-                        'contains',
                         'equals',
-                        'startsWith',
-                        'isEmpty',
                         'isNotEmpty'
                     ]
                 };
@@ -314,5 +327,224 @@
     [CRM_CONTACT_VIEW_FIELDS.company]: 'Company',
     emailState: 'Email'
 };
+/*------------------------------------------
+ * THE QUERY THE CONTACTS LIST RUNS.
+ *-----------------------------------------*/ /** The list's one order: newest change first. */ export const CONTACT_LIST_SORTS = [
+    {
+        path: 'updatedAt',
+        direction: 'desc'
+    }
+];
+/** The stored array a facet clause is asked of. */ export const CONTACT_FACET_KEYS_PATH = 'facetKeys';
+/** The fields the Contacts query asks — each a stored field, as named. */ export const CONTACT_QUERY_FIELDS = [
+    NAME_FIELD,
+    EMAIL_FIELD,
+    FORM_FIELD,
+    CREATED_FIELD,
+    {
+        column: 'hostId',
+        kind: 'exact',
+        path: 'hostId',
+        presence: 'always'
+    },
+    {
+        column: 'updatedAt',
+        kind: 'date',
+        path: 'updatedAt',
+        presence: 'always',
+        operators: [
+            'is',
+            'after',
+            'onOrAfter',
+            'before',
+            'onOrBefore'
+        ]
+    },
+    {
+        column: 'nextTaskAtMs',
+        kind: 'date',
+        path: 'nextTaskAtMs',
+        presence: 'nullable',
+        storedAs: 'millis',
+        operators: [
+            'isEmpty'
+        ]
+    },
+    {
+        column: 'emailStatus',
+        kind: 'exact',
+        path: 'emailStatus',
+        operators: [
+            'equals',
+            'isAnyOf'
+        ]
+    },
+    {
+        column: CONTACT_FACET_KEYS_PATH,
+        kind: 'exact',
+        path: CONTACT_FACET_KEYS_PATH,
+        tokensPath: CONTACT_FACET_KEYS_PATH,
+        operators: [
+            'contains',
+            'isAnyOf'
+        ]
+    }
+];
+export const CONTACT_LIST_DECLARATION = {
+    fields: CONTACT_QUERY_FIELDS,
+    sorts: CONTACT_LIST_SORTS,
+    search: CRM_LIST_SEARCH
+};
+/** The grid fields a stored clause passes to the query unchanged. */ const AS_STORED = new Set([
+    'name',
+    'email',
+    'formIds',
+    'hostId',
+    'createdAt',
+    'updatedAt',
+    'nextTaskAtMs'
+]);
+/**
+ * The ranges that stand ALONE beside the scope clause: Created and a name
+ * or address prefix each order the list by their own field, which the
+ * `(visibleTo, field)` composites serve and nothing beside them. Updated is
+ * not one: the list is ordered by it already, so it composes freely.
+ */ export function contactSoloClause(clause) {
+    if (clause.field === 'createdAt') return true;
+    if (clause.field === 'name') return clause.op === 'startsWith' || clause.op === 'endsWith';
+    return clause.field === 'email' && clause.op === 'startsWith';
+}
+/**
+ * A collaborator's search (see `prefixSearch` in `useCrmListQuery`): the
+ * start of the contact's name, beside the scope clause.
+ */ export const CONTACT_PREFIX_SEARCH = {
+    field: NAME_FIELD,
+    notice: 'Search matches the start of a contact’s name for access limited to specific sites.'
+};
+/** The facet field each grid column is keyed under. */ const FACET_FIELDS = {
+    [CRM_CONTACT_VIEW_FIELDS.owner]: 'owner',
+    [CRM_CONTACT_VIEW_FIELDS.stage]: 'stage',
+    [CRM_CONTACT_VIEW_FIELDS.source]: 'source',
+    [CRM_CONTACT_VIEW_FIELDS.company]: 'company',
+    [CRM_CONTACT_VIEW_FIELDS.tags]: 'tag',
+    [CRM_CONTACT_VIEW_FIELDS.orders]: 'orders',
+    [CRM_CONTACT_VIEW_FIELDS.ltv]: 'ltv'
+};
+/** Why a reader whose access is some sites cannot filter by a holder's field. */ const LIMITED_ACCESS = 'your access is limited to specific sites, which this filter cannot be combined with — an organization administrator can use it';
+/** The facet field a grid column names, or null for one that is not a facet field. */ function facetFieldOf(column) {
+    if (FACET_FIELDS[column]) return FACET_FIELDS[column];
+    if (column.startsWith(CRM_CONTACT_VIEW_FIELDS.custom)) {
+        return `custom.${column.slice(CRM_CONTACT_VIEW_FIELDS.custom.length)}`;
+    }
+    return null;
+}
+/**
+ * One grid clause as the clause the Contacts query asks — see the block at
+ * the top. A clause a query cannot serve for this reader is refused by
+ * name, never matched over the rows a page loaded.
+ */ export function contactQueryClause(clause, reader) {
+    var _reader_groupId;
+    if (AS_STORED.has(clause.field)) {
+        if (clause.field === 'formIds' && !reader.foldsScope) return {
+            refused: LIMITED_ACCESS
+        };
+        return {
+            field: clause.field,
+            op: clause.op,
+            value: clause.value
+        };
+    }
+    if (clause.field === 'emailState') {
+        if (clause.op === 'isEmpty') return {
+            field: 'emailStatus',
+            op: 'equals',
+            value: 'none'
+        };
+        if (clause.op === 'isNotEmpty') return crmAnyOf('emailStatus', EMAIL_STATE_STATUSES);
+        const values = crmClauseValues(clause);
+        if (values.some((value)=>!EMAIL_STATE_STATUSES.includes(value))) {
+            return {
+                refused: 'pick one of the choices'
+            };
+        }
+        return crmAnyOf('emailStatus', values);
+    }
+    const facet = facetFieldOf(clause.field);
+    if (!facet) return {
+        refused: 'this list does not filter by that'
+    };
+    if (!reader.foldsScope) return {
+        refused: LIMITED_ACCESS
+    };
+    const group = (_reader_groupId = reader.groupId) != null ? _reader_groupId : CRM_FACET_KEY_ANY_GROUP;
+    if (clause.op === 'isNotEmpty') {
+        return {
+            field: CONTACT_FACET_KEYS_PATH,
+            op: 'contains',
+            value: crmFacetKey(group, facet)
+        };
+    }
+    const keys = [];
+    for (const value of crmClauseValues(clause)){
+        const key = crmFacetKeyValue(clause.op === '=' ? Number(value) : value);
+        if (key === null) return {
+            refused: 'no value yet'
+        };
+        keys.push(crmFacetKey(group, facet, key));
+    }
+    const asked = crmAnyOf(CONTACT_FACET_KEYS_PATH, keys);
+    // One key is an `array-contains`; several, an `array-contains-any`.
+    return 'refused' in asked || asked.op === 'isAnyOf' ? asked : _extends({}, asked, {
+        op: 'contains'
+    });
+}
+/**
+ * Whether an asked clause stands in for the scope clause: a facet key of
+ * the viewing holder, which only a record that holder keeps carries, or a
+ * form, which only its site's captures carry.
+ */ export function contactClauseImpliesScope(groupId) {
+    return (clause)=>{
+        if (clause.field === 'formIds') return true;
+        if (clause.field !== CONTACT_FACET_KEYS_PATH || !groupId) return false;
+        return crmClauseValues(clause).every((key)=>key.startsWith(`${groupId}:`));
+    };
+}
+/**
+ * The query shapes the Contacts list can send, as declarations the index
+ * pin enumerates (AGL-3321): the list's own, without its solo ranges, whose
+ * every equality rides `(field, updatedAt DESC)`; and each solo range beside
+ * the scope clause alone.
+ */ export function contactIndexShapes() {
+    const soloOps = new Set([
+        'startsWith',
+        'endsWith'
+    ]);
+    const main = _extends({}, CONTACT_LIST_DECLARATION, {
+        fields: CONTACT_QUERY_FIELDS.filter((field)=>field !== CREATED_FIELD).map((field)=>field.operators ? _extends({}, field, {
+                operators: field.operators.filter((op)=>!soloOps.has(op))
+            }) : field)
+    });
+    const solo = {
+        fields: [
+            _extends({}, NAME_FIELD, {
+                operators: [
+                    'startsWith',
+                    'endsWith'
+                ]
+            }),
+            _extends({}, EMAIL_FIELD, {
+                operators: [
+                    'startsWith'
+                ]
+            }),
+            CREATED_FIELD
+        ],
+        sorts: []
+    };
+    return [
+        main,
+        solo
+    ];
+}
 
 //# sourceMappingURL=contact-filters.js.map