@hostwebhook/node-types 1.69.0 → 1.71.0

package/dist/esm/github-operations.js

@@ -0,0 +1,551 @@
+/**
+ * GitHub operation enum — única fuente de verdad para la api, el dashboard y
+ * el Message Broker. Lo usan:
+ *   - la entidad y el DTO de `githubAction` (api): campo `operation` + validación
+ *   - la página de detalle del dashboard, que pinta el formulario desde los specs
+ *   - specs de toolkit MCP, si algún día el nodo gana modo herramienta
+ *
+ * Mismo patrón que `notion-operations.ts` y `shopify-operations.ts`.
+ *
+ * ── Qué credencial hay debajo ──
+ *
+ * Dos tipos, y la diferencia se nota en UNA cosa que no es una operación:
+ * de dónde sale la lista de repositorios.
+ *
+ *   - `github_app`  — la instalación de la GitHub App. El camino principal.
+ *     Los repos son los que abarca esa instalación.
+ *   - `github_pat`  — un fine-grained token pegado por el usuario. La salida
+ *     de emergencia, detrás de "Use a personal access token instead".
+ *     Los repos son los del usuario.
+ *
+ * Las 14 operaciones de abajo se ejecutan IGUAL con las dos. Lo que cambia es
+ * el listado que rellena el formulario, y eso vive en el controlador, no aquí.
+ *
+ * ── Por qué 14 y no la API entera ──
+ *
+ * Paridad con lo que la gente encadena en un flujo, no con los docs de GitHub.
+ * Abrir un issue, comentarlo, mover un PR, leer o escribir un archivo, disparar
+ * un workflow. Lo demás —releases, gists, administración de la organización,
+ * búsqueda de código— lo cubre el MCP oficial de GitHub dentro del AI Node, que
+ * ya existe y no hay que construir.
+ *
+ * Y la regla que dejó escrita Notion se respeta al pie: **ninguna operación
+ * declarada sin implementar**. El enum ES el contrato de la pantalla — una op
+ * declarada se pinta en el desplegable y luego revienta al ejecutarse. Entran
+ * cuando entre su código.
+ *
+ * ── Lo que NO es un parámetro, a propósito ──
+ *
+ * El `sha`. Actualizar un archivo y crear una rama lo necesitan, y GitHub no
+ * perdona uno equivocado. Pedírselo al usuario es pedirle que se equivoque: lo
+ * resuelve el nodo, desde la ruta del archivo o el nombre de la rama base. Es
+ * el mismo criterio por el que un id de Notion se elige de una lista en vez de
+ * teclearse.
+ *
+ * Tampoco son operaciones listar repos, ramas, etiquetas, asignables o
+ * workflows. Una operación existe para producir payload en una corrida; eso
+ * otro es para rellenar el formulario, y son endpoints del controlador — como
+ * Drive alimenta su `DriveFilePicker`.
+ *
+ * ── Límites de GitHub que condicionan el diseño ──
+ *
+ *   - 5.000 peticiones/hora autenticadas. Suficiente salvo en bucles largos.
+ *   - `searchIssues` NO comparte ese cubo: la API de búsqueda va por su cuenta,
+ *     del orden de 30 por minuto. Por eso está marcada aparte más abajo.
+ *   - Las escrituras tienen además un límite secundario por ráfaga, y GitHub
+ *     responde con `Retry-After`. Se respeta con `common/rate-limiter.ts` y
+ *     `common/retry-transient.ts`, que ya existen. No escribir otro backoff.
+ */
+export const GITHUB_OPERATIONS = [
+    // Issues
+    'createIssue', // POST   /repos/{o}/{r}/issues
+    'updateIssue', // PATCH  /repos/{o}/{r}/issues/{n}   (cubre cerrar y reabrir)
+    'getIssue', // GET    /repos/{o}/{r}/issues/{n}
+    'commentIssue', // POST   /repos/{o}/{r}/issues/{n}/comments
+    'listIssues', // GET    /repos/{o}/{r}/issues       → iterable
+    // Pull requests
+    'createPullRequest', // POST   /repos/{o}/{r}/pulls
+    'getPullRequest', // GET    /repos/{o}/{r}/pulls/{n}
+    'mergePullRequest', // PUT    /repos/{o}/{r}/pulls/{n}/merge
+    'listPullRequests', // GET    /repos/{o}/{r}/pulls        → iterable
+    // Contenido del repositorio
+    'getFile', // GET    /repos/{o}/{r}/contents/{path}
+    'createOrUpdateFile', // PUT    /repos/{o}/{r}/contents/{path}
+    'createBranch', // POST   /repos/{o}/{r}/git/refs
+    // Automatización
+    'dispatchWorkflow', // POST   /repos/{o}/{r}/actions/workflows/{id}/dispatches
+    // Transversal
+    'searchIssues', // GET    /search/issues              → iterable, cubo propio
+];
+/** Type guard — para validar entrada no fiable (DTOs, tool calls). */
+export function isGithubOperation(value) {
+    return (typeof value === 'string' &&
+        GITHUB_OPERATIONS.includes(value));
+}
+/**
+ * Las operaciones que devuelven un ARRAY y por tanto obligan a marcar
+ * `_meta.iterable` en `getOutputPayload`.
+ *
+ * Está aquí y no sólo en la api porque el error de 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. Que la lista viva en el paquete permite que
+ * el test de la api la recorra en vez de repetirla a mano.
+ */
+export const GITHUB_ITERABLE_OPERATIONS = [
+    'listIssues',
+    'listPullRequests',
+    'searchIssues',
+];
+/* Ayudantes — casi toda operación empieza eligiendo repositorio, y repetir el
+   mismo objeto catorce veces es cómo se desincronizan las descripciones. */
+const repo = () => ({
+    name: 'repo',
+    label: 'Repository',
+    type: 'githubRepo',
+    required: true,
+    description: 'De la lista de repos que alcanza esta credencial. Se guarda como owner/repo.',
+});
+const issueNumber = (label = 'Issue number') => ({
+    name: 'issueNumber',
+    label,
+    type: 'template',
+    required: true,
+    placeholder: '{{payload.issue.number}}',
+    description: 'El número que se ve en la URL del issue, no su id interno.',
+});
+const pullNumber = () => ({
+    name: 'pullNumber',
+    label: 'Pull request number',
+    type: 'template',
+    required: true,
+    placeholder: '{{payload.pull_request.number}}',
+    description: 'El número que se ve en la URL del PR, no su id interno.',
+});
+const perPage = () => ({
+    name: 'perPage',
+    label: 'How many at most',
+    type: 'number',
+    default: 30,
+    min: 1,
+    max: 100,
+    advanced: true,
+    description: 'GitHub no devuelve más de 100 por página.',
+});
+export const GITHUB_OPERATION_SPECS = {
+    /* ── Issues ────────────────────────────────────────────────────────────── */
+    createIssue: {
+        label: 'Create issue',
+        description: 'Abre un issue nuevo en el repositorio.',
+        apiRoute: 'POST /repos/{owner}/{repo}/issues',
+        params: [
+            repo(),
+            {
+                name: 'title',
+                label: 'Title',
+                type: 'template',
+                required: true,
+                placeholder: 'Error en el pago: {{payload.order.id}}',
+            },
+            {
+                name: 'body',
+                label: 'Body',
+                type: 'textarea',
+                placeholder: 'Lo que llegó:\n\n{{payload.message}}',
+                description: 'Admite Markdown, que es como GitHub lo va a pintar.',
+            },
+            {
+                name: 'labels',
+                label: 'Labels',
+                type: 'githubLabels',
+                description: 'De las que ya existen en el repo.',
+            },
+            {
+                name: 'assignees',
+                label: 'Assignees',
+                type: 'githubAssignees',
+                description: 'Sólo se puede asignar a quien tiene acceso al repo.',
+            },
+        ],
+    },
+    updateIssue: {
+        label: 'Update issue',
+        description: 'Cambia título, cuerpo, estado, etiquetas o asignados.',
+        apiRoute: 'PATCH /repos/{owner}/{repo}/issues/{issue_number}',
+        params: [
+            repo(),
+            issueNumber(),
+            {
+                name: 'title',
+                label: 'New title',
+                type: 'template',
+                description: 'Se deja vacío para no tocarlo.',
+            },
+            {
+                name: 'body',
+                label: 'New body',
+                type: 'textarea',
+                description: 'Se deja vacío para no tocarlo. Reemplaza el cuerpo entero.',
+            },
+            {
+                name: 'state',
+                label: 'State',
+                type: 'select',
+                options: [
+                    { value: '', label: '— sin tocar —' },
+                    { value: 'open', label: 'Open (reabrir)' },
+                    { value: 'closed', label: 'Closed (cerrar)' },
+                ],
+                description: 'Cerrar y reabrir se hacen aquí; no hay operación aparte.',
+            },
+            {
+                name: 'stateReason',
+                label: 'Why closed',
+                type: 'select',
+                showWhen: { field: 'state', in: ['closed'] },
+                options: [
+                    { value: 'completed', label: 'Completed — se resolvió' },
+                    { value: 'not_planned', label: 'Not planned — no se va a hacer' },
+                ],
+                description: 'Es lo que decide qué icono pinta GitHub al cerrarlo.',
+            },
+            {
+                name: 'labels',
+                label: 'Labels',
+                type: 'githubLabels',
+                description: 'Ojo: REEMPLAZA las etiquetas del issue, no las añade. Vacío las deja como están.',
+            },
+            {
+                name: 'assignees',
+                label: 'Assignees',
+                type: 'githubAssignees',
+                description: 'Igual que las etiquetas: reemplaza, no añade.',
+            },
+        ],
+    },
+    getIssue: {
+        label: 'Get issue',
+        description: 'Lee un issue por su número.',
+        apiRoute: 'GET /repos/{owner}/{repo}/issues/{issue_number}',
+        params: [repo(), issueNumber()],
+    },
+    commentIssue: {
+        label: 'Comment on issue',
+        description: 'Añade un comentario a un issue o a un pull request.',
+        apiRoute: 'POST /repos/{owner}/{repo}/issues/{issue_number}/comments',
+        params: [
+            repo(),
+            issueNumber('Issue or PR number'),
+            {
+                name: 'body',
+                label: 'Comment',
+                type: 'textarea',
+                required: true,
+                placeholder: 'Desplegado en producción: {{payload.deployment.url}}',
+                description: 'Vale igual para un PR: en la API de GitHub un pull request ES un issue.',
+            },
+        ],
+    },
+    listIssues: {
+        label: 'List issues',
+        description: 'Los issues del repositorio, filtrables. Devuelve una lista.',
+        apiRoute: 'GET /repos/{owner}/{repo}/issues',
+        params: [
+            repo(),
+            {
+                name: 'state',
+                label: 'State',
+                type: 'select',
+                default: 'open',
+                options: [
+                    { value: 'open', label: 'Open' },
+                    { value: 'closed', label: 'Closed' },
+                    { value: 'all', label: 'Todos' },
+                ],
+            },
+            {
+                name: 'labels',
+                label: 'With these labels',
+                type: 'githubLabels',
+                description: 'Un issue tiene que llevarlas TODAS para salir.',
+            },
+            {
+                name: 'assignee',
+                label: 'Assigned to',
+                type: 'githubAssignees',
+                description: 'Una sola persona. Vacío no filtra.',
+            },
+            perPage(),
+        ],
+    },
+    /* ── Pull requests ─────────────────────────────────────────────────────── */
+    createPullRequest: {
+        label: 'Create pull request',
+        description: 'Abre un PR de una rama contra otra.',
+        apiRoute: 'POST /repos/{owner}/{repo}/pulls',
+        params: [
+            repo(),
+            {
+                name: 'title',
+                label: 'Title',
+                type: 'template',
+                required: true,
+                placeholder: 'Actualiza dependencias — {{payload.date}}',
+            },
+            {
+                name: 'head',
+                label: 'From branch',
+                type: 'githubBranch',
+                required: true,
+                description: 'La rama con los cambios. La que se quiere fusionar.',
+            },
+            {
+                name: 'base',
+                label: 'Into branch',
+                type: 'githubBranch',
+                required: true,
+                description: 'La rama de destino. Normalmente main.',
+            },
+            { name: 'body', label: 'Description', type: 'textarea' },
+            {
+                name: 'draft',
+                label: 'Open as draft',
+                type: 'booleanSelect',
+                options: [
+                    { value: '', label: '— sin tocar —' },
+                    { value: 'true', label: 'Sí, en borrador' },
+                    { value: 'false', label: 'No, listo para revisar' },
+                ],
+                advanced: true,
+            },
+        ],
+    },
+    getPullRequest: {
+        label: 'Get pull request',
+        description: 'Lee un PR por su número, con su estado de fusión.',
+        apiRoute: 'GET /repos/{owner}/{repo}/pulls/{pull_number}',
+        params: [repo(), pullNumber()],
+    },
+    mergePullRequest: {
+        label: 'Merge pull request',
+        description: 'Fusiona un PR abierto.',
+        apiRoute: 'PUT /repos/{owner}/{repo}/pulls/{pull_number}/merge',
+        params: [
+            repo(),
+            pullNumber(),
+            {
+                name: 'mergeMethod',
+                label: 'How',
+                type: 'select',
+                default: 'merge',
+                options: [
+                    { value: 'merge', label: 'Merge commit' },
+                    { value: 'squash', label: 'Squash and merge' },
+                    { value: 'rebase', label: 'Rebase and merge' },
+                ],
+                description: 'El repo puede tener métodos deshabilitados en sus ajustes; si el elegido no está permitido, GitHub responde 405.',
+            },
+            {
+                name: 'commitTitle',
+                label: 'Commit title',
+                type: 'template',
+                advanced: true,
+                description: 'Vacío deja el que GitHub genera solo.',
+            },
+            {
+                name: 'commitMessage',
+                label: 'Commit message',
+                type: 'textarea',
+                advanced: true,
+            },
+        ],
+    },
+    listPullRequests: {
+        label: 'List pull requests',
+        description: 'Los PRs del repositorio, filtrables. Devuelve una lista.',
+        apiRoute: 'GET /repos/{owner}/{repo}/pulls',
+        params: [
+            repo(),
+            {
+                name: 'state',
+                label: 'State',
+                type: 'select',
+                default: 'open',
+                options: [
+                    { value: 'open', label: 'Open' },
+                    { value: 'closed', label: 'Closed' },
+                    { value: 'all', label: 'Todos' },
+                ],
+            },
+            {
+                name: 'base',
+                label: 'Into branch',
+                type: 'githubBranch',
+                description: 'Sólo los que apuntan a esta rama. Vacío no filtra.',
+            },
+            perPage(),
+        ],
+    },
+    /* ── Contenido del repositorio ─────────────────────────────────────────── */
+    getFile: {
+        label: 'Get file',
+        description: 'Lee un archivo del repositorio, ya decodificado.',
+        apiRoute: 'GET /repos/{owner}/{repo}/contents/{path}',
+        params: [
+            repo(),
+            {
+                name: 'path',
+                label: 'Path',
+                type: 'template',
+                required: true,
+                placeholder: 'package.json',
+                description: 'Ruta desde la raíz del repo, sin barra inicial.',
+            },
+            {
+                name: 'ref',
+                label: 'Branch',
+                type: 'githubBranch',
+                description: 'Vacío usa la rama por defecto del repo.',
+            },
+        ],
+    },
+    createOrUpdateFile: {
+        label: 'Create or update file',
+        description: 'Escribe un archivo y commitea el cambio.',
+        apiRoute: 'PUT /repos/{owner}/{repo}/contents/{path}',
+        params: [
+            repo(),
+            {
+                name: 'path',
+                label: 'Path',
+                type: 'template',
+                required: true,
+                placeholder: 'data/report.md',
+                description: 'Si el archivo ya existe se actualiza; si no, se crea. El sha lo resuelve el nodo — no hace falta dárselo.',
+            },
+            {
+                name: 'content',
+                label: 'Content',
+                type: 'textarea',
+                required: true,
+                description: 'Texto plano. El nodo lo codifica antes de mandarlo.',
+            },
+            {
+                name: 'commitMessage',
+                label: 'Commit message',
+                type: 'template',
+                required: true,
+                placeholder: 'Actualiza el informe de {{payload.date}}',
+            },
+            {
+                name: 'branch',
+                label: 'Branch',
+                type: 'githubBranch',
+                description: 'Vacío commitea en la rama por defecto del repo.',
+            },
+        ],
+    },
+    createBranch: {
+        label: 'Create branch',
+        description: 'Crea una rama a partir de otra.',
+        apiRoute: 'POST /repos/{owner}/{repo}/git/refs',
+        params: [
+            repo(),
+            {
+                name: 'newBranch',
+                label: 'New branch name',
+                type: 'template',
+                required: true,
+                placeholder: 'fix/{{payload.issue.number}}',
+                description: 'Sin el prefijo refs/heads/ — lo pone el nodo.',
+            },
+            {
+                name: 'fromBranch',
+                label: 'From branch',
+                type: 'githubBranch',
+                required: true,
+                description: 'De dónde parte. El sha de su punta lo resuelve el nodo desde este nombre.',
+            },
+        ],
+    },
+    /* ── Automatización ────────────────────────────────────────────────────── */
+    dispatchWorkflow: {
+        label: 'Run workflow',
+        description: 'Dispara un workflow de GitHub Actions.',
+        apiRoute: 'POST /repos/{owner}/{repo}/actions/workflows/{workflow_id}/dispatches',
+        params: [
+            repo(),
+            {
+                name: 'workflow',
+                label: 'Workflow',
+                type: 'githubWorkflow',
+                required: true,
+                description: 'Sólo salen los que declaran workflow_dispatch: el resto no se puede disparar desde fuera.',
+            },
+            {
+                name: 'ref',
+                label: 'Branch or tag',
+                type: 'githubBranch',
+                required: true,
+                description: 'Desde dónde se corre el workflow.',
+            },
+            {
+                name: 'inputs',
+                label: 'Inputs',
+                type: 'json',
+                advanced: true,
+                placeholder: '{ "environment": "production" }',
+                description: 'Los inputs que declara el workflow. Objeto plano: GitHub sólo acepta cadenas como valores.',
+            },
+        ],
+    },
+    /* ── Transversal ───────────────────────────────────────────────────────── */
+    searchIssues: {
+        label: 'Search issues and PRs',
+        description: 'Busca en todo GitHub con su sintaxis de búsqueda. Devuelve una lista.',
+        apiRoute: 'GET /search/issues',
+        params: [
+            {
+                name: 'query',
+                label: 'Query',
+                type: 'template',
+                required: true,
+                placeholder: 'repo:hostwebhook/dashboard is:open label:bug',
+                description: 'La misma sintaxis de la barra de búsqueda de GitHub. Sin repo: busca en todo lo que alcance la credencial.',
+            },
+            {
+                name: 'sort',
+                label: 'Sort by',
+                type: 'select',
+                options: [
+                    { value: '', label: 'Relevancia' },
+                    { value: 'created', label: 'Fecha de creación' },
+                    { value: 'updated', label: 'Última actualización' },
+                    { value: 'comments', label: 'Número de comentarios' },
+                ],
+                advanced: true,
+            },
+            {
+                name: 'order',
+                label: 'Order',
+                type: 'select',
+                default: 'desc',
+                options: [
+                    { value: 'desc', label: 'Descendente' },
+                    { value: 'asc', label: 'Ascendente' },
+                ],
+                advanced: true,
+            },
+            perPage(),
+        ],
+    },
+};
+/**
+ * Lo que se ofrece en el desplegable de operación.
+ *
+ * Hoy son todas. Existe como constante aparte —y no como alias de
+ * `GITHUB_OPERATIONS`— porque es exactamente el punto donde otros nodos han
+ * necesitado esconder una op sin sacarla del enum: retirarla del enum rompe
+ * las que ya estaban guardadas en la base de datos.
+ */
+export const GITHUB_DROPDOWN_OPERATIONS = GITHUB_OPERATIONS;