@hostwebhook/node-types 1.69.0 → 1.71.0

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

@@ -0,0 +1,125 @@
+/**
+ * Notion operation enum — single source of truth across the API, Dashboard y
+ * Message Broker. Lo usan:
+ *   - notionAction entity / DTO (api): campo `operation` + validación
+ *   - la página de detalle del dashboard
+ *   - specs de toolkit MCP, si algún día el nodo gana modo herramienta
+ *
+ * Mismo patrón que `google-analytics-operations.ts` y `drive-operations.ts`.
+ *
+ * ── Contra qué versión está escrito ──
+ *
+ * `Notion-Version: 2026-03-11`. Importa más de lo normal porque Notion movió
+ * cosas de sitio dos veces seguidas y los ejemplos que hay por internet están
+ * casi todos contra la API anterior:
+ *
+ *   - 2025-09-03 partió `database` en database + **data source**. El query
+ *     dejó de vivir en `databases/{id}/query` y pasó a
+ *     `data_sources/{id}/query`. Una database contiene N data sources.
+ *   - 2026-03-11 quitó el alias `archived` (ahora es **`in_trash`**), cambió
+ *     el `after` de append blocks por un objeto **`position`**, y renombró el
+ *     bloque `transcription` a `meeting_notes`.
+ *
+ * ── Por qué hay operaciones de markdown ──
+ *
+ * Escribir contenido en Notion era construir un árbol de bloques a mano, que
+ * es con diferencia lo más pesado de su API. Desde 2026-03-11 hay
+ * `GET/PATCH /v1/pages/{id}/markdown`, disponible —lo dicen los docs con esas
+ * palabras— para "all connection types (public, internal, and personal access
+ * tokens)". Con eso, escribir una página es mandar texto.
+ *
+ * Y el markdown cubre también el añadir-sin-pisar, vía el comando
+ * `insert_content` con `position: end`. `PATCH /v1/blocks/{id}/children` NO
+ * acepta markdown —sólo objetos de bloque—, así que la única op de bloques que
+ * queda es la de LEER la estructura cruda, que es lo que markdown no da.
+ *
+ * ── Lo que NO es una operación ──
+ *
+ * Listar las databases/data sources a las que la credencial tiene acceso, y
+ * leer el esquema para pintar un selector, NO son ops del nodo: son endpoints
+ * del controlador, como Drive alimenta su `DriveFilePicker`. Una op existe
+ * para producir payload en una corrida; esto otro es para rellenar el
+ * formulario.
+ *
+ * ── Decisiones propias de Notion (anti-n8n) ──
+ *
+ *   - La database/data source y la página se ELIGEN de una lista viva, no se
+ *     teclean. Un id de Notion es un UUID sin guiones dentro de una URL larga;
+ *     pedirle eso al usuario es pedirle que se equivoque.
+ *   - Las propiedades de una página van en JSON crudo salvo el título, que es
+ *     el 90% de los casos y tiene campo propio. Cada tipo de propiedad de
+ *     Notion tiene una forma distinta (`rich_text`, `select`, `date`,
+ *     `relation`…) y fingir que caben en tres campos genéricos produce un 400
+ *     que no explica nada.
+ *   - Ninguna op declarada sin implementar. El enum ES el contrato de la
+ *     pantalla: una op declarada se pinta en el desplegable y falla al
+ *     ejecutarse. Entran cuando entre su código.
+ */
+export declare const NOTION_OPERATIONS: readonly ["createPage", "getPage", "getPageMarkdown", "updatePageProperties", "updatePageMarkdown", "archivePage", "queryDataSource", "getDataSource", "appendToPage", "getBlockChildren", "search", "createComment"];
+export type NotionOperation = (typeof NOTION_OPERATIONS)[number];
+/** Type guard — para validar entrada no fiable (DTOs, tool calls). */
+export declare function isNotionOperation(value: unknown): value is NotionOperation;
+export type NotionParamType = 
+/** Selector vivo de data sources accesibles (necesita credencial). */
+'notionDataSource'
+/** Selector vivo de páginas accesibles; admite pegar un id o una URL. */
+ | 'notionPage'
+/** Cualquier bloque contenedor: una página vale como bloque. */
+ | 'notionBlock'
+/** 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 (propiedades, filtros, orden). */
+ | 'json';
+export interface NotionParamSpec {
+    /** La clave de `operationConfig`. Es lo que lee la api, no un nombre de UI. */
+    name: string;
+    label: string;
+    type: NotionParamType;
+    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 NotionOperationSpec {
+    /** Etiqueta de la fila en el desplegable de operación. */
+    label: string;
+    /** Sub-línea bajo la etiqueta. */
+    description: string;
+    /** Endpoint al que mapea, tal cual, para poder cotejarlo con los docs. */
+    apiMethod: string;
+    /** Esquema de parámetros. El orden ES el orden en pantalla. */
+    params: NotionParamSpec[];
+}
+export declare const NOTION_OPERATION_SPECS: Record<NotionOperation, NotionOperationSpec>;
+/**
+ * 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 NOTION_DROPDOWN_OPERATIONS: readonly NotionOperation[];

package/dist/esm/notion-operations.js

@@ -0,0 +1,511 @@
+/**
+ * Notion operation enum — single source of truth across the API, Dashboard y
+ * Message Broker. Lo usan:
+ *   - notionAction entity / DTO (api): campo `operation` + validación
+ *   - la página de detalle del dashboard
+ *   - specs de toolkit MCP, si algún día el nodo gana modo herramienta
+ *
+ * Mismo patrón que `google-analytics-operations.ts` y `drive-operations.ts`.
+ *
+ * ── Contra qué versión está escrito ──
+ *
+ * `Notion-Version: 2026-03-11`. Importa más de lo normal porque Notion movió
+ * cosas de sitio dos veces seguidas y los ejemplos que hay por internet están
+ * casi todos contra la API anterior:
+ *
+ *   - 2025-09-03 partió `database` en database + **data source**. El query
+ *     dejó de vivir en `databases/{id}/query` y pasó a
+ *     `data_sources/{id}/query`. Una database contiene N data sources.
+ *   - 2026-03-11 quitó el alias `archived` (ahora es **`in_trash`**), cambió
+ *     el `after` de append blocks por un objeto **`position`**, y renombró el
+ *     bloque `transcription` a `meeting_notes`.
+ *
+ * ── Por qué hay operaciones de markdown ──
+ *
+ * Escribir contenido en Notion era construir un árbol de bloques a mano, que
+ * es con diferencia lo más pesado de su API. Desde 2026-03-11 hay
+ * `GET/PATCH /v1/pages/{id}/markdown`, disponible —lo dicen los docs con esas
+ * palabras— para "all connection types (public, internal, and personal access
+ * tokens)". Con eso, escribir una página es mandar texto.
+ *
+ * Y el markdown cubre también el añadir-sin-pisar, vía el comando
+ * `insert_content` con `position: end`. `PATCH /v1/blocks/{id}/children` NO
+ * acepta markdown —sólo objetos de bloque—, así que la única op de bloques que
+ * queda es la de LEER la estructura cruda, que es lo que markdown no da.
+ *
+ * ── Lo que NO es una operación ──
+ *
+ * Listar las databases/data sources a las que la credencial tiene acceso, y
+ * leer el esquema para pintar un selector, NO son ops del nodo: son endpoints
+ * del controlador, como Drive alimenta su `DriveFilePicker`. Una op existe
+ * para producir payload en una corrida; esto otro es para rellenar el
+ * formulario.
+ *
+ * ── Decisiones propias de Notion (anti-n8n) ──
+ *
+ *   - La database/data source y la página se ELIGEN de una lista viva, no se
+ *     teclean. Un id de Notion es un UUID sin guiones dentro de una URL larga;
+ *     pedirle eso al usuario es pedirle que se equivoque.
+ *   - Las propiedades de una página van en JSON crudo salvo el título, que es
+ *     el 90% de los casos y tiene campo propio. Cada tipo de propiedad de
+ *     Notion tiene una forma distinta (`rich_text`, `select`, `date`,
+ *     `relation`…) y fingir que caben en tres campos genéricos produce un 400
+ *     que no explica nada.
+ *   - Ninguna op declarada sin implementar. El enum ES el contrato de la
+ *     pantalla: una op declarada se pinta en el desplegable y falla al
+ *     ejecutarse. Entran cuando entre su código.
+ */
+export const NOTION_OPERATIONS = [
+    // Páginas
+    'createPage', // POST   /v1/pages
+    'getPage', // GET    /v1/pages/{id}
+    'getPageMarkdown', // GET    /v1/pages/{id}/markdown
+    'updatePageProperties', // PATCH  /v1/pages/{id}
+    'updatePageMarkdown', // PATCH  /v1/pages/{id}/markdown
+    'archivePage', // PATCH  /v1/pages/{id}  { in_trash: true }
+    // Data sources (lo que antes era "la database")
+    'queryDataSource', // POST   /v1/data_sources/{id}/query
+    'getDataSource', // GET    /v1/data_sources/{id}
+    // Bloques
+    'appendToPage', // PATCH  /v1/pages/{id}/markdown  (insert_content)
+    'getBlockChildren', // GET    /v1/blocks/{id}/children
+    // Transversales
+    'search', // POST   /v1/search
+    'createComment', // POST   /v1/comments
+];
+/** Type guard — para validar entrada no fiable (DTOs, tool calls). */
+export function isNotionOperation(value) {
+    return (typeof value === 'string' &&
+        NOTION_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 pageId = (label = 'Page') => ({
+    name: 'pageId',
+    label,
+    type: 'notionPage',
+    required: true,
+    description: 'Pick a page the connection can see, or paste a page URL or id — a templated value like {{payload.pageId}} works too. Notion only shows pages that were explicitly shared with this connection.',
+});
+const dataSourceId = () => ({
+    name: 'dataSourceId',
+    label: 'Data source',
+    type: 'notionDataSource',
+    required: true,
+    description: 'Since API version 2025-09-03 a database holds one or more data sources, and rows live in the data source — not in the database. Most databases have exactly one.',
+});
+/** El JSON de propiedades, con el aviso que ahorra el 400 más común. */
+const propertiesJson = () => ({
+    name: 'properties',
+    label: 'Properties (JSON)',
+    type: 'json',
+    advanced: true,
+    placeholder: '{ "Status": { "select": { "name": "In progress" } }, "Due": { "date": { "start": "2026-09-01" } } }',
+    description: 'Raw Notion property values, keyed by property name. Every property type has its own shape (rich_text, select, date, relation, …) — check the data source schema. Leave empty to only set the title.',
+});
+const notionVersionNote = 'Runs against Notion-Version 2026-03-11.';
+export const NOTION_OPERATION_SPECS = {
+    createPage: {
+        label: 'Create page',
+        description: 'A new page — as a row in a data source, or under another page.',
+        apiMethod: 'POST /v1/pages',
+        params: [
+            {
+                name: 'parentType',
+                label: 'Create it in',
+                type: 'select',
+                required: true,
+                default: 'data_source',
+                options: [
+                    { value: 'data_source', label: 'A data source (adds a row)' },
+                    { value: 'page', label: 'Another page (adds a subpage)' },
+                ],
+                description: 'A row in a database IS a page in Notion — same object, different parent.',
+            },
+            {
+                ...dataSourceId(),
+                showWhen: { field: 'parentType', in: ['data_source'] },
+            },
+            {
+                ...pageId('Parent page'),
+                name: 'parentPageId',
+                showWhen: { field: 'parentType', in: ['page'] },
+            },
+            {
+                name: 'title',
+                label: 'Title',
+                type: 'template',
+                required: true,
+                placeholder: '{{payload.subject}}',
+                description: 'Goes into the title property, whatever it is called in this data source.',
+            },
+            {
+                name: 'markdown',
+                label: 'Content (Markdown)',
+                type: 'textarea',
+                placeholder: '## Summary\n\n{{payload.body}}',
+                description: 'The page body, as Notion-flavored Markdown. This is the shortcut that avoids building a block tree by hand.',
+            },
+            {
+                name: 'icon',
+                label: 'Icon',
+                type: 'template',
+                advanced: true,
+                placeholder: '🚀',
+                description: 'A single emoji, or an external image URL.',
+            },
+            propertiesJson(),
+        ],
+    },
+    getPage: {
+        label: 'Get page',
+        description: 'The page object and its properties — not its content.',
+        apiMethod: 'GET /v1/pages/{page_id}',
+        params: [
+            pageId(),
+            {
+                name: 'filterProperties',
+                label: 'Only these properties',
+                type: 'template',
+                advanced: true,
+                placeholder: 'title,Status,Due',
+                description: 'Comma-separated property names. Notion returns every property by default, which on a wide database is a lot of payload for nothing.',
+            },
+        ],
+    },
+    getPageMarkdown: {
+        label: 'Get page as Markdown',
+        description: 'The whole page content as one Markdown string.',
+        apiMethod: 'GET /v1/pages/{page_id}/markdown',
+        params: [
+            pageId(),
+            {
+                name: 'includeTranscript',
+                label: 'Include meeting transcript',
+                type: 'booleanSelect',
+                advanced: true,
+                options: [
+                    { value: '', label: '— leave alone —' },
+                    { value: 'true', label: 'Yes' },
+                    { value: 'false', label: 'No' },
+                ],
+                description: 'Only matters on pages holding meeting notes. Transcripts can be very long.',
+            },
+        ],
+    },
+    updatePageProperties: {
+        label: 'Update page properties',
+        description: 'Change property values — status, dates, relations.',
+        apiMethod: 'PATCH /v1/pages/{page_id}',
+        params: [
+            pageId(),
+            {
+                name: 'title',
+                label: 'New title',
+                type: 'template',
+                description: 'Leave empty to keep the current title.',
+            },
+            {
+                ...propertiesJson(),
+                advanced: false,
+                description: 'Raw Notion property values, keyed by property name. Only the properties you list are touched; the rest keep their value. Every property type has its own shape (rich_text, select, date, relation, …).',
+            },
+            {
+                name: 'icon',
+                label: 'Icon',
+                type: 'template',
+                advanced: true,
+                placeholder: '✅',
+                description: 'A single emoji, or an external image URL.',
+            },
+        ],
+    },
+    updatePageMarkdown: {
+        label: 'Update page content',
+        description: 'Rewrite the body, or search and replace inside it.',
+        apiMethod: 'PATCH /v1/pages/{page_id}/markdown',
+        params: [
+            pageId(),
+            {
+                name: 'mode',
+                label: 'How',
+                type: 'select',
+                required: true,
+                default: 'replace_content',
+                options: [
+                    { value: 'replace_content', label: 'Replace the whole body' },
+                    { value: 'update_content', label: 'Find and replace' },
+                ],
+                description: 'Replacing drops everything currently on the page — including blocks this flow did not write.',
+            },
+            {
+                name: 'markdown',
+                label: 'New content (Markdown)',
+                type: 'textarea',
+                required: true,
+                showWhen: { field: 'mode', in: ['replace_content'] },
+                placeholder: '## Report\n\n{{payload.summary}}',
+            },
+            {
+                name: 'find',
+                label: 'Find',
+                type: 'template',
+                required: true,
+                showWhen: { field: 'mode', in: ['update_content'] },
+                description: 'The exact text to look for. Notion matches it literally, not as a regex.',
+            },
+            {
+                name: 'replace',
+                label: 'Replace with',
+                type: 'textarea',
+                showWhen: { field: 'mode', in: ['update_content'] },
+                description: 'Leave empty to delete the matched text.',
+            },
+        ],
+    },
+    archivePage: {
+        label: 'Archive page',
+        description: 'Send it to the trash, or bring it back.',
+        apiMethod: 'PATCH /v1/pages/{page_id}',
+        params: [
+            pageId(),
+            {
+                name: 'inTrash',
+                label: 'Trashed',
+                type: 'booleanSelect',
+                required: true,
+                default: 'true',
+                options: [
+                    { value: 'true', label: 'Move to trash' },
+                    { value: 'false', label: 'Restore from trash' },
+                ],
+                description: 'Notion calls this in_trash since API version 2026-03-11; the old archived field is gone. Trashed pages are recoverable for 30 days.',
+            },
+        ],
+    },
+    queryDataSource: {
+        label: 'Query data source',
+        description: 'Rows matching a filter, in the order you ask for.',
+        apiMethod: 'POST /v1/data_sources/{data_source_id}/query',
+        params: [
+            dataSourceId(),
+            {
+                name: 'filterProperty',
+                label: 'Filter — property',
+                type: 'template',
+                placeholder: 'Status',
+                description: 'The property name as it reads in Notion. Leave the three filter fields empty to get everything.',
+            },
+            {
+                name: 'filterCondition',
+                label: 'Filter — condition',
+                type: 'select',
+                default: 'equals',
+                options: [
+                    { value: 'equals', label: 'equals' },
+                    { value: 'does_not_equal', label: 'does not equal' },
+                    { value: 'contains', label: 'contains' },
+                    { value: 'does_not_contain', label: 'does not contain' },
+                    { value: 'is_empty', label: 'is empty' },
+                    { value: 'is_not_empty', label: 'is not empty' },
+                    { value: 'after', label: 'is after (date)' },
+                    { value: 'before', label: 'is before (date)' },
+                    { value: 'on_or_after', label: 'is on or after (date)' },
+                ],
+            },
+            {
+                name: 'filterValue',
+                label: 'Filter — value',
+                type: 'template',
+                placeholder: 'In progress',
+                showWhen: {
+                    field: 'filterCondition',
+                    in: [
+                        'equals',
+                        'does_not_equal',
+                        'contains',
+                        'does_not_contain',
+                        'after',
+                        'before',
+                        'on_or_after',
+                    ],
+                },
+            },
+            {
+                name: 'sortProperty',
+                label: 'Sort by',
+                type: 'template',
+                placeholder: 'last_edited_time',
+                description: 'A property name, or the built-ins created_time / last_edited_time.',
+            },
+            {
+                name: 'sortDirection',
+                label: 'Direction',
+                type: 'select',
+                default: 'descending',
+                options: [
+                    { value: 'descending', label: 'Newest first' },
+                    { value: 'ascending', label: 'Oldest first' },
+                ],
+            },
+            {
+                name: 'pageSize',
+                label: 'How many',
+                type: 'number',
+                default: 25,
+                min: 1,
+                max: 100,
+                description: 'Notion caps a single query at 100 rows. Past that it paginates, and this node returns the first page only.',
+            },
+            {
+                name: 'filterJson',
+                label: 'Filter (raw JSON)',
+                type: 'json',
+                advanced: true,
+                placeholder: '{ "and": [ { "property": "Status", "select": { "equals": "Done" } } ] }',
+                description: 'The escape hatch for anything the three fields above cannot say — compound and/or, rollups, formulas. When this is filled in, it WINS and the simple filter is ignored.',
+            },
+        ],
+    },
+    getDataSource: {
+        label: 'Get data source schema',
+        description: 'Which properties exist and what type each one is.',
+        apiMethod: 'GET /v1/data_sources/{data_source_id}',
+        params: [dataSourceId()],
+    },
+    appendToPage: {
+        label: 'Append content',
+        description: 'Add to a page without touching what is already there.',
+        apiMethod: 'PATCH /v1/pages/{page_id}/markdown (insert_content)',
+        params: [
+            pageId(),
+            {
+                name: 'markdown',
+                label: 'Content (Markdown)',
+                type: 'textarea',
+                required: true,
+                placeholder: '- [ ] {{payload.task}}',
+                description: 'Appended as new blocks. Nothing already on the page is touched — this is the safe alternative to replacing the body.',
+            },
+            {
+                name: 'position',
+                label: 'Where',
+                type: 'select',
+                default: 'end',
+                options: [
+                    { value: 'end', label: 'At the end' },
+                    { value: 'start', label: 'At the top' },
+                ],
+            },
+        ],
+    },
+    getBlockChildren: {
+        label: 'Get block children',
+        description: 'The raw block tree, one level down.',
+        apiMethod: 'GET /v1/blocks/{block_id}/children',
+        params: [
+            {
+                name: 'blockId',
+                label: 'Page or block',
+                type: 'notionBlock',
+                required: true,
+                description: 'For reading a whole page as text, "Get page as Markdown" is almost always the one you want instead.',
+            },
+            {
+                name: 'pageSize',
+                label: 'How many',
+                type: 'number',
+                default: 50,
+                min: 1,
+                max: 100,
+            },
+        ],
+    },
+    search: {
+        label: 'Search',
+        description: 'Find pages and data sources by title.',
+        apiMethod: 'POST /v1/search',
+        params: [
+            {
+                name: 'query',
+                label: 'Query',
+                type: 'template',
+                placeholder: '{{payload.customerName}}',
+                description: 'Matches against titles only, not page content. Empty returns everything shared with the connection.',
+            },
+            {
+                name: 'filterObject',
+                label: 'Only',
+                type: 'select',
+                default: '',
+                options: [
+                    { value: '', label: 'Pages and data sources' },
+                    { value: 'page', label: 'Pages' },
+                    { value: 'data_source', label: 'Data sources' },
+                ],
+            },
+            {
+                name: 'sortDirection',
+                label: 'Sort by last edited',
+                type: 'select',
+                default: 'descending',
+                options: [
+                    { value: 'descending', label: 'Newest first' },
+                    { value: 'ascending', label: 'Oldest first' },
+                ],
+            },
+            {
+                name: 'pageSize',
+                label: 'How many',
+                type: 'number',
+                default: 25,
+                min: 1,
+                max: 100,
+            },
+        ],
+    },
+    createComment: {
+        label: 'Add comment',
+        description: 'A comment on a page, or a reply in an existing thread.',
+        apiMethod: 'POST /v1/comments',
+        params: [
+            {
+                name: 'target',
+                label: 'Comment on',
+                type: 'select',
+                required: true,
+                default: 'page',
+                options: [
+                    { value: 'page', label: 'A page' },
+                    { value: 'discussion', label: 'An existing thread' },
+                ],
+            },
+            {
+                ...pageId(),
+                showWhen: { field: 'target', in: ['page'] },
+            },
+            {
+                name: 'discussionId',
+                label: 'Discussion id',
+                type: 'template',
+                required: true,
+                showWhen: { field: 'target', in: ['discussion'] },
+                description: 'Comes from a comment.created trigger payload, or from Get page comments.',
+            },
+            {
+                name: 'text',
+                label: 'Comment',
+                type: 'textarea',
+                required: true,
+                placeholder: 'Handled automatically — {{payload.result}}',
+                description: `Plain text. ${notionVersionNote}`,
+            },
+        ],
+    },
+};
+/**
+ * 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 const NOTION_DROPDOWN_OPERATIONS = NOTION_OPERATIONS;