@aglyn/aglyn 1.0.0-beta.218 → 1.0.0-beta.220

package/src/lib/app-utils/site-interactions.d.ts

@@ -0,0 +1,501 @@
+/**
+ * @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.
+ */
+/**
+ * SITE INTERACTIONS: what a published page does when a visitor does something.
+ *
+ * An interaction is a trigger and an ordered step list. The trigger names an
+ * event — a SITE event the page runtime watches for itself (a click, a hover,
+ * an element scrolled into view, exit intent), or an event raised on the
+ * server — narrowed by payload conditions and capped in how often it fires.
+ * The steps the platform knows are the ones a page carries out in the
+ * visitor's own browser: showing and hiding elements, opening menus and
+ * drawers, classes and ARIA attributes, scrolling, playing a video, an alert,
+ * a redirect, an analytics event, author HTML and script.
+ *
+ * An interaction is stored on the element that carries it
+ * (`node-interactions.ts`) or as a row of `hosts/{hostId}/actions`, and the
+ * same shape holds more than the platform's own steps. A plugin adds steps of
+ * its own — the workflows plugin's server steps, which a page hands to
+ * `/api/events/dispatch` for the host-event listener that owns them. The
+ * platform types only its own steps ({@link ClientInteractionStep}), knows any
+ * other step only by its `type`, and treats every step that is not one of its
+ * client steps as the server's to run. A plugin that wants one of its steps
+ * offered in the interaction builder DECLARES it, under `interactionSteps` in
+ * `plugins.config.json` ({@link InteractionStepDeclaration}); nothing here
+ * names a plugin.
+ */
+/**
+ * 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 interaction'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-interaction 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 interaction is
+ * skipped when unmet.
+ */
+export interface InteractionCondition {
+    /** 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: InteractionCondition | 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<InteractionTrigger, 'condition' | 'conditions'> | undefined | null): InteractionCondition[];
+/**
+ * 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<InteractionTrigger, 'condition' | 'conditions' | 'combinator'> | undefined | null, payload: Record<string, unknown>): boolean;
+export interface InteractionTrigger {
+    /**
+     * Event the interaction listens for: a HOST_EVENT_TYPE (server-emitted), a
+     * SITE_EVENT_TYPE (client-emitted, AGL-256), or a custom name fired by
+     * another automation'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?: InteractionCondition | 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?: InteractionCondition[] | 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.
+ *
+ * `InteractionTrigger.conditions` gates the whole interaction: 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 InteractionStepGuard {
+    conditions: InteractionCondition[];
+    /** How the clauses combine; default `and`, as on the trigger. */
+    combinator?: TriggerCombinator | null;
+}
+/**
+ * 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: InteractionStepGuard | undefined | null, scope: Record<string, unknown>): boolean;
+/**
+ * The steps the platform itself carries out, in the visitor's browser (AGL-257).
+ *
+ * Every other step an interaction may hold is a plugin's, known here only as
+ * {@link InteractionStepBase}.
+ */
+export type ClientInteractionStep = ({
+    type: 'siteAlert';
+    message: string;
+    severity?: 'info' | 'success' | 'warning' | 'error';
+} | {
+    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>;
+}) & {
+    /** See {@link InteractionStepGuard}. Absent means the step always runs. */
+    when?: InteractionStepGuard | null;
+};
+export type ClientInteractionStepType = ClientInteractionStep['type'];
+/**
+ * Any step, as the platform holds it: a type, the guard every step may carry,
+ * and fields the platform does not read. A plugin's own step types its other
+ * fields itself.
+ */
+export interface InteractionStepBase {
+    type: string;
+    when?: InteractionStepGuard | null;
+    [field: string]: unknown;
+}
+/**
+ * An interaction, as `hosts/{hostId}/actions/{id}` and an element's own
+ * `interactions` hold it.
+ *
+ * `Step` is the platform's client vocabulary unless a reader names more: the
+ * workflows plugin reads the same documents with its server steps added, and
+ * a step from a plugin this reader does not know is still carried, untyped,
+ * in the list.
+ */
+export interface SiteInteraction<Step extends InteractionStepBase = ClientInteractionStep> {
+    name: string;
+    trigger: InteractionTrigger;
+    steps: Step[];
+    /** A disabled interaction never runs; a new one defaults enabled. */
+    enabled?: boolean;
+}
+/** Steps the tenant page runtime executes client-side (AGL-257). */
+export declare const CLIENT_ACTION_STEP_TYPES: ReadonlySet<string>;
+export declare function isClientActionStep(step: InteractionStepBase): step is ClientInteractionStep;
+/**
+ * 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. A step that is not a client step is
+ * the server's, and is re-checked against `actions` where it runs.
+ */
+export declare const BASIC_CLIENT_ACTION_STEP_TYPES: ReadonlySet<string>;
+/** A client step available on all plans (no `actions` entitlement). */
+export declare function isBasicClientActionStep(step: InteractionStepBase): 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: InteractionStepBase, entitlements: {
+    actionsEntitled: boolean;
+    allowJs: boolean;
+}): boolean;
+/** The longest step list an interaction may hold. */
+export declare const ACTION_MAX_STEPS = 10;
+/**
+ * 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 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 interaction.
+ */
+export declare function isInteractionAttributeAllowed(name: unknown): boolean;
+/**
+ * An interaction step a plugin declares under `interactionSteps` in
+ * `plugins.config.json`, compiled into the first-party catalog, so the
+ * interaction builder can offer it and every validator can check it without
+ * the plugin loaded.
+ *
+ * A step may be the plugin's own (a server step the plugin runs) or a
+ * platform client step whose target is a record the plugin keeps. Either way
+ * the declaration says how the builder names it and, for a step that PICKS a
+ * record, where the builder lists the records from and which of the step's
+ * fields hold the pick.
+ */
+export interface InteractionStepDeclaration {
+    /** The plugin that declared it. */
+    pluginId: string;
+    /** The stored step `type`. */
+    type: string;
+    /** How the builder's step picker names it: "Run a workflow". */
+    label: string;
+    /** The record this step acts on, picked in the builder. */
+    picks?: {
+        /** The site collection the records are listed from — one the plugin declares it owns. */
+        collection: string;
+        /** How many records the builder lists. */
+        limit: number;
+        /** The step field holding the picked record's id (rename-safe). */
+        idField: string;
+        /** The step field holding its name at the time it was picked (display only). */
+        nameField: string;
+        /** The picker's label: "Workflow". */
+        label: string;
+        /** What a step with no pick is told, after its `Step N:` prefix. */
+        missing: string;
+    };
+}
+/** Every step the first-party plugins declare, in `plugins.config.json` order. */
+export declare function declaredInteractionSteps(): readonly InteractionStepDeclaration[];
+/** The declared step of this type, or `null` for one no plugin declares. */
+export declare function declaredInteractionStep(type: string, declarations?: readonly InteractionStepDeclaration[]): InteractionStepDeclaration | null;
+export interface ValidateInteractionOptions {
+    /**
+     * One step's checks that belong to its owner — a plugin's own step types.
+     * Runs after the step's guard is checked; its answer, when not `null`, is
+     * the interaction's.
+     */
+    validateStep?: (step: InteractionStepBase, label: string) => string | null;
+    /** The declared steps; the compiled first-party catalog unless a spec says otherwise. */
+    declarations?: readonly InteractionStepDeclaration[];
+}
+/**
+ * Validates an interaction's shape; returns a human-readable error or null.
+ * Every surface that writes one shares this, so a bad step never persists or
+ * runs.
+ *
+ * The platform checks what is its own: the name, the trigger and its
+ * conditions, the step count, each step's guard, its client steps, and the
+ * pick of every declared step that picks a record. A step it does not know is
+ * left to its owner, through `validateStep`.
+ */
+export declare function validateInteraction(interaction: SiteInteraction<InteractionStepBase>, options?: ValidateInteractionOptions): string | null;
+/** Alert produced by a `siteAlert` step, surfaced to the emitting client. */
+export interface SiteAlert {
+    message: string;
+    severity: 'info' | 'success' | 'warning' | 'error';
+}
+/**
+ * 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;