@aglyn/plugins-workflows 1.0.0-beta.143

package/src/lib/engine/run-event-actions.js

@@ -0,0 +1,1392 @@
+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 { ACTION_MAX_EVENT_DEPTH, ACTION_MAX_STEPS, checkEntitlement, planLabelGrantingFeature, checkQuota, WEBHOOK_URL_PATTERN, evaluateExpression, evaluateStepGuard, evaluateTriggerConditions, FLOW_TIMED_OUT_FIELD, flowEmailTopicId, hostPublicOrigin, isClientActionStep, isCrmActionStep, isFlowSuspendingStep, buildDatasetRecordValues, datasetDisplayName, contactCampaignFieldPath, datasetIntegrityFields, datasetIntegrityUpdate, describeStepOutcome, effectiveDatasetModel, normalizeTriggerConditions, resolveOrgEntitlements, runWorkflow, WORKFLOW_MAX_STEPS } from "@aglyn/aglyn/server";
+import { isDeferrableSendResult, isEmailConfigured, sendEmail, sendFailureReason } from "@aglyn/shared-util-email";
+import { dataStorageRefusal, enrollListMember, firebaseAdmin, flowEmailRefusal, getOrgForHost, hostSendingIdentity, meterHostEmail, notifyHostManagers, consentGroupForSite, orgDataCollectionForHost, orgDataQueryForHost, resolveOrgIdForHost } from "@aglyn/tenant-data-admin";
+import { announceDatasetRecordChange } from "@aglyn/tenant-data-admin/server/dataset-live-pages";
+// The leaf, not the barrel: this library's specs substitute the barrel
+// wholesale, and the lookup must reach the real index logic under them.
+import { findContactByEmail } from "@aglyn/tenant-data-admin/server/contact-email-index";
+import { createHmac } from "crypto";
+import { FieldValue } from "firebase-admin/firestore";
+import { advanceFlowEnrollment, claimFlowEnrollment, deferFlowEnrollment, endFlowEnrollment, enrollInFlow, findFlowEnrollmentsAwaiting, sweepDueFlowEnrollments } from "./flow-enrollments.js";
+import { logCrmEmailActivity, prepareCrmEmailActivity, runCrmActionStep } from "./crm-action-steps.js";
+import { resolveDatasetDoc } from "@aglyn/tenant-runtime/resolve-dataset";
+import { resumeWorkflowEnrollment, runEventWorkflows } from "./run-event-workflows.js";
+import { isWorkflowActionStep, workflowActionStepRefusal, workflowHasActionSteps, workflowStepTypeLabel } from "./workflow-steps.js";
+/** Bounded fan-out per event, mirroring the workflow runner. */ const MAX_TRIGGERED_ACTIONS = 10;
+/**
+ * The run environment for one automation run: the org's plan gates resolved
+ * once, from the org document the caller already read.
+ */ export function automationRunEnv(input) {
+    var _ref, _input_alerts, _ref1, _input_loadWorkflowContext;
+    var _input_owner, _input_owner1;
+    const org = (_ref = (_input_owner = input.owner) == null ? void 0 : _input_owner.org) != null ? _ref : null;
+    return {
+        hostId: input.hostId,
+        hostRef: input.hostRef,
+        alerts: (_input_alerts = input.alerts) != null ? _input_alerts : [],
+        actionsAllowed: checkEntitlement(org, 'actions'),
+        webhooksAllowed: checkEntitlement(org, 'webhooks'),
+        crmAllowed: checkEntitlement(org, 'crm'),
+        depth: input.depth,
+        org,
+        orgId: (_ref1 = (_input_owner1 = input.owner) == null ? void 0 : _input_owner1.orgId) != null ? _ref1 : null,
+        loadWorkflowContext: (_input_loadWorkflowContext = input.loadWorkflowContext) != null ? _input_loadWorkflowContext : makeWorkflowContextLoader(input.hostRef)
+    };
+}
+export function makeWorkflowContextLoader(hostRef) {
+    let workflowContext = null;
+    return async ()=>{
+        if (workflowContext) return workflowContext;
+        const [functionDocs, variableDocs, workflowDocs] = await Promise.all([
+            hostRef.collection('functions').limit(100).get(),
+            hostRef.collection('variables').limit(100).get(),
+            hostRef.collection('workflows').limit(100).get()
+        ]);
+        workflowContext = workflowContextFromDocs(functionDocs.docs, variableDocs.docs, workflowDocs.docs);
+        return workflowContext;
+    };
+}
+/**
+ * The working set a run reads, from documents already in hand — for a door
+ * that read them itself and must not pay for them twice.
+ */ export function workflowContextFromDocs(functionDocs, variableDocs, workflowDocs) {
+    // Double-keyed by doc id AND name (AGL-261): id references are
+    // rename-safe; legacy name references keep resolving.
+    const byName = (docs)=>{
+        const map = {};
+        for (const doc of docs){
+            const data = doc.data();
+            if (data.deletedAt) continue;
+            map[doc.id] = data;
+            if (data == null ? void 0 : data.name) map[data.name] = data;
+        }
+        return map;
+    };
+    // A workflow is carried with its id so a step naming it by its legacy
+    // name still runs it as the automation it is (see `WorkflowContext`).
+    const workflows = {};
+    for (const doc of workflowDocs){
+        const data = doc.data();
+        if (data.deletedAt) continue;
+        const withId = _extends({}, data, {
+            $id: doc.id
+        });
+        workflows[doc.id] = withId;
+        if (data == null ? void 0 : data.name) workflows[data.name] = withId;
+    }
+    return {
+        functions: byName(functionDocs),
+        variables: byName(variableDocs),
+        workflows
+    };
+}
+/**
+ * Whether this dataset may take ANOTHER record, on the plan of the org that
+ * owns the site — the row band and the byte band, in that order. Null when
+ * the append may proceed; a reason string when it may not.
+ *
+ * ## Why an append needs a gate at all
+ *
+ * Every other door onto `datasets/{id}/records` already has one: the console
+ * route re-checks `recordsPerDataset` inside the creating transaction, the
+ * `/v1` record route checks it below its idempotency claim, and the public
+ * form-submission leg checks the rows and the bytes. A workflow step wrote
+ * with no check of either — and it is the door a visitor drives hardest,
+ * because an action fires per event on a published site. A cap enforced at
+ * three of four doors is not a cap; it is the shape of the one that is left.
+ *
+ * ## What it does NOT do
+ *
+ * It refuses the WRITE, never the dataset. A dataset already holding more
+ * rows than the plan includes keeps every row it has and keeps being read —
+ * nothing here deletes, truncates, or hides anything, and nothing may be
+ * added that does. What is refused is the next row, which is the same
+ * boundary the other three doors draw, and the reason a plan change cannot
+ * cost a customer data they already have.
+ *
+ * The update leg of `updateDataset` is deliberately NOT gated: merging fields
+ * into a record that already exists adds no row, so refusing it would refuse
+ * the state of being over rather than the raise.
+ *
+ * ## What it costs
+ *
+ * Nothing on the plans that sell the data store. The row count is read only
+ * when `recordsPerDataset` is FINITE, so an uncapped plan pays nothing; and
+ * `dataStorageRefusal` answers null with no read at all whenever the plan
+ * carries an `extraDataGbMonthlyUsd` rate, which every metered plan does. The
+ * reads are paid on the shapes that can actually refuse.
+ */ /**
+ * Refresh the live pages showing the dataset this step just wrote to
+ * (AGL-3113).
+ *
+ * An automation that appends a row is the same change to a visitor as a form
+ * submission or a console edit: the pages repeating over the dataset go on
+ * serving the rows they were built from. Announced from the step rather than
+ * from the run, so a workflow whose steps write two different datasets
+ * refreshes both — the announce coalesces repeats of the SAME dataset itself,
+ * which is what a run hitting one dataset several times needs.
+ *
+ * Silent without an org: datasets are org-scoped, so a host with no resolvable
+ * org has no dataset to have written to. Best effort, and never thrown: the
+ * row is already stored.
+ */ async function announceDatasetStepWrite(env, datasetId) {
+    if (!env.orgId) return;
+    await announceDatasetRecordChange({
+        firestore: firebaseAdmin.app().firestore(),
+        orgId: env.orgId,
+        datasetId
+    });
+}
+async function datasetAppendRefusal(env, datasetRef) {
+    const limit = resolveOrgEntitlements(env.org).recordsPerDataset;
+    if (Number.isFinite(limit)) {
+        const used = (await datasetRef.collection('records').count().get()).data().count;
+        if (!checkQuota(env.org, 'recordsPerDataset', used).allowed) {
+            return `dataset is full (${limit} records on this plan)`;
+        }
+    }
+    if (!env.orgId) return null;
+    const bytes = await dataStorageRefusal(env.org, firebaseAdmin.app().firestore().collection('orgs').doc(env.orgId));
+    if (!bytes) return null;
+    return `dataset storage is full (${bytes.includedMb} MB on this plan)`;
+}
+/**
+ * Folds one step's verdict into its run's tally, in the run-history phrasing
+ * every automation shares; true when the run stops at this step.
+ */ function tallyStep(tally, type, verdict) {
+    switch(verdict.kind){
+        case 'skipped':
+            return false;
+        case 'done':
+            tally.outcomes.push(describeStepOutcome(type, verdict.detail));
+            return false;
+        case 'failed':
+            tally.errors.push(verdict.error);
+            return false;
+        case 'exited':
+            tally.ending = 'exited';
+            tally.outcomes.push(describeStepOutcome(type));
+            return true;
+        case 'waiting':
+            tally.ending = 'waiting';
+            tally.outcomes.push(describeStepOutcome(type, verdict.detail));
+            return true;
+        case 'halted':
+            tally.errors.push(verdict.error);
+            return true;
+        case 'deferred':
+            tally.ending = 'deferred';
+            return true;
+    }
+}
+/**
+ * Runs ONE Actions step on the server: the executor every automation shares.
+ *
+ * An action's step list runs through it one step at a time, and so does
+ * every Actions step inside a workflow — so the two engines cannot disagree
+ * about what `sendEmail` or `datasetAppend` does, what a step is gated on, or
+ * how its outcome reads in the run history. There is no second copy of any
+ * branch below.
+ *
+ * Client-side steps (AGL-257) are skipped — the tenant page runtime runs
+ * those in the visitor's browser.
+ *
+ * Never throws: a step that throws is a failed step, and the run continues.
+ */ async function runServerStep(env, run, step, context) {
+    const { hostId, hostRef, alerts, depth } = env;
+    const { event, payload, enrollmentRef } = context;
+    /**
+   * The one fact worth carrying into the summary — the dataset's name,
+   * the webhook's status. Set by the branch that knows it.
+   */ let detail;
+    const failed = (error)=>({
+            kind: 'failed',
+            error
+        });
+    try {
+        /*
+     * BRANCHING INSIDE A FLOW: the step's own condition, evaluated against
+     * the same scope the trigger's is. An unmet guard skips this step and
+     * only this step — the run continues, which is what makes "wait three
+     * days, then, only if they have not ordered, send the reminder" a thing
+     * an author can write without a second action.
+     */ if (!evaluateStepGuard(step.when, context.scope)) return {
+            kind: 'skipped'
+        };
+        if (isClientActionStep(step) && step.type !== 'siteAlert') {
+            return {
+                kind: 'skipped'
+            } // Runs in the visitor's page (AGL-257).
+            ;
+        }
+        if (step.type === 'exitFlow') return {
+            kind: 'exited'
+        };
+        if (isFlowSuspendingStep(step)) {
+            // A run inside another automation's run finishes inside it: there is
+            // no enrollment of its own for the person to wait in.
+            if (context.nested) {
+                return {
+                    kind: 'halted',
+                    error: 'a workflow run as a step of another automation cannot wait — ' + 'give it its own trigger instead'
+                };
+            }
+            const suspended = await suspendFlow(env, run, {
+                step,
+                steps: context.steps,
+                nextStepIndex: context.index + 1,
+                event,
+                payload,
+                enrollmentRef
+            });
+            if (suspended.error) return {
+                kind: 'halted',
+                error: suspended.error
+            };
+            return {
+                kind: 'waiting',
+                detail: suspended.detail
+            };
+        }
+        if (step.type === 'siteAlert') {
+            var _step_message, _step_severity;
+            alerts.push({
+                message: String((_step_message = step.message) != null ? _step_message : '').slice(0, 300),
+                severity: (_step_severity = step.severity) != null ? _step_severity : 'info'
+            });
+        } else if (step.type === 'runWorkflow') {
+            var _workflowContext_workflows_, _ref, _ref1;
+            var _step_workflowId, _step_workflowName;
+            const workflowContext = await env.loadWorkflowContext();
+            const workflow = (_workflowContext_workflows_ = workflowContext.workflows[(_ref = (_step_workflowId = step.workflowId) == null ? void 0 : _step_workflowId.trim()) != null ? _ref : '']) != null ? _workflowContext_workflows_ : workflowContext.workflows[(_ref1 = (_step_workflowName = step.workflowName) == null ? void 0 : _step_workflowName.trim()) != null ? _ref1 : ''];
+            if (!workflow) {
+                return failed(`unknown workflow "${step.workflowName || step.workflowId}"`);
+            }
+            if (workflowHasActionSteps(workflow)) {
+                var _ref2, _workflow_$id, _workflow_name;
+                var _step_workflowId1;
+                /*
+         * A workflow with Actions steps is PERFORMED, not evaluated: its
+         * steps run here, inside this run, one level deeper under the same
+         * guard a custom-event chain runs under. It is part of this run, so
+         * it is not metered or recorded as a run of its own.
+         */ if (depth + 1 > ACTION_MAX_EVENT_DEPTH) {
+                    return failed(`workflow "${workflow.name}" is nested too deeply`);
+                }
+                const nested = await executeWorkflow(_extends({}, env, {
+                    depth: depth + 1
+                }), {
+                    kind: 'workflow',
+                    id: (_ref2 = (_workflow_$id = workflow.$id) != null ? _workflow_$id : (_step_workflowId1 = step.workflowId) == null ? void 0 : _step_workflowId1.trim()) != null ? _ref2 : '',
+                    name: (_workflow_name = workflow.name) != null ? _workflow_name : ''
+                }, workflow, event, payload, {
+                    nested: true
+                });
+                if (nested.errors.length) {
+                    return failed(`workflow "${workflow.name}": ${nested.errors.join('; ')}`.slice(0, 300));
+                }
+            } else {
+                const evaluated = runWorkflow(workflow, workflowContext.functions, workflowContext.variables, _extends({
+                    event
+                }, payload), {
+                    workflows: workflowContext.workflows
+                });
+                if (evaluated.ok === false) return failed(evaluated.error);
+            }
+        } else if (step.type === 'customEvent') {
+            const nested = await runEventActions(hostId, step.eventName.trim(), payload, depth + 1);
+            alerts.push(...nested);
+        } else if (step.type === 'webhookPost') {
+            var _ref3;
+            var _step_webhookId, _step_webhookName;
+            if (!env.webhooksAllowed) return failed('webhooks require a Business plan');
+            // Id-first lookup (AGL-261); the name query is the legacy path.
+            const hookDoc = ((_step_webhookId = step.webhookId) == null ? void 0 : _step_webhookId.trim()) ? await hostRef.collection('webhooks').doc(step.webhookId.trim()).get() : (await hostRef.collection('webhooks').where('name', '==', (_ref3 = (_step_webhookName = step.webhookName) == null ? void 0 : _step_webhookName.trim()) != null ? _ref3 : '').limit(1).get()).docs[0];
+            const hook = (hookDoc == null ? void 0 : hookDoc.exists) ? hookDoc.data() : undefined;
+            if (!hook || hookDoc.get('deletedAt') || hook.enabled === false || hook.direction !== 'outbound' || !hook.url || !WEBHOOK_URL_PATTERN.test(hook.url)) {
+                return failed(`unknown webhook "${step.webhookName || step.webhookId}"`);
+            }
+            const body = JSON.stringify({
+                event,
+                payload,
+                sentAt: new Date().toISOString()
+            });
+            const signature = hook.secret ? createHmac('sha256', hook.secret).update(body).digest('hex') : '';
+            // Two quick retries — serverless-friendly; longer retry queues
+            // are a follow-up.
+            let delivered = false;
+            let lastStatus;
+            for(let attempt = 0; attempt < 3 && !delivered; attempt += 1){
+                try {
+                    const response = await fetch(hook.url, {
+                        method: 'POST',
+                        headers: _extends({
+                            'Content-Type': 'application/json'
+                        }, signature && {
+                            'X-Aglyn-Signature': signature
+                        }),
+                        body,
+                        signal: AbortSignal.timeout(5000)
+                    });
+                    lastStatus = response.status;
+                    delivered = response.ok;
+                } catch (unused) {
+                // Retry below.
+                }
+                if (!delivered && attempt < 2) {
+                    await new Promise((resolve)=>setTimeout(resolve, 500 * (attempt + 1)));
+                }
+            }
+            if (!delivered) {
+                return failed(`webhook "${step.webhookName || step.webhookId}" delivery failed`);
+            }
+            // The status the mockup prints — discarded on the line it arrived
+            // until AGL-2171. A 200 and a 204 are both `ok`, and knowing which is
+            // the whole reason anyone opens a run history after a webhook.
+            detail = String(lastStatus != null ? lastStatus : '');
+        } else if (step.type === 'datasetAppend') {
+            // Id-first lookup (AGL-261/556); the name query is the legacy path.
+            const datasetsRef = await orgDataCollectionForHost(hostId, 'datasets');
+            const datasetDoc = await resolveDatasetDoc(datasetsRef, step, hostId);
+            if (!(datasetDoc == null ? void 0 : datasetDoc.exists) || datasetDoc.get('deletedAt')) {
+                return failed(`unknown dataset "${step.datasetName || step.datasetId}"`);
+            }
+            // Restrict to the model's field ids (AGL-556) — covers model-only
+            // datasets whose flat v1 `fields` mirror is absent.
+            const appendDataset = {
+                model: datasetDoc.get('model'),
+                fields: Array.isArray(datasetDoc.get('fields')) ? datasetDoc.get('fields') : []
+            };
+            const values = buildDatasetRecordValues(appendDataset, payload);
+            // Same name precedence `findDatasetByName` resolves in.
+            const appendLabel = (datasetDisplayName({
+                displayName: datasetDoc.get('displayName'),
+                name: datasetDoc.get('name')
+            }) || step.datasetName || '').slice(0, 60);
+            // No event field matched a field of the dataset, so there is nothing
+            // to write. An error rather than a quiet success: a run history that
+            // says `saved to Leads` while nothing saves is how a mismatched field
+            // name goes unnoticed.
+            if (!Object.keys(values).length) {
+                return failed(`no event field matches a field in dataset "${appendLabel || step.datasetId}"`);
+            }
+            const refusal = await datasetAppendRefusal(env, datasetDoc.ref);
+            if (refusal) return failed(refusal);
+            await datasetDoc.ref.collection('records').add(_extends({
+                values
+            }, datasetIntegrityFields(effectiveDatasetModel(appendDataset), values), {
+                createdAt: FieldValue.serverTimestamp()
+            }));
+            await announceDatasetStepWrite(env, datasetDoc.id);
+            // `saved to Leads` beats `saved to dataset` (AGL-2171).
+            detail = appendLabel;
+        } else if (step.type === 'updateDataset') {
+            var _payload_email;
+            // Update-or-append (AGL-257): matches the record whose `email`
+            // field equals the payload's email; appends when nothing matches.
+            const datasetsRef = await orgDataCollectionForHost(hostId, 'datasets');
+            const datasetDoc = await resolveDatasetDoc(datasetsRef, step, hostId);
+            if (!(datasetDoc == null ? void 0 : datasetDoc.exists) || datasetDoc.get('deletedAt')) {
+                return failed(`unknown dataset "${step.datasetName || step.datasetId}"`);
+            }
+            const updateDataset = {
+                model: datasetDoc.get('model'),
+                fields: Array.isArray(datasetDoc.get('fields')) ? datasetDoc.get('fields') : []
+            };
+            const updateModel = effectiveDatasetModel(updateDataset);
+            const values = buildDatasetRecordValues(updateDataset, payload);
+            // Nothing to merge or append — an error, for the reason the append
+            // branch above gives.
+            if (!Object.keys(values).length) {
+                const updateLabel = datasetDisplayName({
+                    displayName: datasetDoc.get('displayName'),
+                    name: datasetDoc.get('name')
+                }) || step.datasetName || step.datasetId;
+                return failed(`no event field matches a field in dataset "${String(updateLabel != null ? updateLabel : '').slice(0, 60)}"`);
+            }
+            const email = String((_payload_email = payload.email) != null ? _payload_email : '').trim();
+            // `records.values` is exempt from indexing, so this lookup is served
+            // only by the `values.email` field override in
+            // cloud/firebase-firestore.indexes.json. Without that override
+            // production refuses the query and neither leg below runs.
+            const existing = email ? await datasetDoc.ref.collection('records').where('values.email', '==', email).limit(1).get() : null;
+            if (existing && !existing.empty) {
+                var _existing_docs__get;
+                const merged = _extends({}, (_existing_docs__get = existing.docs[0].get('values')) != null ? _existing_docs__get : {}, values);
+                await existing.docs[0].ref.set(_extends({
+                    values: merged
+                }, datasetIntegrityUpdate(updateModel, merged, FieldValue.delete()), {
+                    updatedAt: FieldValue.serverTimestamp()
+                }), {
+                    merge: true
+                });
+            } else {
+                // The APPEND leg of update-or-append, and the only one of the two
+                // that adds a row — the merge above rewrites a record that already
+                // counts against the band.
+                const refusal = await datasetAppendRefusal(env, datasetDoc.ref);
+                if (refusal) return failed(refusal);
+                await datasetDoc.ref.collection('records').add(_extends({
+                    values
+                }, datasetIntegrityFields(updateModel, values), {
+                    createdAt: FieldValue.serverTimestamp()
+                }));
+            }
+            // Both legs changed a row, so both make the same pages stale — an edited
+            // record reads no differently from a new one on a page that lists them.
+            await announceDatasetStepWrite(env, datasetDoc.id);
+        } else if (step.type === 'notifyAdmins') {
+            var _step_title;
+            await notifyHostManagers(hostId, _extends({
+                type: 'system.announcement',
+                title: String((_step_title = step.title) != null ? _step_title : '').slice(0, 200)
+            }, step.body ? {
+                body: String(step.body).slice(0, 500)
+            } : {}, {
+                link: `/${hostId}`
+            }));
+        } else if (step.type === 'sendEmail') {
+            var _payload_, _hostPublicOrigin, _step_topicId, _step_subject, _step_body;
+            var _step_toField, _this;
+            const to = String((_payload_ = payload[((_step_toField = step.toField) == null ? void 0 : _step_toField.trim()) || 'email']) != null ? _payload_ : '').trim();
+            if (!isEmailConfigured()) return failed('email is not configured');
+            if (!to || !to.includes('@')) {
+                return failed('no recipient email in the event payload');
+            }
+            // The site's own origin, for the unsubscribe link. Read here rather
+            // than carried on the run env because most action runs send no email
+            // at all, and a document read every workflow pays for is a read on
+            // the hot path for a link nine runs in ten never need.
+            const siteBase = (_hostPublicOrigin = hostPublicOrigin((_this = await hostRef.get().catch(()=>null)) == null ? void 0 : _this.data())) != null ? _hostPublicOrigin : '';
+            /*
+       * MARKETING. The subject and body are merchant-authored and the
+       * recipient comes out of the event payload — which, for the collect
+       * route, is a write triggered by an anonymous visitor. So this is a
+       * site mailing an address on the merchant's say-so, and it owes what
+       * every other such message owes: the unsubscribe header pair and a
+       * visible link, both suppression lists, and a share of the ceiling on
+       * how much one person receives from this site.
+       *
+       * Priority stays transactional. An action run is not resumable — the
+       * event has already happened and there is no beat that comes back for
+       * it — and the rule on `'bulk'` is that only a resumable sweep may
+       * refuse in a way the recipient survives.
+       *
+       * A merchant who wants an internal alert that no suppression can stop
+       * uses the `notifyAdmins` step beside this one: it reaches managers
+       * in the console rather than the shared sending domain, which is the
+       * right instrument for a notification nobody consented to receive.
+       */ /*
+       * A STEP THAT RUNS AFTER A WAIT IS A CAMPAIGN, not a reply.
+       *
+       * The paragraph above is exactly right about an IMMEDIATE step: the
+       * event has already happened, the recipient just did something, and
+       * the message is the response to it. None of that survives a three-day
+       * delay. Everything after a wait goes out on the merchant's schedule,
+       * to somebody who did one thing once — which is `marketing-send.ts`'s
+       * own definition of marketing mail, and it earns the full consent
+       * split and the default stream, exactly as a campaign does.
+       *
+       * An immediate step is not ungated, which it used to be. `to` is read
+       * out of the event payload — an anonymous visitor's write on the
+       * collect route — so nothing here establishes that whoever typed the
+       * address is whoever receives the mail, and a person with a RECORDED
+       * REFUSAL on this site was mailed merchant-authored content because a
+       * third party entered their address in a form. `'immediate'` asks the
+       * narrower question that catches exactly that and cannot refuse a
+       * new visitor their auto-response: see `FlowEmailScope`.
+       *
+       * Refused BEFORE `sendEmail` rather than inside it, because these two
+       * are the merchant's own policy over their own audience, where the
+       * ones the seam asks are platform controls over the shared sending
+       * domain. Both refusals are permanent for this message, so the
+       * enrollment moves on rather than retrying.
+       */ const scope = enrollmentRef ? 'scheduled' : 'immediate';
+            /*
+       * The stream this message belongs to, resolved ONCE and read twice:
+       * the gate below filters on it, and it rides the `marketing` context
+       * so the opt-out link the seam mints names it. Without that the
+       * preference page opens on a list of every stream the site has, and
+       * the recipient has to find the one they were trying to leave.
+       */ const topicId = flowEmailTopicId(step.topicId, scope);
+            const gate = await flowEmailRefusal({
+                hostId,
+                email: to,
+                topicId: (_step_topicId = step.topicId) != null ? _step_topicId : null,
+                org: env.org,
+                scope
+            });
+            if (gate) {
+                return failed(gate !== 'consent-withheld' ? 'the recipient has left this email topic' : // only on a stated refusal, so reporting it as a missing
+                // record would send a merchant looking for a consent field to
+                // fill in that would change nothing.
+                enrollmentRef ? 'the recipient has no marketing consent record on this site' : 'the recipient has declined marketing from this site');
+            }
+            const emailSubject = String((_step_subject = step.subject) != null ? _step_subject : '').slice(0, 200);
+            const emailText = String((_step_body = step.body) != null ? _step_body : '').slice(0, 5000);
+            /*
+       * THE TIMELINE ENTRY (AGL-2615). A message addressed to the contact
+       * the event is about is logged on that contact's timeline as an
+       * email activity — the same row the console's own send logs — so an
+       * automated welcome shows beside the calls a rep made, with its
+       * delivery state. Prepared first because the row's id has to be on
+       * the message for the webhook to find it; written only after the
+       * provider accepted. Behind the suite gate like every other CRM
+       * write an action makes.
+       */ const emailActivity = env.crmAllowed ? await prepareCrmEmailActivity({
+                hostId,
+                org: env.org,
+                orgId: env.orgId
+            }, to, payload) : null;
+            const result = await sendEmail(_extends({
+                to,
+                subject: emailSubject,
+                text: emailText,
+                sendingIdentity: await hostSendingIdentity(hostId)
+            }, emailActivity ? {
+                tags: emailActivity.tags
+            } : {}, {
+                audience: 'tenant',
+                context: enrollmentRef ? 'flow step' : 'event action'
+            }, enrollmentRef ? {
+                priority: 'bulk'
+            } : {}, {
+                // `topicId` is `''` for a step that belongs to no stream, which
+                // every reader of it treats as absent — see `flowEmailTopicId`.
+                marketing: {
+                    hostId,
+                    siteBase,
+                    topicId
+                }
+            }));
+            /*
+       * DEFERRED IS NOT FAILED, and it is not SENT either.
+       *
+       * The platform's hourly ceiling and this person's own frequency window
+       * are both refusals a later beat can pass. Advancing past this step
+       * would turn "not this hour" into an email nobody ever receives, which
+       * is the defect the campaign processor and the cart sweep each name.
+       * So the enrollment is put back with the SAME `nextStepIndex` and the
+       * run ends here.
+       */ if (enrollmentRef && isDeferrableSendResult(result)) {
+                return {
+                    kind: 'deferred'
+                };
+            }
+            // Named rather than lumped into "delivery failed": a suppression and
+            // a frequency ceiling are the controls working, and a merchant
+            // reading the run's alerts has a different thing to do about each.
+            const refusal = sendFailureReason(result);
+            const sendError = refusal ? refusal === 'suppressed' ? 'the recipient is unsubscribed or suppressed' : refusal === 'frequency-capped' ? 'the recipient has already had today’s limit of email ' + 'from this site' : 'email delivery failed' : null;
+            // Cost meter (AGL-1438). A workflow notification is transactional:
+            // counted, never capped. `sent` is false when Resend refused or the
+            // environment is unconfigured, and an email that never left is not a
+            // cost.
+            if (result.sent) {
+                await meterHostEmail(hostId);
+                if (emailActivity) {
+                    await logCrmEmailActivity({
+                        hostId,
+                        org: env.org,
+                        orgId: env.orgId
+                    }, emailActivity, {
+                        subject: emailSubject,
+                        body: emailText,
+                        to
+                    }, run.id);
+                }
+            }
+            if (sendError) return failed(sendError);
+        } else if (step.type === 'enrollList') {
+            var _payload_email1, _ref4;
+            var _step_listId, _step_listName;
+            const orgId = await resolveOrgIdForHost(hostId);
+            const email = String((_payload_email1 = payload.email) != null ? _payload_email1 : '').trim().toLowerCase();
+            if (!orgId || !email || !email.includes('@')) {
+                return failed('no email to enroll');
+            }
+            const listsRef = firebaseAdmin.app().firestore().collection('orgs').doc(orgId).collection('lists');
+            const listDoc = ((_step_listId = step.listId) == null ? void 0 : _step_listId.trim()) ? await listsRef.doc(step.listId.trim()).get() : (await listsRef.where('name', '==', (_ref4 = (_step_listName = step.listName) == null ? void 0 : _step_listName.trim()) != null ? _ref4 : '').limit(1).get()).docs[0];
+            if (!(listDoc == null ? void 0 : listDoc.exists)) {
+                return failed(`unknown list "${step.listName || step.listId}"`);
+            }
+            // `enrollListMember` owns the document id: the commerce newsletter
+            // handler enrolls into the same collection, and an id derived here
+            // would be a second answer to which document describes which person.
+            await enrollListMember({
+                listRef: listDoc.ref,
+                group: await consentGroupForSite(hostId),
+                email,
+                // Which automation enrolled them: `action:<id>` or `workflow:<id>`.
+                source: `${run.kind}:${run.id}`
+            });
+        } else if (step.type === 'assignCampaign') {
+            var _payload_email2, _ref5, _ref6;
+            var _step_campaignId, _step_campaignName;
+            const email = String((_payload_email2 = payload.email) != null ? _payload_email2 : '').trim().toLowerCase();
+            if (!email || !email.includes('@')) {
+                return failed('no contact email to assign');
+            }
+            // Scoped to this host (AGL-1039): a site must not reach a contact
+            // it cannot see, even to tag it onto a campaign. Through the org's
+            // address index (AGL-2633), so an address a merge folded into
+            // another record still names the person who now holds it.
+            const { ref: contactsRef } = await orgDataQueryForHost(hostId, 'contacts');
+            const contact = await findContactByEmail(contactsRef, email, {
+                hostId
+            });
+            if (!contact) return failed(`no contact for ${email}`);
+            /*
+       * THE CAMPAIGN IS RESOLVED TO A DOCUMENT, exactly as `enrollList`
+       * resolves a list one branch above.
+       *
+       * A step may name a campaign by id or by name — the picker writes the
+       * id, an imported automation may carry only the name — and what gets
+       * stored is the id either way. Storing whichever of the two the step
+       * happened to hold would put names and ids in one array, and every
+       * reader of that array resolves ids: a name in it renders as a chip
+       * nobody can click and matches no campaign the console can find.
+       *
+       * An unknown campaign is an ERROR rather than a stored string. The
+       * reference audit already reports a step pointing at a campaign that
+       * does not exist; a run that wrote the dangling name anyway would
+       * make the audit's finding untrue the moment it fired.
+       */ const campaignsRef = hostRef.collection('emailCampaigns');
+            const namedId = (_ref5 = (_step_campaignId = step.campaignId) == null ? void 0 : _step_campaignId.trim()) != null ? _ref5 : '';
+            const campaignDoc = namedId ? await campaignsRef.doc(namedId).get() : (await campaignsRef.where('name', '==', (_ref6 = (_step_campaignName = step.campaignName) == null ? void 0 : _step_campaignName.trim()) != null ? _ref6 : '').limit(1).get()).docs[0];
+            if (!(campaignDoc == null ? void 0 : campaignDoc.exists)) {
+                return failed(`unknown campaign "${step.campaignName || step.campaignId}"`);
+            }
+            /*
+       * INSIDE THIS SITE'S FACET, not at the top of the document.
+       *
+       * A contact is one row shared by every site in the org, and which
+       * campaigns a merchant has filed somebody under is that merchant's
+       * business record on the same footing as their notes and their tags.
+       * Written at the top it would be readable by every other site in an
+       * agency's account.
+       *
+       * `update` with a dotted path, never `set({merge:true})`: a `set`
+       * treats the string as a literal field NAME and would mint a
+       * top-level key with dots in it. The document was just read, so the
+       * update cannot fail for absence.
+       */ const group = await consentGroupForSite(hostId);
+            await contact.ref.update({
+                [contactCampaignFieldPath(group.groupId)]: FieldValue.arrayUnion(campaignDoc.id),
+                updatedAt: FieldValue.serverTimestamp()
+            });
+        } else if (isCrmActionStep(step)) {
+            // The plan gate, the way `webhookPost` takes the `webhooks` one:
+            // refused into the run history with the tier that carries it, so
+            // a Free workspace whose flow names a CRM step reads why the step
+            // did nothing rather than a log that says it ran.
+            if (!env.crmAllowed) {
+                return failed(`CRM steps require the ${planLabelGrantingFeature('crm')} plan`);
+            }
+            // The five CRM steps (AGL-2605) share a resolver and a scope, so
+            // they share a module; see `crm-action-steps.ts`.
+            const outcome = await runCrmActionStep({
+                hostId,
+                org: env.org,
+                orgId: env.orgId
+            }, run.id, step, payload);
+            if (outcome.error) return failed(outcome.error);
+            detail = outcome.detail;
+            /*
+       * A stage set by an automation IS a stage change, and whatever
+       * listens for one must hear it — fanned out here, under the same
+       * depth guard a `customEvent` chain runs under, rather than through
+       * `emitHostEvent`, which starts every chain at depth zero and would
+       * let an automation that sets the stage it listens for run forever.
+       * Workflows take the guard too, now that a workflow can set a stage.
+       */ if (outcome.emit) {
+                const [fromWorkflows, fromActions] = await Promise.all([
+                    runEventWorkflows(hostId, outcome.emit.event, outcome.emit.payload, depth + 1),
+                    runEventActions(hostId, outcome.emit.event, outcome.emit.payload, depth + 1)
+                ]);
+                alerts.push(...fromActions, ...fromWorkflows);
+            }
+        }
+    } catch (error) {
+        return failed(error.message);
+    }
+    return {
+        kind: 'done',
+        detail
+    };
+}
+/**
+ * Executes one action's SERVER steps in order, collecting per-step errors
+ * into the activity summary. Each step runs through {@link runServerStep}.
+ *
+ * A `wait` step ENDS this call and hands the rest of the list to the job
+ * beat: everything after the wait belongs to a run that has not happened yet,
+ * so nothing below the wait may execute in this request.
+ */ async function executeAction(env, actionId, action, event, payload, options = {}) {
+    var _action_name, _options_enrollmentRef, _ref, _options_steps, _options_startIndex, _action_name1;
+    const { hostRef } = env;
+    const run = {
+        kind: 'action',
+        id: actionId,
+        name: (_action_name = action.name) != null ? _action_name : ''
+    };
+    const enrollmentRef = (_options_enrollmentRef = options.enrollmentRef) != null ? _options_enrollmentRef : null;
+    const steps = ((_ref = (_options_steps = options.steps) != null ? _options_steps : action.steps) != null ? _ref : []).slice(0, ACTION_MAX_STEPS);
+    const startIndex = Math.max(0, (_options_startIndex = options.startIndex) != null ? _options_startIndex : 0);
+    /**
+   * What each step actually DID (AGL-2171). Only failures were recorded,
+   * so a run that sent an email, wrote a row and posted a webhook logged
+   * the same eight words as a run that did nothing — and
+   * `/product/workflows` advertises a `What happened` column reading
+   * `Sent email · saved to Leads · webhook 200`.
+   */ const tally = {
+        ending: 'ran',
+        errors: [],
+        outcomes: []
+    };
+    const scope = _extends({
+        event
+    }, payload);
+    for(let index = startIndex; index < steps.length; index += 1){
+        const step = steps[index];
+        const verdict = await runServerStep(env, run, step, {
+            index,
+            steps,
+            event,
+            payload,
+            scope,
+            enrollmentRef
+        });
+        if (tallyStep(tally, step.type, verdict)) break;
+    }
+    const { ending, errors: stepErrors, outcomes } = tally;
+    /*
+   * A DEFERRED run writes no history line and leaves the enrollment where it
+   * was. Nothing happened that a merchant should read as a run: the step is
+   * still ahead of this person, and a row per refused beat would bury the
+   * runs that did something under a log of the ceiling working.
+   */ if (ending === 'deferred') return ending;
+    const summary = stepErrors.length ? `Action ran on ${event} with errors: ${stepErrors.join('; ')}`.slice(0, 300) : ending === 'waiting' ? `Action is waiting, on ${event}` : `Action ran on ${event}`;
+    await hostRef.collection('activity').add({
+        actorId: null,
+        actorEmail: null,
+        // The prose line stays exactly as it was: `activityPrimaryText` and
+        // three other renderers read it, and the run table is not the only
+        // thing this collection feeds.
+        action: summary,
+        // The structured half (AGL-2171) — the two columns the advertised
+        // run-history table could not otherwise fill.
+        result: stepErrors.length ? 'failed' : 'succeeded',
+        trigger: event,
+        summary: (outcomes.length ? outcomes.join(' · ') : 'Ran').slice(0, 300),
+        target: {
+            type: 'workflow',
+            id: actionId,
+            name: (_action_name1 = action.name) != null ? _action_name1 : ''
+        },
+        createdAt: FieldValue.serverTimestamp()
+    }).catch(()=>undefined);
+    return ending;
+}
+/**
+ * Runs a workflow whose steps include Actions steps: function calls and
+ * Actions steps, in order, in one scope.
+ *
+ * - A FUNCTION CALL is evaluated by the platform's pure evaluator,
+ *   `runWorkflow`, one call at a time, so its expressions see the event, the
+ *   site's variables and every result bound before it — exactly the scope a
+ *   function-only workflow gives it. A call that fails ends the run.
+ * - An ACTIONS STEP runs through {@link runServerStep}, the executor actions
+ *   use, and reads the event payload together with every result bound so
+ *   far: a workflow can compute a score and write it to a dataset. Each one
+ *   takes the Actions tier gate (`actions`, Pro and up) on top of its own —
+ *   `webhookPost` on Business, the CRM steps on the CRM suite — and a step
+ *   only the visitor's browser can run is refused.
+ * - `wait` and `waitForEvent` enroll the person and end this call; the rest
+ *   of the list, results included, continues from the beat. `exitFlow` ends
+ *   the run.
+ *
+ * Records nothing and meters nothing: the caller that admitted the run does
+ * both, once.
+ */ export async function executeWorkflow(env, run, workflow, event, payload, options = {}) {
+    var _ref, _options_steps, _options_enrollmentRef, _options_startIndex, _Object_values_at;
+    var _workflow_returnValue;
+    const steps = (_ref = (_options_steps = options.steps) != null ? _options_steps : workflow.steps) != null ? _ref : [];
+    const tally = {
+        ending: 'ran',
+        errors: [],
+        outcomes: []
+    };
+    const results = {};
+    if (steps.length > WORKFLOW_MAX_STEPS) {
+        return _extends({}, tally, {
+            errors: [
+                `Workflows are capped at ${WORKFLOW_MAX_STEPS} steps`
+            ],
+            value: '',
+            results
+        });
+    }
+    const context = await env.loadWorkflowContext();
+    const enrollmentRef = (_options_enrollmentRef = options.enrollmentRef) != null ? _options_enrollmentRef : null;
+    const startIndex = Math.max(0, (_options_startIndex = options.startIndex) != null ? _options_startIndex : 0);
+    /** The payload an Actions step reads: the event's, then every result. */ const stepPayload = ()=>_extends({}, payload, results);
+    for(let index = startIndex; index < steps.length; index += 1){
+        const step = steps[index];
+        if (!isWorkflowActionStep(step)) {
+            var _call_resultName;
+            const call = step;
+            const resultName = ((_call_resultName = call.resultName) == null ? void 0 : _call_resultName.trim()) || `step${index + 1}`;
+            const evaluated = runWorkflow({
+                name: workflow.name,
+                steps: [
+                    _extends({}, call, {
+                        resultName
+                    })
+                ]
+            }, context.functions, context.variables, _extends({
+                event
+            }, stepPayload()), {
+                workflows: context.workflows
+            });
+            if (evaluated.ok === false) {
+                // The evaluator numbers the one step it was handed; the author
+                // numbers it by its place in the workflow.
+                tally.errors.push(evaluated.error.replace(/^Step 1\b/, `Step ${index + 1}`));
+                break;
+            }
+            results[resultName] = evaluated.results[resultName];
+            tally.outcomes.push(`ran ${String(call.functionName || call.functionId || 'a function').trim()}`);
+            continue;
+        }
+        const refusal = workflowActionStepRefusal(step);
+        if (refusal) {
+            tally.errors.push(refusal);
+            continue;
+        }
+        if (!env.actionsAllowed) {
+            tally.errors.push(`“${workflowStepTypeLabel(step.type)}” needs the ` + `${planLabelGrantingFeature('actions')} plan`);
+            continue;
+        }
+        const verdict = await runServerStep(env, run, step, {
+            index,
+            steps,
+            event,
+            payload: stepPayload(),
+            scope: _extends({
+                event
+            }, stepPayload()),
+            enrollmentRef,
+            nested: options.nested
+        });
+        if (tallyStep(tally, step.type, verdict)) break;
+    }
+    /*
+   * The return value the pure evaluator would give: the named scope entry —
+   * a result, a payload field or a variable — when the workflow names one,
+   * and the last result otherwise. Asked of the evaluator itself, with no
+   * steps, so a variable resolves by the evaluator's own rules.
+   */ const returnName = (_workflow_returnValue = workflow.returnValue) == null ? void 0 : _workflow_returnValue.trim();
+    const value = returnName ? (()=>{
+        const named = runWorkflow({
+            name: workflow.name,
+            steps: [],
+            returnValue: returnName
+        }, context.functions, context.variables, _extends({
+            event
+        }, stepPayload()));
+        return named.ok === false ? '' : named.value;
+    })() : (_Object_values_at = Object.values(results).at(-1)) != null ? _Object_values_at : '';
+    return _extends({}, tally, {
+        value,
+        results
+    });
+}
+/**
+ * Suspends the run at a `wait` or `waitForEvent` step.
+ *
+ * One function for both the first suspension and every later one, because the
+ * two differ only in whether a row already exists — and writing "create here,
+ * update there" twice is how the two drift into disagreeing about which
+ * fields a waiting enrollment carries.
+ */ async function suspendFlow(env, run, request) {
+    var _ref, _request_payload;
+    var _request_payload1;
+    const { step } = request;
+    const minutes = step.type === 'wait' ? Number(step.delayMinutes) : step.type === 'waitForEvent' ? Number(step.timeoutMinutes) : 0;
+    if (!Number.isFinite(minutes) || minutes <= 0) {
+        return {
+            error: 'the wait has no duration'
+        };
+    }
+    const nowMs = Date.now();
+    const resumeAtMs = nowMs + minutes * 60000;
+    const awaitingEvent = step.type === 'waitForEvent' ? step.eventName.trim() : null;
+    const detail = step.type === 'waitForEvent' ? `${awaitingEvent} (up to ${minutes}m)` : `${minutes}m`;
+    if (request.enrollmentRef) {
+        await advanceFlowEnrollment(request.enrollmentRef, {
+            nextStepIndex: request.nextStepIndex,
+            resumeAtMs,
+            awaitingEvent,
+            payload: request.payload
+        }, nowMs);
+        return {
+            detail
+        };
+    }
+    const enrolled = await enrollInFlow(_extends({
+        hostId: env.hostId,
+        actionId: run.id
+    }, run.kind === 'workflow' ? {
+        automation: 'workflow'
+    } : {}, {
+        // The SNAPSHOT is the list this run is executing, which on a first run is
+        // the automation's own — so one edited later cannot move this person's
+        // remaining steps out from under them.
+        action: {
+            name: run.name,
+            steps: [
+                ...request.steps
+            ]
+        },
+        email: String((_ref = (_request_payload1 = request.payload) == null ? void 0 : _request_payload1['email']) != null ? _ref : ''),
+        event: request.event,
+        payload: (_request_payload = request.payload) != null ? _request_payload : {},
+        nextStepIndex: request.nextStepIndex,
+        resumeAtMs,
+        awaitingEvent,
+        nowMs
+    }));
+    if (enrolled.enrolled === true) return {
+        detail
+    };
+    /*
+   * Both refusals are stated rather than swallowed, because both are things
+   * an author can act on: a flow that waits needs an address in its trigger
+   * payload, and a person already inside this flow is not put through it
+   * twice concurrently.
+   */ return {
+        error: enrolled.reason === 'no-person' ? 'a flow that waits needs the person’s email in the event payload' : 'this person is already waiting inside this flow'
+    };
+}
+/**
+ * Events too frequent to log a skip for.
+ *
+ * `runEventActions` fires on EVERY page view of every published site. A
+ * Firestore write per visitor per non-matching action is not a run
+ * history, it is an outage — and a page-view condition is one an author
+ * tunes by watching the site, not by reading a log. The events people
+ * actually debug are the server-emitted ones (a form submission, a
+ * booking, a sign-up), and those are low-volume by construction.
+ */ const SKIP_LOG_EXCLUDED_EVENTS = new Set([
+    'pageView'
+]);
+/**
+ * Writes the `Skipped` row (AGL-2171): which condition stopped the run,
+ * so the answer to "why didn't it fire?" is in the same place as every
+ * run that did.
+ *
+ * Never counts against `actionRunsPerMonth` — nothing executed, and
+ * charging for a condition that said no would be its own bug.
+ */ async function recordSkippedRun(hostRef, actionId, action, event) {
+    var _action_name;
+    if (SKIP_LOG_EXCLUDED_EVENTS.has(event)) return;
+    // `normalizeTriggerConditions`, not `trigger.conditions` — a pre-AGL-565
+    // action carries a single `condition` and reading only the array would
+    // give every one of them the nameless fallback.
+    const named = normalizeTriggerConditions(action.trigger).map((condition)=>{
+        var _ref;
+        return String((_ref = condition == null ? void 0 : condition.field) != null ? _ref : '').trim();
+    }).filter(Boolean);
+    const reason = named.length ? `Condition on ${named.slice(0, 3).join(', ')} not met` : 'Trigger condition not met';
+    await hostRef.collection('activity').add({
+        actorId: null,
+        actorEmail: null,
+        action: `Action skipped on ${event}`,
+        result: 'skipped',
+        trigger: event,
+        summary: reason.slice(0, 300),
+        target: {
+            type: 'workflow',
+            id: actionId,
+            name: (_action_name = action.name) != null ? _action_name : ''
+        },
+        createdAt: FieldValue.serverTimestamp()
+    }).catch(()=>undefined);
+}
+/**
+ * Event-triggered action runner (AGL-148): loads enabled actions whose
+ * `trigger.event` matches (built-in, site event, or custom), evaluates
+ * optional filters over the payload, and executes each step list in
+ * order. Never throws into the emitting request. Paid feature: the
+ * `actions` flag gates and `actionRunsPerMonth` meters runs.
+ */ export async function runEventActions(hostId, event, payload = {}, depth = 0) {
+    const alerts = [];
+    if (depth > ACTION_MAX_EVENT_DEPTH) return alerts;
+    /*
+   * A flow waiting for THIS event, for THIS person, resumes here.
+   *
+   * Above the action lookup and outside its try, because the two are
+   * unrelated: an event that matches no action can still be the one a flow
+   * has been waiting a week for, and a site with no actions at all can hold
+   * enrollments from an action that has since been rewritten.
+   */ await wakeFlowsAwaitingEvent(hostId, event, payload).catch(()=>undefined);
+    try {
+        var _ref, _ref1;
+        const firestore = firebaseAdmin.app().firestore();
+        const hostRef = firestore.collection('hosts').doc(hostId);
+        const triggered = await hostRef.collection('actions').where('trigger.event', '==', event).limit(MAX_TRIGGERED_ACTIONS).get();
+        const actions = triggered.docs.filter((doc)=>!doc.get('deletedAt') && doc.get('enabled') !== false);
+        if (!actions.length) return alerts;
+        const monthKey = new Date().toISOString().slice(0, 7);
+        const runCounterRef = hostRef.collection('counters').doc('actionRuns');
+        // Webhook steps take the higher `webhooks` gate (AGL-149); plan gates
+        // ride the owning org's doc (AGL-238).
+        let webhooksAllowed = true;
+        let crmAllowed = true;
+        // Plan-less orgs resolve as free (AGL-247) — gates always run. Held for
+        // the rest of the run so the dataset caps below cost no second read.
+        const owner = await getOrgForHost(hostId);
+        {
+            var _counterSnapshot_get;
+            const org = owner == null ? void 0 : owner.org;
+            if (!checkEntitlement(org, 'actions')) return alerts;
+            webhooksAllowed = checkEntitlement(org, 'webhooks');
+            crmAllowed = checkEntitlement(org, 'crm');
+            const limit = resolveOrgEntitlements(org).actionRunsPerMonth;
+            const counterSnapshot = await runCounterRef.get();
+            const used = Number((_counterSnapshot_get = counterSnapshot.get(monthKey)) != null ? _counterSnapshot_get : 0);
+            if (used + actions.length > limit) return alerts;
+        }
+        const env = {
+            hostId,
+            hostRef,
+            alerts,
+            // Admitted by the `actions` gate above.
+            actionsAllowed: true,
+            webhooksAllowed,
+            crmAllowed,
+            depth,
+            org: (_ref = owner == null ? void 0 : owner.org) != null ? _ref : null,
+            orgId: (_ref1 = owner == null ? void 0 : owner.orgId) != null ? _ref1 : null,
+            loadWorkflowContext: makeWorkflowContextLoader(hostRef)
+        };
+        let executed = 0;
+        for (const doc of actions){
+            var _action_trigger_filter, _action_trigger;
+            const action = doc.data();
+            const filter = (_action_trigger = action.trigger) == null ? void 0 : (_action_trigger_filter = _action_trigger.filter) == null ? void 0 : _action_trigger_filter.trim();
+            if (filter) {
+                try {
+                    if (!evaluateExpression(filter, _extends({
+                        event
+                    }, payload))) continue;
+                } catch (unused) {
+                    continue; // A broken filter never fires.
+                }
+            }
+            // Structured payload conditions (AGL-557; AND/OR chaining AGL-565):
+            // same scope as the filter; unmet conditions skip the action and
+            // never count as a run against the quota.
+            if (!evaluateTriggerConditions(action.trigger, _extends({
+                event
+            }, payload))) {
+                // …but they are RECORDED now (AGL-2171). This was a bare
+                // `continue`, so "why didn't my automation fire?" — the most
+                // common support question about automations — had no answer
+                // anywhere in the product, while `/product/workflows` advertises
+                // an amber `Skipped` row that answers it.
+                await recordSkippedRun(hostRef, doc.id, action, event);
+                continue;
+            }
+            executed += 1;
+            await executeAction(env, doc.id, action, event, payload);
+        }
+        if (executed > 0) {
+            await runCounterRef.set({
+                [monthKey]: FieldValue.increment(executed)
+            }, {
+                merge: true
+            }).catch(()=>undefined);
+        }
+    } catch (error) {
+        console.error('runEventActions failed', hostId, event, error);
+    }
+    return alerts;
+}
+/**
+ * Runs ONE action's server steps (AGL-256): the tenant page runtime
+ * evaluates site-event trigger conditions (scroll thresholds, selectors)
+ * client-side and dispatches the specific action here — re-matching by
+ * event name would wrongly fire sibling actions with different
+ * thresholds. Same gates and metering as the event runner.
+ */ export async function runSingleAction(hostId, actionId, event, payload = {}) {
+    const alerts = [];
+    try {
+        var _ref, _ref1, _ref2;
+        var _action_trigger;
+        const firestore = firebaseAdmin.app().firestore();
+        const hostRef = firestore.collection('hosts').doc(hostId);
+        const doc = await hostRef.collection('actions').doc(actionId).get();
+        if (!doc.exists || doc.get('deletedAt') || doc.get('enabled') === false) {
+            return alerts;
+        }
+        const action = doc.data();
+        // Only site-event actions may be dispatched externally — server
+        // events flow through their own emitters.
+        if (String((_ref = (_action_trigger = action.trigger) == null ? void 0 : _action_trigger.event) != null ? _ref : '') !== String(event)) return alerts;
+        // Structured payload conditions (AGL-557; AND/OR chaining AGL-565):
+        // the single-action dispatch path honors them too, so
+        // client-evaluated triggers can't bypass them.
+        if (!evaluateTriggerConditions(action.trigger, _extends({
+            event
+        }, payload))) {
+            return alerts;
+        }
+        const monthKey = new Date().toISOString().slice(0, 7);
+        const runCounterRef = hostRef.collection('counters').doc('actionRuns');
+        let webhooksAllowed = true;
+        let crmAllowed = true;
+        // Held for the rest of the run, as in `runEventActions` above.
+        const owner = await getOrgForHost(hostId);
+        {
+            var _counterSnapshot_get;
+            const org = owner == null ? void 0 : owner.org;
+            if (!checkEntitlement(org, 'actions')) return alerts;
+            webhooksAllowed = checkEntitlement(org, 'webhooks');
+            crmAllowed = checkEntitlement(org, 'crm');
+            const limit = resolveOrgEntitlements(org).actionRunsPerMonth;
+            const counterSnapshot = await runCounterRef.get();
+            const used = Number((_counterSnapshot_get = counterSnapshot.get(monthKey)) != null ? _counterSnapshot_get : 0);
+            if (used + 1 > limit) return alerts;
+        }
+        const env = {
+            hostId,
+            hostRef,
+            alerts,
+            // Admitted by the `actions` gate above.
+            actionsAllowed: true,
+            webhooksAllowed,
+            crmAllowed,
+            depth: 0,
+            org: (_ref1 = owner == null ? void 0 : owner.org) != null ? _ref1 : null,
+            orgId: (_ref2 = owner == null ? void 0 : owner.orgId) != null ? _ref2 : null,
+            loadWorkflowContext: makeWorkflowContextLoader(hostRef)
+        };
+        await executeAction(env, doc.id, action, event, payload);
+        await runCounterRef.set({
+            [monthKey]: FieldValue.increment(1)
+        }, {
+            merge: true
+        }).catch(()=>undefined);
+    } catch (error) {
+        console.error('runSingleAction failed', hostId, actionId, error);
+    }
+    return alerts;
+}
+/**
+ * Ends an enrollment its automation may no longer run, and says why in the
+ * run history — the automation was deleted or switched off, or the plan that
+ * carried it lapsed. Shared by both kinds of enrollment, so "stopped mid-wait"
+ * reads the same for an action and a workflow.
+ */ export async function stopFlowEnrollment(enrollment, ref, reason) {
+    var _enrollment_actionName;
+    const hostRef = firebaseAdmin.app().firestore().collection('hosts').doc(enrollment.hostId);
+    await endFlowEnrollment(ref);
+    await hostRef.collection('activity').add({
+        actorId: null,
+        actorEmail: null,
+        action: `Flow stopped mid-wait: ${reason}`.slice(0, 300),
+        result: 'skipped',
+        trigger: enrollment.event,
+        summary: reason.slice(0, 300),
+        target: {
+            type: 'workflow',
+            id: enrollment.actionId,
+            name: (_enrollment_actionName = enrollment.actionName) != null ? _enrollment_actionName : ''
+        },
+        createdAt: FieldValue.serverTimestamp()
+    }).catch(()=>undefined);
+    return 'stopped';
+}
+/**
+ * Continues one enrollment from where its wait ended.
+ *
+ * The enrollment carries everything the run needs except the gates: the step
+ * list it entered with, the position inside it, the payload the trigger
+ * produced, and who it is about. What it deliberately does NOT carry is
+ * permission — the `actions` entitlement, the site's lockdown and the
+ * action's own enabled flag are all re-asked here, because a flow that waits
+ * three days is a flow that can outlive the plan, the site and the merchant's
+ * decision to run it.
+ */ export async function resumeFlowEnrollment(enrollment, ref, options) {
+    var _ref, _ref1, _ref2, _enrollment_payload;
+    const nowMs = (_ref = options == null ? void 0 : options.nowMs) != null ? _ref : Date.now();
+    // A workflow's enrollment continues the workflow, against the workflow's
+    // own kill switch and meter; every enrollment without the field is an
+    // action's, which is every one written before a workflow could wait.
+    if (enrollment.automation === 'workflow') {
+        return await resumeWorkflowEnrollment(enrollment, ref, _extends({}, options, {
+            nowMs
+        }));
+    }
+    const hostId = enrollment.hostId;
+    const firestore = firebaseAdmin.app().firestore();
+    const hostRef = firestore.collection('hosts').doc(hostId);
+    const stop = (reason)=>stopFlowEnrollment(enrollment, ref, reason);
+    const doc = await hostRef.collection('actions').doc(enrollment.actionId).get().catch(()=>null);
+    /*
+   * A KILL SWITCH HAS TO KILL, including for the people already inside.
+   *
+   * Editing a flow leaves an enrollment alone — it runs the snapshot it
+   * entered with. DELETING or DISABLING one does not: "off" that keeps mailing
+   * the queue for the next three days is not off, and it is the control a
+   * merchant reaches for when a flow is doing something wrong. So the two
+   * cases are deliberately different, and this is the one that stops.
+   */ if (!(doc == null ? void 0 : doc.exists) || doc.get('deletedAt') || doc.get('enabled') === false) {
+        return await stop('the automation was turned off or deleted');
+    }
+    const action = doc.data();
+    const owner = await getOrgForHost(hostId).catch(()=>null);
+    if (!checkEntitlement(owner == null ? void 0 : 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 == null ? void 0 : owner.org, 'webhooks'),
+        crmAllowed: checkEntitlement(owner == null ? void 0 : owner.org, 'crm'),
+        depth: 0,
+        org: (_ref1 = owner == null ? void 0 : owner.org) != null ? _ref1 : null,
+        orgId: (_ref2 = owner == null ? void 0 : owner.orgId) != null ? _ref2 : null,
+        loadWorkflowContext: makeWorkflowContextLoader(hostRef)
+    };
+    const payload = _extends({}, (_enrollment_payload = enrollment.payload) != null ? _enrollment_payload : {}, (options == null ? void 0 : options.timedOut) ? {
+        [FLOW_TIMED_OUT_FIELD]: true
+    } : {});
+    const ending = await executeAction(env, enrollment.actionId, action, enrollment.event, payload, {
+        startIndex: enrollment.nextStepIndex,
+        // An action's enrollment holds only Actions steps: its snapshot is the
+        // action's own list.
+        steps: enrollment.steps,
+        enrollmentRef: ref
+    });
+    if (ending === 'deferred') {
+        /*
+     * Pushed a beat down the queue rather than retried immediately: the two
+     * refusals that reach here are an hour-long platform ceiling and a
+     * day-long per-person window, so retrying in sixty seconds would spend a
+     * read to be told the same thing sixty more times.
+     */ await deferFlowEnrollment(ref, nowMs + FLOW_CLAIM_RETRY_MS, nowMs);
+        return ending;
+    }
+    if (ending !== 'waiting') await endFlowEnrollment(ref);
+    /*
+   * COUNTED, NEVER REFUSED.
+   *
+   * A resume is real work and belongs on the run meter, so the usage card and
+   * the COGS rollup see it. It is not GATED on `actionRunsPerMonth` the way a
+   * new run is, because the person is already inside the flow: refusing here
+   * would abandon somebody half-way through a sequence, which is a capacity
+   * limit enforced against a person rather than against the decision that
+   * added them. The gate belongs at enrollment, and that is where it is.
+   */ 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;
+}
+/** How long a deferred enrollment waits before the next attempt. */ export const FLOW_CLAIM_RETRY_MS = 15 * 60000;
+/**
+ * The job beat's entry point: resume every flow whose wait has ended.
+ *
+ * Thin on purpose. The scheduling contract — due-ness, the transactional
+ * claim, the scan budget, the lockdown skip — is `sweepDueFlowEnrollments`,
+ * and the work is `resumeFlowEnrollment`; this is the wire between them, so
+ * neither has to import the other's dependencies to be tested.
+ */ export async function runDueFlowEnrollments(gate, options) {
+    return await sweepDueFlowEnrollments(gate, _extends({}, (options == null ? void 0 : options.nowMs) !== undefined ? {
+        nowMs: options.nowMs
+    } : {}, (options == null ? void 0 : options.scanBudget) !== undefined ? {
+        scanBudget: options.scanBudget
+    } : {}, (options == null ? void 0 : options.cursor) ? {
+        cursor: options.cursor
+    } : {}, {
+        resume: async (enrollment, ref)=>{
+            await resumeFlowEnrollment(enrollment, ref, _extends({
+                // Reaching the sweep IS the timeout for a `waitForEvent`: the event
+                // it was watching for never arrived before `resumeAtMs`. A plain
+                // `wait` has no timeout to report, so the flag rides the presence of
+                // an awaited event rather than the fact of being swept.
+                timedOut: Boolean(enrollment.awaitingEvent)
+            }, (options == null ? void 0 : options.nowMs) !== undefined ? {
+                nowMs: options.nowMs
+            } : {}));
+        }
+    }));
+}
+/**
+ * Wakes the flows this person's event was being waited for.
+ *
+ * NOT A POLL. Nothing here scans the enrolled population asking whose turn it
+ * is — the event arrives already naming a person, and the lookup is three
+ * equality filters against that person's key. A site with ten thousand people
+ * waiting costs the same as one with ten.
+ *
+ * The COST GUARD is the caller's, and it is why this takes an email rather
+ * than reading one: `runEventActions` fires on every page view of every
+ * published site, so it asks only for events that name a person. A page view
+ * does not, and pays nothing.
+ */ async function wakeFlowsAwaitingEvent(hostId, event, payload) {
+    var _ref;
+    const email = String((_ref = payload == null ? void 0 : payload['email']) != null ? _ref : '').trim();
+    if (!email || !email.includes('@')) return;
+    const waiting = await findFlowEnrollmentsAwaiting({
+        hostId,
+        event,
+        email
+    });
+    for (const doc of waiting){
+        const claimed = await claimFlowEnrollment(doc.ref).catch(()=>null);
+        if (!claimed) continue;
+        try {
+            var _claimed_payload;
+            /*
+       * The awaited event ARRIVED, so this is not the timeout branch — and
+       * the arriving payload joins the carried one, so a step after the wait
+       * can read the order total the flow was waiting for.
+       */ await resumeFlowEnrollment(_extends({}, claimed, {
+                payload: _extends({}, (_claimed_payload = claimed.payload) != null ? _claimed_payload : {}, payload != null ? payload : {})
+            }), doc.ref, {
+                timedOut: false
+            });
+        } catch (error) {
+            console.error('[flow] event wake failed', doc.ref.path, error);
+            await deferFlowEnrollment(doc.ref, Date.now() + FLOW_CLAIM_RETRY_MS);
+        }
+    }
+}
+export default runEventActions;
+
+//# sourceMappingURL=run-event-actions.js.map