@hostwebhook/node-types 1.69.0 → 1.70.0

package/dist/esm/registry.js

@@ -0,0 +1,555 @@
+/**
+ * Centralized NODE_REGISTRY — single source of truth for all node metadata.
+ *
+ * When adding a new node type, add ONE entry here. The dashboard derives
+ * all per-node maps (colors, URLs, Redux keys, palette, delete, etc.)
+ * from this registry. No more 18+ touch points.
+ */
+export const NODE_REGISTRY = {
+    // ── Sources ──
+    webhook: {
+        type: 'webhook', prefix: 'wh', label: 'Webhook',
+        group: 'Sources', detailPath: '/dashboard/webhooks', apiPath: '/webhooks',
+        stateKey: 'webhooks', allStateKey: 'allWebhooks',
+        color: '#a78bfa', testable: false,
+    },
+    scheduledWorkflow: {
+        type: 'scheduledWorkflow', prefix: 'swf', label: 'Scheduled Workflow',
+        group: 'Sources', detailPath: '/dashboard/scheduled-workflows', apiPath: '/scheduled-workflows',
+        stateKey: 'scheduledWorkflows', allStateKey: 'allScheduledWorkflows',
+        color: '#2dd4bf', testable: true,
+    },
+    chatTrigger: {
+        type: 'chatTrigger', prefix: 'chat', label: 'Chat Trigger',
+        group: 'Sources', detailPath: '/dashboard/chat-triggers', apiPath: '/chat-triggers',
+        stateKey: 'chatTriggers', allStateKey: 'allChatTriggers',
+        color: '#06b6d4', testable: false,
+    },
+    trigger: {
+        type: 'trigger', prefix: 'trg', label: 'Trigger',
+        group: 'Sources', detailPath: '/dashboard/triggers', apiPath: '/triggers',
+        stateKey: 'triggers', allStateKey: 'allTriggers',
+        color: '#ef4444', testable: false,
+    },
+    voiceAgent: {
+        type: 'voiceAgent', prefix: 'va', label: 'Voice Agent',
+        group: 'Sources', detailPath: '/dashboard/voice-agents', apiPath: '/voice-agents',
+        stateKey: 'voiceAgents', allStateKey: 'allVoiceAgents',
+        color: '#a855f7', testable: false,
+    },
+    // ── Flow Control ──
+    filter: {
+        type: 'filter', prefix: 'fi', label: 'Filter',
+        group: 'Flow Control', detailPath: '/dashboard/filter-nodes', apiPath: '/filter-nodes',
+        stateKey: 'filterNodes', allStateKey: 'allFilterNodes',
+        color: '#facc15', testable: true,
+    },
+    transform: {
+        type: 'transform', prefix: 'tr', label: 'Transform',
+        group: 'Flow Control', detailPath: '/dashboard/transform-nodes', apiPath: '/transform-nodes',
+        stateKey: 'transformNodes', allStateKey: 'allTransformNodes',
+        color: '#fbbf24', testable: true,
+    },
+    schemaValidator: {
+        type: 'schemaValidator', prefix: 'sv', label: 'Schema Validator',
+        group: 'Flow Control', detailPath: '/dashboard/schema-validators', apiPath: '/schema-validators',
+        stateKey: 'schemaValidators', allStateKey: 'allSchemaValidators',
+        color: '#818cf8', testable: true,
+    },
+    conditional: {
+        type: 'conditional', prefix: 'cond', label: 'Conditional',
+        group: 'Flow Control', detailPath: '/dashboard/conditional-nodes', apiPath: '/conditional-nodes',
+        stateKey: 'conditionalNodes', allStateKey: 'allConditionalNodes',
+        color: '#c084fc', testable: true,
+    },
+    delay: {
+        type: 'delay', prefix: 'delay', label: 'Delay',
+        group: 'Flow Control', detailPath: '/dashboard/delay-nodes', apiPath: '/delay-nodes',
+        stateKey: 'delayNodes', allStateKey: 'allDelayNodes',
+        color: '#94a3b8', testable: true,
+    },
+    rateLimiter: {
+        type: 'rateLimiter', prefix: 'rl', label: 'Rate Limiter',
+        group: 'Flow Control', detailPath: '/dashboard/rate-limiter-nodes', apiPath: '/rate-limiter-nodes',
+        stateKey: 'rateLimiterNodes', allStateKey: 'allRateLimiterNodes',
+        color: '#f97316', testable: false,
+    },
+    aggregator: {
+        type: 'aggregator', prefix: 'agg', label: 'Aggregator',
+        group: 'Flow Control', detailPath: '/dashboard/aggregator-nodes', apiPath: '/aggregator-nodes',
+        stateKey: 'aggregatorNodes', allStateKey: 'allAggregatorNodes',
+        color: '#84cc16', testable: true,
+    },
+    cache: {
+        type: 'cache', prefix: 'cache', label: 'Cache',
+        group: 'Flow Control', detailPath: '/dashboard/cache-nodes', apiPath: '/cache-nodes',
+        stateKey: 'cacheNodes', allStateKey: 'allCacheNodes',
+        color: '#d946ef', testable: true,
+    },
+    code: {
+        type: 'code', prefix: 'code', label: 'Code',
+        group: 'Flow Control', detailPath: '/dashboard/code-nodes', apiPath: '/code-nodes',
+        stateKey: 'codeNodes', allStateKey: 'allCodeNodes',
+        color: '#a855f7', testable: true,
+    },
+    ai: {
+        type: 'ai', prefix: 'ai', label: 'AI',
+        /* 'Actions' y no 'Flow Control': un nodo de IA no encamina ni retiene un
+           evento —eso es control de flujo— sino que HACE algo con él y devuelve un
+           resultado, igual que enviar un correo o escribir en una hoja. Además es
+           lo que decide qué se ofrece como acción en el flujo guiado del primer
+           flujo (`FIRST_FLOW_ACTIONS` en el dashboard), y ahí tiene que estar. */
+        group: 'Actions', detailPath: '/dashboard/ai-nodes', apiPath: '/ai-nodes',
+        stateKey: 'aiNodes', allStateKey: 'allAiNodes',
+        color: '#d946ef', testable: true,
+    },
+    split: {
+        type: 'split', prefix: 'split', label: 'Split',
+        group: 'Flow Control', detailPath: '/dashboard/split-nodes', apiPath: '/split-nodes',
+        stateKey: 'splitNodes', allStateKey: 'allSplitNodes',
+        color: '#38bdf8', testable: true,
+    },
+    merge: {
+        type: 'merge', prefix: 'merge', label: 'Merge',
+        group: 'Flow Control', detailPath: '/dashboard/merge-nodes', apiPath: '/merge-nodes',
+        stateKey: 'mergeNodes', allStateKey: 'allMergeNodes',
+        color: '#94a3b8', testable: false,
+    },
+    approval: {
+        type: 'approval', prefix: 'appr', label: 'Approval',
+        group: 'Flow Control', detailPath: '/dashboard/approval-nodes', apiPath: '/approval-nodes',
+        stateKey: 'approvalNodes', allStateKey: 'allApprovalNodes',
+        color: '#94a3b8', testable: true,
+    },
+    loop: {
+        type: 'loop', prefix: 'loop', label: 'Loop',
+        group: 'Flow Control', detailPath: '/dashboard/loop-nodes', apiPath: '/loop-nodes',
+        stateKey: 'loopNodes', allStateKey: 'allLoopNodes',
+        color: '#f59e0b', testable: true,
+    },
+    markdown: {
+        type: 'markdown', prefix: 'md', label: 'Markdown',
+        group: 'Flow Control', detailPath: '/dashboard/markdown-nodes', apiPath: '/markdown-nodes',
+        stateKey: 'markdownNodes', allStateKey: 'allMarkdownNodes',
+        color: '#6366f1', testable: true,
+    },
+    fileTransform: {
+        type: 'fileTransform', prefix: 'ft', label: 'File Transform',
+        group: 'Flow Control', detailPath: '/dashboard/file-transform-nodes', apiPath: '/file-transform-nodes',
+        stateKey: 'fileTransformNodes', allStateKey: 'allFileTransformNodes',
+        color: '#f97316', testable: true,
+    },
+    limit: {
+        type: 'limit', prefix: 'lim', label: 'Limit',
+        group: 'Flow Control', detailPath: '/dashboard/limit-nodes', apiPath: '/limit-nodes',
+        stateKey: 'limitNodes', allStateKey: 'allLimitNodes',
+        // Amber matches filter / aggregator family — visually groups
+        // "array-shape transformations" together on the canvas.
+        color: '#fbbf24', testable: true,
+    },
+    // ── Routing ──
+    router: {
+        type: 'router', prefix: 'ro', label: 'Router',
+        group: 'Flow Control', detailPath: '/dashboard/routers', apiPath: '/routers',
+        stateKey: 'routers', allStateKey: 'allRouters',
+        color: '#38bdf8', testable: true,
+    },
+    // ── Actions ──
+    /**
+     * Manda correo por Resend, y sólo por Resend.
+     *
+     * Tuvo un campo `provider` con Gmail y un Outlook que nunca llegó. Gmail se
+     * fue a su propio nodo —ver `gmailAction`— y con él su OAuth, sus dieciséis
+     * operaciones y el toolkit de IA, que era suyo: aquí sólo quedan enviar y
+     * el modo de IA no tiene dieciséis herramientas que ofrecer.
+     */
+    emailAction: {
+        type: 'emailAction', prefix: 'ea', label: 'Email Action',
+        group: 'Actions', detailPath: '/dashboard/email-actions', apiPath: '/email-actions',
+        stateKey: 'emailActions', allStateKey: 'allEmailActions',
+        color: '#f472b6', testable: true,
+        /**
+         * Sigue siendo herramienta: hay una ruta native + aiEnabled donde el nodo
+         * AI genera el correo y este lo manda por Resend —en produccion existe un
+         * «using native email as tool»—. Se la quite al partir Gmail dando por
+         * hecho que el toolkit era solo suyo, y sin esto el nodo recupera sus
+         * handles en modo herramienta: justo el mal enrutado que este flag evita.
+         */
+        isToolOnly: (e) => e.aiEnabled === true,
+    },
+    /**
+     * Gmail salio del nodo Email, que ahora manda SOLO por Resend.
+     *
+     * Estaban juntos bajo un campo `provider`, y eso obligaba a que un nodo de
+     * dos operaciones —enviar por Resend— cargara con las dieciseis de Gmail, su
+     * OAuth, su toolkit de IA y su send-and-wait. Partidos, cada uno se explica
+     * solo y el de Email vuelve a caber en una pantalla.
+     */
+    gmailAction: {
+        type: 'gmailAction', prefix: 'gm', label: 'Gmail',
+        group: 'Actions', detailPath: '/dashboard/gmail-actions', apiPath: '/gmail-actions',
+        stateKey: 'gmailActions', allStateKey: 'allGmailActions',
+        color: '#ea4335', testable: true,
+        // El toolkit de IA se vino con Gmail: son sus dieciseis operaciones las
+        // que el LLM llama, no las dos de Resend. Ver el comentario de arriba.
+        isToolOnly: (e) => e.aiEnabled === true,
+    },
+    httpAction: {
+        type: 'httpAction', prefix: 'ha', label: 'HTTP Action',
+        group: 'Actions', detailPath: '/dashboard/http-actions', apiPath: '/http-actions',
+        stateKey: 'httpActions', allStateKey: 'allHttpActions',
+        color: '#3b82f6', testable: true,
+    },
+    mongoAction: {
+        type: 'mongoAction', prefix: 'ma', label: 'MongoDB Action',
+        group: 'Actions', detailPath: '/dashboard/mongo-actions', apiPath: '/mongo-actions',
+        stateKey: 'mongoActions', allStateKey: 'allMongoActions',
+        color: '#34d399', testable: true,
+    },
+    postgresAction: {
+        type: 'postgresAction', prefix: 'pg', label: 'Postgres Action',
+        group: 'Actions', detailPath: '/dashboard/postgres-actions', apiPath: '/postgres-actions',
+        stateKey: 'postgresActions', allStateKey: 'allPostgresActions',
+        color: '#336791', testable: true,
+    },
+    notificationAction: {
+        type: 'notificationAction', prefix: 'na', label: 'Notification',
+        group: 'Actions', detailPath: '/dashboard/notification-actions', apiPath: '/notification-actions',
+        stateKey: 'notificationActions', allStateKey: 'allNotificationActions',
+        color: '#f472b6', testable: true,
+    },
+    sheetsAction: {
+        type: 'sheetsAction', prefix: 'sheet', label: 'Google Sheets Action',
+        group: 'Actions', detailPath: '/dashboard/sheets-actions', apiPath: '/sheets-actions',
+        stateKey: 'sheetsActions', allStateKey: 'allSheetsActions',
+        color: '#34d399', testable: true,
+    },
+    calendarAction: {
+        type: 'calendarAction', prefix: 'cal', label: 'Google Calendar Action',
+        group: 'Actions', detailPath: '/dashboard/calendar-actions', apiPath: '/calendar-actions',
+        stateKey: 'calendarActions', allStateKey: 'allCalendarActions',
+        color: '#60a5fa', testable: true,
+        // AI Toolkit mode wires the node through the upstream AI Node's
+        // tools[] list, not via canvas edges — same pattern as emailAction.
+        isToolOnly: (e) => e.aiEnabled === true,
+    },
+    docsAction: {
+        type: 'docsAction', prefix: 'doc', label: 'Google Docs',
+        group: 'Actions', detailPath: '/dashboard/docs-actions', apiPath: '/docs-actions',
+        stateKey: 'docsActions', allStateKey: 'allDocsActions',
+        color: '#4285F4', testable: true,
+    },
+    driveAction: {
+        type: 'driveAction', prefix: 'drv', label: 'Google Drive',
+        group: 'Actions', detailPath: '/dashboard/drive-actions', apiPath: '/drive-actions',
+        stateKey: 'driveActions', allStateKey: 'allDriveActions',
+        color: '#22c55e', testable: true,
+        // AI Toolkit mode wires the node through the upstream AI Node's
+        // tools[] list, not via canvas edges — same pattern as emailAction.
+        isToolOnly: (e) => e.aiEnabled === true,
+    },
+    firecrawlAction: {
+        type: 'firecrawlAction', prefix: 'fc', label: 'Firecrawl',
+        group: 'Actions', detailPath: '/dashboard/firecrawl-actions', apiPath: '/firecrawl-actions',
+        stateKey: 'firecrawlActions', allStateKey: 'allFirecrawlActions',
+        color: '#f97316', testable: true,
+    },
+    mailchimpAction: {
+        type: 'mailchimpAction', prefix: 'mc', label: 'Mailchimp',
+        group: 'Actions', detailPath: '/dashboard/mailchimp-actions', apiPath: '/mailchimp-actions',
+        stateKey: 'mailchimpActions', allStateKey: 'allMailchimpActions',
+        // Mailchimp's Cavendish yellow, darkened until it holds contrast on a
+        // light canvas. The brand value (#ffe01b) reads as a highlighter there.
+        color: '#c9a227', testable: true,
+    },
+    shopifyAction: {
+        type: 'shopifyAction', prefix: 'shp', label: 'Shopify',
+        group: 'Actions', detailPath: '/dashboard/shopify-actions', apiPath: '/shopify-actions',
+        stateKey: 'shopifyActions', allStateKey: 'allShopifyActions',
+        // Shopify's green, abierto un punto. El de marca (#008060) es más oscuro
+        // que cualquier otro color de este registro y se hunde contra el lienzo
+        // en modo oscuro; éste sigue leyéndose como Shopify y aguanta en los dos
+        // temas. Mismo criterio que el amarillo de Mailchimp, al revés.
+        color: '#0a9e70', testable: true,
+    },
+    githubAction: {
+        type: 'githubAction', prefix: 'gh', label: 'GitHub',
+        group: 'Actions', detailPath: '/dashboard/github-actions', apiPath: '/github-actions',
+        stateKey: 'githubActions', allStateKey: 'allGithubActions',
+        // El morado de "merged" de GitHub. Su marca real es acromática, y ahí no
+        // hay elección posible: en el minimapa lo único que distingue a un nodo es
+        // el color, el gris cálido ya lo ocupa Notion y el frío lo llevan tres.
+        //
+        // ⚠️ Es la banda MÁS disputada de este registro — ocho nodos en morado,
+        // con #7c3aed y #a855f7 como vecinos inmediatos. Se eligió por ser el
+        // color que de verdad dice GitHub, pero **la decisión se cierra mirando el
+        // minimapa**, no leyendo este comentario. Si choca, el plan B es un
+        // grafito claro, sabiendo que compite con Notion.
+        color: '#8957e5', testable: true,
+        /* Sin isToolOnly: la v1 no trae modo toolkit de IA, y aquí pesa más que en
+           ningún otro nodo — el MCP oficial de GitHub ya cubre ese caso dentro del
+           AI Node. Los rieles son este nodo; la improvisación es el MCP. */
+    },
+    jiraAction: {
+        type: 'jiraAction', prefix: 'jr', label: 'Jira',
+        group: 'Actions', detailPath: '/dashboard/jira-actions', apiPath: '/jira-actions',
+        stateKey: 'jiraActions', allStateKey: 'allJiraActions',
+        // El azul de marca de Jira, y estaba libre. La banda azul es la segunda
+        // mas poblada de este registro —nueve nodos— pero ninguno tan profundo:
+        // #3b82f6 y #60a5fa son claramente mas claros, y el #336791 de Postgres es
+        // mas apagado. En el minimapa es el azul oscuro, y eso lo distingue.
+        //
+        // Sigue valiendo lo que escribio GitHub aqui al lado: **la decision se
+        // cierra mirando el minimapa**, no leyendo este comentario.
+        color: '#0052CC', testable: true,
+        /* Sin isToolOnly: la v1 no trae modo toolkit de IA. Cada toolkit vive dos
+           veces —specs del dashboard para el AI Node y specs de la api para MCP— y
+           esa duplicacion no se paga antes de ver el nodo en pantalla. Ademas
+           Atlassian tiene servidor MCP propio, ya registrado en
+           `MCP_OAUTH_PRESETS.atlassian`, que cubre la cola larga dentro del AI
+           Node. Los rieles son este nodo. */
+    },
+    telegramAction: {
+        type: 'telegramAction', prefix: 'tg', label: 'Telegram Action',
+        group: 'Actions', detailPath: '/dashboard/telegram-actions', apiPath: '/telegram-actions',
+        stateKey: 'telegramActions', allStateKey: 'allTelegramActions',
+        color: '#0ea5e9', testable: true,
+        // AI Toolkit mode — same pattern as emailAction. One aiEnabled
+        // telegramAction expands into N MCP tools (one per operation) in
+        // the upstream AI Node's tool list, so we hide canvas handles to
+        // prevent accidental misrouting that would silently fire with
+        // empty fields.
+        isToolOnly: (e) => e.aiEnabled === true,
+    },
+    whatsappAction: {
+        type: 'whatsappAction', prefix: 'wa', label: 'WhatsApp Action',
+        group: 'Actions', detailPath: '/dashboard/whatsapp-actions', apiPath: '/whatsapp-actions',
+        stateKey: 'whatsappActions', allStateKey: 'allWhatsappActions',
+        // WhatsApp brand green (#25d366) — instantly recognisable on the canvas.
+        color: '#25d366', testable: true,
+        // Same toolkit pattern as telegramAction — when aiEnabled the
+        // entity stops being a manually-wired single-op action and becomes
+        // a multi-op tool surface for an upstream AI Node. Hide canvas
+        // handles to prevent accidental wiring that would fire with empty
+        // fields the LLM is supposed to populate.
+        isToolOnly: (e) => e.aiEnabled === true,
+    },
+    discordAction: {
+        type: 'discordAction', prefix: 'dc', label: 'Discord Action',
+        group: 'Actions', detailPath: '/dashboard/discord-actions', apiPath: '/discord-actions',
+        stateKey: 'discordActions', allStateKey: 'allDiscordActions',
+        // Discord brand "Blurple" (#5865F2).
+        color: '#5865F2', testable: true,
+        // Same toolkit pattern as telegramAction / whatsappAction. Hide
+        // canvas handles when aiEnabled so the user can't manually wire a
+        // multi-op tool surface — the LLM picks the operation per call.
+        isToolOnly: (e) => e.aiEnabled === true,
+    },
+    slackAction: {
+        type: 'slackAction', prefix: 'sl', label: 'Slack Action',
+        group: 'Actions', detailPath: '/dashboard/slack-actions', apiPath: '/slack-actions',
+        stateKey: 'slackActions', allStateKey: 'allSlackActions',
+        // Slack brand purple ("aubergine"-derived family). Matches the
+        // accent color used by SlackConfigSection / ServiceTriggerNode for
+        // visual continuity across Slack-related nodes.
+        color: '#7c3aed', testable: true,
+        // Same AI-tool gating as Telegram/Discord/WhatsApp/Email/Calendar/
+        // Contacts. When aiEnabled the node fans out into 16 MCP tools
+        // (one per SLACK_OPERATIONS entry); hide canvas handles to prevent
+        // accidental wiring with empty fields the LLM is supposed to fill.
+        isToolOnly: (e) => e.aiEnabled === true,
+    },
+    googleContactsAction: {
+        type: 'googleContactsAction', prefix: 'gc', label: 'Google Contacts',
+        group: 'Actions', detailPath: '/dashboard/google-contacts-actions', apiPath: '/google-contacts-actions',
+        stateKey: 'googleContactsActions', allStateKey: 'allGoogleContactsActions',
+        // Google "blue" used by Google Drive / Docs (#4285F4) — same family.
+        color: '#4285F4', testable: true,
+        // AI toolkit mode mirrors emailAction / calendarAction — when
+        // aiEnabled the node expands into N MCP tools (one per People API
+        // operation) in the upstream AI Node's tool list. Hide canvas
+        // handles to keep manual + tool modes from being mixed.
+        isToolOnly: (e) => e.aiEnabled === true,
+    },
+    googleAnalyticsAction: {
+        type: 'googleAnalyticsAction', prefix: 'gaa', label: 'Google Analytics',
+        group: 'Actions', detailPath: '/dashboard/google-analytics-actions', apiPath: '/google-analytics-actions',
+        stateKey: 'googleAnalyticsActions', allStateKey: 'allGoogleAnalyticsActions',
+        // Naranja de marca de Google Analytics (#E37400). No reutiliza el
+        // #ff9933 de RSS ni el orange-500 de Tailwind que ya llevan tres nodos:
+        // en el minimapa lo unico que distingue a un nodo es el color.
+        color: '#E37400', testable: true,
+        /* Sin isToolOnly: la v1 no trae modo toolkit de IA. Cada toolkit vive
+           dos veces --specs del dashboard para el AI Node y specs de la api para
+           MCP, sin nada que las ate-- y esa duplicacion no se paga antes de ver
+           el nodo funcionando en pantalla. */
+    },
+    notionAction: {
+        type: 'notionAction', prefix: 'ntn', label: 'Notion',
+        group: 'Actions', detailPath: '/dashboard/notion-actions', apiPath: '/notion-actions',
+        stateKey: 'notionActions', allStateKey: 'allNotionActions',
+        // Notion es monocromo de marca (su negro es #37352F), y un punto negro
+        // en el minimapa desaparece en modo oscuro. Este stone-500 es el gris
+        // CÁLIDO más cercano a esa marca, y no choca con el #94a3b8 (slate, gris
+        // frío) que ya llevan tres nodos: en el minimapa lo único que distingue
+        // a un nodo es el color.
+        color: '#78716c', testable: true,
+        /* Sin isToolOnly: la v1 no trae modo toolkit de IA. Cada toolkit vive dos
+           veces --specs del dashboard para el AI Node y specs de la api para
+           MCP-- y esa duplicación no se paga antes de ver el nodo en pantalla. */
+    },
+    vectorStore: {
+        type: 'vectorStore', prefix: 'vs', label: 'Vector Store',
+        group: 'Actions', detailPath: '/dashboard/vector-store-nodes', apiPath: '/vector-store-nodes',
+        stateKey: 'vectorStoreNodes', allStateKey: 'allVectorStoreNodes',
+        color: '#06b6d4', testable: true,
+    },
+    rssAction: {
+        type: 'rssAction', prefix: 'rssa', label: 'RSS Fetch',
+        group: 'Actions', detailPath: '/dashboard/rss-actions', apiPath: '/rss-actions',
+        stateKey: 'rssActions', allStateKey: 'allRssActions',
+        // Classic RSS feed orange (#ff9933) — distinguishes from rateLimiter /
+        // fileTransform / firecrawl which sit on Tailwind orange-500.
+        color: '#ff9933', testable: true,
+    },
+    socialMediaAction: {
+        type: 'socialMediaAction', prefix: 'sm', label: 'Social Media',
+        group: 'Actions', detailPath: '/dashboard/social-media-actions', apiPath: '/social-media-actions',
+        stateKey: 'socialMediaActions', allStateKey: 'allSocialMediaActions',
+        // Pink/magenta (#ec4899) — neutral default; the canvas card overrides
+        // with the picked provider's brandColor at render time so each
+        // platform reads at a glance (Bluesky #0085ff, Mastodon #6364ff, ...).
+        color: '#ec4899', testable: true,
+        // AI toolkit mode (Sprint 4) wires through tools[] like the other
+        // toolkit-capable actions. Manual + toolkit modes share the same
+        // detail page; the segmented control hides ops-config when toolkit.
+        isToolOnly: (e) => e.aiEnabled === true,
+    },
+    // ── Annotations ──
+    stickyNote: {
+        type: 'stickyNote', prefix: 'note', label: 'Sticky Note',
+        group: 'Annotations', detailPath: '', apiPath: '/sticky-notes',
+        stateKey: 'stickyNotes', allStateKey: 'allStickyNotes',
+        color: '#fbbf24', testable: false,
+    },
+};
+// ── Derived helpers ──
+/** Get registry entry by canonical type */
+export function getNodeRegistryEntry(type) {
+    return NODE_REGISTRY[type];
+}
+/** type → detail page path */
+export const NODE_DETAIL_PATHS = Object.fromEntries(Object.values(NODE_REGISTRY).filter(n => n.detailPath).map(n => [n.type, n.detailPath]));
+/** type → minimap color */
+export const NODE_COLORS = Object.fromEntries(Object.values(NODE_REGISTRY).map(n => [n.type, n.color]));
+/** type → [stateKey, allStateKey] */
+export const NODE_STATE_KEYS = Object.fromEntries(Object.values(NODE_REGISTRY).map(n => [n.type, [n.stateKey, n.allStateKey]]));
+/** prefix → type */
+export const PREFIX_TO_NODE_TYPE = Object.fromEntries(Object.values(NODE_REGISTRY).map(n => [n.prefix, n.type]));
+/** type → prefix */
+export const NODE_TYPE_TO_PREFIX = Object.fromEntries(Object.values(NODE_REGISTRY).map(n => [n.type, n.prefix]));
+function specsFor(type, catalog) {
+    return catalog[type]?.versions;
+}
+/** True when this type ships more than one version. False for every type today. */
+export function isVersioned(type, catalog = NODE_REGISTRY) {
+    return (specsFor(type, catalog)?.length ?? 0) > 0;
+}
+/**
+ * Every declared version, newest first — the order a picker wants.
+ * Empty for a type that does not version.
+ */
+export function versionsOf(type, catalog = NODE_REGISTRY) {
+    const declared = specsFor(type, catalog);
+    if (!declared)
+        return [];
+    return [...declared].sort((a, b) => b.v - a.v);
+}
+/** One version's spec, or undefined when the type or the number is unknown. */
+export function versionSpec(type, v, catalog = NODE_REGISTRY) {
+    return specsFor(type, catalog)?.find(s => s.v === v);
+}
+/**
+ * The version a new node of this type is born on.
+ *
+ * Returns 1 for a type that does not version, which is also how an entity
+ * with no `nodeVersion` is read. A node created before its type ever
+ * versioned was calling the original endpoints, so calling it version 1
+ * is not a convention — it is the truth.
+ */
+export function currentVersion(type, catalog = NODE_REGISTRY) {
+    const current = specsFor(type, catalog)?.find(s => s.status === 'current');
+    return current?.v ?? 1;
+}
+/**
+ * Config fields present in `from` that `to` does not declare — the exact
+ * list a confirmation dialog should name, and the exact list the server
+ * should unset.
+ *
+ * Returns `null` when the question cannot be answered: the type does not
+ * version, or one of the two versions is not declared. `null` is not the
+ * same as "nothing is lost", and callers must not treat it that way — a
+ * dialog should refuse to offer the switch, and the api should reject the
+ * request. Returning `null` rather than `[]` is what stops "I don't know"
+ * from being read as "nothing".
+ *
+ * This lives here rather than in each consumer because the dialog that
+ * ANNOUNCES the loss and the server that PERFORMS it have to give the
+ * same answer. Two implementations would agree right until the day they
+ * did not, and that day the dialog lies.
+ */
+export function fieldsLostBetween(type, from, to, catalog = NODE_REGISTRY) {
+    const a = versionSpec(type, from, catalog);
+    const b = versionSpec(type, to, catalog);
+    if (!a || !b)
+        return null;
+    return fieldsLost(a, b);
+}
+/**
+ * The same answer for two specs already in hand — what `fieldsLostBetween`
+ * delegates to once it has resolved both, and what a caller that already
+ * holds them from `versionsOf()` can use without a second lookup.
+ */
+export function fieldsLost(from, to) {
+    if (from.v === to.v)
+        return [];
+    if (to.cleanBreak)
+        return [...from.fields];
+    const kept = new Set(to.fields);
+    return from.fields.filter(f => !kept.has(f));
+}
+/**
+ * Declaration mistakes in the version catalogs, as readable lines.
+ *
+ * A guard rather than a line in a document: what this codebase learned
+ * from fifteen nodes skipping a checklist point everyone had read is that
+ * the written rule prevented nothing and the guard did. Empty means every
+ * catalog is well-formed.
+ */
+export function versionCatalogErrors(catalog = NODE_REGISTRY) {
+    const errors = [];
+    for (const entry of Object.values(catalog)) {
+        const versions = entry.versions;
+        if (!versions)
+            continue;
+        if (versions.length === 0) {
+            errors.push(`${entry.type}: declares an empty versions array — omit the field instead`);
+            continue;
+        }
+        const numbers = versions.map(s => s.v);
+        const repeatedNumbers = [...new Set(numbers.filter((n, i) => numbers.indexOf(n) !== i))];
+        if (repeatedNumbers.length)
+            errors.push(`${entry.type}: repeated version number ${repeatedNumbers.join(', ')}`);
+        for (const spec of versions) {
+            if (!Number.isInteger(spec.v) || spec.v < 1)
+                errors.push(`${entry.type}: version "${spec.v}" is not a positive integer`);
+            const repeatedFields = [...new Set(spec.fields.filter((f, i) => spec.fields.indexOf(f) !== i))];
+            if (repeatedFields.length)
+                errors.push(`${entry.type} v${spec.v}: repeated field ${repeatedFields.join(', ')}`);
+        }
+        const current = versions.filter(s => s.status === 'current');
+        if (current.length !== 1)
+            errors.push(`${entry.type}: needs exactly one version with status "current", found ${current.length}`);
+    }
+    return errors;
+}

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

@@ -0,0 +1,78 @@
+/**
+ * Google Sheets operation enum + form schema — single source of truth across
+ * the API, Dashboard, and Message Broker. Used by:
+ *   - sheetsAction entity / DTO (api): operation field + validation
+ *   - dashboard SheetsAction detail page: the whole operation form
+ *
+ * The api already accepts these six; the dashboard's own `SheetsAction` type
+ * only listed four (it never learned about appendOrUpdateRow and
+ * createSpreadsheet), which is exactly the drift this enum removes.
+ */
+export declare const SHEETS_OPERATIONS: readonly ["appendRow", "updateRow", "appendOrUpdateRow", "readRange", "getRows", "createSpreadsheet"];
+export type SheetsOperation = (typeof SHEETS_OPERATIONS)[number];
+/** Type guard — useful when validating untrusted input (DTOs, AI tool calls). */
+export declare function isSheetsOperation(value: unknown): value is SheetsOperation;
+/**
+ * Per-operation form schema, same idea as SLACK_OPERATION_SPECS and
+ * GOOGLE_CONTACTS_OPERATION_SPECS: the detail page renders it with one loop
+ * instead of a branch per operation.
+ *
+ * Two things make this node's schema different from the others, and both are
+ * deliberate:
+ *
+ * 1. **The values are top-level entity fields, not an `operationConfig`
+ *    record.** `name` here is the property on the sheetsAction document
+ *    (`spreadsheetId`, `sheetName`, …), and `columnMapping` is a complex field.
+ *    A renderer copied from Contacts would write to the wrong place.
+ * 2. **Half the fields are discovered at run time.** The column list comes from
+ *    the chosen sheet's header row, fetched live. So the schema names the
+ *    *picker* rather than carrying options — the same trick Discord's
+ *    `channel` / `guild` / `role` types use.
+ */
+export interface SheetsParamSpec {
+    /** Field key — the property name on the sheetsAction document. */
+    name: string;
+    /** UI label. Empty string where the control has never shown one. */
+    label: string;
+    /**
+     * Param type for form rendering.
+     *
+     * - `string` — one-line input with `{{payload.x}}` templating.
+     * - `spreadsheet` — the spreadsheet picker **plus** the "or paste ID / URL"
+     *   input that sits under it. They are one field with two ways in, not two
+     *   fields, and the paste box extracts the id out of a full URL.
+     * - `sheetTab` — the tab picker for the chosen spreadsheet. Picking a tab
+     *   clears `columnMapping`, because the headers just changed.
+     * - `headerColumn` — a dropdown of the sheet's live header row.
+     * - `columnMapping` — the header-to-template editor. It owns the three
+     *   states of the header fetch (loading, loaded, failed), which is what
+     *   used to be six copies of the same conditional in the page.
+     */
+    type: 'string' | 'spreadsheet' | 'sheetTab' | 'headerColumn' | 'columnMapping';
+    /** Required by the operation. Metadata — the form does not gate on it. */
+    required?: boolean;
+    /** Help text under the control. Absent where the form shows none. */
+    description?: string;
+    /** Hint shown inside the input. */
+    placeholder?: string;
+    /**
+     * Section this field is rendered inside. Fields without one share the first
+     * section with the operation picker; the mapping fields sit in a second
+     * section whose title changes per operation ("Columns to Append",
+     * "Update Row", "Match & Upsert").
+     */
+    section?: string;
+    /** `columnMapping` only — the line shown while no column has been added. */
+    emptyText?: string;
+}
+export interface SheetsOperationSpec {
+    /** UI label for the operation picker. */
+    label: string;
+    /** Sub-line under the label in the picker. */
+    description: string;
+    /** googleapis call the operation maps to (sheets v4). */
+    apiMethod: string;
+    /** Parameter schema. Order matters for form rendering. */
+    params: SheetsParamSpec[];
+}
+export declare const SHEETS_OPERATION_SPECS: Record<SheetsOperation, SheetsOperationSpec>;