@hostwebhook/node-types 1.69.0 → 1.70.0

package/dist/esm/discord-operations.js

@@ -0,0 +1,407 @@
+/**
+ * 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 { camposNoDisponiblesPara, operacionesPara, puedeEjecutar, } from './capacidad-de-credencial.js';
+export const DISCORD_OPERATIONS = [
+    // Messages
+    'sendMessage',
+    'editMessage',
+    'deleteMessage',
+    'getMessage',
+    'addReaction',
+    'removeReaction',
+    'pinMessage',
+    // Channels
+    'createChannel',
+    'editChannel',
+    'deleteChannel',
+    'getChannel',
+    'listChannels',
+    // Threads
+    'createThread',
+    // DMs
+    'sendDM',
+    // Members & roles
+    'addRole',
+    'removeRole',
+    'getMember',
+];
+/** Type guard — useful when validating untrusted input (DTOs, tool calls). */
+export function isDiscordOperation(value) {
+    return (typeof value === 'string' &&
+        DISCORD_OPERATIONS.includes(value));
+}
+/* Fields several operations share. Each takes overrides because the same key
+   can want different wording per operation: messageId is a required "Message
+   ID" in six ops and an optional anchor in createThread. */
+const channelId = (over = {}) => ({
+    name: 'channelId',
+    label: 'Channel ID',
+    type: 'channel',
+    required: true,
+    placeholder: '{{payload.channelId}}',
+    description: 'Snowflake of the channel. The picker auto-discovers the channels the bot can see; a template such as {{payload.channelId}} works too.',
+    ...over,
+});
+const guildId = (over = {}) => ({
+    name: 'guildId',
+    label: 'Guild ID',
+    type: 'guild',
+    required: true,
+    description: 'Snowflake of the server. The picker auto-discovers the servers the bot belongs to; a template such as {{payload.guildId}} works too.',
+    ...over,
+});
+const messageId = (over = {}) => ({
+    name: 'messageId',
+    label: 'Message ID',
+    type: 'string',
+    required: true,
+    placeholder: '{{payload.messageId}}',
+    description: 'Snowflake of the message.',
+    ...over,
+});
+const userId = (over = {}) => ({
+    name: 'userId',
+    label: 'User ID',
+    type: 'member',
+    required: true,
+    description: 'Snowflake of the user. Listing members needs the Server Members Intent enabled in Developer Portal.',
+    ...over,
+});
+const roleId = (over = {}) => ({
+    name: 'roleId',
+    label: 'Role ID',
+    type: 'role',
+    required: true,
+    description: 'Snowflake of the role. The role of the bot itself must sit above the target role in the hierarchy for grant and remove to work.',
+    ...over,
+});
+const emoji = () => ({
+    name: 'emoji',
+    label: 'Emoji',
+    type: 'emoji',
+    required: true,
+    placeholder: 'name:id',
+    description: 'Unicode emoji, or a custom server emoji written as name:id. URL-encoding is handled.',
+});
+const content = () => ({
+    name: 'content',
+    label: 'Message content',
+    type: 'text',
+    required: true,
+    rows: 4,
+    placeholder: 'Hello! Anything I can help with?',
+    description: 'Message text. Markdown is supported, up to the 2000 characters Discord allows.',
+});
+const topic = (label) => ({
+    name: 'topic',
+    label,
+    type: 'text',
+    rows: 2,
+    placeholder: label.startsWith('New') ? 'New description' : 'Channel description',
+    description: 'Channel description, shown under its name in Discord.',
+});
+const slowmode = (label) => ({
+    name: 'slowmode',
+    label,
+    type: 'number',
+    min: 0,
+    max: 21600,
+    default: 0,
+    description: 'Seconds a member has to wait between messages. 0 turns slowmode off, 21600 is the six-hour maximum.',
+});
+const parentId = (label) => ({
+    name: 'parentId',
+    label,
+    type: 'channel',
+    allowCategories: true,
+    placeholder: 'Snowflake of a category',
+    description: 'Category to nest the channel under. Categories show in the picker with a folder icon.',
+});
+export const DISCORD_OPERATION_SPECS = {
+    // ── Messages ──────────────────────────────────────────────────────
+    sendMessage: {
+        label: 'Send message',
+        description: 'Post text/embed to a channel or thread. Optional reply-to + threadId.',
+        apiMethod: 'POST /channels/{channel.id}/messages',
+        params: [
+            channelId(),
+            content(),
+            {
+                name: 'replyToMessageId',
+                label: 'Reply to message ID (optional)',
+                type: 'string',
+                placeholder: '{{payload.messageId}}',
+                description: 'Snowflake of a message to quote-reply to.',
+            },
+            {
+                name: 'threadId',
+                label: 'Thread ID (optional)',
+                type: 'string',
+                placeholder: '{{payload.threadId}}',
+                description: 'Thread snowflake. When set, the message is posted into that thread instead of the parent channel.',
+            },
+            {
+                name: 'interactionReply',
+                label: 'Reply inline to slash command',
+                type: 'boolean',
+                /* Absent means on: an action downstream of a slash command should
+                   answer the command by default, so only an explicit false opts out.
+                   Renderers must compare against false rather than coerce. */
+                default: true,
+                switchLabel: 'Auto-reply to slash commands (recommended)',
+                description: 'When the run came from a Discord slash command, replace the "Bot is thinking" spinner with this message instead of posting a separate one. Falls back to a normal channel post otherwise.',
+            },
+        ],
+    },
+    editMessage: {
+        label: 'Edit message',
+        description: 'Edit content/embeds of a message the bot owns.',
+        apiMethod: 'PATCH /channels/{channel.id}/messages/{message.id}',
+        params: [channelId(), messageId(), content()],
+    },
+    deleteMessage: {
+        label: 'Delete message',
+        description: 'Delete by id. Messages from other users need Manage Messages.',
+        apiMethod: 'DELETE /channels/{channel.id}/messages/{message.id}',
+        params: [channelId(), messageId()],
+    },
+    getMessage: {
+        label: 'Get message',
+        description: 'Fetch a single message plus its reactions and attachments.',
+        apiMethod: 'GET /channels/{channel.id}/messages/{message.id}',
+        params: [channelId(), messageId()],
+    },
+    addReaction: {
+        label: 'Add reaction',
+        description: 'React as the bot. Custom emoji format: name:id.',
+        apiMethod: 'PUT /channels/{channel.id}/messages/{message.id}/reactions/{emoji}/@me',
+        params: [channelId(), messageId(), emoji()],
+    },
+    removeReaction: {
+        label: 'Remove reaction',
+        description: 'Remove the reaction the bot itself added.',
+        apiMethod: 'DELETE /channels/{channel.id}/messages/{message.id}/reactions/{emoji}/@me',
+        params: [channelId(), messageId(), emoji()],
+    },
+    pinMessage: {
+        label: 'Pin message',
+        description: 'Pin a message in its channel. Needs Manage Messages.',
+        apiMethod: 'PUT /channels/{channel.id}/pins/{message.id}',
+        params: [channelId(), messageId()],
+    },
+    // ── Channels ──────────────────────────────────────────────────────
+    createChannel: {
+        label: 'Create channel',
+        description: 'Create text/voice/forum/announcement/category in a guild.',
+        apiMethod: 'POST /guilds/{guild.id}/channels',
+        params: [
+            guildId(),
+            {
+                name: 'name',
+                label: 'Name',
+                type: 'string',
+                required: true,
+                placeholder: 'ticket-1234',
+                description: 'Name for the new channel.',
+            },
+            {
+                name: 'type',
+                label: 'Channel type',
+                type: 'select',
+                default: 'text',
+                description: 'Kind of channel to create.',
+                options: [
+                    { value: 'text', label: 'Text' },
+                    { value: 'voice', label: 'Voice' },
+                    { value: 'forum', label: 'Forum' },
+                    { value: 'announcement', label: 'Announcement' },
+                    { value: 'category', label: 'Category' },
+                ],
+            },
+            parentId('Parent category (optional)'),
+            topic('Topic (optional)'),
+            slowmode('Slowmode seconds (optional)'),
+        ],
+    },
+    editChannel: {
+        label: 'Edit channel',
+        description: 'Rename, change topic, slowmode, parent category.',
+        apiMethod: 'PATCH /channels/{channel.id}',
+        params: [
+            channelId(),
+            {
+                name: 'name',
+                label: 'New name (optional)',
+                type: 'string',
+                placeholder: 'renamed-channel',
+                description: 'Replacement channel name.',
+            },
+            topic('New topic (optional)'),
+            slowmode('New slowmode seconds (optional)'),
+            parentId('New parent category (optional)'),
+        ],
+    },
+    deleteChannel: {
+        label: 'Delete channel',
+        description: 'Permanently deletes a channel — irreversible.',
+        apiMethod: 'DELETE /channels/{channel.id}',
+        params: [channelId()],
+    },
+    getChannel: {
+        label: 'Get channel',
+        description: 'Fetch the full config and permissions of a channel.',
+        apiMethod: 'GET /channels/{channel.id}',
+        params: [channelId()],
+    },
+    listChannels: {
+        label: 'List channels',
+        description: 'Iterate every channel in a guild — output is iterable.',
+        apiMethod: 'GET /guilds/{guild.id}/channels',
+        params: [guildId()],
+    },
+    // ── Threads ───────────────────────────────────────────────────────
+    createThread: {
+        label: 'Create thread',
+        description: 'Off a message OR standalone (public/private/announcement).',
+        apiMethod: 'POST /channels/{channel.id}/threads',
+        params: [
+            channelId(),
+            {
+                name: 'name',
+                label: 'Name',
+                type: 'string',
+                required: true,
+                placeholder: 'Conversation about issue',
+                description: 'Name for the new thread.',
+            },
+            messageId({
+                label: 'Anchor message ID (optional)',
+                required: false,
+                description: 'Snowflake of a message to spawn the thread from. Leave blank for a standalone thread.',
+            }),
+            {
+                name: 'type',
+                label: 'Thread type',
+                type: 'select',
+                default: 'public',
+                description: 'Thread visibility. Ignored when an anchor message is set, since the thread then inherits from its parent.',
+                options: [
+                    { value: 'public', label: 'Public' },
+                    { value: 'private', label: 'Private' },
+                    { value: 'announcement', label: 'Announcement' },
+                ],
+            },
+            {
+                name: 'autoArchiveMinutes',
+                label: 'Auto-archive minutes',
+                type: 'select',
+                default: 1440,
+                description: 'Idle time before Discord archives the thread.',
+                options: [
+                    { value: 60, label: '1 hour' },
+                    { value: 1440, label: '24 hours (default)' },
+                    { value: 4320, label: '3 days' },
+                    { value: 10080, label: '1 week' },
+                ],
+            },
+        ],
+    },
+    // ── DMs ───────────────────────────────────────────────────────────
+    sendDM: {
+        label: 'Send DM',
+        description: 'Direct message a user by id. Silently dropped if DMs disabled.',
+        apiMethod: 'POST /users/@me/channels then POST /channels/{channel.id}/messages',
+        params: [
+            userId({
+                description: 'Snowflake of the user to DM. The bot needs a server in common with them.',
+            }),
+            content(),
+        ],
+    },
+    // ── Members & roles ───────────────────────────────────────────────
+    addRole: {
+        label: 'Add role to member',
+        description: 'The role of the bot must be ABOVE the target role in the hierarchy.',
+        apiMethod: 'PUT /guilds/{guild.id}/members/{user.id}/roles/{role.id}',
+        params: [guildId(), userId(), roleId()],
+    },
+    removeRole: {
+        label: 'Remove role from member',
+        description: 'Same hierarchy rule applies.',
+        apiMethod: 'DELETE /guilds/{guild.id}/members/{user.id}/roles/{role.id}',
+        params: [guildId(), userId(), roleId()],
+    },
+    getMember: {
+        label: 'Get member',
+        description: 'Fetch the nick, roles, joined_at and user object of a member.',
+        apiMethod: 'GET /guilds/{guild.id}/members/{user.id}',
+        params: [guildId(), userId()],
+    },
+};
+/**
+ * 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 const DISCORD_CAPACIDADES_POR_CREDENCIAL = {
+    discord_webhook: {
+        operaciones: [
+            'sendMessage',
+            'editMessage',
+            'deleteMessage',
+            'getMessage',
+        ],
+        camposNoDisponibles: [
+            'channelId',
+            'replyToMessageId',
+            'interactionReply',
+        ],
+    },
+};
+/** Las operaciones que ofrecer para una credencial de Discord. */
+export function operacionesDeDiscordPara(tipoDeCredencial) {
+    return operacionesPara(DISCORD_OPERATIONS, DISCORD_CAPACIDADES_POR_CREDENCIAL, tipoDeCredencial);
+}
+/** Si esa credencial puede ejecutar esa operación de Discord. */
+export function discordPuedeEjecutar(tipoDeCredencial, operacion) {
+    return puedeEjecutar(DISCORD_OPERATIONS, DISCORD_CAPACIDADES_POR_CREDENCIAL, tipoDeCredencial, operacion);
+}
+/** Los campos que esa credencial de Discord no deja elegir. */
+export function camposDeDiscordNoDisponibles(tipoDeCredencial) {
+    return camposNoDisponiblesPara(DISCORD_CAPACIDADES_POR_CREDENCIAL, tipoDeCredencial);
+}

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

@@ -0,0 +1,64 @@
+/**
+ * Discord AI Toolkit — las herramientas que un discordAction expone cuando
+ * `aiEnabled` está encendido.
+ *
+ * **Se escribe una sola vez.** Antes vivía dos veces: una copia en
+ * `dashboard/components/discord-actions/discord-operations-schemas.ts` y otra en
+ * `api/src/mcp-servers/toolkit-specs.ts`, las dos a mano y en repos distintos,
+ * así que ningún test podía compararlas. Es la octava y novena mudanza de esta
+ * serie; de las siete anteriores, la de Contacts salió de que una copia
+ * anunciara 15 herramientas y expusiera una.
+ *
+ * Y sí había deriva, medida al mudar: la descripción de `addReaction` decía en
+ * el dashboard «URL-encoding is handled.» y en la api «URL-encoding is handled —
+ * pass the raw form.». Gana la de la api, que es la que el servidor MCP sirve
+ * hoy a clientes externos y la que dice qué hacer. Las 17 operaciones, sus
+ * nombres de herramienta y sus parámetros coincidían exactamente.
+ *
+ * Targets Discord API v10. Los parámetros snowflake son `string` porque los ids
+ * de Discord se pasan de la precisión de Number (17-20 dígitos).
+ *
+ * La forma es la que ya consume `toolkitSpecToMcpTool` en la api, para que
+ * pueda usarse sin adaptador. Los textos van en inglés porque los lee el modelo
+ * y quien mire la lista de herramientas del servidor MCP.
+ */
+import type { DiscordOperation } from './discord-operations.js';
+export interface DiscordToolkitParameter {
+    name: string;
+    type: 'string' | 'number' | 'boolean';
+    description: string;
+    required: boolean;
+}
+export interface DiscordToolkitSpec {
+    operation: DiscordOperation;
+    /** Etiqueta corta de la fila en la lista de herramientas. */
+    label: string;
+    /** Nombre con el que el LLM llama a la herramienta. */
+    toolName: string;
+    /** Descripción (más reglas de uso) que ve el LLM. */
+    description: string;
+    parameters: DiscordToolkitParameter[];
+    /** Operaciones irreversibles o que cambian privilegios. La capa MCP las
+     *  bloquea cuando el nodo de IA lleva `requireConfirmationForDestructive`,
+     *  salvo que la llamada traiga confirmación explícita. */
+    destructive?: boolean;
+}
+export declare const DISCORD_TOOLKIT_SPECS: DiscordToolkitSpec[];
+export declare const DISCORD_TOOLKIT_BY_TOOL_NAME: Record<string, DiscordToolkitSpec>;
+/**
+ * Las herramientas que ofrecerle al modelo con ESTA credencial.
+ *
+ * Vive aquí y no en cada consumidor porque son dos —la expansión MCP de la api
+ * y el selector del AI Node del dashboard— y filtrar «casi igual» en dos sitios
+ * es exactamente la duplicación que costó tres PR quitar de este paquete.
+ *
+ * Filtra en los dos niveles, que es lo que hace falta y no es obvio:
+ *
+ *   1. **Operaciones**: sin esto, a un nodo con credencial de webhook se le
+ *      entregan al modelo 17 herramientas de las que 13 fallan siempre. El
+ *      modelo no tiene forma de saberlo: las ve anunciadas.
+ *   2. **Parámetros**: una herramienta que sigue pidiendo `channelId` invita al
+ *      modelo a inventarse un canal que el webhook va a ignorar. Peor que
+ *      fallar, porque parece que funcionó.
+ */
+export declare function herramientasDeDiscordPara(tipoDeCredencial: string | null | undefined): DiscordToolkitSpec[];