@hostwebhook/node-types 1.69.0 → 1.71.0

package/dist/esm/docs-toolkit.js

@@ -0,0 +1,97 @@
+/**
+ * Google Docs AI Toolkit — las herramientas que un docsAction expone cuando
+ * `aiEnabled` está encendido.
+ *
+ * Se escribe **una sola vez**, aquí, y la importan la api
+ * (`mcp-servers/toolkit-specs.ts`) y el dashboard (`NodeAsToolPicker`,
+ * `DocsActionDetail`). Es el sexto toolkit que vive en el paquete —van Gmail,
+ * native email, Calendar, Drive, Telegram y Sheets—; los que siguen con copia a
+ * mano en los dos repos son WhatsApp, Discord, Slack y Contacts, y de ese
+ * reparto salió que Contacts anunciara 15 herramientas y expusiera una.
+ *
+ * La forma es la que ya consume `toolkitSpecToMcpTool` en la api, para poder
+ * usarse sin adaptador. Los textos van en inglés porque los lee el modelo y
+ * quien mire la lista de herramientas del servidor MCP.
+ */
+const p = (name, description, required = true, type = 'string') => ({ name, type, description, required });
+/*
+ * El documento del nodo va como **defecto** y el modelo puede cambiarlo — la
+ * misma decisión y la misma maquinaria que la hoja de Sheets:
+ * `toolkitSpecToMcpTool(spec, nombre, { documentId })` lo saca de `required`
+ * **y le cuenta el valor al modelo** en la descripción. Las dos cosas o
+ * ninguna: mientras el esquema diga `required`, el LLM siempre lo rellena y el
+ * documento configurado no se usaría jamás.
+ *
+ * Por eso aquí se declara `required: true`: lo es para la API de Google, y es
+ * el defecto del nodo quien lo vuelve opcional, nodo por nodo.
+ *
+ * `create_doc` es el único que NO lo declara —todavía no hay documento al que
+ * apuntar— y su nombre de campo es `title`. Si se llamara `documentId`, la
+ * inyección de defectos se lo rellenaría con el documento del nodo y el
+ * documento nuevo nacería con el id del viejo por título.
+ */
+const documento = () => p('documentId', 'Id of the Google Docs document — the long chunk of its URL, between /d/ and /edit.');
+export const DOCS_TOOLKIT_SPECS = [
+    {
+        operation: 'readDoc',
+        label: 'Read document',
+        toolName: 'read_doc',
+        description: 'Read the whole document as plain text. Use it before editing when you do not know what the document already says — replace_text and append_text act blindly otherwise.',
+        parameters: [documento()],
+    },
+    {
+        operation: 'createDoc',
+        label: 'Create document',
+        toolName: 'create_doc',
+        description: 'Create a new Google Docs document and return its id. The id it returns is what the other tools take as documentId.',
+        parameters: [
+            p('title', 'Name of the new document.'),
+            p('content', 'Initial body, as HTML. Basic tags work (<p>, <b>, <i>, <ul>, <li>, <h1>…). Plain text is fine too. Leave it out for an empty document.', false),
+        ],
+        destructive: true,
+    },
+    {
+        operation: 'appendText',
+        label: 'Append text',
+        toolName: 'append_text',
+        description: 'Add content at the END of the document. It never replaces what is already there, so it is the safe way to add a paragraph, a note or a log line.',
+        parameters: [
+            p('content', 'What to add, as HTML. Basic tags work (<p>, <b>, <i>, <ul>, <li>, <h1>…). Plain text is fine too.'),
+            documento(),
+        ],
+        destructive: true,
+    },
+    {
+        operation: 'replaceText',
+        label: 'Replace text',
+        toolName: 'replace_text',
+        description: 'Find every occurrence of a piece of text and swap it for another. It matches literally and it is case-sensitive; a search string that appears nowhere changes nothing and is not an error.',
+        parameters: [
+            p('searchText', 'Exact text to look for. Every occurrence is replaced, not just the first.'),
+            p('replaceWith', 'Text to put in its place. An empty string deletes the matches.'),
+            documento(),
+        ],
+        destructive: true,
+    },
+    {
+        operation: 'insertTable',
+        label: 'Insert table',
+        toolName: 'insert_table',
+        description: 'Insert an empty table at the end of the document. It creates the grid only — fill the cells afterwards with replace_text, or build the content as HTML and use append_text instead.',
+        parameters: [
+            p('rows', 'Number of rows, including the header row if you want one.', true, 'number'),
+            p('cols', 'Number of columns.', true, 'number'),
+            documento(),
+        ],
+        destructive: true,
+    },
+];
+/** Las herramientas por nombre, para despachar una llamada del modelo. */
+export const DOCS_TOOLKIT_BY_TOOL_NAME = Object.fromEntries(DOCS_TOOLKIT_SPECS.map((s) => [s.toolName, s]));
+/**
+ * El parámetro que el nodo puede rellenar por defecto. Se exporta para que la
+ * api y el dashboard no vuelvan a escribir la lista a mano — `create_doc` no
+ * lo declara y por eso se queda fuera de la inyección sin necesidad de
+ * excepciones.
+ */
+export const DOCS_TOOLKIT_DEFAULTABLE = ['documentId'];

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

@@ -0,0 +1,103 @@
+/**
+ * Google Drive operation enum — single source of truth across the API,
+ * Dashboard, and Message Broker. Used by:
+ *   - driveAction entity / DTO (api): operation field + validation
+ *   - dashboard DriveAction operation type
+ *   - broker hostwebhook types + tool schemas
+ *   - MCP toolkit specs (when aiEnabled: true)
+ *
+ * Same pattern as gmail-operations.ts and calendar-operations.ts.
+ *
+ * Op semantics (anti-n8n choices):
+ *   - delete = move to trash (recoverable for 30 days), NOT permanent erase
+ *   - upload / download stream via the api Files / R2 layer, never load
+ *     full file contents into memory (n8n breaks past ~70MB)
+ *   - download returns a `_file` ref so downstream FileTransform / AI /
+ *     HTTP nodes can chain on it directly (n8n returns raw binary, often
+ *     misformatted as HTML on errors)
+ */
+export declare const DRIVE_OPERATIONS: readonly ["upload", "download", "copy", "move", "delete", "share", "update", "list", "get", "createFolder", "export", "getPermissions"];
+export type DriveOperation = (typeof DRIVE_OPERATIONS)[number];
+/** Type guard — useful when validating untrusted input (DTOs, tool calls). */
+export declare function isDriveOperation(value: unknown): value is DriveOperation;
+export type DriveParamType = 
+/** Live file picker (needs a credential) + templated paste. */
+'driveFile'
+/** Text input with `{{payload.*}}` autocomplete. */
+ | 'template'
+/** Plain `<select>`; the labels are not the values, so `options` is required. */
+ | 'select'
+/**
+ * Searchable mime-type dropdown. The option list is long and shared with
+ * other screens, so it stays in the dashboard (`lib/drive-mime-options`)
+ * and the schema only says "this field is a mime picker".
+ */
+ | 'mimeSelect' | 'number'
+/**
+ * A `<select>` whose values are `''` / `'true'` / `'false'` but which is
+ * stored as a BOOLEAN, or omitted entirely when `''`.
+ *
+ * This is the shape that keeps `starred` honest: the api applies it with
+ * `typeof config.starred === 'boolean'`, so "— don't change —" has to mean
+ * *no key at all*. A plain Switch cannot express that third state, and
+ * storing `''` or `'false'` would silently stop the star from ever changing.
+ */
+ | 'booleanSelect'
+/**
+ * Full-width explainer card that toggles: icon, title, prose and bullets,
+ * with the switch on the right. The card's rich body is JSX, so it lives in
+ * the page keyed by param name — the schema only declares the field.
+ */
+ | 'switchCard'
+/** Live multi-select of the starting folder's immediate children. */
+ | 'driveSubfolders';
+export interface DriveParamSpec {
+    /** The `operationConfig` key. This is what the api reads — not a UI name. */
+    name: string;
+    label: string;
+    type: DriveParamType;
+    required?: boolean;
+    /**
+     * Help text under the field. Plain text on purpose: the package holds no
+     * React, so the `<code>` spans the page used to have are gone. Deliberate.
+     */
+    description?: string;
+    placeholder?: string;
+    /** Prefilled when the saved config has no value for this key. */
+    default?: string | number;
+    /** Required for `select` and `booleanSelect` — label and value differ. */
+    options?: ReadonlyArray<{
+        value: string;
+        label: string;
+    }>;
+    min?: number;
+    max?: number;
+    /**
+     * Renders in the "Advanced" tab instead of "Config". The page used to keep
+     * a two-name `ADVANCED_FIELDS` array while the advanced *tab* actually held
+     * four fields, so `recursive` and `subfolderIds` only showed up because
+     * `list` happened to also carry one of the two named fields. Marking all
+     * four here removes that coincidence.
+     */
+    advanced?: boolean;
+    /**
+     * Only shown when a sibling field holds one of these values. No other node's
+     * schema needed this yet; Drive has three cases (the two share targets and
+     * the subfolder scope).
+     */
+    showWhen?: {
+        field: string;
+        in: ReadonlyArray<string>;
+    };
+}
+export interface DriveOperationSpec {
+    /** UI label for the operation dropdown row. */
+    label: string;
+    /** Sub-line under the label in the dropdown. */
+    description: string;
+    /** Drive API method it maps to (developers.google.com/drive/api/reference). */
+    apiMethod: string;
+    /** Parameter schema. Order matters: it is the on-screen order. */
+    params: DriveParamSpec[];
+}
+export declare const DRIVE_OPERATION_SPECS: Record<DriveOperation, DriveOperationSpec>;

package/dist/esm/drive-operations.js

@@ -0,0 +1,319 @@
+/**
+ * Google Drive operation enum — single source of truth across the API,
+ * Dashboard, and Message Broker. Used by:
+ *   - driveAction entity / DTO (api): operation field + validation
+ *   - dashboard DriveAction operation type
+ *   - broker hostwebhook types + tool schemas
+ *   - MCP toolkit specs (when aiEnabled: true)
+ *
+ * Same pattern as gmail-operations.ts and calendar-operations.ts.
+ *
+ * Op semantics (anti-n8n choices):
+ *   - delete = move to trash (recoverable for 30 days), NOT permanent erase
+ *   - upload / download stream via the api Files / R2 layer, never load
+ *     full file contents into memory (n8n breaks past ~70MB)
+ *   - download returns a `_file` ref so downstream FileTransform / AI /
+ *     HTTP nodes can chain on it directly (n8n returns raw binary, often
+ *     misformatted as HTML on errors)
+ */
+export const DRIVE_OPERATIONS = [
+    'upload', // upload a file (from _file ref or inline content)
+    'download', // download a file → _file ref
+    'copy', // duplicate a file in place or to another folder
+    'move', // relocate a file to a different folder
+    'delete', // trash a file (recoverable; permanent erase is opt-in)
+    'share', // grant viewer/commenter/editor permission to email/domain/anyone
+    'update', // rename or set metadata (description, starred, etc.)
+    'list', // search by name / mimeType / parent / query → iterable output
+    'get', // get metadata for one file
+    'createFolder', // create a new folder (with optional parent)
+    'export', // export Google native doc → PDF / DOCX / XLSX / etc.
+    'getPermissions', // list current permissions on a file
+];
+/** Type guard — useful when validating untrusted input (DTOs, tool calls). */
+export function isDriveOperation(value) {
+    return typeof value === 'string' && DRIVE_OPERATIONS.includes(value);
+}
+/* Fábricas de los campos que se repiten, para que un cambio de copy no haya
+   que perseguirlo por doce operaciones. */
+const fileId = () => ({
+    name: 'fileId',
+    label: 'Drive File',
+    type: 'driveFile',
+    required: true,
+    description: 'Pick a file from Drive or paste a templated value like {{payload.driveFileId}}.',
+});
+const parentFolderId = () => ({
+    name: 'parentFolderId',
+    label: 'Parent Folder ID (override)',
+    type: 'template',
+    advanced: true,
+    placeholder: 'Empty = use Default Folder above',
+    description: "Folder id used for this operation only. Leave empty to use the action's Default Folder. Templates work — e.g. {{payload.folderId}}.",
+});
+/** El filtro por tipo de upload/list. En `export` el mismo `mimeType` es otra
+    cosa y se declara aparte. */
+const mimeTypeFilter = () => ({
+    name: 'mimeType',
+    label: 'File type filter (optional)',
+    type: 'mimeSelect',
+    description: 'Restrict the operation to files of this type. Leave as "Any" to match every file.',
+});
+const ORDER_BY_OPTIONS = [
+    { value: 'modifiedTime desc', label: 'Modified time (newest first)' },
+    { value: 'modifiedTime', label: 'Modified time (oldest first)' },
+    { value: 'createdTime desc', label: 'Created time (newest first)' },
+    { value: 'createdTime', label: 'Created time (oldest first)' },
+    { value: 'name', label: 'Name (A→Z)' },
+    { value: 'name desc', label: 'Name (Z→A)' },
+];
+const EXPORT_FORMAT_OPTIONS = [
+    { value: 'application/pdf', label: 'PDF (.pdf)' },
+    {
+        value: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+        label: 'Word (.docx) — for Google Docs',
+    },
+    {
+        value: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+        label: 'Excel (.xlsx) — for Google Sheets',
+    },
+    {
+        value: 'application/vnd.openxmlformats-officedocument.presentationml.presentation',
+        label: 'PowerPoint (.pptx) — for Google Slides',
+    },
+    { value: 'text/plain', label: 'Plain text (.txt)' },
+    { value: 'text/csv', label: 'CSV (.csv) — for Google Sheets' },
+    { value: 'text/html', label: 'HTML (.html)' },
+];
+export const DRIVE_OPERATION_SPECS = {
+    upload: {
+        label: 'Upload File',
+        description: 'Stream a file from a payload _file ref into Drive',
+        apiMethod: 'files.create',
+        params: [
+            {
+                name: 'fileName',
+                label: 'Destination File Name',
+                type: 'template',
+                placeholder: '{{payload.name}} — leave blank to use _file.originalName',
+            },
+            {
+                name: 'sourceField',
+                label: 'Source Field (payload path)',
+                type: 'template',
+                placeholder: '_file',
+                default: '_file',
+                description: 'Where the _file ref lives in the incoming payload. Default _file. For nested refs use a dotted path (e.g. doc if upstream is { doc: { _file: ... } }).',
+            },
+            mimeTypeFilter(),
+            parentFolderId(),
+        ],
+    },
+    download: {
+        label: 'Download File',
+        description: 'Fetch a Drive file → payload _file ref for downstream nodes',
+        apiMethod: 'files.get (alt=media)',
+        params: [fileId()],
+    },
+    list: {
+        label: 'List / Search',
+        description: 'List or search files (iterable output)',
+        apiMethod: 'files.list',
+        params: [
+            {
+                name: 'query',
+                label: 'Search Query',
+                type: 'template',
+                placeholder: 'Substring to match against file names — empty = list all',
+            },
+            mimeTypeFilter(),
+            {
+                name: 'pageSize',
+                label: 'Max Results',
+                type: 'number',
+                min: 1,
+                max: 100,
+                default: 50,
+                description: 'Up to 100 per call. Output is iterable — downstream nodes process each file independently.',
+            },
+            {
+                name: 'orderBy',
+                label: 'Order By',
+                type: 'select',
+                default: 'modifiedTime desc',
+                options: ORDER_BY_OPTIONS,
+            },
+            parentFolderId(),
+            { name: 'recursive', label: 'Search subfolders too', type: 'switchCard', advanced: true },
+            {
+                name: 'subfolderIds',
+                label: 'Limit to specific subfolders',
+                type: 'driveSubfolders',
+                advanced: true,
+                showWhen: { field: 'recursive', in: ['true'] },
+            },
+            {
+                name: 'downloadResults',
+                label: 'Auto-download matching files',
+                type: 'switchCard',
+                advanced: true,
+            },
+        ],
+    },
+    get: {
+        label: 'Get Metadata',
+        description: 'Read metadata for one file (no bytes)',
+        apiMethod: 'files.get',
+        params: [fileId()],
+    },
+    copy: {
+        label: 'Copy File',
+        description: 'Duplicate a file, optionally rename and/or move',
+        apiMethod: 'files.copy',
+        params: [
+            fileId(),
+            {
+                name: 'newName',
+                label: 'New File Name',
+                type: 'template',
+                placeholder: "Optional — defaults to 'Copy of <original>'",
+            },
+            parentFolderId(),
+        ],
+    },
+    move: {
+        label: 'Move File',
+        description: 'Move a file to a different folder',
+        apiMethod: 'files.update (addParents / removeParents)',
+        params: [fileId(), parentFolderId()],
+    },
+    delete: {
+        label: 'Delete (Trash)',
+        description: 'Move to trash — recoverable for 30 days',
+        apiMethod: 'files.update (trashed) / files.delete when permanent',
+        params: [
+            fileId(),
+            {
+                name: 'permanent',
+                label: 'Delete Permanently?',
+                type: 'booleanSelect',
+                options: [
+                    { value: '', label: 'No — move to trash (recoverable)' },
+                    { value: 'true', label: '⚠️ Yes — erase forever (irreversible)' },
+                ],
+            },
+        ],
+    },
+    share: {
+        label: 'Share File',
+        description: 'Grant viewer / commenter / editor permission',
+        apiMethod: 'permissions.create',
+        params: [
+            fileId(),
+            {
+                name: 'type',
+                label: 'Share With',
+                type: 'select',
+                default: 'user',
+                options: [
+                    { value: 'user', label: 'Specific user (email)' },
+                    { value: 'group', label: 'Group (email)' },
+                    { value: 'domain', label: 'Entire domain' },
+                    { value: 'anyone', label: '⚠️ Anyone with the link (public)' },
+                ],
+            },
+            {
+                name: 'role',
+                label: 'Permission Role',
+                type: 'select',
+                default: 'reader',
+                options: [
+                    { value: 'reader', label: 'Viewer (read-only)' },
+                    { value: 'commenter', label: 'Commenter' },
+                    { value: 'writer', label: 'Editor' },
+                ],
+            },
+            {
+                name: 'emailAddress',
+                label: 'Email Address',
+                type: 'template',
+                placeholder: 'user@example.com or {{payload.email}}',
+                showWhen: { field: 'type', in: ['user', 'group'] },
+            },
+            {
+                name: 'domain',
+                label: 'Domain',
+                type: 'template',
+                placeholder: 'example.com',
+                showWhen: { field: 'type', in: ['domain'] },
+            },
+            {
+                name: 'sendNotificationEmail',
+                label: 'Notify Recipient',
+                type: 'booleanSelect',
+                options: [
+                    { value: '', label: "No — don't send email" },
+                    { value: 'true', label: 'Yes — send share notification email' },
+                ],
+            },
+        ],
+    },
+    update: {
+        label: 'Update Metadata',
+        description: 'Rename, set description, or star/unstar',
+        apiMethod: 'files.update',
+        params: [
+            fileId(),
+            { name: 'name', label: 'New Name', type: 'template', placeholder: '{{payload.title}}' },
+            {
+                name: 'description',
+                label: 'Description (optional)',
+                type: 'template',
+                placeholder: '{{payload.description}}',
+            },
+            {
+                name: 'starred',
+                label: 'Starred (optional)',
+                type: 'booleanSelect',
+                options: [
+                    { value: '', label: "— don't change —" },
+                    { value: 'true', label: '⭐ Star' },
+                    { value: 'false', label: 'Un-star' },
+                ],
+            },
+        ],
+    },
+    createFolder: {
+        label: 'Create Folder',
+        description: 'Create a new folder, optionally inside a parent',
+        apiMethod: 'files.create (folder mimeType)',
+        params: [
+            /* Mismo `name` que en update, con otra etiqueta y otro placeholder: por
+               eso los params son por operación y no un registro global de campos. */
+            { name: 'name', label: 'Folder Name', type: 'template', placeholder: 'Reports' },
+            parentFolderId(),
+        ],
+    },
+    export: {
+        label: 'Export Google Doc',
+        description: 'Export a Doc / Sheet / Slide to PDF / DOCX / XLSX',
+        apiMethod: 'files.export',
+        params: [
+            fileId(),
+            {
+                name: 'mimeType',
+                label: 'Export Format',
+                type: 'select',
+                default: 'application/pdf',
+                options: EXPORT_FORMAT_OPTIONS,
+                description: 'Export only works on Google native docs (Docs, Sheets, Slides, Drawings). For regular files use Download instead.',
+            },
+        ],
+    },
+    getPermissions: {
+        label: 'List Permissions',
+        description: 'List who has access (audit before changing)',
+        apiMethod: 'permissions.list',
+        params: [fileId()],
+    },
+};

package/dist/esm/drive-toolkit.d.ts

@@ -0,0 +1,54 @@
+/**
+ * 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.
+ */
+import type { DriveOperation } from './drive-operations.js';
+export interface DriveToolkitParameter {
+    name: string;
+    type: 'string' | 'number' | 'boolean';
+    description: string;
+    required: boolean;
+}
+export interface DriveToolkitSpec {
+    operation: DriveOperation;
+    /** Etiqueta corta de la fila en la lista de herramientas. */
+    label: string;
+    /**
+     * Nombre con el que el LLM llama a la herramienta. Todas llevan `_drive_` o
+     * `_to_drive` para no chocar con las de Gmail, Sheets o Calendar cuando un
+     * mismo AI Node tiene varios toolkits encendidos.
+     */
+    toolName: string;
+    /** Descripción (más reglas de uso) que ve el LLM. */
+    description: string;
+    parameters: DriveToolkitParameter[];
+    /** Encabezado de grupo de la página de detalle. El orden es el que agrupa. */
+    group?: string;
+    /**
+     * Marca que la herramienta cambia algo difícil de deshacer, para que la página
+     * lo enseñe y el AI Node pida confirmación. Son **dos**, las mismas que ya
+     * estaban marcadas: `delete_drive_file` y `share_drive_file`. `move` no lo
+     * lleva, y es defendible — deshacerlo es otro move.
+     */
+    destructive?: boolean;
+}
+export declare const DRIVE_TOOLKIT_SPECS: DriveToolkitSpec[];
+/** Índice por nombre de herramienta, para enrutar un `tools/call` sin recorrer. */
+export declare const DRIVE_TOOLKIT_BY_TOOL_NAME: Record<string, DriveToolkitSpec>;