@aglyn/plugins-crm 1.0.0-beta.143

package/src/lib/server-deal-stage.js

@@ -0,0 +1,316 @@
+import { _ as _extends } from "@swc/helpers/_/_extends";
+/**
+ * @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.
+ */ /**
+ * `POST /api/crm/deal-stage` — the one writer of a deal's stage (AGL-2598).
+ *
+ * ## Why a route, when the rules would let the browser do it
+ *
+ * A deal's title, amount and owner are edited client-direct against the
+ * Firestore rules, and nothing about a stage change needs a server to be
+ * SAFE. What it needs a server for is to be HEARD: a move between stages, a
+ * win and a loss are the three moments an automation wants — "when a deal is
+ * won, email the owner", "when one reaches negotiation, file a task" — and a
+ * workflow only fires on an event the tenant runtime emits. A stage written
+ * by the browser would be a fact nothing could react to. So every surface
+ * that moves a deal calls here, and this handler updates the document and
+ * then emits `dealStageChanged`, `dealWon` or `dealLost` with a flat payload
+ * a workflow filter can read.
+ *
+ * ## Who may call it
+ *
+ * Three gates, in the order the cheapest fails first:
+ *
+ *  1. A verified Firebase session — the console's `authorizedFetch` puts the
+ *     id token on every call.
+ *  2. An admin or editor role ON THIS SITE, resolved by `hostRoleFor` from
+ *     the org member document, which is the same projection the rules read.
+ *  3. The `data.manage` permission in the org — the key the whole CRM is
+ *     gated on, resolved through the custom-role and per-member layers by
+ *     `memberHasOrgPermission`, because a member document alone cannot say
+ *     what a custom role took away.
+ *
+ * And then the deal has to be VISIBLE to the site: its `visibleTo` must
+ * intersect the scope tokens a contact captured on this site would carry.
+ * The Admin SDK evaluates no rules, so without this check an editor of one
+ * site in an agency could move another client's deals by id.
+ *
+ * ## The organization variant (AGL-2634)
+ *
+ * `{ orgId, dealId, … }` instead of a site: the org-level hub's board. The
+ * caller is authorized by the ORG — an org-wide member holding
+ * `data.manage`, the org hub's own gate — and no visibility check is made,
+ * because an org-wide member reads every row the org holds. The event
+ * still goes to the deal's own capturing site, which is where the
+ * automations that listen for it live; a deal no site captured has none to
+ * tell. And the act is logged in the org's feed, since there is no one
+ * site's feed it happened in.
+ *
+ * ## What it writes
+ *
+ * `stageId`, `status` (from the target stage's `kind`, never from the body),
+ * `stageChangedAtMs`, `closedAtMs` (set on a close, cleared on a reopen) and
+ * `lostReason` (kept on a loss, removed on anything else). A move to the
+ * stage the deal is already in writes nothing and emits nothing — an
+ * automation must not fire twice because a card was dropped where it was.
+ *
+ * ## A won deal makes its contact a customer (AGL-2641)
+ *
+ * A win is the same fact as a purchase — the business has decided this
+ * person bought — and an order already floors a contact's lifecycle stage
+ * at `customer` on capture. So the transition INTO `won` applies the same
+ * floor to the contact the deal names, in the same write path, behind no
+ * setting: `floorContactLifecycleStage` fills an empty stage or advances an
+ * earlier one inside the facet of the site the deal was made on, and never
+ * moves anybody back — a customer stays a customer, an evangelist an
+ * evangelist. When the stage did move, `contactStageChanged` is announced
+ * after `dealWon`, so an automation keyed on "became a customer" hears it,
+ * and the org's activity line says so. A failure to write the contact does
+ * not undo the win: the deal is already closed, and the response reports
+ * `customer: null` rather than a 500 for a stage change that did happen.
+ */ import { CRM_COLLECTIONS, dealStageById, hostRoleFor, hostScopeToken, ORG_SCOPE_TOKEN } from "@aglyn/aglyn/server";
+import { consentGroupForSite, firebaseAdmin, floorContactLifecycleStage, getOrgForHost, logOrgActivity, memberHasOrgPermission, resolveOrgMembership } from "@aglyn/tenant-data-admin";
+import { isRefusedIdToken } from "@aglyn/tenant-data-admin/server/id-token-refusal";
+import { emitHostEvent } from "@aglyn/tenant-runtime";
+import { FieldValue } from "firebase-admin/firestore";
+import { closingStage, dealEventName, dealEventPayload } from "./model/deal-board-model.js";
+import { authorizeOrgCaller, readCrmRouteScope } from "./server/org-caller.js";
+import { crmSuiteRefusal } from "./server/suite-gate.js";
+/** The most a lost reason may carry — a sentence or two, not a post-mortem. */ export const LOST_REASON_MAX = 500;
+export const crmDealStageHandler = async (req, res)=>{
+    var _ref, _ref1, _deal_pipelineId, _deal_stageId, _deal_hostId, _deal_contactId;
+    var _req_body, _req_body1, _req_body2, _req_body3;
+    if (req.method !== 'POST') {
+        res.setHeader('Allow', 'POST');
+        return res.status(405).json({
+            error: 'Method not allowed'
+        });
+    }
+    const routeScope = readCrmRouteScope(req.body);
+    const dealId = String((_ref = (_req_body = req.body) == null ? void 0 : _req_body.dealId) != null ? _ref : '').trim();
+    const stageId = typeof ((_req_body1 = req.body) == null ? void 0 : _req_body1.stageId) === 'string' ? req.body.stageId.trim() : '';
+    const status = (_req_body2 = req.body) == null ? void 0 : _req_body2.status;
+    const closing = status === 'won' || status === 'lost' ? status : null;
+    const lostReason = String((_ref1 = (_req_body3 = req.body) == null ? void 0 : _req_body3.lostReason) != null ? _ref1 : '').trim().slice(0, LOST_REASON_MAX);
+    if (!routeScope || !dealId) {
+        return res.status(400).json({
+            error: 'Missing hostId or dealId'
+        });
+    }
+    if (!stageId && !closing) {
+        return res.status(400).json({
+            error: 'Name a stageId to move to, or a status of won or lost.'
+        });
+    }
+    /*
+   * Who is calling, and the org whose deal it is. The site variant
+   * resolves the org from the site and the caller's role on it; the org
+   * variant is authorized by the org itself, and the site the body may
+   * name beside it is not consulted — the deal's own site, read off the
+   * document, is the one its event goes to.
+   */ let orgId;
+    let org;
+    let actor = null;
+    if (routeScope.level === 'org') {
+        const caller = await authorizeOrgCaller(req, routeScope.orgId, {
+            needs: 'data.manage',
+            refusal: 'Moving a deal at the organization level requires the "Manage data" ' + 'permission across the whole workspace.'
+        });
+        if (caller.ok === false) {
+            return res.status(caller.status).json({
+                error: caller.error
+            });
+        }
+        orgId = caller.orgId;
+        org = caller.org;
+        actor = {
+            uid: caller.uid,
+            email: caller.email
+        };
+    } else {
+        var _req_headers_authorization;
+        const authorization = String((_req_headers_authorization = req.headers.authorization) != null ? _req_headers_authorization : '');
+        const idToken = authorization.startsWith('Bearer ') ? authorization.slice('Bearer '.length) : '';
+        if (!idToken) {
+            return res.status(401).json({
+                error: 'Unauthenticated'
+            });
+        }
+        let uid;
+        try {
+            uid = (await firebaseAdmin.app().auth().verifyIdToken(idToken)).uid;
+        } catch (error) {
+            // A refused credential is the caller's 401; a failure to check one is
+            // ours and keeps a 5xx (AGL-2852).
+            if (isRefusedIdToken(error)) return res.status(401).json({
+                error: 'Unauthenticated'
+            });
+            console.error('[crm] deal-stage could not verify the caller', error);
+            return res.status(500).json({
+                error: 'The sign-in could not be checked. Try again.'
+            });
+        }
+        const owner = await getOrgForHost(routeScope.hostId).catch(()=>null);
+        if (!owner) {
+            return res.status(404).json({
+                error: 'This site has no organization, so it has no deals.'
+            });
+        }
+        const membership = await resolveOrgMembership(uid, owner.orgId).catch(()=>null);
+        const member = membership == null ? void 0 : membership.member;
+        const hostRole = hostRoleFor(member, routeScope.hostId);
+        if (!member || hostRole !== 'admin' && hostRole !== 'editor') {
+            return res.status(403).json({
+                error: 'Moving a deal needs an admin or editor role on this site.'
+            });
+        }
+        if (!await memberHasOrgPermission(owner.orgId, member, 'data.manage')) {
+            return res.status(403).json({
+                error: 'Moving a deal requires the "Manage data" permission.'
+            });
+        }
+        orgId = owner.orgId;
+        org = owner.org;
+    }
+    // Deals are the CRM suite's, at either level (AGL-2787).
+    const suite = crmSuiteRefusal(org, 'Moving a deal through its pipeline');
+    if (suite) return res.status(suite.status).json(suite.body);
+    const firestore = firebaseAdmin.app().firestore();
+    const orgRef = firestore.collection('orgs').doc(orgId);
+    const dealRef = orgRef.collection(CRM_COLLECTIONS.deals).doc(dealId);
+    const dealSnapshot = await dealRef.get();
+    if (!dealSnapshot.exists) {
+        return res.status(404).json({
+            error: 'Unknown deal'
+        });
+    }
+    const deal = dealSnapshot.data();
+    if (routeScope.level === 'site') {
+        var _deal_visibleTo;
+        const group = await consentGroupForSite(routeScope.hostId, org);
+        const readable = new Set([
+            ORG_SCOPE_TOKEN,
+            ...group.hostIds.map(hostScopeToken)
+        ]);
+        if (!((_deal_visibleTo = deal.visibleTo) != null ? _deal_visibleTo : []).some((token)=>readable.has(token))) {
+            return res.status(403).json({
+                error: 'This deal is not visible to this site.'
+            });
+        }
+    }
+    const pipelineSnapshot = await orgRef.collection(CRM_COLLECTIONS.pipelines).doc(String((_deal_pipelineId = deal.pipelineId) != null ? _deal_pipelineId : '')).get();
+    if (!pipelineSnapshot.exists) {
+        return res.status(409).json({
+            error: "This deal's pipeline no longer exists, so it has no stages to move to."
+        });
+    }
+    const pipeline = pipelineSnapshot.data();
+    const target = stageId ? dealStageById(pipeline, stageId) : closingStage(pipeline, closing);
+    if (!target) {
+        return res.status(400).json({
+            error: stageId ? 'This pipeline has no such stage.' : `This pipeline has no ${closing} stage.`
+        });
+    }
+    const previousStageId = String((_deal_stageId = deal.stageId) != null ? _deal_stageId : '');
+    const nextStatus = target.kind;
+    if (target.id === previousStageId && deal.status === nextStatus) {
+        return res.status(200).json({
+            ok: true,
+            dealId,
+            stageId: target.id,
+            status: nextStatus,
+            previousStageId,
+            event: null
+        });
+    }
+    const nowMs = Date.now();
+    await dealRef.update({
+        stageId: target.id,
+        status: nextStatus,
+        stageChangedAtMs: nowMs,
+        closedAtMs: nextStatus === 'open' ? null : nowMs,
+        lostReason: nextStatus === 'lost' ? lostReason : FieldValue.delete(),
+        updatedAt: new Date()
+    });
+    const event = dealEventName(nextStatus);
+    // The site whose automations hear the move: the mounted site, or at the
+    // organization level the deal's own — a deal no site captured has none.
+    const eventHostId = routeScope.level === 'site' ? routeScope.hostId : String((_deal_hostId = deal.hostId) != null ? _deal_hostId : '').trim();
+    /*
+   * The customer floor, on the transition into `won` alone: a move between
+   * open stages, a loss and a reopen say nothing about whether the person
+   * bought. The facet written is the site's the deal was made on — under
+   * a site the mounted one, at the organization level the deal's own, and
+   * for a deal no site captured the person's own capturing site.
+   */ let customer = null;
+    const contactId = String((_deal_contactId = deal.contactId) != null ? _deal_contactId : '').trim();
+    if (nextStatus === 'won' && contactId) {
+        customer = await floorContactLifecycleStage({
+            contactRef: orgRef.collection('contacts').doc(contactId),
+            org,
+            hostId: eventHostId || null,
+            floor: 'customer'
+        }).catch((error)=>{
+            console.error('[crm] deal-stage: the customer floor failed', dealId, contactId, error);
+            return null;
+        });
+    }
+    const becameCustomer = (customer == null ? void 0 : customer.outcome) === 'advanced';
+    if (eventHostId) {
+        await emitHostEvent(eventHostId, event, dealEventPayload(dealId, _extends({}, deal, {
+            stageId: target.id,
+            lostReason: nextStatus === 'lost' ? lostReason : undefined
+        }), previousStageId));
+    }
+    if ((customer == null ? void 0 : customer.outcome) === 'advanced') {
+        // The stage change is the win's effect, announced after its cause, to
+        // the site whose facet moved — the same site as the win's, unless no
+        // site captured the deal and the person's own site holds the stage.
+        await emitHostEvent(customer.hostId, 'contactStageChanged', {
+            contactId: customer.contactId,
+            email: customer.email,
+            lifecycleStage: customer.lifecycleStage,
+            previousStage: customer.previousStage
+        });
+    }
+    if (actor) {
+        var _deal_title;
+        await logOrgActivity(orgId, actor, nextStatus === 'won' ? becameCustomer ? 'Marked deal won — contact now a customer' : 'Marked deal won' : nextStatus === 'lost' ? 'Marked deal lost' : `Moved deal to ${target.name}`, {
+            type: 'deal',
+            id: dealId,
+            name: String((_deal_title = deal.title) != null ? _deal_title : '')
+        });
+    }
+    return res.status(200).json({
+        ok: true,
+        dealId,
+        stageId: target.id,
+        status: nextStatus,
+        previousStageId,
+        event,
+        /*
+     * What the win did to the contact: the stage it now holds and whether
+     * this call raised it. `null` on anything but a win, on a deal that
+     * names no contact, and on a contact write that failed.
+     */ customer: customer && (customer.outcome === 'advanced' || customer.outcome === 'held') ? {
+            contactId: customer.contactId,
+            lifecycleStage: customer.lifecycleStage,
+            advanced: customer.outcome === 'advanced'
+        } : null
+    });
+};
+
+//# sourceMappingURL=server-deal-stage.js.map

package/src/lib/server-deal-stage.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/plugins/crm/src/lib/server-deal-stage.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 * `POST /api/crm/deal-stage` — the one writer of a deal's stage (AGL-2598).\n *\n * ## Why a route, when the rules would let the browser do it\n *\n * A deal's title, amount and owner are edited client-direct against the\n * Firestore rules, and nothing about a stage change needs a server to be\n * SAFE. What it needs a server for is to be HEARD: a move between stages, a\n * win and a loss are the three moments an automation wants — \"when a deal is\n * won, email the owner\", \"when one reaches negotiation, file a task\" — and a\n * workflow only fires on an event the tenant runtime emits. A stage written\n * by the browser would be a fact nothing could react to. So every surface\n * that moves a deal calls here, and this handler updates the document and\n * then emits `dealStageChanged`, `dealWon` or `dealLost` with a flat payload\n * a workflow filter can read.\n *\n * ## Who may call it\n *\n * Three gates, in the order the cheapest fails first:\n *\n *  1. A verified Firebase session — the console's `authorizedFetch` puts the\n *     id token on every call.\n *  2. An admin or editor role ON THIS SITE, resolved by `hostRoleFor` from\n *     the org member document, which is the same projection the rules read.\n *  3. The `data.manage` permission in the org — the key the whole CRM is\n *     gated on, resolved through the custom-role and per-member layers by\n *     `memberHasOrgPermission`, because a member document alone cannot say\n *     what a custom role took away.\n *\n * And then the deal has to be VISIBLE to the site: its `visibleTo` must\n * intersect the scope tokens a contact captured on this site would carry.\n * The Admin SDK evaluates no rules, so without this check an editor of one\n * site in an agency could move another client's deals by id.\n *\n * ## The organization variant (AGL-2634)\n *\n * `{ orgId, dealId, … }` instead of a site: the org-level hub's board. The\n * caller is authorized by the ORG — an org-wide member holding\n * `data.manage`, the org hub's own gate — and no visibility check is made,\n * because an org-wide member reads every row the org holds. The event\n * still goes to the deal's own capturing site, which is where the\n * automations that listen for it live; a deal no site captured has none to\n * tell. And the act is logged in the org's feed, since there is no one\n * site's feed it happened in.\n *\n * ## What it writes\n *\n * `stageId`, `status` (from the target stage's `kind`, never from the body),\n * `stageChangedAtMs`, `closedAtMs` (set on a close, cleared on a reopen) and\n * `lostReason` (kept on a loss, removed on anything else). A move to the\n * stage the deal is already in writes nothing and emits nothing — an\n * automation must not fire twice because a card was dropped where it was.\n *\n * ## A won deal makes its contact a customer (AGL-2641)\n *\n * A win is the same fact as a purchase — the business has decided this\n * person bought — and an order already floors a contact's lifecycle stage\n * at `customer` on capture. So the transition INTO `won` applies the same\n * floor to the contact the deal names, in the same write path, behind no\n * setting: `floorContactLifecycleStage` fills an empty stage or advances an\n * earlier one inside the facet of the site the deal was made on, and never\n * moves anybody back — a customer stays a customer, an evangelist an\n * evangelist. When the stage did move, `contactStageChanged` is announced\n * after `dealWon`, so an automation keyed on \"became a customer\" hears it,\n * and the org's activity line says so. A failure to write the contact does\n * not undo the win: the deal is already closed, and the response reports\n * `customer: null` rather than a 500 for a stage change that did happen.\n */\n\nimport {\n  CRM_COLLECTIONS,\n  type CrmDeal,\n  type CrmPipeline,\n  dealStageById,\n  hostRoleFor,\n  hostScopeToken,\n  ORG_SCOPE_TOKEN,\n  type PluginApiHandler,\n} from '@aglyn/aglyn/server'\nimport {\n  consentGroupForSite,\n  type ContactLifecycleFloor,\n  firebaseAdmin,\n  floorContactLifecycleStage,\n  getOrgForHost,\n  logOrgActivity,\n  memberHasOrgPermission,\n  resolveOrgMembership,\n} from '@aglyn/tenant-data-admin'\nimport { isRefusedIdToken } from '@aglyn/tenant-data-admin/server/id-token-refusal'\nimport { emitHostEvent } from '@aglyn/tenant-runtime'\nimport { FieldValue } from 'firebase-admin/firestore'\nimport {\n  closingStage,\n  dealEventName,\n  dealEventPayload,\n} from './model/deal-board-model'\nimport { authorizeOrgCaller, readCrmRouteScope } from './server/org-caller'\nimport { crmSuiteRefusal } from './server/suite-gate'\n\n/** The most a lost reason may carry — a sentence or two, not a post-mortem. */\nexport const LOST_REASON_MAX = 500\n\nexport const crmDealStageHandler: PluginApiHandler = async (req, res) => {\n  if (req.method !== 'POST') {\n    res.setHeader('Allow', 'POST')\n    return res.status(405).json({ error: 'Method not allowed' })\n  }\n\n  const routeScope = readCrmRouteScope(req.body as Record<string, unknown>)\n  const dealId = String(req.body?.dealId ?? '').trim()\n  const stageId =\n    typeof req.body?.stageId === 'string' ? req.body.stageId.trim() : ''\n  const status = req.body?.status\n  const closing = status === 'won' || status === 'lost' ? status : null\n  const lostReason = String(req.body?.lostReason ?? '')\n    .trim()\n    .slice(0, LOST_REASON_MAX)\n  if (!routeScope || !dealId) {\n    return res.status(400).json({ error: 'Missing hostId or dealId' })\n  }\n  if (!stageId && !closing) {\n    return res.status(400).json({\n      error: 'Name a stageId to move to, or a status of won or lost.',\n    })\n  }\n\n  /*\n   * Who is calling, and the org whose deal it is. The site variant\n   * resolves the org from the site and the caller's role on it; the org\n   * variant is authorized by the org itself, and the site the body may\n   * name beside it is not consulted — the deal's own site, read off the\n   * document, is the one its event goes to.\n   */\n  let orgId: string\n  let org: Record<string, unknown>\n  let actor: { uid: string; email: string | null } | null = null\n  if (routeScope.level === 'org') {\n    const caller = await authorizeOrgCaller(req, routeScope.orgId, {\n      needs: 'data.manage',\n      refusal:\n        'Moving a deal at the organization level requires the \"Manage data\" ' +\n        'permission across the whole workspace.',\n    })\n    if (caller.ok === false) {\n      return res.status(caller.status).json({ error: caller.error })\n    }\n    orgId = caller.orgId\n    org = caller.org as Record<string, unknown>\n    actor = { uid: caller.uid, email: caller.email }\n  } else {\n    const authorization = String(req.headers.authorization ?? '')\n    const idToken = authorization.startsWith('Bearer ')\n      ? authorization.slice('Bearer '.length)\n      : ''\n    if (!idToken) {\n      return res.status(401).json({ error: 'Unauthenticated' })\n    }\n    let uid: string\n    try {\n      uid = (await firebaseAdmin.app().auth().verifyIdToken(idToken)).uid\n    } catch (error) {\n      // A refused credential is the caller's 401; a failure to check one is\n      // ours and keeps a 5xx (AGL-2852).\n      if (isRefusedIdToken(error)) return res.status(401).json({ error: 'Unauthenticated' })\n      console.error('[crm] deal-stage could not verify the caller', error)\n      return res.status(500).json({ error: 'The sign-in could not be checked. Try again.' })\n    }\n\n    const owner = await getOrgForHost(routeScope.hostId).catch(() => null)\n    if (!owner) {\n      return res.status(404).json({\n        error: 'This site has no organization, so it has no deals.',\n      })\n    }\n    const membership = await resolveOrgMembership(uid, owner.orgId).catch(\n      () => null,\n    )\n    const member = membership?.member\n    const hostRole = hostRoleFor(member, routeScope.hostId)\n    if (!member || (hostRole !== 'admin' && hostRole !== 'editor')) {\n      return res.status(403).json({\n        error: 'Moving a deal needs an admin or editor role on this site.',\n      })\n    }\n    if (!(await memberHasOrgPermission(owner.orgId, member, 'data.manage'))) {\n      return res.status(403).json({\n        error: 'Moving a deal requires the \"Manage data\" permission.',\n      })\n    }\n    orgId = owner.orgId\n    org = owner.org as Record<string, unknown>\n  }\n\n  // Deals are the CRM suite's, at either level (AGL-2787).\n  const suite = crmSuiteRefusal(org, 'Moving a deal through its pipeline')\n  if (suite) return res.status(suite.status).json(suite.body)\n\n  const firestore = firebaseAdmin.app().firestore()\n  const orgRef = firestore.collection('orgs').doc(orgId)\n  const dealRef = orgRef.collection(CRM_COLLECTIONS.deals).doc(dealId)\n  const dealSnapshot = await dealRef.get()\n  if (!dealSnapshot.exists) {\n    return res.status(404).json({ error: 'Unknown deal' })\n  }\n  const deal = dealSnapshot.data() as CrmDeal\n\n  if (routeScope.level === 'site') {\n    const group = await consentGroupForSite(routeScope.hostId, org)\n    const readable = new Set<string>([\n      ORG_SCOPE_TOKEN,\n      ...group.hostIds.map(hostScopeToken),\n    ])\n    if (!(deal.visibleTo ?? []).some((token) => readable.has(token))) {\n      return res.status(403).json({ error: 'This deal is not visible to this site.' })\n    }\n  }\n\n  const pipelineSnapshot = await orgRef\n    .collection(CRM_COLLECTIONS.pipelines)\n    .doc(String(deal.pipelineId ?? ''))\n    .get()\n  if (!pipelineSnapshot.exists) {\n    return res.status(409).json({\n      error: \"This deal's pipeline no longer exists, so it has no stages to move to.\",\n    })\n  }\n  const pipeline = pipelineSnapshot.data() as CrmPipeline\n  const target = stageId\n    ? dealStageById(pipeline, stageId)\n    : closingStage(pipeline, closing as 'won' | 'lost')\n  if (!target) {\n    return res.status(400).json({\n      error: stageId\n        ? 'This pipeline has no such stage.'\n        : `This pipeline has no ${closing} stage.`,\n    })\n  }\n\n  const previousStageId = String(deal.stageId ?? '')\n  const nextStatus = target.kind\n  if (target.id === previousStageId && deal.status === nextStatus) {\n    return res.status(200).json({\n      ok: true,\n      dealId,\n      stageId: target.id,\n      status: nextStatus,\n      previousStageId,\n      event: null,\n    })\n  }\n\n  const nowMs = Date.now()\n  await dealRef.update({\n    stageId: target.id,\n    status: nextStatus,\n    stageChangedAtMs: nowMs,\n    closedAtMs: nextStatus === 'open' ? null : nowMs,\n    lostReason: nextStatus === 'lost' ? lostReason : FieldValue.delete(),\n    updatedAt: new Date(),\n  })\n\n  const event = dealEventName(nextStatus)\n  // The site whose automations hear the move: the mounted site, or at the\n  // organization level the deal's own — a deal no site captured has none.\n  const eventHostId =\n    routeScope.level === 'site' ? routeScope.hostId : String(deal.hostId ?? '').trim()\n\n  /*\n   * The customer floor, on the transition into `won` alone: a move between\n   * open stages, a loss and a reopen say nothing about whether the person\n   * bought. The facet written is the site's the deal was made on — under\n   * a site the mounted one, at the organization level the deal's own, and\n   * for a deal no site captured the person's own capturing site.\n   */\n  let customer: ContactLifecycleFloor | null = null\n  const contactId = String(deal.contactId ?? '').trim()\n  if (nextStatus === 'won' && contactId) {\n    customer = await floorContactLifecycleStage({\n      contactRef: orgRef.collection('contacts').doc(contactId),\n      org,\n      hostId: eventHostId || null,\n      floor: 'customer',\n    }).catch((error: unknown) => {\n      console.error('[crm] deal-stage: the customer floor failed', dealId, contactId, error)\n      return null\n    })\n  }\n  const becameCustomer = customer?.outcome === 'advanced'\n\n  if (eventHostId) {\n    await emitHostEvent(\n      eventHostId,\n      event,\n      dealEventPayload(\n        dealId,\n        {\n          ...deal,\n          stageId: target.id,\n          lostReason: nextStatus === 'lost' ? lostReason : undefined,\n        },\n        previousStageId,\n      ),\n    )\n  }\n  if (customer?.outcome === 'advanced') {\n    // The stage change is the win's effect, announced after its cause, to\n    // the site whose facet moved — the same site as the win's, unless no\n    // site captured the deal and the person's own site holds the stage.\n    await emitHostEvent(customer.hostId, 'contactStageChanged', {\n      contactId: customer.contactId,\n      email: customer.email,\n      lifecycleStage: customer.lifecycleStage,\n      previousStage: customer.previousStage,\n    })\n  }\n  if (actor) {\n    await logOrgActivity(\n      orgId,\n      actor,\n      nextStatus === 'won'\n        ? becameCustomer\n          ? 'Marked deal won — contact now a customer'\n          : 'Marked deal won'\n        : nextStatus === 'lost'\n          ? 'Marked deal lost'\n          : `Moved deal to ${target.name}`,\n      { type: 'deal', id: dealId, name: String(deal.title ?? '') },\n    )\n  }\n\n  return res.status(200).json({\n    ok: true,\n    dealId,\n    stageId: target.id,\n    status: nextStatus,\n    previousStageId,\n    event,\n    /*\n     * What the win did to the contact: the stage it now holds and whether\n     * this call raised it. `null` on anything but a win, on a deal that\n     * names no contact, and on a contact write that failed.\n     */\n    customer:\n      customer && (customer.outcome === 'advanced' || customer.outcome === 'held')\n        ? {\n            contactId: customer.contactId,\n            lifecycleStage: customer.lifecycleStage,\n            advanced: customer.outcome === 'advanced',\n          }\n        : null,\n  })\n}\n"],"names":["CRM_COLLECTIONS","dealStageById","hostRoleFor","hostScopeToken","ORG_SCOPE_TOKEN","consentGroupForSite","firebaseAdmin","floorContactLifecycleStage","getOrgForHost","logOrgActivity","memberHasOrgPermission","resolveOrgMembership","isRefusedIdToken","emitHostEvent","FieldValue","closingStage","dealEventName","dealEventPayload","authorizeOrgCaller","readCrmRouteScope","crmSuiteRefusal","LOST_REASON_MAX","crmDealStageHandler","req","res","deal","method","setHeader","status","json","error","routeScope","body","dealId","String","trim","stageId","closing","lostReason","slice","orgId","org","actor","level","caller","needs","refusal","ok","uid","email","authorization","headers","idToken","startsWith","length","app","auth","verifyIdToken","console","owner","hostId","catch","membership","member","hostRole","suite","firestore","orgRef","collection","doc","dealRef","deals","dealSnapshot","get","exists","data","group","readable","Set","hostIds","map","visibleTo","some","token","has","pipelineSnapshot","pipelines","pipelineId","pipeline","target","previousStageId","nextStatus","kind","id","event","nowMs","Date","now","update","stageChangedAtMs","closedAtMs","delete","updatedAt","eventHostId","customer","contactId","contactRef","floor","becameCustomer","outcome","undefined","lifecycleStage","previousStage","name","type","title","advanced"],"mappings":"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"}

package/src/lib/server.d.ts

@@ -0,0 +1,149 @@
+/**
+ * @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.
+ */
+/**
+ * The Contacts plugin's SERVER half (AGL-2595).
+ *
+ * Contacts CRM v1 had none: every console write was client-direct against
+ * the Firestore rules, and the one server path that creates a contact —
+ * `upsertHostContact` — belongs to the capture doors, not to this plugin.
+ * v2 needs a server for the things a browser must not do alone: an import
+ * that dedupes forty thousand rows, a bulk action over a selection, an
+ * auto-association of contacts to companies by domain. Each of those lands
+ * as a `crm/<route>` handler registered here.
+ *
+ * `crm/ping` exists so the wiring is PROVEN rather than assumed:
+ * `plugins.config.json` names this module's register function and the
+ * `crm` API prefix, the generated server manifest loads this file, and the
+ * console's `/api/[...pluginApi]` dispatcher reaches the handler. A plugin
+ * whose first real route also had to be its first wiring test would have
+ * two things to debug at once.
+ *
+ * The real routes are the writes with a side effect outside the document:
+ * `crm/contact-stage` (AGL-2605) exists for the EVENT — `contactStageChanged`
+ * can only be emitted by a server path that performed the write, so a record
+ * page that moved the stage client-direct would move the person and tell no
+ * automation; the task routes (AGL-2599) carry an assignee's notification and
+ * the `taskCompleted` event; `crm/contacts-import` (AGL-2602) pushes one chunk
+ * of a file through the same capture door every other server door uses.
+ * `crm/deal-stage` (AGL-2598) is the one writer of a deal's stage, won and lost,
+ * because a stage change is what automations listen for (`server-deal-stage.ts`).
+ * `crm/contacts-create` (AGL-2596) is a person typed into the console by a
+ * member of the team — a server route because the dedupe against every
+ * holder's rows and the audience band are judgments the browser cannot make.
+ * `crm/contact-update` (AGL-2804) is every other write to a contact's facets:
+ * the rules cannot tell one field of a holder's facet from another, so they
+ * leave a client nothing there but letting a holder go, and the plan is
+ * asked here about the fields a save carries.
+ */
+import { type PluginApiHandler } from '@aglyn/aglyn/server';
+/**
+ * `GET /api/crm/ping` → `{ ok: true, plugin: 'crm' }`.
+ *
+ * No auth, no host, no data: it answers whether the plugin's server bundle
+ * was loaded and its routes registered, which is a fact about the process
+ * and not about any org. Anything that reads a document goes behind the
+ * same session and role checks the other plugins' console routes use.
+ */
+export declare const crmPingHandler: PluginApiHandler;
+/**
+ * `POST /api/crm/contact-stage` with `{ hostId, contactId, lifecycleStage }`.
+ *
+ * Writes the stage into THIS site's facet on the contact — a dotted
+ * `update()`, never a top-level field, because the row is shared by every
+ * site in the org and a stage is one holder's reading of the person — and
+ * then announces `contactStageChanged` with the stage it replaced.
+ *
+ * A stage set to what it already is writes nothing and announces nothing:
+ * the response says `changed: false`, and no automation listening for a
+ * change hears one that did not happen.
+ *
+ * `lifecycleStage: null` CLEARS the stage (AGL-2804). A facet is the
+ * server's to write, so "not placed yet" comes through the route that owns
+ * the stage rather than as a client-direct delete, and it is refused to a
+ * plan without the suite the way a move is. There is no event for "no
+ * stage", so a clear announces nothing; an empty string names no stage and
+ * is refused like any other the list does not have.
+ *
+ * The contact is looked up by id and then checked against `visibleTo`,
+ * because the Admin SDK evaluates no rules: a caller who can edit site A
+ * must not be able to restage a contact only site B holds by guessing its
+ * id, and the scoped query the list uses is not available to a `doc()` read.
+ */
+export declare const contactStageHandler: PluginApiHandler;
+/**
+ * What the create route says when the band refused (AGL-2596).
+ *
+ * The contacts list's own alert, in the past tense: the list says new
+ * visitors are "no longer captured", and this says the one contact the
+ * reader just tried to add was not. The remedy is the same sentence in both
+ * places, so a reader who sees one and then the other is told one thing.
+ */
+export declare const CONTACT_BAND_FULL_MESSAGE: string;
+/**
+ * `POST /api/crm/contacts-create` — a person added by hand (AGL-2596).
+ *
+ * Body: `{ hostId, email, name?, phone?, jobTitle?, companyName?,
+ * companyId?, address?, ownerUid?, lifecycleStage?, tags?,
+ * marketingConsent? }`. Answers `{ contactId, created }`: `created` is
+ * false when the address already belonged to somebody, in which case what
+ * was typed MERGES into the existing row — the dedupe the shared address
+ * book exists for, and the reason a second "create" of one person is not
+ * an error.
+ *
+ * ## Who may call it
+ *
+ * The caller's ID token, then `data.manage` on the site's org — the same key
+ * the console surface itself is gated on, resolved through the same
+ * three-layer permission read the members route uses. A scoped member is
+ * admitted only for a site they reach: the rules would refuse a browser
+ * write outside their tokens, and a server route that admitted it would be
+ * a way round the rules rather than a service in front of them.
+ *
+ * ## What it refuses, and how
+ *
+ * A malformed email or phone number is a 400 with a sentence the drawer can
+ * show under the field. The band is a 409 carrying the list's own wording:
+ * it is not a bad request and not a server fault, it is the plan saying no,
+ * and the drawer relays the sentence rather than inventing one.
+ *
+ * ## The company (AGL-2613)
+ *
+ * `companyId` is the picker's choice, and it is checked before anything is
+ * written: the company has to exist and be visible to the capturing site's
+ * scope, or a caller could file a person under a record they cannot open —
+ * the same refusal the lead conversion makes. It reaches the upsert as
+ * `facet.companyId`, which is where the link is kept in step with its mirror
+ * and the company's contacts count; a merge onto somebody already at another
+ * company is a MOVE there, not a second link. The stored company's own name
+ * is what is echoed, over whatever the client sent, because the name on the
+ * record is the company's and not the form's.
+ *
+ * ## What it writes beyond the upsert
+ *
+ * `upsertHostContact` takes the profile — phone, title, address, owner,
+ * stage, company — and writes it into the capturing group's facet. The two
+ * things it does not take are written here by DOTTED path afterwards: the
+ * tags, which union into whatever the person already carried, and the
+ * company name — the picked company's, or free text for a person filed
+ * under a name no company record carries yet. Dotted paths because this is
+ * an `update()`, and only an update reads a dot as a path — a nested object
+ * here would replace the facet map and take every other holder's records
+ * with it.
+ */
+export declare const crmContactsCreateHandler: PluginApiHandler;
+/** Console API registration, named in `plugins.config.json` as `consoleApi`. */
+export declare function registerCrmConsoleApi(): void;