@aglyn/plugins-marketing 1.0.0-beta.221 → 1.0.0-beta.223

package/src/lib/server/campaign-touch-targets.d.ts

@@ -0,0 +1,61 @@
+/**
+ * @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.
+ */
+/** A campaign container, as much of it as a touch's credit needs. */
+export interface LiveCampaign {
+    id: string;
+    name: string;
+}
+/**
+ * The campaign at `orgs/{orgId}/emailCampaigns/{campaignId}`, or `null` when
+ * it does not exist or its owner retired it.
+ */
+export declare function readLiveCampaign(options: {
+    orgId: string;
+    campaignId: string;
+}, firestore: any): Promise<LiveCampaign | null>;
+/**
+ * The campaigns a site's screen is filed under right now, or `null` when the
+ * screen does not exist.
+ */
+export declare function readScreenCampaignIds(options: {
+    hostId: string;
+    screenId: string;
+}, firestore: any): Promise<string[] | null>;
+/**
+ * Of the campaigns a page touch carries, the first that the page is STILL
+ * filed under and that still exists — or `null`.
+ *
+ * The touch carries the screen's campaigns in the screen's own order, so a
+ * page filed under two campaigns credits the one it names first. One
+ * outcome, one campaign: crediting both would count one visitor's form twice
+ * across the org's campaigns.
+ */
+export declare function filedCampaignForPage(options: {
+    orgId: string;
+    hostId: string;
+    screenId: string;
+    campaignIds: readonly string[];
+}, firestore: any): Promise<LiveCampaign | null>;
+/**
+ * The one live campaign placed on this site that declares `label` among its
+ * `utmCampaigns`, or `null` — for no such campaign, and for two.
+ */
+export declare function campaignForUtmLabel(options: {
+    orgId: string;
+    hostId: string;
+    label: string | null | undefined;
+}, firestore: any): Promise<LiveCampaign | null>;

package/src/lib/server/campaign-touch-targets.js

@@ -0,0 +1,162 @@
+/**
+ * @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 { EMAIL_CAMPAIGNS_COLLECTION, campaignPlacedOnHost, normalizeCampaignUtmLabel } from "../model/campaign-container.js";
+import { readContainerIds } from "@aglyn/aglyn/app-utils/container-membership";
+import { isDocumentId } from "@aglyn/tenant-data-admin/server/document-id";
+import { CAMPAIGN_KIND } from "../model/campaign-kind.js";
+/**
+ * WHAT A VISITOR'S TOUCH NAMES, CHECKED AGAINST WHAT IS STORED (AGL-3461).
+ *
+ * Two touches name a campaign DOCUMENT without a click on its mail: a page
+ * the visitor viewed that is filed under a campaign, and a `utm_campaign`
+ * label a campaign declares as its own. Both arrive from the visitor's
+ * browser, so neither is trusted as sent:
+ *
+ *  - a page touch credits a campaign only while the campaign exists and the
+ *    page is still filed under it — one screen read and one campaign read;
+ *  - a label credits a campaign only when exactly one live campaign placed
+ *    on the site declares it — one `array-contains` query on the org's
+ *    campaigns, served by the automatic single-field index. A label two
+ *    campaigns claim credits neither, rather than whichever the index
+ *    happens to return first.
+ *
+ * The conversion join (`campaign-conversion-attribution.ts`) asks at an
+ * identify moment and the first-visit beacon (`campaign-visit-beacon.ts`) on
+ * a pageview. Each answer is memoized for a minute per Firestore instance —
+ * the beacon is per pageview and a landing page's visitors all ask the same
+ * question — so a campaign deleted or a page refiled is believed within the
+ * minute, which is the staleness the site collector's own caches accept.
+ *
+ * Never throws: a lookup that fails answers "names nothing", and the touch is
+ * then treated as the label or the page it is, credited to no document.
+ */ /** How long one answer is believed, per Firestore instance. */ const MEMO_MS = 60000;
+/** Size cap on each memo; cleared wholesale like every visitor-keyed map. */ const MEMO_MAX = 2000;
+const memos = new WeakMap();
+function memoFor(firestore) {
+    let memo = memos.get(firestore);
+    if (!memo) {
+        memo = new Map();
+        memos.set(firestore, memo);
+    }
+    return memo;
+}
+async function remembered(firestore, key, read) {
+    const memo = memoFor(firestore);
+    const hit = memo.get(key);
+    const now = Date.now();
+    if (hit && now - hit.at < MEMO_MS) return hit.value;
+    const value = await read();
+    if (memo.size > MEMO_MAX) memo.clear();
+    memo.set(key, {
+        value,
+        at: now
+    });
+    return value;
+}
+/**
+ * The campaign at `orgs/{orgId}/emailCampaigns/{campaignId}`, or `null` when
+ * it does not exist or its owner retired it.
+ */ export async function readLiveCampaign(options, firestore) {
+    const { orgId, campaignId } = options;
+    if (!isDocumentId(orgId) || !isDocumentId(campaignId)) return null;
+    try {
+        return await remembered(firestore, `campaign:${orgId}:${campaignId}`, async ()=>{
+            var _snapshot_data, _data_name;
+            const snapshot = await firestore.collection('orgs').doc(orgId).collection(EMAIL_CAMPAIGNS_COLLECTION).doc(campaignId).get();
+            if (!snapshot.exists) return null;
+            const data = (_snapshot_data = snapshot.data()) != null ? _snapshot_data : {};
+            if (data.deletedAt) return null;
+            return {
+                id: campaignId,
+                name: String((_data_name = data.name) != null ? _data_name : '').trim() || campaignId
+            };
+        });
+    } catch (error) {
+        console.error('[campaign-touch] campaign read failed', error);
+        return null;
+    }
+}
+/**
+ * The campaigns a site's screen is filed under right now, or `null` when the
+ * screen does not exist.
+ */ export async function readScreenCampaignIds(options, firestore) {
+    const { hostId, screenId } = options;
+    if (!isDocumentId(hostId) || !isDocumentId(screenId)) return null;
+    try {
+        return await remembered(firestore, `screen:${hostId}:${screenId}`, async ()=>{
+            var _snapshot_data;
+            const snapshot = await firestore.collection('hosts').doc(hostId).collection('screens').doc(screenId).get();
+            if (!snapshot.exists) return null;
+            return readContainerIds((_snapshot_data = snapshot.data()) != null ? _snapshot_data : {}, CAMPAIGN_KIND);
+        });
+    } catch (error) {
+        console.error('[campaign-touch] screen read failed', error);
+        return null;
+    }
+}
+/**
+ * Of the campaigns a page touch carries, the first that the page is STILL
+ * filed under and that still exists — or `null`.
+ *
+ * The touch carries the screen's campaigns in the screen's own order, so a
+ * page filed under two campaigns credits the one it names first. One
+ * outcome, one campaign: crediting both would count one visitor's form twice
+ * across the org's campaigns.
+ */ export async function filedCampaignForPage(options, firestore) {
+    const filed = await readScreenCampaignIds(options, firestore);
+    if (!(filed == null ? void 0 : filed.length)) return null;
+    for (const campaignId of options.campaignIds){
+        if (!filed.includes(campaignId)) continue;
+        const campaign = await readLiveCampaign({
+            orgId: options.orgId,
+            campaignId
+        }, firestore);
+        if (campaign) return campaign;
+    }
+    return null;
+}
+/**
+ * The one live campaign placed on this site that declares `label` among its
+ * `utmCampaigns`, or `null` — for no such campaign, and for two.
+ */ export async function campaignForUtmLabel(options, firestore) {
+    const { orgId, hostId } = options;
+    const label = normalizeCampaignUtmLabel(options.label);
+    if (!label || !isDocumentId(orgId)) return null;
+    try {
+        return await remembered(firestore, `label:${orgId}:${hostId}:${label}`, async ()=>{
+            var _snapshot_docs, _match_data_name;
+            const snapshot = await firestore.collection('orgs').doc(orgId).collection(EMAIL_CAMPAIGNS_COLLECTION).where('utmCampaigns', 'array-contains', label).limit(5).get();
+            const matches = ((_snapshot_docs = snapshot.docs) != null ? _snapshot_docs : []).map((doc)=>{
+                var _doc_data;
+                return {
+                    id: String(doc.id),
+                    data: (_doc_data = doc.data()) != null ? _doc_data : {}
+                };
+            }).filter(({ data })=>!data.deletedAt).filter(({ data })=>campaignPlacedOnHost(data, hostId));
+            if (matches.length !== 1) return null;
+            const [match] = matches;
+            return {
+                id: match.id,
+                name: String((_match_data_name = match.data.name) != null ? _match_data_name : '').trim() || match.id
+            };
+        });
+    } catch (error) {
+        console.error('[campaign-touch] label lookup failed', error);
+        return null;
+    }
+}
+
+//# sourceMappingURL=campaign-touch-targets.js.map

package/src/lib/server/campaign-touch-targets.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/marketing/src/lib/server/campaign-touch-targets.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  EMAIL_CAMPAIGNS_COLLECTION,\n  campaignPlacedOnHost,\n  normalizeCampaignUtmLabel,\n  type EmailCampaign,\n} from '../model/campaign-container'\nimport { readContainerIds } from '@aglyn/aglyn/app-utils/container-membership'\nimport { isDocumentId } from '@aglyn/tenant-data-admin/server/document-id'\nimport { CAMPAIGN_KIND } from '../model/campaign-kind'\n\n/**\n * WHAT A VISITOR'S TOUCH NAMES, CHECKED AGAINST WHAT IS STORED (AGL-3461).\n *\n * Two touches name a campaign DOCUMENT without a click on its mail: a page\n * the visitor viewed that is filed under a campaign, and a `utm_campaign`\n * label a campaign declares as its own. Both arrive from the visitor's\n * browser, so neither is trusted as sent:\n *\n *  - a page touch credits a campaign only while the campaign exists and the\n *    page is still filed under it — one screen read and one campaign read;\n *  - a label credits a campaign only when exactly one live campaign placed\n *    on the site declares it — one `array-contains` query on the org's\n *    campaigns, served by the automatic single-field index. A label two\n *    campaigns claim credits neither, rather than whichever the index\n *    happens to return first.\n *\n * The conversion join (`campaign-conversion-attribution.ts`) asks at an\n * identify moment and the first-visit beacon (`campaign-visit-beacon.ts`) on\n * a pageview. Each answer is memoized for a minute per Firestore instance —\n * the beacon is per pageview and a landing page's visitors all ask the same\n * question — so a campaign deleted or a page refiled is believed within the\n * minute, which is the staleness the site collector's own caches accept.\n *\n * Never throws: a lookup that fails answers \"names nothing\", and the touch is\n * then treated as the label or the page it is, credited to no document.\n */\n\n/** How long one answer is believed, per Firestore instance. */\nconst MEMO_MS = 60_000\n\n/** Size cap on each memo; cleared wholesale like every visitor-keyed map. */\nconst MEMO_MAX = 2_000\n\ntype Memo = Map<string, { value: unknown; at: number }>\n\nconst memos = new WeakMap<object, Memo>()\n\nfunction memoFor(firestore: object): Memo {\n  let memo = memos.get(firestore)\n  if (!memo) {\n    memo = new Map()\n    memos.set(firestore, memo)\n  }\n  return memo\n}\n\nasync function remembered<T>(\n  firestore: object,\n  key: string,\n  read: () => Promise<T>,\n): Promise<T> {\n  const memo = memoFor(firestore)\n  const hit = memo.get(key)\n  const now = Date.now()\n  if (hit && now - hit.at < MEMO_MS) return hit.value as T\n  const value = await read()\n  if (memo.size > MEMO_MAX) memo.clear()\n  memo.set(key, { value, at: now })\n  return value\n}\n\n/** A campaign container, as much of it as a touch's credit needs. */\nexport interface LiveCampaign {\n  id: string\n  name: string\n}\n\n/**\n * The campaign at `orgs/{orgId}/emailCampaigns/{campaignId}`, or `null` when\n * it does not exist or its owner retired it.\n */\nexport async function readLiveCampaign(\n  options: { orgId: string; campaignId: string },\n  firestore: any,\n): Promise<LiveCampaign | null> {\n  const { orgId, campaignId } = options\n  if (!isDocumentId(orgId) || !isDocumentId(campaignId)) return null\n  try {\n    return await remembered(firestore, `campaign:${orgId}:${campaignId}`, async () => {\n      const snapshot = await firestore\n        .collection('orgs')\n        .doc(orgId)\n        .collection(EMAIL_CAMPAIGNS_COLLECTION)\n        .doc(campaignId)\n        .get()\n      if (!snapshot.exists) return null\n      const data = (snapshot.data() ?? {}) as Partial<EmailCampaign>\n      if (data.deletedAt) return null\n      return { id: campaignId, name: String(data.name ?? '').trim() || campaignId }\n    })\n  } catch (error) {\n    console.error('[campaign-touch] campaign read failed', error)\n    return null\n  }\n}\n\n/**\n * The campaigns a site's screen is filed under right now, or `null` when the\n * screen does not exist.\n */\nexport async function readScreenCampaignIds(\n  options: { hostId: string; screenId: string },\n  firestore: any,\n): Promise<string[] | null> {\n  const { hostId, screenId } = options\n  if (!isDocumentId(hostId) || !isDocumentId(screenId)) return null\n  try {\n    return await remembered(firestore, `screen:${hostId}:${screenId}`, async () => {\n      const snapshot = await firestore\n        .collection('hosts')\n        .doc(hostId)\n        .collection('screens')\n        .doc(screenId)\n        .get()\n      if (!snapshot.exists) return null\n      return readContainerIds(\n        (snapshot.data() ?? {}) as Record<string, unknown>,\n        CAMPAIGN_KIND,\n      )\n    })\n  } catch (error) {\n    console.error('[campaign-touch] screen read failed', error)\n    return null\n  }\n}\n\n/**\n * Of the campaigns a page touch carries, the first that the page is STILL\n * filed under and that still exists — or `null`.\n *\n * The touch carries the screen's campaigns in the screen's own order, so a\n * page filed under two campaigns credits the one it names first. One\n * outcome, one campaign: crediting both would count one visitor's form twice\n * across the org's campaigns.\n */\nexport async function filedCampaignForPage(\n  options: {\n    orgId: string\n    hostId: string\n    screenId: string\n    campaignIds: readonly string[]\n  },\n  firestore: any,\n): Promise<LiveCampaign | null> {\n  const filed = await readScreenCampaignIds(options, firestore)\n  if (!filed?.length) return null\n  for (const campaignId of options.campaignIds) {\n    if (!filed.includes(campaignId)) continue\n    const campaign = await readLiveCampaign(\n      { orgId: options.orgId, campaignId },\n      firestore,\n    )\n    if (campaign) return campaign\n  }\n  return null\n}\n\n/**\n * The one live campaign placed on this site that declares `label` among its\n * `utmCampaigns`, or `null` — for no such campaign, and for two.\n */\nexport async function campaignForUtmLabel(\n  options: { orgId: string; hostId: string; label: string | null | undefined },\n  firestore: any,\n): Promise<LiveCampaign | null> {\n  const { orgId, hostId } = options\n  const label = normalizeCampaignUtmLabel(options.label)\n  if (!label || !isDocumentId(orgId)) return null\n  try {\n    return await remembered(firestore, `label:${orgId}:${hostId}:${label}`, async () => {\n      const snapshot = await firestore\n        .collection('orgs')\n        .doc(orgId)\n        .collection(EMAIL_CAMPAIGNS_COLLECTION)\n        .where('utmCampaigns', 'array-contains', label)\n        .limit(5)\n        .get()\n      const matches = (snapshot.docs ?? [])\n        .map((doc: any) => ({ id: String(doc.id), data: (doc.data() ?? {}) as Partial<EmailCampaign> }))\n        .filter(({ data }: { data: Partial<EmailCampaign> }) => !data.deletedAt)\n        .filter(({ data }: { data: Partial<EmailCampaign> }) => campaignPlacedOnHost(data, hostId))\n      if (matches.length !== 1) return null\n      const [match] = matches\n      return { id: match.id, name: String(match.data.name ?? '').trim() || match.id }\n    })\n  } catch (error) {\n    console.error('[campaign-touch] label lookup failed', error)\n    return null\n  }\n}\n"],"names":["EMAIL_CAMPAIGNS_COLLECTION","campaignPlacedOnHost","normalizeCampaignUtmLabel","readContainerIds","isDocumentId","CAMPAIGN_KIND","MEMO_MS","MEMO_MAX","memos","WeakMap","memoFor","firestore","memo","get","Map","set","remembered","key","read","hit","now","Date","at","value","size","clear","readLiveCampaign","options","orgId","campaignId","snapshot","data","collection","doc","exists","deletedAt","id","name","String","trim","error","console","readScreenCampaignIds","hostId","screenId","filedCampaignForPage","filed","length","campaignIds","includes","campaign","campaignForUtmLabel","label","match","where","limit","matches","docs","map","filter"],"mappings":"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"}

package/src/lib/server/campaign-visit-beacon.d.ts

@@ -0,0 +1,44 @@
+/**
+ * @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 { PluginSiteBeaconRequest } from '@aglyn/aglyn/plugin-manager/plugin-site-beacons';
+/**
+ * The body field that marks a beacon as a campaign visit. The site runtime
+ * sends it; the collector hands the beacon here after its host, lockdown and
+ * rate gates.
+ */
+export declare const CAMPAIGN_VISIT_BEACON_FIELD = "campaignVisit";
+/**
+ * Counts one campaign visit beacon (AGL-3461) into
+ * `orgs/{orgId}/campaignVisitReports/{campaignId}`.
+ *
+ * The body says what the visitor's browser saw — the screen and the
+ * campaigns its page was filed under, the `utm_campaign` label on the
+ * address, and which of those the device claimed as a FIRST visit — and none
+ * of it is believed as sent:
+ *
+ *  - a page's campaign is counted only while the screen is still filed under
+ *    it and the campaign still exists;
+ *  - a label is counted only for the one live campaign on the site that
+ *    declares it;
+ *  - a campaign named by both the page and the label in one beacon is one
+ *    visit, and counts once.
+ *
+ * `views` moves for the page's campaigns only — a label is an arrival, not a
+ * view of the campaign's pages. Never throws past the collector, which logs
+ * and answers 204 either way.
+ */
+export declare function countCampaignVisitBeacon(request: PluginSiteBeaconRequest, firestore?: any): Promise<number>;

package/src/lib/server/campaign-visit-beacon.js

@@ -0,0 +1,125 @@
+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 { FieldValue } from "firebase-admin/firestore";
+import firebaseAdmin from "@aglyn/tenant-data-admin/server/firebase-admin";
+import { resolveOrgIdForHost } from "@aglyn/tenant-data-admin/server/organizations";
+import { CAMPAIGN_VISIT_REPORTS_COLLECTION } from "../model/campaign-visits.js";
+import { campaignForUtmLabel, readLiveCampaign, readScreenCampaignIds } from "./campaign-touch-targets.js";
+/**
+ * The body field that marks a beacon as a campaign visit. The site runtime
+ * sends it; the collector hands the beacon here after its host, lockdown and
+ * rate gates.
+ */ export const CAMPAIGN_VISIT_BEACON_FIELD = 'campaignVisit';
+/** The most campaigns one beacon may name, matching the page touch. */ const MAX_CAMPAIGNS = 5;
+const DOCUMENT_ID = /^[A-Za-z0-9_-]{1,64}$/;
+function idsOf(raw) {
+    if (!Array.isArray(raw)) return [];
+    const ids = [];
+    for (const entry of raw){
+        const id = typeof entry === 'string' ? entry.trim() : '';
+        if (!DOCUMENT_ID.test(id) || ids.includes(id)) continue;
+        ids.push(id);
+        if (ids.length >= MAX_CAMPAIGNS) break;
+    }
+    return ids;
+}
+/**
+ * Counts one campaign visit beacon (AGL-3461) into
+ * `orgs/{orgId}/campaignVisitReports/{campaignId}`.
+ *
+ * The body says what the visitor's browser saw — the screen and the
+ * campaigns its page was filed under, the `utm_campaign` label on the
+ * address, and which of those the device claimed as a FIRST visit — and none
+ * of it is believed as sent:
+ *
+ *  - a page's campaign is counted only while the screen is still filed under
+ *    it and the campaign still exists;
+ *  - a label is counted only for the one live campaign on the site that
+ *    declares it;
+ *  - a campaign named by both the page and the label in one beacon is one
+ *    visit, and counts once.
+ *
+ * `views` moves for the page's campaigns only — a label is an arrival, not a
+ * view of the campaign's pages. Never throws past the collector, which logs
+ * and answers 204 either way.
+ */ export async function countCampaignVisitBeacon(request, firestore = firebaseAdmin.app().firestore()) {
+    const { hostId, day, body } = request;
+    const orgId = await resolveOrgIdForHost(hostId);
+    if (!orgId) return 0;
+    const month = String(day != null ? day : '').slice(0, 7);
+    /** Per campaign: whether this pageview viewed its page, and whether it was a first visit. */ const counted = new Map();
+    const note = (id, view, first)=>{
+        var _counted_get;
+        const held = (_counted_get = counted.get(id)) != null ? _counted_get : {
+            view: false,
+            first: false
+        };
+        counted.set(id, {
+            view: held.view || view,
+            first: held.first || first
+        });
+    };
+    const screenId = typeof body['screenId'] === 'string' ? body['screenId'].trim() : '';
+    const carried = idsOf(body['campaignIds']);
+    const firsts = new Set(idsOf(body['first']));
+    if (DOCUMENT_ID.test(screenId) && carried.length) {
+        const filed = await readScreenCampaignIds({
+            hostId,
+            screenId
+        }, firestore);
+        for (const id of carried){
+            if (!(filed == null ? void 0 : filed.includes(id))) continue;
+            if (!await readLiveCampaign({
+                orgId,
+                campaignId: id
+            }, firestore)) continue;
+            note(id, true, firsts.has(id));
+        }
+    }
+    const label = typeof body['utmCampaign'] === 'string' ? body['utmCampaign'] : '';
+    if (label && body['firstLabel'] === true) {
+        const campaign = await campaignForUtmLabel({
+            orgId,
+            hostId,
+            label
+        }, firestore);
+        if (campaign) note(campaign.id, false, true);
+    }
+    const reports = firestore.collection('orgs').doc(orgId).collection(CAMPAIGN_VISIT_REPORTS_COLLECTION);
+    await Promise.all([
+        ...counted.entries()
+    ].map(([campaignId, { view, first }])=>{
+        const fields = _extends({}, view ? {
+            views: FieldValue.increment(1)
+        } : {}, first ? {
+            firstVisits: FieldValue.increment(1)
+        } : {});
+        if (!Object.keys(fields).length) return Promise.resolve();
+        return reports.doc(campaignId).set(_extends({}, fields, /^\d{4}-\d{2}$/.test(month) ? {
+            byMonth: {
+                [month]: fields
+            }
+        } : {}, {
+            updatedAt: FieldValue.serverTimestamp()
+        }), {
+            merge: true
+        });
+    }));
+    return counted.size;
+}
+
+//# sourceMappingURL=campaign-visit-beacon.js.map

package/src/lib/server/campaign-visit-beacon.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/marketing/src/lib/server/campaign-visit-beacon.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 { FieldValue } from 'firebase-admin/firestore'\nimport type { PluginSiteBeaconRequest } from '@aglyn/aglyn/plugin-manager/plugin-site-beacons'\nimport firebaseAdmin from '@aglyn/tenant-data-admin/server/firebase-admin'\nimport { resolveOrgIdForHost } from '@aglyn/tenant-data-admin/server/organizations'\nimport { CAMPAIGN_VISIT_REPORTS_COLLECTION } from '../model/campaign-visits'\nimport {\n  campaignForUtmLabel,\n  readLiveCampaign,\n  readScreenCampaignIds,\n} from './campaign-touch-targets'\n\n/**\n * The body field that marks a beacon as a campaign visit. The site runtime\n * sends it; the collector hands the beacon here after its host, lockdown and\n * rate gates.\n */\nexport const CAMPAIGN_VISIT_BEACON_FIELD = 'campaignVisit'\n\n/** The most campaigns one beacon may name, matching the page touch. */\nconst MAX_CAMPAIGNS = 5\n\nconst DOCUMENT_ID = /^[A-Za-z0-9_-]{1,64}$/\n\nfunction idsOf(raw: unknown): string[] {\n  if (!Array.isArray(raw)) return []\n  const ids: string[] = []\n  for (const entry of raw) {\n    const id = typeof entry === 'string' ? entry.trim() : ''\n    if (!DOCUMENT_ID.test(id) || ids.includes(id)) continue\n    ids.push(id)\n    if (ids.length >= MAX_CAMPAIGNS) break\n  }\n  return ids\n}\n\n/**\n * Counts one campaign visit beacon (AGL-3461) into\n * `orgs/{orgId}/campaignVisitReports/{campaignId}`.\n *\n * The body says what the visitor's browser saw — the screen and the\n * campaigns its page was filed under, the `utm_campaign` label on the\n * address, and which of those the device claimed as a FIRST visit — and none\n * of it is believed as sent:\n *\n *  - a page's campaign is counted only while the screen is still filed under\n *    it and the campaign still exists;\n *  - a label is counted only for the one live campaign on the site that\n *    declares it;\n *  - a campaign named by both the page and the label in one beacon is one\n *    visit, and counts once.\n *\n * `views` moves for the page's campaigns only — a label is an arrival, not a\n * view of the campaign's pages. Never throws past the collector, which logs\n * and answers 204 either way.\n */\nexport async function countCampaignVisitBeacon(\n  request: PluginSiteBeaconRequest,\n  firestore: any = firebaseAdmin.app().firestore(),\n): Promise<number> {\n  const { hostId, day, body } = request\n  const orgId = await resolveOrgIdForHost(hostId)\n  if (!orgId) return 0\n  const month = String(day ?? '').slice(0, 7)\n\n  /** Per campaign: whether this pageview viewed its page, and whether it was a first visit. */\n  const counted = new Map<string, { view: boolean; first: boolean }>()\n  const note = (id: string, view: boolean, first: boolean) => {\n    const held = counted.get(id) ?? { view: false, first: false }\n    counted.set(id, { view: held.view || view, first: held.first || first })\n  }\n\n  const screenId = typeof body['screenId'] === 'string' ? body['screenId'].trim() : ''\n  const carried = idsOf(body['campaignIds'])\n  const firsts = new Set(idsOf(body['first']))\n  if (DOCUMENT_ID.test(screenId) && carried.length) {\n    const filed = await readScreenCampaignIds({ hostId, screenId }, firestore)\n    for (const id of carried) {\n      if (!filed?.includes(id)) continue\n      if (!(await readLiveCampaign({ orgId, campaignId: id }, firestore))) continue\n      note(id, true, firsts.has(id))\n    }\n  }\n\n  const label = typeof body['utmCampaign'] === 'string' ? body['utmCampaign'] : ''\n  if (label && body['firstLabel'] === true) {\n    const campaign = await campaignForUtmLabel({ orgId, hostId, label }, firestore)\n    if (campaign) note(campaign.id, false, true)\n  }\n\n  const reports = firestore\n    .collection('orgs')\n    .doc(orgId)\n    .collection(CAMPAIGN_VISIT_REPORTS_COLLECTION)\n  await Promise.all(\n    [...counted.entries()].map(([campaignId, { view, first }]) => {\n      const fields: Record<string, unknown> = {\n        ...(view ? { views: FieldValue.increment(1) } : {}),\n        ...(first ? { firstVisits: FieldValue.increment(1) } : {}),\n      }\n      if (!Object.keys(fields).length) return Promise.resolve()\n      return reports.doc(campaignId).set(\n        {\n          ...fields,\n          ...(/^\\d{4}-\\d{2}$/.test(month) ? { byMonth: { [month]: fields } } : {}),\n          updatedAt: FieldValue.serverTimestamp(),\n        },\n        { merge: true },\n      )\n    }),\n  )\n  return counted.size\n}\n"],"names":["FieldValue","firebaseAdmin","resolveOrgIdForHost","CAMPAIGN_VISIT_REPORTS_COLLECTION","campaignForUtmLabel","readLiveCampaign","readScreenCampaignIds","CAMPAIGN_VISIT_BEACON_FIELD","MAX_CAMPAIGNS","DOCUMENT_ID","idsOf","raw","Array","isArray","ids","entry","id","trim","test","includes","push","length","countCampaignVisitBeacon","request","firestore","app","hostId","day","body","orgId","month","String","slice","counted","Map","note","view","first","held","get","set","screenId","carried","firsts","Set","filed","campaignId","has","label","campaign","reports","collection","doc","Promise","all","entries","map","fields","views","increment","firstVisits","Object","keys","resolve","byMonth","updatedAt","serverTimestamp","merge","size"],"mappings":"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"}

package/src/lib/server/conversion-creditor.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @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 { PluginConversionCreditor } from '@aglyn/aglyn/plugin-manager/plugin-conversion-credit';
+export declare const marketingConversionCreditor: PluginConversionCreditor;