@aglyn/plugins-crm 1.0.0-beta.218 → 1.0.0-beta.220

package/src/lib/server/crm-records-meter.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/crm/src/lib/server/crm-records-meter.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport { checkCrmRecordsQuota } from '@aglyn/aglyn/app-utils/plan-entitlements'\nimport type {\n  PluginUsageMeterContext,\n  PluginUsageMeterReading,\n} from '@aglyn/aglyn/plugin-manager/plugin-usage-meters'\nimport { firebaseAdmin } from '@aglyn/tenant-data-admin'\n\n/**\n * The CRM's month in the usage sweep: the records band (AGL-890, widened in\n * AGL-2611) — contacts, companies and deals, counted together across the\n * workspace and measured against the ONE band `contactsPerHost` names.\n *\n * ## A stock, read at the end of the month it bills (AGL-2399)\n *\n * Records are a LEVEL, not a total: the count read now describes now. The\n * closed-month sweep runs after the month is over, so it bills the last\n * reading taken INSIDE the month — the period-end stamp each in-progress\n * sweep writes — and falls back to measuring only when no such reading\n * exists. The in-progress sweep stamps its own reading as the period-end one,\n * and a closed sweep never stamps, so every re-run of a closed month reads\n * the same input and bills the same amount.\n *\n * The records trio is resolved as a unit, so `contactsCount + companiesCount\n * + dealsCount === crmRecordsCount` on every row. A closed month with a\n * contacts reading but no records reading was measured on contacts alone,\n * before the band was widened, and bills the other two as nothing — the\n * permissive direction, and the only one the period-end rule permits. The\n * persisted names still say \"contacts\" because every reader of the rollup\n * keys on them; the quantity behind them is the records band.\n *\n * ## Withheld while the CRM is dark (AGL-1604)\n *\n * `release_crm` gates the console CRM. Records still accrue while it is off —\n * capture and `GET /v1/contacts` keep running — and nobody may be charged for\n * what they cannot reach, so the overage is withheld rather than billed, and\n * recorded as withheld so the month is legible. The COUNT is written always:\n * it is an entitlement input, and only the figure that reaches the invoice\n * moves with the flag.\n */\nexport async function measureCrmRecords(\n  context: PluginUsageMeterContext,\n): Promise<PluginUsageMeterReading> {\n  const orgRef = firebaseAdmin.app().firestore().collection('orgs').doc(context.orgId)\n  // Three aggregate counts, one per collection the band counts. Tasks and\n  // activities are not counted, deliberately.\n  const [contactsSnap, companiesSnap, dealsSnap] = await Promise.all([\n    orgRef.collection('contacts').count().get(),\n    orgRef.collection('companies').count().get(),\n    orgRef.collection('deals').count().get(),\n  ])\n  const contactsCountAtSweep = Number(contactsSnap.data().count ?? 0)\n  const companiesCountAtSweep = Number(companiesSnap.data().count ?? 0)\n  const dealsCountAtSweep = Number(dealsSnap.data().count ?? 0)\n  // The band's own figure: the three summed, measured at the same instant, so\n  // the total and its parts describe one moment.\n  const crmRecordsCountAtSweep =\n    contactsCountAtSweep + companiesCountAtSweep + dealsCountAtSweep\n\n  /**\n   * A reading an earlier sweep stamped, or `null` when there is none to\n   * trust. A missing field, a NaN or a negative falls back to measuring and\n   * never bills as zero: billing zero on a malformed field would forfeit the\n   * overage silently and look exactly like a customer inside the band.\n   */\n  const stamped = (field: string): number | null => {\n    const value = Number(context.previous[field])\n    return Number.isFinite(value) && value >= 0 ? value : null\n  }\n  const contactsAtPeriodEnd = stamped('contactsCountAtPeriodEnd')\n  const crmRecordsAtPeriodEnd = stamped('crmRecordsCountAtPeriodEnd')\n  const companiesAtPeriodEnd = stamped('companiesCountAtPeriodEnd')\n  const dealsAtPeriodEnd = stamped('dealsCountAtPeriodEnd')\n\n  const { closed } = context\n  const contactsCount =\n    closed && contactsAtPeriodEnd !== null ? contactsAtPeriodEnd : contactsCountAtSweep\n  const [crmRecordsCount, companiesCount, dealsCount] =\n    closed && crmRecordsAtPeriodEnd !== null\n      ? [crmRecordsAtPeriodEnd, companiesAtPeriodEnd ?? 0, dealsAtPeriodEnd ?? 0]\n      : closed && contactsAtPeriodEnd !== null\n        ? [contactsAtPeriodEnd, 0, 0]\n        : [crmRecordsCountAtSweep, companiesCountAtSweep, dealsCountAtSweep]\n\n  // The band's verdict on the SUM, unchanged by the flag — the count and the\n  // quota are what entitlement resolution reads, and only the figure that\n  // reaches the invoice moves.\n  const quota = checkCrmRecordsQuota(context.org as never, crmRecordsCount)\n  const billed = context.releaseFlagOn('release_crm')\n  const overageUsd = billed ? quota.overageMonthlyUsd : 0\n\n  return {\n    fields: {\n      contactsCount,\n      crmRecordsCount,\n      companiesCount,\n      dealsCount,\n      // What this run measured, beside the billed basis: the difference is\n      // how much a month moved by being measured inside it.\n      contactsCountAtSweep,\n      crmRecordsCountAtSweep,\n      contactsOverageUsd: overageUsd,\n      contactsOverageBilled: billed,\n      contactsOverageWithheldUsd: billed ? 0 : quota.overageMonthlyUsd,\n    },\n    // Stamped together, so a closed sweep reads the total and its parts back\n    // as one unit taken on one day.\n    periodEndFields: {\n      contactsCountAtPeriodEnd: contactsCountAtSweep,\n      crmRecordsCountAtPeriodEnd: crmRecordsCountAtSweep,\n      companiesCountAtPeriodEnd: companiesCountAtSweep,\n      dealsCountAtPeriodEnd: dealsCountAtSweep,\n    },\n    billedUsd: overageUsd,\n    periodEndBasis:\n      closed && (contactsAtPeriodEnd !== null || crmRecordsAtPeriodEnd !== null),\n  }\n}\n"],"names":["checkCrmRecordsQuota","firebaseAdmin","measureCrmRecords","context","contactsSnap","companiesSnap","dealsSnap","orgRef","app","firestore","collection","doc","orgId","Promise","all","count","get","contactsCountAtSweep","Number","data","companiesCountAtSweep","dealsCountAtSweep","crmRecordsCountAtSweep","stamped","field","value","previous","isFinite","contactsAtPeriodEnd","crmRecordsAtPeriodEnd","companiesAtPeriodEnd","dealsAtPeriodEnd","closed","contactsCount","crmRecordsCount","companiesCount","dealsCount","quota","org","billed","releaseFlagOn","overageUsd","overageMonthlyUsd","fields","contactsOverageUsd","contactsOverageBilled","contactsOverageWithheldUsd","periodEndFields","contactsCountAtPeriodEnd","crmRecordsCountAtPeriodEnd","companiesCountAtPeriodEnd","dealsCountAtPeriodEnd","billedUsd","periodEndBasis"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED,SAASA,oBAAoB,QAAQ,2CAA0C;AAK/E,SAASC,aAAa,QAAQ,2BAA0B;AAExD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA+BC,GACD,OAAO,eAAeC,kBACpBC,OAAgC;QAUIC,0BACCC,2BACJC;IAVjC,MAAMC,SAASN,cAAcO,GAAG,GAAGC,SAAS,GAAGC,UAAU,CAAC,QAAQC,GAAG,CAACR,QAAQS,KAAK;IACnF,wEAAwE;IACxE,4CAA4C;IAC5C,MAAM,CAACR,cAAcC,eAAeC,UAAU,GAAG,MAAMO,QAAQC,GAAG,CAAC;QACjEP,OAAOG,UAAU,CAAC,YAAYK,KAAK,GAAGC,GAAG;QACzCT,OAAOG,UAAU,CAAC,aAAaK,KAAK,GAAGC,GAAG;QAC1CT,OAAOG,UAAU,CAAC,SAASK,KAAK,GAAGC,GAAG;KACvC;IACD,MAAMC,uBAAuBC,QAAOd,2BAAAA,aAAae,IAAI,GAAGJ,KAAK,YAAzBX,2BAA6B;IACjE,MAAMgB,wBAAwBF,QAAOb,4BAAAA,cAAcc,IAAI,GAAGJ,KAAK,YAA1BV,4BAA8B;IACnE,MAAMgB,oBAAoBH,QAAOZ,wBAAAA,UAAUa,IAAI,GAAGJ,KAAK,YAAtBT,wBAA0B;IAC3D,4EAA4E;IAC5E,+CAA+C;IAC/C,MAAMgB,yBACJL,uBAAuBG,wBAAwBC;IAEjD;;;;;GAKC,GACD,MAAME,UAAU,CAACC;QACf,MAAMC,QAAQP,OAAOf,QAAQuB,QAAQ,CAACF,MAAM;QAC5C,OAAON,OAAOS,QAAQ,CAACF,UAAUA,SAAS,IAAIA,QAAQ;IACxD;IACA,MAAMG,sBAAsBL,QAAQ;IACpC,MAAMM,wBAAwBN,QAAQ;IACtC,MAAMO,uBAAuBP,QAAQ;IACrC,MAAMQ,mBAAmBR,QAAQ;IAEjC,MAAM,EAAES,MAAM,EAAE,GAAG7B;IACnB,MAAM8B,gBACJD,UAAUJ,wBAAwB,OAAOA,sBAAsBX;IACjE,MAAM,CAACiB,iBAAiBC,gBAAgBC,WAAW,GACjDJ,UAAUH,0BAA0B,OAChC;QAACA;QAAuBC,+BAAAA,uBAAwB;QAAGC,2BAAAA,mBAAoB;KAAE,GACzEC,UAAUJ,wBAAwB,OAChC;QAACA;QAAqB;QAAG;KAAE,GAC3B;QAACN;QAAwBF;QAAuBC;KAAkB;IAE1E,2EAA2E;IAC3E,wEAAwE;IACxE,6BAA6B;IAC7B,MAAMgB,QAAQrC,qBAAqBG,QAAQmC,GAAG,EAAWJ;IACzD,MAAMK,SAASpC,QAAQqC,aAAa,CAAC;IACrC,MAAMC,aAAaF,SAASF,MAAMK,iBAAiB,GAAG;IAEtD,OAAO;QACLC,QAAQ;YACNV;YACAC;YACAC;YACAC;YACA,qEAAqE;YACrE,sDAAsD;YACtDnB;YACAK;YACAsB,oBAAoBH;YACpBI,uBAAuBN;YACvBO,4BAA4BP,SAAS,IAAIF,MAAMK,iBAAiB;QAClE;QACA,yEAAyE;QACzE,gCAAgC;QAChCK,iBAAiB;YACfC,0BAA0B/B;YAC1BgC,4BAA4B3B;YAC5B4B,2BAA2B9B;YAC3B+B,uBAAuB9B;QACzB;QACA+B,WAAWX;QACXY,gBACErB,UAAWJ,CAAAA,wBAAwB,QAAQC,0BAA0B,IAAG;IAC5E;AACF"}

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

@@ -0,0 +1,108 @@
+/**
+ * @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 { PluginApiHandler } from '@aglyn/aglyn/server';
+import { type CrmShareGrant, type CrmSharingObject, type CrmSharingRule, type CrmSharingSite } from '../model/crm-sharing';
+type Firestore = FirebaseFirestore.Firestore;
+/** Test seam, and what a rule write calls so its own process reads it fresh. */
+export declare function forgetCrmSharingRules(orgId?: string): void;
+export declare function crmSharingRulesOf(firestore: Firestore, orgId: string, options?: {
+    fresh?: boolean;
+    nowMs?: number;
+}): Promise<{
+    rules: CrmSharingRule[];
+    fresh: boolean;
+}>;
+export interface RecomputeRecordSharingInput {
+    firestore: Firestore;
+    orgId: string;
+    object: CrmSharingObject;
+    id: string;
+    /** Every rule the org has, in any state. */
+    rules: readonly CrmSharingRule[];
+    /** Whether `rules` was read just now; a stale list is re-read before it takes a grant away. */
+    fresh: boolean;
+    /** The hand shares' change, for a share or an unshare. */
+    manual?: (grants: Record<string, CrmShareGrant>) => Record<string, CrmShareGrant>;
+    atMs: number;
+}
+export type RecomputeOutcome = 'changed' | 'unchanged' | 'missing';
+export declare function recomputeRecordSharing(input: RecomputeRecordSharingInput): Promise<RecomputeOutcome>;
+/**
+ * Re-evaluates the org's rules for these records — the one thing a write
+ * anywhere owes the sharing. An org with no active rule for the object
+ * costs one cached read and nothing else; grants of a rule switched off
+ * are taken away by that rule's own removal pass, not here.
+ */
+export declare function evaluateCrmSharing(firestore: Firestore, orgId: string, object: CrmSharingObject, ids: readonly string[]): Promise<{
+    changed: number;
+    missing: number;
+}>;
+/**
+ * The core's record-written seam (AGL-3336): every server writer of a lead,
+ * a contact, a company or a deal restamps it, and the restamp tells this.
+ * Never throws — the write it is told about already landed.
+ */
+export declare function crmSharingRecordWritten(event: {
+    path: string;
+    collection: string;
+}): Promise<void>;
+export declare function crmSharingSites(firestore: Firestore, orgId: string): Promise<CrmSharingSite[]>;
+/**
+ * The rule a request describes, judged: an object, a name, sites that are
+ * the org's own, targets that are the org's own or all sites. `null` with
+ * the reason when it cannot be saved.
+ */
+export declare function ruleFromRequest(raw: unknown, context: {
+    hostIds: readonly string[];
+    existing: CrmSharingRule | null;
+    uid: string;
+    nowMs: number;
+}): {
+    rule: CrmSharingRule;
+    error: null;
+} | {
+    rule: null;
+    error: string;
+};
+/**
+ * One budgeted pass of a rule's run, with the progress written on the rule
+ * after every page so a reopened settings page shows where it stands and
+ * `rule-continue` picks up from the cursor.
+ *
+ * `apply` walks the object's whole collection by document id — a rule
+ * matches on fields no index narrows to (a facet's tags, a site that
+ * captured the person) — and writes only the records whose sharing moves.
+ * `remove` asks for exactly the records the rule holds a grant on
+ * (`sharing.ruleIds`), each of which the recompute then takes it off; a
+ * page that makes no progress fails the run rather than looping.
+ */
+export declare function advanceSharingRuleRun(firestore: Firestore, orgId: string, ruleId: string, deadlineMs: number): Promise<{
+    rule: CrmSharingRule | null;
+    more: boolean;
+}>;
+/**
+ * `POST /api/crm/sharing` — `{ action, hostId | orgId, … }`.
+ *
+ * Every action but `evaluate` is an org manager's: an OWNER or ADMIN of the
+ * whole workspace (`authorizeOrgCaller(…, 'manage-org')`), under a site's
+ * hub or the org's. `evaluate` is what a client-direct write owes the rules
+ * and is open to whoever may write the CRM. The plan gate is the CRM's own
+ * (`crmSuiteRefusal`): sharing is only meaningful across several sites, and
+ * the number of sites a workspace may have is already the plan's.
+ */
+export declare const crmSharingHandler: PluginApiHandler;
+export {};