@aglyn/tenant-runtime 1.0.0-beta.143

package/src/lib/built-in-page-layout.js

@@ -0,0 +1,107 @@
+/**
+ * @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 Aglyn from "@aglyn/aglyn/server";
+import getScreen from "./get-screen.js";
+import getScreenVersion from "./get-screen-version.js";
+/**
+ * Which shared layout wraps the pages the platform builds rather than the
+ * author does (AGL-2513) — site search today, and the collection article a
+ * site with no entry template falls back to.
+ *
+ * ## Why a setting and not just the home screen's layout
+ *
+ * The home screen's layout was already the implicit answer for the collection
+ * fallback, and it is the right DEFAULT — a site with one layout needs to
+ * configure nothing, and every site has a home page. It is the wrong RULE.
+ * Plenty of sites give the home page a layout of its own: a transparent
+ * header over a hero, no breadcrumb, a fat marketing footer. Search results
+ * inheriting that is how `/search` ends up with a header designed to sit on
+ * top of an image it does not have.
+ *
+ * `host.builtInPageLayoutId` is the escape hatch, and it is a LAYOUT id
+ * rather than a screen id on purpose. What a built-in page needs is the
+ * site's chrome around a body the platform composes; designating a screen
+ * would mean designating a page whose content is ignored — a slot the author
+ * cannot fill and cannot see the shape of.
+ *
+ * Returns `undefined` when neither is available, and every caller treats that
+ * as "render the body with no chrome" rather than as a failure: a search page
+ * without a header is worse than one with, and a search page that 500s
+ * because a layout was deleted is worse than both.
+ */ export const BUILT_IN_PAGE_LAYOUT_FIELD = 'builtInPageLayoutId';
+export async function resolveBuiltInPageLayoutId(options) {
+    var _ref;
+    const { hostId, host } = options;
+    const designated = String((_ref = host == null ? void 0 : host[BUILT_IN_PAGE_LAYOUT_FIELD]) != null ? _ref : '').trim();
+    if (designated) return designated;
+    try {
+        var _ref1;
+        /*
+      The home screen's layout, which is the closest thing a site has to a
+      site-wide default.
+
+      ## Version-first, then the screen
+
+      This used to read `screen.layoutId` alone, on the stated grounds that
+      "screens carry their own `layoutId`". They frequently do not. The
+      binding lives on the VERSION document whenever a layout was chosen while
+      editing — key-present on the version wins over the screen's, which is
+      the precedence `composeScreenNodes` applies on every published page —
+      and a screen whose layout was only ever set that way has no `layoutId`
+      of its own at all.
+
+      So the fallback resolved to `undefined` for those hosts and every
+      built-in page rendered with NO CHROME, which is precisely the defect
+      AGL-2513 existed to fix. It was invisible for a while because nothing
+      linked to a built-in page; AGL-2518 made every byline on every article
+      link to one, and `aglyn.com` turned out to be exactly this shape — a
+      home page bound to "Marketing base" on its version, an unset
+      `builtInPageLayoutId`, and a chrome-less `/search` nobody had reason to
+      visit.
+
+      `null` on the version is a deliberate "no layout" and is honoured as
+      such rather than falling through to the screen — same as composition.
+    */ const screensMap = (_ref1 = host == null ? void 0 : host.screens) != null ? _ref1 : {};
+        const homeEntry = Object.entries(screensMap).find(([, path])=>path === Aglyn.SCREEN_ROOT_PATH);
+        if (!homeEntry) return undefined;
+        const homeRes = await getScreen({
+            hostId,
+            screenId: homeEntry[0]
+        });
+        const screen = homeRes.screen;
+        if (!screen) return undefined;
+        if (screen.versionId) {
+            // Fail-open to the screen's own binding, exactly as composition does:
+            // a version read that throws must not cost the page its chrome.
+            const versionRes = await getScreenVersion({
+                hostId: hostId,
+                screenId: homeEntry[0],
+                versionId: screen.versionId
+            }).catch(()=>null);
+            const version = versionRes == null ? void 0 : versionRes.version;
+            if (version && 'layoutId' in version) {
+                return version.layoutId ? String(version.layoutId) : undefined;
+            }
+        }
+        return screen.layoutId ? String(screen.layoutId) : undefined;
+    } catch (error) {
+        console.error('built-in page layout lookup failed', error);
+        return undefined;
+    }
+}
+export default resolveBuiltInPageLayoutId;
+
+//# sourceMappingURL=built-in-page-layout.js.map

package/src/lib/built-in-page-layout.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/tenant/runtime/src/lib/built-in-page-layout.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 * as Aglyn from '@aglyn/aglyn/server'\nimport getScreen from './get-screen'\nimport getScreenVersion from './get-screen-version'\n\n/**\n * Which shared layout wraps the pages the platform builds rather than the\n * author does (AGL-2513) — site search today, and the collection article a\n * site with no entry template falls back to.\n *\n * ## Why a setting and not just the home screen's layout\n *\n * The home screen's layout was already the implicit answer for the collection\n * fallback, and it is the right DEFAULT — a site with one layout needs to\n * configure nothing, and every site has a home page. It is the wrong RULE.\n * Plenty of sites give the home page a layout of its own: a transparent\n * header over a hero, no breadcrumb, a fat marketing footer. Search results\n * inheriting that is how `/search` ends up with a header designed to sit on\n * top of an image it does not have.\n *\n * `host.builtInPageLayoutId` is the escape hatch, and it is a LAYOUT id\n * rather than a screen id on purpose. What a built-in page needs is the\n * site's chrome around a body the platform composes; designating a screen\n * would mean designating a page whose content is ignored — a slot the author\n * cannot fill and cannot see the shape of.\n *\n * Returns `undefined` when neither is available, and every caller treats that\n * as \"render the body with no chrome\" rather than as a failure: a search page\n * without a header is worse than one with, and a search page that 500s\n * because a layout was deleted is worse than both.\n */\nexport const BUILT_IN_PAGE_LAYOUT_FIELD = 'builtInPageLayoutId' as const\n\nexport async function resolveBuiltInPageLayoutId(options: {\n  hostId: string\n  host: any\n}): Promise<string | undefined> {\n  const { hostId, host } = options\n  const designated = String(host?.[BUILT_IN_PAGE_LAYOUT_FIELD] ?? '').trim()\n  if (designated) return designated\n  try {\n    /*\n      The home screen's layout, which is the closest thing a site has to a\n      site-wide default.\n\n      ## Version-first, then the screen\n\n      This used to read `screen.layoutId` alone, on the stated grounds that\n      \"screens carry their own `layoutId`\". They frequently do not. The\n      binding lives on the VERSION document whenever a layout was chosen while\n      editing — key-present on the version wins over the screen's, which is\n      the precedence `composeScreenNodes` applies on every published page —\n      and a screen whose layout was only ever set that way has no `layoutId`\n      of its own at all.\n\n      So the fallback resolved to `undefined` for those hosts and every\n      built-in page rendered with NO CHROME, which is precisely the defect\n      AGL-2513 existed to fix. It was invisible for a while because nothing\n      linked to a built-in page; AGL-2518 made every byline on every article\n      link to one, and `aglyn.com` turned out to be exactly this shape — a\n      home page bound to \"Marketing base\" on its version, an unset\n      `builtInPageLayoutId`, and a chrome-less `/search` nobody had reason to\n      visit.\n\n      `null` on the version is a deliberate \"no layout\" and is honoured as\n      such rather than falling through to the screen — same as composition.\n    */\n    const screensMap = (host?.screens ?? {}) as Record<string, string>\n    const homeEntry = Object.entries(screensMap).find(\n      ([, path]) => path === Aglyn.SCREEN_ROOT_PATH,\n    )\n    if (!homeEntry) return undefined\n    const homeRes = await getScreen({ hostId, screenId: homeEntry[0] })\n    const screen = homeRes.screen as\n      | { layoutId?: string | null; versionId?: string }\n      | undefined\n    if (!screen) return undefined\n    if (screen.versionId) {\n      // Fail-open to the screen's own binding, exactly as composition does:\n      // a version read that throws must not cost the page its chrome.\n      const versionRes = await getScreenVersion({\n        hostId: hostId as never,\n        screenId: homeEntry[0] as never,\n        versionId: screen.versionId as never,\n      }).catch(() => null)\n      const version = versionRes?.version as\n        | { layoutId?: string | null }\n        | undefined\n      if (version && 'layoutId' in version) {\n        return version.layoutId ? String(version.layoutId) : undefined\n      }\n    }\n    return screen.layoutId ? String(screen.layoutId) : undefined\n  } catch (error) {\n    console.error('built-in page layout lookup failed', error)\n    return undefined\n  }\n}\n\nexport default resolveBuiltInPageLayoutId\n"],"names":["Aglyn","getScreen","getScreenVersion","BUILT_IN_PAGE_LAYOUT_FIELD","resolveBuiltInPageLayoutId","options","hostId","host","designated","String","trim","screensMap","screens","homeEntry","Object","entries","find","path","SCREEN_ROOT_PATH","undefined","homeRes","screenId","screen","versionId","versionRes","catch","version","layoutId","error","console"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED,YAAYA,WAAW,sBAAqB;AAC5C,OAAOC,eAAe,kBAAc;AACpC,OAAOC,sBAAsB,0BAAsB;AAEnD;;;;;;;;;;;;;;;;;;;;;;;;;CAyBC,GACD,OAAO,MAAMC,6BAA6B,sBAA8B;AAExE,OAAO,eAAeC,2BAA2BC,OAGhD;;IACC,MAAM,EAAEC,MAAM,EAAEC,IAAI,EAAE,GAAGF;IACzB,MAAMG,aAAaC,eAAOF,wBAAAA,IAAM,CAACJ,2BAA2B,mBAAI,IAAIO,IAAI;IACxE,IAAIF,YAAY,OAAOA;IACvB,IAAI;;QACF;;;;;;;;;;;;;;;;;;;;;;;;;IAyBA,GACA,MAAMG,sBAAcJ,wBAAAA,KAAMK,OAAO,oBAAI,CAAC;QACtC,MAAMC,YAAYC,OAAOC,OAAO,CAACJ,YAAYK,IAAI,CAC/C,CAAC,GAAGC,KAAK,GAAKA,SAASjB,MAAMkB,gBAAgB;QAE/C,IAAI,CAACL,WAAW,OAAOM;QACvB,MAAMC,UAAU,MAAMnB,UAAU;YAAEK;YAAQe,UAAUR,SAAS,CAAC,EAAE;QAAC;QACjE,MAAMS,SAASF,QAAQE,MAAM;QAG7B,IAAI,CAACA,QAAQ,OAAOH;QACpB,IAAIG,OAAOC,SAAS,EAAE;YACpB,sEAAsE;YACtE,gEAAgE;YAChE,MAAMC,aAAa,MAAMtB,iBAAiB;gBACxCI,QAAQA;gBACRe,UAAUR,SAAS,CAAC,EAAE;gBACtBU,WAAWD,OAAOC,SAAS;YAC7B,GAAGE,KAAK,CAAC,IAAM;YACf,MAAMC,UAAUF,8BAAAA,WAAYE,OAAO;YAGnC,IAAIA,WAAW,cAAcA,SAAS;gBACpC,OAAOA,QAAQC,QAAQ,GAAGlB,OAAOiB,QAAQC,QAAQ,IAAIR;YACvD;QACF;QACA,OAAOG,OAAOK,QAAQ,GAAGlB,OAAOa,OAAOK,QAAQ,IAAIR;IACrD,EAAE,OAAOS,OAAO;QACdC,QAAQD,KAAK,CAAC,sCAAsCA;QACpD,OAAOT;IACT;AACF;AAEA,eAAef,2BAA0B"}

package/src/lib/capture-host-contact.d.ts

@@ -0,0 +1,95 @@
+/**
+ * @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 HostContactCreated, type UpsertHostContactOptions, type UpsertHostContactVerdict } from '@aglyn/tenant-data-admin';
+import type { HostEventPayload } from './host-event-listeners';
+/**
+ * THE contact capture door for a server path (AGL-2605).
+ *
+ * `upsertHostContact` writes the contact and reports, through its
+ * `onCreated` hook, when the write made a NEW person. This wrapper is the
+ * one place that hook is bound to `contactCreated`, and it is the function
+ * every server door calls — the forms route, the membership and newsletter
+ * handlers, the order and booking webhooks. A door that calls
+ * `upsertHostContact` directly still captures the contact and fires nothing,
+ * which is a contact no automation can welcome; `capture-host-contact.spec`
+ * scans for exactly that call.
+ *
+ * ## Why the binding lives here and not in the data library
+ *
+ * What listens for the event — the automation engine among them — imports
+ * the data library for its Firestore handle, its org helpers and its
+ * senders. The data library emitting an event would import the listeners
+ * back, which is a cycle, and the module boundaries (`scope:data` depends on
+ * data and util only) refuse it in any case. So the lower layer reports a
+ * fact and this layer, which already knows how to announce one, announces
+ * it. The alternative — a sink the runtime registers into when its module
+ * happens to be imported — would fire only in a process that had loaded the
+ * runtime, and a Stripe webhook that created a contact in a process that had
+ * not would announce nothing with no error anywhere. The listeners themselves
+ * are registered by a call made at boot (`host-event-listeners.ts`), so every
+ * process has them before its first request.
+ *
+ * Fire-and-forget in the same sense the capture itself is: the hook's
+ * failure is caught inside `upsertHostContact`, so a runner that throws
+ * costs the door nothing, and this function never rejects.
+ *
+ * ## The company, before the announcement (AGL-2613)
+ *
+ * A new person with a work email address is linked to the company at that
+ * domain here, in the same hook, BEFORE `contactCreated` goes out — so an
+ * automation that reads the new contact finds them already filed, rather
+ * than racing a link that lands a moment later. Only when the door did not
+ * name a company itself: the console's drawer and an import row that
+ * carried one have written it into the facet, and the capture must not
+ * second-guess a person's choice with a domain match. The association never
+ * rejects, and its own catch keeps a failed lookup from costing the event.
+ *
+ * ## The owner, on the same terms (AGL-2618)
+ *
+ * Then the org's assignment rules and the site's default owner decide who
+ * follows the new person up — again before `contactCreated`, so an
+ * automation's "create a task for the owner" finds one — and again only
+ * when the door named none: a drawer, an import column or a conversion
+ * that picked an owner has said whose the record is. The pass reads the
+ * form and the tags off the same options the data library was handed,
+ * because the created-report carries the identity and not the routing.
+ * It never rejects either; a record it could not assign is one somebody
+ * assigns by hand, which is what every record was before this existed.
+ */
+export declare function captureHostContact(options: Omit<UpsertHostContactOptions, 'onCreated'>): Promise<UpsertHostContactVerdict>;
+/**
+ * The `contactCreated` payload, as the scalars an event may carry.
+ *
+ * `HostEventPayload` holds strings, numbers and booleans and nothing
+ * nested, because the payload seeds an expression scope and a condition
+ * editor whose operators compare strings. So `campaignIds` rides as one
+ * comma-joined string — `contains` still finds a campaign in it — and is
+ * present only when the capture had campaigns, so `notEmpty` on it reads
+ * as "came in through a campaign form". `name` and `lifecycleStage` are
+ * always present, empty when the door had none, so a condition on either
+ * never sees a missing key: `lifecycleStage == "lead"` is the filter that
+ * picks the form captures out of the sign-ups (AGL-2612).
+ *
+ * `formId` rides the same way `campaignIds` does — present only when the
+ * capture came through a form — because the created-report carries the
+ * person's identity and not the routing, and the form is routing: it is
+ * read off the interaction the door was handed. Present, it is what lets a
+ * condition say `formId` equals this form and no other (AGL-2626); absent,
+ * `notEmpty` on it reads as "came in through a form".
+ */
+export declare function contactCreatedPayload(created: HostContactCreated, formId?: string | null): HostEventPayload;
+export default captureHostContact;

package/src/lib/capture-host-contact.js

@@ -0,0 +1,137 @@
+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 { upsertHostContact } from "@aglyn/tenant-data-admin";
+import { assignOwnerForCapture } from "./assign-contact-owner.js";
+import { associateCompanyByDomain } from "./associate-company-by-domain.js";
+import { emitHostEvent } from "./emit-host-event.js";
+/**
+ * THE contact capture door for a server path (AGL-2605).
+ *
+ * `upsertHostContact` writes the contact and reports, through its
+ * `onCreated` hook, when the write made a NEW person. This wrapper is the
+ * one place that hook is bound to `contactCreated`, and it is the function
+ * every server door calls — the forms route, the membership and newsletter
+ * handlers, the order and booking webhooks. A door that calls
+ * `upsertHostContact` directly still captures the contact and fires nothing,
+ * which is a contact no automation can welcome; `capture-host-contact.spec`
+ * scans for exactly that call.
+ *
+ * ## Why the binding lives here and not in the data library
+ *
+ * What listens for the event — the automation engine among them — imports
+ * the data library for its Firestore handle, its org helpers and its
+ * senders. The data library emitting an event would import the listeners
+ * back, which is a cycle, and the module boundaries (`scope:data` depends on
+ * data and util only) refuse it in any case. So the lower layer reports a
+ * fact and this layer, which already knows how to announce one, announces
+ * it. The alternative — a sink the runtime registers into when its module
+ * happens to be imported — would fire only in a process that had loaded the
+ * runtime, and a Stripe webhook that created a contact in a process that had
+ * not would announce nothing with no error anywhere. The listeners themselves
+ * are registered by a call made at boot (`host-event-listeners.ts`), so every
+ * process has them before its first request.
+ *
+ * Fire-and-forget in the same sense the capture itself is: the hook's
+ * failure is caught inside `upsertHostContact`, so a runner that throws
+ * costs the door nothing, and this function never rejects.
+ *
+ * ## The company, before the announcement (AGL-2613)
+ *
+ * A new person with a work email address is linked to the company at that
+ * domain here, in the same hook, BEFORE `contactCreated` goes out — so an
+ * automation that reads the new contact finds them already filed, rather
+ * than racing a link that lands a moment later. Only when the door did not
+ * name a company itself: the console's drawer and an import row that
+ * carried one have written it into the facet, and the capture must not
+ * second-guess a person's choice with a domain match. The association never
+ * rejects, and its own catch keeps a failed lookup from costing the event.
+ *
+ * ## The owner, on the same terms (AGL-2618)
+ *
+ * Then the org's assignment rules and the site's default owner decide who
+ * follows the new person up — again before `contactCreated`, so an
+ * automation's "create a task for the owner" finds one — and again only
+ * when the door named none: a drawer, an import column or a conversion
+ * that picked an owner has said whose the record is. The pass reads the
+ * form and the tags off the same options the data library was handed,
+ * because the created-report carries the identity and not the routing.
+ * It never rejects either; a record it could not assign is one somebody
+ * assigns by hand, which is what every record was before this existed.
+ */ export async function captureHostContact(options) {
+    return upsertHostContact(_extends({}, options, {
+        onCreated: async (created)=>{
+            var _options_facet, _options_facet1;
+            if (!((_options_facet = options.facet) == null ? void 0 : _options_facet.companyId)) {
+                await associateCompanyByDomain(created).catch((error)=>{
+                    console.error('captureHostContact company association failed', error);
+                });
+            }
+            if (!((_options_facet1 = options.facet) == null ? void 0 : _options_facet1.ownerUid)) {
+                var _options_interaction_formId;
+                await assignOwnerForCapture({
+                    hostId: created.hostId,
+                    contactId: created.contactId,
+                    email: created.email,
+                    source: created.source,
+                    formId: (_options_interaction_formId = options.interaction.formId) != null ? _options_interaction_formId : null,
+                    tags: options.tags
+                }).catch((error)=>{
+                    console.error('captureHostContact owner assignment failed', error);
+                });
+            }
+            await emitHostEvent(created.hostId, 'contactCreated', contactCreatedPayload(created, options.interaction.formId));
+        }
+    }));
+}
+/**
+ * The `contactCreated` payload, as the scalars an event may carry.
+ *
+ * `HostEventPayload` holds strings, numbers and booleans and nothing
+ * nested, because the payload seeds an expression scope and a condition
+ * editor whose operators compare strings. So `campaignIds` rides as one
+ * comma-joined string — `contains` still finds a campaign in it — and is
+ * present only when the capture had campaigns, so `notEmpty` on it reads
+ * as "came in through a campaign form". `name` and `lifecycleStage` are
+ * always present, empty when the door had none, so a condition on either
+ * never sees a missing key: `lifecycleStage == "lead"` is the filter that
+ * picks the form captures out of the sign-ups (AGL-2612).
+ *
+ * `formId` rides the same way `campaignIds` does — present only when the
+ * capture came through a form — because the created-report carries the
+ * person's identity and not the routing, and the form is routing: it is
+ * read off the interaction the door was handed. Present, it is what lets a
+ * condition say `formId` equals this form and no other (AGL-2626); absent,
+ * `notEmpty` on it reads as "came in through a form".
+ */ export function contactCreatedPayload(created, formId) {
+    var _created_name, _created_lifecycleStage;
+    const form = String(formId != null ? formId : '').trim();
+    return _extends({
+        contactId: created.contactId,
+        email: created.email,
+        name: (_created_name = created.name) != null ? _created_name : '',
+        source: created.source,
+        hostId: created.hostId,
+        lifecycleStage: (_created_lifecycleStage = created.lifecycleStage) != null ? _created_lifecycleStage : ''
+    }, created.campaignIds.length ? {
+        campaignIds: created.campaignIds.join(',')
+    } : {}, form ? {
+        formId: form
+    } : {});
+}
+export default captureHostContact;
+
+//# sourceMappingURL=capture-host-contact.js.map

package/src/lib/capture-host-contact.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/tenant/runtime/src/lib/capture-host-contact.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  type HostContactCreated,\n  upsertHostContact,\n  type UpsertHostContactOptions,\n  type UpsertHostContactVerdict,\n} from '@aglyn/tenant-data-admin'\nimport { assignOwnerForCapture } from './assign-contact-owner'\nimport { associateCompanyByDomain } from './associate-company-by-domain'\nimport { emitHostEvent } from './emit-host-event'\nimport type { HostEventPayload } from './host-event-listeners'\n\n/**\n * THE contact capture door for a server path (AGL-2605).\n *\n * `upsertHostContact` writes the contact and reports, through its\n * `onCreated` hook, when the write made a NEW person. This wrapper is the\n * one place that hook is bound to `contactCreated`, and it is the function\n * every server door calls — the forms route, the membership and newsletter\n * handlers, the order and booking webhooks. A door that calls\n * `upsertHostContact` directly still captures the contact and fires nothing,\n * which is a contact no automation can welcome; `capture-host-contact.spec`\n * scans for exactly that call.\n *\n * ## Why the binding lives here and not in the data library\n *\n * What listens for the event — the automation engine among them — imports\n * the data library for its Firestore handle, its org helpers and its\n * senders. The data library emitting an event would import the listeners\n * back, which is a cycle, and the module boundaries (`scope:data` depends on\n * data and util only) refuse it in any case. So the lower layer reports a\n * fact and this layer, which already knows how to announce one, announces\n * it. The alternative — a sink the runtime registers into when its module\n * happens to be imported — would fire only in a process that had loaded the\n * runtime, and a Stripe webhook that created a contact in a process that had\n * not would announce nothing with no error anywhere. The listeners themselves\n * are registered by a call made at boot (`host-event-listeners.ts`), so every\n * process has them before its first request.\n *\n * Fire-and-forget in the same sense the capture itself is: the hook's\n * failure is caught inside `upsertHostContact`, so a runner that throws\n * costs the door nothing, and this function never rejects.\n *\n * ## The company, before the announcement (AGL-2613)\n *\n * A new person with a work email address is linked to the company at that\n * domain here, in the same hook, BEFORE `contactCreated` goes out — so an\n * automation that reads the new contact finds them already filed, rather\n * than racing a link that lands a moment later. Only when the door did not\n * name a company itself: the console's drawer and an import row that\n * carried one have written it into the facet, and the capture must not\n * second-guess a person's choice with a domain match. The association never\n * rejects, and its own catch keeps a failed lookup from costing the event.\n *\n * ## The owner, on the same terms (AGL-2618)\n *\n * Then the org's assignment rules and the site's default owner decide who\n * follows the new person up — again before `contactCreated`, so an\n * automation's \"create a task for the owner\" finds one — and again only\n * when the door named none: a drawer, an import column or a conversion\n * that picked an owner has said whose the record is. The pass reads the\n * form and the tags off the same options the data library was handed,\n * because the created-report carries the identity and not the routing.\n * It never rejects either; a record it could not assign is one somebody\n * assigns by hand, which is what every record was before this existed.\n */\nexport async function captureHostContact(\n  options: Omit<UpsertHostContactOptions, 'onCreated'>,\n): Promise<UpsertHostContactVerdict> {\n  return upsertHostContact({\n    ...options,\n    onCreated: async (created) => {\n      if (!options.facet?.companyId) {\n        await associateCompanyByDomain(created).catch((error: unknown) => {\n          console.error('captureHostContact company association failed', error)\n        })\n      }\n      if (!options.facet?.ownerUid) {\n        await assignOwnerForCapture({\n          hostId: created.hostId,\n          contactId: created.contactId,\n          email: created.email,\n          source: created.source,\n          formId: options.interaction.formId ?? null,\n          tags: options.tags,\n        }).catch((error: unknown) => {\n          console.error('captureHostContact owner assignment failed', error)\n        })\n      }\n      await emitHostEvent(\n        created.hostId,\n        'contactCreated',\n        contactCreatedPayload(created, options.interaction.formId),\n      )\n    },\n  })\n}\n\n/**\n * The `contactCreated` payload, as the scalars an event may carry.\n *\n * `HostEventPayload` holds strings, numbers and booleans and nothing\n * nested, because the payload seeds an expression scope and a condition\n * editor whose operators compare strings. So `campaignIds` rides as one\n * comma-joined string — `contains` still finds a campaign in it — and is\n * present only when the capture had campaigns, so `notEmpty` on it reads\n * as \"came in through a campaign form\". `name` and `lifecycleStage` are\n * always present, empty when the door had none, so a condition on either\n * never sees a missing key: `lifecycleStage == \"lead\"` is the filter that\n * picks the form captures out of the sign-ups (AGL-2612).\n *\n * `formId` rides the same way `campaignIds` does — present only when the\n * capture came through a form — because the created-report carries the\n * person's identity and not the routing, and the form is routing: it is\n * read off the interaction the door was handed. Present, it is what lets a\n * condition say `formId` equals this form and no other (AGL-2626); absent,\n * `notEmpty` on it reads as \"came in through a form\".\n */\nexport function contactCreatedPayload(\n  created: HostContactCreated,\n  formId?: string | null,\n): HostEventPayload {\n  const form = String(formId ?? '').trim()\n  return {\n    contactId: created.contactId,\n    email: created.email,\n    name: created.name ?? '',\n    source: created.source,\n    hostId: created.hostId,\n    lifecycleStage: created.lifecycleStage ?? '',\n    ...(created.campaignIds.length\n      ? { campaignIds: created.campaignIds.join(',') }\n      : {}),\n    ...(form ? { formId: form } : {}),\n  }\n}\n\nexport default captureHostContact\n"],"names":["upsertHostContact","assignOwnerForCapture","associateCompanyByDomain","emitHostEvent","captureHostContact","options","onCreated","created","facet","companyId","catch","error","console","ownerUid","hostId","contactId","email","source","formId","interaction","tags","contactCreatedPayload","form","String","trim","name","lifecycleStage","campaignIds","length","join"],"mappings":";AAAA;;;;;;;;;;;;;;;CAeC,GAED,SAEEA,iBAAiB,QAGZ,2BAA0B;AACjC,SAASC,qBAAqB,QAAQ,4BAAwB;AAC9D,SAASC,wBAAwB,QAAQ,mCAA+B;AACxE,SAASC,aAAa,QAAQ,uBAAmB;AAGjD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAqDC,GACD,OAAO,eAAeC,mBACpBC,OAAoD;IAEpD,OAAOL,kBAAkB,aACpBK;QACHC,WAAW,OAAOC;gBACXF,gBAKAA;YALL,IAAI,GAACA,iBAAAA,QAAQG,KAAK,qBAAbH,eAAeI,SAAS,GAAE;gBAC7B,MAAMP,yBAAyBK,SAASG,KAAK,CAAC,CAACC;oBAC7CC,QAAQD,KAAK,CAAC,iDAAiDA;gBACjE;YACF;YACA,IAAI,GAACN,kBAAAA,QAAQG,KAAK,qBAAbH,gBAAeQ,QAAQ,GAAE;oBAMlBR;gBALV,MAAMJ,sBAAsB;oBAC1Ba,QAAQP,QAAQO,MAAM;oBACtBC,WAAWR,QAAQQ,SAAS;oBAC5BC,OAAOT,QAAQS,KAAK;oBACpBC,QAAQV,QAAQU,MAAM;oBACtBC,MAAM,GAAEb,8BAAAA,QAAQc,WAAW,CAACD,MAAM,YAA1Bb,8BAA8B;oBACtCe,MAAMf,QAAQe,IAAI;gBACpB,GAAGV,KAAK,CAAC,CAACC;oBACRC,QAAQD,KAAK,CAAC,8CAA8CA;gBAC9D;YACF;YACA,MAAMR,cACJI,QAAQO,MAAM,EACd,kBACAO,sBAAsBd,SAASF,QAAQc,WAAW,CAACD,MAAM;QAE7D;;AAEJ;AAEA;;;;;;;;;;;;;;;;;;;CAmBC,GACD,OAAO,SAASG,sBACdd,OAA2B,EAC3BW,MAAsB;QAMdX,eAGUA;IAPlB,MAAMe,OAAOC,OAAOL,iBAAAA,SAAU,IAAIM,IAAI;IACtC,OAAO;QACLT,WAAWR,QAAQQ,SAAS;QAC5BC,OAAOT,QAAQS,KAAK;QACpBS,IAAI,GAAElB,gBAAAA,QAAQkB,IAAI,YAAZlB,gBAAgB;QACtBU,QAAQV,QAAQU,MAAM;QACtBH,QAAQP,QAAQO,MAAM;QACtBY,cAAc,GAAEnB,0BAAAA,QAAQmB,cAAc,YAAtBnB,0BAA0B;OACtCA,QAAQoB,WAAW,CAACC,MAAM,GAC1B;QAAED,aAAapB,QAAQoB,WAAW,CAACE,IAAI,CAAC;IAAK,IAC7C,CAAC,GACDP,OAAO;QAAEJ,QAAQI;IAAK,IAAI,CAAC;AAEnC;AAEA,eAAelB,mBAAkB"}

package/src/lib/collection-fallback-nodes.d.ts

@@ -0,0 +1,90 @@
+/**
+ * @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 Aglyn from '@aglyn/aglyn/server';
+type NodesMap = Record<string, Aglyn.AglynNodeSchema>;
+interface FallbackCollection {
+    slug: string;
+    displayName: string;
+    /** Category taxonomy (AGL-582) for `categoryId` → name resolution. */
+    categories?: Aglyn.CollectionCategory[];
+}
+interface FallbackEntry {
+    title?: string;
+    slug?: string;
+    excerpt?: string;
+    /** Per-entry byline (AGL-686); falls back to the site as author. */
+    authorName?: string;
+    body?: string;
+    coverImage?: string;
+    /** The featured video (AGL-2956); plays in the cover's place. */
+    coverVideo?: string;
+    /** Meta description override (AGL-582); falls back to `excerpt`. */
+    seoDescription?: string;
+    /** Stable taxonomy reference (AGL-582); wins over `category`. */
+    categoryId?: string;
+    /** Legacy free-typed category (AGL-582); read-only fallback. */
+    category?: string;
+    tags?: string[];
+    publishedAt?: {
+        seconds: number;
+    } | null;
+}
+/**
+ * Built-in entry article as canvas nodes (AGL-551): when a collection has
+ * no entry-template screen, `/{collection}/{entry}` renders these through
+ * the normal compose pipeline — site theme, shared layout chrome, and the
+ * markdown-rendering Entry body block — instead of the old unthemed HTML.
+ */
+export declare function buildCollectionEntryFallbackNodes(collection: FallbackCollection, entry: FallbackEntry, 
+/**
+ * The site being composed, so an org-scoped reference is host-qualified the
+ * way every other render surface qualifies one (AGL-1043/AGL-1407). Optional
+ * because a bare org reference still resolves without it; passing it is what
+ * lets an asset restricted to this site resolve at all.
+ */
+hostId?: string): NodesMap;
+/** Pagination state for the built-in list (AGL-620). */
+export interface FallbackListPagination {
+    page: number;
+    perPage: number;
+    totalPages: number;
+}
+/** The routed category for a filtered listing (AGL-1321). */
+export interface FallbackListCategory {
+    slug: string;
+    name: string;
+}
+/**
+ * Built-in entry list as canvas nodes (AGL-551): a heading plus a
+ * Collection entries block whose template (title, date, excerpt, Read
+ * more) the compose pipeline expands over the published entries — the same
+ * block designers drop onto their own list-template screens. With
+ * `pagination` (AGL-620) the block renders one page and prev/next nav links
+ * to `/{slug}/page/{n}`.
+ */
+export declare function buildCollectionListFallbackNodes(collection: FallbackCollection, hasEntries: boolean, pagination?: FallbackListPagination, category?: FallbackListCategory): NodesMap;
+/** Entry vs list fallback selection for the routed content (AGL-551). */
+export declare function buildCollectionFallbackNodes(content: {
+    collection: FallbackCollection;
+    entries: FallbackEntry[];
+    entry: FallbackEntry | null;
+    pagination?: FallbackListPagination | null;
+    category?: FallbackListCategory | null;
+    /** The composing site, for host-qualifying a media reference (AGL-1407). */
+    hostId?: string;
+}): NodesMap;
+export default buildCollectionFallbackNodes;