@hostwebhook/node-types 1.69.0 → 1.71.0

package/dist/esm/gmail-operations.js

@@ -0,0 +1,560 @@
+/**
+ * Gmail operation enum — single source of truth across the API, Dashboard,
+ * and Message Broker. Used by:
+ *   - emailAction entity / DTO (api): operation field + validation
+ *   - dashboard EmailActionGmailOperation type
+ *   - broker hostwebhook types + tool schemas
+ *   - trigger / future Gmail-related nodes
+ *
+ * Adding a new Gmail operation = add it here, bump this package's
+ * version, publish to npm, and re-install in the consuming repos.
+ * Each consumer still owns its operation-specific config schema (the
+ * dashboard owns the UI form schema, the api owns the dispatch logic),
+ * but the canonical list of valid operation strings lives here.
+ */
+export const GMAIL_OPERATIONS = [
+    'send',
+    // Pause-the-pipeline op — sends an email with Approve / (optional)
+    // Disapprove buttons and waits for the recipient to click before
+    // dispatching downstream. Backed by the shared send-and-wait infra in
+    // api/src/nodes/approval-nodes (PendingApproval + 1-click controller).
+    // Output of the node carries `payload._waitResponse = { approved,
+    // decidedAt, ipAddress, comment }` for downstream Conditional Nodes.
+    'sendAndWaitForResponse',
+    'createDraft',
+    'sendDraft',
+    'replyToThread',
+    'getMessage',
+    'listMessages',
+    'deleteMessage',
+    'markRead',
+    'markUnread',
+    'addLabel',
+    'removeLabel',
+    'listLabels',
+    'createLabel',
+    'getThread',
+    'trashThread',
+    'untrashThread',
+];
+/** Type guard — useful when validating untrusted input (DTOs, tool calls). */
+export function isGmailOperation(value) {
+    return typeof value === 'string' && GMAIL_OPERATIONS.includes(value);
+}
+/**
+ * Esquema de formulario, grupos del desplegable y toolkits de Gmail.
+ *
+ * El enum de arriba ya estaba aquí y ya lo importaban la api (DTO + entidad) y
+ * el dashboard. Lo que baja ahora es todo lo demás, que vivía escrito a mano en
+ * cuatro sitios:
+ *
+ *   - `OP_SCHEMA` de `OperationFieldsRenderer.tsx` — 17 ops, 53 campos
+ *   - `OPERATION_GROUPS` de `OperationSelector.tsx` — 16 ops con etiqueta,
+ *     descripción y grupo
+ *   - `GMAIL_OPERATION_SPECS` del dashboard y **la misma lista otra vez** en
+ *     `api/src/mcp-servers/toolkit-specs.ts` — 16 herramientas cada una
+ *   - `NATIVE_EMAIL_OPERATION_SPECS`, igual, por duplicado
+ *
+ * Las dos copias del toolkit estaban idénticas el día de la mudanza (0
+ * divergencias medidas), lo cual es suerte y no diseño: viven en repos
+ * distintos, así que **ningún test podía compararlas**. Por eso bajan.
+ *
+ * OJO CON EL NOMBRE. En el dashboard `GMAIL_OPERATION_SPECS` eran las specs del
+ * *toolkit*, al revés que en los otros diez nodos. Aquí se respeta la convención
+ * del paquete: `*_OPERATION_SPECS` es el **formulario** y `*_TOOLKIT_SPECS` son
+ * las **herramientas**.
+ */
+/** Encabezados del desplegable, en orden de aparición. */
+export const GMAIL_OPERATION_GROUPS = ['Messages', 'Drafts', 'Labels', 'Threads'];
+/**
+ * El orden de las claves dentro de cada grupo **es** el orden del desplegable,
+ * igual que en Contacts: mover una clave mueve la pantalla.
+ *
+ * `send` ya no lleva `cc` ni `bcc`. Estaban declaradas y no se pintaban nunca —el
+ * renderizador se invocaba tras `operation !== "send"`— y la ruta determinista no
+ * las sabe mandar: `emailSender.send` recibe to/subject/html y nada más. Darles
+ * soporte es una función nueva, no una mudanza.
+ */
+export const GMAIL_OPERATION_SPECS = {
+    send: {
+        label: 'Send message',
+        labelShort: 'SEND',
+        description: 'Send a new email',
+        group: 'Messages',
+        params: [
+            { name: 'to', label: 'To', type: 'emails', required: true, placeholder: '{{payload.email}}' },
+            { name: 'subject', label: 'Subject', type: 'string', required: true, placeholder: 'Order #{{payload.id}}' },
+            { name: 'body', label: 'Body (HTML)', type: 'htmlTemplate', required: true, placeholder: '<p>Hi {{payload.name}}...</p>', language: 'html' },
+        ],
+    },
+    sendAndWaitForResponse: {
+        label: 'Send and wait for response',
+        labelShort: 'SEND & WAIT',
+        description: 'Send with Approve / Disapprove buttons; pause workflow until clicked',
+        group: 'Messages',
+        params: [
+            { name: 'to', label: 'To', type: 'emails', required: true, placeholder: '{{payload.email}}', description: 'Recipient(s) who will see the Approve / Disapprove buttons.' },
+            { name: 'subject', label: 'Subject', type: 'string', required: true, placeholder: 'Approve order #{{payload.id}}?' },
+            { name: 'body', label: 'Body (HTML)', type: 'htmlTemplate', required: true, placeholder: '<p>Please review and approve...</p>', language: 'html', description: 'Approve / Disapprove buttons are appended automatically below your content.' },
+            { name: 'approveLabel', label: 'Approve button label', type: 'string', placeholder: 'Approve', description: 'Default: Approve' },
+            { name: 'includeDisapprove', label: 'Include Disapprove button', type: 'boolean', description: 'Off = approve-only confirmation. Default: on.' },
+            { name: 'disapproveLabel', label: 'Disapprove button label', type: 'string', placeholder: 'Disapprove', description: 'Only used when Disapprove button is enabled.' },
+            { name: 'requireDisapproveComment', label: 'Require comment on disapprove', type: 'boolean', description: 'Off = 1-click decline. On = recipient sees a feedback form before submitting; the comment lands in payload._waitResponse.comment for downstream AI/Conditional nodes to read.' },
+            { name: 'disapproveCommentLabel', label: 'Comment form label', type: 'string', placeholder: 'Why are you disapproving?', description: "Heading shown above the textarea. Only used when 'Require comment' is on." },
+            { name: 'disapproveCommentPlaceholder', label: 'Comment placeholder', type: 'string', placeholder: 'Tell the sender why — this helps them improve the next attempt.', description: "Hint shown inside the empty textarea. Only used when 'Require comment' is on." },
+            { name: 'timeoutMinutes', label: 'Timeout (minutes)', type: 'number', placeholder: '1440', description: 'Auto-resolve as approved=false after this many minutes. Default 1440 (24h).' },
+        ],
+    },
+    createDraft: {
+        label: 'Create draft',
+        labelShort: 'DRAFT',
+        description: 'Save a draft without sending',
+        group: 'Drafts',
+        params: [
+            { name: 'to', label: 'To', type: 'emails', required: true, placeholder: '{{payload.email}}', description: 'Recipients the draft will be addressed to' },
+            { name: 'subject', label: 'Subject', type: 'string', placeholder: 'Draft: {{payload.topic}}' },
+            { name: 'body', label: 'Body (HTML)', type: 'htmlTemplate', language: 'html' },
+            { name: 'cc', label: 'CC', type: 'emails' },
+            { name: 'bcc', label: 'BCC', type: 'emails' },
+            { name: 'threadId', label: 'Thread ID', type: 'string', description: 'Optional — attach draft to an existing thread' },
+            { name: 'inReplyTo', label: 'In-Reply-To', type: 'string', description: 'Optional Message-ID header' },
+            { name: 'references', label: 'References', type: 'string', description: 'Optional References chain' },
+        ],
+    },
+    sendDraft: {
+        label: 'Send draft',
+        labelShort: 'SEND DRAFT',
+        description: 'Send a draft that createDraft already saved, in one shot',
+        params: [
+            { name: 'draftId', label: 'Draft ID', type: 'string', required: true, placeholder: '{{payload.draftId}}', description: 'Id returned by createDraft. The draft moves from Drafts/ to Sent/ in one shot — no orphans.' },
+        ],
+    },
+    replyToThread: {
+        label: 'Reply to thread',
+        labelShort: 'REPLY',
+        description: 'Reply preserving thread headers',
+        group: 'Messages',
+        params: [
+            { name: 'threadId', label: 'Thread ID', type: 'string', required: true, placeholder: '{{payload.threadId}}' },
+            { name: 'body', label: 'Body (HTML)', type: 'htmlTemplate', required: true, language: 'html' },
+            { name: 'subject', label: 'Subject', type: 'string', description: 'Optional — defaults to "Re: <original>"' },
+            { name: 'to', label: 'To', type: 'emails', description: 'Optional — defaults to last sender in thread' },
+            { name: 'cc', label: 'CC', type: 'emails' },
+            { name: 'bcc', label: 'BCC', type: 'emails' },
+        ],
+    },
+    getMessage: {
+        label: 'Get message',
+        labelShort: 'GET',
+        description: 'Fetch a single message by id',
+        group: 'Messages',
+        params: [
+            { name: 'messageId', label: 'Message ID', type: 'string', required: true, placeholder: '{{payload.messageId}}' },
+            { name: 'format', label: 'Format', type: 'select', options: [{ value: 'full', label: 'full' }, { value: 'metadata', label: 'metadata' }, { value: 'minimal', label: 'minimal' }] },
+        ],
+    },
+    listMessages: {
+        label: 'List messages',
+        labelShort: 'LIST',
+        description: 'Search inbox (Gmail query syntax)',
+        group: 'Messages',
+        params: [
+            { name: 'query', label: 'Query', type: 'string', placeholder: 'from:alice@example.com is:unread', description: 'Gmail search query — supports operators like from:, is:, has:, newer_than:' },
+            { name: 'labelIds', label: 'Label IDs', type: 'csvList', placeholder: 'INBOX,UNREAD', description: 'Comma-separated label IDs (use Gmail listLabels op to discover)' },
+            { name: 'maxResults', label: 'Max results', type: 'number', placeholder: '25' },
+            { name: 'includeSpamTrash', label: 'Include spam + trash', type: 'boolean' },
+            { name: 'expand', label: 'Expand each result (≤20)', type: 'boolean', description: 'Fetch headers + snippet per message. Off = id+threadId stubs only.' },
+            { name: 'expandFormat', label: 'Expand format', type: 'select', options: [{ value: 'metadata', label: 'Metadata (headers + snippet)' }, { value: 'full', label: 'Full body (expensive)' }], description: 'metadata = ~150-char snippet (default, cheap). full = entire body (expensive on tokens).' },
+        ],
+    },
+    deleteMessage: {
+        label: 'Delete message',
+        labelShort: 'DELETE',
+        description: 'Trash (default) or hard delete',
+        group: 'Messages',
+        params: [
+            { name: 'messageId', label: 'Message ID', type: 'string', required: true },
+            { name: 'permanent', label: 'Permanent delete (otherwise moves to trash)', type: 'boolean' },
+        ],
+    },
+    markRead: {
+        label: 'Mark as read',
+        labelShort: 'MARK READ',
+        description: 'Remove UNREAD label',
+        group: 'Messages',
+        params: [
+            { name: 'messageId', label: 'Message ID', type: 'string', required: true },
+        ],
+    },
+    markUnread: {
+        label: 'Mark as unread',
+        labelShort: 'MARK UNREAD',
+        description: 'Add UNREAD label',
+        group: 'Messages',
+        params: [
+            { name: 'messageId', label: 'Message ID', type: 'string', required: true },
+        ],
+    },
+    addLabel: {
+        label: 'Add label',
+        labelShort: 'ADD LABEL',
+        description: 'Attach label IDs to a message',
+        group: 'Messages',
+        params: [
+            { name: 'messageId', label: 'Message ID', type: 'string', required: true },
+            { name: 'labelIds', label: 'Label IDs to add', type: 'csvList', required: true, placeholder: 'Label_12345', description: 'Comma-separated' },
+        ],
+    },
+    removeLabel: {
+        label: 'Remove label',
+        labelShort: 'REMOVE LABEL',
+        description: 'Detach label IDs from a message',
+        group: 'Messages',
+        params: [
+            { name: 'messageId', label: 'Message ID', type: 'string', required: true },
+            { name: 'labelIds', label: 'Label IDs to remove', type: 'csvList', required: true, placeholder: 'Label_12345' },
+        ],
+    },
+    listLabels: {
+        label: 'List labels',
+        labelShort: 'LABELS',
+        description: 'All user + system labels',
+        group: 'Labels',
+        params: [],
+    },
+    createLabel: {
+        label: 'Create label',
+        labelShort: 'NEW LABEL',
+        description: 'New user label (supports / for nesting)',
+        group: 'Labels',
+        params: [
+            { name: 'name', label: 'Label name', type: 'string', required: true, placeholder: 'Clients/Active', description: 'Use / for nested labels' },
+            { name: 'messageListVisibility', label: 'Message list visibility', type: 'select', options: [{ value: 'show', label: 'show' }, { value: 'hide', label: 'hide' }] },
+            { name: 'labelListVisibility', label: 'Label list visibility', type: 'select', options: [{ value: 'labelShow', label: 'labelShow' }, { value: 'labelShowIfUnread', label: 'labelShowIfUnread' }, { value: 'labelHide', label: 'labelHide' }] },
+        ],
+    },
+    getThread: {
+        label: 'Get thread',
+        labelShort: 'THREAD',
+        description: 'Fetch an entire conversation',
+        group: 'Threads',
+        params: [
+            { name: 'threadId', label: 'Thread ID', type: 'string', required: true },
+            { name: 'format', label: 'Format', type: 'select', options: [{ value: 'full', label: 'full' }, { value: 'metadata', label: 'metadata' }, { value: 'minimal', label: 'minimal' }] },
+        ],
+    },
+    trashThread: {
+        label: 'Trash thread',
+        labelShort: 'TRASH',
+        description: 'Move all thread messages to trash',
+        group: 'Threads',
+        params: [
+            { name: 'threadId', label: 'Thread ID', type: 'string', required: true },
+        ],
+    },
+    untrashThread: {
+        label: 'Untrash thread',
+        labelShort: 'UNTRASH',
+        description: 'Restore a thread from trash',
+        group: 'Threads',
+        params: [
+            { name: 'threadId', label: 'Thread ID', type: 'string', required: true },
+        ],
+    },
+};
+/*
+ * Los dos subconjuntos de las 17, **declarados**. Antes había que deducirlos de
+ * qué lista se dejaba a quién fuera, y las dos ausencias son decisiones tomadas:
+ *
+ *   - `sendDraft` no se ofrece en el desplegable porque sólo tiene sentido
+ *     detrás de un `createDraft` de la misma conversación. Sí es herramienta.
+ *   - `sendAndWaitForResponse` no es herramienta porque por esa vía no espera:
+ *     el modelo recibe algo inmediato y acaba diciendo que ya se aprobó. Sí se
+ *     ofrece en el desplegable, con un Conditional detrás leyendo
+ *     `_waitResponse.approved`.
+ *
+ * Que cada una siga teniendo 16 lo fija un test. No las "arregles".
+ */
+export const GMAIL_DROPDOWN_OPERATIONS = GMAIL_OPERATIONS.filter((op) => GMAIL_OPERATION_SPECS[op].group !== undefined);
+export const GMAIL_TOOLKIT_OPERATIONS = GMAIL_OPERATIONS.filter((op) => op !== 'sendAndWaitForResponse');
+const p = (name, description, required = true, type = 'string') => ({ name, type, description, required });
+export const GMAIL_TOOLKIT_SPECS = [
+    {
+        operation: 'send',
+        label: 'Send message',
+        toolName: 'send_email',
+        description: 'Send a fresh Gmail message that you compose from scratch right now. USAGE RULES: (1) ' +
+            'Only use this when the user asks for a brand-new email and there is NO recent draft to ' +
+            'confirm. (2) If you previously called createDraft in this conversation and the user just ' +
+            'confirmed it, do NOT call send — call sendDraft with that draftId instead. Calling send ' +
+            're-composes the message from your memory and risks sending stale content from an earlier ' +
+            "conversation. (3) Compose the body fresh from the user's CURRENT request. Never reuse " +
+            'content recalled from memory unless the user explicitly references it. (4) Not for ' +
+            'replies inside an existing thread — use replyToThread for that.',
+        parameters: [
+            p('to', 'Recipient email address(es). Single string or comma-separated list.'),
+            p('subject', 'Email subject line.'),
+            p('body', 'HTML-formatted email body.'),
+            p('cc', 'Optional CC recipients.', false),
+            p('bcc', 'Optional BCC recipients.', false),
+        ],
+    },
+    {
+        operation: 'createDraft',
+        label: 'Create draft',
+        toolName: 'draft_email',
+        description: "Save a draft in the user's Gmail drafts folder. Does NOT send. Use when asked to draft, " +
+            'prepare, or compose without sending. USAGE RULES: (1) Compose the body fresh from the ' +
+            "user's CURRENT request. Never reuse content recalled from memory unless the user " +
+            "explicitly says 'use the same content as before' or similar. (2) Always return the " +
+            'draftId in your response so the user (and you, on the next turn) can reference it. (3) ' +
+            'After creating, ask the user to confirm. If they confirm, call sendDraft with the ' +
+            'returned draftId — never re-call this tool or send.',
+        parameters: [
+            p('to', 'Recipient email address(es).'),
+            p('subject', 'Email subject line.', false),
+            p('body', 'HTML-formatted email body.', false),
+            p('cc', 'Optional CC recipients.', false),
+            p('bcc', 'Optional BCC recipients.', false),
+            p('threadId', 'Optional — attach draft to an existing thread.', false),
+            p('inReplyTo', 'Optional Message-ID header to reply to.', false),
+            p('references', 'Optional References header chain.', false),
+        ],
+    },
+    {
+        operation: 'sendDraft',
+        label: 'Send draft',
+        toolName: 'send_draft',
+        description: 'Send an existing draft (it gets removed from Drafts and a copy appears in Sent). USAGE ' +
+            'RULES: (1) Only call this with a draftId returned by a createDraft tool call earlier in ' +
+            'THE CURRENT conversation. (2) Never use a draftId you remember from past conversations ' +
+            'or memory recall — those drafts may have been already sent, deleted, or belonged to a ' +
+            'different topic; sending the wrong one will silently deliver the wrong message to the ' +
+            "user's contacts. (3) If the user confirms a draft, immediately call sendDraft with the " +
+            "draftId from your latest createDraft response in this conversation. (4) If you're not " +
+            'sure which draftId is current, call createDraft again with the latest content the user ' +
+            'agreed to instead of guessing.',
+        parameters: [
+            p('draftId', 'Draft id returned by the MOST RECENT createDraft call in this conversation. Do NOT pull this id from memory or a past conversation — it will send the wrong content.'),
+        ],
+    },
+    {
+        operation: 'replyToThread',
+        label: 'Reply to thread',
+        toolName: 'reply_email',
+        description: 'Reply to an existing Gmail thread preserving thread integrity (In-Reply-To / References ' +
+            'chain). Recipient defaults to the last sender if not provided. USAGE RULES: (1) Compose ' +
+            "the reply body fresh from the user's CURRENT request. Never reuse content recalled from " +
+            'memory of past replies unless the user explicitly references it. (2) Use the threadId ' +
+            'from a getThread / listMessages tool call EARLIER IN THIS CONVERSATION, not from memory ' +
+            'of past conversations.',
+        parameters: [
+            p('threadId', 'Thread to reply to.'),
+            p('body', 'HTML-formatted reply body.'),
+            p('to', 'Optional — defaults to last sender in thread.', false),
+            p('subject', 'Optional — defaults to "Re: <original>".', false),
+            p('cc', 'Optional CC recipients.', false),
+            p('bcc', 'Optional BCC recipients.', false),
+        ],
+    },
+    {
+        operation: 'getMessage',
+        label: 'Get message',
+        toolName: 'get_email',
+        description: 'Fetch a single Gmail message by id. Returns headers, snippet, and decoded plain+HTML ' +
+            'body.',
+        parameters: [
+            p('messageId', 'Gmail message id.'),
+            p('format', 'full | metadata | minimal.', false),
+        ],
+    },
+    {
+        operation: 'listMessages',
+        label: 'List messages',
+        toolName: 'list_emails',
+        description: 'Search the inbox. Supports Gmail search syntax (e.g. "from:boss is:unread"). Returns ' +
+            'headers + a ~150-char snippet per message by default — enough to identify which messages ' +
+            'match without flooding context with full bodies. If the user needs the full content of a ' +
+            'SPECIFIC message, call getMessage with that id afterwards (cheaper than expanding all ' +
+            'results to full).',
+        parameters: [
+            p('query', 'Gmail search query. Examples: "from:alice@x.com", "is:unread", "has:attachment newer_than:7d".', false),
+            p('labelIds', 'Filter by label id(s), comma-separated.', false),
+            p('maxResults', 'Default 25, max 500.', false, 'number'),
+            p('includeSpamTrash', 'Include spam + trash (default false).', false, 'boolean'),
+            p('expand', 'Fetch headers+snippet for each result (default true). Set false to return only id+threadId stubs.', false, 'boolean'),
+            p('expandFormat', "When expanding: 'metadata' (default — headers + snippet) or 'full' (entire body, expensive on context).", false),
+        ],
+    },
+    {
+        operation: 'deleteMessage',
+        label: 'Delete message',
+        toolName: 'delete_email',
+        description: 'Move a message to trash (default) or permanently delete it. Trash is safer — users can ' +
+            'restore.',
+        parameters: [
+            p('messageId', 'Gmail message id.'),
+            p('permanent', 'true = permanent delete, false/default = trash.', false, 'boolean'),
+        ],
+    },
+    {
+        operation: 'markRead',
+        label: 'Mark as read',
+        toolName: 'mark_email_read',
+        description: 'Mark a message as read (removes the UNREAD label).',
+        parameters: [
+            p('messageId', 'Gmail message id.'),
+        ],
+    },
+    {
+        operation: 'markUnread',
+        label: 'Mark as unread',
+        toolName: 'mark_email_unread',
+        description: 'Mark a message as unread (adds the UNREAD label).',
+        parameters: [
+            p('messageId', 'Gmail message id.'),
+        ],
+    },
+    {
+        operation: 'addLabel',
+        label: 'Add label to message',
+        toolName: 'add_email_label',
+        description: 'Add one or more labels to a message. Use label IDs from listLabels (e.g. "Label_123") ' +
+            'not label names.',
+        parameters: [
+            p('messageId', 'Gmail message id.'),
+            p('labelIds', 'Label id(s) to add, comma-separated.'),
+        ],
+    },
+    {
+        operation: 'removeLabel',
+        label: 'Remove label from message',
+        toolName: 'remove_email_label',
+        description: 'Remove one or more labels from a message.',
+        parameters: [
+            p('messageId', 'Gmail message id.'),
+            p('labelIds', 'Label id(s) to remove, comma-separated.'),
+        ],
+    },
+    {
+        operation: 'listLabels',
+        label: 'List labels',
+        toolName: 'list_email_labels',
+        description: "List all labels in the user's Gmail account (system + user labels). Use to discover " +
+            'label ids before calling addLabel / removeLabel.',
+        parameters: [],
+    },
+    {
+        operation: 'createLabel',
+        label: 'Create label',
+        toolName: 'create_email_label',
+        description: "Create a new user label in the user's Gmail account.",
+        parameters: [
+            p('name', 'Label name (can use / for nested labels, e.g. "Clients/Active").'),
+            p('messageListVisibility', 'show | hide.', false),
+            p('labelListVisibility', 'labelShow | labelShowIfUnread | labelHide.', false),
+        ],
+    },
+    {
+        operation: 'getThread',
+        label: 'Get thread',
+        toolName: 'get_email_thread',
+        description: 'Fetch an entire Gmail thread with all its messages. Use for summarizing or deeply ' +
+            'analyzing a conversation.',
+        parameters: [
+            p('threadId', 'Gmail thread id.'),
+            p('format', 'full | metadata | minimal.', false),
+        ],
+    },
+    {
+        operation: 'trashThread',
+        label: 'Trash thread',
+        toolName: 'trash_email_thread',
+        description: 'Move an entire thread to trash.',
+        parameters: [
+            p('threadId', 'Gmail thread id.'),
+        ],
+    },
+    {
+        operation: 'untrashThread',
+        label: 'Untrash thread',
+        toolName: 'untrash_email_thread',
+        description: 'Restore a thread from trash.',
+        parameters: [
+            p('threadId', 'Gmail thread id.'),
+        ],
+    },
+];
+/**
+ * La op que espera, **fuera** del toolkit y aparte a propósito. Sigue haciendo
+ * falta para dos cosas que no son el toolkit: reconocer la operación de una
+ * herramienta ya guardada (si desapareciera, un `send_email_and_wait` creado antes
+ * se quedaría sin etiqueta) y el modo de una sola op elegido como herramienta
+ * suelta, donde el pipeline sí espera el clic.
+ */
+export const GMAIL_SEND_AND_WAIT_TOOL_SPEC = {
+    operation: 'sendAndWaitForResponse',
+    label: 'Send and wait for response',
+    toolName: 'send_email_and_wait',
+    description: 'Send an email with Approve / Disapprove buttons and PAUSE the pipeline until the ' +
+        'recipient clicks one. Resumes downstream with `payload._waitResponse = { approved, ' +
+        'decidedAt, ipAddress, comment }` so a Conditional Node can branch on the decision. Times ' +
+        'out after timeoutMinutes (default 24h) if nobody clicks; the timeout cron auto-resolves ' +
+        'with approved=false. Use for human-in-the-loop approvals (e.g. confirm before sending ' +
+        'money, deploying, or notifying customers).',
+    parameters: [
+        p('to', 'Recipient email address(es). Single string or comma-separated list.'),
+        p('subject', 'Email subject line.'),
+        p('body', 'HTML-formatted email body. The Approve / Disapprove buttons are appended automatically below your content.'),
+        p('approveLabel', "Optional. Approve button label. Default: 'Approve'.", false),
+        p('disapproveLabel', "Optional. Disapprove button label. Default: 'Disapprove'.", false),
+        p('includeDisapprove', 'Optional. Include the Disapprove button. Default: true. Set to false for approve-only confirmations.', false),
+        p('timeoutMinutes', 'Optional. Minutes to wait before auto-resolving with approved=false. Default 1440 (24h).', false),
+    ],
+};
+/** Todo lo que el nodo sabe ejecutar, se ofrezca o no como herramienta. */
+export const GMAIL_ALL_TOOLKIT_SPECS = [
+    ...GMAIL_TOOLKIT_SPECS,
+    GMAIL_SEND_AND_WAIT_TOOL_SPEC,
+];
+/** El toolkit del proveedor nativo (Resend): una sola herramienta. */
+export const NATIVE_EMAIL_TOOLKIT_SPECS = [
+    {
+        operation: 'send',
+        label: 'Send email',
+        toolName: 'send_email',
+        description: 'Send a transactional email via Resend. Use for confirmations, notifications, receipts, ' +
+            'password resets. One email per call. The sender domain is fixed by the node; you cannot ' +
+            'change it per call. Body accepts HTML.',
+        parameters: [
+            p('to', 'Recipient email address(es). Single string or comma-separated list.'),
+            p('subject', 'Email subject line.'),
+            p('body', 'HTML-formatted email body.'),
+            p('cc', 'Optional CC recipients. Single string or comma-separated.', false),
+            p('bcc', 'Optional BCC recipients. Single string or comma-separated.', false),
+            p('reply_to', 'Optional Reply-To address.', false),
+            p('from_name', 'Optional display name for this specific email (overrides the node default).', false),
+            p('attachment_file_ids', 'Optional. Comma-separated list of file IDs from `_file.id` refs in the upstream payload (e.g., a File Transform output or a webhook multipart upload). Max 5 files, 30MB total. Do NOT invent IDs — only use values actually present in the current payload.', false),
+        ],
+    },
+];
+export const GMAIL_TOOLKIT_BY_TOOL_NAME = Object.fromEntries(GMAIL_ALL_TOOLKIT_SPECS.map((s) => [s.toolName, s]));
+export const NATIVE_EMAIL_TOOLKIT_BY_TOOL_NAME = Object.fromEntries(NATIVE_EMAIL_TOOLKIT_SPECS.map((s) => [s.toolName, s]));
+/** Los tres campos que un día vivieron en la raíz. */
+export const GMAIL_SEND_LEGACY_FIELDS = ['to', 'subject', 'body'];
+export function resolveGmailSendFields(entity) {
+    const cfg = (entity?.operationConfig ?? {});
+    const crudoTo = cfg.to ?? entity?.to;
+    const to = Array.isArray(crudoTo)
+        ? crudoTo.filter((x) => typeof x === 'string')
+        : typeof crudoTo === 'string' && crudoTo !== ''
+            ? [crudoTo]
+            : [];
+    const subject = cfg.subject ?? entity?.subject;
+    const body = cfg.body ?? entity?.body;
+    return {
+        to,
+        subject: typeof subject === 'string' ? subject : '',
+        body: typeof body === 'string' ? body : '',
+    };
+}

package/dist/esm/google-analytics-operations.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Google Analytics 4 operation enum — single source of truth across the API,
+ * Dashboard, and Message Broker. Used by:
+ *   - googleAnalyticsAction entity / DTO (api): operation field + validation
+ *   - dashboard GoogleAnalyticsAction operation type
+ *   - MCP toolkit specs, si algún día el nodo gana modo toolkit
+ *
+ * Mismo patrón que `drive-operations.ts` y `sheets-operations.ts`.
+ *
+ * ── Por qué sólo dos operaciones ──
+ *
+ * GA4 tiene más superficie (`runPivotReport`, `batchRunReports`,
+ * `checkCompatibility`), pero declarar una op que el servicio todavía no
+ * implementa la pinta en el desplegable y la deja fallar al ejecutarse: el
+ * enum ES el contrato de la pantalla. Entran cuando entre su código.
+ *
+ * ── Lo que NO es una operación ──
+ *
+ * Listar propiedades y listar las dimensiones/métricas disponibles NO son
+ * ops del nodo: son endpoints del controlador, que es como Drive alimenta su
+ * `DriveFilePicker` (`@Get('files/:credentialId')`). Una op existe para
+ * producir payload en una corrida; esto otro es para rellenar el formulario.
+ *
+ * ── Decisiones propias de GA (anti-n8n) ──
+ *
+ *   - La propiedad se ELIGE de una lista, no se teclea. `properties/123456789`
+ *     y `G-XXXXXXX` se confunden todo el rato y el error de GA no lo aclara.
+ *   - Las fechas admiten `NdaysAgo` / `yesterday` / `today` además de
+ *     `YYYY-MM-DD`, que es lo que acepta la API, y son el sitio donde avisar
+ *     de que el dato no está cerrado hasta pasadas ~48 h.
+ *   - El filtro común (una dimensión, un valor) son tres campos; la
+ *     `FilterExpression` cruda queda de escape en Advanced y gana si está.
+ */
+export declare const GOOGLE_ANALYTICS_OPERATIONS: readonly ["runReport", "runRealtimeReport"];
+export type GoogleAnalyticsOperation = (typeof GOOGLE_ANALYTICS_OPERATIONS)[number];
+/** Type guard — para validar entrada no fiable (DTOs, tool calls). */
+export declare function isGoogleAnalyticsOperation(value: unknown): value is GoogleAnalyticsOperation;
+export type GoogleAnalyticsParamType = 
+/** Selector vivo de propiedades GA4 (necesita credencial). */
+'analyticsProperty'
+/** Multi-selección de métricas, con las opciones vivas del metadata. */
+ | 'analyticsMetrics'
+/** Multi-selección de dimensiones, igual que las métricas. */
+ | 'analyticsDimensions'
+/** Texto con autocompletado de `{{payload.*}}`. */
+ | 'template'
+/** `<select>` normal; las etiquetas no son los valores, `options` obliga. */
+ | 'select' | 'number'
+/**
+ * `<select>` de `''` / `'true'` / `'false'` que se guarda como BOOLEANO, o
+ * no se guarda si es `''`. Mismo motivo que el `starred` de Drive: "— sin
+ * tocar —" tiene que significar que la clave no viaja.
+ */
+ | 'booleanSelect'
+/** Área de texto para JSON crudo (la FilterExpression de escape). */
+ | 'json';
+export interface GoogleAnalyticsParamSpec {
+    /** La clave de `operationConfig`. Es lo que lee la api, no un nombre de UI. */
+    name: string;
+    label: string;
+    type: GoogleAnalyticsParamType;
+    required?: boolean;
+    /** Ayuda bajo el campo. Texto plano: el paquete no lleva React. */
+    description?: string;
+    placeholder?: string;
+    /** Prerrellenado cuando la config guardada no trae valor para esta clave. */
+    default?: string | number;
+    /** Obligatorio en `select` y `booleanSelect` — etiqueta y valor difieren. */
+    options?: ReadonlyArray<{
+        value: string;
+        label: string;
+    }>;
+    min?: number;
+    max?: number;
+    /** Se pinta en la pestaña "Advanced" en vez de en "Config". */
+    advanced?: boolean;
+    /** Sólo visible cuando un campo hermano vale uno de estos. */
+    showWhen?: {
+        field: string;
+        in: ReadonlyArray<string>;
+    };
+}
+export interface GoogleAnalyticsOperationSpec {
+    /** Etiqueta de la fila en el desplegable de operación. */
+    label: string;
+    /** Sub-línea bajo la etiqueta. */
+    description: string;
+    /** Método de la API al que mapea (developers.google.com/analytics/devguides/reporting/data/v1). */
+    apiMethod: string;
+    /** Esquema de parámetros. El orden ES el orden en pantalla. */
+    params: GoogleAnalyticsParamSpec[];
+}
+export declare const GOOGLE_ANALYTICS_OPERATION_SPECS: Record<GoogleAnalyticsOperation, GoogleAnalyticsOperationSpec>;
+/**
+ * Las operaciones tal y como se listan en el desplegable. Hoy es el enum
+ * entero; existe para que añadir una op interna (sin fila propia) no obligue
+ * a que la página vuelva a decidir por su cuenta qué enseñar.
+ */
+export declare const GOOGLE_ANALYTICS_DROPDOWN_OPERATIONS: readonly GoogleAnalyticsOperation[];