@aglyn/plugins-workflows 1.0.0-beta.179 → 1.0.0-beta.181

package/src/lib/engine/run-org-automations.d.ts

@@ -0,0 +1,75 @@
+/**
+ * @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 FlowEnrollment } from './flow-enrollments';
+/**
+ * THE ORGANIZATION'S AUTOMATIONS, as the engine meets them (AGL-3302).
+ *
+ * Two doors lead here. An event arrives and the site's own actions are
+ * joined by the org automations placed on the site — `runEventActions` asks
+ * {@link findOrgAutomationsForEvent} and runs what it answers beside them. A
+ * person waiting inside an org automation comes due, or the event they were
+ * waiting for arrives, and {@link resumeOrgAutomationEnrollment} continues
+ * them against the organization's document.
+ *
+ * Both run on the event's SITE. The run environment is the site's, so the
+ * sending identity, the suppression lists, the consent group, the email meter
+ * and the run allowance are all the site's — an automation placed on five
+ * sites is five sites running it for themselves.
+ */
+/** The org automations one event runs on one site, and whose they are. */
+export interface PlacedOrgAutomations {
+    orgId: string;
+    docs: FirebaseFirestore.QueryDocumentSnapshot[];
+}
+/** Test seam: forget every remembered organization. */
+export declare function resetOrgAutomationLookupsForTests(): void;
+/**
+ * The org automations this event runs on this site, or null when there are
+ * none — including when the event is not one an org automation can start on,
+ * which is answered before any read.
+ *
+ * One query: the event, switched on, and placed on this site — by the org
+ * token or the site's own — capped at {@link MAX_TRIGGERED_ORG_AUTOMATIONS}.
+ * `enabled` is in the query rather than filtered after it so a switched-off
+ * or deleted automation (deletion switches it off too) can never take one of
+ * the capped places; a PAUSE is per site and cannot be asked of an array in
+ * the same query, so a paused automation is dropped here, after it.
+ *
+ * Served by the composite index on `automations` — `visibleTo` CONTAINS,
+ * `trigger.event`, `enabled` — in `cloud/firebase-firestore.indexes.json`.
+ *
+ * Never throws: an organization that cannot be read runs no org automation,
+ * and the site's own actions run exactly as they would have.
+ */
+export declare function findOrgAutomationsForEvent(hostId: string, event: string): Promise<PlacedOrgAutomations | null>;
+/**
+ * Continues one person waiting inside an org automation, on the site they
+ * were enrolled on — the org twin of the site action's resume, asking the
+ * same questions of the organization's document instead of the site's.
+ *
+ * - The kill switch is `orgs/{orgId}/automations/{id}`: deleted, switched
+ *   off, taken off this site, or paused on this site, and the person stops.
+ * - The site must still belong to that organization, and its plan must
+ *   still carry the actions builder.
+ * - The snapshot runs, never the automation's current steps.
+ * - Counted on this site's action-run meter, never refused by it: the person
+ *   is already inside, and the gate belongs at enrollment.
+ */
+export declare function resumeOrgAutomationEnrollment(enrollment: FlowEnrollment, ref: FirebaseFirestore.DocumentReference, options: {
+    timedOut?: boolean;
+    nowMs: number;
+}): Promise<'ran' | 'waiting' | 'exited' | 'deferred' | 'stopped'>;

package/src/lib/engine/run-org-automations.js

@@ -0,0 +1,154 @@
+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 { checkEntitlement, FLOW_TIMED_OUT_FIELD } from "@aglyn/aglyn/server";
+import { scopeTokensForHost } from "@aglyn/aglyn/app-utils/scope-tokens";
+import { firebaseAdmin, getOrgForHost, resolveOrgIdForHost } from "@aglyn/tenant-data-admin";
+import { FieldValue } from "firebase-admin/firestore";
+import { isOrgAutomationTriggerEvent, MAX_TRIGGERED_ORG_AUTOMATIONS, ORG_AUTOMATIONS_COLLECTION, orgAutomationRunsOnHost, orgAutomationStopReason } from "../model/org-automations.js";
+import { deferFlowEnrollment, endFlowEnrollment } from "./flow-enrollments.js";
+import { executeAction, FLOW_CLAIM_RETRY_MS, makeWorkflowContextLoader, stopFlowEnrollment } from "./run-event-actions.js";
+/**
+ * How long a site's organization is remembered between events.
+ *
+ * The `hostIndex` read is the price of asking the organization at all, and it
+ * repeats on every server event of a busy site and again for each event a
+ * run's own steps raise. Remembered briefly rather than forever: a site that
+ * changes hands is picked up within the window, and the engine refuses to run
+ * a remembered organization's automations for a site whose current owner —
+ * read fresh by the entitlement gate before anything runs — is another.
+ */ const ORG_LOOKUP_TTL_MS = 60000;
+/** Entries kept before the memo starts over; far past one instance's working set. */ const ORG_LOOKUP_MAX_ENTRIES = 1000;
+const orgLookups = new Map();
+/** Test seam: forget every remembered organization. */ export function resetOrgAutomationLookupsForTests() {
+    orgLookups.clear();
+}
+async function orgIdForHost(hostId) {
+    const nowMs = Date.now();
+    const known = orgLookups.get(hostId);
+    if (known && nowMs - known.atMs < ORG_LOOKUP_TTL_MS) return known.orgId;
+    const orgId = await resolveOrgIdForHost(hostId);
+    if (orgLookups.size >= ORG_LOOKUP_MAX_ENTRIES) orgLookups.clear();
+    orgLookups.set(hostId, {
+        orgId,
+        atMs: nowMs
+    });
+    return orgId;
+}
+/**
+ * The org automations this event runs on this site, or null when there are
+ * none — including when the event is not one an org automation can start on,
+ * which is answered before any read.
+ *
+ * One query: the event, switched on, and placed on this site — by the org
+ * token or the site's own — capped at {@link MAX_TRIGGERED_ORG_AUTOMATIONS}.
+ * `enabled` is in the query rather than filtered after it so a switched-off
+ * or deleted automation (deletion switches it off too) can never take one of
+ * the capped places; a PAUSE is per site and cannot be asked of an array in
+ * the same query, so a paused automation is dropped here, after it.
+ *
+ * Served by the composite index on `automations` — `visibleTo` CONTAINS,
+ * `trigger.event`, `enabled` — in `cloud/firebase-firestore.indexes.json`.
+ *
+ * Never throws: an organization that cannot be read runs no org automation,
+ * and the site's own actions run exactly as they would have.
+ */ export async function findOrgAutomationsForEvent(hostId, event) {
+    if (!isOrgAutomationTriggerEvent(event)) return null;
+    try {
+        const orgId = await orgIdForHost(hostId);
+        if (!orgId) return null;
+        const snapshot = await firebaseAdmin.app().firestore().collection('orgs').doc(orgId).collection(ORG_AUTOMATIONS_COLLECTION).where('trigger.event', '==', event).where('enabled', '==', true).where('visibleTo', 'array-contains-any', scopeTokensForHost(hostId)).limit(MAX_TRIGGERED_ORG_AUTOMATIONS).get();
+        const docs = snapshot.docs.filter((doc)=>orgAutomationRunsOnHost(doc.data(), hostId));
+        return docs.length ? {
+            orgId,
+            docs
+        } : null;
+    } catch (error) {
+        console.error('[org automations] lookup failed', hostId, event, error);
+        return null;
+    }
+}
+/**
+ * Continues one person waiting inside an org automation, on the site they
+ * were enrolled on — the org twin of the site action's resume, asking the
+ * same questions of the organization's document instead of the site's.
+ *
+ * - The kill switch is `orgs/{orgId}/automations/{id}`: deleted, switched
+ *   off, taken off this site, or paused on this site, and the person stops.
+ * - The site must still belong to that organization, and its plan must
+ *   still carry the actions builder.
+ * - The snapshot runs, never the automation's current steps.
+ * - Counted on this site's action-run meter, never refused by it: the person
+ *   is already inside, and the gate belongs at enrollment.
+ */ export async function resumeOrgAutomationEnrollment(enrollment, ref, options) {
+    var _enrollment_orgId, _owner_org, _enrollment_payload;
+    const { nowMs } = options;
+    const hostId = enrollment.hostId;
+    const firestore = firebaseAdmin.app().firestore();
+    const hostRef = firestore.collection('hosts').doc(hostId);
+    const stop = (reason)=>stopFlowEnrollment(enrollment, ref, reason);
+    const orgId = String((_enrollment_orgId = enrollment.orgId) != null ? _enrollment_orgId : '');
+    const doc = orgId ? await firestore.collection('orgs').doc(orgId).collection(ORG_AUTOMATIONS_COLLECTION).doc(enrollment.actionId).get().catch(()=>null) : null;
+    const automation = (doc == null ? void 0 : doc.exists) ? doc.data() : null;
+    if (!automation) return await stop('the org automation was deleted');
+    const refusal = orgAutomationStopReason(automation, hostId);
+    if (refusal) return await stop(refusal);
+    const owner = await getOrgForHost(hostId).catch(()=>null);
+    if (!owner || owner.orgId !== orgId) {
+        return await stop('this site is no longer part of the organization that runs the org automation');
+    }
+    if (!checkEntitlement(owner.org, 'actions')) {
+        return await stop('this site’s plan no longer includes automations');
+    }
+    const env = {
+        hostId,
+        hostRef,
+        alerts: [],
+        // Admitted by the `actions` gate above.
+        actionsAllowed: true,
+        webhooksAllowed: checkEntitlement(owner.org, 'webhooks'),
+        crmAllowed: checkEntitlement(owner.org, 'crm'),
+        depth: 0,
+        org: (_owner_org = owner.org) != null ? _owner_org : null,
+        orgId: owner.orgId,
+        loadWorkflowContext: makeWorkflowContextLoader(hostRef)
+    };
+    const payload = _extends({}, (_enrollment_payload = enrollment.payload) != null ? _enrollment_payload : {}, options.timedOut ? {
+        [FLOW_TIMED_OUT_FIELD]: true
+    } : {});
+    const ending = await executeAction(env, enrollment.actionId, automation, enrollment.event, payload, {
+        startIndex: enrollment.nextStepIndex,
+        steps: enrollment.steps,
+        enrollmentRef: ref,
+        orgAutomation: {
+            orgId
+        }
+    });
+    if (ending === 'deferred') {
+        await deferFlowEnrollment(ref, nowMs + FLOW_CLAIM_RETRY_MS, nowMs);
+        return ending;
+    }
+    if (ending !== 'waiting') await endFlowEnrollment(ref);
+    const monthKey = new Date(nowMs).toISOString().slice(0, 7);
+    await hostRef.collection('counters').doc('actionRuns').set({
+        [monthKey]: FieldValue.increment(1)
+    }, {
+        merge: true
+    }).catch(()=>undefined);
+    return ending;
+}
+
+//# sourceMappingURL=run-org-automations.js.map

package/src/lib/engine/run-org-automations.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/workflows/src/lib/engine/run-org-automations.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  checkEntitlement,\n  FLOW_TIMED_OUT_FIELD,\n  type HostActionStep,\n} from '@aglyn/aglyn/server'\nimport { scopeTokensForHost } from '@aglyn/aglyn/app-utils/scope-tokens'\nimport {\n  firebaseAdmin,\n  getOrgForHost,\n  resolveOrgIdForHost,\n} from '@aglyn/tenant-data-admin'\nimport type { HostEventPayload } from '@aglyn/tenant-runtime/host-event-listeners'\nimport { FieldValue } from 'firebase-admin/firestore'\nimport {\n  isOrgAutomationTriggerEvent,\n  MAX_TRIGGERED_ORG_AUTOMATIONS,\n  ORG_AUTOMATIONS_COLLECTION,\n  type OrgAutomation,\n  orgAutomationRunsOnHost,\n  orgAutomationStopReason,\n} from '../model/org-automations'\nimport {\n  deferFlowEnrollment,\n  endFlowEnrollment,\n  type FlowEnrollment,\n} from './flow-enrollments'\nimport {\n  type ActionRunEnv,\n  executeAction,\n  FLOW_CLAIM_RETRY_MS,\n  makeWorkflowContextLoader,\n  stopFlowEnrollment,\n} from './run-event-actions'\n\n/**\n * THE ORGANIZATION'S AUTOMATIONS, as the engine meets them (AGL-3302).\n *\n * Two doors lead here. An event arrives and the site's own actions are\n * joined by the org automations placed on the site — `runEventActions` asks\n * {@link findOrgAutomationsForEvent} and runs what it answers beside them. A\n * person waiting inside an org automation comes due, or the event they were\n * waiting for arrives, and {@link resumeOrgAutomationEnrollment} continues\n * them against the organization's document.\n *\n * Both run on the event's SITE. The run environment is the site's, so the\n * sending identity, the suppression lists, the consent group, the email meter\n * and the run allowance are all the site's — an automation placed on five\n * sites is five sites running it for themselves.\n */\n\n/** The org automations one event runs on one site, and whose they are. */\nexport interface PlacedOrgAutomations {\n  orgId: string\n  docs: FirebaseFirestore.QueryDocumentSnapshot[]\n}\n\n/**\n * How long a site's organization is remembered between events.\n *\n * The `hostIndex` read is the price of asking the organization at all, and it\n * repeats on every server event of a busy site and again for each event a\n * run's own steps raise. Remembered briefly rather than forever: a site that\n * changes hands is picked up within the window, and the engine refuses to run\n * a remembered organization's automations for a site whose current owner —\n * read fresh by the entitlement gate before anything runs — is another.\n */\nconst ORG_LOOKUP_TTL_MS = 60_000\n\n/** Entries kept before the memo starts over; far past one instance's working set. */\nconst ORG_LOOKUP_MAX_ENTRIES = 1_000\n\nconst orgLookups = new Map<string, { orgId: string | null; atMs: number }>()\n\n/** Test seam: forget every remembered organization. */\nexport function resetOrgAutomationLookupsForTests(): void {\n  orgLookups.clear()\n}\n\nasync function orgIdForHost(hostId: string): Promise<string | null> {\n  const nowMs = Date.now()\n  const known = orgLookups.get(hostId)\n  if (known && nowMs - known.atMs < ORG_LOOKUP_TTL_MS) return known.orgId\n  const orgId = await resolveOrgIdForHost(hostId)\n  if (orgLookups.size >= ORG_LOOKUP_MAX_ENTRIES) orgLookups.clear()\n  orgLookups.set(hostId, { orgId, atMs: nowMs })\n  return orgId\n}\n\n/**\n * The org automations this event runs on this site, or null when there are\n * none — including when the event is not one an org automation can start on,\n * which is answered before any read.\n *\n * One query: the event, switched on, and placed on this site — by the org\n * token or the site's own — capped at {@link MAX_TRIGGERED_ORG_AUTOMATIONS}.\n * `enabled` is in the query rather than filtered after it so a switched-off\n * or deleted automation (deletion switches it off too) can never take one of\n * the capped places; a PAUSE is per site and cannot be asked of an array in\n * the same query, so a paused automation is dropped here, after it.\n *\n * Served by the composite index on `automations` — `visibleTo` CONTAINS,\n * `trigger.event`, `enabled` — in `cloud/firebase-firestore.indexes.json`.\n *\n * Never throws: an organization that cannot be read runs no org automation,\n * and the site's own actions run exactly as they would have.\n */\nexport async function findOrgAutomationsForEvent(\n  hostId: string,\n  event: string,\n): Promise<PlacedOrgAutomations | null> {\n  if (!isOrgAutomationTriggerEvent(event)) return null\n  try {\n    const orgId = await orgIdForHost(hostId)\n    if (!orgId) return null\n    const snapshot = await firebaseAdmin\n      .app()\n      .firestore()\n      .collection('orgs')\n      .doc(orgId)\n      .collection(ORG_AUTOMATIONS_COLLECTION)\n      .where('trigger.event', '==', event)\n      .where('enabled', '==', true)\n      .where('visibleTo', 'array-contains-any', scopeTokensForHost(hostId))\n      .limit(MAX_TRIGGERED_ORG_AUTOMATIONS)\n      .get()\n    const docs = snapshot.docs.filter((doc) =>\n      orgAutomationRunsOnHost(doc.data() as OrgAutomation, hostId),\n    )\n    return docs.length ? { orgId, docs } : null\n  } catch (error) {\n    console.error('[org automations] lookup failed', hostId, event, error)\n    return null\n  }\n}\n\n/**\n * Continues one person waiting inside an org automation, on the site they\n * were enrolled on — the org twin of the site action's resume, asking the\n * same questions of the organization's document instead of the site's.\n *\n * - The kill switch is `orgs/{orgId}/automations/{id}`: deleted, switched\n *   off, taken off this site, or paused on this site, and the person stops.\n * - The site must still belong to that organization, and its plan must\n *   still carry the actions builder.\n * - The snapshot runs, never the automation's current steps.\n * - Counted on this site's action-run meter, never refused by it: the person\n *   is already inside, and the gate belongs at enrollment.\n */\nexport async function resumeOrgAutomationEnrollment(\n  enrollment: FlowEnrollment,\n  ref: FirebaseFirestore.DocumentReference,\n  options: { timedOut?: boolean; nowMs: number },\n): Promise<'ran' | 'waiting' | 'exited' | 'deferred' | 'stopped'> {\n  const { nowMs } = options\n  const hostId = enrollment.hostId\n  const firestore = firebaseAdmin.app().firestore()\n  const hostRef = firestore.collection('hosts').doc(hostId)\n  const stop = (reason: string) => stopFlowEnrollment(enrollment, ref, reason)\n\n  const orgId = String(enrollment.orgId ?? '')\n  const doc = orgId\n    ? await firestore\n        .collection('orgs')\n        .doc(orgId)\n        .collection(ORG_AUTOMATIONS_COLLECTION)\n        .doc(enrollment.actionId)\n        .get()\n        .catch(() => null)\n    : null\n  const automation = doc?.exists ? (doc.data() as OrgAutomation) : null\n  if (!automation) return await stop('the org automation was deleted')\n  const refusal = orgAutomationStopReason(automation, hostId)\n  if (refusal) return await stop(refusal)\n\n  const owner = await getOrgForHost(hostId).catch(() => null)\n  if (!owner || owner.orgId !== orgId) {\n    return await stop(\n      'this site is no longer part of the organization that runs the org automation',\n    )\n  }\n  if (!checkEntitlement(owner.org as any, 'actions')) {\n    return await stop('this site’s plan no longer includes automations')\n  }\n\n  const env: ActionRunEnv = {\n    hostId,\n    hostRef,\n    alerts: [],\n    // Admitted by the `actions` gate above.\n    actionsAllowed: true,\n    webhooksAllowed: checkEntitlement(owner.org as any, 'webhooks'),\n    crmAllowed: checkEntitlement(owner.org as any, 'crm'),\n    depth: 0,\n    org: owner.org ?? null,\n    orgId: owner.orgId,\n    loadWorkflowContext: makeWorkflowContextLoader(hostRef),\n  }\n  const payload: HostEventPayload = {\n    ...((enrollment.payload ?? {}) as HostEventPayload),\n    // The timeout BRANCH, as on a site action's resume.\n    ...(options.timedOut ? { [FLOW_TIMED_OUT_FIELD]: true } : {}),\n  }\n  const ending = await executeAction(\n    env,\n    enrollment.actionId,\n    automation,\n    enrollment.event,\n    payload,\n    {\n      startIndex: enrollment.nextStepIndex,\n      steps: enrollment.steps as HostActionStep[],\n      enrollmentRef: ref,\n      orgAutomation: { orgId },\n    },\n  )\n  if (ending === 'deferred') {\n    await deferFlowEnrollment(ref, nowMs + FLOW_CLAIM_RETRY_MS, nowMs)\n    return ending\n  }\n  if (ending !== 'waiting') await endFlowEnrollment(ref)\n  const monthKey = new Date(nowMs).toISOString().slice(0, 7)\n  await hostRef\n    .collection('counters')\n    .doc('actionRuns')\n    .set({ [monthKey]: FieldValue.increment(1) }, { merge: true })\n    .catch(() => undefined)\n  return ending\n}\n"],"names":["checkEntitlement","FLOW_TIMED_OUT_FIELD","scopeTokensForHost","firebaseAdmin","getOrgForHost","resolveOrgIdForHost","FieldValue","isOrgAutomationTriggerEvent","MAX_TRIGGERED_ORG_AUTOMATIONS","ORG_AUTOMATIONS_COLLECTION","orgAutomationRunsOnHost","orgAutomationStopReason","deferFlowEnrollment","endFlowEnrollment","executeAction","FLOW_CLAIM_RETRY_MS","makeWorkflowContextLoader","stopFlowEnrollment","ORG_LOOKUP_TTL_MS","ORG_LOOKUP_MAX_ENTRIES","orgLookups","Map","resetOrgAutomationLookupsForTests","clear","orgIdForHost","hostId","nowMs","Date","now","known","get","atMs","orgId","size","set","findOrgAutomationsForEvent","event","snapshot","app","firestore","collection","doc","where","limit","docs","filter","data","length","error","console","resumeOrgAutomationEnrollment","enrollment","ref","options","owner","hostRef","stop","reason","String","actionId","catch","automation","exists","refusal","org","env","alerts","actionsAllowed","webhooksAllowed","crmAllowed","depth","loadWorkflowContext","payload","timedOut","ending","startIndex","nextStepIndex","steps","enrollmentRef","orgAutomation","monthKey","toISOString","slice","increment","merge","undefined"],"mappings":"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"}

package/src/lib/model/org-automations.d.ts

@@ -0,0 +1,232 @@
+/**
+ * @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 HostActionStep, type HostActionTriggerCondition, type TriggerCombinator } from '@aglyn/aglyn/app-utils/actions';
+import { type ScopeToken } from '@aglyn/aglyn/app-utils/scope-tokens';
+/**
+ * ORG AUTOMATIONS (AGL-3302): one automation the organization writes once and
+ * places on the sites it chooses.
+ *
+ * A site's own actions stay where they are, at `hosts/{hostId}/actions`. They
+ * are not moved here, and the reasons are the four things a site action can
+ * do that an org automation must not:
+ *
+ *  - call the site's functions and variables through a workflow step — the
+ *    working set a computed variable binds to, which is one site's;
+ *  - run the steps only a visitor's page can run (overlays, drawers, class
+ *    toggles, a redirect to a screen), which the `actions` collection also
+ *    holds for element interactions;
+ *  - be fired by `/api/events/dispatch`, which is unauthenticated and ties an
+ *    action id to a site only by its path;
+ *  - wait, with the resume beat reading a missing document as the kill
+ *    switch, so a migration would stop every person already inside a flow.
+ *
+ * An org automation is therefore its own document with a narrower
+ * vocabulary: triggers only the server raises, and steps that mean the same
+ * thing on whichever site they run. Each run executes AS the site the event
+ * happened on — that site's sender, suppressions, consent group, meters and
+ * run allowance — so placing one automation on five sites is five sites each
+ * running it for themselves, never one site acting for the others.
+ *
+ * Pure and client-safe: the console's editor, the server routes and the
+ * engine read the same definitions from here.
+ */
+/** `orgs/{orgId}/automations/{automationId}`. */
+export declare const ORG_AUTOMATIONS_COLLECTION = "automations";
+/**
+ * The two server doors onto the collection, under the plugin's `automations`
+ * API prefix: the organization's (`manage`) and a site's own pause
+ * (`pause`). Named here so the console's caller and the server's registration
+ * read one spelling.
+ */
+export declare const ORG_AUTOMATION_API_ROUTES: {
+    readonly manage: "automations/manage";
+    readonly pause: "automations/pause";
+};
+/**
+ * How many live org automations one organization may hold.
+ *
+ * A flat platform cap in the shape `ACTIONS_MAX_PER_HOST` takes, and smaller,
+ * because the two are different things: a site action is authored per site
+ * and per element, where an org automation is a shared building block placed
+ * on many sites at once. A hundred is far past what an organization writes by
+ * hand and keeps the org hub's list — which reads every live one — a single
+ * bounded window. Soft-deleted documents do not count.
+ */
+export declare const ORG_AUTOMATIONS_MAX = 100;
+/**
+ * How many org automations one event may run on one site: the same fan-out
+ * bound the site's own actions take (`MAX_TRIGGERED_ACTIONS`), counted
+ * separately so the two cannot crowd each other out of the query.
+ */
+export declare const MAX_TRIGGERED_ORG_AUTOMATIONS = 10;
+/**
+ * The run history's target type for a run of an org automation, on the
+ * activity feed of the site it ran on.
+ */
+export declare const ORG_AUTOMATION_RUN_TARGET = "orgAutomation";
+/**
+ * The org activity target an org automation's own lifecycle rows are filed
+ * under: the plugin's namespaced resource (`pluginId:noun`), which the org's
+ * feed reads as "Automation" — core's target list names only core's resources.
+ */
+export declare const ORG_AUTOMATION_ACTIVITY_TARGET = "workflows:automation";
+/**
+ * The events an org automation may start on: every host event the SERVER
+ * raises and a person can be the subject of.
+ *
+ * Listed rather than derived from `HOST_EVENT_TYPES`, deliberately. The engine
+ * queries the organization's automations on every event in this list, so a
+ * new host event must not become an org trigger — and a new read on every
+ * occurrence of it — by being added to the platform's list. Two are left out
+ * on purpose: `pageView` fires on every request to every published page, and
+ * an org query on it would be a read per visitor; `memberSignOut` is raised
+ * by no door today.
+ */
+export declare const ORG_AUTOMATION_TRIGGER_EVENTS: readonly ["formSubmission", "lead", "contactCreated", "contactStageChanged", "booking", "memberSignUp", "memberSignIn", "dealStageChanged", "dealWon", "dealLost", "taskCompleted"];
+export type OrgAutomationTriggerEvent = (typeof ORG_AUTOMATION_TRIGGER_EVENTS)[number];
+/** Whether an org automation may start on this event. */
+export declare function isOrgAutomationTriggerEvent(event: unknown): event is OrgAutomationTriggerEvent;
+/**
+ * The steps an org automation may hold: the server steps that read the same
+ * on every site.
+ *
+ * What is left out, and why:
+ *  - every step the visitor's page runs — overlays, drawers, menus, class
+ *    toggles, custom HTML and JavaScript, analytics, redirects, the site
+ *    alert — because an org trigger is a server event with no page to act on;
+ *  - `runWorkflow`, because a workflow is one site's and calls that site's
+ *    functions and variables;
+ *  - `webhookPost`, because a webhook's address and secret are one site's.
+ *
+ * `customEvent` stays: it fires a custom event ON the site the run is on,
+ * which that site's own actions may listen for — the documented way for an
+ * org automation to hand over to something site-specific.
+ */
+export declare const ORG_AUTOMATION_STEP_TYPES: readonly ["sendEmail", "notifyAdmins", "enrollList", "assignCampaign", "datasetAppend", "updateDataset", "setContactStage", "addContactTag", "assignContactOwner", "createCrmTask", "logCrmActivity", "customEvent", "wait", "waitForEvent", "exitFlow"];
+export type OrgAutomationStepType = (typeof ORG_AUTOMATION_STEP_TYPES)[number];
+/** Whether an org automation may run a step of this type. */
+export declare function isOrgAutomationStepType(type: unknown): type is OrgAutomationStepType;
+/** The org editor's "Do" picker: each allowed step with its label, in order. */
+export declare const ORG_AUTOMATION_STEP_KINDS: ReadonlyArray<{
+    value: OrgAutomationStepType;
+    label: string;
+}>;
+/**
+ * Why an org automation cannot hold this step, or null when it can.
+ *
+ * Shared by the save route, which refuses it, and by the engine, which
+ * refuses to run one a writer stored anyway.
+ */
+export declare function orgAutomationStepRefusal(step: {
+    type?: unknown;
+}): string | null;
+/** The trigger an org automation starts on, as it is stored. */
+export interface OrgAutomationTrigger {
+    event: OrgAutomationTriggerEvent;
+    /** Optional expression over the payload; runs only when truthy. */
+    filter?: string;
+    conditions: HostActionTriggerCondition[] | null;
+    combinator: TriggerCombinator | null;
+}
+/**
+ * The fields an org automation is written with — by the save route, and by
+ * nothing else: the collection is closed to client writes.
+ */
+export interface OrgAutomationFields {
+    name: string;
+    trigger: OrgAutomationTrigger;
+    steps: HostActionStep[];
+    enabled: boolean;
+    /**
+     * The sites it runs on, as scope tokens: `['org']` is every site of the
+     * organization, now and later; `['host:{id}', …]` names up to thirty.
+     */
+    visibleTo: ScopeToken[];
+}
+/** `orgs/{orgId}/automations/{id}`, as it is stored. */
+export interface OrgAutomation extends OrgAutomationFields {
+    /**
+     * The sites that have paused it for themselves — each a site id, never a
+     * scope token. The "host level control": a site's admin or editor adds or
+     * removes their own site here, and only their own.
+     */
+    pausedHostIds: string[];
+    createdBy?: string;
+    updatedBy?: string;
+    /**
+     * Set when it was deleted. Always written — `null` while live — so the
+     * org hub's list can ask for the live ones by equality.
+     */
+    deletedAt: unknown;
+}
+/** A stored org automation with its id, as the console lists it. */
+export type OrgAutomationRow = OrgAutomation & {
+    $id: string;
+};
+/** Longest name an org automation may carry: the actions editor's cap. */
+export declare const ORG_AUTOMATION_NAME_MAX = 60;
+/** What a caller sends to create or replace an org automation. */
+export type OrgAutomationInput = Record<string, unknown>;
+/**
+ * Reads an org automation out of an untrusted request body: the fields it may
+ * hold, in the shape they are stored, or the first reason it cannot be saved.
+ *
+ * The rules are the actions builder's own — `validateHostAction` checks the
+ * name, the trigger's conditions and every step's fields — and on top of them
+ * the two this vocabulary adds: the trigger must be an org trigger and every
+ * step an org step. The placement must be a scope a save can store:
+ * `normalizeVisibleTo` refuses an empty one and one over thirty sites rather
+ * than guessing between sharing wider and taking access away.
+ *
+ * Whether each named site belongs to the organization is the route's to ask,
+ * because it takes a read.
+ */
+export declare function readOrgAutomation(input: unknown): {
+    ok: true;
+    value: OrgAutomationFields;
+} | {
+    ok: false;
+    problem: string;
+};
+/** A stored document's pause list, read defensively. */
+export declare function orgAutomationPausedHostIds(automation: {
+    pausedHostIds?: unknown;
+} | null | undefined): string[];
+/**
+ * Why a stored org automation will not run on this site, or null when it
+ * will — the one answer the engine asks when an event arrives and again when
+ * a person waiting inside the automation is due.
+ *
+ * Deleted, switched off, taken off the site and paused there are the four
+ * ways an organization or a site says "not here", and every one of them
+ * stops the people already waiting on this site as well as the next run: the
+ * kill switch a site action's resume applies, for the same reason.
+ */
+export declare function orgAutomationStopReason(automation: {
+    deletedAt?: unknown;
+    enabled?: unknown;
+    visibleTo?: unknown;
+    pausedHostIds?: unknown;
+} | null | undefined, hostId: string): string | null;
+/** Whether a stored org automation runs on this site. */
+export declare function orgAutomationRunsOnHost(automation: Parameters<typeof orgAutomationStopReason>[0], hostId: string): boolean;
+/**
+ * A pause list after the placement changed: a site the automation no longer
+ * runs on has nothing left to pause, so its entry goes with it, and a site
+ * placed on it again later starts unpaused.
+ */
+export declare function prunePausedHostIds(pausedHostIds: readonly string[], visibleTo: readonly string[]): string[];