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

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 {};