@aglyn/plugins-workflows 1.0.0-beta.220 → 1.0.0-beta.222

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

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

package/src/lib/engine/workflow-steps.d.ts

@@ -14,8 +14,8 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import { type HostActionStep, type HostActionStepType } from '@aglyn/aglyn/app-utils/actions';
 import { type HostWorkflow, type HostWorkflowStep } from '../model/workflows';
+import { type HostActionStep, type HostActionStepType } from '../model/host-actions';
 /**
  * ONE STEP MODEL FOR BOTH ENGINES.
  *

package/src/lib/engine/workflow-steps.js

@@ -14,8 +14,9 @@ import { _ as _extends } from "@swc/helpers/_/_extends";
  * 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 { HOST_ACTION_STEP_LABELS, isClientActionStep, validateHostAction } from "@aglyn/aglyn/app-utils/actions";
-import { WORKFLOW_MAX_STEPS } from "../model/workflows.js";
+ */ import { WORKFLOW_MAX_STEPS } from "../model/workflows.js";
+import { isClientActionStep } from "@aglyn/aglyn/app-utils/site-interactions";
+import { HOST_ACTION_STEP_LABELS, validateHostAction } from "../model/host-actions.js";
 /** Whether a stored step is an Actions step rather than a function call. */ export function isWorkflowActionStep(step) {
     const type = step == null ? void 0 : step.type;
     return typeof type === 'string' && Object.prototype.hasOwnProperty.call(HOST_ACTION_STEP_LABELS, type);

package/src/lib/engine/workflow-steps.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../../../../../libs/plugins/workflows/src/lib/engine/workflow-steps.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport {\n  HOST_ACTION_STEP_LABELS,\n  type HostActionStep,\n  type HostActionStepType,\n  isClientActionStep,\n  validateHostAction,\n} from '@aglyn/aglyn/app-utils/actions'\nimport {\n  type HostWorkflow,\n  type HostWorkflowStep,\n  WORKFLOW_MAX_STEPS,\n} from '../model/workflows'\n\n/**\n * ONE STEP MODEL FOR BOTH ENGINES.\n *\n * A workflow step is one of two things:\n *\n *  - a FUNCTION CALL — `{ functionId, functionName, args, resultName }`, the\n *    shape every workflow has stored since the builder shipped, and still the\n *    default. It evaluates its argument expressions and binds the result for\n *    the steps after it;\n *  - an ACTIONS STEP — `{ type, …fields, when? }`, exactly as the Actions\n *    editor stores it: write a dataset record, send an email, update a CRM\n *    contact, post a webhook, wait. It runs through the Actions executors,\n *    with their validation, their tier gates and their run-history phrases.\n *\n * The two are told apart by `type`. An Actions step always carries one of the\n * Actions step types and a function call never has one, so a stored workflow\n * is read as it was written and nothing is migrated. A step whose `type` the\n * Actions vocabulary does not know is read as a function call, which is how\n * every workflow read it before — it fails as a call to no function.\n *\n * Pure and client-safe: the console's editor and the server's engine read the\n * same definitions from here.\n */\n\n/** A workflow step that runs one of the Actions steps, stored in the Actions shape. */\nexport type WorkflowActionStep = HostActionStep\n\n/** Any step a stored workflow holds. */\nexport type WorkflowStep = HostWorkflowStep | WorkflowActionStep\n\n/** A stored workflow, read with the unified step model. */\nexport interface AutomationWorkflow extends Omit<HostWorkflow, 'steps'> {\n  steps: WorkflowStep[]\n}\n\n/** Whether a stored step is an Actions step rather than a function call. */\nexport function isWorkflowActionStep(step: unknown): step is WorkflowActionStep {\n  const type = (step as { type?: unknown } | null | undefined)?.type\n  return (\n    typeof type === 'string' &&\n    Object.prototype.hasOwnProperty.call(HOST_ACTION_STEP_LABELS, type)\n  )\n}\n\n/** Whether a stored step is a function call. */\nexport function isWorkflowFunctionStep(step: unknown): step is HostWorkflowStep {\n  return Boolean(step) && typeof step === 'object' && !isWorkflowActionStep(step)\n}\n\n/** Whether any step of a workflow is an Actions step. */\nexport function workflowHasActionSteps(\n  workflow: { steps?: readonly unknown[] | null } | null | undefined,\n): boolean {\n  return (workflow?.steps ?? []).some(isWorkflowActionStep)\n}\n\n/**\n * The Actions steps a workflow may hold: every step the SERVER runs.\n *\n * The executor's own rule, stated once. It runs every step that is not a\n * client step, and `siteAlert`, whose alert it hands back to the request that\n * raised the event. What is left out is what only a visitor's browser can do —\n * class toggles, drawers, menus, overlays, scrolling, custom HTML and\n * JavaScript, analytics events, redirects — and a workflow runs on a server\n * event, where there is no page to do it on.\n */\nexport const WORKFLOW_ACTION_STEP_TYPES: readonly HostActionStepType[] = (\n  Object.keys(HOST_ACTION_STEP_LABELS) as HostActionStepType[]\n).filter(\n  (type) =>\n    type === 'siteAlert' || !isClientActionStep({ type } as HostActionStep),\n)\n\nconst WORKFLOW_ACTION_STEP_TYPE_SET: ReadonlySet<string> = new Set(\n  WORKFLOW_ACTION_STEP_TYPES,\n)\n\n/** Whether a workflow may run an Actions step of this type. */\nexport function isWorkflowActionStepType(type: unknown): boolean {\n  return typeof type === 'string' && WORKFLOW_ACTION_STEP_TYPE_SET.has(type)\n}\n\n/** How a step type reads in a sentence: its picker label, or its raw type. */\nexport function workflowStepTypeLabel(type: string): string {\n  return HOST_ACTION_STEP_LABELS[type as HostActionStepType] ?? type\n}\n\n/**\n * Why a workflow cannot hold this Actions step, or null when it can.\n *\n * Shared by the editor, which refuses to save the step, and by the engine,\n * which refuses to run one a writer stored anyway — an import, the API, an\n * older client.\n */\nexport function workflowActionStepRefusal(step: WorkflowActionStep): string | null {\n  if (isWorkflowActionStepType(step.type)) return null\n  if (HOST_ACTION_STEP_LABELS[step.type as HostActionStepType]) {\n    return (\n      `“${workflowStepTypeLabel(step.type)}” runs in the visitor’s browser, ` +\n      'so a workflow cannot run it — build it as an interaction in Actions'\n    )\n  }\n  return `“${String(step.type)}” is not a step a workflow can run`\n}\n\n/**\n * A workflow's steps checked the way the editors check them; null when they\n * pass, or the first problem, numbered by the step's place in the workflow.\n *\n * An Actions step is held to the Actions editor's own validator,\n * `validateHostAction`, one step at a time — the rules are that validator's,\n * never a second copy of them. The list is capped at `WORKFLOW_MAX_STEPS`,\n * the workflow's own ceiling rather than the ten an action is capped at.\n *\n * A FUNCTION CALL is not checked, deliberately. A workflow has always been\n * savable with a blank step — it is how the builder opens, and how an author\n * leaves a pipeline half-built and comes back to it — and a call naming no\n * function fails at run time with the evaluator's own words. Checking it here\n * would refuse a save that has been allowed since the builder shipped.\n */\nexport function validateWorkflowSteps(\n  steps: readonly unknown[] | null | undefined,\n): string | null {\n  const list = Array.isArray(steps) ? steps : []\n  if (list.length > WORKFLOW_MAX_STEPS) {\n    return `Workflows are capped at ${WORKFLOW_MAX_STEPS} steps`\n  }\n  for (const [index, step] of list.entries()) {\n    const label = `Step ${index + 1}`\n    if (!isWorkflowActionStep(step)) continue\n    const refusal = workflowActionStepRefusal(step)\n    if (refusal) return `${label}: ${refusal}`\n    const problem = validateHostAction({\n      name: 'workflow step',\n      trigger: { event: 'formSubmission' },\n      steps: [step],\n    })\n    if (problem) return problem.replace(/^Step 1\\b/, label)\n  }\n  return null\n}\n\n/**\n * The function calls of a workflow, as a workflow of their own, for the pure\n * evaluator — the console's test run, and anything else that evaluates a\n * workflow without performing it.\n *\n * Each call keeps the result name it would have had in place: an unnamed step\n * binds `step<N>` by its position, and the position is the one it holds among\n * ALL the steps, so a call after an Actions step keeps the name the steps\n * after it refer to.\n */\nexport function workflowFunctionCalls(\n  workflow: AutomationWorkflow | HostWorkflow,\n): HostWorkflow {\n  const steps: HostWorkflowStep[] = []\n  ;(workflow.steps ?? []).forEach((step, index) => {\n    if (!isWorkflowFunctionStep(step)) return\n    steps.push({\n      ...step,\n      resultName: step.resultName?.trim() || `step${index + 1}`,\n    })\n  })\n  return { ...workflow, steps } as HostWorkflow\n}\n"],"names":["HOST_ACTION_STEP_LABELS","isClientActionStep","validateHostAction","WORKFLOW_MAX_STEPS","isWorkflowActionStep","step","type","Object","prototype","hasOwnProperty","call","isWorkflowFunctionStep","Boolean","workflowHasActionSteps","workflow","steps","some","WORKFLOW_ACTION_STEP_TYPES","keys","filter","WORKFLOW_ACTION_STEP_TYPE_SET","Set","isWorkflowActionStepType","has","workflowStepTypeLabel","workflowActionStepRefusal","String","validateWorkflowSteps","list","Array","isArray","length","index","entries","label","refusal","problem","name","trigger","event","replace","workflowFunctionCalls","forEach","push","resultName","trim"],"mappings":"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"}
+{"version":3,"sources":["../../../../../../../libs/plugins/workflows/src/lib/engine/workflow-steps.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport {\n  type HostWorkflow,\n  type HostWorkflowStep,\n  WORKFLOW_MAX_STEPS,\n} from '../model/workflows'\nimport { isClientActionStep } from '@aglyn/aglyn/app-utils/site-interactions'\nimport {\n  HOST_ACTION_STEP_LABELS,\n  type HostActionStep,\n  type HostActionStepType,\n  validateHostAction,\n} from '../model/host-actions'\n\n/**\n * ONE STEP MODEL FOR BOTH ENGINES.\n *\n * A workflow step is one of two things:\n *\n *  - a FUNCTION CALL — `{ functionId, functionName, args, resultName }`, the\n *    shape every workflow has stored since the builder shipped, and still the\n *    default. It evaluates its argument expressions and binds the result for\n *    the steps after it;\n *  - an ACTIONS STEP — `{ type, …fields, when? }`, exactly as the Actions\n *    editor stores it: write a dataset record, send an email, update a CRM\n *    contact, post a webhook, wait. It runs through the Actions executors,\n *    with their validation, their tier gates and their run-history phrases.\n *\n * The two are told apart by `type`. An Actions step always carries one of the\n * Actions step types and a function call never has one, so a stored workflow\n * is read as it was written and nothing is migrated. A step whose `type` the\n * Actions vocabulary does not know is read as a function call, which is how\n * every workflow read it before — it fails as a call to no function.\n *\n * Pure and client-safe: the console's editor and the server's engine read the\n * same definitions from here.\n */\n\n/** A workflow step that runs one of the Actions steps, stored in the Actions shape. */\nexport type WorkflowActionStep = HostActionStep\n\n/** Any step a stored workflow holds. */\nexport type WorkflowStep = HostWorkflowStep | WorkflowActionStep\n\n/** A stored workflow, read with the unified step model. */\nexport interface AutomationWorkflow extends Omit<HostWorkflow, 'steps'> {\n  steps: WorkflowStep[]\n}\n\n/** Whether a stored step is an Actions step rather than a function call. */\nexport function isWorkflowActionStep(step: unknown): step is WorkflowActionStep {\n  const type = (step as { type?: unknown } | null | undefined)?.type\n  return (\n    typeof type === 'string' &&\n    Object.prototype.hasOwnProperty.call(HOST_ACTION_STEP_LABELS, type)\n  )\n}\n\n/** Whether a stored step is a function call. */\nexport function isWorkflowFunctionStep(step: unknown): step is HostWorkflowStep {\n  return Boolean(step) && typeof step === 'object' && !isWorkflowActionStep(step)\n}\n\n/** Whether any step of a workflow is an Actions step. */\nexport function workflowHasActionSteps(\n  workflow: { steps?: readonly unknown[] | null } | null | undefined,\n): boolean {\n  return (workflow?.steps ?? []).some(isWorkflowActionStep)\n}\n\n/**\n * The Actions steps a workflow may hold: every step the SERVER runs.\n *\n * The executor's own rule, stated once. It runs every step that is not a\n * client step, and `siteAlert`, whose alert it hands back to the request that\n * raised the event. What is left out is what only a visitor's browser can do —\n * class toggles, drawers, menus, overlays, scrolling, custom HTML and\n * JavaScript, analytics events, redirects — and a workflow runs on a server\n * event, where there is no page to do it on.\n */\nexport const WORKFLOW_ACTION_STEP_TYPES: readonly HostActionStepType[] = (\n  Object.keys(HOST_ACTION_STEP_LABELS) as HostActionStepType[]\n).filter(\n  (type) =>\n    type === 'siteAlert' || !isClientActionStep({ type } as HostActionStep),\n)\n\nconst WORKFLOW_ACTION_STEP_TYPE_SET: ReadonlySet<string> = new Set(\n  WORKFLOW_ACTION_STEP_TYPES,\n)\n\n/** Whether a workflow may run an Actions step of this type. */\nexport function isWorkflowActionStepType(type: unknown): boolean {\n  return typeof type === 'string' && WORKFLOW_ACTION_STEP_TYPE_SET.has(type)\n}\n\n/** How a step type reads in a sentence: its picker label, or its raw type. */\nexport function workflowStepTypeLabel(type: string): string {\n  return HOST_ACTION_STEP_LABELS[type as HostActionStepType] ?? type\n}\n\n/**\n * Why a workflow cannot hold this Actions step, or null when it can.\n *\n * Shared by the editor, which refuses to save the step, and by the engine,\n * which refuses to run one a writer stored anyway — an import, the API, an\n * older client.\n */\nexport function workflowActionStepRefusal(step: WorkflowActionStep): string | null {\n  if (isWorkflowActionStepType(step.type)) return null\n  if (HOST_ACTION_STEP_LABELS[step.type as HostActionStepType]) {\n    return (\n      `“${workflowStepTypeLabel(step.type)}” runs in the visitor’s browser, ` +\n      'so a workflow cannot run it — build it as an interaction in Actions'\n    )\n  }\n  return `“${String(step.type)}” is not a step a workflow can run`\n}\n\n/**\n * A workflow's steps checked the way the editors check them; null when they\n * pass, or the first problem, numbered by the step's place in the workflow.\n *\n * An Actions step is held to the Actions editor's own validator,\n * `validateHostAction`, one step at a time — the rules are that validator's,\n * never a second copy of them. The list is capped at `WORKFLOW_MAX_STEPS`,\n * the workflow's own ceiling rather than the ten an action is capped at.\n *\n * A FUNCTION CALL is not checked, deliberately. A workflow has always been\n * savable with a blank step — it is how the builder opens, and how an author\n * leaves a pipeline half-built and comes back to it — and a call naming no\n * function fails at run time with the evaluator's own words. Checking it here\n * would refuse a save that has been allowed since the builder shipped.\n */\nexport function validateWorkflowSteps(\n  steps: readonly unknown[] | null | undefined,\n): string | null {\n  const list = Array.isArray(steps) ? steps : []\n  if (list.length > WORKFLOW_MAX_STEPS) {\n    return `Workflows are capped at ${WORKFLOW_MAX_STEPS} steps`\n  }\n  for (const [index, step] of list.entries()) {\n    const label = `Step ${index + 1}`\n    if (!isWorkflowActionStep(step)) continue\n    const refusal = workflowActionStepRefusal(step)\n    if (refusal) return `${label}: ${refusal}`\n    const problem = validateHostAction({\n      name: 'workflow step',\n      trigger: { event: 'formSubmission' },\n      steps: [step],\n    })\n    if (problem) return problem.replace(/^Step 1\\b/, label)\n  }\n  return null\n}\n\n/**\n * The function calls of a workflow, as a workflow of their own, for the pure\n * evaluator — the console's test run, and anything else that evaluates a\n * workflow without performing it.\n *\n * Each call keeps the result name it would have had in place: an unnamed step\n * binds `step<N>` by its position, and the position is the one it holds among\n * ALL the steps, so a call after an Actions step keeps the name the steps\n * after it refer to.\n */\nexport function workflowFunctionCalls(\n  workflow: AutomationWorkflow | HostWorkflow,\n): HostWorkflow {\n  const steps: HostWorkflowStep[] = []\n  ;(workflow.steps ?? []).forEach((step, index) => {\n    if (!isWorkflowFunctionStep(step)) return\n    steps.push({\n      ...step,\n      resultName: step.resultName?.trim() || `step${index + 1}`,\n    })\n  })\n  return { ...workflow, steps } as HostWorkflow\n}\n"],"names":["WORKFLOW_MAX_STEPS","isClientActionStep","HOST_ACTION_STEP_LABELS","validateHostAction","isWorkflowActionStep","step","type","Object","prototype","hasOwnProperty","call","isWorkflowFunctionStep","Boolean","workflowHasActionSteps","workflow","steps","some","WORKFLOW_ACTION_STEP_TYPES","keys","filter","WORKFLOW_ACTION_STEP_TYPE_SET","Set","isWorkflowActionStepType","has","workflowStepTypeLabel","workflowActionStepRefusal","String","validateWorkflowSteps","list","Array","isArray","length","index","entries","label","refusal","problem","name","trigger","event","replace","workflowFunctionCalls","forEach","push","resultName","trim"],"mappings":"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"}

package/src/lib/model/host-actions.d.ts

@@ -0,0 +1,231 @@
+/**
+ * @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 '@aglyn/aglyn/app-utils/crm-kinds';
+import type { CrmActivityDirection, CrmTaskPriority } from '@aglyn/aglyn/app-utils/crm';
+import { type ClientInteractionStep, type InteractionCondition, type InteractionStepBase, type InteractionStepGuard, type InteractionTrigger, type SiteAlert, type SiteInteraction } from '@aglyn/aglyn/app-utils/site-interactions';
+/**
+ * THE AUTOMATION VOCABULARY (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 and
+ * validation; the engine that runs them is this plugin's (`engine/`).
+ *
+ * An action is a SITE INTERACTION (core `site-interactions.ts`) with server
+ * steps added: its trigger, its conditions, its client steps, its stored shape
+ * (`siteInteractionDocument`), the slice a visitor's page receives
+ * (`interactionStepsForClient`) and its recipe stamp are the platform's. What
+ * is declared below is the automation's own — the server steps' shapes, the
+ * flow's bounds and each server step's checks. How each step is named, which
+ * steps hold a run and which fields a person types words into are declared in
+ * `plugins.config.json` (`interactionSteps`), so a page, a drafter and a
+ * validator read them without loading this plugin; the checks are registered
+ * from this plugin's declarations (`interaction-step-checks`).
+ */
+/** The automation's names for the platform's interaction shapes. */
+export type HostActionTriggerCondition = InteractionCondition;
+export type HostActionTrigger = InteractionTrigger;
+export type HostActionStepGuard = InteractionStepGuard;
+/** Alert produced by a `siteAlert` step, surfaced to the emitting client. */
+export type HostActionAlert = SiteAlert;
+/**
+ * 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.
+ * Declared as the step's `holds.timeoutField` for readers that do not load
+ * this plugin; this plugin's spec holds the two equal.
+ */
+export declare const FLOW_TIMED_OUT_FIELD = "_waitTimedOut";
+/** The steps an automation adds to the platform's client steps: the server's, run by the workflows plugin. */
+type ServerActionStep = ({
+    type: 'runWorkflow';
+    workflowId?: string;
+    workflowName?: string;
+} | {
+    type: 'customEvent';
+    eventName: string;
+} | {
+    type: 'datasetAppend';
+    datasetId?: string;
+    datasetName?: string;
+} | {
+    type: 'webhookPost';
+    webhookId?: string;
+    webhookName?: 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;
+    /** The task's Type, by meaning; the run stores the org's label for it (AGL-3517). */
+    kind: CrmTaskKind;
+    /** Its Priority, by meaning — `normal` when absent. */
+    priority?: CrmTaskPriority;
+    /** 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;
+    /** Which way a call or an email went (AGL-3517); no other kind takes one. */
+    direction?: CrmActivityDirection;
+}) & {
+    /** See {@link InteractionStepGuard}. Absent means the step always runs. */
+    when?: InteractionStepGuard | null;
+};
+/** A step of an automation: one of the platform's client steps, or one of its server steps. */
+export type HostActionStep = ClientInteractionStep | ServerActionStep;
+/**
+ * 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. A visitor's page and a drafter read the same
+ * fact from each step's declaration (`holds`, `interactionSteps` in
+ * `plugins.config.json`), which this plugin's spec holds to this set.
+ */
+export declare const FLOW_SUSPENDING_STEP_TYPES: ReadonlySet<HostActionStepType>;
+export declare function isFlowSuspendingStep(step: HostActionStep): boolean;
+export type HostActionStepType = HostActionStep['type'];
+/**
+ * `hosts/{hostId}/actions/{id}` doc: a site interaction whose steps may be
+ * the automation's server steps as well as the platform's client steps.
+ */
+export type HostAction = SiteInteraction<HostActionStep>;
+/**
+ * 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. Declared as the band
+ * each waiting step `holds`; this plugin's spec holds the two equal.
+ */
+export declare const FLOW_WAIT_MIN_MINUTES = 1;
+export declare const FLOW_WAIT_MAX_MINUTES: number;
+/** Every step type an action may hold, in the picker's order. */
+export declare const HOST_ACTION_STEP_TYPES: readonly HostActionStepType[];
+/** The server steps among them: every type that is not one of the platform's client steps. */
+export declare const SERVER_ACTION_STEP_TYPES: readonly HostActionStepType[];
+/**
+ * How each step reads in the editor's picker, a run history and a sentence:
+ * the platform's label for a client step, and the label its declaration
+ * gives every other (`interactionSteps` in `plugins.config.json`), so a page,
+ * a drafter and this editor name a step alike.
+ */
+export declare const HOST_ACTION_STEP_LABELS: Readonly<Record<HostActionStepType, 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;
+/**
+ * A server step's own complaint, or null. A `runWorkflow` step's pick is
+ * checked with every other declared step's (`interactionSteps` in
+ * `plugins.config.json`), by `validateInteraction`.
+ *
+ * Registered from this plugin's declarations as the check of every server
+ * step (`interaction-step-checks`), so a plugin that writes an automation it
+ * does not edit — a recipe installed into a site — refuses what this editor
+ * would.
+ */
+export declare function hostActionStepProblem(candidate: InteractionStepBase, label: string): string | null;
+export {};

package/src/lib/model/host-actions.js

@@ -0,0 +1,268 @@
+/**
+ * @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 { CONTACT_TAG_MAX_LENGTH, CRM_TASK_MAX_DUE_DAYS, isContactLifecycleStage, isCrmActivityKind, isCrmTaskKind } from "@aglyn/aglyn/app-utils/crm-kinds";
+import { HOST_EVENT_TYPES } from "@aglyn/aglyn/app-utils/host-events";
+import { CLIENT_ACTION_STEP_TYPES, CUSTOM_EVENT_PATTERN, interactionStepLabel, validateInteraction } from "@aglyn/aglyn/app-utils/site-interactions";
+/** A task's priorities, by meaning (AGL-3517) — the `taskPriority` picklist's meanings. */ const TASK_PRIORITIES = [
+    'low',
+    'normal',
+    'high'
+];
+/** The directions a logged call or email takes (AGL-3517) — `CRM_ACTIVITY_DIRECTIONS`. */ const ACTIVITY_DIRECTIONS = {
+    call: [
+        'outbound',
+        'inbound',
+        'internal'
+    ],
+    email: [
+        'outbound',
+        'inbound'
+    ]
+};
+/**
+ * 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.
+ * Declared as the step's `holds.timeoutField` for readers that do not load
+ * this plugin; this plugin's spec holds the two equal.
+ */ export const FLOW_TIMED_OUT_FIELD = '_waitTimedOut';
+/**
+ * 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. A visitor's page and a drafter read the same
+ * fact from each step's declaration (`holds`, `interactionSteps` in
+ * `plugins.config.json`), which this plugin's spec holds to this set.
+ */ export const FLOW_SUSPENDING_STEP_TYPES = new Set([
+    'wait',
+    'waitForEvent'
+]);
+export function isFlowSuspendingStep(step) {
+    return FLOW_SUSPENDING_STEP_TYPES.has(step.type);
+}
+/**
+ * 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. Declared as the band
+ * each waiting step `holds`; this plugin's spec holds the two equal.
+ */ export const FLOW_WAIT_MIN_MINUTES = 1;
+export const FLOW_WAIT_MAX_MINUTES = 90 * 24 * 60;
+/**
+ * Every step an action may hold, in the order the editor's "Do" picker offers
+ * them. Total over the step types: a type the vocabulary gains is a compile
+ * error here until it is placed.
+ */ const STEP_ORDER = {
+    runWorkflow: 0,
+    siteAlert: 1,
+    customEvent: 2,
+    datasetAppend: 3,
+    webhookPost: 4,
+    showOverlay: 5,
+    stickyNav: 6,
+    addClass: 7,
+    toggleClass: 8,
+    removeClass: 9,
+    showElement: 10,
+    hideElement: 11,
+    toggleElement: 12,
+    openDrawer: 13,
+    closeDrawer: 14,
+    toggleDrawer: 15,
+    openMenu: 16,
+    closeMenu: 17,
+    toggleMenu: 18,
+    setAttribute: 19,
+    removeAttribute: 20,
+    scrollTo: 21,
+    playVideo: 22,
+    showHtml: 23,
+    runJs: 24,
+    redirect: 25,
+    trackGaEvent: 26,
+    sendEmail: 27,
+    notifyAdmins: 28,
+    enrollList: 29,
+    updateDataset: 30,
+    assignCampaign: 31,
+    wait: 32,
+    waitForEvent: 33,
+    exitFlow: 34,
+    setContactStage: 35,
+    addContactTag: 36,
+    assignContactOwner: 37,
+    createCrmTask: 38,
+    logCrmActivity: 39
+};
+/** Every step type an action may hold, in the picker's order. */ export const HOST_ACTION_STEP_TYPES = Object.keys(STEP_ORDER).sort((a, b)=>STEP_ORDER[a] - STEP_ORDER[b]);
+/** The server steps among them: every type that is not one of the platform's client steps. */ export const SERVER_ACTION_STEP_TYPES = HOST_ACTION_STEP_TYPES.filter((type)=>!CLIENT_ACTION_STEP_TYPES.has(type));
+/**
+ * How each step reads in the editor's picker, a run history and a sentence:
+ * the platform's label for a client step, and the label its declaration
+ * gives every other (`interactionSteps` in `plugins.config.json`), so a page,
+ * a drafter and this editor name a step alike.
+ */ export const HOST_ACTION_STEP_LABELS = Object.fromEntries(HOST_ACTION_STEP_TYPES.map((type)=>{
+    var _interactionStepLabel;
+    return [
+        type,
+        (_interactionStepLabel = interactionStepLabel(type)) != null ? _interactionStepLabel : type
+    ];
+}));
+/** A whole number of minutes inside the wait band. */ export function isFlowWaitMinutes(value) {
+    return Number.isInteger(value) && value >= FLOW_WAIT_MIN_MINUTES && value <= FLOW_WAIT_MAX_MINUTES;
+}
+/** True for a custom (non-built-in) event name an action may fire. */ export function isCustomEventName(event) {
+    return !HOST_EVENT_TYPES.includes(event) && CUSTOM_EVENT_PATTERN.test(event);
+}
+/**
+ * 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 function validateHostAction(action) {
+    // The name, the recipe stamp, the trigger, the step guards, the client
+    // steps and every declared step's pick are the platform's to check; the
+    // server steps are this module's.
+    return validateInteraction(action, {
+        validateStep: (step, label)=>hostActionStepProblem(step, label)
+    });
+}
+/**
+ * A server step's own complaint, or null. A `runWorkflow` step's pick is
+ * checked with every other declared step's (`interactionSteps` in
+ * `plugins.config.json`), by `validateInteraction`.
+ *
+ * Registered from this plugin's declarations as the check of every server
+ * step (`interaction-step-checks`), so a plugin that writes an automation it
+ * does not edit — a recipe installed into a site — refuses what this editor
+ * would.
+ */ export function hostActionStepProblem(candidate, label) {
+    var _step_datasetId, _step_datasetName, _step_webhookId, _step_webhookName, _step_title, _step_listId, _step_listName, _step_datasetId1, _step_datasetName1, _step_campaignId, _step_campaignName;
+    const step = candidate;
+    if (step.type === 'wait' && !isFlowWaitMinutes(step.delayMinutes)) {
+        return `${label}: wait between ${FLOW_WAIT_MIN_MINUTES} minute and ${FLOW_WAIT_MAX_MINUTES} minutes`;
+    }
+    if (step.type === 'waitForEvent') {
+        var _ref;
+        var _step_eventName;
+        const waited = (_ref = (_step_eventName = step.eventName) == null ? void 0 : _step_eventName.trim()) != null ? _ref : '';
+        if (!waited || !HOST_EVENT_TYPES.includes(waited) && !isCustomEventName(waited)) {
+            return `${label}: pick the event to wait for`;
+        }
+        if (!isFlowWaitMinutes(step.timeoutMinutes)) {
+            return `${label}: give up after ${FLOW_WAIT_MIN_MINUTES}–${FLOW_WAIT_MAX_MINUTES} minutes`;
+        }
+    }
+    if (step.type === 'customEvent') {
+        var _ref1;
+        var _step_eventName1;
+        if (!isCustomEventName((_ref1 = (_step_eventName1 = step.eventName) == null ? void 0 : _step_eventName1.trim()) != null ? _ref1 : '')) {
+            return `${label}: custom event names are 2–40 letters, digits, dashes`;
+        }
+    }
+    if (step.type === 'datasetAppend' && !((_step_datasetId = step.datasetId) == null ? void 0 : _step_datasetId.trim()) && !((_step_datasetName = step.datasetName) == null ? void 0 : _step_datasetName.trim())) {
+        return `${label}: pick a dataset`;
+    }
+    if (step.type === 'webhookPost' && !((_step_webhookId = step.webhookId) == null ? void 0 : _step_webhookId.trim()) && !((_step_webhookName = step.webhookName) == null ? void 0 : _step_webhookName.trim())) {
+        return `${label}: pick a webhook`;
+    }
+    if (step.type === 'sendEmail') {
+        var _step_subject, _step_body;
+        if (!((_step_subject = step.subject) == null ? void 0 : _step_subject.trim())) return `${label}: enter the subject`;
+        if (!((_step_body = step.body) == null ? void 0 : _step_body.trim())) return `${label}: enter the email body`;
+    }
+    if (step.type === 'notifyAdmins' && !((_step_title = step.title) == null ? void 0 : _step_title.trim())) {
+        return `${label}: enter the notification title`;
+    }
+    if (step.type === 'enrollList' && !((_step_listId = step.listId) == null ? void 0 : _step_listId.trim()) && !((_step_listName = step.listName) == null ? void 0 : _step_listName.trim())) {
+        return `${label}: pick a list`;
+    }
+    if (step.type === 'updateDataset' && !((_step_datasetId1 = step.datasetId) == null ? void 0 : _step_datasetId1.trim()) && !((_step_datasetName1 = step.datasetName) == null ? void 0 : _step_datasetName1.trim())) {
+        return `${label}: pick a dataset`;
+    }
+    if (step.type === 'assignCampaign' && !((_step_campaignId = step.campaignId) == null ? void 0 : _step_campaignId.trim()) && !((_step_campaignName = step.campaignName) == null ? void 0 : _step_campaignName.trim())) {
+        return `${label}: pick a campaign`;
+    }
+    // CRM steps (AGL-2605). A stage or a kind outside its vocabulary is
+    // refused here rather than stored: the executor treats the value as
+    // trusted and would write it into a facet every stage report counts.
+    if (step.type === 'setContactStage' && !isContactLifecycleStage(step.lifecycleStage)) {
+        return `${label}: pick a lifecycle stage`;
+    }
+    if (step.type === 'addContactTag') {
+        var _ref2;
+        var _step_tag;
+        const tag = (_ref2 = (_step_tag = step.tag) == null ? void 0 : _step_tag.trim()) != null ? _ref2 : '';
+        if (!tag) return `${label}: enter the tag`;
+        if (tag.length > CONTACT_TAG_MAX_LENGTH) {
+            return `${label}: tags are at most ${CONTACT_TAG_MAX_LENGTH} characters`;
+        }
+    }
+    if (step.type === 'assignContactOwner') {
+        var _step_ownerUid, _step_ownerEmail, _step_ownerUid1, _step_ownerEmail1;
+        const named = Boolean(((_step_ownerUid = step.ownerUid) == null ? void 0 : _step_ownerUid.trim()) || ((_step_ownerEmail = step.ownerEmail) == null ? void 0 : _step_ownerEmail.trim()));
+        if (step.roundRobin === true && named) {
+            return `${label}: pick round robin or a member, not both`;
+        }
+        if (step.roundRobin !== true && !((_step_ownerUid1 = step.ownerUid) == null ? void 0 : _step_ownerUid1.trim()) && !((_step_ownerEmail1 = step.ownerEmail) == null ? void 0 : _step_ownerEmail1.trim().includes('@'))) {
+            return `${label}: enter the owner’s email address`;
+        }
+    }
+    if (step.type === 'createCrmTask') {
+        var _ref3;
+        var _step_title1, _step_assigneeEmail;
+        if (!((_step_title1 = step.title) == null ? void 0 : _step_title1.trim())) return `${label}: give the task a title`;
+        if (!isCrmTaskKind(step.kind)) return `${label}: pick the type of task`;
+        if (step.priority !== undefined && !TASK_PRIORITIES.includes(step.priority)) {
+            return `${label}: pick the task’s priority`;
+        }
+        if (!Number.isInteger(step.dueInDays) || step.dueInDays < 0 || step.dueInDays > CRM_TASK_MAX_DUE_DAYS) {
+            return `${label}: due in 0–${CRM_TASK_MAX_DUE_DAYS} days`;
+        }
+        // Optional — but an address that is not one would resolve to nobody at
+        // run time, and the task would land unassigned with no word why.
+        const assigneeEmail = (_ref3 = (_step_assigneeEmail = step.assigneeEmail) == null ? void 0 : _step_assigneeEmail.trim()) != null ? _ref3 : '';
+        if (assigneeEmail && !assigneeEmail.includes('@')) {
+            return `${label}: enter the assignee’s email address`;
+        }
+    }
+    if (step.type === 'logCrmActivity') {
+        var _step_body1;
+        if (!isCrmActivityKind(step.kind)) {
+            return `${label}: pick the kind of activity`;
+        }
+        if (step.direction !== undefined) {
+            var _ACTIVITY_DIRECTIONS_step_kind;
+            const directions = (_ACTIVITY_DIRECTIONS_step_kind = ACTIVITY_DIRECTIONS[step.kind]) != null ? _ACTIVITY_DIRECTIONS_step_kind : [];
+            if (!directions.includes(step.direction)) {
+                return directions.length ? `${label}: pick which way the ${step.kind} went` : `${label}: only a call or an email takes a direction`;
+            }
+        }
+        if (!((_step_body1 = step.body) == null ? void 0 : _step_body1.trim())) return `${label}: write what happened`;
+    }
+    return null;
+}
+
+//# sourceMappingURL=host-actions.js.map