@hostwebhook/node-types 1.69.0 → 1.71.0

package/dist/esm/drive-toolkit.js

@@ -0,0 +1,177 @@
+/**
+ * Drive AI Toolkit — las herramientas que un driveAction expone cuando
+ * `aiEnabled` está encendido.
+ *
+ * **Se escribe una sola vez**, como el de Sheets y el de Telegram. Antes vivía
+ * TRES veces, y las tres a mano:
+ *
+ *   1. `dashboard/components/drive-actions/drive-operations-schemas.ts`
+ *   2. `api/src/mcp-servers/toolkit-specs.ts`
+ *   3. la página de detalle, que pintaba las doce herramientas como doce
+ *      `<li>` escritos a mano, con el número `12` también a mano en tres sitios
+ *
+ * La 1 y la 2 no habían derivado todavía (medido el 2026-08-10: cero
+ * diferencias, al contrario que Slack con 13 y WhatsApp con 4). Esto es lo que
+ * hace que sigan sin derivar.
+ *
+ * El ORDEN de este array importa: `AiToolkitPreview` pinta el encabezado de
+ * grupo sólo cuando cambia respecto a la fila anterior, así que las
+ * herramientas del mismo grupo tienen que ir seguidas. Los tres grupos son los
+ * que ya inventaba el JSX que sustituye.
+ */
+const p = (name, description, required = true, type = 'string') => ({ name, type, description, required });
+const ENTRAN_Y_SALEN = 'Files in / out';
+const DESCUBRIR = 'Discovery';
+const MUTACIONES = 'Mutations (LLM confirms first)';
+export const DRIVE_TOOLKIT_SPECS = [
+    /* ── Files in / out ─────────────────────────────────────────────────── */
+    {
+        operation: 'upload',
+        label: 'Upload file',
+        toolName: 'upload_to_drive',
+        group: ENTRAN_Y_SALEN,
+        description: 'Upload a file into Google Drive. TWO ways to hand it the bytes. (1) `contentBase64` — the file contents, base64. Use this one when YOU hold the file: an MCP client, an assistant with an attachment, anything outside a running flow. Nothing has to be online first. If the file does not fit in a single call, send it in chunks with partIndex/partTotal — see those parameters. (2) Leave `contentBase64` out and it takes the `_file` ref from the current event payload, put there by an upstream node (multipart ingress, File Transform, another Drive download). The payload route streams from R2, never holds the file in memory, and needs no chunking at any size.',
+        parameters: [
+            p('fileName', 'Optional with a payload _file (defaults to its originalName). REQUIRED with contentBase64 — there is no ref to inherit a name from.', false),
+            p('contentBase64', 'Optional. File contents, base64-encoded — or ONE chunk of them when using partIndex/partTotal. Raw base64; a `data:` URL prefix is stripped if you send one. Max 8 MB decoded in a single call, 1 MB per chunk.', false),
+            p('partTotal', 'Optional. How many chunks the file is split into. Set it to send a file that does not fit in one call: the limit is the size of each MESSAGE, not of the file, so chunking lifts it entirely. Leave it out for a normal one-call upload.', false),
+            p('partIndex', 'Which chunk this is, ZERO-BASED (0 to partTotal-1). Required whenever partTotal is set.', false),
+            p('uploadId', 'Ties the chunks together. Leave it out on the first chunk — the response gives you one — and pass that same value on every chunk after it. While chunks are missing the call answers 202 with how many arrived and which one is next; the last one uploads the file and returns normally.', false),
+            p('sourceField', 'Optional. Payload field path holding the _file ref. Defaults to "_file". Ignored when contentBase64 is set.', false),
+            p('parentFolderId', 'Optional. Drive folder ID to upload into. Empty = root.', false),
+            p('mimeType', 'Optional. Override the MIME type. Defaults to the _file ref mimeType, or application/octet-stream with contentBase64.', false),
+        ],
+    },
+    {
+        operation: 'download',
+        label: 'Download file',
+        toolName: 'download_from_drive',
+        group: ENTRAN_Y_SALEN,
+        description: 'Download a Drive file to HostWebhook storage and return a `_file` ref the next pipeline node can consume (FileTransform, AI vision, HTTP body). Use the file ID from list_drive_files / search.',
+        parameters: [p('fileId', 'The Drive file ID to download.')],
+    },
+    {
+        operation: 'export',
+        label: 'Export Google doc',
+        toolName: 'export_drive_file',
+        group: ENTRAN_Y_SALEN,
+        description: 'Export a Google native document (Doc / Sheet / Slide / Drawing) to a downloadable format like PDF or DOCX, returning a `_file` ref the next pipeline node can consume. Does NOT work on regular files (those use download_from_drive).',
+        parameters: [
+            p('fileId', 'The Drive file ID (must be a Google native doc).'),
+            /* De las dos copias me quedo con la de la api, que es la que dice qué
+               formato de origen va a cada destino. La del dashboard se había quedado
+               sin esa parte. Es la única deriva que tenían Drive y, como estaba en la
+               descripción de un PARÁMETRO, ningún conteo la miraba. */
+            p('mimeType', 'Target MIME type. Common: "application/pdf" (Doc/Slide → PDF), "application/vnd.openxmlformats-officedocument.wordprocessingml.document" (Doc → DOCX), "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet" (Sheet → XLSX), "text/plain", "text/csv".'),
+        ],
+    },
+    /* ── Discovery ──────────────────────────────────────────────────────── */
+    {
+        operation: 'list',
+        label: 'List / search files',
+        toolName: 'list_drive_files',
+        group: DESCUBRIR,
+        description: "Search the user's Drive (or shared drive). Returns up to N matching files with id, name, mimeType, size, modifiedTime. Use this BEFORE any operation that needs a fileId — never invent IDs.",
+        parameters: [
+            p('query', 'Optional. Substring to match against file names.', false),
+            p('parentFolderId', 'Optional. Restrict search to a single folder.', false),
+            p('mimeType', 'Optional. Filter by MIME type (e.g. "application/pdf", "application/vnd.google-apps.folder").', false),
+            p('pageSize', 'Optional. Max results (default 50, max 100).', false, 'number'),
+            p('orderBy', 'Optional. Drive ordering string (default "modifiedTime desc").', false),
+        ],
+    },
+    {
+        operation: 'get',
+        label: 'Get file metadata',
+        toolName: 'get_drive_file',
+        group: DESCUBRIR,
+        description: 'Read full metadata for one Drive file (name, mimeType, size, parents, owners, starred, trashed). Does NOT download the bytes — use download_from_drive for that.',
+        parameters: [p('fileId', 'The Drive file ID.')],
+    },
+    {
+        operation: 'getPermissions',
+        label: 'List file permissions',
+        toolName: 'get_drive_permissions',
+        group: DESCUBRIR,
+        description: 'List who has access to a Drive file (id, type, role, emailAddress/domain, displayName). Use to audit sharing before changing permissions.',
+        parameters: [p('fileId', 'The Drive file ID.')],
+    },
+    /* ── Mutations ──────────────────────────────────────────────────────── */
+    {
+        operation: 'copy',
+        label: 'Copy file',
+        toolName: 'copy_drive_file',
+        group: MUTACIONES,
+        description: 'Duplicate a Drive file. Optionally rename and/or move into a different folder in one step.',
+        parameters: [
+            p('fileId', 'The source Drive file ID.'),
+            p('newName', 'Optional. Name for the copy. Defaults to "Copy of <original>".', false),
+            p('parentFolderId', 'Optional. Folder ID to place the copy into. Defaults to the source folder.', false),
+        ],
+    },
+    {
+        operation: 'move',
+        label: 'Move file',
+        toolName: 'move_drive_file',
+        group: MUTACIONES,
+        description: 'Move a Drive file to a different folder. The current parents are removed; the file is added to the new parent.',
+        parameters: [
+            p('fileId', 'The Drive file ID to move.'),
+            p('parentFolderId', 'Destination folder ID.'),
+        ],
+    },
+    {
+        operation: 'update',
+        label: 'Update file metadata',
+        toolName: 'update_drive_file',
+        group: MUTACIONES,
+        description: 'Rename a Drive file or change its description / starred status. Use list_drive_files first to find the fileId.',
+        parameters: [
+            p('fileId', 'The Drive file ID.'),
+            p('name', 'Optional. New name.', false),
+            p('description', 'Optional. New description.', false),
+            p('starred', 'Optional. Star/unstar.', false, 'boolean'),
+        ],
+    },
+    {
+        operation: 'createFolder',
+        label: 'Create folder',
+        toolName: 'create_drive_folder',
+        group: MUTACIONES,
+        description: 'Create a new folder in Drive. Use this BEFORE upload_to_drive when the user asks to put a file in a specific named folder that does not yet exist.',
+        parameters: [
+            p('name', 'Folder name.'),
+            p('parentFolderId', 'Optional. Parent folder ID. Empty = root.', false),
+        ],
+    },
+    {
+        operation: 'delete',
+        label: 'Delete file (trash)',
+        toolName: 'delete_drive_file',
+        group: MUTACIONES,
+        description: 'Move a Drive file to trash (recoverable for 30 days). Set permanent=true ONLY when the user explicitly confirms a permanent delete — irreversible. ALWAYS confirm with the user before calling this with permanent=true.',
+        parameters: [
+            p('fileId', 'The Drive file ID to delete.'),
+            p('permanent', 'Optional. true = bypass trash and erase forever (irreversible). Default false.', false, 'boolean'),
+        ],
+        destructive: true,
+    },
+    {
+        operation: 'share',
+        label: 'Share file',
+        toolName: 'share_drive_file',
+        group: MUTACIONES,
+        description: 'Grant a permission on a Drive file. CONFIRM with the user before calling this — sharing externally is sensitive. Public sharing (type="anyone") is especially dangerous; only use when the user explicitly says "make it public" or similar.',
+        parameters: [
+            p('fileId', 'The Drive file ID to share.'),
+            p('type', 'One of: "user" | "group" | "domain" | "anyone". Use "anyone" only with explicit user confirmation.'),
+            p('role', 'One of: "reader" | "commenter" | "writer".'),
+            p('emailAddress', 'Required when type=user|group.', false),
+            p('domain', 'Required when type=domain.', false),
+            p('sendNotificationEmail', 'Optional. true = email the recipient about the share.', false, 'boolean'),
+        ],
+        destructive: true,
+    },
+];
+/** Índice por nombre de herramienta, para enrutar un `tools/call` sin recorrer. */
+export const DRIVE_TOOLKIT_BY_TOOL_NAME = Object.fromEntries(DRIVE_TOOLKIT_SPECS.map((s) => [s.toolName, s]));

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

@@ -0,0 +1,147 @@
+/**
+ * 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 declare const GITHUB_OPERATIONS: readonly ["createIssue", "updateIssue", "getIssue", "commentIssue", "listIssues", "createPullRequest", "getPullRequest", "mergePullRequest", "listPullRequests", "getFile", "createOrUpdateFile", "createBranch", "dispatchWorkflow", "searchIssues"];
+export type GithubOperation = (typeof GITHUB_OPERATIONS)[number];
+/** Type guard — para validar entrada no fiable (DTOs, tool calls). */
+export declare function isGithubOperation(value: unknown): value is GithubOperation;
+/**
+ * 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 declare const GITHUB_ITERABLE_OPERATIONS: readonly GithubOperation[];
+export type GithubParamType = 
+/** Selector vivo de repositorios que alcanza la credencial. Guarda
+ *  `owner/repo`, que es como lo consumen todas las rutas. */
+'githubRepo'
+/** Selector vivo de ramas del repo elegido. Admite escribir una que aún no
+ *  existe: `createBranch` la crea, y una plantilla puede resolverla. */
+ | 'githubBranch'
+/** Etiquetas del repo elegido, selección múltiple. */
+ | 'githubLabels'
+/** Usuarios asignables en el repo elegido, selección múltiple. */
+ | 'githubAssignees'
+/** Workflows del repo que declaran `workflow_dispatch`. Los demás no se
+ *  pueden disparar, así que no se ofrecen. */
+ | 'githubWorkflow'
+/** Texto con autocompletado de `{{payload.*}}`. */
+ | 'template'
+/** Área de texto larga, también con autocompletado. */
+ | 'textarea'
+/** `<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 `''`. "— sin tocar —" tiene que significar que la clave
+ * no viaja, no que viaja en `false`.
+ */
+ | 'booleanSelect'
+/** Área de texto para JSON crudo. */
+ | 'json';
+export interface GithubParamSpec {
+    /** La clave de `operationConfig`. Es lo que lee la api, no un nombre de UI. */
+    name: string;
+    label: string;
+    type: GithubParamType;
+    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 GithubOperationSpec {
+    /** Etiqueta de la fila en el desplegable de operación. */
+    label: string;
+    /** Sub-línea bajo la etiqueta. */
+    description: string;
+    /** Ruta a la que mapea, tal cual, para poder cotejarla con los docs. */
+    apiRoute: string;
+    /** Esquema de parámetros. El orden ES el orden en pantalla. */
+    params: GithubParamSpec[];
+}
+export declare const GITHUB_OPERATION_SPECS: Record<GithubOperation, GithubOperationSpec>;
+/**
+ * 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 declare const GITHUB_DROPDOWN_OPERATIONS: readonly GithubOperation[];