@aglyn/plugins-crm 1.0.0-beta.164 → 1.0.0-beta.165

package/src/lib/hooks/use-campaign-filing-log.js

@@ -0,0 +1,91 @@
+/**
+ * @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.
+ */ 'use client';
+import { _ as _extends } from "@swc/helpers/_/_extends";
+import { CRM_COLLECTIONS, consentGroupForHost, createResourceUid, crmScopeTokens } from "@aglyn/aglyn";
+import { useFirestore, useUser, useUserName } from "@aglyn/tenant-feature-instance";
+import { collection, doc, setDoc } from "firebase/firestore";
+import { useCallback } from "react";
+import { buildCampaignFilingActivity } from "../model/campaign-filing-activity.js";
+/**
+ * FILES A MEMBER'S FILING ON THE RECORD'S TIMELINE (AGL-3274), from the
+ * console.
+ *
+ * The lead's Campaigns card and the Leads list's bulk bar write the
+ * membership client-direct — a one-field update the rules already admit —
+ * so the entry that records it is written the same way, into the org's
+ * activity collection the log dialog writes, with the scope a record made
+ * on this site carries (`crmScopeTokens`), the signed-in member as author,
+ * and the CRM's own id as the filing plugin.
+ *
+ * Bookkeeping beside the act: the membership has landed by the time this
+ * runs, so a write that fails is logged and the filing stands — the card
+ * shows the campaigns from the document, not from the timeline.
+ */ export function useCampaignFilingLog(input) {
+    const { orgId, hostId, org } = input;
+    const firestore = useFirestore();
+    const { data: user } = useUser();
+    const authorName = useUserName();
+    const uid = user == null ? void 0 : user.uid;
+    return useCallback(async (link, change)=>{
+        var _change_filed, _change_removed;
+        if (!orgId || !hostId || !uid) return;
+        const entries = [
+            ...((_change_filed = change.filed) != null ? _change_filed : []).map((campaign)=>({
+                    action: 'filed',
+                    campaign
+                })),
+            ...((_change_removed = change.removed) != null ? _change_removed : []).map((campaign)=>({
+                    action: 'removed',
+                    campaign
+                }))
+        ];
+        if (!entries.length) return;
+        const visibleTo = crmScopeTokens(org, consentGroupForHost(org, hostId));
+        const atMs = Date.now();
+        const activities = collection(firestore, 'orgs', orgId, CRM_COLLECTIONS.activities);
+        for (const entry of entries){
+            try {
+                // Named by the platform's own id, as every console resource is.
+                await setDoc(doc(activities, createResourceUid()), _extends({}, buildCampaignFilingActivity({
+                    action: entry.action,
+                    campaign: entry.campaign,
+                    link,
+                    hostId,
+                    visibleTo,
+                    atMs,
+                    byUid: uid,
+                    byName: authorName || null
+                }), {
+                    createdAt: new Date(),
+                    updatedAt: new Date()
+                }));
+            } catch (error) {
+                console.error('[crm] the filing could not be written on the timeline', error);
+            }
+        }
+    }, [
+        firestore,
+        orgId,
+        hostId,
+        org,
+        uid,
+        authorName
+    ]);
+}
+export default useCampaignFilingLog;
+
+//# sourceMappingURL=use-campaign-filing-log.js.map

package/src/lib/hooks/use-campaign-filing-log.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/crm/src/lib/hooks/use-campaign-filing-log.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'use client'\n\nimport {\n  CRM_COLLECTIONS,\n  consentGroupForHost,\n  createResourceUid,\n  crmScopeTokens,\n  type CrmActivityLink,\n} from '@aglyn/aglyn'\nimport { useFirestore, useUser, useUserName } from '@aglyn/tenant-feature-instance'\nimport { collection, doc, setDoc } from 'firebase/firestore'\nimport { useCallback } from 'react'\nimport {\n  buildCampaignFilingActivity,\n  type CampaignFilingRef,\n} from '../model/campaign-filing-activity'\n\n/** What one surface's save changed, by campaign, with the names it showed. */\nexport interface CampaignFilingChange {\n  filed?: readonly CampaignFilingRef[]\n  removed?: readonly CampaignFilingRef[]\n}\n\n/**\n * FILES A MEMBER'S FILING ON THE RECORD'S TIMELINE (AGL-3274), from the\n * console.\n *\n * The lead's Campaigns card and the Leads list's bulk bar write the\n * membership client-direct — a one-field update the rules already admit —\n * so the entry that records it is written the same way, into the org's\n * activity collection the log dialog writes, with the scope a record made\n * on this site carries (`crmScopeTokens`), the signed-in member as author,\n * and the CRM's own id as the filing plugin.\n *\n * Bookkeeping beside the act: the membership has landed by the time this\n * runs, so a write that fails is logged and the filing stands — the card\n * shows the campaigns from the document, not from the timeline.\n */\nexport function useCampaignFilingLog(input: {\n  orgId: string | null | undefined\n  /** The site the entry carries as provenance: the lead's, or the contact's viewing site. */\n  hostId: string | null | undefined\n  org: Record<string, unknown> | null | undefined\n}) {\n  const { orgId, hostId, org } = input\n  const firestore = useFirestore()\n  const { data: user } = useUser()\n  const authorName = useUserName()\n  const uid = user?.uid\n\n  return useCallback(\n    async (link: CrmActivityLink, change: CampaignFilingChange): Promise<void> => {\n      if (!orgId || !hostId || !uid) return\n      const entries = [\n        ...(change.filed ?? []).map((campaign) => ({ action: 'filed' as const, campaign })),\n        ...(change.removed ?? []).map((campaign) => ({ action: 'removed' as const, campaign })),\n      ]\n      if (!entries.length) return\n      const visibleTo = crmScopeTokens(org, consentGroupForHost(org, hostId))\n      const atMs = Date.now()\n      const activities = collection(firestore, 'orgs', orgId, CRM_COLLECTIONS.activities)\n      for (const entry of entries) {\n        try {\n          // Named by the platform's own id, as every console resource is.\n          await setDoc(doc(activities, createResourceUid()), {\n            ...buildCampaignFilingActivity({\n              action: entry.action,\n              campaign: entry.campaign,\n              link,\n              hostId,\n              visibleTo,\n              atMs,\n              byUid: uid,\n              byName: authorName || null,\n            }),\n            createdAt: new Date(),\n            updatedAt: new Date(),\n          })\n        } catch (error) {\n          console.error('[crm] the filing could not be written on the timeline', error)\n        }\n      }\n    },\n    [firestore, orgId, hostId, org, uid, authorName],\n  )\n}\n\nexport default useCampaignFilingLog\n"],"names":["CRM_COLLECTIONS","consentGroupForHost","createResourceUid","crmScopeTokens","useFirestore","useUser","useUserName","collection","doc","setDoc","useCallback","buildCampaignFilingActivity","useCampaignFilingLog","input","orgId","hostId","org","firestore","data","user","authorName","uid","link","change","entries","filed","map","campaign","action","removed","length","visibleTo","atMs","Date","now","activities","entry","byUid","byName","createdAt","updatedAt","error","console"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GACD;;AAEA,SACEA,eAAe,EACfC,mBAAmB,EACnBC,iBAAiB,EACjBC,cAAc,QAET,eAAc;AACrB,SAASC,YAAY,EAAEC,OAAO,EAAEC,WAAW,QAAQ,iCAAgC;AACnF,SAASC,UAAU,EAAEC,GAAG,EAAEC,MAAM,QAAQ,qBAAoB;AAC5D,SAASC,WAAW,QAAQ,QAAO;AACnC,SACEC,2BAA2B,QAEtB,uCAAmC;AAQ1C;;;;;;;;;;;;;;CAcC,GACD,OAAO,SAASC,qBAAqBC,KAKpC;IACC,MAAM,EAAEC,KAAK,EAAEC,MAAM,EAAEC,GAAG,EAAE,GAAGH;IAC/B,MAAMI,YAAYb;IAClB,MAAM,EAAEc,MAAMC,IAAI,EAAE,GAAGd;IACvB,MAAMe,aAAad;IACnB,MAAMe,MAAMF,wBAAAA,KAAME,GAAG;IAErB,OAAOX,YACL,OAAOY,MAAuBC;YAGtBA,eACAA;QAHN,IAAI,CAACT,SAAS,CAACC,UAAU,CAACM,KAAK;QAC/B,MAAMG,UAAU;eACX,EAACD,gBAAAA,OAAOE,KAAK,YAAZF,gBAAgB,EAAE,EAAEG,GAAG,CAAC,CAACC,WAAc,CAAA;oBAAEC,QAAQ;oBAAkBD;gBAAS,CAAA;eAC7E,EAACJ,kBAAAA,OAAOM,OAAO,YAAdN,kBAAkB,EAAE,EAAEG,GAAG,CAAC,CAACC,WAAc,CAAA;oBAAEC,QAAQ;oBAAoBD;gBAAS,CAAA;SACrF;QACD,IAAI,CAACH,QAAQM,MAAM,EAAE;QACrB,MAAMC,YAAY5B,eAAea,KAAKf,oBAAoBe,KAAKD;QAC/D,MAAMiB,OAAOC,KAAKC,GAAG;QACrB,MAAMC,aAAa5B,WAAWU,WAAW,QAAQH,OAAOd,gBAAgBmC,UAAU;QAClF,KAAK,MAAMC,SAASZ,QAAS;YAC3B,IAAI;gBACF,gEAAgE;gBAChE,MAAMf,OAAOD,IAAI2B,YAAYjC,sBAAsB,aAC9CS,4BAA4B;oBAC7BiB,QAAQQ,MAAMR,MAAM;oBACpBD,UAAUS,MAAMT,QAAQ;oBACxBL;oBACAP;oBACAgB;oBACAC;oBACAK,OAAOhB;oBACPiB,QAAQlB,cAAc;gBACxB;oBACAmB,WAAW,IAAIN;oBACfO,WAAW,IAAIP;;YAEnB,EAAE,OAAOQ,OAAO;gBACdC,QAAQD,KAAK,CAAC,yDAAyDA;YACzE;QACF;IACF,GACA;QAACxB;QAAWH;QAAOC;QAAQC;QAAKK;QAAKD;KAAW;AAEpD;AAEA,eAAeR,qBAAoB"}

package/src/lib/model/campaign-filing-activity.d.ts

@@ -0,0 +1,82 @@
+/**
+ * @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 { CrmActivity, CrmActivityLink, ScopeToken } from '@aglyn/aglyn';
+/**
+ * WHAT A FILING WRITES ON THE RECORD'S TIMELINE (AGL-3274).
+ *
+ * A lead or a contact filed under a campaign — from its own page, the bulk
+ * bar, the New lead drawer, or by conversion carrying a lead's campaigns
+ * onto the contact it became — showed nothing of it in Activity, so the
+ * timeline read "email sent" with no line for the act that put the person
+ * in the campaign in the first place. Every door now files one entry per
+ * campaign changed, and this module is the one place their shape lives:
+ * the client hook and the server helper both build the document here, so
+ * an entry filed from the page and one filed by the conversion read alike.
+ *
+ * ## A `note`, not a kind of its own
+ *
+ * The timeline's kinds are what a PERSON logs — call, email, meeting, note
+ * — and a filing is bookkeeping beside them, the way a sequence's "Enrolled
+ * in" entry is. A `filing` kind would need its own label, glyph, report
+ * column and a place in the log dialog where a member could log one by
+ * hand, which is the one thing a filing must never be. So it is a note that
+ * names its author (the member, or the conversion), carries the CRM's own
+ * id as `sourcePluginId` the way a sequence's entries carry Outreach's, and
+ * names the campaign twice: by name in the body, by id in `campaignId`.
+ */
+/** The kind every filing entry is filed as. */
+export declare const CAMPAIGN_FILING_ACTIVITY_KIND: "note";
+/** What the entry says was done: put in the campaign, or taken out of it. */
+export type CampaignFilingAction = 'filed' | 'removed';
+/** A campaign as a filing entry names it: the container's id and its name at the time. */
+export interface CampaignFilingRef {
+    id: string;
+    name: string;
+}
+/**
+ * The author a conversion's carry signs its entries with: nobody in the
+ * room typed it, and "A team member" — the timeline's word for an
+ * anonymous entry — would credit a person with what the conversion did.
+ */
+export declare const CAMPAIGN_FILING_CARRY_BY_NAME = "Lead conversion";
+/** The one line of the entry, as the timeline shows it. */
+export declare function campaignFilingBody(action: CampaignFilingAction, campaignName: string): string;
+/**
+ * The membership a save changed, as the entries it owes: one `filed` per
+ * id the save added, one `removed` per id it dropped. Order-insensitive,
+ * like `campaignMembershipUnchanged`; a reorder owes nothing.
+ */
+export declare function campaignFilingChanges(before: readonly string[], after: readonly string[]): {
+    added: string[];
+    removed: string[];
+};
+export interface CampaignFilingActivityInput {
+    action: CampaignFilingAction;
+    campaign: CampaignFilingRef;
+    link: CrmActivityLink;
+    /** The site the entry carries as provenance — the lead's site, the contact's viewing site. */
+    hostId: string;
+    visibleTo: readonly ScopeToken[];
+    /** When it happened, epoch ms. */
+    atMs: number;
+    /** The member who did it, or `''` for the conversion. */
+    byUid: string;
+    /** The member's name as it read, or the carry's fixed author; absent rather than blank. */
+    byName?: string | null;
+}
+/** The document a filing entry is stored as, minus the timestamps the writer stamps. */
+export declare function buildCampaignFilingActivity(input: CampaignFilingActivityInput): CrmActivity;

package/src/lib/model/campaign-filing-activity.js

@@ -0,0 +1,88 @@
+/**
+ * @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 { _ as _extends } from "@swc/helpers/_/_extends";
+import { BUNDLE_ID } from "../constants/bundle-common.js";
+/**
+ * WHAT A FILING WRITES ON THE RECORD'S TIMELINE (AGL-3274).
+ *
+ * A lead or a contact filed under a campaign — from its own page, the bulk
+ * bar, the New lead drawer, or by conversion carrying a lead's campaigns
+ * onto the contact it became — showed nothing of it in Activity, so the
+ * timeline read "email sent" with no line for the act that put the person
+ * in the campaign in the first place. Every door now files one entry per
+ * campaign changed, and this module is the one place their shape lives:
+ * the client hook and the server helper both build the document here, so
+ * an entry filed from the page and one filed by the conversion read alike.
+ *
+ * ## A `note`, not a kind of its own
+ *
+ * The timeline's kinds are what a PERSON logs — call, email, meeting, note
+ * — and a filing is bookkeeping beside them, the way a sequence's "Enrolled
+ * in" entry is. A `filing` kind would need its own label, glyph, report
+ * column and a place in the log dialog where a member could log one by
+ * hand, which is the one thing a filing must never be. So it is a note that
+ * names its author (the member, or the conversion), carries the CRM's own
+ * id as `sourcePluginId` the way a sequence's entries carry Outreach's, and
+ * names the campaign twice: by name in the body, by id in `campaignId`.
+ */ /** The kind every filing entry is filed as. */ export const CAMPAIGN_FILING_ACTIVITY_KIND = 'note';
+/**
+ * The author a conversion's carry signs its entries with: nobody in the
+ * room typed it, and "A team member" — the timeline's word for an
+ * anonymous entry — would credit a person with what the conversion did.
+ */ export const CAMPAIGN_FILING_CARRY_BY_NAME = 'Lead conversion';
+/** The one line of the entry, as the timeline shows it. */ export function campaignFilingBody(action, campaignName) {
+    const name = campaignName.trim() || 'a campaign';
+    return action === 'filed' ? `Filed under ${name}` : `Removed from ${name}`;
+}
+/**
+ * The membership a save changed, as the entries it owes: one `filed` per
+ * id the save added, one `removed` per id it dropped. Order-insensitive,
+ * like `campaignMembershipUnchanged`; a reorder owes nothing.
+ */ export function campaignFilingChanges(before, after) {
+    return {
+        added: after.filter((id)=>!before.includes(id)),
+        removed: before.filter((id)=>!after.includes(id))
+    };
+}
+/** The document a filing entry is stored as, minus the timestamps the writer stamps. */ export function buildCampaignFilingActivity(input) {
+    var _input_byName;
+    const byName = String((_input_byName = input.byName) != null ? _input_byName : '').trim();
+    return _extends({
+        kind: CAMPAIGN_FILING_ACTIVITY_KIND,
+        body: campaignFilingBody(input.action, input.campaign.name),
+        atMs: input.atMs,
+        byUid: input.byUid
+    }, byName ? {
+        byName
+    } : {}, input.link.contactId ? {
+        contactId: input.link.contactId
+    } : {}, input.link.companyId ? {
+        companyId: input.link.companyId
+    } : {}, input.link.dealId ? {
+        dealId: input.link.dealId
+    } : {}, input.link.leadId ? {
+        leadId: input.link.leadId
+    } : {}, {
+        hostId: input.hostId,
+        visibleTo: [
+            ...input.visibleTo
+        ],
+        sourcePluginId: BUNDLE_ID,
+        campaignId: input.campaign.id
+    });
+}
+
+//# sourceMappingURL=campaign-filing-activity.js.map

package/src/lib/model/campaign-filing-activity.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/crm/src/lib/model/campaign-filing-activity.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 { CrmActivity, CrmActivityLink, ScopeToken } from '@aglyn/aglyn'\nimport { BUNDLE_ID } from '../constants/bundle-common'\n\n/**\n * WHAT A FILING WRITES ON THE RECORD'S TIMELINE (AGL-3274).\n *\n * A lead or a contact filed under a campaign — from its own page, the bulk\n * bar, the New lead drawer, or by conversion carrying a lead's campaigns\n * onto the contact it became — showed nothing of it in Activity, so the\n * timeline read \"email sent\" with no line for the act that put the person\n * in the campaign in the first place. Every door now files one entry per\n * campaign changed, and this module is the one place their shape lives:\n * the client hook and the server helper both build the document here, so\n * an entry filed from the page and one filed by the conversion read alike.\n *\n * ## A `note`, not a kind of its own\n *\n * The timeline's kinds are what a PERSON logs — call, email, meeting, note\n * — and a filing is bookkeeping beside them, the way a sequence's \"Enrolled\n * in\" entry is. A `filing` kind would need its own label, glyph, report\n * column and a place in the log dialog where a member could log one by\n * hand, which is the one thing a filing must never be. So it is a note that\n * names its author (the member, or the conversion), carries the CRM's own\n * id as `sourcePluginId` the way a sequence's entries carry Outreach's, and\n * names the campaign twice: by name in the body, by id in `campaignId`.\n */\n\n/** The kind every filing entry is filed as. */\nexport const CAMPAIGN_FILING_ACTIVITY_KIND = 'note' as const\n\n/** What the entry says was done: put in the campaign, or taken out of it. */\nexport type CampaignFilingAction = 'filed' | 'removed'\n\n/** A campaign as a filing entry names it: the container's id and its name at the time. */\nexport interface CampaignFilingRef {\n  id: string\n  name: string\n}\n\n/**\n * The author a conversion's carry signs its entries with: nobody in the\n * room typed it, and \"A team member\" — the timeline's word for an\n * anonymous entry — would credit a person with what the conversion did.\n */\nexport const CAMPAIGN_FILING_CARRY_BY_NAME = 'Lead conversion'\n\n/** The one line of the entry, as the timeline shows it. */\nexport function campaignFilingBody(action: CampaignFilingAction, campaignName: string): string {\n  const name = campaignName.trim() || 'a campaign'\n  return action === 'filed' ? `Filed under ${name}` : `Removed from ${name}`\n}\n\n/**\n * The membership a save changed, as the entries it owes: one `filed` per\n * id the save added, one `removed` per id it dropped. Order-insensitive,\n * like `campaignMembershipUnchanged`; a reorder owes nothing.\n */\nexport function campaignFilingChanges(\n  before: readonly string[],\n  after: readonly string[],\n): { added: string[]; removed: string[] } {\n  return {\n    added: after.filter((id) => !before.includes(id)),\n    removed: before.filter((id) => !after.includes(id)),\n  }\n}\n\nexport interface CampaignFilingActivityInput {\n  action: CampaignFilingAction\n  campaign: CampaignFilingRef\n  link: CrmActivityLink\n  /** The site the entry carries as provenance — the lead's site, the contact's viewing site. */\n  hostId: string\n  visibleTo: readonly ScopeToken[]\n  /** When it happened, epoch ms. */\n  atMs: number\n  /** The member who did it, or `''` for the conversion. */\n  byUid: string\n  /** The member's name as it read, or the carry's fixed author; absent rather than blank. */\n  byName?: string | null\n}\n\n/** The document a filing entry is stored as, minus the timestamps the writer stamps. */\nexport function buildCampaignFilingActivity(input: CampaignFilingActivityInput): CrmActivity {\n  const byName = String(input.byName ?? '').trim()\n  return {\n    kind: CAMPAIGN_FILING_ACTIVITY_KIND,\n    body: campaignFilingBody(input.action, input.campaign.name),\n    atMs: input.atMs,\n    byUid: input.byUid,\n    ...(byName ? { byName } : {}),\n    ...(input.link.contactId ? { contactId: input.link.contactId } : {}),\n    ...(input.link.companyId ? { companyId: input.link.companyId } : {}),\n    ...(input.link.dealId ? { dealId: input.link.dealId } : {}),\n    ...(input.link.leadId ? { leadId: input.link.leadId } : {}),\n    hostId: input.hostId,\n    visibleTo: [...input.visibleTo],\n    sourcePluginId: BUNDLE_ID,\n    campaignId: input.campaign.id,\n  }\n}\n"],"names":["BUNDLE_ID","CAMPAIGN_FILING_ACTIVITY_KIND","CAMPAIGN_FILING_CARRY_BY_NAME","campaignFilingBody","action","campaignName","name","trim","campaignFilingChanges","before","after","added","filter","id","includes","removed","buildCampaignFilingActivity","input","byName","String","kind","body","campaign","atMs","byUid","link","contactId","companyId","dealId","leadId","hostId","visibleTo","sourcePluginId","campaignId"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC;AAGD,SAASA,SAAS,QAAQ,gCAA4B;AAEtD;;;;;;;;;;;;;;;;;;;;;;CAsBC,GAED,6CAA6C,GAC7C,OAAO,MAAMC,gCAAgC,OAAe;AAW5D;;;;CAIC,GACD,OAAO,MAAMC,gCAAgC,kBAAiB;AAE9D,yDAAyD,GACzD,OAAO,SAASC,mBAAmBC,MAA4B,EAAEC,YAAoB;IACnF,MAAMC,OAAOD,aAAaE,IAAI,MAAM;IACpC,OAAOH,WAAW,UAAU,CAAC,YAAY,EAAEE,MAAM,GAAG,CAAC,aAAa,EAAEA,MAAM;AAC5E;AAEA;;;;CAIC,GACD,OAAO,SAASE,sBACdC,MAAyB,EACzBC,KAAwB;IAExB,OAAO;QACLC,OAAOD,MAAME,MAAM,CAAC,CAACC,KAAO,CAACJ,OAAOK,QAAQ,CAACD;QAC7CE,SAASN,OAAOG,MAAM,CAAC,CAACC,KAAO,CAACH,MAAMI,QAAQ,CAACD;IACjD;AACF;AAiBA,sFAAsF,GACtF,OAAO,SAASG,4BAA4BC,KAAkC;QACtDA;IAAtB,MAAMC,SAASC,QAAOF,gBAAAA,MAAMC,MAAM,YAAZD,gBAAgB,IAAIV,IAAI;IAC9C,OAAO;QACLa,MAAMnB;QACNoB,MAAMlB,mBAAmBc,MAAMb,MAAM,EAAEa,MAAMK,QAAQ,CAAChB,IAAI;QAC1DiB,MAAMN,MAAMM,IAAI;QAChBC,OAAOP,MAAMO,KAAK;OACdN,SAAS;QAAEA;IAAO,IAAI,CAAC,GACvBD,MAAMQ,IAAI,CAACC,SAAS,GAAG;QAAEA,WAAWT,MAAMQ,IAAI,CAACC,SAAS;IAAC,IAAI,CAAC,GAC9DT,MAAMQ,IAAI,CAACE,SAAS,GAAG;QAAEA,WAAWV,MAAMQ,IAAI,CAACE,SAAS;IAAC,IAAI,CAAC,GAC9DV,MAAMQ,IAAI,CAACG,MAAM,GAAG;QAAEA,QAAQX,MAAMQ,IAAI,CAACG,MAAM;IAAC,IAAI,CAAC,GACrDX,MAAMQ,IAAI,CAACI,MAAM,GAAG;QAAEA,QAAQZ,MAAMQ,IAAI,CAACI,MAAM;IAAC,IAAI,CAAC;QACzDC,QAAQb,MAAMa,MAAM;QACpBC,WAAW;eAAId,MAAMc,SAAS;SAAC;QAC/BC,gBAAgBhC;QAChBiC,YAAYhB,MAAMK,QAAQ,CAACT,EAAE;;AAEjC"}

package/src/lib/server/campaign-filing-activity.d.ts

@@ -0,0 +1,79 @@
+/**
+ * @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 CrmActivityLink } from '@aglyn/aglyn/app-utils/crm';
+import { type CampaignFilingAction, type CampaignFilingRef } from '../model/campaign-filing-activity';
+/**
+ * FILES A FILING ON THE RECORD'S TIMELINE (AGL-3274), from the server.
+ *
+ * The two doors that file a lead under a campaign on the server — the
+ * `leads-create` route behind the New lead drawer, and the conversion's
+ * carry of a lead's campaigns onto the contact — write the entry through
+ * this, with the scope a record made on the site carries and the CRM's
+ * own id as the filing plugin, exactly as the console's hook writes one.
+ *
+ * ## Once, when the caller says so
+ *
+ * A member's act is an act each time, and the route's entries are named
+ * by `createResourceUid()`, the id every console resource carries. The
+ * conversion carry runs from a seam every converting
+ * door reaches, and a door that runs twice must not file twice — so a
+ * caller that hands in a `dedupeKey` gets a keyed `create()`, and the
+ * second run finds its own entry and writes nothing. The key is hashed
+ * under the CRM's id the way the timeline seam hashes a plugin's, so no
+ * caller's raw key becomes a document id.
+ *
+ * ## Never throws
+ *
+ * The membership has landed by the time this runs; an entry that could
+ * not be filed is logged, and the record's page shows the campaigns from
+ * the document either way. A record at its activity ceiling is refused
+ * before anything is written, in the same breath.
+ */
+type Firestore = FirebaseFirestore.Firestore;
+export interface CampaignFilingActivitiesInput {
+    orgId: string;
+    /**
+     * The organization document, when the caller already holds it — the
+     * scope tokens read `defaultResourceScope` and the consent groups off
+     * it. Read here otherwise.
+     */
+    org?: Record<string, unknown> | null;
+    /** The site the entry carries as provenance. */
+    hostId: string;
+    link: CrmActivityLink;
+    action: CampaignFilingAction;
+    campaigns: readonly CampaignFilingRef[];
+    atMs: number;
+    /** The member who did it, or `''` for the conversion. */
+    byUid: string;
+    byName?: string | null;
+    /**
+     * A key that files each campaign's entry once across runs — the carry's
+     * — or nothing for a member's act, which is new each time.
+     */
+    dedupeKey?: string | null;
+}
+/** The document id a keyed entry files under: the CRM's namespace, never a raw key. */
+export declare function campaignFilingActivityId(key: string): string;
+/**
+ * The names of a site's campaigns, by id, for the entries that name them.
+ * A container that is gone answers its id, so the entry still says which.
+ */
+export declare function siteCampaignRefs(firestore: Firestore, hostId: string, campaignIds: readonly string[]): Promise<CampaignFilingRef[]>;
+/** Files one entry per campaign; answers how many were written. */
+export declare function fileCampaignFilingActivities(firestore: Firestore, input: CampaignFilingActivitiesInput): Promise<number>;
+export {};

package/src/lib/server/campaign-filing-activity.js

@@ -0,0 +1,93 @@
+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.
+ */ import { consentGroupForHost } from "@aglyn/aglyn/app-utils/consent-groups";
+import { createResourceUid } from "@aglyn/aglyn/app-utils/create-resource-uid";
+import { CRM_COLLECTIONS, crmActivityLogHasRoom, crmScopeTokens } from "@aglyn/aglyn/app-utils/crm";
+import { countCrmActivitiesForRecord } from "@aglyn/tenant-data-admin/server/crm-records";
+import { createHash } from "crypto";
+import { FieldValue } from "firebase-admin/firestore";
+import { BUNDLE_ID } from "../constants/bundle-common.js";
+import { buildCampaignFilingActivity } from "../model/campaign-filing-activity.js";
+/** The document id a keyed entry files under: the CRM's namespace, never a raw key. */ export function campaignFilingActivityId(key) {
+    return `plg_${createHash('sha256').update(`${BUNDLE_ID}:${key}`).digest('hex').slice(0, 28)}`;
+}
+/** gRPC `ALREADY_EXISTS`, which `create()` rejects with when the document is there. */ const ALREADY_EXISTS = 6;
+/**
+ * The names of a site's campaigns, by id, for the entries that name them.
+ * A container that is gone answers its id, so the entry still says which.
+ */ export async function siteCampaignRefs(firestore, hostId, campaignIds) {
+    if (!campaignIds.length) return [];
+    const containers = firestore.collection('hosts').doc(hostId).collection('emailCampaigns');
+    const found = await firestore.getAll(...campaignIds.map((id)=>containers.doc(id)));
+    return campaignIds.map((id, index)=>{
+        var _ref;
+        var _found_index;
+        return {
+            id,
+            name: String((_ref = (_found_index = found[index]) == null ? void 0 : _found_index.get('name')) != null ? _ref : '').trim() || id
+        };
+    });
+}
+/** Files one entry per campaign; answers how many were written. */ export async function fileCampaignFilingActivities(firestore, input) {
+    if (!input.campaigns.length) return 0;
+    try {
+        var _ref, _input_org;
+        const orgRef = firestore.collection('orgs').doc(input.orgId);
+        const org = (_ref = (_input_org = input.org) != null ? _input_org : (await orgRef.get()).data()) != null ? _ref : null;
+        const visibleTo = crmScopeTokens(org, consentGroupForHost(org, input.hostId));
+        if (!crmActivityLogHasRoom(await countCrmActivitiesForRecord(orgRef, input.link))) {
+            console.warn('[crm] the filing was not written on the timeline: the record’s log is full', input.link);
+            return 0;
+        }
+        const activities = orgRef.collection(CRM_COLLECTIONS.activities);
+        let written = 0;
+        for (const campaign of input.campaigns){
+            var _input_byName;
+            const entry = _extends({}, buildCampaignFilingActivity({
+                action: input.action,
+                campaign,
+                link: input.link,
+                hostId: input.hostId,
+                visibleTo,
+                atMs: input.atMs,
+                byUid: input.byUid,
+                byName: (_input_byName = input.byName) != null ? _input_byName : null
+            }), {
+                createdAt: FieldValue.serverTimestamp(),
+                updatedAt: FieldValue.serverTimestamp()
+            });
+            if (input.dedupeKey) {
+                try {
+                    await activities.doc(campaignFilingActivityId(`${input.dedupeKey}:${campaign.id}`)).create(entry);
+                    written += 1;
+                } catch (error) {
+                    if ((error == null ? void 0 : error.code) !== ALREADY_EXISTS) throw error;
+                }
+            } else {
+                // A member's act, new each time, named by the platform's own id.
+                await activities.doc(createResourceUid()).create(entry);
+                written += 1;
+            }
+        }
+        return written;
+    } catch (error) {
+        console.error('[crm] the filing could not be written on the timeline', input.link, error);
+        return 0;
+    }
+}
+
+//# sourceMappingURL=campaign-filing-activity.js.map

package/src/lib/server/campaign-filing-activity.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/crm/src/lib/server/campaign-filing-activity.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 { consentGroupForHost } from '@aglyn/aglyn/app-utils/consent-groups'\nimport { createResourceUid } from '@aglyn/aglyn/app-utils/create-resource-uid'\nimport {\n  CRM_COLLECTIONS,\n  crmActivityLogHasRoom,\n  crmScopeTokens,\n  type CrmActivityLink,\n} from '@aglyn/aglyn/app-utils/crm'\nimport { countCrmActivitiesForRecord } from '@aglyn/tenant-data-admin/server/crm-records'\nimport { createHash } from 'crypto'\nimport { FieldValue } from 'firebase-admin/firestore'\nimport { BUNDLE_ID } from '../constants/bundle-common'\nimport {\n  buildCampaignFilingActivity,\n  type CampaignFilingAction,\n  type CampaignFilingRef,\n} from '../model/campaign-filing-activity'\n\n/**\n * FILES A FILING ON THE RECORD'S TIMELINE (AGL-3274), from the server.\n *\n * The two doors that file a lead under a campaign on the server — the\n * `leads-create` route behind the New lead drawer, and the conversion's\n * carry of a lead's campaigns onto the contact — write the entry through\n * this, with the scope a record made on the site carries and the CRM's\n * own id as the filing plugin, exactly as the console's hook writes one.\n *\n * ## Once, when the caller says so\n *\n * A member's act is an act each time, and the route's entries are named\n * by `createResourceUid()`, the id every console resource carries. The\n * conversion carry runs from a seam every converting\n * door reaches, and a door that runs twice must not file twice — so a\n * caller that hands in a `dedupeKey` gets a keyed `create()`, and the\n * second run finds its own entry and writes nothing. The key is hashed\n * under the CRM's id the way the timeline seam hashes a plugin's, so no\n * caller's raw key becomes a document id.\n *\n * ## Never throws\n *\n * The membership has landed by the time this runs; an entry that could\n * not be filed is logged, and the record's page shows the campaigns from\n * the document either way. A record at its activity ceiling is refused\n * before anything is written, in the same breath.\n */\n\ntype Firestore = FirebaseFirestore.Firestore\n\nexport interface CampaignFilingActivitiesInput {\n  orgId: string\n  /**\n   * The organization document, when the caller already holds it — the\n   * scope tokens read `defaultResourceScope` and the consent groups off\n   * it. Read here otherwise.\n   */\n  org?: Record<string, unknown> | null\n  /** The site the entry carries as provenance. */\n  hostId: string\n  link: CrmActivityLink\n  action: CampaignFilingAction\n  campaigns: readonly CampaignFilingRef[]\n  atMs: number\n  /** The member who did it, or `''` for the conversion. */\n  byUid: string\n  byName?: string | null\n  /**\n   * A key that files each campaign's entry once across runs — the carry's\n   * — or nothing for a member's act, which is new each time.\n   */\n  dedupeKey?: string | null\n}\n\n/** The document id a keyed entry files under: the CRM's namespace, never a raw key. */\nexport function campaignFilingActivityId(key: string): string {\n  return `plg_${createHash('sha256').update(`${BUNDLE_ID}:${key}`).digest('hex').slice(0, 28)}`\n}\n\n/** gRPC `ALREADY_EXISTS`, which `create()` rejects with when the document is there. */\nconst ALREADY_EXISTS = 6\n\n/**\n * The names of a site's campaigns, by id, for the entries that name them.\n * A container that is gone answers its id, so the entry still says which.\n */\nexport async function siteCampaignRefs(\n  firestore: Firestore,\n  hostId: string,\n  campaignIds: readonly string[],\n): Promise<CampaignFilingRef[]> {\n  if (!campaignIds.length) return []\n  const containers = firestore.collection('hosts').doc(hostId).collection('emailCampaigns')\n  const found = await firestore.getAll(...campaignIds.map((id) => containers.doc(id)))\n  return campaignIds.map((id, index) => ({\n    id,\n    name: String(found[index]?.get('name') ?? '').trim() || id,\n  }))\n}\n\n/** Files one entry per campaign; answers how many were written. */\nexport async function fileCampaignFilingActivities(\n  firestore: Firestore,\n  input: CampaignFilingActivitiesInput,\n): Promise<number> {\n  if (!input.campaigns.length) return 0\n  try {\n    const orgRef = firestore.collection('orgs').doc(input.orgId)\n    const org =\n      input.org ?? ((await orgRef.get()).data() as Record<string, unknown> | undefined) ?? null\n    const visibleTo = crmScopeTokens(org, consentGroupForHost(org, input.hostId))\n    if (!crmActivityLogHasRoom(await countCrmActivitiesForRecord(orgRef, input.link))) {\n      console.warn('[crm] the filing was not written on the timeline: the record’s log is full', input.link)\n      return 0\n    }\n    const activities = orgRef.collection(CRM_COLLECTIONS.activities)\n    let written = 0\n    for (const campaign of input.campaigns) {\n      const entry = {\n        ...buildCampaignFilingActivity({\n          action: input.action,\n          campaign,\n          link: input.link,\n          hostId: input.hostId,\n          visibleTo,\n          atMs: input.atMs,\n          byUid: input.byUid,\n          byName: input.byName ?? null,\n        }),\n        createdAt: FieldValue.serverTimestamp(),\n        updatedAt: FieldValue.serverTimestamp(),\n      }\n      if (input.dedupeKey) {\n        try {\n          await activities.doc(campaignFilingActivityId(`${input.dedupeKey}:${campaign.id}`)).create(entry)\n          written += 1\n        } catch (error) {\n          if ((error as { code?: unknown })?.code !== ALREADY_EXISTS) throw error\n        }\n      } else {\n        // A member's act, new each time, named by the platform's own id.\n        await activities.doc(createResourceUid()).create(entry)\n        written += 1\n      }\n    }\n    return written\n  } catch (error) {\n    console.error('[crm] the filing could not be written on the timeline', input.link, error)\n    return 0\n  }\n}\n"],"names":["consentGroupForHost","createResourceUid","CRM_COLLECTIONS","crmActivityLogHasRoom","crmScopeTokens","countCrmActivitiesForRecord","createHash","FieldValue","BUNDLE_ID","buildCampaignFilingActivity","campaignFilingActivityId","key","update","digest","slice","ALREADY_EXISTS","siteCampaignRefs","firestore","hostId","campaignIds","length","containers","collection","doc","found","getAll","map","id","index","name","String","get","trim","fileCampaignFilingActivities","input","campaigns","orgRef","orgId","org","data","visibleTo","link","console","warn","activities","written","campaign","entry","action","atMs","byUid","byName","createdAt","serverTimestamp","updatedAt","dedupeKey","create","error","code"],"mappings":";AAAA;;;;;;;;;;;;;;;CAeC,GAED,SAASA,mBAAmB,QAAQ,wCAAuC;AAC3E,SAASC,iBAAiB,QAAQ,6CAA4C;AAC9E,SACEC,eAAe,EACfC,qBAAqB,EACrBC,cAAc,QAET,6BAA4B;AACnC,SAASC,2BAA2B,QAAQ,8CAA6C;AACzF,SAASC,UAAU,QAAQ,SAAQ;AACnC,SAASC,UAAU,QAAQ,2BAA0B;AACrD,SAASC,SAAS,QAAQ,gCAA4B;AACtD,SACEC,2BAA2B,QAGtB,uCAAmC;AAwD1C,qFAAqF,GACrF,OAAO,SAASC,yBAAyBC,GAAW;IAClD,OAAO,CAAC,IAAI,EAAEL,WAAW,UAAUM,MAAM,CAAC,GAAGJ,UAAU,CAAC,EAAEG,KAAK,EAAEE,MAAM,CAAC,OAAOC,KAAK,CAAC,GAAG,KAAK;AAC/F;AAEA,qFAAqF,GACrF,MAAMC,iBAAiB;AAEvB;;;CAGC,GACD,OAAO,eAAeC,iBACpBC,SAAoB,EACpBC,MAAc,EACdC,WAA8B;IAE9B,IAAI,CAACA,YAAYC,MAAM,EAAE,OAAO,EAAE;IAClC,MAAMC,aAAaJ,UAAUK,UAAU,CAAC,SAASC,GAAG,CAACL,QAAQI,UAAU,CAAC;IACxE,MAAME,QAAQ,MAAMP,UAAUQ,MAAM,IAAIN,YAAYO,GAAG,CAAC,CAACC,KAAON,WAAWE,GAAG,CAACI;IAC/E,OAAOR,YAAYO,GAAG,CAAC,CAACC,IAAIC;;YAEbJ;eAFwB;YACrCG;YACAE,MAAMC,gBAAON,eAAAA,KAAK,CAACI,MAAM,qBAAZJ,aAAcO,GAAG,CAAC,0BAAW,IAAIC,IAAI,MAAML;QAC1D;;AACF;AAEA,iEAAiE,GACjE,OAAO,eAAeM,6BACpBhB,SAAoB,EACpBiB,KAAoC;IAEpC,IAAI,CAACA,MAAMC,SAAS,CAACf,MAAM,EAAE,OAAO;IACpC,IAAI;YAGAc,MAAAA;QAFF,MAAME,SAASnB,UAAUK,UAAU,CAAC,QAAQC,GAAG,CAACW,MAAMG,KAAK;QAC3D,MAAMC,OACJJ,QAAAA,aAAAA,MAAMI,GAAG,YAATJ,aAAc,AAAC,CAAA,MAAME,OAAOL,GAAG,EAAC,EAAGQ,IAAI,cAAvCL,OAAqF;QACvF,MAAMM,YAAYpC,eAAekC,KAAKtC,oBAAoBsC,KAAKJ,MAAMhB,MAAM;QAC3E,IAAI,CAACf,sBAAsB,MAAME,4BAA4B+B,QAAQF,MAAMO,IAAI,IAAI;YACjFC,QAAQC,IAAI,CAAC,8EAA8ET,MAAMO,IAAI;YACrG,OAAO;QACT;QACA,MAAMG,aAAaR,OAAOd,UAAU,CAACpB,gBAAgB0C,UAAU;QAC/D,IAAIC,UAAU;QACd,KAAK,MAAMC,YAAYZ,MAAMC,SAAS,CAAE;gBAU1BD;YATZ,MAAMa,QAAQ,aACTtC,4BAA4B;gBAC7BuC,QAAQd,MAAMc,MAAM;gBACpBF;gBACAL,MAAMP,MAAMO,IAAI;gBAChBvB,QAAQgB,MAAMhB,MAAM;gBACpBsB;gBACAS,MAAMf,MAAMe,IAAI;gBAChBC,OAAOhB,MAAMgB,KAAK;gBAClBC,MAAM,GAAEjB,gBAAAA,MAAMiB,MAAM,YAAZjB,gBAAgB;YAC1B;gBACAkB,WAAW7C,WAAW8C,eAAe;gBACrCC,WAAW/C,WAAW8C,eAAe;;YAEvC,IAAInB,MAAMqB,SAAS,EAAE;gBACnB,IAAI;oBACF,MAAMX,WAAWrB,GAAG,CAACb,yBAAyB,GAAGwB,MAAMqB,SAAS,CAAC,CAAC,EAAET,SAASnB,EAAE,EAAE,GAAG6B,MAAM,CAACT;oBAC3FF,WAAW;gBACb,EAAE,OAAOY,OAAO;oBACd,IAAI,CAACA,yBAAD,AAACA,MAA8BC,IAAI,MAAK3C,gBAAgB,MAAM0C;gBACpE;YACF,OAAO;gBACL,iEAAiE;gBACjE,MAAMb,WAAWrB,GAAG,CAACtB,qBAAqBuD,MAAM,CAACT;gBACjDF,WAAW;YACb;QACF;QACA,OAAOA;IACT,EAAE,OAAOY,OAAO;QACdf,QAAQe,KAAK,CAAC,yDAAyDvB,MAAMO,IAAI,EAAEgB;QACnF,OAAO;IACT;AACF"}

package/src/lib/server/lead-campaign-carry.js

@@ -17,6 +17,8 @@
 import { firebaseAdmin } from "@aglyn/tenant-data-admin/server/firebase-admin";
 import { consentGroupForSite } from "@aglyn/tenant-data-admin/server/organizations";
 import { FieldValue } from "firebase-admin/firestore";
+import { CAMPAIGN_FILING_CARRY_BY_NAME } from "../model/campaign-filing-activity.js";
+import { fileCampaignFilingActivities, siteCampaignRefs } from "./campaign-filing-activity.js";
 /**
  * WHAT A LEAD'S CAMPAIGNS BECOME WHEN IT CONVERTS (AGL-3254).
  *
@@ -48,6 +50,29 @@ import { FieldValue } from "firebase-admin/firestore";
             [contactCampaignFieldPath(group.groupId)]: FieldValue.arrayUnion(...campaignIds),
             updatedAt: FieldValue.serverTimestamp()
         });
+        /*
+     * The carry on the contact's Activity (AGL-3274): one "Filed under"
+     * per campaign, by the conversion rather than a member, keyed once per
+     * lead and contact so a door that converts twice files once. After the
+     * membership has landed, and never failing the carry that is done.
+     */ await fileCampaignFilingActivities(firestore, {
+            orgId: request.orgId,
+            hostId: request.hostId,
+            link: {
+                contactId: request.contactId
+            },
+            action: 'filed',
+            // Named where the containers answer; by id where a read fails, so a
+            // name lookup can never unmake a carry that has landed.
+            campaigns: await siteCampaignRefs(firestore, request.hostId, campaignIds).catch(()=>campaignIds.map((id)=>({
+                        id,
+                        name: id
+                    }))),
+            atMs: Date.now(),
+            byUid: '',
+            byName: CAMPAIGN_FILING_CARRY_BY_NAME,
+            dedupeKey: `carry:${request.leadId}:${request.contactId}`
+        });
         return {
             campaigns: campaignIds.length
         };

package/src/lib/server/lead-campaign-carry.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../../../../../libs/plugins/crm/src/lib/server/lead-campaign-carry.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 {\n  contactCampaignFieldPath,\n  readCampaignIds,\n} from '@aglyn/aglyn/app-utils/campaign-membership'\nimport type {\n  PluginLeadConversionReport,\n  PluginLeadConversionRequest,\n} from '@aglyn/aglyn/plugin-manager/plugin-lead-conversion'\nimport { firebaseAdmin } from '@aglyn/tenant-data-admin/server/firebase-admin'\nimport { consentGroupForSite } from '@aglyn/tenant-data-admin/server/organizations'\nimport { FieldValue } from 'firebase-admin/firestore'\n\n/**\n * WHAT A LEAD'S CAMPAIGNS BECOME WHEN IT CONVERTS (AGL-3254).\n *\n * A lead is filed under a site's campaigns at the top of its own document;\n * a contact holds the same membership inside the site's consent-group\n * facet, because a contact is shared across the org and a campaign is one\n * site's. When the lead becomes a contact, the campaigns go with it — added\n * to what the contact already carries there with `arrayUnion`, never in\n * place of it — so the campaign's page goes on listing the person after\n * they became a contact, and a lead a sequence enrolled under a campaign\n * does not leave the campaign by converting.\n *\n * The CRM's own module, because a lead and a contact are the CRM's records\n * (docs/PACKAGES.md rule 3): it runs as the CRM's share of the platform's\n * lead-conversion seam, which every door that converts a lead — the\n * dialog, the REST API, a sign-up, a purchase — reaches through\n * `handOffLeadRecords`. Never throws: the conversion has happened, and a\n * membership that could not be carried is one the contact's page can pick\n * by hand.\n */\nexport async function carryLeadCampaignsToContact(\n  firestore: FirebaseFirestore.Firestore,\n  request: Pick<\n    PluginLeadConversionRequest,\n    'orgId' | 'hostId' | 'leadId' | 'contactId'\n  >,\n): Promise<PluginLeadConversionReport> {\n  try {\n    const lead = await firestore\n      .collection('hosts')\n      .doc(request.hostId)\n      .collection('leads')\n      .doc(request.leadId)\n      .get()\n    const campaignIds = readCampaignIds(\n      lead.exists ? (lead.data() as Record<string, unknown>) : null,\n    )\n    if (!campaignIds.length) return { campaigns: 0 }\n    const group = await consentGroupForSite(request.hostId)\n    await firestore\n      .collection('orgs')\n      .doc(request.orgId)\n      .collection('contacts')\n      .doc(request.contactId)\n      .update({\n        [contactCampaignFieldPath(group.groupId)]: FieldValue.arrayUnion(\n          ...campaignIds,\n        ),\n        updatedAt: FieldValue.serverTimestamp(),\n      })\n    return { campaigns: campaignIds.length }\n  } catch (error) {\n    console.error(\n      '[crm] the lead’s campaigns could not be carried to the contact',\n      request.hostId,\n      request.leadId,\n      error,\n    )\n    return { campaigns: null }\n  }\n}\n\n/**\n * The carry as the lead-conversion seam calls it: on the Admin SDK's own\n * Firestore. The SDK is resolved HERE, not in `declarations.server.ts`, for\n * two reasons that point the same way. That file must stay light — it runs\n * at the boot of every server process — so it defers this module and must\n * not import the data layer itself. And a library the plugin imports\n * statically in thirty files cannot also be lazy-loaded in one:\n * `enforce-module-boundaries` refuses every static import of a library the\n * project lazy-loads anywhere. This module is the deferred one; the SDK\n * comes with it, the way `capture-contact` brings its own.\n */\nexport function carryLeadCampaignsOnConversion(\n  request: Pick<\n    PluginLeadConversionRequest,\n    'orgId' | 'hostId' | 'leadId' | 'contactId'\n  >,\n): Promise<PluginLeadConversionReport> {\n  return carryLeadCampaignsToContact(firebaseAdmin.app().firestore(), request)\n}\n"],"names":["contactCampaignFieldPath","readCampaignIds","firebaseAdmin","consentGroupForSite","FieldValue","carryLeadCampaignsToContact","firestore","request","lead","collection","doc","hostId","leadId","get","campaignIds","exists","data","length","campaigns","group","orgId","contactId","update","groupId","arrayUnion","updatedAt","serverTimestamp","error","console","carryLeadCampaignsOnConversion","app"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED,SACEA,wBAAwB,EACxBC,eAAe,QACV,6CAA4C;AAKnD,SAASC,aAAa,QAAQ,iDAAgD;AAC9E,SAASC,mBAAmB,QAAQ,gDAA+C;AACnF,SAASC,UAAU,QAAQ,2BAA0B;AAErD;;;;;;;;;;;;;;;;;;;CAmBC,GACD,OAAO,eAAeC,4BACpBC,SAAsC,EACtCC,OAGC;IAED,IAAI;QACF,MAAMC,OAAO,MAAMF,UAChBG,UAAU,CAAC,SACXC,GAAG,CAACH,QAAQI,MAAM,EAClBF,UAAU,CAAC,SACXC,GAAG,CAACH,QAAQK,MAAM,EAClBC,GAAG;QACN,MAAMC,cAAcb,gBAClBO,KAAKO,MAAM,GAAIP,KAAKQ,IAAI,KAAiC;QAE3D,IAAI,CAACF,YAAYG,MAAM,EAAE,OAAO;YAAEC,WAAW;QAAE;QAC/C,MAAMC,QAAQ,MAAMhB,oBAAoBI,QAAQI,MAAM;QACtD,MAAML,UACHG,UAAU,CAAC,QACXC,GAAG,CAACH,QAAQa,KAAK,EACjBX,UAAU,CAAC,YACXC,GAAG,CAACH,QAAQc,SAAS,EACrBC,MAAM,CAAC;YACN,CAACtB,yBAAyBmB,MAAMI,OAAO,EAAE,EAAEnB,WAAWoB,UAAU,IAC3DV;YAELW,WAAWrB,WAAWsB,eAAe;QACvC;QACF,OAAO;YAAER,WAAWJ,YAAYG,MAAM;QAAC;IACzC,EAAE,OAAOU,OAAO;QACdC,QAAQD,KAAK,CACX,kEACApB,QAAQI,MAAM,EACdJ,QAAQK,MAAM,EACde;QAEF,OAAO;YAAET,WAAW;QAAK;IAC3B;AACF;AAEA;;;;;;;;;;CAUC,GACD,OAAO,SAASW,+BACdtB,OAGC;IAED,OAAOF,4BAA4BH,cAAc4B,GAAG,GAAGxB,SAAS,IAAIC;AACtE"}
+{"version":3,"sources":["../../../../../../../libs/plugins/crm/src/lib/server/lead-campaign-carry.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 {\n  contactCampaignFieldPath,\n  readCampaignIds,\n} from '@aglyn/aglyn/app-utils/campaign-membership'\nimport type {\n  PluginLeadConversionReport,\n  PluginLeadConversionRequest,\n} from '@aglyn/aglyn/plugin-manager/plugin-lead-conversion'\nimport { firebaseAdmin } from '@aglyn/tenant-data-admin/server/firebase-admin'\nimport { consentGroupForSite } from '@aglyn/tenant-data-admin/server/organizations'\nimport { FieldValue } from 'firebase-admin/firestore'\nimport { CAMPAIGN_FILING_CARRY_BY_NAME } from '../model/campaign-filing-activity'\nimport { fileCampaignFilingActivities, siteCampaignRefs } from './campaign-filing-activity'\n\n/**\n * WHAT A LEAD'S CAMPAIGNS BECOME WHEN IT CONVERTS (AGL-3254).\n *\n * A lead is filed under a site's campaigns at the top of its own document;\n * a contact holds the same membership inside the site's consent-group\n * facet, because a contact is shared across the org and a campaign is one\n * site's. When the lead becomes a contact, the campaigns go with it — added\n * to what the contact already carries there with `arrayUnion`, never in\n * place of it — so the campaign's page goes on listing the person after\n * they became a contact, and a lead a sequence enrolled under a campaign\n * does not leave the campaign by converting.\n *\n * The CRM's own module, because a lead and a contact are the CRM's records\n * (docs/PACKAGES.md rule 3): it runs as the CRM's share of the platform's\n * lead-conversion seam, which every door that converts a lead — the\n * dialog, the REST API, a sign-up, a purchase — reaches through\n * `handOffLeadRecords`. Never throws: the conversion has happened, and a\n * membership that could not be carried is one the contact's page can pick\n * by hand.\n */\nexport async function carryLeadCampaignsToContact(\n  firestore: FirebaseFirestore.Firestore,\n  request: Pick<\n    PluginLeadConversionRequest,\n    'orgId' | 'hostId' | 'leadId' | 'contactId'\n  >,\n): Promise<PluginLeadConversionReport> {\n  try {\n    const lead = await firestore\n      .collection('hosts')\n      .doc(request.hostId)\n      .collection('leads')\n      .doc(request.leadId)\n      .get()\n    const campaignIds = readCampaignIds(\n      lead.exists ? (lead.data() as Record<string, unknown>) : null,\n    )\n    if (!campaignIds.length) return { campaigns: 0 }\n    const group = await consentGroupForSite(request.hostId)\n    await firestore\n      .collection('orgs')\n      .doc(request.orgId)\n      .collection('contacts')\n      .doc(request.contactId)\n      .update({\n        [contactCampaignFieldPath(group.groupId)]: FieldValue.arrayUnion(\n          ...campaignIds,\n        ),\n        updatedAt: FieldValue.serverTimestamp(),\n      })\n    /*\n     * The carry on the contact's Activity (AGL-3274): one \"Filed under\"\n     * per campaign, by the conversion rather than a member, keyed once per\n     * lead and contact so a door that converts twice files once. After the\n     * membership has landed, and never failing the carry that is done.\n     */\n    await fileCampaignFilingActivities(firestore, {\n      orgId: request.orgId,\n      hostId: request.hostId,\n      link: { contactId: request.contactId },\n      action: 'filed',\n      // Named where the containers answer; by id where a read fails, so a\n      // name lookup can never unmake a carry that has landed.\n      campaigns: await siteCampaignRefs(firestore, request.hostId, campaignIds).catch(() =>\n        campaignIds.map((id) => ({ id, name: id })),\n      ),\n      atMs: Date.now(),\n      byUid: '',\n      byName: CAMPAIGN_FILING_CARRY_BY_NAME,\n      dedupeKey: `carry:${request.leadId}:${request.contactId}`,\n    })\n    return { campaigns: campaignIds.length }\n  } catch (error) {\n    console.error(\n      '[crm] the lead’s campaigns could not be carried to the contact',\n      request.hostId,\n      request.leadId,\n      error,\n    )\n    return { campaigns: null }\n  }\n}\n\n/**\n * The carry as the lead-conversion seam calls it: on the Admin SDK's own\n * Firestore. The SDK is resolved HERE, not in `declarations.server.ts`, for\n * two reasons that point the same way. That file must stay light — it runs\n * at the boot of every server process — so it defers this module and must\n * not import the data layer itself. And a library the plugin imports\n * statically in thirty files cannot also be lazy-loaded in one:\n * `enforce-module-boundaries` refuses every static import of a library the\n * project lazy-loads anywhere. This module is the deferred one; the SDK\n * comes with it, the way `capture-contact` brings its own.\n */\nexport function carryLeadCampaignsOnConversion(\n  request: Pick<\n    PluginLeadConversionRequest,\n    'orgId' | 'hostId' | 'leadId' | 'contactId'\n  >,\n): Promise<PluginLeadConversionReport> {\n  return carryLeadCampaignsToContact(firebaseAdmin.app().firestore(), request)\n}\n"],"names":["contactCampaignFieldPath","readCampaignIds","firebaseAdmin","consentGroupForSite","FieldValue","CAMPAIGN_FILING_CARRY_BY_NAME","fileCampaignFilingActivities","siteCampaignRefs","carryLeadCampaignsToContact","firestore","request","lead","collection","doc","hostId","leadId","get","campaignIds","exists","data","length","campaigns","group","orgId","contactId","update","groupId","arrayUnion","updatedAt","serverTimestamp","link","action","catch","map","id","name","atMs","Date","now","byUid","byName","dedupeKey","error","console","carryLeadCampaignsOnConversion","app"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED,SACEA,wBAAwB,EACxBC,eAAe,QACV,6CAA4C;AAKnD,SAASC,aAAa,QAAQ,iDAAgD;AAC9E,SAASC,mBAAmB,QAAQ,gDAA+C;AACnF,SAASC,UAAU,QAAQ,2BAA0B;AACrD,SAASC,6BAA6B,QAAQ,uCAAmC;AACjF,SAASC,4BAA4B,EAAEC,gBAAgB,QAAQ,gCAA4B;AAE3F;;;;;;;;;;;;;;;;;;;CAmBC,GACD,OAAO,eAAeC,4BACpBC,SAAsC,EACtCC,OAGC;IAED,IAAI;QACF,MAAMC,OAAO,MAAMF,UAChBG,UAAU,CAAC,SACXC,GAAG,CAACH,QAAQI,MAAM,EAClBF,UAAU,CAAC,SACXC,GAAG,CAACH,QAAQK,MAAM,EAClBC,GAAG;QACN,MAAMC,cAAchB,gBAClBU,KAAKO,MAAM,GAAIP,KAAKQ,IAAI,KAAiC;QAE3D,IAAI,CAACF,YAAYG,MAAM,EAAE,OAAO;YAAEC,WAAW;QAAE;QAC/C,MAAMC,QAAQ,MAAMnB,oBAAoBO,QAAQI,MAAM;QACtD,MAAML,UACHG,UAAU,CAAC,QACXC,GAAG,CAACH,QAAQa,KAAK,EACjBX,UAAU,CAAC,YACXC,GAAG,CAACH,QAAQc,SAAS,EACrBC,MAAM,CAAC;YACN,CAACzB,yBAAyBsB,MAAMI,OAAO,EAAE,EAAEtB,WAAWuB,UAAU,IAC3DV;YAELW,WAAWxB,WAAWyB,eAAe;QACvC;QACF;;;;;KAKC,GACD,MAAMvB,6BAA6BG,WAAW;YAC5Cc,OAAOb,QAAQa,KAAK;YACpBT,QAAQJ,QAAQI,MAAM;YACtBgB,MAAM;gBAAEN,WAAWd,QAAQc,SAAS;YAAC;YACrCO,QAAQ;YACR,oEAAoE;YACpE,wDAAwD;YACxDV,WAAW,MAAMd,iBAAiBE,WAAWC,QAAQI,MAAM,EAAEG,aAAae,KAAK,CAAC,IAC9Ef,YAAYgB,GAAG,CAAC,CAACC,KAAQ,CAAA;wBAAEA;wBAAIC,MAAMD;oBAAG,CAAA;YAE1CE,MAAMC,KAAKC,GAAG;YACdC,OAAO;YACPC,QAAQnC;YACRoC,WAAW,CAAC,MAAM,EAAE/B,QAAQK,MAAM,CAAC,CAAC,EAAEL,QAAQc,SAAS,EAAE;QAC3D;QACA,OAAO;YAAEH,WAAWJ,YAAYG,MAAM;QAAC;IACzC,EAAE,OAAOsB,OAAO;QACdC,QAAQD,KAAK,CACX,kEACAhC,QAAQI,MAAM,EACdJ,QAAQK,MAAM,EACd2B;QAEF,OAAO;YAAErB,WAAW;QAAK;IAC3B;AACF;AAEA;;;;;;;;;;CAUC,GACD,OAAO,SAASuB,+BACdlC,OAGC;IAED,OAAOF,4BAA4BN,cAAc2C,GAAG,GAAGpC,SAAS,IAAIC;AACtE"}

package/src/lib/server/lead-create.d.ts

@@ -45,7 +45,8 @@
  * because a lead entered by hand is suite work: the capture doors that fill
  * a Free workspace's leads do not come through here.
  */
-import { type CrmLeadProfilePatch, type CrmLeadStatus, type PluginApiHandler } from '@aglyn/aglyn/server';
+import { type CrmCustomValue, type CrmLeadProfilePatch, type CrmLeadStatus, type PluginApiHandler } from '@aglyn/aglyn/server';
+import type { CampaignFilingRef } from '../model/campaign-filing-activity';
 /** The surface a hand-entered lead names, beside `signup`, `booking`, `form:{id}` and `import`. */
 export declare const LEAD_MANUAL_SOURCE = "manual";
 /** What the New lead drawer posts. */
@@ -65,17 +66,27 @@ export interface LeadCreateRequest {
     notes?: string;
     /** The site's campaigns to file the lead under (AGL-3254), by container id. */
     campaignIds?: string[];
+    /**
+     * The org's custom LEAD fields (AGL-3272), keyed by each definition's
+     * `key`. Judged against the definitions whose `object` is `lead`, so a
+     * contact field of the same name cannot be written through this door.
+     */
+    custom?: Record<string, CrmCustomValue>;
 }
 /** The sentence a campaign that is not the site's is refused with, under the field. */
 export declare const LEAD_CAMPAIGN_REFUSAL = "One of the campaigns picked isn't a campaign of this site any more. Pick it again.";
 /**
- * The campaign ids a request may file a lead under: the site's own live
+ * The campaigns a request may file a lead under: the site's own live
  * containers, and nothing else. A request can claim any id, and a lead
  * filed under another site's campaign — or one the console soft-deleted —
- * would sit on a page nobody at this site can open.
+ * would sit on a page nobody at this site can open. Answered with the
+ * names as they stand, for the timeline entries the filing writes
+ * (AGL-3274).
  *
- * @returns the clean ids, or `null` when one of them is not the site's.
+ * @returns the clean ids with their names, or `null` when one is not the site's.
  */
+export declare function siteCampaigns(hostRef: FirebaseFirestore.DocumentReference, raw: unknown): Promise<CampaignFilingRef[] | null>;
+/** The ids alone — see {@link siteCampaigns}. */
 export declare function siteCampaignIds(hostRef: FirebaseFirestore.DocumentReference, raw: unknown): Promise<string[] | null>;
 /** What the route answers on success. */
 export interface LeadCreateResponse {