@aglyn/tenant-data-admin 1.0.0-beta.221 → 1.0.0-beta.223

package/src/lib/server/dataset-live-pages.js

@@ -1,421 +0,0 @@
-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.
- */ /**
- * A dataset record write refreshes the live pages that show it (AGL-3113).
- *
- * ## What was missing
- *
- * Every other change a visitor can see announces itself the moment it lands: a
- * publish, a layout, a component, a content entry, a redirect rule, the
- * maintenance toggle. A dataset RECORD did not. It was written — by a form, by
- * an automation, over `/v1`, from the console — and the pages repeating over
- * it went on serving the rows they were built from until the hour-long window
- * lapsed. `PUBLISHED_SITE_DATA_TTL_SECONDS` was the propagation mechanism,
- * which is the same mistake AGL-1302 and AGL-1150 each had to undo elsewhere:
- * a backstop doing a job nothing else was doing.
- *
- * ## Scope, not the site
- *
- * A record changed one dataset, so this drops the pages that repeat over that
- * dataset and nothing else. The set is derived from the SAME binding the
- * published page expands — `repeatKeys`, the generic
- * `props.repeatDataset` any node can now carry (AGL-3111) — rather than from a
- * list of components that may repeat. A component allowlist was already wrong
- * the day repeat stopped being the Stack's: a heading bound to a dataset
- * renders rows exactly as a Stack does, and would have been missed.
- *
- * Three corpora, because the composer reads repeat keys after the layout chain
- * and the reusable-component graft: a repeat in a layout's chrome or inside a
- * component reaches every screen that renders it.
- *
- * ## Which sites
- *
- * Datasets are ORG-scoped and shared with sites through `visibleTo` — every
- * site in the org, or up to `MAX_SCOPE_HOSTS` named ones. Each site caches its
- * own copy of the rows under its own `tenant-data:{hostId}` tag and its own
- * page keys, so one record write is a fan-out. A missing `visibleTo` is
- * visible to NOBODY and announces nothing; defaulting it to org-wide here
- * would re-make AGL-1466 in the cache layer.
- *
- * ## Best effort, always
- *
- * The record is already written by the time any of this runs. A refused or
- * failed drop is reported to the caller and logged, never thrown: a record
- * must not be lost because a cache refused, and the TTL is still underneath as
- * the backstop it was always meant to be.
- */ import { ORG_SCOPE_TOKEN, hostIdsFromScope, repeatKeys, screenRoutePathToUrl } from "@aglyn/aglyn/server";
-import { readUsageSources, screenIdsUsingComponentDeep, screenIdsUsingLayoutDeep, isLiveUsageCandidate } from "./live-page-usage.js";
-/**
- * How many documents per collection the per-site scan reads.
- *
- * The console's publish scan uses the same number for the same reason
- * (AGL-1161): this decides which caches get dropped, so a prefix scan would
- * report a refreshed site and leave real pages serving the old rows. Bounded
- * all the same, and when the bound bites it is SAID rather than absorbed.
- */ export const DATASET_SCAN_LIMIT = 2000;
-/**
- * How many sites one record write fans out to.
- *
- * `MAX_SCOPE_HOSTS` is the ceiling on a NAMED selection, so only an org-wide
- * dataset can reach this — an org with more sites than this pays a scan per
- * site on every write otherwise, which is a cost the person writing one row
- * did not ask for. Sites past the cap keep the TTL they had before this
- * existed, and the shortfall is returned and logged rather than swallowed.
- */ export const MAX_DATASET_FANOUT_HOSTS = 30;
-/**
- * How long one site-and-dataset pair waits before announcing again.
- *
- * A 1,000-row import is one announce because the importer announces after its
- * loop, not per row. This covers the other burst — many small writes arriving
- * separately, a form under load or an automation fanning out — where each one
- * would otherwise pay a full scan per site and hand the tenant the same path
- * list again.
- *
- * Leading edge, so the FIRST write of a burst refreshes immediately; what is
- * skipped is a repeat inside the window, and the next write after it announces
- * again. The cost of the skip is bounded by the window: a row written during
- * one is visible no later than the next announce.
- */ export const DATASET_ANNOUNCE_WINDOW_MS = 2000;
-/** Last announce per `orgId/datasetId/hostId`, for the window above. */ const lastAnnouncedAt = new Map();
-/**
- * Bounded so a long-lived server cannot grow this map without limit. Far above
- * the number of datasets any one instance writes in a window; when it bites,
- * the oldest entries simply lose their throttle and announce again.
- */ const MAX_THROTTLE_ENTRIES = 5000;
-function throttleAllows(key, now) {
-    const previous = lastAnnouncedAt.get(key);
-    if (previous !== undefined && now - previous < DATASET_ANNOUNCE_WINDOW_MS) {
-        return false;
-    }
-    if (lastAnnouncedAt.size >= MAX_THROTTLE_ENTRIES) lastAnnouncedAt.clear();
-    lastAnnouncedAt.set(key, now);
-    return true;
-}
-/** Test seam: the window is process-wide state, so a spec has to reset it. */ export function resetDatasetAnnounceThrottle() {
-    lastAnnouncedAt.clear();
-}
-/**
- * Whether a node tree repeats over any of `keys`.
- *
- * Asks `repeatKeys` — literally the function the tenant composer calls
- * to decide which datasets to load for a page — so this cannot come to
- * disagree with what actually renders. A predicate even slightly narrower than
- * the expansion's is a page that renders rows and never refreshes them.
- */ function nodesRepeatDataset(nodes, keys) {
-    return repeatKeys(nodes).some((key)=>keys.has(key));
-}
-/**
- * Every live screen whose rendered output repeats over the dataset, however
- * indirectly.
- *
- * The same three-bucket closure a placed form's pages are found by, for the
- * same reason: a binding is found by SEARCHING node trees rather than by
- * matching a pointer, so it can sit on the screen, in the chrome of the layout
- * the screen renders inside, or inside a reusable component a third component
- * nests. After the first level the fan-out is identical, so it is delegated
- * rather than restated.
- *
- * Pure, and separate from the Firestore read, so the closure is testable
- * without a database.
- */ export function screenIdsRepeatingDataset(keys, sources) {
-    if (!keys.size) return [];
-    const screenIds = new Set();
-    for (const candidate of sources.screens){
-        if (!isLiveUsageCandidate(candidate)) continue;
-        if (nodesRepeatDataset(candidate.nodes, keys)) screenIds.add(candidate.id);
-    }
-    for (const candidate of sources.layouts){
-        if (!isLiveUsageCandidate(candidate)) continue;
-        if (!nodesRepeatDataset(candidate.nodes, keys)) continue;
-        // The layout itself renders no URL; the screens beneath it do.
-        for (const screenId of screenIdsUsingLayoutDeep(candidate.id, sources.screens, sources.layouts)){
-            screenIds.add(screenId);
-        }
-    }
-    for (const candidate of sources.components){
-        if (!isLiveUsageCandidate(candidate)) continue;
-        if (!nodesRepeatDataset(candidate.nodes, keys)) continue;
-        // And a component renders wherever it is placed, however deeply nested.
-        for (const screenId of screenIdsUsingComponentDeep(candidate.id, sources)){
-            screenIds.add(screenId);
-        }
-    }
-    return [
-        ...screenIds
-    ];
-}
-/**
- * The keys a page can be bound to this dataset by: its id, and the display
- * name editors type into the Repeat attribute.
- *
- * Both, because the expansion looks a key up either way (the data plugin's
- * repeat rows resolve an id first and then a display name). Matching only the id would
- * miss every binding written by name, which is the older and still-supported
- * half of them.
- */ function datasetKeysOf(snapshot) {
-    var _snapshot_get;
-    const keys = new Set([
-        snapshot.id
-    ]);
-    const displayName = String((_snapshot_get = snapshot.get('displayName')) != null ? _snapshot_get : '').trim();
-    if (displayName) keys.add(displayName);
-    return keys;
-}
-/**
- * The sites a dataset is shared with, as host ids.
- *
- * Fails CLOSED on a missing or empty `visibleTo`, matching `visibleToHost` and
- * both enforcement layers underneath it: a document nobody scoped is shared
- * with nobody, and reading it as org-wide here would announce one org's
- * dataset change to sites that cannot see the dataset at all.
- */ async function hostIdsSharingDataset(firestore, orgId, visibleTo) {
-    if (!Array.isArray(visibleTo) || !visibleTo.length) {
-        return {
-            hostIds: [],
-            hostsDropped: 0
-        };
-    }
-    if (!visibleTo.includes(ORG_SCOPE_TOKEN)) {
-        const named = hostIdsFromScope(visibleTo);
-        return {
-            hostIds: named,
-            hostsDropped: 0
-        };
-    }
-    // One over the cap, so a shortfall is detected rather than assumed away.
-    const hosts = await firestore.collection('hosts').where('orgId', '==', orgId).limit(MAX_DATASET_FANOUT_HOSTS + 1).get();
-    const all = hosts.docs.map((doc)=>doc.id);
-    return {
-        hostIds: all.slice(0, MAX_DATASET_FANOUT_HOSTS),
-        hostsDropped: Math.max(0, all.length - MAX_DATASET_FANOUT_HOSTS)
-    };
-}
-/** One site's paths, or `null` when the site has nothing to refresh. */ async function targetForHost(firestore, hostId, keys) {
-    var _hostSnapshot_get, _hostSnapshot_get1, _hostSnapshot_get2;
-    const hostRef = firestore.collection('hosts').doc(hostId);
-    const hostSnapshot = await hostRef.get();
-    if (!hostSnapshot.exists) return null;
-    const subdomain = String((_hostSnapshot_get = hostSnapshot.get('subdomain')) != null ? _hostSnapshot_get : '');
-    // Without a subdomain there is no tenant deployment holding cached pages for
-    // this site — the ordinary state of one not yet given a name, not a failure.
-    if (!subdomain) return null;
-    const sources = await readUsageSources(hostRef, DATASET_SCAN_LIMIT);
-    const screens = (_hostSnapshot_get1 = hostSnapshot.get('screens')) != null ? _hostSnapshot_get1 : {};
-    const paths = screenIdsRepeatingDataset(keys, sources.candidates).map((screenId)=>screens[screenId]).filter((path)=>Boolean(path)).map((path)=>screenRoutePathToUrl(path)).filter((path, index, all)=>all.indexOf(path) === index);
-    if (!paths.length) return null;
-    const cname = String((_hostSnapshot_get2 = hostSnapshot.get('cname')) != null ? _hostSnapshot_get2 : '');
-    return _extends({
-        hostId,
-        subdomain
-    }, cname ? {
-        cname
-    } : {}, {
-        paths,
-        truncated: sources.truncated
-    });
-}
-/**
- * Every live page a change to this dataset's records makes stale, per site.
- *
- * Reads only; announcing is the caller's, because the two runtimes announce
- * differently — the console posts to the tenant over the shared secret, and
- * the tenant drops its own caches in process. Splitting it here is what lets
- * both use one answer to the question of WHICH pages.
- *
- * Never throws. A scope that could not be computed is a scope of nothing, and
- * the TTL underneath is unaffected.
- */ export async function datasetLivePageScope(options) {
-    const { firestore, orgId, datasetId } = options;
-    if (!orgId || !datasetId) {
-        return {
-            targets: [],
-            hostsDropped: 0,
-            reason: 'no-dataset'
-        };
-    }
-    try {
-        const snapshot = await firestore.collection('orgs').doc(orgId).collection('datasets').doc(datasetId).get();
-        if (!snapshot.exists) {
-            return {
-                targets: [],
-                hostsDropped: 0,
-                reason: 'no-dataset'
-            };
-        }
-        const { hostIds, hostsDropped } = await hostIdsSharingDataset(firestore, orgId, snapshot.get('visibleTo'));
-        if (!hostIds.length) {
-            return {
-                targets: [],
-                hostsDropped,
-                reason: 'no-sites'
-            };
-        }
-        const keys = datasetKeysOf(snapshot);
-        const resolved = await Promise.all(hostIds.map(async (hostId)=>{
-            try {
-                return await targetForHost(firestore, hostId, keys);
-            } catch (error) {
-                // One unreadable site must not cost the others their refresh.
-                console.error('[dataset-live-pages] site scan failed', hostId, error);
-                return null;
-            }
-        }));
-        const targets = resolved.filter((target)=>target !== null);
-        return {
-            targets,
-            hostsDropped,
-            reason: targets.length ? 'ok' : 'not-rendered'
-        };
-    } catch (error) {
-        console.error('[dataset-live-pages] scope failed', datasetId, error);
-        return {
-            targets: [],
-            hostsDropped: 0,
-            reason: 'error'
-        };
-    }
-}
-let registeredDropper;
-/**
- * Registers the dropper for this process, replacing any previous one. Returns
- * the unregister, which removes it only if it is still the one registered.
- *
- * Called from a function the platform calls BY NAME at boot, never from a
- * module's top level: a bundler deletes a module imported only for its side
- * effect when its package says it has none (AGL-3025).
- */ export function registerLivePageDropper(drop) {
-    registeredDropper = drop;
-    return ()=>{
-        if (registeredDropper === drop) registeredDropper = undefined;
-    };
-}
-const EMPTY_RESULT = {
-    sitesRefreshed: 0,
-    pathsRefreshed: 0,
-    sitesRefused: 0,
-    hostsDropped: 0,
-    scanTruncated: false
-};
-/**
- * Refresh every live page that shows this dataset's records.
- *
- * The one call a write path makes. BEST EFFORT, ALWAYS: it never throws and
- * never rejects, so a caller can `await` it inside the try that already guards
- * the write without any chance of turning a stored record into a failed one.
- *
- * `drop` overrides the registered dropper for callers that hold their own —
- * the console, whose announce is an authenticated request rather than a local
- * cache call.
- */ export async function announceDatasetRecordChange(options) {
-    var _options_drop;
-    const { firestore, orgId, datasetId } = options;
-    const drop = (_options_drop = options.drop) != null ? _options_drop : registeredDropper;
-    if (!drop) {
-        // Said out loud: a process that writes records and registered no dropper
-        // is one where this feature is silently absent, which reads exactly like
-        // a working one until somebody watches a page fail to change.
-        console.warn(JSON.stringify({
-            tag: 'AGL-3113:no-live-page-dropper',
-            orgId,
-            datasetId
-        }));
-        return _extends({}, EMPTY_RESULT, {
-            reason: 'no-dropper'
-        });
-    }
-    const throttleKey = `${orgId}/${datasetId}`;
-    if (!throttleAllows(throttleKey, Date.now())) {
-        return _extends({}, EMPTY_RESULT, {
-            reason: 'throttled'
-        });
-    }
-    const scope = await datasetLivePageScope({
-        firestore,
-        orgId,
-        datasetId
-    });
-    if (!scope.targets.length) {
-        return _extends({}, EMPTY_RESULT, {
-            hostsDropped: scope.hostsDropped,
-            reason: scope.reason
-        });
-    }
-    let sitesRefreshed = 0;
-    let sitesRefused = 0;
-    let pathsRefreshed = 0;
-    for (const target of scope.targets){
-        let landed = false;
-        try {
-            landed = await drop(target);
-        } catch (error) {
-            // A dropper that throws is a dropper that failed; it is not a write
-            // that failed.
-            console.error('[dataset-live-pages] drop failed', target.hostId, error);
-        }
-        if (landed) {
-            sitesRefreshed += 1;
-            pathsRefreshed += target.paths.length;
-        } else {
-            sitesRefused += 1;
-        }
-    }
-    const scanTruncated = scope.targets.some((target)=>target.truncated);
-    const result = {
-        sitesRefreshed,
-        pathsRefreshed,
-        sitesRefused,
-        hostsDropped: scope.hostsDropped,
-        scanTruncated,
-        reason: scope.reason
-    };
-    // ONE line per announce, on success as well as failure, for the reason
-    // `postTenantRevalidate` gives: a record that only logs its failures cannot
-    // tell "every write refreshed" apart from "the call never happened", and
-    // that ambiguity is how an eleven-day propagation outage went unnoticed.
-    console.log(JSON.stringify(_extends({
-        tag: 'AGL-3113:dataset-announce',
-        orgId,
-        datasetId
-    }, result)));
-    return result;
-}
-/**
- * One sentence for a refresh that did not cover every page, or `null` when it
- * did.
- *
- * Beside the call rather than at each surface, so the console cannot word this
- * differently in two places — the same reason `describeRevalidateShortfall`
- * lives beside `revalidateLivePages`. `lead` names the act that succeeded,
- * because only that word differs between surfaces: a record is SAVED, and
- * telling someone who fixed a typo that they published it is a worse error
- * than the staleness the sentence is about.
- */ export function describeDatasetAnnounceShortfall(result, lead = 'Saved.') {
-    if (!result) return null;
-    // `not-rendered`, `no-sites` and `throttled` are deliberately silent: a
-    // dataset no page shows has no stale page, and a throttled drop means one
-    // already went out a moment ago. Saying anything would be alarming and wrong.
-    if (result.reason === 'error' || result.sitesRefused) {
-        return `${lead} The live pages could not be refreshed just now, so they ` + 'may show the previous records for up to an hour.';
-    }
-    if (result.hostsDropped || result.scanTruncated) {
-        return `${lead} Some pages that use this dataset are too many to refresh at ` + 'once — they update on their own within an hour.';
-    }
-    return null;
-}
-export default announceDatasetRecordChange;
-
-//# sourceMappingURL=dataset-live-pages.js.map

package/src/lib/server/dataset-live-pages.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../../../../../../../../libs/tenant/data/admin/src/lib/server/dataset-live-pages.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n/**\n * A dataset record write refreshes the live pages that show it (AGL-3113).\n *\n * ## What was missing\n *\n * Every other change a visitor can see announces itself the moment it lands: a\n * publish, a layout, a component, a content entry, a redirect rule, the\n * maintenance toggle. A dataset RECORD did not. It was written — by a form, by\n * an automation, over `/v1`, from the console — and the pages repeating over\n * it went on serving the rows they were built from until the hour-long window\n * lapsed. `PUBLISHED_SITE_DATA_TTL_SECONDS` was the propagation mechanism,\n * which is the same mistake AGL-1302 and AGL-1150 each had to undo elsewhere:\n * a backstop doing a job nothing else was doing.\n *\n * ## Scope, not the site\n *\n * A record changed one dataset, so this drops the pages that repeat over that\n * dataset and nothing else. The set is derived from the SAME binding the\n * published page expands — `repeatKeys`, the generic\n * `props.repeatDataset` any node can now carry (AGL-3111) — rather than from a\n * list of components that may repeat. A component allowlist was already wrong\n * the day repeat stopped being the Stack's: a heading bound to a dataset\n * renders rows exactly as a Stack does, and would have been missed.\n *\n * Three corpora, because the composer reads repeat keys after the layout chain\n * and the reusable-component graft: a repeat in a layout's chrome or inside a\n * component reaches every screen that renders it.\n *\n * ## Which sites\n *\n * Datasets are ORG-scoped and shared with sites through `visibleTo` — every\n * site in the org, or up to `MAX_SCOPE_HOSTS` named ones. Each site caches its\n * own copy of the rows under its own `tenant-data:{hostId}` tag and its own\n * page keys, so one record write is a fan-out. A missing `visibleTo` is\n * visible to NOBODY and announces nothing; defaulting it to org-wide here\n * would re-make AGL-1466 in the cache layer.\n *\n * ## Best effort, always\n *\n * The record is already written by the time any of this runs. A refused or\n * failed drop is reported to the caller and logged, never thrown: a record\n * must not be lost because a cache refused, and the TTL is still underneath as\n * the backstop it was always meant to be.\n */\n\nimport {\n  ORG_SCOPE_TOKEN,\n  hostIdsFromScope,\n  repeatKeys,\n  screenRoutePathToUrl,\n} from '@aglyn/aglyn/server'\nimport type { Firestore } from 'firebase-admin/firestore'\nimport {\n  readUsageSources,\n  screenIdsUsingComponentDeep,\n  screenIdsUsingLayoutDeep,\n  isLiveUsageCandidate,\n  type UsageCandidate,\n  type UsageSources,\n} from './live-page-usage'\n\n/**\n * How many documents per collection the per-site scan reads.\n *\n * The console's publish scan uses the same number for the same reason\n * (AGL-1161): this decides which caches get dropped, so a prefix scan would\n * report a refreshed site and leave real pages serving the old rows. Bounded\n * all the same, and when the bound bites it is SAID rather than absorbed.\n */\nexport const DATASET_SCAN_LIMIT = 2000\n\n/**\n * How many sites one record write fans out to.\n *\n * `MAX_SCOPE_HOSTS` is the ceiling on a NAMED selection, so only an org-wide\n * dataset can reach this — an org with more sites than this pays a scan per\n * site on every write otherwise, which is a cost the person writing one row\n * did not ask for. Sites past the cap keep the TTL they had before this\n * existed, and the shortfall is returned and logged rather than swallowed.\n */\nexport const MAX_DATASET_FANOUT_HOSTS = 30\n\n/**\n * How long one site-and-dataset pair waits before announcing again.\n *\n * A 1,000-row import is one announce because the importer announces after its\n * loop, not per row. This covers the other burst — many small writes arriving\n * separately, a form under load or an automation fanning out — where each one\n * would otherwise pay a full scan per site and hand the tenant the same path\n * list again.\n *\n * Leading edge, so the FIRST write of a burst refreshes immediately; what is\n * skipped is a repeat inside the window, and the next write after it announces\n * again. The cost of the skip is bounded by the window: a row written during\n * one is visible no later than the next announce.\n */\nexport const DATASET_ANNOUNCE_WINDOW_MS = 2000\n\n/** Last announce per `orgId/datasetId/hostId`, for the window above. */\nconst lastAnnouncedAt = new Map<string, number>()\n\n/**\n * Bounded so a long-lived server cannot grow this map without limit. Far above\n * the number of datasets any one instance writes in a window; when it bites,\n * the oldest entries simply lose their throttle and announce again.\n */\nconst MAX_THROTTLE_ENTRIES = 5000\n\nfunction throttleAllows(key: string, now: number): boolean {\n  const previous = lastAnnouncedAt.get(key)\n  if (previous !== undefined && now - previous < DATASET_ANNOUNCE_WINDOW_MS) {\n    return false\n  }\n  if (lastAnnouncedAt.size >= MAX_THROTTLE_ENTRIES) lastAnnouncedAt.clear()\n  lastAnnouncedAt.set(key, now)\n  return true\n}\n\n/** Test seam: the window is process-wide state, so a spec has to reset it. */\nexport function resetDatasetAnnounceThrottle(): void {\n  lastAnnouncedAt.clear()\n}\n\n/** One site's share of a dataset change. */\nexport interface DatasetLivePageTarget {\n  hostId: string\n  /** The tenant keys its cache on this, never on `hostId`. */\n  subdomain: string\n  /** The attached custom domain, whose pages live under a second cache key. */\n  cname?: string\n  /** Site-absolute addresses (`/`, `/team`) that repeat over the dataset. */\n  paths: string[]\n  /** The site held more documents than the scan read, so `paths` is partial. */\n  truncated: boolean\n}\n\nexport interface DatasetLivePageScope {\n  targets: DatasetLivePageTarget[]\n  /**\n   * Sites the fan-out cap left out. Zero in the ordinary case, and reported\n   * rather than logged because a caller that says \"refreshed\" while some sites\n   * were skipped is the failure this whole arc exists to remove.\n   */\n  hostsDropped: number\n  /**\n   * Why there is nothing to announce, or `'ok'`.\n   *\n   * `'not-rendered'` is a success: a dataset no page repeats over has no live\n   * page to refresh. It is kept apart from `'error'` for the same reason the\n   * revalidate route keeps `not-routed` apart from a refusal — one means there\n   * was nothing to do, the other means something was left stale.\n   */\n  reason: 'ok' | 'no-dataset' | 'no-sites' | 'not-rendered' | 'error'\n}\n\n/**\n * Whether a node tree repeats over any of `keys`.\n *\n * Asks `repeatKeys` — literally the function the tenant composer calls\n * to decide which datasets to load for a page — so this cannot come to\n * disagree with what actually renders. A predicate even slightly narrower than\n * the expansion's is a page that renders rows and never refreshes them.\n */\nfunction nodesRepeatDataset(\n  nodes: UsageCandidate['nodes'],\n  keys: ReadonlySet<string>,\n): boolean {\n  return repeatKeys(nodes).some((key) => keys.has(key))\n}\n\n/**\n * Every live screen whose rendered output repeats over the dataset, however\n * indirectly.\n *\n * The same three-bucket closure a placed form's pages are found by, for the\n * same reason: a binding is found by SEARCHING node trees rather than by\n * matching a pointer, so it can sit on the screen, in the chrome of the layout\n * the screen renders inside, or inside a reusable component a third component\n * nests. After the first level the fan-out is identical, so it is delegated\n * rather than restated.\n *\n * Pure, and separate from the Firestore read, so the closure is testable\n * without a database.\n */\nexport function screenIdsRepeatingDataset(\n  keys: ReadonlySet<string>,\n  sources: UsageSources,\n): string[] {\n  if (!keys.size) return []\n  const screenIds = new Set<string>()\n\n  for (const candidate of sources.screens) {\n    if (!isLiveUsageCandidate(candidate)) continue\n    if (nodesRepeatDataset(candidate.nodes, keys)) screenIds.add(candidate.id)\n  }\n  for (const candidate of sources.layouts) {\n    if (!isLiveUsageCandidate(candidate)) continue\n    if (!nodesRepeatDataset(candidate.nodes, keys)) continue\n    // The layout itself renders no URL; the screens beneath it do.\n    for (const screenId of screenIdsUsingLayoutDeep(\n      candidate.id,\n      sources.screens,\n      sources.layouts,\n    )) {\n      screenIds.add(screenId)\n    }\n  }\n  for (const candidate of sources.components) {\n    if (!isLiveUsageCandidate(candidate)) continue\n    if (!nodesRepeatDataset(candidate.nodes, keys)) continue\n    // And a component renders wherever it is placed, however deeply nested.\n    for (const screenId of screenIdsUsingComponentDeep(candidate.id, sources)) {\n      screenIds.add(screenId)\n    }\n  }\n\n  return [...screenIds]\n}\n\n/**\n * The keys a page can be bound to this dataset by: its id, and the display\n * name editors type into the Repeat attribute.\n *\n * Both, because the expansion looks a key up either way (the data plugin's\n * repeat rows resolve an id first and then a display name). Matching only the id would\n * miss every binding written by name, which is the older and still-supported\n * half of them.\n */\nfunction datasetKeysOf(\n  snapshot: FirebaseFirestore.DocumentSnapshot,\n): Set<string> {\n  const keys = new Set<string>([snapshot.id])\n  const displayName = String(snapshot.get('displayName') ?? '').trim()\n  if (displayName) keys.add(displayName)\n  return keys\n}\n\n/**\n * The sites a dataset is shared with, as host ids.\n *\n * Fails CLOSED on a missing or empty `visibleTo`, matching `visibleToHost` and\n * both enforcement layers underneath it: a document nobody scoped is shared\n * with nobody, and reading it as org-wide here would announce one org's\n * dataset change to sites that cannot see the dataset at all.\n */\nasync function hostIdsSharingDataset(\n  firestore: Firestore,\n  orgId: string,\n  visibleTo: readonly string[] | undefined,\n): Promise<{ hostIds: string[]; hostsDropped: number }> {\n  if (!Array.isArray(visibleTo) || !visibleTo.length) {\n    return { hostIds: [], hostsDropped: 0 }\n  }\n  if (!visibleTo.includes(ORG_SCOPE_TOKEN)) {\n    const named = hostIdsFromScope(visibleTo)\n    return { hostIds: named, hostsDropped: 0 }\n  }\n  // One over the cap, so a shortfall is detected rather than assumed away.\n  const hosts = await firestore\n    .collection('hosts')\n    .where('orgId', '==', orgId)\n    .limit(MAX_DATASET_FANOUT_HOSTS + 1)\n    .get()\n  const all = hosts.docs.map((doc) => doc.id)\n  return {\n    hostIds: all.slice(0, MAX_DATASET_FANOUT_HOSTS),\n    hostsDropped: Math.max(0, all.length - MAX_DATASET_FANOUT_HOSTS),\n  }\n}\n\n/** One site's paths, or `null` when the site has nothing to refresh. */\nasync function targetForHost(\n  firestore: Firestore,\n  hostId: string,\n  keys: ReadonlySet<string>,\n): Promise<DatasetLivePageTarget | null> {\n  const hostRef = firestore.collection('hosts').doc(hostId)\n  const hostSnapshot = await hostRef.get()\n  if (!hostSnapshot.exists) return null\n  const subdomain = String(hostSnapshot.get('subdomain') ?? '')\n  // Without a subdomain there is no tenant deployment holding cached pages for\n  // this site — the ordinary state of one not yet given a name, not a failure.\n  if (!subdomain) return null\n\n  const sources = await readUsageSources(hostRef, DATASET_SCAN_LIMIT)\n  const screens = (hostSnapshot.get('screens') ?? {}) as Record<string, string>\n  const paths = screenIdsRepeatingDataset(keys, sources.candidates)\n    .map((screenId) => screens[screenId])\n    .filter((path): path is string => Boolean(path))\n    .map((path) => screenRoutePathToUrl(path))\n    .filter((path, index, all) => all.indexOf(path) === index)\n  if (!paths.length) return null\n\n  const cname = String(hostSnapshot.get('cname') ?? '')\n  return {\n    hostId,\n    subdomain,\n    ...(cname ? { cname } : {}),\n    paths,\n    truncated: sources.truncated,\n  }\n}\n\n/**\n * Every live page a change to this dataset's records makes stale, per site.\n *\n * Reads only; announcing is the caller's, because the two runtimes announce\n * differently — the console posts to the tenant over the shared secret, and\n * the tenant drops its own caches in process. Splitting it here is what lets\n * both use one answer to the question of WHICH pages.\n *\n * Never throws. A scope that could not be computed is a scope of nothing, and\n * the TTL underneath is unaffected.\n */\nexport async function datasetLivePageScope(options: {\n  firestore: Firestore\n  orgId: string\n  datasetId: string\n}): Promise<DatasetLivePageScope> {\n  const { firestore, orgId, datasetId } = options\n  if (!orgId || !datasetId) {\n    return { targets: [], hostsDropped: 0, reason: 'no-dataset' }\n  }\n  try {\n    const snapshot = await firestore\n      .collection('orgs')\n      .doc(orgId)\n      .collection('datasets')\n      .doc(datasetId)\n      .get()\n    if (!snapshot.exists) {\n      return { targets: [], hostsDropped: 0, reason: 'no-dataset' }\n    }\n    const { hostIds, hostsDropped } = await hostIdsSharingDataset(\n      firestore,\n      orgId,\n      snapshot.get('visibleTo') as readonly string[] | undefined,\n    )\n    if (!hostIds.length) {\n      return { targets: [], hostsDropped, reason: 'no-sites' }\n    }\n    const keys = datasetKeysOf(snapshot)\n    const resolved = await Promise.all(\n      hostIds.map(async (hostId) => {\n        try {\n          return await targetForHost(firestore, hostId, keys)\n        } catch (error) {\n          // One unreadable site must not cost the others their refresh.\n          console.error('[dataset-live-pages] site scan failed', hostId, error)\n          return null\n        }\n      }),\n    )\n    const targets = resolved.filter(\n      (target): target is DatasetLivePageTarget => target !== null,\n    )\n    return {\n      targets,\n      hostsDropped,\n      reason: targets.length ? 'ok' : 'not-rendered',\n    }\n  } catch (error) {\n    console.error('[dataset-live-pages] scope failed', datasetId, error)\n    return { targets: [], hostsDropped: 0, reason: 'error' }\n  }\n}\n\n/**\n * How one runtime drops a site's cached pages.\n *\n * The generic seam, registered by the deployment that owns the caches. The\n * tenant registers an in-process drop at boot; the console announces over the\n * shared secret and passes its own dropper at the call site. Core names\n * neither, exactly as it names no repeat source.\n *\n * Returns whether the drop landed. It must never throw: everything above it\n * has already been written.\n */\nexport type LivePageDropper = (\n  target: DatasetLivePageTarget,\n) => Promise<boolean>\n\nlet registeredDropper: LivePageDropper | undefined\n\n/**\n * Registers the dropper for this process, replacing any previous one. Returns\n * the unregister, which removes it only if it is still the one registered.\n *\n * Called from a function the platform calls BY NAME at boot, never from a\n * module's top level: a bundler deletes a module imported only for its side\n * effect when its package says it has none (AGL-3025).\n */\nexport function registerLivePageDropper(drop: LivePageDropper): () => void {\n  registeredDropper = drop\n  return () => {\n    if (registeredDropper === drop) registeredDropper = undefined\n  }\n}\n\nexport interface DatasetAnnounceResult {\n  /** Sites whose cached pages were dropped. */\n  sitesRefreshed: number\n  /** Pages named across those sites. */\n  pathsRefreshed: number\n  /** Sites the drop was attempted on and refused. */\n  sitesRefused: number\n  /** Sites past the fan-out cap, and sites whose scan was truncated. */\n  hostsDropped: number\n  scanTruncated: boolean\n  /** `'throttled'` when a drop for this pair already went out just now. */\n  reason: DatasetLivePageScope['reason'] | 'throttled' | 'no-dropper'\n}\n\nconst EMPTY_RESULT: Omit<DatasetAnnounceResult, 'reason'> = {\n  sitesRefreshed: 0,\n  pathsRefreshed: 0,\n  sitesRefused: 0,\n  hostsDropped: 0,\n  scanTruncated: false,\n}\n\n/**\n * Refresh every live page that shows this dataset's records.\n *\n * The one call a write path makes. BEST EFFORT, ALWAYS: it never throws and\n * never rejects, so a caller can `await` it inside the try that already guards\n * the write without any chance of turning a stored record into a failed one.\n *\n * `drop` overrides the registered dropper for callers that hold their own —\n * the console, whose announce is an authenticated request rather than a local\n * cache call.\n */\nexport async function announceDatasetRecordChange(options: {\n  firestore: Firestore\n  orgId: string\n  datasetId: string\n  drop?: LivePageDropper\n}): Promise<DatasetAnnounceResult> {\n  const { firestore, orgId, datasetId } = options\n  const drop = options.drop ?? registeredDropper\n  if (!drop) {\n    // Said out loud: a process that writes records and registered no dropper\n    // is one where this feature is silently absent, which reads exactly like\n    // a working one until somebody watches a page fail to change.\n    console.warn(\n      JSON.stringify({\n        tag: 'AGL-3113:no-live-page-dropper',\n        orgId,\n        datasetId,\n      }),\n    )\n    return { ...EMPTY_RESULT, reason: 'no-dropper' }\n  }\n  const throttleKey = `${orgId}/${datasetId}`\n  if (!throttleAllows(throttleKey, Date.now())) {\n    return { ...EMPTY_RESULT, reason: 'throttled' }\n  }\n  const scope = await datasetLivePageScope({ firestore, orgId, datasetId })\n  if (!scope.targets.length) {\n    return {\n      ...EMPTY_RESULT,\n      hostsDropped: scope.hostsDropped,\n      reason: scope.reason,\n    }\n  }\n\n  let sitesRefreshed = 0\n  let sitesRefused = 0\n  let pathsRefreshed = 0\n  for (const target of scope.targets) {\n    let landed = false\n    try {\n      landed = await drop(target)\n    } catch (error) {\n      // A dropper that throws is a dropper that failed; it is not a write\n      // that failed.\n      console.error('[dataset-live-pages] drop failed', target.hostId, error)\n    }\n    if (landed) {\n      sitesRefreshed += 1\n      pathsRefreshed += target.paths.length\n    } else {\n      sitesRefused += 1\n    }\n  }\n\n  const scanTruncated = scope.targets.some((target) => target.truncated)\n  const result: DatasetAnnounceResult = {\n    sitesRefreshed,\n    pathsRefreshed,\n    sitesRefused,\n    hostsDropped: scope.hostsDropped,\n    scanTruncated,\n    reason: scope.reason,\n  }\n  // ONE line per announce, on success as well as failure, for the reason\n  // `postTenantRevalidate` gives: a record that only logs its failures cannot\n  // tell \"every write refreshed\" apart from \"the call never happened\", and\n  // that ambiguity is how an eleven-day propagation outage went unnoticed.\n  console.log(\n    JSON.stringify({\n      tag: 'AGL-3113:dataset-announce',\n      orgId,\n      datasetId,\n      ...result,\n    }),\n  )\n  return result\n}\n\n/**\n * One sentence for a refresh that did not cover every page, or `null` when it\n * did.\n *\n * Beside the call rather than at each surface, so the console cannot word this\n * differently in two places — the same reason `describeRevalidateShortfall`\n * lives beside `revalidateLivePages`. `lead` names the act that succeeded,\n * because only that word differs between surfaces: a record is SAVED, and\n * telling someone who fixed a typo that they published it is a worse error\n * than the staleness the sentence is about.\n */\nexport function describeDatasetAnnounceShortfall(\n  result: DatasetAnnounceResult | null,\n  lead = 'Saved.',\n): string | null {\n  if (!result) return null\n  // `not-rendered`, `no-sites` and `throttled` are deliberately silent: a\n  // dataset no page shows has no stale page, and a throttled drop means one\n  // already went out a moment ago. Saying anything would be alarming and wrong.\n  if (result.reason === 'error' || result.sitesRefused) {\n    return (\n      `${lead} The live pages could not be refreshed just now, so they ` +\n      'may show the previous records for up to an hour.'\n    )\n  }\n  if (result.hostsDropped || result.scanTruncated) {\n    return (\n      `${lead} Some pages that use this dataset are too many to refresh at ` +\n      'once — they update on their own within an hour.'\n    )\n  }\n  return null\n}\n\nexport default announceDatasetRecordChange\n"],"names":["ORG_SCOPE_TOKEN","hostIdsFromScope","repeatKeys","screenRoutePathToUrl","readUsageSources","screenIdsUsingComponentDeep","screenIdsUsingLayoutDeep","isLiveUsageCandidate","DATASET_SCAN_LIMIT","MAX_DATASET_FANOUT_HOSTS","DATASET_ANNOUNCE_WINDOW_MS","lastAnnouncedAt","Map","MAX_THROTTLE_ENTRIES","throttleAllows","key","now","previous","get","undefined","size","clear","set","resetDatasetAnnounceThrottle","nodesRepeatDataset","nodes","keys","some","has","screenIdsRepeatingDataset","sources","screenIds","Set","candidate","screens","add","id","layouts","screenId","components","datasetKeysOf","snapshot","displayName","String","trim","hostIdsSharingDataset","firestore","orgId","visibleTo","Array","isArray","length","hostIds","hostsDropped","includes","named","hosts","collection","where","limit","all","docs","map","doc","slice","Math","max","targetForHost","hostId","hostSnapshot","hostRef","exists","subdomain","paths","candidates","filter","path","Boolean","index","indexOf","cname","truncated","datasetLivePageScope","options","datasetId","targets","reason","resolved","Promise","error","console","target","registeredDropper","registerLivePageDropper","drop","EMPTY_RESULT","sitesRefreshed","pathsRefreshed","sitesRefused","scanTruncated","announceDatasetRecordChange","warn","JSON","stringify","tag","throttleKey","Date","scope","landed","result","log","describeDatasetAnnounceShortfall","lead"],"mappings":"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"}

package/src/lib/server/email-revenue-attribution.d.ts

@@ -1,185 +0,0 @@
-/**
- * @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_ATTRIBUTION_WINDOW_MS } from '@aglyn/shared-util-email';
-/**
- * THE COMMERCE↔EMAIL JOIN — an order, credited to the campaign that led to it.
- *
- * ## Why this is a join
- *
- * Every compared ESP attributes revenue through an integration into a store
- * it does not own: a catalog sync, an on-site tracking snippet, an identity
- * graph, and a window wide enough to absorb what the reconciliation misses.
- * Commerce here is first-party and runs on the merchant's own Stripe Connect
- * account, so the click and the order are two rows in one database keyed the
- * same way. The window is not a fudge factor here — it is the model, and
- * nothing else about the number is estimated.
- *
- * ## Three writes, and what each one is for
- *
- *  - **The touch**, `emailDeliveries/{personKey}.campaignTouches[hostId]`,
- *    written by the delivery webhook on a click. Owned by
- *    `email-delivery-log.ts`, because it lives on the person's document and
- *    the erasure path has to be able to remove it.
- *  - **The attribution record**, `hosts/{hostId}/emailAttributions/{orderId}`,
- *    written here when an order is credited. It is the audit trail — which
- *    campaign, which click, which model, which window — and it is what the
- *    refund path reads to find out which campaign to take the money back off.
- *  - **The rollup**, `campaigns/{campaignId}/reports/revenue`, incremented
- *    here. One document per campaign, so the report reads it whole.
- *
- * ## Why the record is a document and not a field on the order
- *
- * Three reasons, and the first is decisive. `create()` fails when the
- * document already exists, which is exact idempotency for free: webhook
- * delivery is at-least-once, and a redelivered purchase must not be able to
- * credit a campaign twice. Second, not every purchase door writes an order —
- * a booking is a sale with no order document — and a field would have had to
- * either skip those or conjure the document, and conjuring is the
- * phantom-document shape this codebase spent a sweep removing. Third, the
- * order document is read by the console list, the fulfilment path, the
- * supplier outbox and the CSV export, and none of them wants a field about
- * email.
- *
- * ## Never throws
- *
- * Same contract as `upsertHostContact`, which calls it, and for the same
- * reason: the money has already moved and the order already records it, so
- * nothing here may fail a sale. A lost attribution understates a campaign; a
- * thrown one loses a checkout.
- */
-/** The per-host collection of attribution records. */
-export declare const EMAIL_ATTRIBUTIONS_COLLECTION = "emailAttributions";
-/** The single rollup document under a campaign. */
-export declare const CAMPAIGN_REVENUE_REPORT_DOC = "revenue";
-/**
- * The currency an amount is recorded under when the caller does not say.
- *
- * Every checkout door in this repo — cart, buy-now, POS, draft orders,
- * reservations, subscriptions — writes `currency: 'usd'` onto the Stripe line
- * items, and no order document carries a currency field to read back. So this
- * is a statement about what the code charges rather than a guess about the
- * money. The parameter exists so a door that ever charges in something else
- * says so and lands in its own bucket, because the one thing the report may
- * never do is add two currencies together.
- */
-export declare const DEFAULT_ATTRIBUTION_CURRENCY = "usd";
-/** What one attribution record holds. */
-export interface EmailAttributionRecord {
-    campaignId: string;
-    /** When the credited click happened. */
-    clickedAtMs: number;
-    /** When the order was placed. */
-    orderedAtMs: number;
-    /** Minor units credited, gross — the amount the buyer was charged. */
-    amountCents: number;
-    /** Lowercase currency code the amount is in. */
-    currency: string;
-    /** The model this credit was decided under. */
-    model: string;
-    /** The window, in days, it was decided inside. */
-    windowDays: number;
-}
-/**
- * Credits one order to the campaign whose link the buyer last clicked.
- *
- * ## What happens when there is nobody to credit
- *
- * Each case answers `null` and writes NOTHING, which is the whole design:
- *
- *  - **No email on the order.** A guest checkout that never identified its
- *    buyer cannot be joined to anybody's clicks. There is no fallback and
- *    there deliberately is not one — the alternatives are an IP or a device
- *    guess, which is the probabilistic attribution owning the checkout exists
- *    to avoid.
- *  - **A guest with an email but no contact record.** This is ATTRIBUTED
- *    normally. The join keys on the address hash, exactly as the touch and
- *    the suppression list do, so it never asks whether a contact document
- *    exists — which matters, because contact creation is audience-band gated
- *    and a Free org's dropped contact would otherwise silently drop the
- *    revenue with it.
- *  - **No touch, or a touch on another site.** Nobody clicked, so nobody is
- *    credited. The touch map is keyed by host and the send path refuses
- *    cross-site reach; the revenue join agrees with it.
- *  - **A touch outside the window**, in either direction. See
- *    {@link emailTouchIsInWindow} — a click AFTER the order is the receipt,
- *    not the cause.
- *
- * None of these is counted anywhere. A miss costs no write, which is what
- * keeps the ordinary order — placed by somebody who is not on the mailing
- * list at all — at exactly one document read. What it means for the report is
- * stated on the report: the figure counts orders it could join, and is a
- * floor.
- *
- * @returns the record written, or `null` when nothing was credited.
- */
-export declare function attributeOrderToEmail(options: {
-    hostId: string;
-    /** The order, booking or invoice the money came in on. */
-    orderId: string;
-    /** The buyer as the sale recorded them, raw — normalized downstream. */
-    email: unknown;
-    /** Gross minor units the buyer was charged. */
-    amountCents: number;
-    /** Lowercase currency code, when the door knows one. */
-    currency?: string;
-    /** When the order was placed. Defaults to now. */
-    orderedAtMs?: number;
-}, firestore?: any): Promise<EmailAttributionRecord | null>;
-/**
- * Takes back revenue a campaign was credited with, when it is refunded.
- *
- * ## Recorded beside the gross, never subtracted from it
- *
- * `grossCents` is left exactly as it is and the reversal lands in
- * `refundedCents` next to it. This is the shape `contact-refund.ts` chose for
- * `ltvCents`/`refundedCents` and the orders CSV chose for
- * `amountUsd`/`refundedUsd`, and it is chosen a third time here so all three
- * answer "what did this earn, net" identically. Decrementing would make a
- * stored number mean one thing for rollups written before a refund and
- * another after, with nothing on the document to tell them apart — and would
- * put the question "can it go negative" onto storage, where the answer cannot
- * be clamped without destroying evidence. Both stored figures are monotonic
- * counters of money that really moved in one direction; the derived net is
- * clamped at the point of display and nowhere else.
- *
- * ## The currency comes from the RECORD, not from the caller
- *
- * A refund reverses a specific sale, and the bucket it comes out of has to be
- * the bucket it went into. Reading the currency back off the attribution
- * record is what guarantees that, and it is the second thing the record is
- * for.
- *
- * ## Chargebacks come through here too
- *
- * Money reversed is money reversed, whichever door it left by, so a lost
- * dispute reverses the credit the same way a refund does. `kind` exists for
- * the caller's clarity and changes nothing about the arithmetic — the same
- * choice `recordContactRefund` made one field along.
- *
- * @returns whether a reversal was recorded.
- */
-export declare function reverseEmailAttributedRevenue(options: {
-    hostId: string;
-    orderId: string;
-    /** Minor units reversed by THIS attempt, never the order total. */
-    amountCents: number;
-    /** True only for the write that moved the order into `refunded`. */
-    closedTheOrder: boolean;
-    kind?: 'refund' | 'chargeback';
-}, firestore?: any): Promise<boolean>;
-/** The window, re-exported so a caller needs one import for the whole join. */
-export { EMAIL_ATTRIBUTION_WINDOW_MS };