@divyacon/piece-telegram-bot 0.0.0-stage → 0.1.0

package/src/lib/action/telegram-send-photo-or-video.ts

@@ -0,0 +1,238 @@
+import {
+  ApFile,
+  createAction,
+  DynamicPropsValue,
+  Property,
+} from '@agnocon/pieces-framework';
+import {
+  HttpMessageBody,
+  HttpMethod,
+  QueryParams,
+  httpClient,
+} from '@agnocon/pieces-common';
+import { telegramCommons } from '../common';
+import { telegramBotAuth } from '../..';
+import FormData from 'form-data';
+import { telegramSendPhotoOrVideoActionOutputSchema } from '../output-schemas';
+
+export const telegramSendPhotoOrVideo = createAction({
+  auth: telegramBotAuth,
+  name: 'telegram_send_photo_or_video',
+  displayName: 'Send Photo, Video, Sticker or GIF',
+  description:
+    'Send a single photo, video, sticker, or animated GIF to a Telegram chat.',
+  audience: 'ai',
+  aiMetadata: {
+    description:
+      'Sends a single photo, video, sticker, or animated GIF to a chat (chat_id is a numeric id or @channelusername the bot can reach), supplied as an uploaded file OR a previously uploaded Telegram file_id, with an optional caption. Pick the media_type, then provide either the file or its file_id for that type. Use for one inline media item; for several in one album use telegram_send_media_group, for an arbitrary attachment use telegram_send_document. Caption format defaults to plain text. Not idempotent: each call posts a new message.',
+    idempotent: false,
+  },
+  outputSchema: telegramSendPhotoOrVideoActionOutputSchema,
+  props: {
+    chat_id: telegramCommons.chatIdProp(),
+    media_type: Property.StaticDropdown({
+      displayName: 'Media Type',
+      required: true,
+      options: {
+        disabled: false,
+        placeholder: 'Select media type',
+        options: [
+          { label: 'Image', value: 'photo' },
+          { label: 'Video', value: 'video' },
+          { label: 'Sticker', value: 'sticker' },
+          { label: 'GIF', value: 'animation' },
+        ],
+      },
+    }),
+    media: Property.DynamicProperties({
+      auth: telegramBotAuth,
+      displayName: 'Media Properties',
+      required: false,
+      refreshers: ['media_type'],
+      async props({ media_type }) {
+        const propsBuilders: Record<string, () => DynamicPropsValue> = {
+          photo: () => ({
+            photo: Property.File({
+              displayName: 'Image',
+              description: 'The image to be uploaded as a file',
+              required: false,
+            }),
+            photoId: Property.ShortText({
+              displayName: 'Image Id',
+              description:
+                "The image file_id previously uploaded to Telegram's servers",
+              required: false,
+            }),
+          }),
+          video: () => ({
+            video: Property.File({
+              displayName: 'Video',
+              description: 'The video to be uploaded as a file',
+              required: false,
+            }),
+            videoId: Property.ShortText({
+              displayName: 'Video Id',
+              description:
+                "The video file_id previously uploaded to Telegram's servers",
+              required: false,
+            }),
+          }),
+          sticker: () => ({
+            sticker: Property.File({
+              displayName: 'Sticker',
+              description:
+                'The sticker to be uploaded as a file (supports .WEBP files for static and .TGS for animated)',
+              required: false,
+            }),
+            emoji: Property.ShortText({
+              displayName: 'Emoji',
+              description:
+                'Emoji associated with the sticker. Only for just uploaded stickers',
+              required: false,
+            }),
+            stickerId: Property.ShortText({
+              displayName: 'Sticker Id',
+              description:
+                "The sticker file_id previously uploaded to Telegram's servers",
+              required: false,
+            }),
+          }),
+          animation: () => ({
+            animation: Property.File({
+              displayName: 'GIF',
+              description:
+                'The GIF or MPEG-4 without sound file to be uploaded as a auto-playing animation',
+              required: false,
+            }),
+            animationId: Property.ShortText({
+              displayName: 'GIF Id',
+              description:
+                "The GIF or MPEG-4 without sound file_id previously uploaded to Telegram's servers",
+              required: false,
+            }),
+            duration: Property.Number({
+              displayName: 'Duration',
+              description: 'Duration of sent video in seconds',
+              required: false,
+            }),
+          }),
+        };
+        const builder = propsBuilders[media_type as unknown as string];
+        if (!builder) {
+          return {};
+        }
+        return builder();
+      },
+    }),
+    format: Property.StaticDropdown({
+      displayName: 'Caption Format',
+      description:
+        'How the caption should be parsed by Telegram. Defaults to plain text; only set MarkdownV2 or HTML when the caption is correctly escaped/tagged.',
+      required: false,
+      options: {
+        options: [
+          { label: 'Plain Text', value: 'None' },
+          { label: 'Markdown (V2)', value: 'MarkdownV2' },
+          { label: 'HTML', value: 'HTML' },
+        ],
+      },
+      defaultValue: 'None',
+    }),
+    message: Property.LongText({
+      displayName: 'Caption',
+      description: 'The caption to send with the media',
+      required: false,
+    }),
+    message_thread_id: Property.ShortText({
+      displayName: 'Message Thread Id',
+      description:
+        'Unique identifier for the target message thread of the forum; supergroup forums only.',
+      required: false,
+    }),
+    disable_notification: telegramCommons.disableNotificationProp(),
+    protect_content: telegramCommons.protectContentProp(),
+    reply_markup: Property.Json({
+      displayName: 'Reply Markup',
+      description:
+        'Advanced/optional. A raw JSON-serialized inline keyboard, e.g. {"inline_keyboard":[[{"text":"Open","url":"https://example.com"}]]}. Malformed markup is rejected by Telegram.',
+      required: false,
+    }),
+  },
+  async run(ctx) {
+    const mediaType = ctx.propsValue['media_type'];
+    if (!mediaType) {
+      throw new Error('media_type is required');
+    }
+
+    const methods: Partial<Record<string, string>> = {
+      photo: 'sendPhoto',
+      video: 'sendVideo',
+      sticker: 'sendSticker',
+      animation: 'sendAnimation',
+    };
+
+    const method = methods[mediaType];
+    if (!method) {
+      throw new Error('Unknown media type method (' + mediaType + ')');
+    }
+
+    const headers: Record<string, string> = {};
+    const queryParams: QueryParams = {};
+    let body: HttpMessageBody | undefined = undefined;
+
+    const file = ctx.propsValue.media?.[mediaType] as ApFile | undefined;
+    const id = ctx.propsValue.media?.[mediaType + 'Id'] as string | undefined;
+    const parseMode = telegramCommons.resolveParseMode(ctx.propsValue['format']);
+
+    if (file && file.data && file.filename) {
+      const form = new FormData();
+      form.append(mediaType, file.data, file.filename);
+      form.append('chat_id', ctx.propsValue['chat_id']);
+      if (ctx.propsValue['message']) {
+        form.append('caption', ctx.propsValue['message']);
+      }
+      if (ctx.propsValue['message_thread_id']) {
+        form.append('message_thread_id', ctx.propsValue['message_thread_id']);
+      }
+      if (parseMode) {
+        form.append('parse_mode', parseMode);
+      }
+      if (ctx.propsValue['disable_notification']) {
+        form.append('disable_notification', 'true');
+      }
+      if (ctx.propsValue['protect_content']) {
+        form.append('protect_content', 'true');
+      }
+      if (ctx.propsValue['reply_markup']) {
+        form.append(
+          'reply_markup',
+          JSON.stringify(ctx.propsValue['reply_markup'])
+        );
+      }
+
+      body = form;
+      Object.assign(headers, form.getHeaders());
+    } else if (typeof id !== 'undefined' && id !== '') {
+      body = {
+        [mediaType]: id,
+        chat_id: ctx.propsValue['chat_id'],
+        caption: ctx.propsValue['message'] ?? undefined,
+        message_thread_id: ctx.propsValue['message_thread_id'] ?? undefined,
+        parse_mode: parseMode,
+        disable_notification: ctx.propsValue['disable_notification'] ?? false,
+        protect_content: ctx.propsValue['protect_content'] ?? false,
+        reply_markup: ctx.propsValue['reply_markup'] ?? undefined,
+      };
+    } else {
+      throw new Error('No media defined. Provide either a file or an id.');
+    }
+
+    return await httpClient.sendRequest<never>({
+      method: HttpMethod.POST,
+      url: telegramCommons.getApiUrl(ctx.auth, method),
+      headers,
+      body,
+      queryParams,
+    });
+  },
+});

package/src/lib/action/telegram-send-poll.ts

@@ -0,0 +1,170 @@
+import { createAction, Property } from '@agnocon/pieces-framework';
+import { HttpMethod, httpClient } from '@agnocon/pieces-common';
+import { telegramCommons } from '../common';
+import { telegramBotAuth } from '../..';
+import { telegramSendPollActionOutputSchema } from '../output-schemas';
+
+export const telegramSendPoll = createAction({
+  auth: telegramBotAuth,
+  name: 'telegram_send_poll',
+  displayName: 'Send Poll',
+  description: 'Send a native Telegram poll (regular or quiz) to a chat.',
+  audience: 'ai',
+  aiMetadata: {
+    description:
+      'Posts a native poll (regular or quiz) to a chat addressed by chat_id (a numeric id or @channelusername the bot can reach) with 2–10 answer options. Use to collect votes or run a quiz; quiz polls require correct_option_id (a 0-based index) and cannot allow multiple answers, and open_period and close_date are mutually exclusive. Not idempotent: each call creates a new poll.',
+    idempotent: false,
+  },
+  outputSchema: telegramSendPollActionOutputSchema,
+  props: {
+    chat_id: telegramCommons.chatIdProp(),
+    question: Property.ShortText({
+      displayName: 'Question',
+      description: 'Poll question, 1–300 characters.',
+      required: true,
+    }),
+    options: Property.Array({
+      displayName: 'Options',
+      description: 'List of answer options (2–10 options, each 1–100 characters).',
+      required: true,
+    }),
+    is_anonymous: Property.Checkbox({
+      displayName: 'Anonymous',
+      description: 'True, if the poll needs to be anonymous. Default true.',
+      required: false,
+      defaultValue: true,
+    }),
+    type: Property.StaticDropdown({
+      displayName: 'Poll Type',
+      description: 'Poll type. Defaults to "regular".',
+      required: false,
+      options: {
+        options: [
+          { label: 'Regular', value: 'regular' },
+          { label: 'Quiz', value: 'quiz' },
+        ],
+      },
+      defaultValue: 'regular',
+    }),
+    allows_multiple_answers: Property.Checkbox({
+      displayName: 'Allow Multiple Answers',
+      description: 'True if the poll allows multiple answers (regular polls only).',
+      required: false,
+      defaultValue: false,
+    }),
+    correct_option_id: Property.Number({
+      displayName: 'Correct Option Id (Quiz)',
+      description: '0-based index of the correct answer option (required for quizzes).',
+      required: false,
+    }),
+    explanation: Property.LongText({
+      displayName: 'Explanation (Quiz)',
+      description: 'Explanation shown when a user picks an incorrect answer (0–200 chars).',
+      required: false,
+    }),
+    explanation_parse_mode: Property.StaticDropdown({
+      displayName: 'Explanation Format',
+      description:
+        'How the quiz explanation should be parsed by Telegram. Defaults to plain text; only set MarkdownV2 or HTML when the explanation is correctly escaped/tagged.',
+      required: false,
+      options: {
+        options: [
+          { label: 'Plain Text', value: 'None' },
+          { label: 'Markdown (V2)', value: 'MarkdownV2' },
+          { label: 'HTML', value: 'HTML' },
+        ],
+      },
+      defaultValue: 'None',
+    }),
+    open_period: Property.Number({
+      displayName: 'Open Period (seconds)',
+      description: 'Amount of time in seconds the poll will be active (5–600).',
+      required: false,
+    }),
+    close_date: Property.DateTime({
+      displayName: 'Close Date',
+      description: 'Point in time when the poll will be automatically closed.',
+      required: false,
+    }),
+    is_closed: Property.Checkbox({
+      displayName: 'Closed',
+      description: 'Pass True if the poll should be immediately closed. Useful for previews.',
+      required: false,
+      defaultValue: false,
+    }),
+    message_thread_id: Property.ShortText({
+      displayName: 'Message Thread Id',
+      description:
+        'Unique identifier for the target message thread of the forum; supergroup forums only.',
+      required: false,
+    }),
+    disable_notification: telegramCommons.disableNotificationProp(),
+    protect_content: telegramCommons.protectContentProp(),
+    reply_to_message_id: telegramCommons.replyToMessageIdProp(),
+    reply_markup: Property.Json({
+      displayName: 'Reply Markup',
+      description:
+        'Advanced/optional. A raw JSON-serialized inline keyboard, e.g. {"inline_keyboard":[[{"text":"Open","url":"https://example.com"}]]}. Malformed markup is rejected by Telegram.',
+      required: false,
+    }),
+  },
+  async run(ctx) {
+    const options = (ctx.propsValue.options ?? []).map((option) => String(option));
+    if (options.length < 2 || options.length > 10) {
+      throw new Error('A poll requires between 2 and 10 options.');
+    }
+    const pollType = ctx.propsValue.type ?? 'regular';
+    const correctOptionId = ctx.propsValue.correct_option_id;
+    if (pollType === 'quiz') {
+      if (correctOptionId === undefined || correctOptionId === null) {
+        throw new Error('Quiz polls require "Correct Option Id".');
+      }
+      if (correctOptionId < 0 || correctOptionId >= options.length) {
+        throw new Error(
+          `"Correct Option Id" must be between 0 and ${options.length - 1} (the index of an option).`
+        );
+      }
+      if (ctx.propsValue.allows_multiple_answers) {
+        throw new Error('Quiz polls cannot allow multiple answers.');
+      }
+    } else if (correctOptionId !== undefined && correctOptionId !== null) {
+      throw new Error(
+        '"Correct Option Id" is only valid for quiz polls. Set "Poll Type" to Quiz or clear this field.'
+      );
+    }
+    if (ctx.propsValue.open_period && ctx.propsValue.close_date) {
+      throw new Error(
+        '"Open Period" and "Close Date" are mutually exclusive — set at most one.'
+      );
+    }
+    const explanationParseMode = telegramCommons.resolveParseMode(
+      ctx.propsValue.explanation_parse_mode
+    );
+
+    return await httpClient.sendRequest<never>({
+      method: HttpMethod.POST,
+      url: telegramCommons.getApiUrl(ctx.auth, 'sendPoll'),
+      body: {
+        chat_id: ctx.propsValue.chat_id,
+        question: ctx.propsValue.question,
+        options,
+        message_thread_id: ctx.propsValue.message_thread_id ?? undefined,
+        is_anonymous: ctx.propsValue.is_anonymous ?? true,
+        type: ctx.propsValue.type ?? 'regular',
+        allows_multiple_answers: ctx.propsValue.allows_multiple_answers ?? false,
+        correct_option_id: ctx.propsValue.correct_option_id ?? undefined,
+        explanation: ctx.propsValue.explanation ?? undefined,
+        explanation_parse_mode: explanationParseMode,
+        open_period: ctx.propsValue.open_period ?? undefined,
+        close_date: ctx.propsValue.close_date
+          ? Math.floor(new Date(ctx.propsValue.close_date).getTime() / 1000)
+          : undefined,
+        is_closed: ctx.propsValue.is_closed ?? false,
+        disable_notification: ctx.propsValue.disable_notification ?? false,
+        protect_content: ctx.propsValue.protect_content ?? false,
+        reply_to_message_id: ctx.propsValue.reply_to_message_id ?? undefined,
+        reply_markup: ctx.propsValue.reply_markup ?? undefined,
+      },
+    });
+  },
+});

package/src/lib/action/telegram-unpin-message.ts

@@ -0,0 +1,38 @@
+import { createAction, Property } from '@agnocon/pieces-framework';
+import { HttpMethod, httpClient } from '@agnocon/pieces-common';
+import { telegramCommons } from '../common';
+import { telegramBotAuth } from '../..';
+import { telegramUnpinMessageActionOutputSchema } from '../output-schemas';
+
+export const telegramUnpinMessage = createAction({
+  auth: telegramBotAuth,
+  name: 'telegram_unpin_message',
+  displayName: 'Unpin Message',
+  description: 'Unpin a message in a Telegram chat.',
+  audience: 'ai',
+  aiMetadata: {
+    description:
+      'Unpins a message in a chat addressed by chat_id (a numeric id or @channelusername the bot can reach) — supply message_id to unpin a specific message, or omit it to unpin the most recent pinned message; the bot must be an administrator with pin rights. Use to clear a pin set by telegram_pin_message. Idempotent: an already-unpinned message stays unpinned.',
+    idempotent: true,
+  },
+  outputSchema: telegramUnpinMessageActionOutputSchema,
+  props: {
+    chat_id: telegramCommons.chatIdProp(),
+    message_id: Property.ShortText({
+      displayName: 'Message Id',
+      description:
+        'Identifier of the pinned message to unpin. Leave empty to unpin the most recent pinned message.',
+      required: false,
+    }),
+  },
+  async run(ctx) {
+    return await httpClient.sendRequest<never>({
+      method: HttpMethod.POST,
+      url: telegramCommons.getApiUrl(ctx.auth, 'unpinChatMessage'),
+      body: {
+        chat_id: ctx.propsValue.chat_id,
+        message_id: ctx.propsValue.message_id ?? undefined,
+      },
+    });
+  },
+});

package/src/lib/action/unpin-message.action.ts

@@ -0,0 +1,36 @@
+import { createAction, Property } from '@agnocon/pieces-framework';
+import { HttpMethod, httpClient } from '@agnocon/pieces-common';
+import { telegramCommons } from '../common';
+import { telegramBotAuth } from '../..';
+import { unpinMessageActionOutputSchema } from '../output-schemas';
+
+export const telegramUnpinMessageAction = createAction({
+  auth: telegramBotAuth,
+  name: 'unpin_message',
+  displayName: 'Unpin Message',
+  description:
+    'Unpin a message in a chat. Leave Message Id empty to unpin the most recent pinned message.',
+  audience: 'human',
+  aiMetadata: { description: 'Unpins a message in a chat; supply message_id to unpin a specific message, or leave it empty to unpin the most recent pinned message. The bot must be an administrator with pin rights. Idempotent: a message that is already unpinned stays unpinned.', idempotent: true },
+  props: {
+    instructions: telegramCommons.chatIdInstructions(),
+    chat_id: telegramCommons.chatIdProp(),
+    message_id: Property.Number({
+      displayName: 'Message Id',
+      description:
+        'Identifier of the pinned message to unpin. Leave empty to unpin the most recent pinned message.',
+      required: false,
+    }),
+  },
+  outputSchema: unpinMessageActionOutputSchema,
+  async run(ctx) {
+    return await httpClient.sendRequest<never>({
+      method: HttpMethod.POST,
+      url: telegramCommons.getApiUrl(ctx.auth, 'unpinChatMessage'),
+      body: {
+        chat_id: ctx.propsValue.chat_id,
+        message_id: ctx.propsValue.message_id ?? undefined,
+      },
+    });
+  },
+});

package/src/lib/common/index.ts

@@ -0,0 +1,147 @@
+import {
+  HttpMethod,
+  HttpRequest,
+  httpClient,
+} from '@agnocon/pieces-common';
+import { telegramBotAuth } from '../..';
+import {
+  AppConnectionValueForAuthProperty,
+  Property,
+} from '@agnocon/pieces-framework';
+
+const chatIdInstructions = `
+**How to obtain Chat ID:**
+1. Search for the bot "@getmyid_bot" in Telegram.
+2. Start a conversation with the bot.
+3. Send the command "/my_id" to the bot.
+4. The bot will reply with your chat ID.
+
+**Note: Remember to initiate the chat with the bot, or you'll get an error for "chat not found."**
+`;
+
+const formatLinkMarkdown = `
+[Formatting options](https://core.telegram.org/bots/api#formatting-options)
+`;
+
+const buildChatIdInstructions = () =>
+  Property.MarkDown({ value: chatIdInstructions });
+
+const buildFormatLinkInstructions = () =>
+  Property.MarkDown({ value: formatLinkMarkdown });
+
+const buildChatIdProp = () =>
+  Property.ShortText({
+    displayName: 'Chat Id',
+    description:
+      'Unique identifier for the target chat or username of the target channel (e.g. @channelusername).',
+    required: true,
+  });
+
+const buildMessageThreadIdProp = () =>
+  Property.ShortText({
+    displayName: 'Message Thread Id',
+    description:
+      'Unique identifier for the target message thread of the forum; supergroup forums only.',
+    required: false,
+  });
+
+const buildParseModeProp = () =>
+  Property.StaticDropdown({
+    displayName: 'Format',
+    description: 'How the message text should be parsed by Telegram.',
+    required: false,
+    options: {
+      options: [
+        { label: 'Markdown (V2)', value: 'MarkdownV2' },
+        { label: 'HTML', value: 'HTML' },
+        { label: 'Plain Text', value: 'None' },
+      ],
+    },
+    defaultValue: 'MarkdownV2',
+  });
+
+const buildReplyMarkupProp = () =>
+  Property.Json({
+    required: false,
+    displayName: 'Reply Markup',
+    description:
+      'Additional interface options. A JSON-serialized object for an inline keyboard, custom reply keyboard, instructions to remove reply keyboard or to force a reply from the user.',
+  });
+
+const buildDisableNotificationProp = () =>
+  Property.Checkbox({
+    displayName: 'Disable Notification',
+    description: 'Send the message silently. Users will receive a notification with no sound.',
+    required: false,
+    defaultValue: false,
+  });
+
+const buildProtectContentProp = () =>
+  Property.Checkbox({
+    displayName: 'Protect Content',
+    description: 'Protects the contents of the sent message from forwarding and saving.',
+    required: false,
+    defaultValue: false,
+  });
+
+const buildReplyToMessageIdProp = () =>
+  Property.Number({
+    displayName: 'Reply To Message Id',
+    description: 'If the message is a reply, ID of the original message.',
+    required: false,
+  });
+
+const resolveParseMode = (value: string | undefined): string | undefined => {
+  if (!value || value === 'None') {
+    return undefined;
+  }
+  return value;
+};
+
+export type SetWebhookRequest = {
+  ip_address: string;
+  max_connections: number;
+  allowed_updates: string[];
+  drop_pending_updates: boolean;
+  secret_token: string;
+};
+
+export const telegramCommons = {
+  getApiUrl: (auth: AppConnectionValueForAuthProperty<typeof telegramBotAuth>, methodName: string) => {
+    return `https://api.telegram.org/bot${auth.secret_text}/${methodName}`;
+  },
+  subscribeWebhook: async (
+    botToken: string,
+    webhookUrl: string,
+    overrides?: Partial<SetWebhookRequest>
+  ) => {
+    const request: HttpRequest = {
+      method: HttpMethod.POST,
+      url: `https://api.telegram.org/bot${botToken}/setWebhook`,
+      body: {
+        allowed_updates: [],
+        url: webhookUrl,
+        ...overrides,
+      },
+    };
+
+    await httpClient.sendRequest(request);
+  },
+  unsubscribeWebhook: async (botToken: string) => {
+    const request: HttpRequest = {
+      method: HttpMethod.GET,
+      url: `https://api.telegram.org/bot${botToken}/deleteWebhook`,
+    };
+    return await httpClient.sendRequest(request);
+  },
+  chatIdInstructions: buildChatIdInstructions,
+  formatLinkInstructions: buildFormatLinkInstructions,
+  chatIdProp: buildChatIdProp,
+  messageThreadIdProp: buildMessageThreadIdProp,
+  parseModeProp: buildParseModeProp,
+  replyMarkupProp: buildReplyMarkupProp,
+  disableNotificationProp: buildDisableNotificationProp,
+  protectContentProp: buildProtectContentProp,
+  replyToMessageIdProp: buildReplyToMessageIdProp,
+  resolveParseMode,
+};