@aglyn/plugins-crm 1.0.0-beta.143

package/src/lib/model/crm-activity-report.d.ts

@@ -0,0 +1,27 @@
+/**
+ * @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.
+ */
+export declare function reportDroppedActivityLine(error: unknown): void;
+/**
+ * A refusal the route ANSWERED rather than threw.
+ *
+ * `authorizedFetch` resolves for a 403 as readily as for a 200, so a line
+ * the route declined to write comes back through the success path. Turning
+ * it into an error is what puts it on the same reporting road as a network
+ * failure — without this, the one outcome the reporting exists to catch is
+ * the one that leaves no trace.
+ */
+export declare function orgActivityRefusal(status: number, payload: Record<string, unknown>): Error;

package/src/lib/model/crm-activity-report.js

@@ -0,0 +1,56 @@
+/**
+ * @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.
+ */ /**
+ * WHAT A DROPPED CRM ACTIVITY LINE DOES INSTEAD OF NOTHING (AGL-2738).
+ *
+ * Every CRM feed append is fire-and-forget on both sides of the hub — an
+ * audit miss must never turn a finished save into a failed one, and a
+ * snackbar about the LOG is a worse answer to "your record saved" than
+ * silence. But a line that can only fail silently is a feature that stays
+ * broken for months without a single signal, so a drop leaves by the two
+ * doors `useHostActivityLogger` already opens for a refused client-direct
+ * append, and for the same reasons: the beacon reaches Cloud Error
+ * Reporting and dedupes a failure that repeats on every edit into one
+ * report, and the console line fires once for whoever has devtools open.
+ *
+ * A module of its own, and not a hook: the bulk bars' hook and the record
+ * surfaces' both report through it, and only one of them has any business
+ * pulling in the tenant runtime.
+ */ import { reportHandledError } from "@aglyn/aglyn/app-utils/error-beacon";
+/** One console line per session, however many lines are dropped. */ let announced = false;
+export function reportDroppedActivityLine(error) {
+    reportHandledError(error, {
+        kind: 'crm-activity-write'
+    });
+    if (announced) return;
+    announced = true;
+    console.error('CRM activity logging failed; lines from this session are being dropped.', error);
+}
+/**
+ * A refusal the route ANSWERED rather than threw.
+ *
+ * `authorizedFetch` resolves for a 403 as readily as for a 200, so a line
+ * the route declined to write comes back through the success path. Turning
+ * it into an error is what puts it on the same reporting road as a network
+ * failure — without this, the one outcome the reporting exists to catch is
+ * the one that leaves no trace.
+ */ export function orgActivityRefusal(status, payload) {
+    var _payload_error;
+    const said = String((_payload_error = payload['error']) != null ? _payload_error : '').slice(0, 200);
+    return new Error(`crm/org-activity refused the line (${status})${said ? `: ${said}` : ''}`);
+}
+
+//# sourceMappingURL=crm-activity-report.js.map

package/src/lib/model/crm-activity-report.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/crm/src/lib/model/crm-activity-report.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\n/**\n * WHAT A DROPPED CRM ACTIVITY LINE DOES INSTEAD OF NOTHING (AGL-2738).\n *\n * Every CRM feed append is fire-and-forget on both sides of the hub — an\n * audit miss must never turn a finished save into a failed one, and a\n * snackbar about the LOG is a worse answer to \"your record saved\" than\n * silence. But a line that can only fail silently is a feature that stays\n * broken for months without a single signal, so a drop leaves by the two\n * doors `useHostActivityLogger` already opens for a refused client-direct\n * append, and for the same reasons: the beacon reaches Cloud Error\n * Reporting and dedupes a failure that repeats on every edit into one\n * report, and the console line fires once for whoever has devtools open.\n *\n * A module of its own, and not a hook: the bulk bars' hook and the record\n * surfaces' both report through it, and only one of them has any business\n * pulling in the tenant runtime.\n */\n\nimport { reportHandledError } from '@aglyn/aglyn/app-utils/error-beacon'\n\n/** One console line per session, however many lines are dropped. */\nlet announced = false\n\nexport function reportDroppedActivityLine(error: unknown): void {\n  reportHandledError(error, { kind: 'crm-activity-write' })\n  if (announced) return\n  announced = true\n  console.error(\n    'CRM activity logging failed; lines from this session are being dropped.',\n    error,\n  )\n}\n\n/**\n * A refusal the route ANSWERED rather than threw.\n *\n * `authorizedFetch` resolves for a 403 as readily as for a 200, so a line\n * the route declined to write comes back through the success path. Turning\n * it into an error is what puts it on the same reporting road as a network\n * failure — without this, the one outcome the reporting exists to catch is\n * the one that leaves no trace.\n */\nexport function orgActivityRefusal(\n  status: number,\n  payload: Record<string, unknown>,\n): Error {\n  const said = String(payload['error'] ?? '').slice(0, 200)\n  return new Error(\n    `crm/org-activity refused the line (${status})${said ? `: ${said}` : ''}`,\n  )\n}\n"],"names":["reportHandledError","announced","reportDroppedActivityLine","error","kind","console","orgActivityRefusal","status","payload","said","String","slice","Error"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;;;;;;;;CAgBC,GAED,SAASA,kBAAkB,QAAQ,sCAAqC;AAExE,kEAAkE,GAClE,IAAIC,YAAY;AAEhB,OAAO,SAASC,0BAA0BC,KAAc;IACtDH,mBAAmBG,OAAO;QAAEC,MAAM;IAAqB;IACvD,IAAIH,WAAW;IACfA,YAAY;IACZI,QAAQF,KAAK,CACX,2EACAA;AAEJ;AAEA;;;;;;;;CAQC,GACD,OAAO,SAASG,mBACdC,MAAc,EACdC,OAAgC;QAEZA;IAApB,MAAMC,OAAOC,QAAOF,iBAAAA,OAAO,CAAC,QAAQ,YAAhBA,iBAAoB,IAAIG,KAAK,CAAC,GAAG;IACrD,OAAO,IAAIC,MACT,CAAC,mCAAmC,EAAEL,OAAO,CAAC,EAAEE,OAAO,CAAC,EAAE,EAAEA,MAAM,GAAG,IAAI;AAE7E"}

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

@@ -0,0 +1,49 @@
+/**
+ * @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 { ContactLifecycleStage } from '@aglyn/aglyn';
+import { type MaybeTokenSource } from '@aglyn/shared-util-http/authorized-token';
+/**
+ * The console's client half of the CRM server routes (AGL-2605).
+ *
+ * A stage change goes through the server rather than a client-direct
+ * Firestore write, and the reason is the event: `contactStageChanged` can
+ * only be emitted by a server path that performed the write, so a record
+ * page that wrote the facet itself would move the person and tell no
+ * automation. A CLEAR comes the same way (AGL-2804), because a facet is the
+ * server's to write. This is the one function a stage control calls.
+ */
+/** What `crm/contact-stage` answers. */
+export interface ContactStageResult {
+    ok: true;
+    /** False when the contact was already in that stage — nothing moved. */
+    changed: boolean;
+    /** The stage the contact now holds, `''` after a clear. */
+    lifecycleStage: ContactLifecycleStage | '';
+    /** The stage before the move, `''` when the contact had none. */
+    previousStage: string;
+}
+/**
+ * Moves one contact to a lifecycle stage — or, with `null`, clears it — as
+ * the signed-in user.
+ *
+ * Throws with the route's own message on a refusal, so a control can show
+ * "Not a site admin or editor" rather than a generic failure; a network
+ * failure throws as `fetch` would.
+ */
+export declare function setContactStage(user: MaybeTokenSource, hostId: string, contactId: string, stage: ContactLifecycleStage | null, options?: {
+    fetchImpl?: typeof fetch;
+}): Promise<ContactStageResult>;

package/src/lib/model/crm-api.js

@@ -0,0 +1,47 @@
+/**
+ * @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 { authorizedFetch } from "@aglyn/shared-util-http/authorized-token";
+import { crmApiUrl } from "../constants/api-routes.js";
+/**
+ * Moves one contact to a lifecycle stage — or, with `null`, clears it — as
+ * the signed-in user.
+ *
+ * Throws with the route's own message on a refusal, so a control can show
+ * "Not a site admin or editor" rather than a generic failure; a network
+ * failure throws as `fetch` would.
+ */ export async function setContactStage(user, hostId, contactId, stage, options = {}) {
+    const response = await authorizedFetch(user, crmApiUrl('contactStage'), {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json'
+        },
+        body: JSON.stringify({
+            hostId,
+            contactId,
+            lifecycleStage: stage
+        })
+    }, options.fetchImpl ? {
+        fetchImpl: options.fetchImpl
+    } : {});
+    const payload = await response.json().catch(()=>({}));
+    if (!response.ok) {
+        var _payload_error;
+        throw new Error((_payload_error = payload.error) != null ? _payload_error : 'The stage could not be changed');
+    }
+    return payload;
+}
+
+//# sourceMappingURL=crm-api.js.map

package/src/lib/model/crm-api.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/crm/src/lib/model/crm-api.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 type { ContactLifecycleStage } from '@aglyn/aglyn'\nimport {\n  authorizedFetch,\n  type MaybeTokenSource,\n} from '@aglyn/shared-util-http/authorized-token'\nimport { crmApiUrl } from '../constants/api-routes'\n\n/**\n * The console's client half of the CRM server routes (AGL-2605).\n *\n * A stage change goes through the server rather than a client-direct\n * Firestore write, and the reason is the event: `contactStageChanged` can\n * only be emitted by a server path that performed the write, so a record\n * page that wrote the facet itself would move the person and tell no\n * automation. A CLEAR comes the same way (AGL-2804), because a facet is the\n * server's to write. This is the one function a stage control calls.\n */\n\n/** What `crm/contact-stage` answers. */\nexport interface ContactStageResult {\n  ok: true\n  /** False when the contact was already in that stage — nothing moved. */\n  changed: boolean\n  /** The stage the contact now holds, `''` after a clear. */\n  lifecycleStage: ContactLifecycleStage | ''\n  /** The stage before the move, `''` when the contact had none. */\n  previousStage: string\n}\n\n/**\n * Moves one contact to a lifecycle stage — or, with `null`, clears it — as\n * the signed-in user.\n *\n * Throws with the route's own message on a refusal, so a control can show\n * \"Not a site admin or editor\" rather than a generic failure; a network\n * failure throws as `fetch` would.\n */\nexport async function setContactStage(\n  user: MaybeTokenSource,\n  hostId: string,\n  contactId: string,\n  stage: ContactLifecycleStage | null,\n  options: { fetchImpl?: typeof fetch } = {},\n): Promise<ContactStageResult> {\n  const response = await authorizedFetch(\n    user,\n    crmApiUrl('contactStage'),\n    {\n      method: 'POST',\n      headers: { 'Content-Type': 'application/json' },\n      body: JSON.stringify({ hostId, contactId, lifecycleStage: stage }),\n    },\n    options.fetchImpl ? { fetchImpl: options.fetchImpl } : {},\n  )\n  const payload = (await response.json().catch(() => ({}))) as\n    | ContactStageResult\n    | { error?: string }\n  if (!response.ok) {\n    throw new Error(\n      (payload as { error?: string }).error ?? 'The stage could not be changed',\n    )\n  }\n  return payload as ContactStageResult\n}\n"],"names":["authorizedFetch","crmApiUrl","setContactStage","user","hostId","contactId","stage","options","response","method","headers","body","JSON","stringify","lifecycleStage","fetchImpl","payload","json","catch","ok","Error","error"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAGD,SACEA,eAAe,QAEV,2CAA0C;AACjD,SAASC,SAAS,QAAQ,6BAAyB;AAwBnD;;;;;;;CAOC,GACD,OAAO,eAAeC,gBACpBC,IAAsB,EACtBC,MAAc,EACdC,SAAiB,EACjBC,KAAmC,EACnCC,UAAwC,CAAC,CAAC;IAE1C,MAAMC,WAAW,MAAMR,gBACrBG,MACAF,UAAU,iBACV;QACEQ,QAAQ;QACRC,SAAS;YAAE,gBAAgB;QAAmB;QAC9CC,MAAMC,KAAKC,SAAS,CAAC;YAAET;YAAQC;YAAWS,gBAAgBR;QAAM;IAClE,GACAC,QAAQQ,SAAS,GAAG;QAAEA,WAAWR,QAAQQ,SAAS;IAAC,IAAI,CAAC;IAE1D,MAAMC,UAAW,MAAMR,SAASS,IAAI,GAAGC,KAAK,CAAC,IAAO,CAAA,CAAC,CAAA;IAGrD,IAAI,CAACV,SAASW,EAAE,EAAE;YAEd;QADF,MAAM,IAAIC,OACR,iBAAA,AAACJ,QAA+BK,KAAK,YAArC,iBAAyC;IAE7C;IACA,OAAOL;AACT"}

package/src/lib/model/crm-bulk-writes.d.ts

@@ -0,0 +1,147 @@
+/**
+ * @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.
+ */
+/**
+ * HOW A BULK ACTION IS APPLIED, whichever CRM collection it is over
+ * (AGL-2621).
+ *
+ * The contacts bar settled the shape (AGL-2603): one act over many rows is
+ * a PLAN of per-row writes, applied in batches with a per-row fallback, and
+ * whatever the store refused comes back NAMED — by the address, the company,
+ * the deal's title — never as a count. Companies, deals and tasks each have
+ * a bar now, and each bar's runner would be the same forty lines with a
+ * different noun. So the runner lives here once, parametric over what a
+ * write is called, and `contacts-bulk-writes.ts` stands on it under the
+ * names it always exported.
+ *
+ * ## Two kinds of act
+ *
+ * A write to the document — an owner, a tag, a due date, a delete — goes
+ * through {@link runCrmBulkWrites}: batched, and re-applied row by row when a
+ * batch fails, because a batch that fails names no row. An act with a side
+ * effect outside the document — a deal's stage, a task's completion, an
+ * assignment that notifies — goes through its ROUTE, one request per row, and
+ * {@link runCrmBulkCalls} is the same tally over those: each refusal is named
+ * by the row and carries the route's own sentence. A route that takes the
+ * whole selection at once and answers per row — the organization-level task
+ * routes (AGL-2637) — is tallied by {@link runCrmBulkBatch} from its answers.
+ *
+ * Pure apart from the Firestore SDK the writer factory binds: the runners
+ * take their writers as ports, so a spec wires a ledger in.
+ */
+import { type DocumentReference, type Firestore } from 'firebase/firestore';
+/**
+ * The Firestore batch cap is 500 writes; 400 leaves room for the sentinel
+ * transforms a patch carries, which the cap counts as writes of their own.
+ * The same margin the datasets card keeps.
+ */
+export declare const CRM_BULK_WRITE_CHUNK = 400;
+/**
+ * One write to one document, named for the report — the name a person
+ * recognizes the row by, which is what a refusal is listed under.
+ */
+export type CrmBulkWrite = {
+    id: string;
+    label: string;
+} & ({
+    kind: 'update';
+    data: Record<string, unknown>;
+} | {
+    kind: 'delete';
+});
+/** A row an action deliberately left alone, and why. */
+export interface CrmBulkSkip {
+    label: string;
+    reason: string;
+}
+/** What one action wants written, and what it declined to. */
+export interface CrmBulkPlan<W = CrmBulkWrite> {
+    writes: W[];
+    skipped: CrmBulkSkip[];
+}
+/** The writers the runner needs — Firestore's, or a spec's ledger. */
+export interface CrmBulkWriters<W> {
+    /** Apply every write atomically, or throw. */
+    commitBatch: (writes: readonly W[]) => Promise<void>;
+    /** Apply one write, or throw. */
+    commitOne: (write: W) => Promise<void>;
+}
+export interface CrmBulkOutcome {
+    /** Rows written, or requests answered. */
+    done: number;
+    /** Rows the store or the route refused, by label, with the reason given. */
+    refused: Array<{
+        label: string;
+        error: string;
+    }>;
+}
+export declare function chunked<T>(items: readonly T[], size: number): T[][];
+/** Whatever the store or the route threw, as one sentence a report can carry. */
+export declare function bulkRefusalReason(error: unknown): string;
+/**
+ * Apply the writes in chunks, and re-apply a failed chunk row by row.
+ *
+ * The batch is the fast path and the common one: four hundred patches in
+ * one round trip. The fallback is the honest one: a batch that fails names
+ * no row, so the only way to say WHICH of four hundred was refused is to
+ * ask about each. The chunk that failed is the only one that pays for that;
+ * the others commit as batches.
+ */
+export declare function runCrmBulkWrites<W>(writers: CrmBulkWriters<W>, writes: readonly W[], labelOf: (write: W) => string, chunkSize?: number): Promise<CrmBulkOutcome>;
+/**
+ * One request per row, in order, tallied the same way.
+ *
+ * In ORDER rather than in parallel: the routes these calls reach each
+ * verify a session, resolve a membership and emit an event, and two hundred
+ * of them fired at once is a burst the console's request budget is not
+ * sized for. A refusal carries the route's own sentence, which is written
+ * for the person reading it.
+ */
+export declare function runCrmBulkCalls<T>(items: readonly T[], labelOf: (item: T) => string, call: (item: T) => Promise<unknown>): Promise<CrmBulkOutcome>;
+/** What a batch route answers for one row: written, or refused with a sentence. */
+export interface CrmBulkAnswer {
+    id: string;
+    ok: boolean;
+    error?: string;
+}
+/**
+ * One request for the whole selection, answered per row (AGL-2637).
+ *
+ * The tally is read off the answers rather than off N calls, in the rows'
+ * own order. A row the answer does not mention was not written — a route
+ * that dropped it silently would otherwise read as success — and is refused
+ * by name. A request refused WHOLE (no session, no reach over the org) is
+ * every row it carried refused with the route's one sentence, which is what
+ * the same selection through {@link runCrmBulkCalls} would have said N times.
+ *
+ * A route that caps how many rows one request names takes the selection in
+ * pieces of `chunkSize`, one request after another; by default the whole
+ * selection is one request.
+ */
+export declare function runCrmBulkBatch<T>(items: readonly T[], idOf: (item: T) => string, labelOf: (item: T) => string, call: (items: readonly T[]) => Promise<readonly CrmBulkAnswer[]>, chunkSize?: number): Promise<CrmBulkOutcome>;
+/**
+ * The Firestore writers for a collection whose bulk writes touch ONE
+ * document each — companies, deals, tasks. The contacts bar keeps its own
+ * pair, because a contact's company link moves a count on a second document
+ * and that count has to land in the same commit.
+ */
+export declare function crmBulkWriters(firestore: Firestore, refFor: (id: string) => DocumentReference): CrmBulkWriters<CrmBulkWrite>;
+/**
+ * The report under a bar: what the plan skipped on purpose, then what the
+ * store refused, one line each, named. `null` when there is nothing to say,
+ * so the bar renders no empty alert.
+ */
+export declare function bulkReport(plan: Pick<CrmBulkPlan<unknown>, 'skipped'>, outcome: CrmBulkOutcome): CrmBulkSkip[] | null;

package/src/lib/model/crm-bulk-writes.js

@@ -0,0 +1,207 @@
+/**
+ * @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.
+ */ /**
+ * HOW A BULK ACTION IS APPLIED, whichever CRM collection it is over
+ * (AGL-2621).
+ *
+ * The contacts bar settled the shape (AGL-2603): one act over many rows is
+ * a PLAN of per-row writes, applied in batches with a per-row fallback, and
+ * whatever the store refused comes back NAMED — by the address, the company,
+ * the deal's title — never as a count. Companies, deals and tasks each have
+ * a bar now, and each bar's runner would be the same forty lines with a
+ * different noun. So the runner lives here once, parametric over what a
+ * write is called, and `contacts-bulk-writes.ts` stands on it under the
+ * names it always exported.
+ *
+ * ## Two kinds of act
+ *
+ * A write to the document — an owner, a tag, a due date, a delete — goes
+ * through {@link runCrmBulkWrites}: batched, and re-applied row by row when a
+ * batch fails, because a batch that fails names no row. An act with a side
+ * effect outside the document — a deal's stage, a task's completion, an
+ * assignment that notifies — goes through its ROUTE, one request per row, and
+ * {@link runCrmBulkCalls} is the same tally over those: each refusal is named
+ * by the row and carries the route's own sentence. A route that takes the
+ * whole selection at once and answers per row — the organization-level task
+ * routes (AGL-2637) — is tallied by {@link runCrmBulkBatch} from its answers.
+ *
+ * Pure apart from the Firestore SDK the writer factory binds: the runners
+ * take their writers as ports, so a spec wires a ledger in.
+ */ import { deleteDoc, updateDoc, writeBatch } from "firebase/firestore";
+/**
+ * The Firestore batch cap is 500 writes; 400 leaves room for the sentinel
+ * transforms a patch carries, which the cap counts as writes of their own.
+ * The same margin the datasets card keeps.
+ */ export const CRM_BULK_WRITE_CHUNK = 400;
+export function chunked(items, size) {
+    const chunks = [];
+    for(let start = 0; start < items.length; start += size){
+        chunks.push(items.slice(start, start + size));
+    }
+    return chunks;
+}
+/** Whatever the store or the route threw, as one sentence a report can carry. */ export function bulkRefusalReason(error) {
+    const code = error == null ? void 0 : error.code;
+    if (code === 'permission-denied') return 'not permitted';
+    if (code === 'not-found') return 'no longer exists';
+    const message = error == null ? void 0 : error.message;
+    return typeof message === 'string' && message ? message : 'the write failed';
+}
+/**
+ * Apply the writes in chunks, and re-apply a failed chunk row by row.
+ *
+ * The batch is the fast path and the common one: four hundred patches in
+ * one round trip. The fallback is the honest one: a batch that fails names
+ * no row, so the only way to say WHICH of four hundred was refused is to
+ * ask about each. The chunk that failed is the only one that pays for that;
+ * the others commit as batches.
+ */ export async function runCrmBulkWrites(writers, writes, labelOf, chunkSize = CRM_BULK_WRITE_CHUNK) {
+    const outcome = {
+        done: 0,
+        refused: []
+    };
+    for (const chunk of chunked(writes, chunkSize)){
+        try {
+            await writers.commitBatch(chunk);
+            outcome.done += chunk.length;
+            continue;
+        } catch (unused) {
+        // Fall through to the per-row pass below.
+        }
+        for (const write of chunk){
+            try {
+                await writers.commitOne(write);
+                outcome.done += 1;
+            } catch (error) {
+                outcome.refused.push({
+                    label: labelOf(write),
+                    error: bulkRefusalReason(error)
+                });
+            }
+        }
+    }
+    return outcome;
+}
+/**
+ * One request per row, in order, tallied the same way.
+ *
+ * In ORDER rather than in parallel: the routes these calls reach each
+ * verify a session, resolve a membership and emit an event, and two hundred
+ * of them fired at once is a burst the console's request budget is not
+ * sized for. A refusal carries the route's own sentence, which is written
+ * for the person reading it.
+ */ export async function runCrmBulkCalls(items, labelOf, call) {
+    const outcome = {
+        done: 0,
+        refused: []
+    };
+    for (const item of items){
+        try {
+            await call(item);
+            outcome.done += 1;
+        } catch (error) {
+            outcome.refused.push({
+                label: labelOf(item),
+                error: bulkRefusalReason(error)
+            });
+        }
+    }
+    return outcome;
+}
+/**
+ * One request for the whole selection, answered per row (AGL-2637).
+ *
+ * The tally is read off the answers rather than off N calls, in the rows'
+ * own order. A row the answer does not mention was not written — a route
+ * that dropped it silently would otherwise read as success — and is refused
+ * by name. A request refused WHOLE (no session, no reach over the org) is
+ * every row it carried refused with the route's one sentence, which is what
+ * the same selection through {@link runCrmBulkCalls} would have said N times.
+ *
+ * A route that caps how many rows one request names takes the selection in
+ * pieces of `chunkSize`, one request after another; by default the whole
+ * selection is one request.
+ */ export async function runCrmBulkBatch(items, idOf, labelOf, call, chunkSize = Number.POSITIVE_INFINITY) {
+    const outcome = {
+        done: 0,
+        refused: []
+    };
+    for (const piece of chunked(items, chunkSize)){
+        let answers;
+        try {
+            answers = await call(piece);
+        } catch (error) {
+            const reason = bulkRefusalReason(error);
+            for (const item of piece)outcome.refused.push({
+                label: labelOf(item),
+                error: reason
+            });
+            continue;
+        }
+        const byId = new Map(answers.map((answer)=>[
+                answer.id,
+                answer
+            ]));
+        for (const item of piece){
+            const answer = byId.get(idOf(item));
+            if (answer == null ? void 0 : answer.ok) outcome.done += 1;
+            else {
+                outcome.refused.push({
+                    label: labelOf(item),
+                    error: (answer == null ? void 0 : answer.error) || 'the write failed'
+                });
+            }
+        }
+    }
+    return outcome;
+}
+/**
+ * The Firestore writers for a collection whose bulk writes touch ONE
+ * document each — companies, deals, tasks. The contacts bar keeps its own
+ * pair, because a contact's company link moves a count on a second document
+ * and that count has to land in the same commit.
+ */ export function crmBulkWriters(firestore, refFor) {
+    return {
+        commitBatch: async (writes)=>{
+            const batch = writeBatch(firestore);
+            for (const write of writes){
+                if (write.kind === 'delete') batch.delete(refFor(write.id));
+                else batch.update(refFor(write.id), write.data);
+            }
+            await batch.commit();
+        },
+        commitOne: async (write)=>{
+            if (write.kind === 'delete') await deleteDoc(refFor(write.id));
+            else await updateDoc(refFor(write.id), write.data);
+        }
+    };
+}
+/**
+ * The report under a bar: what the plan skipped on purpose, then what the
+ * store refused, one line each, named. `null` when there is nothing to say,
+ * so the bar renders no empty alert.
+ */ export function bulkReport(plan, outcome) {
+    const left = [
+        ...plan.skipped,
+        ...outcome.refused.map((row)=>({
+                label: row.label,
+                reason: row.error
+            }))
+    ];
+    return left.length ? left : null;
+}
+
+//# sourceMappingURL=crm-bulk-writes.js.map

package/src/lib/model/crm-bulk-writes.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/crm/src/lib/model/crm-bulk-writes.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\n/**\n * HOW A BULK ACTION IS APPLIED, whichever CRM collection it is over\n * (AGL-2621).\n *\n * The contacts bar settled the shape (AGL-2603): one act over many rows is\n * a PLAN of per-row writes, applied in batches with a per-row fallback, and\n * whatever the store refused comes back NAMED — by the address, the company,\n * the deal's title — never as a count. Companies, deals and tasks each have\n * a bar now, and each bar's runner would be the same forty lines with a\n * different noun. So the runner lives here once, parametric over what a\n * write is called, and `contacts-bulk-writes.ts` stands on it under the\n * names it always exported.\n *\n * ## Two kinds of act\n *\n * A write to the document — an owner, a tag, a due date, a delete — goes\n * through {@link runCrmBulkWrites}: batched, and re-applied row by row when a\n * batch fails, because a batch that fails names no row. An act with a side\n * effect outside the document — a deal's stage, a task's completion, an\n * assignment that notifies — goes through its ROUTE, one request per row, and\n * {@link runCrmBulkCalls} is the same tally over those: each refusal is named\n * by the row and carries the route's own sentence. A route that takes the\n * whole selection at once and answers per row — the organization-level task\n * routes (AGL-2637) — is tallied by {@link runCrmBulkBatch} from its answers.\n *\n * Pure apart from the Firestore SDK the writer factory binds: the runners\n * take their writers as ports, so a spec wires a ledger in.\n */\n\nimport {\n  deleteDoc,\n  type DocumentReference,\n  type Firestore,\n  updateDoc,\n  writeBatch,\n} from 'firebase/firestore'\n\n/**\n * The Firestore batch cap is 500 writes; 400 leaves room for the sentinel\n * transforms a patch carries, which the cap counts as writes of their own.\n * The same margin the datasets card keeps.\n */\nexport const CRM_BULK_WRITE_CHUNK = 400\n\n/**\n * One write to one document, named for the report — the name a person\n * recognizes the row by, which is what a refusal is listed under.\n */\nexport type CrmBulkWrite = { id: string; label: string } & (\n  | { kind: 'update'; data: Record<string, unknown> }\n  | { kind: 'delete' }\n)\n\n/** A row an action deliberately left alone, and why. */\nexport interface CrmBulkSkip {\n  label: string\n  reason: string\n}\n\n/** What one action wants written, and what it declined to. */\nexport interface CrmBulkPlan<W = CrmBulkWrite> {\n  writes: W[]\n  skipped: CrmBulkSkip[]\n}\n\n/** The writers the runner needs — Firestore's, or a spec's ledger. */\nexport interface CrmBulkWriters<W> {\n  /** Apply every write atomically, or throw. */\n  commitBatch: (writes: readonly W[]) => Promise<void>\n  /** Apply one write, or throw. */\n  commitOne: (write: W) => Promise<void>\n}\n\nexport interface CrmBulkOutcome {\n  /** Rows written, or requests answered. */\n  done: number\n  /** Rows the store or the route refused, by label, with the reason given. */\n  refused: Array<{ label: string; error: string }>\n}\n\nexport function chunked<T>(items: readonly T[], size: number): T[][] {\n  const chunks: T[][] = []\n  for (let start = 0; start < items.length; start += size) {\n    chunks.push(items.slice(start, start + size))\n  }\n  return chunks\n}\n\n/** Whatever the store or the route threw, as one sentence a report can carry. */\nexport function bulkRefusalReason(error: unknown): string {\n  const code = (error as { code?: unknown } | null)?.code\n  if (code === 'permission-denied') return 'not permitted'\n  if (code === 'not-found') return 'no longer exists'\n  const message = (error as { message?: unknown } | null)?.message\n  return typeof message === 'string' && message ? message : 'the write failed'\n}\n\n/**\n * Apply the writes in chunks, and re-apply a failed chunk row by row.\n *\n * The batch is the fast path and the common one: four hundred patches in\n * one round trip. The fallback is the honest one: a batch that fails names\n * no row, so the only way to say WHICH of four hundred was refused is to\n * ask about each. The chunk that failed is the only one that pays for that;\n * the others commit as batches.\n */\nexport async function runCrmBulkWrites<W>(\n  writers: CrmBulkWriters<W>,\n  writes: readonly W[],\n  labelOf: (write: W) => string,\n  chunkSize: number = CRM_BULK_WRITE_CHUNK,\n): Promise<CrmBulkOutcome> {\n  const outcome: CrmBulkOutcome = { done: 0, refused: [] }\n  for (const chunk of chunked(writes, chunkSize)) {\n    try {\n      await writers.commitBatch(chunk)\n      outcome.done += chunk.length\n      continue\n    } catch {\n      // Fall through to the per-row pass below.\n    }\n    for (const write of chunk) {\n      try {\n        await writers.commitOne(write)\n        outcome.done += 1\n      } catch (error) {\n        outcome.refused.push({ label: labelOf(write), error: bulkRefusalReason(error) })\n      }\n    }\n  }\n  return outcome\n}\n\n/**\n * One request per row, in order, tallied the same way.\n *\n * In ORDER rather than in parallel: the routes these calls reach each\n * verify a session, resolve a membership and emit an event, and two hundred\n * of them fired at once is a burst the console's request budget is not\n * sized for. A refusal carries the route's own sentence, which is written\n * for the person reading it.\n */\nexport async function runCrmBulkCalls<T>(\n  items: readonly T[],\n  labelOf: (item: T) => string,\n  call: (item: T) => Promise<unknown>,\n): Promise<CrmBulkOutcome> {\n  const outcome: CrmBulkOutcome = { done: 0, refused: [] }\n  for (const item of items) {\n    try {\n      await call(item)\n      outcome.done += 1\n    } catch (error) {\n      outcome.refused.push({ label: labelOf(item), error: bulkRefusalReason(error) })\n    }\n  }\n  return outcome\n}\n\n/** What a batch route answers for one row: written, or refused with a sentence. */\nexport interface CrmBulkAnswer {\n  id: string\n  ok: boolean\n  error?: string\n}\n\n/**\n * One request for the whole selection, answered per row (AGL-2637).\n *\n * The tally is read off the answers rather than off N calls, in the rows'\n * own order. A row the answer does not mention was not written — a route\n * that dropped it silently would otherwise read as success — and is refused\n * by name. A request refused WHOLE (no session, no reach over the org) is\n * every row it carried refused with the route's one sentence, which is what\n * the same selection through {@link runCrmBulkCalls} would have said N times.\n *\n * A route that caps how many rows one request names takes the selection in\n * pieces of `chunkSize`, one request after another; by default the whole\n * selection is one request.\n */\nexport async function runCrmBulkBatch<T>(\n  items: readonly T[],\n  idOf: (item: T) => string,\n  labelOf: (item: T) => string,\n  call: (items: readonly T[]) => Promise<readonly CrmBulkAnswer[]>,\n  chunkSize: number = Number.POSITIVE_INFINITY,\n): Promise<CrmBulkOutcome> {\n  const outcome: CrmBulkOutcome = { done: 0, refused: [] }\n  for (const piece of chunked(items, chunkSize)) {\n    let answers: readonly CrmBulkAnswer[]\n    try {\n      answers = await call(piece)\n    } catch (error) {\n      const reason = bulkRefusalReason(error)\n      for (const item of piece) outcome.refused.push({ label: labelOf(item), error: reason })\n      continue\n    }\n    const byId = new Map(answers.map((answer) => [answer.id, answer]))\n    for (const item of piece) {\n      const answer = byId.get(idOf(item))\n      if (answer?.ok) outcome.done += 1\n      else {\n        outcome.refused.push({\n          label: labelOf(item),\n          error: answer?.error || 'the write failed',\n        })\n      }\n    }\n  }\n  return outcome\n}\n\n/**\n * The Firestore writers for a collection whose bulk writes touch ONE\n * document each — companies, deals, tasks. The contacts bar keeps its own\n * pair, because a contact's company link moves a count on a second document\n * and that count has to land in the same commit.\n */\nexport function crmBulkWriters(\n  firestore: Firestore,\n  refFor: (id: string) => DocumentReference,\n): CrmBulkWriters<CrmBulkWrite> {\n  return {\n    commitBatch: async (writes) => {\n      const batch = writeBatch(firestore)\n      for (const write of writes) {\n        if (write.kind === 'delete') batch.delete(refFor(write.id))\n        else batch.update(refFor(write.id), write.data)\n      }\n      await batch.commit()\n    },\n    commitOne: async (write) => {\n      if (write.kind === 'delete') await deleteDoc(refFor(write.id))\n      else await updateDoc(refFor(write.id), write.data)\n    },\n  }\n}\n\n/**\n * The report under a bar: what the plan skipped on purpose, then what the\n * store refused, one line each, named. `null` when there is nothing to say,\n * so the bar renders no empty alert.\n */\nexport function bulkReport(\n  plan: Pick<CrmBulkPlan<unknown>, 'skipped'>,\n  outcome: CrmBulkOutcome,\n): CrmBulkSkip[] | null {\n  const left: CrmBulkSkip[] = [\n    ...plan.skipped,\n    ...outcome.refused.map((row) => ({ label: row.label, reason: row.error })),\n  ]\n  return left.length ? left : null\n}\n"],"names":["deleteDoc","updateDoc","writeBatch","CRM_BULK_WRITE_CHUNK","chunked","items","size","chunks","start","length","push","slice","bulkRefusalReason","error","code","message","runCrmBulkWrites","writers","writes","labelOf","chunkSize","outcome","done","refused","chunk","commitBatch","write","commitOne","label","runCrmBulkCalls","call","item","runCrmBulkBatch","idOf","Number","POSITIVE_INFINITY","piece","answers","reason","byId","Map","map","answer","id","get","ok","crmBulkWriters","firestore","refFor","batch","kind","delete","update","data","commit","bulkReport","plan","left","skipped","row"],"mappings":"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"}