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

package/src/lib/plugin-manager/repeat-rows.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/plugin-manager/repeat-rows.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 type { RepeatableDataset } from '../app-utils/expand-repeatables'\nimport { getRegisteringPluginId } from '../app-utils/registering-plugin'\nimport { PLUGIN_REPEAT_SOURCE_DECLARED } from './first-party-plugins.generated'\nimport { runPluginDeclarationsRepair } from './plugin-declarations-repair'\n\n/**\n * WHERE A PUBLISHED PAGE'S REPEATED ROWS COME FROM (AGL-3080).\n *\n * Any element can repeat, and the platform decides what a repeat MEANS — the\n * scope, the copies, the filter, the bound (`expand-repeatables.ts`). What it\n * does not decide is where the rows live. That is the plugin's that keeps\n * them, and the composition that renders a published page asks it here, with\n * the keys the page's tree repeats over, and never reads a collection itself.\n *\n * `repeat-sources.ts` is the editor's side of the same line: a hook the\n * besigner's canvas mounts to preview the rows. This is the server's side,\n * read once per compose, and it is a different registry because its readers\n * are different processes with different failure costs.\n *\n * ## Declared, then registered — and an absent reader is refused\n *\n * The reader is registered from the owning plugin's `serverDeclarations`\n * entry, which every app runs at boot, so every process that composes a page\n * has it before the first request. But a registry is only safe where an empty\n * one cannot be mistaken for an answer, and here it can: a page whose repeat\n * found no reader would render the template once where the author put a list,\n * and nothing anywhere would be red. That is the AGL-3025 shape on the most\n * public surface the product has.\n *\n * So the plugin that answers also DECLARES that it does, in\n * `plugins.config.json` (`repeatSource`), and the generator compiles that into\n * core. The two together tell the one case that is a real answer from the one\n * that is a broken boot:\n *\n * - nothing declared — this deployment ships no plugin that keeps rows, and a\n *   repeat renders its element once, as written, exactly as a key naming\n *   nothing does;\n * - declared and registered — the reader answers;\n * - declared and NOT registered — the boot failed. The app's declarations\n *   step is run again ({@link runPluginDeclarationsRepair}); if the reader is\n *   still missing, {@link readRepeatRows} THROWS. A render that throws keeps\n *   the page it last rendered in the cache and is loud in the logs, which is\n *   the right way round for a page that would otherwise go out wrong.\n *\n * Per-key failures are the reader's to absorb, as they always were: a deleted\n * or unreadable entry leaves its element rendering once and costs the page\n * nothing else.\n *\n * Reached by path, never through a barrel: only the server composition asks.\n */\n\n/** One composition's question: the keys a page's tree repeats over. */\nexport interface RepeatRowsRequest {\n  /** The site being rendered. A reader answers only what that site may see. */\n  hostId: string\n  /**\n   * The keys exactly as the nodes store them (`repeatKeys`), trimmed,\n   * sorted and without repeats.\n   */\n  keys: readonly string[]\n}\n\n/**\n * The rows for a request, under every key the expansion looks them up by: the\n * key as the node stores it, the entry's own id, and each entry a one-hop\n * reference in the rows reads. A key with nothing to render is absent.\n */\nexport type RepeatRowsAnswer = Record<string, RepeatableDataset>\n\n/** Answers one composition's request. Never rejects for a single bad key. */\nexport type RepeatRowReader = (\n  request: RepeatRowsRequest,\n) => Promise<RepeatRowsAnswer>\n\n/** The compiled declaration: which plugin answers, under which source id. */\nexport interface RepeatSourceDeclaration {\n  pluginId: string\n  /** The same id the plugin's editor source (`repeat-sources.ts`) uses. */\n  id: string\n}\n\n/** The plugin declared to answer repeats, or `null` when none is. */\nexport function declaredRepeatSource(): RepeatSourceDeclaration | null {\n  return PLUGIN_REPEAT_SOURCE_DECLARED\n}\n\ninterface RegisteredReader {\n  pluginId: string\n  reader: RepeatRowReader\n}\n\n/**\n * One table per process, on `globalThis` (AGL-3412): the app registers from\n * `instrumentation.ts`, which Next compiles apart from the routes that read,\n * and a module-scoped map would be filled in one copy and read empty in the\n * other — the exact failure this module exists to refuse.\n */\nconst READERS_KEY = Symbol.for('@aglyn/aglyn:repeat-row-readers')\n\nconst globalScope = globalThis as typeof globalThis & {\n  [READERS_KEY]?: Map<string, RegisteredReader>\n}\n\nconst readers: Map<string, RegisteredReader> =\n  globalScope[READERS_KEY] ?? (globalScope[READERS_KEY] = new Map())\n\n/**\n * Registers the reader for a source. Returns the unregister, which removes it\n * only while it is still the one registered.\n *\n * The owner is the plugin whose register fn is running, or the `pluginId`\n * passed for a boot declaration, where the loader's marker is not set. A\n * registration with neither is refused, and so is one from a plugin other\n * than the one the declaration names — two readers for one source would each\n * answer for the other's rows. The same plugin registering again replaces its\n * reader (a second surface, a repeated boot).\n */\nexport function registerRepeatRowReader(\n  sourceId: string,\n  reader: RepeatRowReader,\n  options?: { pluginId?: string },\n): () => void {\n  const id = sourceId.trim()\n  const pluginId = (getRegisteringPluginId() ?? options?.pluginId ?? '').trim()\n  if (!id) throw new Error('a repeat row reader needs a source id')\n  if (!pluginId) {\n    throw new Error(\n      `repeat row reader \"${id}\" registered with no owner: pass { pluginId } ` +\n        'when registering outside a plugin register fn',\n    )\n  }\n  const declared = declaredRepeatSource()\n  if (declared?.id === id && declared.pluginId !== pluginId) {\n    throw new Error(\n      `repeat source \"${id}\" is declared by \"${declared.pluginId}\"; ` +\n        `refused a reader from \"${pluginId}\"`,\n    )\n  }\n  const held = readers.get(id)\n  if (held && held.pluginId !== pluginId) {\n    throw new Error(\n      `repeat source \"${id}\" already has a reader from \"${held.pluginId}\"; ` +\n        `refused \"${pluginId}\"`,\n    )\n  }\n  const entry: RegisteredReader = { pluginId, reader }\n  readers.set(id, entry)\n  return () => {\n    if (readers.get(id) === entry) readers.delete(id)\n  }\n}\n\n/** The reader registered for a source, with its owner, or `null`. */\nexport function repeatRowReader(sourceId: string): RegisteredReader | null {\n  return readers.get(sourceId) ?? null\n}\n\n/** Only for specs: forgets every registered reader. */\nexport function resetRepeatRowReadersForTests(): void {\n  readers.clear()\n}\n\n/**\n * The declared source's reader was not registered, even after the app's\n * declarations step ran again. Thrown, never answered: see the module note.\n */\nexport class RepeatRowsUnavailableError extends Error {\n  constructor(readonly source: RepeatSourceDeclaration) {\n    super(\n      `repeat source \"${source.id}\" is declared by \"${source.pluginId}\" but ` +\n        'no reader is registered in this process — its server declarations ' +\n        'did not run. Refusing to render repeats as if they had no rows.',\n    )\n    this.name = 'RepeatRowsUnavailableError'\n  }\n}\n\n/**\n * The rows a composition's repeats render. See the module note for what each\n * of the three cases answers; with no keys it answers `{}` and asks nobody.\n */\nexport async function readRepeatRows(\n  request: RepeatRowsRequest,\n): Promise<RepeatRowsAnswer> {\n  const keys = [\n    ...new Set(request.keys.map((key) => key.trim()).filter(Boolean)),\n  ].sort()\n  if (!keys.length) return {}\n  const declared = declaredRepeatSource()\n  if (!declared) return {}\n  let registered = readers.get(declared.id)\n  if (!registered) {\n    try {\n      await runPluginDeclarationsRepair()\n    } catch (error) {\n      console.error('[repeat-rows] the declarations repair failed', error)\n    }\n    registered = readers.get(declared.id)\n  }\n  if (!registered) throw new RepeatRowsUnavailableError(declared)\n  return registered.reader({ hostId: request.hostId, keys })\n}\n"],"names":["globalScope","getRegisteringPluginId","PLUGIN_REPEAT_SOURCE_DECLARED","runPluginDeclarationsRepair","declaredRepeatSource","READERS_KEY","Symbol","for","globalThis","readers","Map","registerRepeatRowReader","sourceId","reader","options","id","trim","pluginId","Error","declared","held","get","entry","set","delete","repeatRowReader","resetRepeatRowReadersForTests","clear","RepeatRowsUnavailableError","source","name","readRepeatRows","request","keys","Set","map","key","filter","Boolean","sort","length","registered","error","console","hostId"],"mappings":"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"}
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/plugin-manager/repeat-rows.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 type { RepeatableDataset } from '../app-utils/expand-repeatables'\nimport { getRegisteringPluginId } from '../app-utils/registering-plugin'\nimport { PLUGIN_REPEAT_SOURCE_DECLARED } from './first-party-plugins.generated'\nimport { runPluginDeclarationsRepair } from './plugin-declarations-repair'\n\n/**\n * WHERE A PUBLISHED PAGE'S REPEATED ROWS COME FROM (AGL-3080).\n *\n * Any element can repeat, and the platform decides what a repeat MEANS — the\n * scope, the copies, the filter, the bound (`expand-repeatables.ts`). What it\n * does not decide is where the rows live. That is the plugin's that keeps\n * them, and the composition that renders a published page asks it here, with\n * the keys the page's tree repeats over, and never reads a collection itself.\n *\n * `repeat-sources.ts` is the editor's side of the same line: a hook the\n * besigner's canvas mounts to preview the rows. This is the server's side,\n * read once per compose, and it is a different registry because its readers\n * are different processes with different failure costs.\n *\n * ## Declared, then registered — and an absent reader is refused\n *\n * The reader is registered from the owning plugin's `serverDeclarations`\n * entry, which every app runs at boot, so every process that composes a page\n * has it before the first request. But a registry is only safe where an empty\n * one cannot be mistaken for an answer, and here it can: a page whose repeat\n * found no reader would render no copies where the author put a list, and\n * nothing anywhere would be red. That is the AGL-3025 shape on the most\n * public surface the product has.\n *\n * So the plugin that answers also DECLARES that it does, in\n * `plugins.config.json` (`repeatSource`), and the generator compiles that into\n * core. The two together tell the one case that is a real answer from the one\n * that is a broken boot:\n *\n * - nothing declared — this deployment ships no plugin that keeps rows, and a\n *   repeat renders no copies, exactly as a key naming nothing does (AGL-3496);\n * - declared and registered — the reader answers;\n * - declared and NOT registered — the boot failed. The app's declarations\n *   step is run again ({@link runPluginDeclarationsRepair}); if the reader is\n *   still missing, {@link readRepeatRows} THROWS. A render that throws keeps\n *   the page it last rendered in the cache and is loud in the logs, which is\n *   the right way round for a page that would otherwise go out wrong.\n *\n * Per-key failures are the reader's to absorb, as they always were: a deleted\n * or unreadable entry renders no copies of its element (AGL-3496) — never its\n * raw `{{item.*}}` template — and costs the page nothing else.\n *\n * Reached by path, never through a barrel: only the server composition asks.\n */\n\n/** One composition's question: the keys a page's tree repeats over. */\nexport interface RepeatRowsRequest {\n  /** The site being rendered. A reader answers only what that site may see. */\n  hostId: string\n  /**\n   * The keys exactly as the nodes store them (`repeatKeys`), trimmed,\n   * sorted and without repeats.\n   */\n  keys: readonly string[]\n}\n\n/**\n * The rows for a request, under every key the expansion looks them up by: the\n * key as the node stores it, the entry's own id, and each entry a one-hop\n * reference in the rows reads. A key with nothing to render is absent.\n */\nexport type RepeatRowsAnswer = Record<string, RepeatableDataset>\n\n/** Answers one composition's request. Never rejects for a single bad key. */\nexport type RepeatRowReader = (\n  request: RepeatRowsRequest,\n) => Promise<RepeatRowsAnswer>\n\n/** The compiled declaration: which plugin answers, under which source id. */\nexport interface RepeatSourceDeclaration {\n  pluginId: string\n  /** The same id the plugin's editor source (`repeat-sources.ts`) uses. */\n  id: string\n}\n\n/** The plugin declared to answer repeats, or `null` when none is. */\nexport function declaredRepeatSource(): RepeatSourceDeclaration | null {\n  return PLUGIN_REPEAT_SOURCE_DECLARED\n}\n\ninterface RegisteredReader {\n  pluginId: string\n  reader: RepeatRowReader\n}\n\n/**\n * One table per process, on `globalThis` (AGL-3412): the app registers from\n * `instrumentation.ts`, which Next compiles apart from the routes that read,\n * and a module-scoped map would be filled in one copy and read empty in the\n * other — the exact failure this module exists to refuse.\n */\nconst READERS_KEY = Symbol.for('@aglyn/aglyn:repeat-row-readers')\n\nconst globalScope = globalThis as typeof globalThis & {\n  [READERS_KEY]?: Map<string, RegisteredReader>\n}\n\nconst readers: Map<string, RegisteredReader> =\n  globalScope[READERS_KEY] ?? (globalScope[READERS_KEY] = new Map())\n\n/**\n * Registers the reader for a source. Returns the unregister, which removes it\n * only while it is still the one registered.\n *\n * The owner is the plugin whose register fn is running, or the `pluginId`\n * passed for a boot declaration, where the loader's marker is not set. A\n * registration with neither is refused, and so is one from a plugin other\n * than the one the declaration names — two readers for one source would each\n * answer for the other's rows. The same plugin registering again replaces its\n * reader (a second surface, a repeated boot).\n */\nexport function registerRepeatRowReader(\n  sourceId: string,\n  reader: RepeatRowReader,\n  options?: { pluginId?: string },\n): () => void {\n  const id = sourceId.trim()\n  const pluginId = (getRegisteringPluginId() ?? options?.pluginId ?? '').trim()\n  if (!id) throw new Error('a repeat row reader needs a source id')\n  if (!pluginId) {\n    throw new Error(\n      `repeat row reader \"${id}\" registered with no owner: pass { pluginId } ` +\n        'when registering outside a plugin register fn',\n    )\n  }\n  const declared = declaredRepeatSource()\n  if (declared?.id === id && declared.pluginId !== pluginId) {\n    throw new Error(\n      `repeat source \"${id}\" is declared by \"${declared.pluginId}\"; ` +\n        `refused a reader from \"${pluginId}\"`,\n    )\n  }\n  const held = readers.get(id)\n  if (held && held.pluginId !== pluginId) {\n    throw new Error(\n      `repeat source \"${id}\" already has a reader from \"${held.pluginId}\"; ` +\n        `refused \"${pluginId}\"`,\n    )\n  }\n  const entry: RegisteredReader = { pluginId, reader }\n  readers.set(id, entry)\n  return () => {\n    if (readers.get(id) === entry) readers.delete(id)\n  }\n}\n\n/** The reader registered for a source, with its owner, or `null`. */\nexport function repeatRowReader(sourceId: string): RegisteredReader | null {\n  return readers.get(sourceId) ?? null\n}\n\n/** Only for specs: forgets every registered reader. */\nexport function resetRepeatRowReadersForTests(): void {\n  readers.clear()\n}\n\n/**\n * The declared source's reader was not registered, even after the app's\n * declarations step ran again. Thrown, never answered: see the module note.\n */\nexport class RepeatRowsUnavailableError extends Error {\n  constructor(readonly source: RepeatSourceDeclaration) {\n    super(\n      `repeat source \"${source.id}\" is declared by \"${source.pluginId}\" but ` +\n        'no reader is registered in this process — its server declarations ' +\n        'did not run. Refusing to render repeats as if they had no rows.',\n    )\n    this.name = 'RepeatRowsUnavailableError'\n  }\n}\n\n/**\n * The rows a composition's repeats render. See the module note for what each\n * of the three cases answers; with no keys it answers `{}` and asks nobody.\n */\nexport async function readRepeatRows(\n  request: RepeatRowsRequest,\n): Promise<RepeatRowsAnswer> {\n  const keys = [\n    ...new Set(request.keys.map((key) => key.trim()).filter(Boolean)),\n  ].sort()\n  if (!keys.length) return {}\n  const declared = declaredRepeatSource()\n  if (!declared) return {}\n  let registered = readers.get(declared.id)\n  if (!registered) {\n    try {\n      await runPluginDeclarationsRepair()\n    } catch (error) {\n      console.error('[repeat-rows] the declarations repair failed', error)\n    }\n    registered = readers.get(declared.id)\n  }\n  if (!registered) throw new RepeatRowsUnavailableError(declared)\n  return registered.reader({ hostId: request.hostId, keys })\n}\n"],"names":["globalScope","getRegisteringPluginId","PLUGIN_REPEAT_SOURCE_DECLARED","runPluginDeclarationsRepair","declaredRepeatSource","READERS_KEY","Symbol","for","globalThis","readers","Map","registerRepeatRowReader","sourceId","reader","options","id","trim","pluginId","Error","declared","held","get","entry","set","delete","repeatRowReader","resetRepeatRowReadersForTests","clear","RepeatRowsUnavailableError","source","name","readRepeatRows","request","keys","Set","map","key","filter","Boolean","sort","length","registered","error","console","hostId"],"mappings":"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"}

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

@@ -1,310 +0,0 @@
-/**
- * @license
- * Copyright 2026 Aglyn LLC
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *   http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-import { type ContactLifecycleStage, type CrmActivityKind, type CrmTaskKind } from './crm-kinds';
-import { type ClientInteractionStep, type InteractionCondition, type InteractionStepGuard, type InteractionTrigger, type SiteAlert, type SiteInteraction, type TriggerCombinator } from './site-interactions';
-/**
- * Actions builder (AGL-148): HubSpot-style event → action automation on
- * top of the AGL-128 event triggers. An action listens for a host event
- * (built-in or a custom name fired by another action), optionally filters
- * on the payload, and runs an ordered step list. Pure types + validation
- * here; the executor lives in the workflows plugin, where the I/O is.
- *
- * An action is a SITE INTERACTION (`site-interactions.ts`) with server steps
- * added: its trigger, its conditions, its client steps and its storage are
- * the platform's, and are re-exported here for the readers that take both
- * from this module. What is declared below is the automation's own — the
- * server steps, flows, recipes and webhooks.
- */
-export * from './site-interactions';
-/** 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.
- */
-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;
-    kind: CrmTaskKind;
-    /** Days from the run to the due date; `0` is due today. */
-    dueInDays: number;
-    /**
-     * Who gets it — by uid or by an address, both resolved against the
-     * roster the way the owner step's are. Neither named, the task goes
-     * to the contact's owner, then to nobody.
-     */
-    assigneeUid?: string;
-    assigneeEmail?: string;
-} | {
-    type: 'logCrmActivity';
-    kind: CrmActivityKind;
-    body: string;
-}) & {
-    /** See {@link 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.
- */
-export declare const FLOW_SUSPENDING_STEP_TYPES: ReadonlySet<HostActionStepType>;
-export declare function isFlowSuspendingStep(step: HostActionStep): boolean;
-/** Longest tag an automation may write — the console's own tag field cap. */
-export declare const CONTACT_TAG_MAX_LENGTH = 60;
-export declare const CRM_ACTION_RECIPE_IDS: readonly ["welcomeNewLead", "followUpWonDeal", "reengageStaleLead", "tagByForm"];
-export type CrmActionRecipeId = (typeof CRM_ACTION_RECIPE_IDS)[number];
-/** What a recipe is handed before it builds — today only the form `tagByForm` reads. */
-export interface CrmActionRecipeInput {
-    form?: {
-        id: string;
-        name: string;
-    };
-}
-export interface CrmActionRecipe {
-    id: CrmActionRecipeId;
-    /** How the recipe reads in the menu; also the action's starting name. */
-    title: string;
-    /** One sentence under the title. */
-    description: string;
-    /**
-     * What must be picked before the recipe can be built. A recipe that needs
-     * nothing opens the editor at once; one that needs a form opens a picker
-     * first. Built WITHOUT its pick, such a recipe yields an action the
-     * validator refuses — a condition with no value — rather than one that
-     * saves and then silently matches nothing.
-     */
-    needs?: 'form';
-    /**
-     * A fresh action each call, because the draft is edited in place. The
-     * action carries `recipe: id` — the provenance is the builder's to stamp,
-     * so a writer that saves what it was handed cannot forget it.
-     */
-    build: (input?: CrmActionRecipeInput) => HostAction;
-}
-/**
- * How long the stale-lead recipe holds before it decides a lead has gone
- * quiet. A week: long enough that a rep who is working the lead has had a
- * chance to move its stage, short enough that a lead nobody touched is
- * still warm when the reminder lands.
- */
-export declare const STALE_LEAD_WAIT_MINUTES: number;
-/**
- * The tag a form's captures get: the form's own name, cut to the tag cap.
- * The name is what the person calls the form, so it is the tag they would
- * have typed; the editor is open to change it before anything is saved.
- */
-export declare function crmRecipeTagForForm(formName: string): string;
-export declare const CRM_ACTION_RECIPES: readonly CrmActionRecipe[];
-/** The recipe with this id, or null for a string that names none. */
-export declare function crmActionRecipe(id: unknown): CrmActionRecipe | null;
-/**
- * The recipe a STORED action came from, read off its document (AGL-2639).
- *
- * Three answers, and the third is the one that matters. A known id: the
- * action was installed from, or begun as, that recipe. `null`: the action
- * was begun blank, or from a recipe this build no longer knows — the
- * editor wrote the field and said "no recipe". `undefined`: the document
- * carries no `recipe` field at all, which is every action saved before the
- * stamp existed. Such an action may well have started from a recipe — the
- * menu opened the editor prefilled long before anything recorded it — so a
- * reader that needs to know whether a site has a recipe treats `undefined`
- * as UNKNOWN, never as absent, and never writes a `null` over it.
- */
-export declare function hostActionRecipeId(action: {
-    recipe?: unknown;
-} | null | undefined): CrmActionRecipeId | null | undefined;
-/**
- * A HostAction as the document at `hosts/{hostId}/actions/{id}` holds it.
- *
- * Every optional trigger key is written OUT — a boolean cap as `false`, a
- * cleared list as `null` — because the editor saves with a merge-set, and
- * a merge keeps whatever key the payload omits: a frequency cap switched
- * off, left out of the payload, would stay on. The legacy single
- * `condition` is always nulled; `conditions` has been canonical since the
- * list shape arrived and a document that carried both would have the
- * reader pick. Everything else is the action, unchanged.
- *
- * `recipe` rides along only when the action SAYS something about it: an
- * id or `null`. An action that carries no stamp (an older document, edited
- * and saved again) keeps carrying none — see {@link hostActionRecipeId}
- * for why an absent stamp must not become a `null` one.
- */
-export interface HostActionDocument extends HostAction {
-    trigger: HostActionTrigger & {
-        oncePerVisitor: boolean;
-        oncePerSession: boolean;
-        cooldownMinutes: number | null;
-        everyTime: boolean;
-        condition: null;
-        conditions: HostActionTriggerCondition[] | null;
-        combinator: TriggerCombinator | null;
-    };
-    enabled: boolean;
-}
-export declare function hostActionDocument(action: HostAction): HostActionDocument;
-/**
- * The step list as the visitor's browser may see it.
- *
- * A client step AFTER a wait must never reach the page. The client engine
- * runs its slice of the list immediately, so shipping the whole list would
- * make "wait three days, then show the popup" show the popup at once — the
- * delay would appear to work on the server, be ignored in the browser, and
- * the two halves of one authored flow would disagree about when it happened.
- *
- * Truncating rather than filtering: everything past the first wait belongs to
- * a run that has not happened yet, whichever side would have executed it.
- */
-export declare function hostActionStepsForClient(steps: readonly HostActionStep[] | undefined | null): HostActionStep[];
-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 interface HostAction extends SiteInteraction<HostActionStep> {
-    /**
-     * The recipe this action was installed from or begun as (AGL-2639), or
-     * `null` for one begun blank. Absent on a document from before the stamp
-     * existed — read it through {@link hostActionRecipeId}, which keeps the
-     * three cases apart.
-     */
-    recipe?: CrmActionRecipeId | null;
-}
-/**
- * The shortest and longest a flow may wait.
- *
- * The floor is a minute because the resume beat runs on a minute, so anything
- * under one is a delay the scheduler cannot honor and would only read as
- * imprecision. The ceiling is ninety days: long enough for the win-back that
- * is the longest sequence anybody writes, and short enough that an enrollment
- * is not an unbounded lease on a document. A person waiting inside a flow is
- * storage the merchant is not looking at, and a wait measured in years is
- * indistinguishable from one nobody will ever collect.
- */
-export declare const FLOW_WAIT_MIN_MINUTES = 1;
-export declare const FLOW_WAIT_MAX_MINUTES: number;
-export declare const HOST_ACTION_STEP_LABELS: 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;
-/** The most webhooks one site keeps; the site create route enforces it. */
-export declare const WEBHOOK_MAX_PER_HOST = 5;