@aglyn/aglyn 1.0.0-beta.143

package/src/lib/app-utils/actions.d.ts

@@ -0,0 +1,717 @@
+/**
+ * @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 ContactLifecycleStage, type CrmActivityKind, type CrmTaskKind } from './crm-kinds';
+/**
+ * Actions builder (AGL-148): HubSpot-style event → action automation on
+ * top of the AGL-128 event triggers. An action listens for a host event
+ * (built-in or a custom name fired by another action), optionally filters
+ * on the payload, and runs an ordered step list. Pure types + validation
+ * here; the executor lives server-side where the I/O is (tenant utils).
+ */
+/**
+ * Client-side site events (AGL-256) the tenant page runtime emits:
+ * element interactions, scroll behavior, dwell time, and exit intent.
+ * Trigger config (selector/threshold/path) rides the action's trigger.
+ */
+export declare const SITE_EVENT_TYPES: readonly ["scrollDepth", "scrollToElement", "elementClick", "elementVisible", "elementHoverEnter", "elementHoverLeave", "exitIntent", "timeOnPage", "pageVisit"];
+/** Site events that watch a specific element and need a selector. */
+export declare const ELEMENT_SCOPED_SITE_EVENTS: readonly ["scrollToElement", "elementClick", "elementVisible", "elementHoverEnter", "elementHoverLeave"];
+export type SiteEventType = (typeof SITE_EVENT_TYPES)[number];
+export declare function isSiteEventType(event: string): event is SiteEventType;
+/** Structured condition operators (AGL-557). */
+export declare const TRIGGER_CONDITION_OPS: readonly ["equals", "contains", "notEmpty"];
+export type TriggerConditionOp = (typeof TRIGGER_CONDITION_OPS)[number];
+/**
+ * Structured per-action condition over the event payload (AGL-557): the
+ * no-code sibling of the free-text `filter` expression, e.g. "only run
+ * when the `subscribe` field is not empty". Evaluated against the same
+ * scope as the filter (event name + payload fields); the action is
+ * skipped when unmet.
+ */
+export interface HostActionTriggerCondition {
+    /** Payload field the condition reads (a submitted form field name). */
+    field: string;
+    op: TriggerConditionOp;
+    /** Comparison value for `equals`/`contains`; unused by `notEmpty`. */
+    value?: string;
+}
+/**
+ * Evaluates a structured trigger condition (AGL-557). String-coerces the
+ * payload value; `equals`/`contains` compare trimmed + case-insensitive
+ * so checkbox values like "Yes" match an author-typed "yes". A missing
+ * field never matches (and is "empty" for `notEmpty`); an absent or
+ * field-less condition always passes, mirroring the filter's default.
+ */
+export declare function evaluateTriggerCondition(condition: HostActionTriggerCondition | undefined | null, payload: Record<string, unknown>): boolean;
+/** How chained trigger conditions combine (AGL-565). */
+export declare const TRIGGER_COMBINATORS: readonly ["and", "or"];
+export type TriggerCombinator = (typeof TRIGGER_COMBINATORS)[number];
+/** Cap on chained conditions per trigger (AGL-565). */
+export declare const ACTION_MAX_CONDITIONS = 5;
+/**
+ * Normalizes a trigger's condition clauses to a list (AGL-565): the
+ * `conditions` array wins when present; a legacy single `condition`
+ * (AGL-557) becomes a one-element list. Read-time only — persisted docs
+ * are never migrated, so pre-565 single-condition docs keep working
+ * unchanged.
+ */
+export declare function normalizeTriggerConditions(trigger: Pick<HostActionTrigger, 'condition' | 'conditions'> | undefined | null): HostActionTriggerCondition[];
+/**
+ * Evaluates a trigger's condition list with its combinator (AGL-565):
+ * `and` (the default) requires every condition to pass, `or` any one.
+ * Per-condition semantics are unchanged from AGL-557
+ * (`evaluateTriggerCondition`), and an empty list always passes — which
+ * covers every pre-565 doc without conditions.
+ */
+export declare function evaluateTriggerConditions(trigger: Pick<HostActionTrigger, 'condition' | 'conditions' | 'combinator'> | undefined | null, payload: Record<string, unknown>): boolean;
+export interface HostActionTrigger {
+    /**
+     * Event the action enrolls on: a HOST_EVENT_TYPE (server-emitted), a
+     * SITE_EVENT_TYPE (client-emitted, AGL-256), or a custom name fired by
+     * another action's `customEvent` step.
+     */
+    event: string;
+    /** Optional expression over the payload; runs only when truthy. */
+    filter?: string;
+    /** Optional structured payload condition (AGL-557); null clears it. */
+    condition?: HostActionTriggerCondition | null;
+    /**
+     * Chained payload conditions (AGL-565), combined with `combinator`.
+     * When present this list wins over the legacy single `condition`
+     * (see `normalizeTriggerConditions`); null clears it.
+     */
+    conditions?: HostActionTriggerCondition[] | null;
+    /** How the chained conditions combine (AGL-565); default `and`. */
+    combinator?: TriggerCombinator | null;
+    /** CSS selector for element-scoped site events (click/visible/scroll-to). */
+    selector?: string;
+    /** Percent 0-100 (scrollDepth) or seconds (timeOnPage). */
+    threshold?: number;
+    /** Path pattern the site event listens on (overlay glob rules); empty = all. */
+    pathPattern?: string;
+    /**
+     * Fire at most once per visitor (AGL-266, localStorage-keyed) instead
+     * of once per pageview. Site events only.
+     */
+    oncePerVisitor?: boolean;
+    /**
+     * Fire at most once per browser session (AGL-274,
+     * sessionStorage-keyed). Site events only.
+     */
+    oncePerSession?: boolean;
+    /**
+     * Minimum minutes between fires for the same visitor (AGL-274,
+     * localStorage timestamp). Site events only; ignored when
+     * `oncePerVisitor` is set.
+     */
+    cooldownMinutes?: number;
+    /**
+     * Fire on EVERY occurrence instead of once per pageview (AGL-562) —
+     * required for repeatable UI choreography (menu toggles, drawer
+     * open/close, hover show/hide). Site events only; the explicit
+     * per-session/visitor/cooldown caps above still win when set.
+     */
+    everyTime?: boolean;
+}
+/**
+ * A per-STEP condition, and the difference between an automation and a flow.
+ *
+ * `HostActionTrigger.conditions` gates the whole action: every step runs or
+ * none does. That is enough for "when a form is submitted, do these three
+ * things" and not enough for anything with a shape — "wait three days, then,
+ * only if they have not ordered, send the reminder" needs the condition to
+ * belong to the step rather than to the run.
+ *
+ * Same clause type and the same combinator as the trigger's, evaluated
+ * against the same scope, so an author learns one condition editor and the
+ * two can never disagree about what `contains` means.
+ */
+export interface HostActionStepGuard {
+    conditions: HostActionTriggerCondition[];
+    /** How the clauses combine; default `and`, as on the trigger. */
+    combinator?: TriggerCombinator | null;
+}
+/**
+ * The scope key a resumed flow carries to say the wait ended on the CLOCK
+ * rather than on the event it was watching for.
+ *
+ * This is how a `waitForEvent` gets its timeout branch without a nested step
+ * list: the flow resumes either way, and the step after it carries a `when`
+ * naming this field. Underscored because it shares a namespace with the
+ * event payload's own fields, which are merchant-authored form field names.
+ */
+export declare const FLOW_TIMED_OUT_FIELD = "_waitTimedOut";
+/**
+ * Evaluates a step's own guard, with the trigger's semantics.
+ *
+ * An absent or clause-less guard passes, exactly as an absent trigger
+ * condition does — so every step written before guards existed keeps running.
+ */
+export declare function evaluateStepGuard(guard: HostActionStepGuard | undefined | null, scope: Record<string, unknown>): boolean;
+export type HostActionStep = ({
+    type: 'runWorkflow';
+    workflowId?: string;
+    workflowName?: string;
+} | {
+    type: 'siteAlert';
+    message: string;
+    severity?: 'info' | 'success' | 'warning' | 'error';
+} | {
+    type: 'customEvent';
+    eventName: string;
+} | {
+    type: 'datasetAppend';
+    datasetId?: string;
+    datasetName?: string;
+} | {
+    type: 'webhookPost';
+    webhookId?: string;
+    webhookName?: string;
+} | {
+    type: 'showOverlay';
+    overlayId?: string;
+    overlayName?: string;
+} | {
+    type: 'stickyNav';
+    selector?: string;
+} | {
+    type: 'addClass';
+    selector: string;
+    className: string;
+} | {
+    type: 'removeClass';
+    selector: string;
+    className: string;
+} | {
+    type: 'toggleClass';
+    selector: string;
+    className: string;
+} | {
+    type: 'showElement';
+    selector: string;
+    delayMs?: number;
+    dismissOn?: ElementDismissOption[];
+} | {
+    type: 'hideElement';
+    selector: string;
+    delayMs?: number;
+} | {
+    type: 'toggleElement';
+    selector: string;
+    delayMs?: number;
+    dismissOn?: ElementDismissOption[];
+} | {
+    type: 'setAttribute';
+    selector: string;
+    name: string;
+    value: string;
+} | {
+    type: 'removeAttribute';
+    selector: string;
+    name: string;
+} | {
+    type: 'scrollTo';
+    selector: string;
+    /** Absent means `smooth`. A visitor who asks for reduced motion is always scrolled instantly. */
+    behavior?: ScrollToBehavior;
+    /** Pixels left above the target, so a sticky header does not cover it. Absent means 0. */
+    offsetPx?: number;
+} | {
+    type: 'playVideo';
+    selector: string;
+} | {
+    type: 'openDrawer';
+    drawerNodeId?: string;
+} | {
+    type: 'closeDrawer';
+    drawerNodeId?: string;
+} | {
+    type: 'toggleDrawer';
+    drawerNodeId?: string;
+} | {
+    type: 'openMenu';
+    menuNodeId?: string;
+} | {
+    type: 'closeMenu';
+    menuNodeId?: string;
+} | {
+    type: 'toggleMenu';
+    menuNodeId?: string;
+} | {
+    type: 'showHtml';
+    html: string;
+} | {
+    type: 'runJs';
+    code: string;
+} | {
+    type: 'redirect';
+    url?: string;
+    screenId?: string;
+} | {
+    type: 'trackGaEvent';
+    eventName: string;
+    params?: Record<string, string>;
+} | {
+    type: 'sendEmail';
+    subject: string;
+    body: string;
+    toField?: string;
+    /**
+     * The stream this message belongs to, so a recipient who left it is not
+     * mailed. Absent on every step authored before topics reached the
+     * actions editor, which the executor resolves to the default topic.
+     */
+    topicId?: string;
+} | {
+    type: 'notifyAdmins';
+    title: string;
+    body?: string;
+} | {
+    type: 'enrollList';
+    listId?: string;
+    listName?: string;
+} | {
+    type: 'updateDataset';
+    datasetId?: string;
+    datasetName?: string;
+} | {
+    type: 'assignCampaign';
+    campaignId?: string;
+    campaignName?: string;
+} | {
+    type: 'wait';
+    /** Whole minutes to hold before the next step. */
+    delayMinutes: number;
+} | {
+    type: 'waitForEvent';
+    /** The host or custom event that resumes this person's flow. */
+    eventName: string;
+    /**
+     * Whole minutes after which the flow continues anyway, with
+     * {@link FLOW_TIMED_OUT_FIELD} true in scope. There is always a
+     * deadline: a wait with no timeout is an enrollment that lives forever.
+     */
+    timeoutMinutes: number;
+}
+/** Ends the enrollment here. Paired with a `when`, this is the exit branch. */
+ | {
+    type: 'exitFlow';
+} | {
+    type: 'setContactStage';
+    lifecycleStage: ContactLifecycleStage;
+} | {
+    type: 'addContactTag';
+    tag: string;
+}
+/**
+ * The owner by uid when a member id was typed or a picker wrote the step,
+ * by email when an address was typed; the executor resolves either against
+ * the org's roster, and only the roster (AGL-2614).
+ * Or `roundRobin`, and the owner is the next member of the pool the CRM's
+ * settings keep (AGL-2618) — a step that names nobody and hands the
+ * choice to the rotation, so a stage change can spread its follow-ups
+ * across a team rather than pile them on one rep. The two are exclusive:
+ * a rotation step carries no member, and the validator refuses one that
+ * names both.
+ */
+ | {
+    type: 'assignContactOwner';
+    ownerUid?: string;
+    ownerEmail?: string;
+    roundRobin?: boolean;
+} | {
+    type: 'createCrmTask';
+    title: string;
+    kind: CrmTaskKind;
+    /** Days from the run to the due date; `0` is due today. */
+    dueInDays: number;
+    /**
+     * Who gets it — by uid or by an address, both resolved against the
+     * roster the way the owner step's are. Neither named, the task goes
+     * to the contact's owner, then to nobody.
+     */
+    assigneeUid?: string;
+    assigneeEmail?: string;
+} | {
+    type: 'logCrmActivity';
+    kind: CrmActivityKind;
+    body: string;
+}) & {
+    /** See {@link HostActionStepGuard}. Absent means the step always runs. */
+    when?: HostActionStepGuard | null;
+};
+/** Steps the tenant page runtime executes client-side (AGL-257). */
+export declare const CLIENT_ACTION_STEP_TYPES: ReadonlySet<HostActionStepType>;
+export declare function isClientActionStep(step: HostActionStep): boolean;
+/**
+ * The steps that suspend a run and continue it later, from a job beat.
+ *
+ * Named as a set rather than checked inline because three surfaces have to
+ * agree on it: the executor stops here and writes an enrollment, the client
+ * payload is truncated here, and the validator refuses a flow that waits
+ * without a person to wait for.
+ */
+export declare const FLOW_SUSPENDING_STEP_TYPES: ReadonlySet<HostActionStepType>;
+export declare function isFlowSuspendingStep(step: HostActionStep): boolean;
+/**
+ * The steps that act on the CRM (AGL-2605) — named as a set because the
+ * executor dispatches all five to one module and the docs list them as one
+ * group, and a step added to the union but not here would be a server step
+ * the executor silently skipped.
+ */
+export declare const CRM_ACTION_STEP_TYPES: ReadonlySet<HostActionStepType>;
+/** The CRM steps, as the type the executor narrows to. */
+export type CrmActionStep = Extract<HostActionStep, {
+    type: 'setContactStage' | 'addContactTag' | 'assignContactOwner' | 'createCrmTask' | 'logCrmActivity';
+}>;
+export declare function isCrmActionStep(step: HostActionStep): step is CrmActionStep;
+/** Longest tag an automation may write — the console's own tag field cap. */
+export declare const CONTACT_TAG_MAX_LENGTH = 60;
+export declare const CRM_ACTION_RECIPE_IDS: readonly ["welcomeNewLead", "followUpWonDeal", "reengageStaleLead", "tagByForm"];
+export type CrmActionRecipeId = (typeof CRM_ACTION_RECIPE_IDS)[number];
+/** What a recipe is handed before it builds — today only the form `tagByForm` reads. */
+export interface CrmActionRecipeInput {
+    form?: {
+        id: string;
+        name: string;
+    };
+}
+export interface CrmActionRecipe {
+    id: CrmActionRecipeId;
+    /** How the recipe reads in the menu; also the action's starting name. */
+    title: string;
+    /** One sentence under the title. */
+    description: string;
+    /**
+     * What must be picked before the recipe can be built. A recipe that needs
+     * nothing opens the editor at once; one that needs a form opens a picker
+     * first. Built WITHOUT its pick, such a recipe yields an action the
+     * validator refuses — a condition with no value — rather than one that
+     * saves and then silently matches nothing.
+     */
+    needs?: 'form';
+    /**
+     * A fresh action each call, because the draft is edited in place. The
+     * action carries `recipe: id` — the provenance is the builder's to stamp,
+     * so a writer that saves what it was handed cannot forget it.
+     */
+    build: (input?: CrmActionRecipeInput) => HostAction;
+}
+/**
+ * How long the stale-lead recipe holds before it decides a lead has gone
+ * quiet. A week: long enough that a rep who is working the lead has had a
+ * chance to move its stage, short enough that a lead nobody touched is
+ * still warm when the reminder lands.
+ */
+export declare const STALE_LEAD_WAIT_MINUTES: number;
+/**
+ * The tag a form's captures get: the form's own name, cut to the tag cap.
+ * The name is what the person calls the form, so it is the tag they would
+ * have typed; the editor is open to change it before anything is saved.
+ */
+export declare function crmRecipeTagForForm(formName: string): string;
+export declare const CRM_ACTION_RECIPES: readonly CrmActionRecipe[];
+/** The recipe with this id, or null for a string that names none. */
+export declare function crmActionRecipe(id: unknown): CrmActionRecipe | null;
+/**
+ * The recipe a STORED action came from, read off its document (AGL-2639).
+ *
+ * Three answers, and the third is the one that matters. A known id: the
+ * action was installed from, or begun as, that recipe. `null`: the action
+ * was begun blank, or from a recipe this build no longer knows — the
+ * editor wrote the field and said "no recipe". `undefined`: the document
+ * carries no `recipe` field at all, which is every action saved before the
+ * stamp existed. Such an action may well have started from a recipe — the
+ * menu opened the editor prefilled long before anything recorded it — so a
+ * reader that needs to know whether a site has a recipe treats `undefined`
+ * as UNKNOWN, never as absent, and never writes a `null` over it.
+ */
+export declare function hostActionRecipeId(action: {
+    recipe?: unknown;
+} | null | undefined): CrmActionRecipeId | null | undefined;
+/**
+ * A HostAction as the document at `hosts/{hostId}/actions/{id}` holds it.
+ *
+ * Every optional trigger key is written OUT — a boolean cap as `false`, a
+ * cleared list as `null` — because the editor saves with a merge-set, and
+ * a merge keeps whatever key the payload omits: a frequency cap switched
+ * off, left out of the payload, would stay on. The legacy single
+ * `condition` is always nulled; `conditions` has been canonical since the
+ * list shape arrived and a document that carried both would have the
+ * reader pick. Everything else is the action, unchanged.
+ *
+ * `recipe` rides along only when the action SAYS something about it: an
+ * id or `null`. An action that carries no stamp (an older document, edited
+ * and saved again) keeps carrying none — see {@link hostActionRecipeId}
+ * for why an absent stamp must not become a `null` one.
+ */
+export interface HostActionDocument extends HostAction {
+    trigger: HostActionTrigger & {
+        oncePerVisitor: boolean;
+        oncePerSession: boolean;
+        cooldownMinutes: number | null;
+        everyTime: boolean;
+        condition: null;
+        conditions: HostActionTriggerCondition[] | null;
+        combinator: TriggerCombinator | null;
+    };
+    enabled: boolean;
+}
+export declare function hostActionDocument(action: HostAction): HostActionDocument;
+/**
+ * The step list as the visitor's browser may see it.
+ *
+ * A client step AFTER a wait must never reach the page. The client engine
+ * runs its slice of the list immediately, so shipping the whole list would
+ * make "wait three days, then show the popup" show the popup at once — the
+ * delay would appear to work on the server, be ignored in the browser, and
+ * the two halves of one authored flow would disagree about when it happened.
+ *
+ * Truncating rather than filtering: everything past the first wait belongs to
+ * a run that has not happened yet, whichever side would have executed it.
+ */
+export declare function hostActionStepsForClient(steps: readonly HostActionStep[] | undefined | null): HostActionStep[];
+/**
+ * Basic presentational interactions (AGL-577): the subset of client steps
+ * that are pure DOM choreography — menu/drawer open-close, element
+ * show/hide, class toggles, sticky nav, navigation, and client-only
+ * alerts. They carry NO server cost and touch NO data, so they run on
+ * every plan (the `interactions` feature, on by default everywhere).
+ *
+ * The powerful client steps stay behind the `actions` entitlement:
+ * `showOverlay` (marketing overlays), `showHtml` (arbitrary HTML
+ * injection), and `trackGaEvent` (analytics). `runJs` keeps its own
+ * higher `webhooks` (Business) gate. Server steps
+ * (sendEmail/notifyAdmins/enrollList/updateDataset/assignCampaign) are
+ * re-checked against `actions` server-side in `runEventActions`.
+ */
+export declare const BASIC_CLIENT_ACTION_STEP_TYPES: ReadonlySet<HostActionStepType>;
+/** A client step available on all plans (no `actions` entitlement). */
+export declare function isBasicClientActionStep(step: HostActionStep): boolean;
+/**
+ * Whether a client step may run for the given entitlement tier (AGL-577).
+ * This is the single source of truth the page enricher uses to trim the
+ * client-automation payload per plan:
+ *
+ * - Basic presentational steps → always (every plan).
+ * - `runJs` → `allowJs` (Business `webhooks` tier).
+ * - Remaining advanced client steps (overlay / showHtml / analytics) →
+ *   `actionsEntitled` (`actions` tier).
+ *
+ * Server steps are not client steps and always return false here; they
+ * are dispatched and re-authorized server-side.
+ */
+export declare function isClientStepEntitled(step: HostActionStep, entitlements: {
+    actionsEntitled: boolean;
+    allowJs: boolean;
+}): boolean;
+export type HostActionStepType = HostActionStep['type'];
+/** `hosts/{hostId}/actions/{id}` doc. */
+export interface HostAction {
+    name: string;
+    trigger: HostActionTrigger;
+    steps: HostActionStep[];
+    /** Disabled actions never run; new actions default enabled. */
+    enabled?: boolean;
+    /**
+     * The recipe this action was installed from or begun as (AGL-2639), or
+     * `null` for one begun blank. Absent on a document from before the stamp
+     * existed — read it through {@link hostActionRecipeId}, which keeps the
+     * three cases apart.
+     */
+    recipe?: CrmActionRecipeId | null;
+}
+export declare const ACTION_MAX_STEPS = 10;
+/** Custom-event chaining depth cap (mirrors CROSS_MAX_DEPTH). */
+export declare const ACTION_MAX_EVENT_DEPTH = 3;
+/**
+ * Cap on the parameters one `trackGaEvent` step may carry (AGL-1587).
+ *
+ * Not a storage concern. These pairs are the least trustworthy analytics
+ * input on the platform — both halves are typed by a site author and land in
+ * that site's own GA4 property — and a bounded list is one an author can read
+ * back in full before publishing, which is the only review a parameter ever
+ * gets. GA4 caps custom parameters per event as well and drops the overflow
+ * without saying so, so an unbounded editor would let an author configure
+ * parameters that are never delivered and never explained. Ten, the same
+ * ceiling {@link ACTION_MAX_STEPS} puts on the step list itself.
+ */
+export declare const ACTION_MAX_EVENT_PARAMS = 10;
+/**
+ * Longest analytics parameter NAME GA4 accepts; it drops a longer one on
+ * arrival, so a name over this is silence rather than a truncated dimension.
+ * The value half is capped by `ANALYTICS_PARAM_MAX_LENGTH`, which truncates
+ * instead of dropping.
+ */
+export declare const ACTION_EVENT_PARAM_NAME_MAX_LENGTH = 40;
+/** Self-dismiss triggers for shown elements (AGL-589). */
+export declare const ELEMENT_DISMISS_OPTIONS: readonly ["escape", "outsideClick"];
+export type ElementDismissOption = (typeof ELEMENT_DISMISS_OPTIONS)[number];
+/** Visibility grace-delay ceiling — enough for hover travel, no dead UIs. */
+export declare const ELEMENT_VISIBILITY_MAX_DELAY_MS = 5000;
+/**
+ * How a `scrollTo` step moves the page. Stored in documents; never rename a
+ * value. `instant` rather than the DOM's `auto`, because `auto` defers to the
+ * site's CSS `scroll-behavior` — a site that sets `smooth` there would animate
+ * a scroll the author asked to be instant.
+ */
+export declare const SCROLL_TO_BEHAVIORS: readonly ["smooth", "instant"];
+export type ScrollToBehavior = (typeof SCROLL_TO_BEHAVIORS)[number];
+/**
+ * The largest offset a `scrollTo` step may leave above its target.
+ *
+ * The offset exists to clear a sticky header, which is tens of pixels and
+ * rarely more than a few hundred with an announcement bar stacked on it. A
+ * thousand leaves room for any header while still refusing the extra digit
+ * that would park the target off the bottom of the screen.
+ */
+export declare const SCROLL_TO_MAX_OFFSET_PX = 1000;
+/** Custom event names: short, no collision with built-ins. */
+export declare const CUSTOM_EVENT_PATTERN: RegExp;
+/**
+ * The shortest and longest a flow may wait.
+ *
+ * The floor is a minute because the resume beat runs on a minute, so anything
+ * under one is a delay the scheduler cannot honor and would only read as
+ * imprecision. The ceiling is ninety days: long enough for the win-back that
+ * is the longest sequence anybody writes, and short enough that an enrollment
+ * is not an unbounded lease on a document. A person waiting inside a flow is
+ * storage the merchant is not looking at, and a wait measured in years is
+ * indistinguishable from one nobody will ever collect.
+ */
+export declare const FLOW_WAIT_MIN_MINUTES = 1;
+export declare const FLOW_WAIT_MAX_MINUTES: number;
+/**
+ * The attribute names an interaction may write (AGL-2546).
+ *
+ * An unrestricted attribute setter is a self-XSS vector authored through the
+ * interactions UI: it reaches `href`, `src`, `onclick`, `formaction` and
+ * `style`, and on a site with collaborators the author and the victim need
+ * not be the same person. `aria-*` and `data-*` carry the entire
+ * accessibility use case and none of that exposure.
+ *
+ * Deliberately NOT solved by an entitlement gate. `runJs` is Business-gated
+ * because it is dangerous at any tier; this has to work on every plan,
+ * because a screen-reader user's access to a menu is not a paid feature.
+ */
+export declare const INTERACTION_ATTRIBUTE_NAME_PATTERN: RegExp;
+/**
+ * Whether an interaction is allowed to write this attribute name.
+ *
+ * Case-insensitive because HTML attribute names are, and a rejected name is
+ * a no-op rather than an error: a step that cannot run must not break the
+ * steps after it in the same automation.
+ */
+export declare function isInteractionAttributeAllowed(name: unknown): boolean;
+export declare const HOST_ACTION_STEP_LABELS: Record<HostActionStepType, string>;
+/**
+ * Past-tense phrases for a run summary (AGL-2171).
+ *
+ * `HOST_ACTION_STEP_LABELS` above names what a step WILL do, in the
+ * imperative, for a `Do` select — "Send an email". A run history is the
+ * opposite tense and a different audience: it says what already happened,
+ * on one line, several steps at a time. `/product/workflows` advertises
+ * exactly that shape — `Sent email · saved to Leads · webhook 200`.
+ *
+ * Two maps rather than one derived from the other, because "Send a webhook
+ * (Business)" cannot be mechanically turned into "webhook" — the plan
+ * suffix is part of the picker's label and has no business in a log line.
+ * Only the steps a SERVER run can perform appear here; the client-side
+ * steps run in the visitor's browser and never reach the activity write.
+ */
+export declare const HOST_ACTION_STEP_OUTCOMES: Partial<Record<HostActionStepType, string>>;
+/**
+ * One step's line in a run summary, with the detail that makes it useful.
+ *
+ * `saved to Leads` beats `saved to dataset`, and `webhook 200` beats
+ * `webhook` — the status code is the entire reason anyone opens a run
+ * history after a webhook, and it was being discarded on the line it
+ * arrived.
+ */
+export declare function describeStepOutcome(type: HostActionStepType, detail?: string): string;
+/** A whole number of minutes inside the wait band. */
+export declare function isFlowWaitMinutes(value: unknown): boolean;
+/** True for a custom (non-built-in) event name an action may fire. */
+export declare function isCustomEventName(event: string): boolean;
+/**
+ * Validates an action doc shape; returns a human-readable error or null.
+ * Server and console share this so bad steps never persist or run.
+ */
+export declare function validateHostAction(action: HostAction): string | null;
+/** Alert produced by a `siteAlert` step, surfaced to the emitting client. */
+export interface HostActionAlert {
+    message: string;
+    severity: 'info' | 'success' | 'warning' | 'error';
+}
+/**
+ * Webhooks (AGL-149) at `hosts/{hostId}/webhooks/{id}`. Outbound entries
+ * are targets a `webhookPost` action step delivers to (HMAC-signed);
+ * inbound entries mint `/api/hooks/{hostId}/{hookId}` endpoints that run
+ * a workflow with the posted JSON in scope. Business tier (`webhooks`
+ * flag); Pro can be enabled per-tenant via entitlement overrides.
+ */
+export interface HostWebhook {
+    name: string;
+    direction: 'outbound' | 'inbound';
+    /** Outbound delivery URL (https only; checked again at send time). */
+    url?: string;
+    /** Shared secret: signs outbound bodies, verifies inbound callers. */
+    secret?: string;
+    /** Inbound: workflow (by name) enrolled with the payload in scope. */
+    workflowName?: string;
+    enabled?: boolean;
+}
+export declare const WEBHOOK_MAX_PER_HOST = 5;
+/**
+ * How many LIVE action documents one host may hold (AGL-2266).
+ *
+ * `hosts/{hostId}/actions` was in NO exclusion list in
+ * `cloud/firebase-firestore.rules`, so the host catch-all's `allow create`
+ * granted it to any editor, client-direct, on any plan — and the import
+ * route's own table said so in as many words: *"no `RESOURCES` entry and no
+ * quota key anywhere; all three creators write the document client-direct."*
+ * A free org could therefore mint unbounded Firestore documents from the
+ * browser against a $0 subscription. Unbounded infrastructure, not a bypass of
+ * anything we sell, which is `WEBHOOK_MAX_PER_HOST`'s (AGL-1360) and
+ * `NON_PAGE_SCREEN_MAX_PER_HOST`'s (AGL-1399) shape exactly: a flat PLATFORM
+ * cap with no `OrgEntitlements` key, no variation by plan, and nothing on the
+ * price list to explain.
+ *
+ * ## Not gated on the `actions` entitlement, deliberately
+ *
+ * `actions` is a Pro feature and `interactions` is free, and BOTH write this
+ * collection — the interaction builder and the besigner's preset wiring create
+ * the same document type the Pro actions card does. Gating creation on the
+ * paid flag would take element interactions away from every free and starter
+ * site, which is a pricing change wearing a cap's clothes. The runtime already
+ * checks the entitlement where it decides what may RUN
+ * (`run-event-actions.ts`), which is the right place for it.
+ *
+ * ## Why 500
+ *
+ * Sized to the busiest plausible site rather than to today's data. An action
+ * is authored per interactive element, so a heavy marketing site with dropdown
+ * choreography on every section reaches tens; presets wire a handful at a
+ * time. 500 is far past anything authoring produces and well short of what a
+ * script in a loop wants, which is the only property a flat cap needs. Live
+ * documents only — the interactions provider soft-deletes with `deletedAt`, so
+ * counting tombstones would be AGL-1173's bug one collection over, where
+ * removing an interaction never frees its slot.
+ */
+export declare const ACTIONS_MAX_PER_HOST = 500;
+/** Outbound URLs must be public https — first-line SSRF guard. */
+export declare const WEBHOOK_URL_PATTERN: RegExp;