@aglyn/plugins-crm 1.0.0-beta.217 → 1.0.0-beta.219

package/src/lib/model/crm-sharing.d.ts

@@ -0,0 +1,333 @@
+/**
+ * @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.
+ */
+/**
+ * CRM SHARING FOR MULTI-BRAND ORGS (AGL-3336).
+ *
+ * An org manager shares a lead, a contact, a company or a deal with other
+ * sites — by hand, from the record or a list's bulk bar, or by a SHARING
+ * RULE that applies to every record it matches, now and later. The model is
+ * Salesforce's three layers:
+ *
+ * 1. the org-wide default — the consent-group scope a record is captured
+ *    with (`consentGroupScope`), untouched by anything here;
+ * 2. sharing rules — `crm.sharingRules` on the org document;
+ * 3. manual shares — per record, per target.
+ *
+ * ## One field is enforced, so one field is widened
+ *
+ * Both enforcement layers read `visibleTo`: the rules with `hasAny`, every
+ * list with `array-contains-any`. A share therefore ADDS its tokens to
+ * `visibleTo`, which is what puts the record on the target site's lists as a
+ * real query — no second field, no second index, no loaded-window match.
+ * `'org'` is the token for "all sites", and it covers a site created later
+ * with nothing to recompute, because every site's read set carries it.
+ *
+ * ## …and the sources stay distinguishable
+ *
+ * The record keeps its grants under `sharing` (`SCOPE_GRANTS_FIELD` in
+ * core): one grant per rule and one per hand-shared target, and `added`,
+ * the tokens the grants put on `visibleTo` that were not there already.
+ * The record's own scope — its HELD tokens — is `visibleTo` without
+ * `added`, so taking a grant away removes only what grants alone
+ * contributed, and never a consent-group token. A token a site later
+ * captures the person on is held from then on: the capturing sites
+ * (`hostId`, `capturedByHostIds`) are never counted as added.
+ *
+ * ## Visibility is not consent, and not write access
+ *
+ * Nothing here reads or writes a consent entry. A site a record is shared
+ * with sees it; it holds no basis to market to the person, and the
+ * audience paths read `heldByHost`, not `visibleTo`. Write access is its
+ * own field, `writeTo`, present only on a shared record: the held tokens
+ * and the tokens of grants whose access is `edit`. The Firestore rules and
+ * the CRM's routes check it; a read-only grant is the default.
+ */
+import type { ScopeToken } from '@aglyn/aglyn';
+/** The four record types a share or a rule applies to, by their collection. */
+export declare const CRM_SHARING_OBJECTS: readonly ["leads", "contacts", "companies", "deals"];
+export type CrmSharingObject = (typeof CRM_SHARING_OBJECTS)[number];
+export declare function isCrmSharingObject(value: unknown): value is CrmSharingObject;
+/** How each object reads in a sentence. */
+export declare const CRM_SHARING_OBJECT_LABELS: Readonly<Record<CrmSharingObject, {
+    one: string;
+    many: string;
+}>>;
+/** What a target site may do with a shared record. Read-only unless a grant says edit. */
+export type CrmShareAccess = 'read' | 'edit';
+export declare function isCrmShareAccess(value: unknown): value is CrmShareAccess;
+/** Where a grant came from. */
+export type CrmShareSource = 'manual' | 'rule';
+/** One grant on one record. */
+export interface CrmShareGrant {
+    source: CrmShareSource;
+    /** The sites it shares with: `['org']` for all sites, else host tokens. */
+    tokens: ScopeToken[];
+    access: CrmShareAccess;
+    /** The rule behind a `rule` grant. */
+    ruleId?: string;
+    /** Who shared it by hand, as they were named at the time. */
+    byUid?: string;
+    byName?: string;
+    /** When the grant was made. */
+    atMs: number;
+}
+/** `sharing` on a record — see the module note. */
+export interface CrmRecordSharing {
+    /** Keyed by {@link manualGrantKey} or {@link ruleGrantKey}. */
+    grants: Record<string, CrmShareGrant>;
+    /** Every token any grant names — the record's shares, however held. */
+    tokens: ScopeToken[];
+    /** The tokens the grants ADDED to `visibleTo` — see `heldScopeTokens`. */
+    added: ScopeToken[];
+    /** The rules holding a grant here, so a rule's removal can find its records. */
+    ruleIds: string[];
+    /**
+     * The held tokens of a record shared with all sites, and nothing
+     * otherwise. `array-contains` on it answers "is this record shared with
+     * everyone AND held by site X" — the one question `added` alone cannot,
+     * since a query takes a single array clause.
+     */
+    orgWideHeldBy: ScopeToken[];
+}
+/** The record field its grants live under — the core's name for it. */
+export declare const CRM_SHARING_FIELD = "sharing";
+/** The record field naming who may WRITE it, present only while it is shared. */
+export declare const CRM_WRITE_SCOPE_FIELD = "writeTo";
+/** The array field a rule's removal queries. */
+export declare const CRM_SHARING_RULE_IDS_PATH = "sharing.ruleIds";
+/** A hand share is one grant per target, so each is unshared on its own. */
+export declare function manualGrantKey(token: string): string;
+export declare function ruleGrantKey(ruleId: string): string;
+/** A record's grants, cleaned; `{}` for a record never shared. */
+export declare function readRecordGrants(record: Readonly<Record<string, unknown>> | null | undefined): Record<string, CrmShareGrant>;
+/**
+ * The sites that captured or created the record. Their tokens are HELD,
+ * whatever `added` says: a person shared to site B and later captured on B
+ * is B's own from then on, and unsharing must not hide them from B.
+ */
+export declare function recordHolderHostIds(record: Readonly<Record<string, unknown>>): string[];
+/**
+ * The record's own scope: `visibleTo` less what grants added, its capturing
+ * sites kept — the core's `heldScopeTokens`, as scope tokens.
+ */
+export declare function recordHeldScope(record: Readonly<Record<string, unknown>>): ScopeToken[];
+export interface CrmSharingPlan {
+    visibleTo: ScopeToken[];
+    /** `null` removes the field: an unshared record writes by `visibleTo`. */
+    writeTo: ScopeToken[] | null;
+    /** `null` removes the field. */
+    sharing: CrmRecordSharing | null;
+}
+/**
+ * The fields a record carries under `grants`.
+ *
+ * A grant naming a token the record already holds adds nothing, and a
+ * record held org-wide adds nothing at all — every site sees it already, so
+ * a share there would only make a later unshare look like it hid something.
+ * The token order is the held scope first and the additions after it, so an
+ * unchanged record plans the `visibleTo` it has.
+ */
+export declare function planRecordSharing(record: Readonly<Record<string, unknown>>, grants: Readonly<Record<string, CrmShareGrant>>): CrmSharingPlan;
+/** Whether writing `plan` would change what the record stores. */
+export declare function sharingPlanChanges(record: Readonly<Record<string, unknown>>, plan: CrmSharingPlan): boolean;
+/** The org document path the rules are stored under. */
+export declare const CRM_SHARING_RULES_PATH = "crm.sharingRules";
+/** A workspace keeps at most this many. */
+export declare const CRM_SHARING_RULES_MAX = 20;
+/** At most this many values per criterion. */
+export declare const CRM_SHARING_CRITERION_MAX = 20;
+/**
+ * Which records a rule matches, beyond the object and the capturing site.
+ * AND across the keys, OR within one; an absent or empty key matches
+ * everything.
+ */
+export interface CrmSharingCriteria {
+    /** A lead's or a contact's lead source, by label. */
+    leadSources?: string[];
+    /** Any of these tags (lead, contact, company). */
+    tags?: string[];
+    /** Filed under any of these campaigns (lead, contact). */
+    campaignIds?: string[];
+    /** A lead's status, a contact's lifecycle stage, or a deal's stage id. */
+    stages?: string[];
+    /** Owned by any of these members. */
+    ownerUids?: string[];
+}
+export declare const CRM_SHARING_CRITERIA_KEYS: readonly ["leadSources", "tags", "campaignIds", "stages", "ownerUids"];
+/** Which criteria an object's records can answer. */
+export declare const CRM_SHARING_CRITERIA_FOR: Readonly<Record<CrmSharingObject, readonly (keyof CrmSharingCriteria)[]>>;
+/** Where a rule's recompute stands. */
+export interface CrmSharingRuleRun {
+    status: 'running' | 'done' | 'failed';
+    /** What the run does: apply the rule everywhere, or take it away. */
+    mode: 'apply' | 'remove';
+    /** Records examined. */
+    processed: number;
+    /** Records whose sharing changed. */
+    changed: number;
+    /** The last record id an `apply` run examined, to continue after. */
+    cursor?: string | null;
+    startedAtMs: number;
+    finishedAtMs?: number;
+    error?: string;
+}
+export interface CrmSharingRule {
+    id: string;
+    name: string;
+    object: CrmSharingObject;
+    /** Off keeps the rule and takes away what it granted. */
+    enabled: boolean;
+    /** Records captured or created on any of these sites; empty is every site. */
+    sourceHostIds: string[];
+    criteria: CrmSharingCriteria;
+    /** `['org']` for all sites, including sites added later; else host tokens. */
+    targets: ScopeToken[];
+    access: CrmShareAccess;
+    /** Being deleted: its grants are being removed, and it matches nothing. */
+    deleting?: boolean;
+    createdByUid?: string;
+    createdAtMs: number;
+    updatedAtMs: number;
+    run?: CrmSharingRuleRun;
+}
+/** One rule as stored, cleaned, or null when it cannot be applied. */
+export declare function readCrmSharingRule(raw: unknown): CrmSharingRule | null;
+/** The org's sharing rules, in their stored order. */
+export declare function readCrmSharingRules(org: Readonly<Record<string, unknown>> | null | undefined): CrmSharingRule[];
+/** The rules that grant anything now: enabled, and not being deleted. */
+export declare function activeSharingRules(rules: readonly CrmSharingRule[], object?: CrmSharingObject): CrmSharingRule[];
+/**
+ * A share's targets, cleaned for storage: `['org']` when all sites are
+ * named, else the host tokens, capped. `null` when nothing is left.
+ */
+export declare function normalizeShareTargets(tokens: readonly string[]): ScopeToken[] | null;
+/** Targets from a request: `'all'`, or a list of host ids. */
+export declare function shareTargetsFrom(input: unknown): ScopeToken[] | null;
+export interface CrmSharingFacts {
+    hostIds: string[];
+    leadSources: string[];
+    tags: string[];
+    campaignIds: string[];
+    stages: string[];
+    ownerUids: string[];
+}
+/**
+ * The facts a rule's criteria are matched against. A contact keeps each
+ * holder's working fields in its own facet, so a contact answers with the
+ * union of its facets: a rule about "contacts tagged vip" matches a person
+ * any holder tagged.
+ */
+export declare function crmSharingFacts(object: CrmSharingObject, record: Readonly<Record<string, unknown>>): CrmSharingFacts;
+/** Whether a rule shares this record. */
+export declare function crmSharingRuleMatches(rule: CrmSharingRule, object: CrmSharingObject, record: Readonly<Record<string, unknown>>): boolean;
+/**
+ * The grants a record should carry: its hand shares as they are, and one
+ * grant per active rule that matches it now. A rule grant already present
+ * keeps its date, so re-evaluating an unchanged record writes nothing.
+ *
+ * A rule grant whose rule is not among `rules` is dropped — the caller
+ * passes every active rule of the org, so a rule absent from them has been
+ * switched off or deleted.
+ */
+export declare function evaluateRecordGrants(object: CrmSharingObject, record: Readonly<Record<string, unknown>>, rules: readonly CrmSharingRule[], atMs: number): Record<string, CrmShareGrant>;
+/** The hand shares after sharing with `targets`, by `by`. */
+export declare function withManualShares(grants: Readonly<Record<string, CrmShareGrant>>, targets: readonly ScopeToken[], access: CrmShareAccess, by: {
+    uid: string;
+    name?: string | null;
+}, atMs: number): Record<string, CrmShareGrant>;
+/** The hand shares after unsharing `targets`. Rule grants are the rule's to take away. */
+export declare function withoutManualShares(grants: Readonly<Record<string, CrmShareGrant>>, targets: readonly string[]): Record<string, CrmShareGrant>;
+/**
+ * Whether a caller holding `tokens` may write the record: `writeTo` on a
+ * shared record, else `visibleTo` — the Firestore rules' own predicate.
+ */
+export declare function crmRecordWritableBy(record: Readonly<Record<string, unknown>>, tokens: readonly string[]): boolean;
+/** How a record reached a site that sees it only through a share. */
+export interface CrmShareChip {
+    source: CrmShareSource;
+    access: CrmShareAccess;
+    /** The member who shared it by hand. */
+    byName?: string;
+    /** The rule that shared it. */
+    ruleId?: string;
+    /** Shared with every site. */
+    allSites: boolean;
+}
+/**
+ * Why a site seeing this record sees it, when the answer is a share — or
+ * `null` when the site holds it (or cannot see it at all). `hostIds` are
+ * the viewing group's sites; at the organization level there is none.
+ */
+export declare function crmShareChipFor(record: Readonly<Record<string, unknown>> | null | undefined, hostIds: readonly string[]): CrmShareChip | null;
+/** The chip's words: "Shared by Dana", "Shared by rule Brand A leads". */
+export declare function crmShareChipLabel(chip: CrmShareChip, rules?: readonly Pick<CrmSharingRule, 'id' | 'name'>[]): string;
+/** One line of a record's Sharing card. */
+export type CrmSharingLine = {
+    kind: 'held';
+    hostIds: string[];
+    allSites: boolean;
+} | {
+    kind: 'manual';
+    key: string;
+    token: ScopeToken;
+    access: CrmShareAccess;
+    byName?: string;
+    atMs: number;
+} | {
+    kind: 'rule';
+    key: string;
+    ruleId: string;
+    tokens: ScopeToken[];
+    access: CrmShareAccess;
+    atMs: number;
+};
+/**
+ * Where a record is visible and why: the sites that hold it (its consent
+ * group or its creating site), then one line per hand share, then one per
+ * rule. The held line is never unsharable; a hand share is, in one click.
+ */
+export declare function describeRecordSharing(record: Readonly<Record<string, unknown>> | null | undefined): CrmSharingLine[];
+/** "All sites", a site's name, or "N sites". */
+export declare function describeShareTargets(tokens: readonly string[], siteName: (hostId: string) => string): string;
+/** A rule as one sentence of its "which records" half. */
+export declare function describeSharingRuleScope(rule: Pick<CrmSharingRule, 'object' | 'sourceHostIds' | 'criteria'>, siteName: (hostId: string) => string, labels?: {
+    owner?: (uid: string) => string;
+    stage?: (id: string) => string;
+}): string;
+/** `POST /api/crm/sharing` — every sharing act, by `action`. */
+export declare const CRM_SHARING_ROUTE: "crm/sharing";
+export declare const crmSharingRouteUrl: () => string;
+/** Records one share or unshare may name. */
+export declare const CRM_SHARING_IDS_MAX = 200;
+export type CrmSharingAction = 'sites' | 'share' | 'unshare' | 'evaluate' | 'rule-save' | 'rule-delete' | 'rule-continue';
+export interface CrmSharingSite {
+    id: string;
+    name: string;
+}
+export interface CrmSharingResponse {
+    ok: true;
+    /** `sites`: the org's sites, by name. */
+    sites?: CrmSharingSite[];
+    /** `share`/`unshare`/`evaluate`: records whose sharing changed. */
+    changed?: number;
+    /** Records named that could not be found. */
+    missing?: number;
+    /** The rule a rule action saved or ran. */
+    rule?: CrmSharingRule | null;
+    /** Whether a rule run has more to do (`rule-continue` again). */
+    more?: boolean;
+}