@hostwebhook/node-types 1.69.0 → 1.71.0

package/dist/esm/slack-toolkit.js

@@ -0,0 +1,235 @@
+/**
+ * Slack AI Toolkit — las herramientas que un slackAction expone cuando
+ * `aiEnabled` está encendido.
+ *
+ * **Se escribe una sola vez.** Antes vivía dos veces: una copia en
+ * `dashboard/components/slack-actions/slack-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.
+ *
+ * La deriva aquí era gorda: **14 de las 16 descripciones** diferían. Gana la de
+ * la api en todas —es sistemáticamente la más completa y es la que sirve el MCP
+ * hoy—, y una no era cosmética: en `deleteMessage` la api nombra el permiso que
+ * hace falta (`chat:write.public` + admin) y el dashboard sólo decía «admin
+ * perms». Operaciones, nombres de herramienta y parámetros sí coincidían.
+ *
+ * Los nombres llevan `_slack_` para no chocar con los de Telegram y Discord
+ * cuando un mismo AI Node tiene varios toolkits encendidos.
+ *
+ * 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 { camposDeSlackNoDisponibles, operacionesDeSlackPara, } from './slack-operations.js';
+const p = (name, description, required = true, type = 'string') => ({ name, type, description, required });
+export const SLACK_TOOLKIT_SPECS = [
+    // ── Messages ─────────────────────────────────────────────────────
+    {
+        operation: 'sendMessage',
+        label: 'Send message',
+        toolName: 'send_slack_message',
+        description: 'Post a message to a Slack channel, group, or DM. ' +
+            'USAGE RULES: ' +
+            '(1) `channel` is a Slack channel id (C…), group id (G…), or DM id (D…). Get it from the trigger payload, listChannels, or the user. Never invent one. ' +
+            '(2) For a thread reply, set `threadTs` to the parent message timestamp. ' +
+            '(3) Either `text` or `blocks` is required. Use blocks for rich layouts.',
+        parameters: [
+            p('channel', 'Channel/group/DM id where the message will be posted.'),
+            p('text', 'Message text. Slack mrkdwn supported. Required when blocks is empty.', false),
+            p('blocks', 'Block Kit JSON for rich layouts. Stringified JSON or JSON array.', false),
+            p('threadTs', 'Parent message timestamp to reply inside an existing thread.', false),
+        ],
+    },
+    {
+        operation: 'updateMessage',
+        label: 'Update message',
+        toolName: 'update_slack_message',
+        description: 'Edit a message previously posted by the bot. The bot can only edit its own messages — editing another user/bot message returns cant_update_message.',
+        parameters: [
+            p('channel', 'Channel where the original message lives.'),
+            p('ts', 'Timestamp of the message to edit (returned by sendMessage).'),
+            p('text', 'New message text. Required when blocks is empty.', false),
+            p('blocks', 'New Block Kit JSON. Replaces the existing layout.', false),
+        ],
+    },
+    {
+        operation: 'deleteMessage',
+        label: 'Delete message',
+        toolName: 'delete_slack_message',
+        description: "Delete a message the bot posted. Other users' messages need chat:write.public + admin perms — usually fails for AI-driven calls. Confirm before destructive use.",
+        parameters: [
+            p('channel', 'Channel where the message lives.'),
+            p('ts', 'Timestamp of the message to delete.'),
+        ],
+        destructive: true,
+    },
+    {
+        operation: 'sendEphemeral',
+        label: 'Send ephemeral',
+        toolName: 'send_slack_ephemeral',
+        description: 'Post a message visible only to a specific user — the rest of the channel does not see it. Useful for per-user prompts, errors, or warnings.',
+        parameters: [
+            p('channel', 'Channel where the ephemeral message will appear.'),
+            p('user', 'User id (U…) — the only viewer of the message.'),
+            p('text', 'Message text. Required when blocks is empty.', false),
+            p('blocks', 'Block Kit JSON for rich layouts.', false),
+        ],
+    },
+    {
+        operation: 'scheduleMessage',
+        label: 'Schedule message',
+        toolName: 'schedule_slack_message',
+        description: 'Schedule a Slack message to be posted at a future time. Returns a scheduled_message_id useful for cancellation later.',
+        parameters: [
+            p('channel', 'Channel where the message will be posted.'),
+            p('postAt', 'When to post — unix timestamp in SECONDS, not milliseconds.', true, 'number'),
+            p('text', 'Message text. Required when blocks is empty.', false),
+            p('blocks', 'Block Kit JSON for rich layouts.', false),
+        ],
+    },
+    {
+        operation: 'getMessage',
+        label: 'Get message',
+        toolName: 'get_slack_message',
+        description: 'Fetch a single message by its timestamp. Returns the message text + author + reactions + attachments. Use BEFORE editing or reacting to verify state.',
+        parameters: [
+            p('channel', 'Channel where the message lives.'),
+            p('ts', 'Timestamp of the message to fetch.'),
+        ],
+    },
+    // ── Channels ─────────────────────────────────────────────────────
+    {
+        operation: 'listChannels',
+        label: 'List channels',
+        toolName: 'list_slack_channels',
+        description: 'List public + private channels the bot can see in the workspace. Returns id, name, isMember, memberCount per channel. Pre-pick a channel before sendMessage.',
+        parameters: [
+            p('limit', 'Max channels to return (1-1000). Default 200.', false, 'number'),
+            p('excludeArchived', 'Hide archived channels. Default true.', false, 'boolean'),
+        ],
+    },
+    {
+        operation: 'getChannelHistory',
+        label: 'Get channel history',
+        toolName: 'get_slack_channel_history',
+        description: 'Read recent messages from a Slack channel. Useful for summarization, context retrieval, or finding a message by content before editing/reacting.',
+        parameters: [
+            p('channel', 'Channel id to read from.'),
+            p('limit', 'Max messages to return (1-200). Default 50.', false, 'number'),
+            p('oldest', 'Only messages newer than this timestamp.', false),
+            p('latest', 'Only messages older than this timestamp.', false),
+        ],
+    },
+    {
+        operation: 'getThreadReplies',
+        label: 'Get thread replies',
+        toolName: 'get_slack_thread_replies',
+        description: 'Fetch the replies inside a Slack thread, given the parent message timestamp. Use for summarizing or continuing a thread.',
+        parameters: [
+            p('channel', 'Channel where the thread lives.'),
+            p('ts', 'Timestamp of the thread parent message.'),
+            p('limit', 'Max replies to return (1-1000). Default 100.', false, 'number'),
+        ],
+    },
+    {
+        operation: 'createChannel',
+        label: 'Create channel',
+        toolName: 'create_slack_channel',
+        description: 'Create a new public or private Slack channel. Names must be lowercase, no spaces, max 80 chars. Confirm with the user before creating channels — they are usually long-lived org artifacts.',
+        parameters: [
+            p('name', 'Channel name — lowercase, no spaces, max 80 chars.'),
+            p('isPrivate', 'Create a private channel instead of public. Default false.', false, 'boolean'),
+        ],
+        destructive: true,
+    },
+    {
+        operation: 'inviteToChannel',
+        label: 'Invite to channel',
+        toolName: 'invite_to_slack_channel',
+        description: 'Invite one or more users to a Slack channel by user id. Comma-separated `users` argument.',
+        parameters: [
+            p('channel', 'Channel id to invite users to.'),
+            p('users', 'Comma-separated user ids (U…) to invite.'),
+        ],
+    },
+    // ── Reactions ────────────────────────────────────────────────────
+    {
+        operation: 'addReaction',
+        label: 'Add reaction',
+        toolName: 'add_slack_reaction',
+        description: 'Add an emoji reaction to a Slack message as the bot. Use the emoji NAME without colons (e.g. `thumbsup`, `white_check_mark`, `eyes`).',
+        parameters: [
+            p('channel', 'Channel where the message lives.'),
+            p('ts', 'Timestamp of the message to react to.'),
+            p('name', 'Emoji name without colons.'),
+        ],
+    },
+    {
+        operation: 'removeReaction',
+        label: 'Remove reaction',
+        toolName: 'remove_slack_reaction',
+        description: "Remove the bot's own emoji reaction from a Slack message. Cannot remove other users' reactions.",
+        parameters: [
+            p('channel', 'Channel where the message lives.'),
+            p('ts', 'Timestamp of the message.'),
+            p('name', 'Emoji name without colons.'),
+        ],
+    },
+    // ── Users ────────────────────────────────────────────────────────
+    {
+        operation: 'listUsers',
+        label: 'List users',
+        toolName: 'list_slack_users',
+        description: 'List human members of the Slack workspace. Returns id, name, real_name, email, avatarUrl. Excludes deleted users + bots by default.',
+        parameters: [
+            p('limit', 'Max users to return (1-1000). Default 200.', false, 'number'),
+            p('includeDeleted', 'Include deactivated users. Default false.', false, 'boolean'),
+            p('includeBots', 'Include bot users + app users. Default false.', false, 'boolean'),
+        ],
+    },
+    {
+        operation: 'getUserInfo',
+        label: 'Get user info',
+        toolName: 'get_slack_user_info',
+        description: 'Fetch a Slack user profile (real_name, email, timezone, status, avatar). Use BEFORE sendEphemeral to confirm the user id is valid.',
+        parameters: [p('user', 'User id (U…) to look up.')],
+    },
+    // ── Files ────────────────────────────────────────────────────────
+    {
+        operation: 'uploadFile',
+        label: 'Upload file',
+        toolName: 'upload_slack_file',
+        description: 'Upload a file to Slack and optionally share it in a channel. Provide either a public `url` to fetch or inline `contentBase64` for small payloads. Optionally attach to a thread via `threadTs`.',
+        parameters: [
+            p('url', 'Public URL or HW _file.downloadUrl that HW will fetch and re-upload.', false),
+            p('contentBase64', 'Inline base64 file content (alternative to url).', false),
+            p('filename', 'Display name in Slack. Auto-derived from URL when omitted.', false),
+            p('channel', 'Channel id to share the uploaded file in.', false),
+            p('title', 'Title shown above the file.', false),
+            p('initialComment', 'Message Slack posts together with the file.', false),
+            p('threadTs', 'Thread to attach the file to.', false),
+        ],
+    },
+];
+export const SLACK_TOOLKIT_BY_TOOL_NAME = Object.fromEntries(SLACK_TOOLKIT_SPECS.map((s) => [s.toolName, s]));
+/**
+ * Las herramientas que ofrecerle al modelo con ESTA credencial.
+ *
+ * Gemelo de `herramientasDeDiscordPara`, y por la misma razón: los dos
+ * consumidores —la expansión MCP de la api y el selector del AI Node del
+ * dashboard— filtrarían por su cuenta y acabarían discrepando.
+ *
+ * En Slack el recorte es brutal y conviene verlo escrito: con un webhook el
+ * modelo pasa de **16 herramientas a una**, y esa una pierde el `channel`,
+ * porque el destino lo fijó quien instaló la credencial. Dejarle el campo sería
+ * invitarle a elegir un canal que Slack va a ignorar sin decir nada.
+ */
+export function herramientasDeSlackPara(tipoDeCredencial) {
+    const permitidas = new Set(operacionesDeSlackPara(tipoDeCredencial));
+    const fuera = camposDeSlackNoDisponibles(tipoDeCredencial);
+    return SLACK_TOOLKIT_SPECS.filter((s) => permitidas.has(s.operation)).map((s) => fuera.size === 0
+        ? s
+        : { ...s, parameters: s.parameters.filter((p) => !fuera.has(p.name)) });
+}

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

@@ -0,0 +1,104 @@
+/**
+ * Telegram Bot API operation enum — single source of truth across the API,
+ * Dashboard, and any future consumers (Message Broker, MCP server). Used by:
+ *   - telegramAction entity / DTO (api): operation field + validation
+ *   - dashboard TelegramAction operation picker
+ *   - MCP toolkit-specs expansion (one aiEnabled telegramAction → N tools)
+ *
+ * Phase 1 covers the eight ops that handle ~95% of bot send use cases.
+ * Phase 2 candidates (sendMediaGroup, voice/video uploads, chat admin,
+ * setMyCommands, message reactions, inline-mode answers) get added by
+ * extending this list, bumping the package, and re-installing in
+ * consumers — same pattern as Gmail / Calendar / Drive.
+ */
+export declare const TELEGRAM_OPERATIONS: readonly ["sendMessage", "replyToMessage", "sendPhoto", "sendDocument", "sendVoice", "sendAndWaitForResponse", "editMessageText", "deleteMessage", "answerCallbackQuery", "forwardMessage", "sendPoll"];
+export type TelegramOperation = (typeof TELEGRAM_OPERATIONS)[number];
+/** Type guard — useful when validating untrusted input (DTOs, tool calls). */
+export declare function isTelegramOperation(value: unknown): value is TelegramOperation;
+/**
+ * Per-operation form schema, same idea as SLACK_OPERATION_SPECS and
+ * DISCORD_OPERATION_SPECS: the detail page renders it with one loop instead of
+ * a branch per operation. It replaces 12 branches and a local `OPERATIONS`
+ * array of 11 entries whose count had already drifted from the truth — the
+ * mode chip read "Choose 1 of 10 ops" while the page painted 11 cards.
+ *
+ * Two things about this node's schema are worth knowing before writing a
+ * renderer for it:
+ *
+ * 1. **`chatId` is per-operation, not global.** The page used to hoist one
+ *    shared field to the top of every form, but `answerCallbackQuery` has no
+ *    chat at all (it answers a callback id) and `forwardMessage` needs two
+ *    chats with their own labels — "Destination" and "Source". So it is
+ *    declared op by op, and where it repeats it repeats on purpose.
+ * 2. **Three booleans default to ON.** See the note on `default` below; a
+ *    renderer that coerces with `!!config[name]` silently turns them off.
+ */
+export interface TelegramParamSpec {
+    /** Field key — the property name inside `operationConfig`. */
+    name: string;
+    /** UI label shown above the control. */
+    label: string;
+    /**
+     * Param type for form rendering.
+     *
+     * - `string` — one-line input with `{{payload.x}}` templating.
+     * - `text` — the same input, multiline; `rows` sets its height.
+     * - `select` — fixed option list (only `parseMode` today).
+     * - `boolean` — a Switch. Read it as `config[name] ?? default`, never as
+     *   `!!config[name]`: see `default`.
+     * - `number` — numeric input clamped to `min`/`max` as it is typed.
+     * - `linesList` — **stored as an array of strings, edited as one per
+     *   line.** Telegram's poll options. The cousin of Contacts' `csvList`,
+     *   split on newlines instead of commas. A renderer that treats it as text
+     *   turns the array into a string on the first save and `sendPoll` starts
+     *   failing.
+     */
+    type: 'string' | 'text' | 'select' | 'boolean' | 'number' | 'linesList';
+    /** Required by the operation. Metadata — the form does not gate on it. */
+    required?: boolean;
+    /** Help text under the control. Absent where the form shows none. */
+    description?: string;
+    /** Hint shown inside the input. May contain newlines for `linesList`. */
+    placeholder?: string;
+    /**
+     * Value to show when the stored one is `undefined`.
+     *
+     * `includeDisapprove`, `isAnonymous` and `parseMode` all have one, and the
+     * first two default to **true**: the stored config only ever holds `false`
+     * when the user turned them off. `config[name] ?? default` reproduces that
+     * exactly; `!!config[name]` does not, and getting it wrong strips the
+     * Disapprove button off every approval flow that already exists.
+     */
+    default?: string | number | boolean;
+    /** `select` only — the fixed option list, in display order. */
+    options?: string[];
+    /** `number` only — the input clamps to these while typing. */
+    min?: number;
+    max?: number;
+    /** `text` only — height of the textarea. */
+    rows?: number;
+    /**
+     * Renders side by side with the next field in a two-column row. Only the
+     * Approve / Disapprove button labels use it — they are one decision split
+     * in two, and stacking them reads as two unrelated fields.
+     */
+    pairedWithNext?: boolean;
+}
+export interface TelegramOperationSpec {
+    /** UI label for the operation picker card. */
+    label: string;
+    /** Sub-line under the label in the picker. */
+    description: string;
+    /** Bot API method the operation maps to (core.telegram.org/bots/api). */
+    apiMethod: string;
+    /**
+     * The op accepts `reply_markup`, so the page offers the inline-keyboard
+     * builder for it. Used to live as a hardcoded array of five strings in the
+     * detail page. `sendAndWaitForResponse` is deliberately absent: it builds
+     * its own Approve / Disapprove keyboard and a second one would collide.
+     */
+    supportsInlineKeyboard?: boolean;
+    /** Parameter schema. Order matters for form rendering. */
+    params: TelegramParamSpec[];
+}
+export declare const TELEGRAM_OPERATION_SPECS: Record<TelegramOperation, TelegramOperationSpec>;