@hostwebhook/node-types 1.68.0 → 1.70.0

package/dist/esm/credentials.js

@@ -0,0 +1,199 @@
+/**
+ * Registry — order matters for fallthrough behavior in pickers (most
+ * common types first), but not for correctness.
+ */
+export const CREDENTIAL_TYPES = [
+    { type: 'google_service_account' },
+    { type: 'oauth2_google' },
+    { type: 'oauth2_atlassian' },
+    { type: 'mongodb', ssrfValidated: true, tunnelable: true },
+    { type: 'postgres', ssrfValidated: true, tunnelable: true },
+    { type: 'slack_webhook' },
+    { type: 'slack_oauth' },
+    { type: 'discord_webhook' },
+    { type: 'llm_anthropic' },
+    { type: 'llm_openai' },
+    { type: 'llm_google' },
+    // La clave de API de Groq (`gsk_…`), que el usuario saca de
+    // https://console.groq.com/keys y pega. Un secreto suyo, sin OAuth de por
+    // medio, igual que los tres de arriba y que `llm_openrouter` de abajo.
+    //
+    // El sufijo es `groq` por la misma regla que explica el bloque de
+    // OpenRouter: de aquí salen `getModelsFor`/`getDefaultModel` quitando el
+    // prefijo `llm_`, así que lo que quede detrás tiene que ser LITERALMENTE el
+    // `LlmProvider`, y ése es `'groq'`.
+    //
+    // 🔥 Llega TARDE, y el agujero que tapa no era teórico: `groq` es un
+    // `LlmProvider` de pleno derecho desde hace tiempo —está en `LLM_PROVIDERS`,
+    // con sus cinco modelos en `LLM_MODELS.groq`— pero no tenía tipo de
+    // credencial. O sea que el proveedor se podía ELEGIR en el selector y no
+    // había dónde guardar su clave: una rama del catálogo inalcanzable, sin un
+    // solo error que lo dijera. El resto de la lista se anota antes de que la
+    // api exista precisamente para no llegar a esto.
+    { type: 'llm_groq' },
+    // La clave de API de OpenRouter (`sk-or-v1-…`). Un secreto pegado por el
+    // usuario, igual que los tres de arriba: no hay OAuth de por medio.
+    //
+    // El sufijo es `openrouter` y no `open_router` porque de aquí sale
+    // `getModelsFor`/`getDefaultModel` quitando el prefijo `llm_` — el resto
+    // tiene que ser LITERALMENTE el `LlmProvider`, y ése es `'openrouter'`.
+    //
+    // ⚠️ Se anota aquí ANTES de que exista nada en la api, por lo que cuenta el
+    // bloque de Mailchimp más abajo: de esta lista salen el `enum` de Mongoose y
+    // el validador del DTO, y un tipo que falte ahí no rompe al compilar — mata
+    // el `create` de la credencial en runtime, con el usuario delante.
+    //
+    // ⚠️ El vecino que faltaba y que este bloque dejó escrito —`groq` sin su
+    // `llm_groq`— ya está arriba. Lo que queda de aquel aviso es la regla que lo
+    // hizo posible, y por eso la cubre ahora un test: cada `LlmProvider` de
+    // `LLM_PROVIDERS` tiene que tener su `llm_*` en esta lista.
+    { type: 'llm_openrouter' },
+    { type: 'llm_ollama' },
+    { type: 'firecrawl' },
+    { type: 'http_auth' },
+    { type: 'aws_s3' },
+    { type: 'memory_contextwindow' },
+    { type: 'memory_mongodb', ssrfValidated: true, tunnelable: true },
+    { type: 'mcp_server' },
+    { type: 'voice_agent' },
+    { type: 'telegram_bot' },
+    { type: 'whatsapp_business' },
+    { type: 'discord_bot' },
+    // Instalar la app de HostWebhook en un servidor de Discord, vía OAuth.
+    //
+    // Es un tipo aparte de `discord_bot` y no una bandera en metadata porque
+    // lo que guarda es DISTINTO: `discord_bot` lleva el token que pegó el
+    // usuario; éste no lleva ningún secreto — el bot token es de la aplicación
+    // y vive en el entorno. Lo que guarda es a qué servidor se autorizó.
+    //
+    // Discord no devuelve un bot token por OAuth (es estático de la app), así
+    // que los dos caminos coexisten: OAuth para el caso normal, y el token
+    // propio para quien quiera un bot con su marca.
+    { type: 'discord_oauth' },
+    { type: 'bluesky_app_password' },
+    { type: 'twitter_oauth2' },
+    { type: 'mastodon_oauth2' },
+    { type: 'linkedin_oauth2' },
+    { type: 'threads_oauth2' },
+    { type: 'instagram_oauth2' },
+    { type: 'facebook_oauth2' },
+    // El secreto de una integración INTERNA de Notion (empieza por `ntn_`),
+    // pegado por el usuario. Un solo workspace, no caduca.
+    //
+    // Va aparte de un futuro `notion_oauth` por la misma razón que
+    // `discord_bot` va aparte de `discord_oauth`: lo que guardan es distinto.
+    // Aquí hay un secreto del usuario; en OAuth habría un access_token y un
+    // refresh_token de una app de HostWebhook.
+    //
+    // Y el orden importa: la URL de autorización de una integración PÚBLICA de
+    // Notion sólo se rellena tras mandarla a revisión de Notion, así que el
+    // camino interno es el único que funciona el primer día.
+    { type: 'notion_internal' },
+    // El OAuth de HostWebhook contra Notion: el usuario autoriza y elige qué
+    // páginas comparte, sin salir del producto.
+    //
+    // Va aparte de `notion_internal` por la misma razón que `discord_oauth` va
+    // aparte de `discord_bot`: lo que guardan es distinto. Ahí hay un secreto
+    // del usuario; aquí, un access_token y un refresh_token de NUESTRA app, más
+    // el `workspace_id` que Notion devuelve en el mismo intercambio.
+    //
+    // Y para que conste, porque estuvo escrito al revés en el ADR-0005 antes de
+    // corregirlo: montar esto NO espera a ninguna revisión de Notion. El
+    // formulario de Distribution entrega client id, secret y URL de
+    // autorización al pulsar Submit; la revisión de 5-10 días es para salir en
+    // su galería, o sea para que te encuentren, no para que funcione.
+    { type: 'notion_oauth' },
+    // El OAuth de HostWebhook contra Mailchimp.
+    //
+    // Faltaba, y el síntoma no señalaba aquí. La api ya tenía el flujo entero
+    // —`mailchimp-oauth.service.ts`, su controlador, su DTO y sus presets— y el
+    // usuario autorizaba bien; lo que moría era el `create` de la credencial:
+    //
+    //   ERROR [CredentialsController] Mailchimp OAuth callback failed:
+    //   Credential validation failed: type: `mailchimp_oauth2` is not a valid
+    //   enum value for path `type`.
+    //
+    // Porque de esta lista salen las DOS validaciones que ve ese documento: el
+    // `enum` de Mongoose en `credential.entity.ts` y el `@IsIn` del DTO. La api
+    // declaraba el string por su cuenta (`MAILCHIMP_CREDENTIAL_TYPE`) sin
+    // anotarlo `: CredentialType`, así que TypeScript lo dio por bueno y sólo
+    // reventó en producción, contra un cliente que no podía conectar su cuenta.
+    //
+    // Lleva `_oauth2` y no `_oauth` —al revés que `notion_oauth`— porque ése es
+    // el string que la api ya guarda y que el dashboard ya filtra en
+    // `components/triggers/registry.tsx` (`scopeFilter: "mailchimp_oauth2"`).
+    // Renombrarlo ahora rompería las credenciales que hayan llegado a existir:
+    // el `type` es la clave por la que los nodos las referencian.
+    { type: 'mailchimp_oauth2' },
+    // El OAuth de HostWebhook contra Shopify.
+    //
+    // Se anota aquí ANTES de escribir el servicio, precisamente por lo que
+    // cuenta el bloque de Mailchimp de arriba: la api puede tener el flujo
+    // entero y bien, y aun así el `create` de la credencial muere con un enum
+    // de Mongoose que TypeScript no ve. Es el mismo agujero, y ya sabemos que
+    // no avisa al compilar.
+    //
+    // Lleva `_oauth2` por coherencia con `mailchimp_oauth2`, y porque el
+    // `scopeFilter` del dashboard filtra por esta cadena exacta.
+    //
+    // Una nota sobre lo que este tipo GUARDA, que aquí no se ve: el dominio de
+    // la tienda (`{shop}.myshopify.com`) viaja DENTRO del blob cifrado, igual
+    // que el `dc` de Mailchimp. Es parte del host de toda llamada y de la URL
+    // de autorización, así que una credencial de Shopify sin su dominio es
+    // inservible — no un detalle de presentación.
+    { type: 'shopify_oauth2' },
+    // La instalación de la GitHub App de HostWebhook. El camino PRINCIPAL: el
+    // usuario pulsa "Connect GitHub", elige en qué repos entra, y vuelve.
+    //
+    // Lo que guarda es un `installationId` y NINGÚN secreto — la private key es
+    // de la app y vive en el entorno (`GITHUB_APP_PRIVATE_KEY_BASE64`). El token
+    // de instalación es corto y se re-emite firmando con esa llave, así que aquí
+    // no hay nada que caduque en la base de datos.
+    //
+    // Va aparte de `github_pat` por lo mismo que `discord_oauth` va aparte de
+    // `discord_bot`: lo que guardan es distinto.
+    //
+    // ⚠️ No confundir con `GITHUB_OAUTH_CLIENT_ID`/`_SECRET`, que ya existían y
+    // son de una OAuth App DISTINTA — la que usa `MCP_OAUTH_PRESETS.github` para
+    // llegar al servidor MCP de GitHub. Dos registros, dos pares de credenciales,
+    // y conviven a propósito: el MCP es la cola larga dentro del AI Node, esto
+    // son los rieles del nodo.
+    { type: 'github_app' },
+    // Un fine-grained personal access token pegado por el usuario. La salida de
+    // emergencia, detrás de "Use a personal access token instead".
+    //
+    // Aquí SÍ hay un secreto del usuario, y además caduca: GitHub obliga a
+    // ponerles fecha. Un aviso antes de que muera es trabajo pendiente, no de
+    // esta versión.
+    //
+    // Ejecuta exactamente las mismas 14 operaciones que `github_app`. Lo único
+    // que cambia es de dónde sale la lista de repositorios del formulario: los
+    // del usuario, en vez de los que abarca una instalación.
+    { type: 'github_pat' },
+    /* ⚠️ `as const satisfies …` y no `: readonly CredentialTypeRegistration[]`.
+       Los dos comprueban lo mismo —que cada entrada tenga la forma del registro—,
+       pero la ANOTACIÓN además ENSANCHA lo que se guarda: con ella cada `type` se
+       recuerda como `string`, y entonces `CredentialType` de más abajo es
+       literalmente `string`. O sea que la promesa de su comentario («un typo al
+       asignar falla al compilar») era falsa desde el primer día: `const t:
+       CredentialType = 'llm_openroutr'` compilaba sin rechistar.
+  
+       `satisfies` comprueba y NO ensancha, así que los literales sobreviven y la
+       unión es de verdad. El control está en `tipos-de-credencial.test.ts`. */
+];
+/**
+ * Plain string array — what the Mongoose `enum` field and the
+ * class-validator `@IsIn(...)` decorator both consume. Keep it as a
+ * readonly array so misuse (push/pop) breaks at compile time.
+ */
+export const CREDENTIAL_TYPE_VALUES = CREDENTIAL_TYPES.map((c) => c.type);
+/** Mutable copy for APIs that take `string[]` (Mongoose `enum`,
+ *  class-validator). The array itself is freshly built each access
+ *  so callers can't mutate the canonical list. */
+export const credentialTypeValues = () => [...CREDENTIAL_TYPE_VALUES];
+export function getCredentialType(type) {
+    return CREDENTIAL_TYPES.find((c) => c.type === type);
+}
+export function isCredentialType(type) {
+    return CREDENTIAL_TYPE_VALUES.includes(type);
+}

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

@@ -0,0 +1,104 @@
+/**
+ * Discord Bot API operation enum — single source of truth across the
+ * API, Dashboard, and any future consumers (Message Broker, MCP server).
+ * Used by:
+ *   - discordAction entity / DTO (api): operation field + validation
+ *   - dashboard DiscordAction operation picker + form generation
+ *   - MCP toolkit-specs expansion (one aiEnabled discordAction → N tools)
+ *
+ * Targets Discord API v10 (the current stable as of 2026). Each op maps
+ * to a single REST call — most go through the Bot Token to the channel/
+ * guild/user resource. createThread + createChannel + sendDM each have
+ * their own multi-step flows handled inside the dispatcher.
+ *
+ * Phase 1 covers 17 ops that handle the bulk of bot automation
+ * (messaging, channel CRUD, threads, DMs, role membership, lookups).
+ * Phase 1.5 candidates (kick / ban / timeout / role CRUD / bulk delete /
+ * forum-post create) extend this list — bump the package and re-install
+ * in consumers, same pattern as Gmail / Calendar / Drive / Telegram.
+ */
+import { type CapacidadesPorCredencial } from './capacidad-de-credencial.js';
+export declare const DISCORD_OPERATIONS: readonly ["sendMessage", "editMessage", "deleteMessage", "getMessage", "addReaction", "removeReaction", "pinMessage", "createChannel", "editChannel", "deleteChannel", "getChannel", "listChannels", "createThread", "sendDM", "addRole", "removeRole", "getMember"];
+export type DiscordOperation = (typeof DISCORD_OPERATIONS)[number];
+/** Type guard — useful when validating untrusted input (DTOs, tool calls). */
+export declare function isDiscordOperation(value: unknown): value is DiscordOperation;
+export interface DiscordParamSpec {
+    /** Field key — also the property name on operationConfig / payload. */
+    name: string;
+    /** UI label. Carries the "(optional)" suffix when the form shows one. */
+    label: string;
+    /**
+     * Param type for form rendering + AI tool schema.
+     *
+     * `channel`, `string`, `text`, `number`, `boolean` and `emoji` mean the same
+     * as in SlackParamSpec. `guild`, `role`, `member` and `select` are Discord's
+     * own: the first three map to its resource pickers, and `select` is a fixed
+     * option list (channel kind, thread kind, archive window) that Slack has no
+     * equivalent for.
+     */
+    type: 'channel' | 'guild' | 'role' | 'member' | 'string' | 'text' | 'number' | 'boolean' | 'emoji' | 'select';
+    /** Required at submit time. */
+    required?: boolean;
+    /** Human description — also used as the AI tool param description. */
+    description: string;
+    /** Hint shown inside the input. */
+    placeholder?: string;
+    /** Value to show when the stored one is undefined. */
+    default?: string | number | boolean;
+    /** `select` only — the fixed option list, in display order. */
+    options?: Array<{
+        value: string | number;
+        label: string;
+    }>;
+    /** `number` only. */
+    min?: number;
+    max?: number;
+    /** `text` only — height of the textarea. */
+    rows?: number;
+    /** `channel` only — let categories be picked, for parent-category fields. */
+    allowCategories?: boolean;
+    /** `boolean` only — the bold line beside the switch. */
+    switchLabel?: string;
+}
+export interface DiscordOperationSpec {
+    /** UI label for the operation picker. */
+    label: string;
+    /** Description shown in the picker + reused by the AI tool description
+     *  when the user hasn't set a custom one on the entity. */
+    description: string;
+    /** Route the operation maps to in Discord's docs (discord.com/developers). */
+    apiMethod: string;
+    /** Parameter schema. Order matters for form rendering. */
+    params: DiscordParamSpec[];
+}
+export declare const DISCORD_OPERATION_SPECS: Record<DiscordOperation, DiscordOperationSpec>;
+/**
+ * Lo que puede hacer una credencial de Discord que NO es de bot.
+ *
+ * Medido contra la documentación de Discord, no de memoria:
+ * https://docs.discord.com/developers/resources/webhook
+ *
+ * `Execute Webhook` publica, y `Get/Edit/Delete Webhook Message` leen, editan y
+ * borran mensajes — pero **sólo los que envió ese mismo webhook**, y sólo en el
+ * canal para el que se creó. Las otras 13 (reacciones, pins, CRUD de canales,
+ * crear hilos, DMs, roles, miembros) piden un Bot Token: la propia doc las
+ * marca con `MANAGE_WEBHOOKS` o con permisos de guild.
+ *
+ * Los tres campos que se caen de `sendMessage`, uno por uno:
+ *
+ *   - `channelId`: la URL del webhook YA dice el canal. El endpoint ni siquiera
+ *     acepta `channel_id`.
+ *   - `replyToMessageId`: `Execute Webhook` no acepta `message_reference`. No
+ *     es que venga fijado — es que responder no existe por esta vía.
+ *   - `interactionReply`: contestar a un slash command es cosa de la
+ *     aplicación, no de un webhook.
+ *
+ * `threadId` SÍ se queda: `?thread_id=` es parámetro de query del endpoint.
+ */
+export declare const DISCORD_CAPACIDADES_POR_CREDENCIAL: CapacidadesPorCredencial<DiscordOperation>;
+/** Las operaciones que ofrecer para una credencial de Discord. */
+export declare function operacionesDeDiscordPara(tipoDeCredencial: string | null | undefined): readonly DiscordOperation[];
+/** Si esa credencial puede ejecutar esa operación de Discord. */
+export declare function discordPuedeEjecutar(tipoDeCredencial: string | null | undefined, operacion: DiscordOperation): boolean;
+/** Los campos que esa credencial de Discord no deja elegir. */
+export declare function camposDeDiscordNoDisponibles(tipoDeCredencial: string | null | undefined): ReadonlySet<string>;