@teleporthq/teleport-plugin-next-workflows 0.44.11 → 0.45.0

package/src/automations/activity-kicks.ts

@@ -0,0 +1,139 @@
+import type { ProjectPluginStructure } from '@teleporthq/teleport-types'
+import { AUTOMATIONS_PATH } from './automations-scope'
+import { dueWaitsSql, retriableEventsSql } from './dispatcher-source'
+
+/**
+ * Activity kicks (spec §5.2): a due Wait, a failed run waiting for its retry,
+ * and the work a stopped dispatcher left behind (a stale `pending` event, a
+ * stale resume) have no event of their own to wake the queue, so the site's
+ * activity does. `lib/automations/due-check.js` exports `kickWhenDue(req?)`, called by
+ * every server read of the TeleportHQ database (the data-source modules a
+ * page's server render and the admin's lists go through) and by the data API:
+ *
+ * - at most one check per minute per process (the rest return null at once);
+ * - never on the request's path: the check is a cheap EXISTS query run after
+ *   the call returns, kept alive by the platform's `waitUntil` on Vercel;
+ * - when work is due it wakes the queue the way an emitter does
+ *   (`scheduleDispatch`);
+ * - never while `next build` renders the pages.
+ *
+ * Generated only with the event bus (generateAutomationFiles), like every
+ * file of `lib/automations/`.
+ */
+
+const CHECK_EVERY_MS = 60 * 1000
+
+/**
+ * Work a dispatch pass would act on now, by the claims' own rules (shared with
+ * the dispatcher), so the kick never wakes a pass with nothing to do: a Wait
+ * that is due or whose resume went stale, and a failed or stale `pending`
+ * event, of an automation of this build ($1: its workflow ids, $2: its event
+ * types). New events are woken by their emitters.
+ */
+const DUE_SQL =
+  `SELECT (EXISTS (SELECT 1 FROM teleport_automation_waits w WHERE ${dueWaitsSql('$1')}) ` +
+  `OR EXISTS (SELECT 1 FROM teleport_events e WHERE ${retriableEventsSql('$2', '$1')})) AS due`
+
+/** `lib/automations/due-check.js`, for the automations of this build. */
+export const generateAutomationDueCheckCode = (
+  workflowIds: string[],
+  eventTypes: string[]
+): string => `'use strict';
+/**
+ * Automations: the activity kick (generated). The site's server reads call
+ * kickWhenDue(req): once a minute at most, off the request, it looks for a
+ * Wait that is due, a failed run waiting for its retry, or work a stopped
+ * dispatcher left behind, and wakes the queue when there is some.
+ */
+var store = require('./store');
+var bus = require('./event-bus');
+
+var CHECK_EVERY_MS = ${CHECK_EVERY_MS};
+var WORKFLOW_IDS = ${JSON.stringify(workflowIds)};
+var EVENT_TYPES = ${JSON.stringify(eventTypes)};
+var DUE_SQL = ${JSON.stringify(DUE_SQL)};
+
+var lastCheckAt = 0;
+
+async function check(req) {
+  try {
+    var result = await store.withClient(function (client) {
+      return client.query(DUE_SQL, [WORKFLOW_IDS, EVENT_TYPES]);
+    });
+    var row = result && result.rows && result.rows[0];
+    var due = !!row && (row.due === true || row.due === 't');
+    if (due) bus.scheduleDispatch(req);
+    return due;
+  } catch (error) {
+    console.warn('[automations] could not check for due work: ' + store.errorMessage(error));
+    return false;
+  }
+}
+
+// Resolves whether it woke the queue; null when this minute's check ran already.
+function kickWhenDue(req) {
+  if (process.env.NEXT_PHASE === 'phase-production-build') return null;
+  var now = Date.now();
+  if (now - lastCheckAt < CHECK_EVERY_MS) return null;
+  lastCheckAt = now;
+  var work = Promise.resolve().then(function () { return check(req); });
+  var waitUntil = process.env.VERCEL && typeof globalThis.__tqWaitUntil === 'function' ? globalThis.__tqWaitUntil : null;
+  if (waitUntil) {
+    try { waitUntil(work); } catch (_e) {}
+  }
+  return work;
+}
+
+module.exports = { kickWhenDue: kickWhenDue };
+`
+
+/** From a data-source module (`utils/data-sources/`, `pages/api/`) to the project root. */
+const DUE_CHECK_IMPORT = `import { kickWhenDue as __tqKickDueAutomations } from '../../${AUTOMATIONS_PATH.join(
+  '/'
+)}/due-check'`
+
+/**
+ * The handler every data-source module of the data-source plugin runs for a
+ * read (`generateDataSourceFetcherWithCore`: an API route, and a page's
+ * server render through `fetchData`).
+ */
+const HANDLER_OPENING = '\nasync function handler(req, res) {\n'
+
+const KICK_CALL =
+  '  // Activity on the site: due automation work (a Wait, a retry) starts off this request.\n' +
+  '  __tqKickDueAutomations(req)\n'
+
+/** Where the data-source plugin writes the modules that read a table. */
+const DATA_SOURCE_MODULE_FOLDERS = ['utils/data-sources', 'pages/api']
+
+/**
+ * Starts the due check from every module that reads the TeleportHQ database
+ * (the data-source plugin names them `teleport-<table>-<id>`), the only one
+ * automations run on: one import, one call at the top of its handler. A module
+ * of another database, or one that only re-exports another's handler, is left
+ * as it is. Runs after the page plugins wrote them.
+ */
+export const installAutomationActivityKicks = (structure: ProjectPluginStructure): void => {
+  for (const entry of structure.files.values()) {
+    if (DATA_SOURCE_MODULE_FOLDERS.indexOf(entry.path.join('/')) === -1) {
+      continue
+    }
+    for (const file of entry.files) {
+      const content = typeof file.content === 'string' ? file.content : ''
+      const at = content.indexOf(HANDLER_OPENING)
+      if (
+        !file.name.startsWith('teleport-') ||
+        at === -1 ||
+        content.indexOf(HANDLER_OPENING, at + 1) !== -1 ||
+        content.indexOf(DUE_CHECK_IMPORT) !== -1
+      ) {
+        continue
+      }
+      const bodyStart = at + HANDLER_OPENING.length
+      file.content = `${DUE_CHECK_IMPORT}\n${content.slice(
+        0,
+        bodyStart
+      )}${KICK_CALL}${content.slice(bodyStart)}`
+    }
+  }
+}

package/src/automations/app-events-source.ts

@@ -0,0 +1,117 @@
+import { FileType, ProjectPluginStructure } from '@teleporthq/teleport-types'
+
+/**
+ * `utils/app-events.js`: how a generated route records a business event
+ * (spec §5.1) on its own database connection — the data API's low-stock
+ * alert:
+ *
+ *   const { recordAppEvent } = require('<root>/utils/app-events');
+ *   await recordAppEvent(db, { type, entityType, entityId, orderId?, payload,
+ *     actor, actorType, dedupeKey }, req);
+ *
+ * `db` is the route's own Postgres client (anything with `query(text,
+ * values)` resolving `{ rows }`), so the row is written on the route's
+ * connection; call it once the route's own writes are committed, or the queue
+ * cannot see the row yet. A replayed `dedupeKey` writes nothing. Never
+ * throws: it resolves `{ recorded, id }`, so the event ledger can never fail
+ * the operation it records.
+ *
+ * The row is always written: it is the record timelines and the editor's
+ * history read. When the project has automations (`withAutomations`, decided
+ * at generation: the in-app event bus `lib/automations/event-bus.js` exists)
+ * a new row also wakes the queue, off the request path, on the app's own
+ * origin as `req` reached it (never a URL a caller hands in). Without them
+ * the module never names the bus.
+ */
+
+export const APP_EVENTS_FILE_KEY = 'app-events'
+export const APP_EVENTS_PATH = ['utils']
+export const APP_EVENTS_FILE_NAME = 'app-events'
+
+/** From `utils/app-events.js` to the bus the automations plugin generates. */
+const EVENT_BUS_REQUIRE_PATH = '../lib/automations/event-bus'
+
+const INSERT_EVENT_SQL =
+  'INSERT INTO teleport_events (event_type, dedupe_key, order_id, entity_type, entity_id, payload, actor, actor_type) ' +
+  'VALUES ($1, $2, $3, $4, $5, $6, $7, $8) ON CONFLICT (dedupe_key) DO NOTHING RETURNING id'
+
+const KICK_WITH_AUTOMATIONS = `// The project has automations: a new event wakes their queue.
+function kick(req) {
+  try {
+    require('${EVENT_BUS_REQUIRE_PATH}').scheduleDispatch(req);
+  } catch (error) {
+    console.warn('[app-events] could not wake the automations: ' + errorMessage(error));
+  }
+}`
+
+const KICK_WITHOUT_AUTOMATIONS = `// The project has no automations: the row is the whole record.
+function kick() {}`
+
+export const generateAppEventsModuleCode = (options: {
+  withAutomations: boolean
+}): string => `'use strict';
+/**
+ * Business events recorded by the app's routes (generated).
+ */
+var crypto = require('crypto');
+
+var INSERT_EVENT_SQL = ${JSON.stringify(INSERT_EVENT_SQL)};
+
+function errorMessage(error) {
+  return error && error.message ? String(error.message) : String(error);
+}
+
+${options.withAutomations ? KICK_WITH_AUTOMATIONS : KICK_WITHOUT_AUTOMATIONS}
+
+function column(value, maxLength) {
+  if (value === undefined || value === null || value === '') return null;
+  return String(value).slice(0, maxLength);
+}
+
+async function recordAppEvent(db, event, req) {
+  var input = event || {};
+  try {
+    var type = column(input.type, 100);
+    if (!type) throw new Error('An event needs its type');
+    var result = await db.query(INSERT_EVENT_SQL, [
+      type,
+      column(input.dedupeKey, 255) || type + ':' + crypto.randomUUID(),
+      column(input.orderId, 64),
+      column(input.entityType, 40),
+      column(input.entityId, 64),
+      input.payload === undefined || input.payload === null ? null : JSON.stringify(input.payload),
+      column(input.actor, 255),
+      column(input.actorType, 50) || 'system',
+    ]);
+    var row = result && result.rows && result.rows[0];
+    if (!row) return { recorded: false, id: null };
+    kick(req);
+    return { recorded: true, id: String(row.id) };
+  } catch (error) {
+    console.error('[app-events] could not record the ' + String(input.type) + ' event: ' + errorMessage(error));
+    return { recorded: false, id: null };
+  }
+}
+
+module.exports = { recordAppEvent: recordAppEvent };
+`
+
+/** Writes `utils/app-events.js` into the project, once. */
+export const ensureAppEventsModule = (
+  structure: ProjectPluginStructure,
+  withAutomations: boolean
+): void => {
+  if (structure.files.has(APP_EVENTS_FILE_KEY)) {
+    return
+  }
+  structure.files.set(APP_EVENTS_FILE_KEY, {
+    path: APP_EVENTS_PATH,
+    files: [
+      {
+        name: APP_EVENTS_FILE_NAME,
+        fileType: FileType.JS,
+        content: generateAppEventsModuleCode({ withAutomations }),
+      },
+    ],
+  })
+}

package/src/automations/automations-project-plugin.ts

@@ -0,0 +1,202 @@
+import {
+  FileType,
+  ProjectPluginStructure,
+  UIDLCustomWorkflowNode,
+  UIDLWorkflow,
+} from '@teleporthq/teleport-types'
+import { getDatabaseDriverDependencies } from '../auth-generator'
+import { declareCronSecretEnv } from '../cron-request-verification'
+import { enableSentEmailAttribution } from '../sent-email-log'
+import {
+  AUTOMATION_HANDLERS_PATH,
+  AUTOMATION_HYDRATE_PATH,
+  AUTOMATIONS_DISPATCH_ROUTE_PATH,
+  AUTOMATIONS_FILE_KEY_PREFIX,
+  AUTOMATIONS_PATH,
+  AUTOMATIONS_UNAVAILABLE_REASON,
+  VERCEL_FUNCTIONS_DEPENDENCY,
+  automationEntityOf,
+  automationEnvelopeKeys,
+  automationEventType,
+  resolveAutomationsDatabase,
+} from './automations-scope'
+import {
+  generateAutomationEventBusCode,
+  generateAutomationStoreCode,
+  generateAutomationWaitUntilCode,
+} from './event-bus-source'
+import {
+  generateAutomationDispatchRouteCode,
+  generateAutomationDispatcherCode,
+  generateAutomationsUnavailableRouteCode,
+} from './dispatcher-source'
+import { generateAutomationHydratorCode } from './hydrators-source'
+import { generateAutomationDueCheckCode, installAutomationActivityKicks } from './activity-kicks'
+import {
+  generateAutomationHandlerModule,
+  generateAutomationRegistryCode,
+  resolveAutomationHandlerFileNames,
+  toRegistryEntry,
+} from './handler-module-generator'
+
+export interface AutomationFilesOptions {
+  customNodes?: Record<string, UIDLCustomWorkflowNode>
+  /** The auth users table, read for the `user` block of account events. */
+  usersTable: string
+  /** The order details page's route prefix, for `order.pageUrl` (null: no link). */
+  orderPagePrefix: string | null
+}
+
+const setFile = (
+  structure: ProjectPluginStructure,
+  key: string,
+  path: string[],
+  name: string,
+  content: string
+): void => {
+  structure.files.set(`${AUTOMATIONS_FILE_KEY_PREFIX}${key}`, {
+    path,
+    files: [{ name, fileType: FileType.JS, content }],
+  })
+}
+
+/**
+ * Emits the in-app event bus for the project's automations (see
+ * automations-scope.ts). Nothing at all without one: an automation whose
+ * trigger names no event is skipped, with a warning, like a mis-scoped page
+ * workflow. No bus either when the UIDL names no TeleportHQ database for the
+ * automation tables (`uidl.automations`, the only database automations run
+ * on): a bus that opened another database than the one the editor writes the
+ * switches to would run nothing the owner sees. The build says why, and the
+ * dispatch route answers why (503), so a test sent from the editor shows the
+ * reason instead of a missing page.
+ */
+export const generateAutomationFiles = (
+  structure: ProjectPluginStructure,
+  workflows: UIDLWorkflow[],
+  options: AutomationFilesOptions
+): void => {
+  const automations = workflows.filter((workflow) => {
+    if (automationEventType(workflow)) {
+      return true
+    }
+    console.warn(
+      `[teleport-plugin-next-workflows] Automation "${
+        workflow.name || workflow.id
+      }" names no business event - skipping code generation for it. Pick the event in its trigger.`
+    )
+    return false
+  })
+  if (automations.length === 0) {
+    return
+  }
+  const database = resolveAutomationsDatabase(structure.uidl.automations)
+  if (!database) {
+    console.warn(
+      `[teleport-plugin-next-workflows] The project has automations but ${AUTOMATIONS_UNAVAILABLE_REASON} (uidl.automations) - no event bus is generated, so they do not run. Create the TeleportHQ database in Automations.`
+    )
+    setFile(
+      structure,
+      'dispatch-route',
+      AUTOMATIONS_DISPATCH_ROUTE_PATH,
+      'dispatch',
+      generateAutomationsUnavailableRouteCode(AUTOMATIONS_UNAVAILABLE_REASON)
+    )
+    return
+  }
+
+  const fileNames = resolveAutomationHandlerFileNames(automations)
+  const entries = automations.map((workflow) => {
+    const fileName = fileNames.get(workflow.id) as string
+    setFile(
+      structure,
+      `handler-${workflow.id}`,
+      AUTOMATION_HANDLERS_PATH,
+      fileName,
+      generateAutomationHandlerModule(workflow, options.customNodes)
+    )
+    return toRegistryEntry(workflow, fileName)
+  })
+
+  const entityByType: Record<string, string | null> = {}
+  const envelopeKeysByType: Record<string, string[] | null> = {}
+  const hydratedEntities: string[] = []
+  for (const { eventType } of entries) {
+    const entity = automationEntityOf(eventType)
+    entityByType[eventType] = entity
+    envelopeKeysByType[eventType] = automationEnvelopeKeys(eventType)
+    if (!entity || hydratedEntities.indexOf(entity) !== -1) {
+      continue
+    }
+    const hydrator = generateAutomationHydratorCode(entity, {
+      usersTable: options.usersTable,
+      orderPagePrefix: options.orderPagePrefix,
+    })
+    if (hydrator) {
+      hydratedEntities.push(entity)
+      setFile(structure, `hydrate-${entity}`, AUTOMATION_HYDRATE_PATH, entity, hydrator)
+    }
+  }
+
+  setFile(
+    structure,
+    'registry',
+    AUTOMATIONS_PATH,
+    'registry',
+    generateAutomationRegistryCode(entries)
+  )
+  setFile(structure, 'store', AUTOMATIONS_PATH, 'store', generateAutomationStoreCode())
+  setFile(
+    structure,
+    'wait-until',
+    AUTOMATIONS_PATH,
+    'wait-until',
+    generateAutomationWaitUntilCode()
+  )
+  setFile(structure, 'event-bus', AUTOMATIONS_PATH, 'event-bus', generateAutomationEventBusCode())
+  setFile(
+    structure,
+    'dispatcher',
+    AUTOMATIONS_PATH,
+    'dispatcher',
+    generateAutomationDispatcherCode({ entityByType, envelopeKeysByType, hydratedEntities })
+  )
+  setFile(
+    structure,
+    'dispatch-route',
+    AUTOMATIONS_DISPATCH_ROUTE_PATH,
+    'dispatch',
+    generateAutomationDispatchRouteCode()
+  )
+  // Due Waits and retries resume on the site's activity: the server reads of
+  // the TeleportHQ database (and the data API, see data-api-route-generator)
+  // start the due check.
+  setFile(
+    structure,
+    'due-check',
+    AUTOMATIONS_PATH,
+    'due-check',
+    generateAutomationDueCheckCode(
+      entries.map((entry) => entry.workflowId),
+      Array.from(new Set(entries.map((entry) => entry.eventType)))
+    )
+  )
+  installAutomationActivityKicks(structure)
+  // The route verifies the editor's signed test requests (and any signed
+  // kick) with the project's cron signing keys, which the deploy fills only
+  // where the env declares them.
+  declareCronSecretEnv(structure.uidl)
+  // The mail automations send is filed under them (and the event's order).
+  enableSentEmailAttribution(structure)
+
+  // The queue is Postgres (spec §5.1): the editor offers automations only on
+  // a Postgres data source.
+  const { pg } = getDatabaseDriverDependencies('postgresql')
+  if (!structure.dependencies.pg) {
+    structure.dependencies.pg = pg
+  }
+  // Vercel's waitUntil keeps a dispatch alive after the response (wait-until.js).
+  if (!structure.dependencies[VERCEL_FUNCTIONS_DEPENDENCY.name]) {
+    structure.dependencies[VERCEL_FUNCTIONS_DEPENDENCY.name] = VERCEL_FUNCTIONS_DEPENDENCY.version
+  }
+}

package/src/automations/automations-scope.ts

@@ -0,0 +1,196 @@
+import type {
+  ProjectUIDL,
+  UIDLAutomationsDataSourceType,
+  UIDLAutomationsSettings,
+  UIDLWorkflow,
+  UIDLWorkflows,
+} from '@teleporthq/teleport-types'
+
+/**
+ * Automations: workflows started by a business event (`event-business-event
+ * { eventType }`, spec §5.2). They never run in a browser; the generated app
+ * runs them itself, off the request path, from a Postgres-backed queue:
+ *
+ * - `lib/automations/event-bus.js` records an event and kicks the queue;
+ * - `lib/automations/dispatcher.js` is the queue worker;
+ * - `lib/automations/registry.js` maps each event type to its handlers;
+ * - `lib/automations/handlers/<slug>-<id8>.js`, one per automation;
+ * - `lib/automations/hydrate/<entity>.js` reads the record an event is about;
+ * - `pages/api/automations/dispatch.js` runs the queue for the app itself;
+ * - `lib/automations/due-check.js` wakes it on the site's activity
+ *   (activity-kicks.ts).
+ *
+ * All of it is generated only when the project has at least one automation.
+ *
+ * Event types only generated routes record: `user-signed-up` and
+ * `user-deleted` (the signup and account-deletion routes, the signup node),
+ * `product-low-stock` (the data API), `waitlist-joined` and
+ * `waitlist-spot-opened` (the waitlist routes). The editor's shared event
+ * writer (teleport-gui `features/shared/builders/record-event-node.ts`, the
+ * one writer a browser can reach) refuses these types, so a row of one of
+ * them was written by the generated app itself. The `user` hydrator relies on
+ * it for `user-deleted`: the account's row is gone before the route records
+ * the event, so the snapshot the route recorded (`payload.user`, naming the
+ * event's own `entity_id`) stands in for the record. Any other event whose
+ * record is missing is refused ("No such <entity>").
+ */
+
+export const BUSINESS_EVENT_TRIGGER = 'event-business-event'
+export const WAIT_NODE_TYPE = 'general-wait'
+
+export const AUTOMATIONS_PATH = ['lib', 'automations']
+export const AUTOMATION_HANDLERS_PATH = [...AUTOMATIONS_PATH, 'handlers']
+export const AUTOMATION_HYDRATE_PATH = [...AUTOMATIONS_PATH, 'hydrate']
+export const AUTOMATIONS_DISPATCH_ROUTE_PATH = ['pages', 'api', 'automations']
+export const AUTOMATIONS_DISPATCH_URL = '/api/automations/dispatch'
+
+/** Every generated file's key in the project structure starts with this. */
+export const AUTOMATIONS_FILE_KEY_PREFIX = 'automations-'
+
+/** The queue's limits (spec §5.2). */
+export const AUTOMATION_QUEUE_LIMITS = {
+  /** Events claimed, and Waits resumed, per pass. */
+  batchSize: 20,
+  /** An event is tried at most this many times. */
+  maxAttempts: 5,
+  /** Older events are left alone. */
+  maxAgeDays: 3,
+  /**
+   * How long the dispatcher waits for one handler. A handler still running
+   * then is left running (its delivery stays `running`): it is only taken
+   * over once its claim is stale, never while it may still be at work.
+   */
+  handlerTimeoutMs: 25000,
+  /**
+   * A dispatch starts no handler after this long, and hands back the claims
+   * it did not start, so one call stays inside a serverless time limit.
+   */
+  passDeadlineMs: 50000,
+  /** A claim older than this was left by a run that died, and is taken over. */
+  staleClaimMinutes: 15,
+  /** The dispatch route's time limit on hosts that read it (Vercel). */
+  routeMaxDurationSeconds: 60,
+}
+
+/**
+ * The platform `waitUntil` the bus uses on Vercel (lib/automations/wait-until.js).
+ * 2.x is the line that still runs on Node 18.
+ */
+export const VERCEL_FUNCTIONS_DEPENDENCY = { name: '@vercel/functions', version: '^2.2.13' }
+
+/**
+ * The database the bus opens, from `uidl.automations` (the data source the
+ * editor keeps the automation tables in). Automations run only on the
+ * TeleportHQ-managed database (v1): the platform fills `TELEPORT_DB_*` for
+ * it, and the data API every event writer goes through opens it. Null for
+ * anything else: no bus is generated then.
+ */
+export const resolveAutomationsDatabase = (
+  settings: UIDLAutomationsSettings | undefined | null
+): UIDLAutomationsDataSourceType | null =>
+  settings && settings.dataSourceType === 'teleport' ? 'teleport' : null
+
+/** Why a project with automations got no bus (the stub dispatch route answers it). */
+export const AUTOMATIONS_UNAVAILABLE_REASON = 'no TeleportHQ database holds the automation tables'
+
+export const isAutomationWorkflow = (workflow: UIDLWorkflow | undefined | null): boolean =>
+  !!workflow && !!workflow.trigger && workflow.trigger.type === BUSINESS_EVENT_TRIGGER
+
+/** The event an automation reacts to; empty when the trigger names none. */
+export const automationEventType = (workflow: UIDLWorkflow): string => {
+  const eventType = workflow.trigger.config ? workflow.trigger.config.eventType : undefined
+  return typeof eventType === 'string' ? eventType.trim() : ''
+}
+
+export const collectAutomationWorkflows = (workflows?: UIDLWorkflows | null): UIDLWorkflow[] =>
+  Object.values((workflows && workflows.workflows) || {}).filter(isAutomationWorkflow)
+
+/**
+ * Whether the project gets the in-app event bus (`lib/automations/event-bus.js`):
+ * `generateAutomationFiles` writes it for the automations that name their
+ * event. The routes that record or wake business events (signup, account
+ * deletion, the data API) carry that code only then, so a project without
+ * automations keeps them byte for byte. Takes the project's workflows, or the
+ * automations `collectAutomationWorkflows` already found.
+ */
+export const hasAutomationEventBus = (
+  workflows?: UIDLWorkflows | UIDLWorkflow[] | null
+): boolean => {
+  const automations = Array.isArray(workflows)
+    ? workflows.filter(isAutomationWorkflow)
+    : collectAutomationWorkflows(workflows)
+  return automations.some((workflow) => automationEventType(workflow) !== '')
+}
+
+/**
+ * Whether the generated app has the in-app event bus: an automation that names
+ * its event (`hasAutomationEventBus`) and a database the queue runs on
+ * (`resolveAutomationsDatabase`). The one gate of every plugin whose routes
+ * record or wake business events, so those routes, `utils/app-events.js` and
+ * `lib/automations/*` always agree.
+ */
+export const hasAutomationsBus = (uidl: Pick<ProjectUIDL, 'workflows' | 'automations'>): boolean =>
+  hasAutomationEventBus(uidl.workflows) && resolveAutomationsDatabase(uidl.automations) !== null
+
+/**
+ * The envelope key of the record an event type is about — the catalog's
+ * `entity` (teleport-gui `packages/workflow-schema/src/constants/business-events.ts`),
+ * which this package cannot import. Types are named `<area>-<what happened>`,
+ * so the prefix decides, except for the two gift-card events, whose blocks
+ * differ. Null for an event without a known record (a plugin's own events):
+ * its details come from the event's payload alone.
+ */
+const ENTITY_BY_PREFIX: Array<[string, string]> = [
+  ['order-', 'order'],
+  ['subscription-', 'subscription'],
+  ['booking-', 'booking'],
+  ['invoice-', 'invoice'],
+  ['cart-', 'cart'],
+  ['product-', 'product'],
+  ['user-', 'user'],
+  ['form-', 'form'],
+  ['newsletter-', 'subscriber'],
+  ['review-', 'review'],
+  // The waitlist plugin's events (waitlist-joined, waitlist-spot-opened).
+  ['waitlist-', 'waitlist'],
+]
+
+export const automationEntityOf = (eventType: string): string | null => {
+  if (eventType === 'gift-card-issued') {
+    return 'giftCards'
+  }
+  if (eventType === 'gift-card-credited') {
+    return 'giftCard'
+  }
+  const match = ENTITY_BY_PREFIX.find(([prefix]) => eventType.startsWith(prefix))
+  return match ? match[1] : null
+}
+
+/**
+ * The envelope keys besides `event` and `actor` an event type carries — the
+ * top-level blocks of the catalog's details: the entity, plus what some types
+ * add (a refund, a parcel, the status it moved from). Null for an event the
+ * catalog does not describe (a plugin's own): its payload is kept whole.
+ */
+const EXTRA_ENVELOPE_KEYS: Record<string, string[]> = {
+  'order-awaiting-confirmation': ['payment'],
+  'order-late-payment': ['payment'],
+  'order-duplicate-payment': ['payment'],
+  'order-underpaid': ['payment'],
+  'order-refunded': ['refund'],
+  'order-partially-refunded': ['refund'],
+  'order-refund-failed': ['refund'],
+  'order-status-changed': ['from', 'to'],
+  'order-shipment-created': ['shipment'],
+  'order-shipment-updated': ['shipment'],
+  'order-shipment-delivered': ['shipment'],
+  'order-digital-delivered': ['delivery'],
+  'gift-card-issued': ['order'],
+  'gift-card-credited': ['order'],
+  'booking-moved': ['from'],
+}
+
+export const automationEnvelopeKeys = (eventType: string): string[] | null => {
+  const entity = automationEntityOf(eventType)
+  return entity ? [entity, ...(EXTRA_ENVELOPE_KEYS[eventType] || [])] : null
+}