@hostwebhook/node-types 1.64.0 → 1.66.0

package/dist/jira-operations.js

@@ -0,0 +1,474 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JIRA_DROPDOWN_OPERATIONS = exports.JIRA_OPERATION_SPECS = exports.JIRA_ITERABLE_OPERATIONS = exports.JIRA_OPERATIONS = void 0;
+exports.isJiraOperation = isJiraOperation;
+/**
+ * Las operaciones del nodo `jiraAction` — la lista que comparten la api, el
+ * dashboard y el broker.
+ *
+ * Mismo patrón que `github-operations.ts` y `shopify-operations.ts`.
+ *
+ * ── Contra qué está escrito ──
+ *
+ * Jira Cloud, **REST API v3**, servida en
+ * `https://api.atlassian.com/ex/jira/{cloudId}/rest/api/3/…`. El `cloudId` sale
+ * de la credencial `oauth2_atlassian`, que ya existe: la montó el trigger de
+ * Jira y aquí se reutiliza entera.
+ *
+ * El permiso que hace falta para escribir es **`write:jira-work`**. Se añadió a
+ * los de por defecto en api#384; toda credencial anterior a eso es de sólo
+ * lectura hasta que su dueño la reconecte, y el síntoma es un 403 al ejecutar,
+ * no un fallo al guardar.
+ *
+ * ── La decisión que ordena todo lo demás: ADF ──
+ *
+ * En la v3, `description` y el `body` de un comentario **no son texto**: son
+ * Atlassian Document Format, un árbol JSON de nodos tipados. Mandar una cadena
+ * da 400.
+ *
+ * La salida fácil sería escribir con la v2, que sí acepta texto plano y sigue
+ * soportada. No se hace, y el motivo está escrito en nuestro propio repositorio
+ * desde antes de este nodo: `jira-watch.service.ts` excluye `description` al
+ * hidratar campos y explica por qué — *"la REST devuelve ADF —un objeto— pero
+ * el webhook manda texto plano; mezclar formas rompería las plantillas de
+ * abajo, que esperan cadenas"*.
+ *
+ * O sea: si este nodo leyera con una versión y escribiera con otra,
+ * `{{payload.fields.description}}` significaría una cosa cuando el flujo lo
+ * dispara un trigger de Jira y otra cuando lo consulta este nodo. Por eso:
+ *
+ *   - **Todo en v3**, para leer y para escribir.
+ *   - Al escribir, el texto del usuario se envuelve en ADF.
+ *   - Al leer, el ADF se aplana a texto, y el árbol original viaja en una clave
+ *     hermana para quien lo necesite.
+ *   - `bodyFormat` deja pegar ADF crudo a quien quiera tablas o paneles.
+ *
+ * ── La otra trampa: la búsqueda cambió de sitio ──
+ *
+ * `GET/POST /rest/api/3/search` está **deprecado**. El sustituto es
+ * `POST /rest/api/3/search/jql`, y no es un renombre: pagina con
+ * `nextPageToken` en vez de `startAt`, **no devuelve `total`** (para contar hay
+ * `/search/approximate-count`) y los campos hay que pedirlos explícitamente.
+ * Casi todo ejemplo que hay por internet usa el endpoint muerto.
+ *
+ * ── Lo que NO es una operación ──
+ *
+ * Listar proyectos, tipos de incidencia, transiciones, estados o usuarios
+ * asignables **no** son operaciones: son endpoints del controlador que alimentan
+ * los selectores, como Drive alimenta su selector de ficheros. Una operación
+ * existe para producir payload en una corrida; esto otro es para rellenar el
+ * formulario. Mezclarlos llena el desplegable de cosas que nadie quiere
+ * ejecutar.
+ *
+ * ── Decisiones propias de Jira ──
+ *
+ *   - El proyecto y el tipo de incidencia se ELIGEN de una lista viva. Un
+ *     `issuetype` se identifica por un id numérico que nadie sabe de memoria.
+ *   - **Las transiciones no son una lista fija.** Dependen del flujo de trabajo
+ *     Y del estado actual de la incidencia, así que el selector las pide para
+ *     esa incidencia concreta. Ofrecer una lista global sería ofrecer
+ *     transiciones que fallan al ejecutarse.
+ *   - Los campos personalizados van en JSON crudo. Cada tipo tiene su forma
+ *     (`select`, `date`, `relation`, usuario…) y fingir que caben en tres
+ *     campos genéricos produce un 400 que no nombra el campo.
+ *   - Ninguna operación declarada sin implementar: el enum ES el contrato de la
+ *     pantalla, y una operación declarada se pinta en el desplegable y falla al
+ *     ejecutarse.
+ */
+exports.JIRA_OPERATIONS = [
+    // Incidencias
+    'createIssue', // POST   /issue
+    'getIssue', // GET    /issue/{key}
+    'updateIssue', // PUT    /issue/{key}
+    'deleteIssue', // DELETE /issue/{key}
+    'assignIssue', // PUT    /issue/{key}/assignee
+    'transitionIssue', // POST   /issue/{key}/transitions
+    // Comentarios
+    'addComment', // POST   /issue/{key}/comment
+    'getComments', // GET    /issue/{key}/comment      → iterable
+    // Adjuntos y trabajo
+    'addAttachment', // POST   /issue/{key}/attachments
+    'addWorklog', // POST   /issue/{key}/worklog
+    // Relaciones
+    'linkIssues', // POST   /issueLink
+    // Transversal
+    'searchIssues', // POST   /search/jql              → iterable
+];
+/** Type guard — para validar entrada no fiable (DTOs, tool calls). */
+function isJiraOperation(value) {
+    return (typeof value === 'string' &&
+        exports.JIRA_OPERATIONS.includes(value));
+}
+/**
+ * Las operaciones que devuelven un ARRAY y por tanto obligan a marcar
+ * `_meta.iterable` en `getOutputPayload`.
+ *
+ * Vive aquí y no sólo en la api porque olvidarlo no falla al compilar: falla
+ * en producción, callado, con el nodo de abajo recibiendo el sobre entero en
+ * vez de un elemento y el PayloadViewer pintando rutas con corchetes que nadie
+ * puede usar.
+ */
+exports.JIRA_ITERABLE_OPERATIONS = [
+    'getComments',
+    'searchIssues',
+];
+/* Ayudantes — repetir el mismo objeto doce veces es cómo se desincronizan las
+   descripciones. */
+const project = (required = true) => ({
+    name: 'projectKey',
+    label: 'Project',
+    type: 'jiraProject',
+    required,
+    description: 'De la lista de proyectos que alcanza esta credencial. Se guarda la clave (ACME).',
+});
+const issueKey = (label = 'Issue') => ({
+    name: 'issueKey',
+    label,
+    type: 'jiraIssueKey',
+    required: true,
+    placeholder: '{{payload.issueKey}}',
+    description: 'La clave que se ve en la URL (ACME-42), no el id interno. El trigger de Jira la deja en issueKey.',
+});
+/**
+ * El interruptor de formato para todo campo que Jira quiere en ADF.
+ *
+ * Por defecto `text`: se escribe normal y el nodo lo envuelve. `adf` es la
+ * salida para quien necesita tablas, paneles o menciones — cosas que el texto
+ * plano no sabe expresar y que no vale la pena inventarse un lenguaje para
+ * cubrir.
+ */
+const bodyFormat = () => ({
+    name: 'bodyFormat',
+    label: 'Format',
+    type: 'select',
+    default: 'text',
+    advanced: true,
+    options: [
+        { value: 'text', label: 'Plain text (se convierte a ADF)' },
+        { value: 'adf', label: 'Atlassian Document Format en crudo' },
+    ],
+    description: 'Jira v3 guarda estos campos como ADF. En "plain text" el nodo lo envuelve por ti: un párrafo por bloque y salto de línea donde lo escribas.',
+});
+const customFields = () => ({
+    name: 'customFields',
+    label: 'Other fields (JSON)',
+    type: 'json',
+    advanced: true,
+    placeholder: '{ "customfield_10042": { "accountId": "..." }, "labels": ["urgente"] }',
+    description: 'Se mezcla tal cual dentro de `fields`. Cada tipo de campo de Jira tiene su forma; el esquema real se lee con el selector de campos de la pantalla.',
+});
+const maxResults = () => ({
+    name: 'maxResults',
+    label: 'How many at most',
+    type: 'number',
+    default: 50,
+    min: 1,
+    max: 100,
+    advanced: true,
+    description: 'Jira no devuelve más de 100 por página.',
+});
+exports.JIRA_OPERATION_SPECS = {
+    createIssue: {
+        label: 'Create issue',
+        description: 'Crea una incidencia en un proyecto.',
+        apiRoute: 'POST /rest/api/3/issue',
+        params: [
+            project(),
+            {
+                name: 'issueTypeId',
+                label: 'Issue type',
+                type: 'jiraIssueType',
+                required: true,
+                description: 'Los tipos son del proyecto, no globales: se piden después de elegirlo.',
+            },
+            {
+                name: 'summary',
+                label: 'Summary',
+                type: 'template',
+                required: true,
+                placeholder: 'Fallo al exportar el informe',
+                description: 'El título. Es el único campo que Jira exige siempre.',
+            },
+            {
+                name: 'description',
+                label: 'Description',
+                type: 'textarea',
+                placeholder: 'Lo que pasó, con {{payload.x}} si hace falta.',
+            },
+            bodyFormat(),
+            {
+                name: 'assigneeAccountId',
+                label: 'Assignee',
+                type: 'jiraUser',
+                advanced: true,
+                description: 'Se guarda el accountId, que es como lo pide Jira.',
+            },
+            {
+                name: 'parentKey',
+                label: 'Parent issue',
+                type: 'template',
+                advanced: true,
+                placeholder: 'ACME-10',
+                description: 'Sólo para subtareas: la incidencia padre. Con un tipo que no sea subtarea, Jira lo rechaza.',
+            },
+            customFields(),
+        ],
+    },
+    getIssue: {
+        label: 'Get issue',
+        description: 'Lee una incidencia por su clave.',
+        apiRoute: 'GET /rest/api/3/issue/{issueIdOrKey}',
+        params: [
+            issueKey(),
+            {
+                name: 'fields',
+                label: 'Fields',
+                type: 'template',
+                advanced: true,
+                placeholder: 'summary,status,assignee',
+                description: 'Separados por comas. Vacío trae los de siempre. Pedir sólo lo que usas hace la respuesta mucho más pequeña.',
+            },
+        ],
+    },
+    updateIssue: {
+        label: 'Update issue',
+        description: 'Cambia campos de una incidencia.',
+        apiRoute: 'PUT /rest/api/3/issue/{issueIdOrKey}',
+        params: [
+            issueKey(),
+            {
+                name: 'summary',
+                label: 'Summary',
+                type: 'template',
+                description: 'Vacío = no se toca.',
+            },
+            {
+                name: 'description',
+                label: 'Description',
+                type: 'textarea',
+                description: 'Vacío = no se toca. REEMPLAZA la descripción entera.',
+            },
+            bodyFormat(),
+            customFields(),
+        ],
+    },
+    deleteIssue: {
+        label: 'Delete issue',
+        description: 'Borra una incidencia. No hay papelera.',
+        apiRoute: 'DELETE /rest/api/3/issue/{issueIdOrKey}',
+        params: [
+            issueKey(),
+            {
+                name: 'deleteSubtasks',
+                label: 'Delete its subtasks too',
+                type: 'booleanSelect',
+                options: [
+                    { value: '', label: '— sin tocar —' },
+                    { value: 'true', label: 'Sí, borrar las subtareas' },
+                    { value: 'false', label: 'No' },
+                ],
+                description: 'Con subtareas y sin esto, Jira se niega a borrar y devuelve 400.',
+            },
+        ],
+    },
+    assignIssue: {
+        label: 'Assign issue',
+        description: 'Cambia a quién está asignada.',
+        apiRoute: 'PUT /rest/api/3/issue/{issueIdOrKey}/assignee',
+        params: [
+            issueKey(),
+            {
+                name: 'accountId',
+                label: 'Assignee',
+                type: 'jiraUser',
+                required: true,
+                description: 'Vacío deja la incidencia sin asignar.',
+            },
+        ],
+    },
+    transitionIssue: {
+        label: 'Move issue',
+        description: 'Mueve la incidencia de columna (transición del flujo).',
+        apiRoute: 'POST /rest/api/3/issue/{issueIdOrKey}/transitions',
+        params: [
+            issueKey(),
+            {
+                name: 'transitionId',
+                label: 'Transition',
+                type: 'jiraTransition',
+                required: true,
+                description: 'Las transiciones legales dependen del flujo de trabajo Y del estado actual, así que se piden para esta incidencia. Una que no aplique falla al ejecutarse.',
+            },
+            {
+                name: 'comment',
+                label: 'Comment (optional)',
+                type: 'textarea',
+                advanced: true,
+                description: 'Jira permite comentar en el mismo paso de la transición.',
+            },
+            bodyFormat(),
+        ],
+    },
+    addComment: {
+        label: 'Add comment',
+        description: 'Comenta en una incidencia.',
+        apiRoute: 'POST /rest/api/3/issue/{issueIdOrKey}/comment',
+        params: [
+            issueKey(),
+            {
+                name: 'body',
+                label: 'Comment',
+                type: 'textarea',
+                required: true,
+                placeholder: 'Desplegado en producción: {{payload.version}}',
+            },
+            bodyFormat(),
+        ],
+    },
+    getComments: {
+        label: 'Get comments',
+        description: 'Trae los comentarios de una incidencia.',
+        apiRoute: 'GET /rest/api/3/issue/{issueIdOrKey}/comment',
+        params: [
+            issueKey(),
+            {
+                name: 'orderBy',
+                label: 'Order',
+                type: 'select',
+                default: '-created',
+                advanced: true,
+                options: [
+                    { value: '-created', label: 'Los más nuevos primero' },
+                    { value: 'created', label: 'Los más viejos primero' },
+                ],
+            },
+            maxResults(),
+        ],
+    },
+    addAttachment: {
+        label: 'Attach file',
+        description: 'Sube un fichero a una incidencia.',
+        apiRoute: 'POST /rest/api/3/issue/{issueIdOrKey}/attachments',
+        params: [
+            issueKey(),
+            {
+                name: 'fileField',
+                label: 'File from payload',
+                type: 'template',
+                required: true,
+                placeholder: '{{payload.file}}',
+                description: 'La ruta del payload donde viene el fichero — lo que dejan el nodo de ficheros o un adjunto de Gmail.',
+            },
+            {
+                name: 'fileName',
+                label: 'File name',
+                type: 'template',
+                advanced: true,
+                placeholder: 'informe.pdf',
+                description: 'Vacío usa el nombre que traiga el propio fichero.',
+            },
+        ],
+    },
+    addWorklog: {
+        label: 'Log work',
+        description: 'Apunta tiempo trabajado en una incidencia.',
+        apiRoute: 'POST /rest/api/3/issue/{issueIdOrKey}/worklog',
+        params: [
+            issueKey(),
+            {
+                name: 'timeSpent',
+                label: 'Time spent',
+                type: 'template',
+                required: true,
+                placeholder: '3h 30m',
+                description: 'En el formato de Jira: 2d, 3h, 30m, o combinados. No admite decimales.',
+            },
+            {
+                name: 'comment',
+                label: 'Comment',
+                type: 'textarea',
+                advanced: true,
+            },
+            bodyFormat(),
+            {
+                name: 'started',
+                label: 'When',
+                type: 'template',
+                advanced: true,
+                placeholder: '{{payload.timestamp}}',
+                description: 'Vacío usa el momento de la ejecución.',
+            },
+        ],
+    },
+    linkIssues: {
+        label: 'Link issues',
+        description: 'Relaciona dos incidencias entre sí.',
+        apiRoute: 'POST /rest/api/3/issueLink',
+        params: [
+            {
+                name: 'inwardIssueKey',
+                label: 'From issue',
+                type: 'jiraIssueKey',
+                required: true,
+                placeholder: '{{payload.issueKey}}',
+            },
+            {
+                name: 'linkType',
+                label: 'Relationship',
+                type: 'jiraLinkType',
+                required: true,
+                description: 'Los tipos los define cada sitio: "Blocks", "Relates", "Duplicates"… Se piden a Jira.',
+            },
+            {
+                name: 'outwardIssueKey',
+                label: 'To issue',
+                type: 'jiraIssueKey',
+                required: true,
+                placeholder: 'ACME-99',
+            },
+        ],
+    },
+    searchIssues: {
+        label: 'Search issues (JQL)',
+        description: 'Busca incidencias con JQL. Devuelve una lista iterable.',
+        /* ⚠️ `/search/jql`, NO `/search`. El viejo está deprecado y pagina distinto:
+           `nextPageToken` en vez de `startAt`, y sin `total` en la respuesta. */
+        apiRoute: 'POST /rest/api/3/search/jql',
+        params: [
+            {
+                name: 'jql',
+                label: 'JQL',
+                type: 'textarea',
+                required: true,
+                placeholder: 'project = ACME AND status != Done ORDER BY created DESC',
+                description: 'La misma consulta que escribirías en el buscador de Jira. Admite {{payload.x}}.',
+            },
+            {
+                name: 'fields',
+                label: 'Fields',
+                type: 'template',
+                advanced: true,
+                placeholder: 'summary,status,assignee',
+                description: 'Separados por comas. En este endpoint los campos hay que pedirlos: sin esto sólo llegan las claves.',
+            },
+            maxResults(),
+            {
+                name: 'nextPageToken',
+                label: 'Page token',
+                type: 'template',
+                advanced: true,
+                placeholder: '{{payload.nextPageToken}}',
+                description: 'Para pedir la página siguiente desde un Loop. La salida de esta operación lo devuelve.',
+            },
+        ],
+    },
+};
+/**
+ * Lo que se ofrece en el desplegable de operación.
+ *
+ * Hoy son todas. Existe como constante aparte —y no como alias de
+ * `JIRA_OPERATIONS`— porque es el punto donde otros nodos han necesitado
+ * esconder una operación sin sacarla del enum: retirarla del enum rompe las que
+ * ya estaban guardadas en la base de datos.
+ */
+exports.JIRA_DROPDOWN_OPERATIONS = exports.JIRA_OPERATIONS;

package/dist/registry.js

@@ -301,6 +301,25 @@ exports.NODE_REGISTRY = {
            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',

package/dist/slack-toolkit.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Slack AI Toolkit — las herramientas que un slackAction expone cuando
+ * `aiEnabled` está encendido.
+ *
+ * **Se escribe una sola vez.** Antes vivía dos veces: una copia en
+ * `dashboard/components/slack-actions/slack-operations-schemas.ts` y otra en
+ * `api/src/mcp-servers/toolkit-specs.ts`, las dos a mano y en repos distintos,
+ * así que ningún test podía compararlas. Es la octava y novena mudanza de esta
+ * serie; de las siete anteriores, la de Contacts salió de que una copia
+ * anunciara 15 herramientas y expusiera una.
+ *
+ * La deriva aquí era gorda: **14 de las 16 descripciones** diferían. Gana la de
+ * la api en todas —es sistemáticamente la más completa y es la que sirve el MCP
+ * hoy—, y una no era cosmética: en `deleteMessage` la api nombra el permiso que
+ * hace falta (`chat:write.public` + admin) y el dashboard sólo decía «admin
+ * perms». Operaciones, nombres de herramienta y parámetros sí coincidían.
+ *
+ * Los nombres llevan `_slack_` para no chocar con los de Telegram y Discord
+ * cuando un mismo AI Node tiene varios toolkits encendidos.
+ *
+ * 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.
+ */
+import type { SlackOperation } from './slack-operations';
+export interface SlackToolkitParameter {
+    name: string;
+    type: 'string' | 'number' | 'boolean';
+    description: string;
+    required: boolean;
+}
+export interface SlackToolkitSpec {
+    operation: SlackOperation;
+    /** Etiqueta corta de la fila en la lista de herramientas. */
+    label: string;
+    /** Nombre con el que el LLM llama a la herramienta. */
+    toolName: string;
+    /** Descripción (más reglas de uso) que ve el LLM. */
+    description: string;
+    parameters: SlackToolkitParameter[];
+    /** Operaciones irreversibles o que cambian privilegios. La capa MCP las
+     *  bloquea cuando el nodo de IA lleva `requireConfirmationForDestructive`,
+     *  salvo que la llamada traiga confirmación explícita. */
+    destructive?: boolean;
+}
+export declare const SLACK_TOOLKIT_SPECS: SlackToolkitSpec[];
+export declare const SLACK_TOOLKIT_BY_TOOL_NAME: Record<string, SlackToolkitSpec>;