@hostwebhook/node-types 1.69.0 → 1.70.0

package/dist/esm/telegram-toolkit.js

@@ -0,0 +1,183 @@
+/**
+ * Telegram AI Toolkit — las herramientas que un telegramAction expone cuando
+ * `aiEnabled` está encendido.
+ *
+ * **Se escribe una sola vez**, como el de Sheets. Antes vivía dos veces: una
+ * copia en `dashboard/components/telegram-actions/telegram-operations-schemas.ts`
+ * y otra en `api/src/mcp-servers/toolkit-specs.ts`, las dos a mano, las dos con
+ * el mismo TODO escrito pidiendo justo esto. Y ya habían derivado: el
+ * `messageId` de `reply_telegram_message` era `number` en el dashboard y
+ * `string` en la api, mientras en las otras tres ops que lo llevan era `number`
+ * en las dos. Aquí es `number` y punto.
+ *
+ * Hay una TERCERA copia que también desaparece: la página de detalle pintaba la
+ * lista de las diez herramientas como diez `<li>` escritos a mano. Ahora sale de
+ * aquí, contada con `.length`, que es lo que evita que un día anuncie diez y
+ * exponga otra cosa.
+ *
+ * La forma es la que ya consume `toolkitSpecToMcpTool` en la api, para que pueda
+ * usarse sin adaptador. Los textos van en inglés porque los lee el modelo y
+ * quien mire la lista de herramientas del servidor MCP.
+ */
+const p = (name, description, required = true, type = 'string') => ({ name, type, description, required });
+/*
+ * `sendAndWaitForResponse` NO está aquí, y es una decisión, no un olvido: la op
+ * para el pipeline durante minutos u horas esperando que alguien pulse un botón,
+ * y por la vía de una herramienta no espera — el modelo recibe algo inmediato y
+ * acaba diciendo que ya se aprobó. Se usa en modo single-op, con un Conditional
+ * detrás leyendo `_waitResponse.approved`. La espera se resuelve por
+ * `triggers.processTelegramPush`, donde el LLM no participa.
+ *
+ * Ninguna lleva `destructive`. `delete_telegram_message` lo merecería —el
+ * toolkit de Drive marca sus borrados— pero hoy la spec de Telegram no tiene ese
+ * campo en ninguna de las dos capas, y añadirlo cambiaría cuándo el AI Node pide
+ * confirmación. Eso es otra decisión, no parte de mudar el esquema de sitio.
+ */
+export const TELEGRAM_TOOLKIT_SPECS = [
+    {
+        operation: 'sendMessage',
+        label: 'Send message',
+        toolName: 'send_telegram_message',
+        group: 'Sending',
+        description: 'Send a text message via the Telegram bot to a chat. Use for replies, notifications, status updates, or any text-only delivery. ' +
+            'Supports HTML formatting (default parse mode). For inline buttons, supply the replyMarkup arg as a 2D array of buttons. ' +
+            'USAGE RULES: ' +
+            '(1) chatId is REQUIRED — when replying inside a flow triggered by a Telegram message, this is normally `{{payload.chatId}}` from the trigger payload. ' +
+            '(2) Telegram caps text at 4096 chars. Split longer messages or use sendDocument with a text file. ' +
+            '(3) For a quote-style reply that points at a SPECIFIC user message, prefer `reply_telegram_message` so Telegram renders the threaded indicator — this op sends a standalone message.',
+        parameters: [
+            p('chatId', 'Target chat id (number) or @channelusername (string).'),
+            p('text', 'Message text. HTML by default — escape <, >, & in user content.'),
+            p('parseMode', 'Optional. "HTML" (default), "MarkdownV2", or "none".', false),
+            p('replyToMessageId', 'Optional. Reply to a specific message id.', false),
+        ],
+    },
+    {
+        operation: 'replyToMessage',
+        label: 'Reply to message',
+        toolName: 'reply_telegram_message',
+        group: 'Sending',
+        description: 'Reply to a SPECIFIC user message with the quote indicator visible. Telegram renders the bot\'s reply with a small "replying to..." card above it pointing back at the quoted message. ' +
+            'USAGE RULES: ' +
+            '(1) Use this in group chats where multiple users post in parallel — the indicator makes it clear which user the bot is answering. In 1:1 DMs only use it when context disambiguates between several recent questions. ' +
+            '(2) messageId is REQUIRED — pass the id of the user\'s message you\'re responding to (typically `{{payload.message.message_id}}` or `{{payload.message_id}}` from the trigger). ' +
+            '(3) chatId is REQUIRED and must match the chat the original message lives in. ' +
+            '(4) Same Telegram /sendMessage webhook underneath — text limit (4096 chars) and parse modes (HTML / MarkdownV2 / none) work the same.',
+        parameters: [
+            p('chatId', 'Target chat id (number) or @channelusername — must match the chat of the quoted message.'),
+            // `number`, como en las otras tres ops que llevan messageId. La api lo
+            // declaraba `string` por un cuarto argumento que se quedó sin escribir.
+            p('messageId', 'Numeric id of the message to quote-reply to. Telegram renders the threaded indicator from this.', true, 'number'),
+            p('text', 'Reply text. HTML by default.'),
+            p('parseMode', 'Optional. "HTML" (default), "MarkdownV2", or "none".', false),
+        ],
+    },
+    {
+        operation: 'sendPhoto',
+        label: 'Send photo',
+        toolName: 'send_telegram_photo',
+        group: 'Sending',
+        description: 'Send a photo to a chat. The photo arg accepts a public URL (Telegram fetches it) or a Telegram file_id from a previously-sent photo (cheap re-send). ' +
+            'For HW-stored files use the `_file.downloadUrl` template. Max 10MB photo size when fetching by URL. Caption is optional and supports HTML.',
+        parameters: [
+            p('chatId', 'Target chat id or @channelusername.'),
+            p('photo', "Public URL OR file_id from a prior send. URLs must be reachable from Telegram's servers."),
+            p('caption', 'Optional caption (max 1024 chars, HTML supported).', false),
+            p('parseMode', 'Optional caption parse mode: HTML / MarkdownV2 / none.', false),
+        ],
+    },
+    {
+        operation: 'sendDocument',
+        label: 'Send document',
+        toolName: 'send_telegram_document',
+        group: 'Sending',
+        description: 'Send a document (any file type) to a chat. Same URL-or-file_id contract as sendPhoto. Max 50MB when Telegram fetches by URL.',
+        parameters: [
+            p('chatId', 'Target chat id or @channelusername.'),
+            p('document', 'Public URL OR file_id.'),
+            p('caption', 'Optional caption (HTML supported).', false),
+            p('parseMode', 'Optional caption parse mode.', false),
+        ],
+    },
+    {
+        operation: 'sendVoice',
+        label: 'Send voice',
+        toolName: 'send_telegram_voice',
+        group: 'Sending',
+        description: 'Send a voice message — Telegram renders it as a voice bubble with waveform. ' +
+            'USAGE RULES: ' +
+            '(1) chatId is REQUIRED — usually `{{payload.chatId}}` from the trigger. ' +
+            '(2) voice is REQUIRED — pass an OGG/OPUS audio URL Telegram can fetch, OR a `file_id` from a prior /sendVoice for cheap re-sends. ' +
+            '(3) To synthesize from text, FIRST call the `synthesize_voice` tool — it returns a JSON `_file` ref; pass its `downloadUrl` string here as `voice`. NEVER pass the raw `_file` object; Telegram needs a string. ' +
+            '(4) Use this when the user sent voice and wants voice back, or when the operator framed the bot as voice-first. For text replies prefer send_telegram_message.',
+        parameters: [
+            p('chatId', 'Target chat id (number) or @channelusername.'),
+            p('voice', 'OGG/OPUS audio URL or Telegram file_id. Use the `downloadUrl` returned by synthesize_voice when chaining from text.'),
+        ],
+    },
+    {
+        operation: 'sendPoll',
+        label: 'Send poll',
+        toolName: 'send_telegram_poll',
+        group: 'Sending',
+        description: 'Send a poll to a chat. The options arg is an array of strings (2-10 options). For quiz-style polls (single correct answer), pass type="quiz" and a numeric correctOptionId. Polls require group/supergroup/channel chats — DMs reject them.',
+        parameters: [
+            p('chatId', 'Target chat id.'),
+            p('question', 'Poll question (max 300 chars).'),
+            p('options', 'Array of 2-10 answer strings. Pass as a JSON array: ["Option A","Option B"]. Each option max 100 chars.'),
+            p('isAnonymous', 'Optional. Default true. Set false to expose voter identities.', false, 'boolean'),
+            p('type', 'Optional. "regular" (default) or "quiz".', false),
+            p('correctOptionId', 'Required when type="quiz" — zero-indexed correct answer.', false, 'number'),
+        ],
+    },
+    {
+        operation: 'forwardMessage',
+        label: 'Forward message',
+        toolName: 'forward_telegram_message',
+        group: 'Sending',
+        description: 'Forward an existing message from one chat to another. Preserves the original sender attribution. Use for announcements, escalations, or copying a message between groups the bot is in.',
+        parameters: [
+            p('chatId', 'Destination chat id.'),
+            p('fromChatId', 'Source chat id.'),
+            p('messageId', 'Source message id.', true, 'number'),
+        ],
+    },
+    {
+        operation: 'editMessageText',
+        label: 'Edit message text',
+        toolName: 'edit_telegram_message',
+        group: 'Modify / acknowledge',
+        description: 'Replace the text of a previously-sent message. Use for progress updates, fixing typos, removing inline buttons after a press. The bot can only edit messages it sent within the last 48h.',
+        parameters: [
+            p('chatId', 'Chat id of the message.'),
+            p('messageId', 'Message id to edit (returned from a prior sendMessage).', true, 'number'),
+            p('text', 'New text for the message.'),
+            p('parseMode', 'Optional parse mode.', false),
+        ],
+    },
+    {
+        operation: 'deleteMessage',
+        label: 'Delete message',
+        toolName: 'delete_telegram_message',
+        group: 'Modify / acknowledge',
+        description: 'Delete a message. Bots can delete their own messages anytime; messages by users only when the bot has Delete Messages admin permission in that chat. Within 48h for bot-own messages in private chats.',
+        parameters: [
+            p('chatId', 'Chat id where the message lives.'),
+            p('messageId', 'Message id to delete.', true, 'number'),
+        ],
+    },
+    {
+        operation: 'answerCallbackQuery',
+        label: 'Answer callback query',
+        toolName: 'answer_telegram_callback',
+        group: 'Modify / acknowledge',
+        description: 'REQUIRED after a callback_query trigger fires (an inline-keyboard button press) — without this, the user sees a forever-spinner on the button. The text optionally shows as a toast or alert above the chat.',
+        parameters: [
+            p('callbackQueryId', 'The callback_query.id from the trigger payload — usually `{{payload.callbackQueryId}}`.'),
+            p('text', 'Optional toast/alert text shown to the user (max 200 chars).', false),
+            p('showAlert', 'Optional. true = modal alert; false (default) = toast notification.', false, 'boolean'),
+        ],
+    },
+];
+/** Las herramientas por nombre, para despachar una llamada del modelo. */
+export const TELEGRAM_TOOLKIT_BY_TOOL_NAME = Object.fromEntries(TELEGRAM_TOOLKIT_SPECS.map((s) => [s.toolName, s]));

package/dist/esm/types.d.ts

@@ -0,0 +1,149 @@
+/** All valid node type identifiers */
+export type NodeType = 'webhook' | 'scheduledWorkflow' | 'chatTrigger' | 'trigger' | 'voiceAgent' | 'filter' | 'transform' | 'schemaValidator' | 'conditional' | 'delay' | 'rateLimiter' | 'aggregator' | 'cache' | 'code' | 'ai' | 'merge' | 'approval' | 'split' | 'loop' | 'markdown' | 'fileTransform' | 'limit' | 'router' | 'emailAction' | 'gmailAction' | 'httpAction' | 'mongoAction' | 'postgresAction' | 'notificationAction' | 'sheetsAction' | 'calendarAction' | 'docsAction' | 'driveAction' | 'firecrawlAction' | 'telegramAction' | 'whatsappAction' | 'discordAction' | 'slackAction' | 'googleContactsAction' | 'googleAnalyticsAction' | 'notionAction' | 'vectorStore' | 'rssAction' | 'socialMediaAction' | 'mailchimpAction' | 'shopifyAction' | 'githubAction' | 'jiraAction' | 'stickyNote';
+/** Node role in the pipeline */
+export type NodeRole = 'source' | 'processing' | 'flowControl' | 'routing' | 'action' | 'monitoring';
+/** Handle positions on the canvas node */
+export type HandlePosition = 'left' | 'right' | 'top' | 'bottom';
+/** Connection rules — which node types can connect to/from this node */
+export interface NodeConnectionConfig {
+    acceptsInputFrom: NodeType[];
+    canOutputTo: NodeType[];
+    special?: {
+        hasRejectionOutputNodes?: boolean;
+        hasBranches?: boolean;
+        isTerminal?: boolean;
+        hasLoopBack?: boolean;
+    };
+}
+/** UI-specific config for the dashboard canvas */
+export interface NodeUIConfig {
+    fromNodes: boolean;
+    toNodes: boolean;
+    isSource?: boolean;
+    inputHandles?: HandlePosition[];
+    outputHandles?: HandlePosition[];
+    dotHandles?: {
+        input?: string[];
+        output?: string[];
+    };
+    /**
+     * When true, the canvas derives output handles from the node entity
+     * at render time (e.g. one handle per `entity.tools[i].name`) rather
+     * than from a static `dotHandles.output` list. Used by Voice Agent —
+     * the count of tools is data, not config. NodeShell branches on this
+     * flag to render the dynamic handle set.
+     */
+    dynamicOutputs?: boolean;
+    special?: {
+        hasBranches?: boolean;
+        isTerminal?: boolean;
+        hasLoopBack?: boolean;
+        connectModal?: 'branch' | 'rule' | 'output-group';
+        routerTargetLabel?: string;
+        /**
+         * Generic named output groups — used by connectModal: 'output-group'.
+         * The modal reads entity[outputGroupsField] as an array of groups,
+         * each with a name (outputGroupNameField), a summary (outputGroupSummaryField),
+         * and its own outputNodes[].
+         * Works for Split (outputs[]), Conditional (branches[]), or any future branching node.
+         */
+        outputGroups?: {
+            /** Entity field containing the array of groups (e.g. 'outputs', 'branches') */
+            field?: string;
+            /** Field within each group for display name (e.g. 'name') */
+            nameField?: string;
+            /** Field within each group for summary/description (e.g. 'field', 'filterMode') */
+            summaryField?: string;
+            /** Label shown in the modal (e.g. 'output', 'branch') */
+            label: string;
+            /** Entity field for the fallback/else path (e.g. 'elseOutputNodes') */
+            elseField?: string;
+            /**
+             * Fixed output groups — for nodes with a static set of outputs (e.g. approval: approve/reject).
+             * Each entry maps to a top-level entity field that holds outputNodes[].
+             * When set, `field`/`nameField` are ignored — modal shows these fixed options.
+             */
+            fixedGroups?: Array<{
+                name: string;
+                field: string;
+            }>;
+            /**
+             * Optional content-aware gate — the output-group modal only opens
+             * when `entity[gate.field] === gate.value`. Lets a node opt into
+             * multi-branch routing only in some modes (e.g. AI Node in
+             * classifier mode) without trapping every connection in the
+             * picker the rest of the time. When the gate fails, the
+             * FlowCanvas falls through to the universal
+             * `entity.outputNodes` connect path.
+             */
+            gate?: {
+                field: string;
+                value: unknown;
+            };
+        };
+        /**
+         * Maps output fields to alternate payload fields on the source entity.
+         * When a downstream node is connected via a specific output field,
+         * InputSection reads the alternate payload instead of lastPayload.
+         * Example: { doneOutputNodes: 'lastDonePayload' } for loop nodes.
+         */
+        alternatePayloads?: Record<string, string>;
+        /** Whether this node can be connected as a loop-back target. Only nodes that go through the unified node-lifecycle support loop-back detection. */
+        loopBackAllowed?: boolean;
+    };
+}
+/**
+ * How the event pipeline routes a payload to this node when an
+ * upstream webhook connects to it directly. Required so adding a
+ * new node type at compile time is impossible without picking one.
+ *
+ * - 'generic': dispatchConnectedNodes loops findActiveByInputEndpoint
+ *   on the service and dispatches every active match. Use for
+ *   pipeline-style nodes that ingest webhook payloads (filter,
+ *   transform, ai, code, markdown, fileTransform, vectorStore).
+ *
+ * - 'custom': has a dedicated `case` in the dispatchOutputNodes
+ *   switch that calls the node's specific service method. Used
+ *   when the node needs scheduling, branching, gating, or queueing
+ *   (delay, cache, aggregator, rateLimiter, conditional, split,
+ *   loop, merge, approval, schemaValidator, router). The generic
+ *   loop must NOT process these — would dispatch twice.
+ *
+ * - 'excluded': not dispatched in the webhook flow at all. Action
+ *   nodes (email/http/mongo/notification/sheets/calendar/docs/
+ *   firecrawl) are fired post-delivery in onDeliveryResult with
+ *   their own loops; ingress nodes (webhook/scheduledWorkflow/
+ *   chatTrigger/trigger) start the flow themselves;
+ *   stickyNote is purely visual.
+ */
+export type PipelineDispatchKind = 'generic' | 'custom' | 'excluded';
+/** API dispatch config — how the event pipeline processes each node */
+export interface NodeDispatchConfig {
+    service: string;
+    collection: string;
+    hasFilters: boolean;
+    outputFields: string[];
+    /** @deprecated Use `pipelineDispatch` instead. Kept for backwards compat
+     *  during the migration; will be removed once every consumer reads
+     *  `pipelineDispatch`. */
+    customDispatch: boolean;
+    /** Required. See PipelineDispatchKind for the contract per value. */
+    pipelineDispatch: PipelineDispatchKind;
+}
+/** Standardized payload metadata — every node output MUST include _meta */
+export interface PayloadMeta {
+    iterable: boolean;
+    count: number;
+    iterateField?: string;
+}
+/** Helper to create _meta for single-object outputs */
+export declare function singleMeta(): PayloadMeta;
+/** Helper to create _meta for iterable array outputs */
+export declare function iterableMeta(field: string, count: number): PayloadMeta;
+/** Canvas prefix → node type mapping */
+export interface PrefixMapping {
+    prefix: string;
+    type: NodeType;
+    /** Canvas node type used in React Flow nodeTypes map (e.g. "cache-node", "email-action") */
+    canvasType: string;
+}

package/dist/esm/types.js

@@ -0,0 +1,8 @@
+/** Helper to create _meta for single-object outputs */
+export function singleMeta() {
+    return { iterable: false, count: 1 };
+}
+/** Helper to create _meta for iterable array outputs */
+export function iterableMeta(field, count) {
+    return { iterable: true, iterateField: field, count };
+}

package/dist/esm/ui.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Dashboard UI config — handle positions, dot visibility, canvas prefixes.
+ * Only imported by the Dashboard. Broker and API don't need this.
+ */
+import type { NodeType, NodeUIConfig, PrefixMapping } from './types.js';
+export declare const NODE_UI: Record<NodeType, NodeUIConfig>;
+/** Canvas prefix → node type mapping (used by FlowCanvas to identify node type from XYFlow node ID) */
+export declare const PREFIX_TO_TYPE: PrefixMapping[];
+/** Resolve canvas node ID to { type, entityId } */
+export declare function resolveNodeId(canvasId: string): {
+    type: NodeType;
+    entityId: string;
+} | null;

package/dist/esm/ui.js

@@ -0,0 +1,150 @@
+/**
+ * Dashboard UI config — handle positions, dot visibility, canvas prefixes.
+ * Only imported by the Dashboard. Broker and API don't need this.
+ */
+export const NODE_UI = {
+    // ── Source nodes ──
+    // Una fuente arranca el flujo: `fromNodes: false` significa que nada puede
+    // conectarse HACIA ella, y por eso su DTO en la API tampoco declara
+    // `inputNodes`. Expone un único punto de salida, `right-out`. El de abajo se
+    // retiró porque no aportaba una segunda semántica — sólo una segunda diana
+    // donde soltar aristas.
+    //
+    // Ya no queda ningún punto de abajo en todo el registro. Aquí ponía que el
+    // `router` conservaba el suyo «porque ahí abajo significa por regla», y era
+    // mentira: el modal de reglas lo abre `special.connectModal`, que mira el
+    // TIPO del nodo origen y no el handle por el que sueltas, así que desde la
+    // derecha salía el mismo modal. El destino de una regla vive en
+    // `port: rule:<id>`; el handle es sólo por dónde entra y sale la línea.
+    webhook: { fromNodes: true, toNodes: true, isSource: true },
+    scheduledWorkflow: { fromNodes: false, toNodes: true, isSource: true, outputHandles: ['right'], dotHandles: { output: ['right-out'] } },
+    chatTrigger: { fromNodes: false, toNodes: true, isSource: true, outputHandles: ['right'], dotHandles: { output: ['right-out'] } },
+    trigger: { fromNodes: false, toNodes: true, isSource: true, outputHandles: ['right'], dotHandles: { output: ['right-out'] } },
+    // Voice Agent: dynamicOutputs=true tells NodeShell to derive ONE
+    // output handle per non-disabled `entity.tools[i].name`. The
+    // `right-out` fallback handle is rendered when the agent has zero
+    // tools so the user has somewhere to drop the first wired connection
+    // before any tools are defined (rare but possible during onboarding).
+    voiceAgent: { fromNodes: false, toNodes: true, isSource: true, outputHandles: ['right'], dotHandles: { output: ['right-out'] }, dynamicOutputs: true },
+    // ── Pipeline processing nodes ──
+    filter: { fromNodes: true, toNodes: true, special: { loopBackAllowed: true } },
+    transform: { fromNodes: true, toNodes: true, special: { loopBackAllowed: true } },
+    // One output only: a payload that fails validation stops at the node.
+    schemaValidator: { fromNodes: true, toNodes: true, outputHandles: ['right'], special: { loopBackAllowed: true } },
+    conditional: { fromNodes: true, toNodes: true, outputHandles: ['right'], special: { loopBackAllowed: true, connectModal: 'output-group', outputGroups: { field: 'branches', nameField: 'name', summaryField: 'filterMode', label: 'branch', elseField: 'elseOutputNodes' } } },
+    delay: { fromNodes: true, toNodes: true },
+    rateLimiter: { fromNodes: true, toNodes: true },
+    aggregator: { fromNodes: true, toNodes: true, special: { loopBackAllowed: true } },
+    cache: { fromNodes: true, toNodes: true },
+    code: { fromNodes: true, toNodes: true, special: { loopBackAllowed: true } },
+    // AI Node: in classifier mode (entity.outputMode === 'classifier') the
+    // node fans out to N output handles — one per category in
+    // `entity.categories[]`, with the wiring in `categories[].outputNodes`.
+    // An item the classifier cannot place lands on the synthetic "other"
+    // value (see `entity.includeOtherBranch`) and stops there — "other" has
+    // no handle and no route. In any other outputMode the node falls back to
+    // the single right-out handle NodeShell renders when no dynamic outputs
+    // materialize.
+    ai: { fromNodes: true, toNodes: true, outputHandles: ['right'], special: { loopBackAllowed: true, connectModal: 'output-group', outputGroups: { field: 'categories', nameField: 'name', summaryField: 'description', label: 'category', gate: { field: 'outputMode', value: 'classifier' } } } },
+    markdown: { fromNodes: true, toNodes: true, special: { loopBackAllowed: true } },
+    fileTransform: { fromNodes: true, toNodes: true },
+    limit: { fromNodes: true, toNodes: true, special: { loopBackAllowed: true } },
+    // ── Flow control nodes ──
+    split: { fromNodes: true, toNodes: true, outputHandles: ['right'], special: { connectModal: 'output-group', outputGroups: { field: 'outputs', nameField: 'name', summaryField: 'field', label: 'output' } } },
+    merge: { fromNodes: true, toNodes: true, inputHandles: ['left', 'top'] },
+    approval: { fromNodes: true, toNodes: true, outputHandles: ['right'], special: { connectModal: 'output-group', outputGroups: { fixedGroups: [{ name: 'Approve', field: 'outputNodes' }, { name: 'Reject', field: 'rejectionOutputNodes' }], label: 'action' } } },
+    loop: { fromNodes: true, toNodes: true, inputHandles: ['left'], outputHandles: ['right'], dotHandles: { input: ['left-in'], output: ['right-out-loop', 'right-in-loopback', 'right-out-done'] }, special: { hasLoopBack: true, alternatePayloads: { doneOutputNodes: 'lastDonePayload' } } },
+    // ── Routing nodes ──
+    router: { fromNodes: true, toNodes: true, outputHandles: ['right'], dotHandles: { output: ['right-out'] }, special: { connectModal: 'rule' } },
+    // ── Action nodes ──
+    emailAction: { fromNodes: true, toNodes: true, inputHandles: ['left', 'top'], outputHandles: ['right'], dotHandles: { input: ['left-in', 'top-in'], output: ['right-out'] }, special: { loopBackAllowed: true, routerTargetLabel: 'email' } },
+    gmailAction: { fromNodes: true, toNodes: true, inputHandles: ['left', 'top'], outputHandles: ['right'], dotHandles: { input: ['left-in', 'top-in'], output: ['right-out'] }, special: { loopBackAllowed: true, routerTargetLabel: 'gmail' } },
+    httpAction: { fromNodes: true, toNodes: true, inputHandles: ['left'], dotHandles: { input: ['left-in'], output: ['right-out'] }, special: { loopBackAllowed: true } },
+    mongoAction: { fromNodes: true, toNodes: true, inputHandles: ['left'], dotHandles: { input: ['left-in'], output: ['right-out'] }, special: { loopBackAllowed: true } },
+    postgresAction: { fromNodes: true, toNodes: true, inputHandles: ['left'], dotHandles: { input: ['left-in'], output: ['right-out'] }, special: { loopBackAllowed: true } },
+    notificationAction: { fromNodes: true, toNodes: false, inputHandles: ['left', 'top'], dotHandles: { input: ['left-in', 'top-in'] }, special: { isTerminal: true, routerTargetLabel: 'notification' } },
+    sheetsAction: { fromNodes: true, toNodes: true, inputHandles: ['left'], dotHandles: { input: ['left-in'], output: ['right-out'] }, special: { loopBackAllowed: true } },
+    calendarAction: { fromNodes: true, toNodes: true, inputHandles: ['left'], dotHandles: { input: ['left-in'], output: ['right-out'] }, special: { loopBackAllowed: true } },
+    docsAction: { fromNodes: true, toNodes: true, inputHandles: ['left'], dotHandles: { input: ['left-in'], output: ['right-out'] }, special: { loopBackAllowed: true } },
+    driveAction: { fromNodes: true, toNodes: true, inputHandles: ['left'], dotHandles: { input: ['left-in'], output: ['right-out'] }, special: { loopBackAllowed: true } },
+    firecrawlAction: { fromNodes: true, toNodes: true, inputHandles: ['left'], dotHandles: { input: ['left-in'], output: ['right-out'] }, special: { loopBackAllowed: true } },
+    telegramAction: { fromNodes: true, toNodes: true, inputHandles: ['left'], dotHandles: { input: ['left-in'], output: ['right-out'] }, special: { loopBackAllowed: true, routerTargetLabel: 'telegram' } },
+    whatsappAction: { fromNodes: true, toNodes: true, inputHandles: ['left'], dotHandles: { input: ['left-in'], output: ['right-out'] }, special: { loopBackAllowed: true, routerTargetLabel: 'whatsapp' } },
+    discordAction: { fromNodes: true, toNodes: true, inputHandles: ['left'], dotHandles: { input: ['left-in'], output: ['right-out'] }, special: { loopBackAllowed: true, routerTargetLabel: 'discord' } },
+    mailchimpAction: { fromNodes: true, toNodes: true, inputHandles: ['left'], dotHandles: { input: ['left-in'], output: ['right-out'] }, special: { loopBackAllowed: true, routerTargetLabel: 'mailchimp' } },
+    shopifyAction: { fromNodes: true, toNodes: true, inputHandles: ['left'], dotHandles: { input: ['left-in'], output: ['right-out'] }, special: { loopBackAllowed: true, routerTargetLabel: 'shopify' } },
+    githubAction: { fromNodes: true, toNodes: true, inputHandles: ['left'], dotHandles: { input: ['left-in'], output: ['right-out'] }, special: { loopBackAllowed: true, routerTargetLabel: 'github' } },
+    jiraAction: { fromNodes: true, toNodes: true, inputHandles: ['left'], dotHandles: { input: ['left-in'], output: ['right-out'] }, special: { loopBackAllowed: true, routerTargetLabel: 'jira' } },
+    slackAction: { fromNodes: true, toNodes: true, inputHandles: ['left'], dotHandles: { input: ['left-in'], output: ['right-out'] }, special: { loopBackAllowed: true, routerTargetLabel: 'slack' } },
+    googleContactsAction: { fromNodes: true, toNodes: true, inputHandles: ['left'], dotHandles: { input: ['left-in'], output: ['right-out'] }, special: { loopBackAllowed: true } },
+    googleAnalyticsAction: { fromNodes: true, toNodes: true, inputHandles: ['left'], dotHandles: { input: ['left-in'], output: ['right-out'] }, special: { loopBackAllowed: true } },
+    notionAction: { fromNodes: true, toNodes: true, inputHandles: ['left'], dotHandles: { input: ['left-in'], output: ['right-out'] }, special: { loopBackAllowed: true, routerTargetLabel: 'notion' } },
+    vectorStore: { fromNodes: true, toNodes: true, inputHandles: ['left'], dotHandles: { input: ['left-in'], output: ['right-out'] }, special: { loopBackAllowed: true } },
+    rssAction: { fromNodes: true, toNodes: true, inputHandles: ['left'], dotHandles: { input: ['left-in'], output: ['right-out'] }, special: { loopBackAllowed: true } },
+    socialMediaAction: { fromNodes: true, toNodes: true, inputHandles: ['left'], dotHandles: { input: ['left-in'], output: ['right-out'] }, special: { loopBackAllowed: true } },
+    // ── Annotations ──
+    stickyNote: { fromNodes: false, toNodes: false },
+};
+/** Canvas prefix → node type mapping (used by FlowCanvas to identify node type from XYFlow node ID) */
+export const PREFIX_TO_TYPE = [
+    { prefix: 'wh-', type: 'webhook', canvasType: 'webhook' },
+    { prefix: 'swf-', type: 'scheduledWorkflow', canvasType: 'scheduledWorkflow' },
+    { prefix: 'chat-', type: 'chatTrigger', canvasType: 'chatTrigger' },
+    { prefix: 'trg-', type: 'trigger', canvasType: 'trigger' },
+    { prefix: 'va-', type: 'voiceAgent', canvasType: 'voiceAgent' },
+    { prefix: 'ea-', type: 'emailAction', canvasType: 'emailAction' },
+    { prefix: 'gm-', type: 'gmailAction', canvasType: 'gmailAction' },
+    { prefix: 'tg-', type: 'telegramAction', canvasType: 'telegramAction' },
+    { prefix: 'wa-', type: 'whatsappAction', canvasType: 'whatsappAction' },
+    { prefix: 'dc-', type: 'discordAction', canvasType: 'discordAction' },
+    { prefix: 'sl-', type: 'slackAction', canvasType: 'slackAction' },
+    { prefix: 'mc-', type: 'mailchimpAction', canvasType: 'mailchimpAction' },
+    { prefix: 'shp-', type: 'shopifyAction', canvasType: 'shopifyAction' },
+    { prefix: 'gh-', type: 'githubAction', canvasType: 'githubAction' },
+    { prefix: 'jr-', type: 'jiraAction', canvasType: 'jiraAction' },
+    { prefix: 'gc-', type: 'googleContactsAction', canvasType: 'googleContactsAction' },
+    { prefix: 'gaa-', type: 'googleAnalyticsAction', canvasType: 'googleAnalyticsAction' },
+    { prefix: 'ntn-', type: 'notionAction', canvasType: 'notionAction' },
+    { prefix: 'ha-', type: 'httpAction', canvasType: 'httpAction' },
+    { prefix: 'ma-', type: 'mongoAction', canvasType: 'mongoAction' },
+    { prefix: 'pg-', type: 'postgresAction', canvasType: 'postgresAction' },
+    { prefix: 'na-', type: 'notificationAction', canvasType: 'notificationAction' },
+    { prefix: 'ro-', type: 'router', canvasType: 'router' },
+    { prefix: 'fi-', type: 'filter', canvasType: 'filter' },
+    { prefix: 'tr-', type: 'transform', canvasType: 'transform' },
+    { prefix: 'sv-', type: 'schemaValidator', canvasType: 'schemaValidator' },
+    { prefix: 'delay-', type: 'delay', canvasType: 'delay' },
+    { prefix: 'sheet-', type: 'sheetsAction', canvasType: 'sheetsAction' },
+    { prefix: 'cal-', type: 'calendarAction', canvasType: 'calendarAction' },
+    { prefix: 'appr-', type: 'approval', canvasType: 'approval' },
+    { prefix: 'merge-', type: 'merge', canvasType: 'merge' },
+    { prefix: 'cond-', type: 'conditional', canvasType: 'conditional' },
+    { prefix: 'rl-', type: 'rateLimiter', canvasType: 'rateLimiter' },
+    { prefix: 'agg-', type: 'aggregator', canvasType: 'aggregator' },
+    { prefix: 'cache-', type: 'cache', canvasType: 'cache' },
+    { prefix: 'code-', type: 'code', canvasType: 'code' },
+    { prefix: 'ai-', type: 'ai', canvasType: 'ai' },
+    { prefix: 'split-', type: 'split', canvasType: 'split' },
+    { prefix: 'loop-', type: 'loop', canvasType: 'loop' },
+    { prefix: 'md-', type: 'markdown', canvasType: 'markdown' },
+    { prefix: 'ft-', type: 'fileTransform', canvasType: 'fileTransform' },
+    { prefix: 'lim-', type: 'limit', canvasType: 'limit' },
+    { prefix: 'doc-', type: 'docsAction', canvasType: 'docsAction' },
+    { prefix: 'drv-', type: 'driveAction', canvasType: 'driveAction' },
+    { prefix: 'fc-', type: 'firecrawlAction', canvasType: 'firecrawlAction' },
+    { prefix: 'vs-', type: 'vectorStore', canvasType: 'vectorStore' },
+    { prefix: 'rssa-', type: 'rssAction', canvasType: 'rssAction' },
+    { prefix: 'sm-', type: 'socialMediaAction', canvasType: 'socialMediaAction' },
+    { prefix: 'note-', type: 'stickyNote', canvasType: 'stickyNote' },
+];
+/** Resolve canvas node ID to { type, entityId } */
+export function resolveNodeId(canvasId) {
+    // Sort by prefix length descending so longer prefixes match first
+    const sorted = [...PREFIX_TO_TYPE].sort((a, b) => b.prefix.length - a.prefix.length);
+    for (const { prefix, type } of sorted) {
+        if (canvasId.startsWith(prefix)) {
+            return { type, entityId: canvasId.slice(prefix.length) };
+        }
+    }
+    return null;
+}

package/dist/esm/whatsapp-operations.d.ts

@@ -0,0 +1,23 @@
+/**
+ * WhatsApp Business Cloud API operation enum — single source of truth
+ * across the API, Dashboard, and any future consumers (Message Broker,
+ * MCP server). Used by:
+ *   - whatsappAction entity / DTO (api): operation field + validation
+ *   - dashboard WhatsAppAction operation picker
+ *   - MCP toolkit-specs expansion (one aiEnabled whatsappAction → N tools)
+ *
+ * Targets Meta Cloud API v21+ (the only supported variant after the
+ * On-Premises sunset on 2025-10-23). Each op maps to a single POST to
+ * `https://graph.facebook.com/v21.0/<phone_number_id>/messages` with
+ * a different `type` discriminator in the body.
+ *
+ * Phase 1 covers the ten ops that handle ~95% of business messaging.
+ * Phase 2 candidates (sendInteractiveButtons, sendInteractiveList,
+ * sendSticker, sendContacts) extend this list — bump the package and
+ * re-install in consumers, same pattern as Gmail / Calendar / Drive
+ * / Telegram.
+ */
+export declare const WHATSAPP_OPERATIONS: readonly ["sendText", "sendImage", "sendAudio", "sendVideo", "sendDocument", "sendLocation", "sendTemplate", "replyToMessage", "markAsRead", "sendReaction"];
+export type WhatsAppOperation = (typeof WHATSAPP_OPERATIONS)[number];
+/** Type guard — useful when validating untrusted input (DTOs, tool calls). */
+export declare function isWhatsAppOperation(value: unknown): value is WhatsAppOperation;

package/dist/esm/whatsapp-operations.js

@@ -0,0 +1,36 @@
+/**
+ * WhatsApp Business Cloud API operation enum — single source of truth
+ * across the API, Dashboard, and any future consumers (Message Broker,
+ * MCP server). Used by:
+ *   - whatsappAction entity / DTO (api): operation field + validation
+ *   - dashboard WhatsAppAction operation picker
+ *   - MCP toolkit-specs expansion (one aiEnabled whatsappAction → N tools)
+ *
+ * Targets Meta Cloud API v21+ (the only supported variant after the
+ * On-Premises sunset on 2025-10-23). Each op maps to a single POST to
+ * `https://graph.facebook.com/v21.0/<phone_number_id>/messages` with
+ * a different `type` discriminator in the body.
+ *
+ * Phase 1 covers the ten ops that handle ~95% of business messaging.
+ * Phase 2 candidates (sendInteractiveButtons, sendInteractiveList,
+ * sendSticker, sendContacts) extend this list — bump the package and
+ * re-install in consumers, same pattern as Gmail / Calendar / Drive
+ * / Telegram.
+ */
+export const WHATSAPP_OPERATIONS = [
+    'sendText',
+    'sendImage',
+    'sendAudio',
+    'sendVideo',
+    'sendDocument',
+    'sendLocation',
+    'sendTemplate',
+    'replyToMessage',
+    'markAsRead',
+    'sendReaction',
+];
+/** Type guard — useful when validating untrusted input (DTOs, tool calls). */
+export function isWhatsAppOperation(value) {
+    return (typeof value === 'string' &&
+        WHATSAPP_OPERATIONS.includes(value));
+}