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

package/src/lib/action/telegram-create-invite-link.ts

@@ -0,0 +1,62 @@
+import { httpClient, HttpMethod } from '@agnocon/pieces-common';
+import { createAction, Property } from '@agnocon/pieces-framework';
+import { telegramBotAuth } from '../..';
+import { telegramCommons } from '../common';
+import { telegramCreateInviteLinkActionOutputSchema } from '../output-schemas';
+
+export const telegramCreateInviteLink = createAction({
+  auth: telegramBotAuth,
+  name: 'telegram_create_invite_link',
+  displayName: 'Create Invite Link',
+  description: 'Create a new invite link for a Telegram chat.',
+  audience: 'ai',
+  aiMetadata: {
+    description:
+      'Creates a new invite link for a chat by chat_id (a numeric id or @channelusername the bot can reach), optionally with a name, expiry, member limit, or join-request approval. Use to generate a shareable join link; the bot must be an administrator with invite rights. Not idempotent: each call mints a distinct new link (it does not reuse or revoke prior links).',
+    idempotent: false,
+  },
+  outputSchema: telegramCreateInviteLinkActionOutputSchema,
+  props: {
+    chat_id: telegramCommons.chatIdProp(),
+    name: Property.ShortText({
+      displayName: 'Name',
+      description: 'Name of the invite link (max 32 chars).',
+      required: false,
+    }),
+    expire_date: Property.DateTime({
+      displayName: 'Expire Date',
+      description: 'Point in time when the link will expire.',
+      required: false,
+    }),
+    member_limit: Property.Number({
+      displayName: 'Member Limit',
+      description:
+        'Maximum number of users that can be members of the chat simultaneously after joining via this invite link; 1-99999.',
+      required: false,
+    }),
+    creates_join_request: Property.Checkbox({
+      displayName: 'Creates Join Request',
+      description:
+        'If True, users joining the chat via the link need to be approved by chat administrators.',
+      required: false,
+      defaultValue: false,
+    }),
+  },
+  async run(ctx) {
+    const response = await httpClient.sendRequest<never>({
+      method: HttpMethod.POST,
+      url: telegramCommons.getApiUrl(ctx.auth, 'createChatInviteLink'),
+      headers: {},
+      body: {
+        chat_id: ctx.propsValue.chat_id,
+        name: ctx.propsValue.name ?? undefined,
+        expire_date: ctx.propsValue.expire_date
+          ? Math.floor(new Date(ctx.propsValue.expire_date).getTime() / 1000)
+          : undefined,
+        member_limit: ctx.propsValue.member_limit ?? undefined,
+        creates_join_request: ctx.propsValue.creates_join_request ?? false,
+      },
+    });
+    return response.body;
+  },
+});

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

@@ -0,0 +1,37 @@
+import { createAction, Property } from '@agnocon/pieces-framework';
+import { HttpMethod, httpClient } from '@agnocon/pieces-common';
+import { telegramCommons } from '../common';
+import { telegramBotAuth } from '../..';
+import { telegramDeleteMessageActionOutputSchema } from '../output-schemas';
+
+export const telegramDeleteMessage = createAction({
+  auth: telegramBotAuth,
+  name: 'telegram_delete_message',
+  displayName: 'Delete Message',
+  description: 'Delete a message from a Telegram chat.',
+  audience: 'ai',
+  aiMetadata: {
+    description:
+      'Permanently removes a message from a chat, targeted by chat_id (a numeric id or @channelusername the bot can reach) and message_id (from a prior send action\'s return or the New Message trigger payload). Use to clean up or retract content; the bot can delete only its own messages, or any message in groups where it is an administrator. Idempotent in effect: the message ends up gone regardless of how many times this runs.',
+    idempotent: true,
+  },
+  outputSchema: telegramDeleteMessageActionOutputSchema,
+  props: {
+    chat_id: telegramCommons.chatIdProp(),
+    message_id: Property.ShortText({
+      displayName: 'Message Id',
+      description: 'Identifier of the message to delete.',
+      required: true,
+    }),
+  },
+  async run(ctx) {
+    return await httpClient.sendRequest<never>({
+      method: HttpMethod.POST,
+      url: telegramCommons.getApiUrl(ctx.auth, 'deleteMessage'),
+      body: {
+        chat_id: ctx.propsValue.chat_id,
+        message_id: ctx.propsValue.message_id,
+      },
+    });
+  },
+});

package/src/lib/action/telegram-edit-message-text.ts

@@ -0,0 +1,92 @@
+import { createAction, Property } from '@agnocon/pieces-framework';
+import { HttpMethod, httpClient } from '@agnocon/pieces-common';
+import { telegramCommons } from '../common';
+import { telegramBotAuth } from '../..';
+import { telegramEditMessageTextActionOutputSchema } from '../output-schemas';
+
+export const telegramEditMessageText = createAction({
+  auth: telegramBotAuth,
+  name: 'telegram_edit_message_text',
+  displayName: 'Edit Message Text',
+  description: 'Edit the text of a message the bot already sent.',
+  audience: 'ai',
+  aiMetadata: {
+    description:
+      'Replaces the text of a message the bot already sent, targeted by chat_id + message_id OR by inline_message_id (the two modes are mutually exclusive — resolve message_id from the send action\'s return or the New Message trigger payload). Use to update a status or correct a message in place instead of sending a new one. Text is sent as plain text unless format is set; if you set MarkdownV2 or HTML the text must be correctly escaped or Telegram rejects it. Idempotent in effect (the message ends at the given text), but Telegram rejects an edit whose new text matches the current content.',
+    idempotent: true,
+  },
+  outputSchema: telegramEditMessageTextActionOutputSchema,
+  props: {
+    chat_id: Property.ShortText({
+      displayName: 'Chat Id',
+      description:
+        'Numeric id or @channelusername of the chat holding the message. Required together with Message Id; leave empty when editing an inline message (use Inline Message Id instead).',
+      required: false,
+    }),
+    message_id: Property.ShortText({
+      displayName: 'Message Id',
+      description: 'Identifier of the message to edit (used together with Chat Id).',
+      required: false,
+    }),
+    inline_message_id: Property.ShortText({
+      displayName: 'Inline Message Id',
+      description:
+        'Identifier of the inline message (mutually exclusive with Chat Id + Message Id).',
+      required: false,
+    }),
+    text: Property.LongText({
+      displayName: 'New Text',
+      description: 'New text of the message (1–4096 chars).',
+      required: true,
+    }),
+    format: Property.StaticDropdown({
+      displayName: 'Format',
+      description:
+        'How the message text should be parsed by Telegram. Defaults to plain text; only set MarkdownV2 or HTML when the text is correctly escaped/tagged.',
+      required: false,
+      options: {
+        options: [
+          { label: 'Plain Text', value: 'None' },
+          { label: 'Markdown (V2)', value: 'MarkdownV2' },
+          { label: 'HTML', value: 'HTML' },
+        ],
+      },
+      defaultValue: 'None',
+    }),
+    disable_web_page_preview: Property.Checkbox({
+      displayName: 'Disable Web Page Preview',
+      description: 'Disable link previews for links in this message.',
+      required: false,
+      defaultValue: false,
+    }),
+    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 hasChatTarget = Boolean(ctx.propsValue.chat_id && ctx.propsValue.message_id);
+    const hasInlineTarget = Boolean(ctx.propsValue.inline_message_id);
+    if (!hasChatTarget && !hasInlineTarget) {
+      throw new Error(
+        'Either Chat Id + Message Id, or Inline Message Id, must be provided.'
+      );
+    }
+
+    return await httpClient.sendRequest<never>({
+      method: HttpMethod.POST,
+      url: telegramCommons.getApiUrl(ctx.auth, 'editMessageText'),
+      body: {
+        chat_id: ctx.propsValue.chat_id ?? undefined,
+        message_id: ctx.propsValue.message_id ?? undefined,
+        inline_message_id: ctx.propsValue.inline_message_id ?? undefined,
+        text: ctx.propsValue.text,
+        parse_mode: telegramCommons.resolveParseMode(ctx.propsValue.format),
+        disable_web_page_preview: ctx.propsValue.disable_web_page_preview ?? false,
+        reply_markup: ctx.propsValue.reply_markup ?? undefined,
+      },
+    });
+  },
+});

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

@@ -0,0 +1,54 @@
+import { createAction, Property } from '@agnocon/pieces-framework';
+import { HttpMethod, httpClient } from '@agnocon/pieces-common';
+import { telegramCommons } from '../common';
+import { telegramBotAuth } from '../..';
+import { telegramForwardMessageActionOutputSchema } from '../output-schemas';
+
+export const telegramForwardMessage = createAction({
+  auth: telegramBotAuth,
+  name: 'telegram_forward_message',
+  displayName: 'Forward Message',
+  description: 'Forward a message from one chat to another.',
+  audience: 'ai',
+  aiMetadata: {
+    description:
+      'Forwards an existing message from a source chat (from_chat_id) to a target chat (chat_id), preserving original sender attribution. chat_id and from_chat_id are each a numeric id or @channelusername the bot can reach; message_id comes from the New Message trigger or a prior send action. Use to relay content the bot can access between chats; the bot must be able to read the source and post to the target. Not idempotent: each call creates a new forwarded message.',
+    idempotent: false,
+  },
+  outputSchema: telegramForwardMessageActionOutputSchema,
+  props: {
+    chat_id: Property.ShortText({
+      displayName: 'Target Chat Id',
+      description:
+        'Chat the message will be forwarded to (a numeric id or @channelusername the bot can reach).',
+      required: true,
+    }),
+    from_chat_id: Property.ShortText({
+      displayName: 'From Chat Id',
+      description: 'Chat the original message came from.',
+      required: true,
+    }),
+    message_id: Property.ShortText({
+      displayName: 'Message Id',
+      description: 'Identifier of the message to forward.',
+      required: true,
+    }),
+    message_thread_id: telegramCommons.messageThreadIdProp(),
+    disable_notification: telegramCommons.disableNotificationProp(),
+    protect_content: telegramCommons.protectContentProp(),
+  },
+  async run(ctx) {
+    return await httpClient.sendRequest<never>({
+      method: HttpMethod.POST,
+      url: telegramCommons.getApiUrl(ctx.auth, 'forwardMessage'),
+      body: {
+        chat_id: ctx.propsValue.chat_id,
+        from_chat_id: ctx.propsValue.from_chat_id,
+        message_id: ctx.propsValue.message_id,
+        message_thread_id: ctx.propsValue.message_thread_id ?? undefined,
+        disable_notification: ctx.propsValue.disable_notification ?? false,
+        protect_content: ctx.propsValue.protect_content ?? false,
+      },
+    });
+  },
+});

package/src/lib/action/telegram-get-bot-info.ts

@@ -0,0 +1,31 @@
+import { HttpError, HttpMethod, httpClient } from '@agnocon/pieces-common';
+import { createAction } from '@agnocon/pieces-framework';
+import { telegramCommons } from '../common';
+import { telegramBotAuth } from '../..';
+import { telegramGetBotInfoActionOutputSchema } from '../output-schemas';
+
+export const telegramGetBotInfo = createAction({
+  auth: telegramBotAuth,
+  name: 'telegram_get_bot_info',
+  displayName: 'Get Bot Info',
+  description: "Get the authenticated bot's own identity and capabilities.",
+  audience: 'ai',
+  aiMetadata: {
+    description:
+      "Returns the authenticated bot's own identity and capabilities (id, username, name, and which features such as inline mode or group joins are enabled). Use to confirm which bot the connection points at or to read the bot's @username before building an invite or mention. Read-only and takes no input.",
+    idempotent: true,
+  },
+  outputSchema: telegramGetBotInfoActionOutputSchema,
+  props: {},
+  async run(ctx) {
+    try {
+      const response = await httpClient.sendRequest<never>({
+        method: HttpMethod.POST,
+        url: telegramCommons.getApiUrl(ctx.auth, 'getMe'),
+      });
+      return response.body;
+    } catch (error) {
+      return (error as HttpError).errorMessage().response.body;
+    }
+  },
+});

package/src/lib/action/telegram-get-chat-administrators.ts

@@ -0,0 +1,36 @@
+import { HttpError, HttpMethod, httpClient } from '@agnocon/pieces-common';
+import { createAction } from '@agnocon/pieces-framework';
+import { telegramCommons } from '../common';
+import { telegramBotAuth } from '../..';
+import { telegramGetChatAdministratorsActionOutputSchema } from '../output-schemas';
+
+export const telegramGetChatAdministrators = createAction({
+  auth: telegramBotAuth,
+  name: 'telegram_get_chat_administrators',
+  displayName: 'Get Chat Administrators',
+  description: 'List the administrators of a Telegram chat.',
+  audience: 'ai',
+  aiMetadata: {
+    description:
+      "Lists the administrators of a chat by chat_id (a numeric id or @channelusername) — each admin's user, status (creator/administrator), and granted rights. Use to discover who can moderate a chat, or to find a user_id before checking one member with telegram_get_chat_member. Returns an empty list for private chats. Read-only.",
+    idempotent: true,
+  },
+  outputSchema: telegramGetChatAdministratorsActionOutputSchema,
+  props: {
+    chat_id: telegramCommons.chatIdProp(),
+  },
+  async run(ctx) {
+    try {
+      const response = await httpClient.sendRequest<never>({
+        method: HttpMethod.POST,
+        url: telegramCommons.getApiUrl(ctx.auth, 'getChatAdministrators'),
+        body: {
+          chat_id: ctx.propsValue.chat_id,
+        },
+      });
+      return response.body;
+    } catch (error) {
+      return (error as HttpError).errorMessage().response.body;
+    }
+  },
+});

package/src/lib/action/telegram-get-chat-member-count.ts

@@ -0,0 +1,36 @@
+import { HttpError, HttpMethod, httpClient } from '@agnocon/pieces-common';
+import { createAction } from '@agnocon/pieces-framework';
+import { telegramCommons } from '../common';
+import { telegramBotAuth } from '../..';
+import { telegramGetChatMemberCountActionOutputSchema } from '../output-schemas';
+
+export const telegramGetChatMemberCount = createAction({
+  auth: telegramBotAuth,
+  name: 'telegram_get_chat_member_count',
+  displayName: 'Get Chat Member Count',
+  description: 'Get the number of members in a Telegram chat.',
+  audience: 'ai',
+  aiMetadata: {
+    description:
+      'Returns the number of members in a chat by chat_id (a numeric id or @channelusername). Use to size a group or channel before posting or to monitor membership; for per-user details use telegram_get_chat_member. Read-only.',
+    idempotent: true,
+  },
+  outputSchema: telegramGetChatMemberCountActionOutputSchema,
+  props: {
+    chat_id: telegramCommons.chatIdProp(),
+  },
+  async run(ctx) {
+    try {
+      const response = await httpClient.sendRequest<never>({
+        method: HttpMethod.POST,
+        url: telegramCommons.getApiUrl(ctx.auth, 'getChatMemberCount'),
+        body: {
+          chat_id: ctx.propsValue.chat_id,
+        },
+      });
+      return response.body;
+    } catch (error) {
+      return (error as HttpError).errorMessage().response.body;
+    }
+  },
+});

package/src/lib/action/telegram-get-chat-member.ts

@@ -0,0 +1,43 @@
+import { httpClient, HttpError, HttpMethod } from '@agnocon/pieces-common';
+import { createAction, Property } from '@agnocon/pieces-framework';
+import { telegramBotAuth } from '../..';
+import { telegramCommons } from '../common';
+import { telegramGetChatMemberActionOutputSchema } from '../output-schemas';
+
+export const telegramGetChatMember = createAction({
+  auth: telegramBotAuth,
+  name: 'telegram_get_chat_member',
+  displayName: 'Get Chat Member',
+  description: 'Get membership info for a user in a Telegram chat.',
+  audience: 'ai',
+  aiMetadata: {
+    description:
+      "Looks up one user's membership in a chat by chat_id (a numeric id or @channelusername) and user_id, returning their status (member, administrator, creator, restricted, left, kicked) and permissions. Use to check whether a user belongs to a chat or what rights they hold before acting; to list all admins use telegram_get_chat_administrators. Read-only.",
+    idempotent: true,
+  },
+  outputSchema: telegramGetChatMemberActionOutputSchema,
+  props: {
+    chat_id: telegramCommons.chatIdProp(),
+    user_id: Property.ShortText({
+      displayName: 'User Id',
+      description: 'Unique identifier for the user (e.g. from the New Message trigger payload).',
+      required: true,
+    }),
+  },
+  async run(ctx) {
+    try {
+      const response = await httpClient.sendRequest<never>({
+        method: HttpMethod.POST,
+        url: telegramCommons.getApiUrl(ctx.auth, 'getChatMember'),
+        headers: {},
+        body: {
+          chat_id: ctx.propsValue.chat_id,
+          user_id: ctx.propsValue.user_id,
+        },
+      });
+      return response.body;
+    } catch (error) {
+      return (error as HttpError).errorMessage().response.body;
+    }
+  },
+});

package/src/lib/action/telegram-get-chat.ts

@@ -0,0 +1,36 @@
+import { HttpError, HttpMethod, httpClient } from '@agnocon/pieces-common';
+import { createAction } from '@agnocon/pieces-framework';
+import { telegramCommons } from '../common';
+import { telegramBotAuth } from '../..';
+import { telegramGetChatActionOutputSchema } from '../output-schemas';
+
+export const telegramGetChat = createAction({
+  auth: telegramBotAuth,
+  name: 'telegram_get_chat',
+  displayName: 'Get Chat',
+  description: 'Get up-to-date information about a Telegram chat.',
+  audience: 'ai',
+  aiMetadata: {
+    description:
+      'Looks up current details about a chat (title, description, type, photo, member count) by chat_id (a numeric id or @channelusername). Use to resolve or inspect a chat before acting on it, or to confirm the bot can reach it; the bot must be a member of or have access to the chat. Read-only and safe to retry.',
+    idempotent: true,
+  },
+  outputSchema: telegramGetChatActionOutputSchema,
+  props: {
+    chat_id: telegramCommons.chatIdProp(),
+  },
+  async run(ctx) {
+    try {
+      const response = await httpClient.sendRequest<never>({
+        method: HttpMethod.POST,
+        url: telegramCommons.getApiUrl(ctx.auth, 'getChat'),
+        body: {
+          chat_id: ctx.propsValue.chat_id,
+        },
+      });
+      return response.body;
+    } catch (error) {
+      return (error as HttpError).errorMessage().response.body;
+    }
+  },
+});

package/src/lib/action/telegram-get-file.ts

@@ -0,0 +1,83 @@
+import { createAction, Property } from '@agnocon/pieces-framework';
+import { HttpMethod, httpClient } from '@agnocon/pieces-common';
+import { telegramCommons } from '../common';
+import { telegramBotAuth } from '../..';
+import { telegramGetFileActionOutputSchema } from '../output-schemas';
+
+type TelegramFileInfo = {
+  file_id: string;
+  file_unique_id: string;
+  file_size?: number;
+  file_path?: string;
+};
+
+type TelegramGetFileResponse = {
+  ok: boolean;
+  result: TelegramFileInfo;
+};
+
+export const telegramGetFile = createAction({
+  auth: telegramBotAuth,
+  name: 'telegram_get_file',
+  displayName: 'Get File',
+  description: 'Resolve a Telegram file_id to its metadata and download URL.',
+  audience: 'ai',
+  aiMetadata: {
+    description:
+      'Resolves a Telegram file_id (from a message the bot received) to its file metadata and download URL, and optionally downloads the content as base64 when download is enabled. Use to retrieve a file attached to an incoming message; the download URL Telegram returns is time-limited. Read-only and safe to retry.',
+    idempotent: true,
+  },
+  outputSchema: telegramGetFileActionOutputSchema,
+  props: {
+    file_id: Property.ShortText({
+      displayName: 'File ID',
+      description: 'File identifier to get information about (from a received message).',
+      required: true,
+    }),
+    download: Property.Checkbox({
+      displayName: 'Download File',
+      description: 'If enabled, the file is downloaded and returned as base64.',
+      required: false,
+      defaultValue: false,
+    }),
+  },
+  async run(ctx) {
+    const fileInfoResponse = await httpClient.sendRequest<TelegramGetFileResponse>({
+      method: HttpMethod.POST,
+      url: telegramCommons.getApiUrl(ctx.auth, 'getFile'),
+      body: {
+        file_id: ctx.propsValue.file_id,
+      },
+    });
+
+    if (!fileInfoResponse.body.ok) {
+      throw new Error(`Failed to get file info: ${JSON.stringify(fileInfoResponse.body)}`);
+    }
+
+    const fileInfo = fileInfoResponse.body.result;
+    const fileUrl = fileInfo.file_path
+      ? `https://api.telegram.org/file/bot${ctx.auth.secret_text}/${fileInfo.file_path}`
+      : undefined;
+
+    if (ctx.propsValue.download && fileUrl) {
+      const fileResponse = await httpClient.sendRequest<Buffer>({
+        method: HttpMethod.GET,
+        url: fileUrl,
+        responseType: 'arraybuffer',
+      });
+
+      const base64Content = Buffer.from(fileResponse.body).toString('base64');
+
+      return {
+        file_info: fileInfo,
+        file_url: fileUrl,
+        file_content_base64: base64Content,
+      };
+    }
+
+    return {
+      file_info: fileInfo,
+      file_url: fileUrl,
+    };
+  },
+});

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

@@ -0,0 +1,45 @@
+import { createAction, Property } from '@agnocon/pieces-framework';
+import { HttpMethod, httpClient } from '@agnocon/pieces-common';
+import { telegramCommons } from '../common';
+import { telegramBotAuth } from '../..';
+import { telegramPinMessageActionOutputSchema } from '../output-schemas';
+
+export const telegramPinMessage = createAction({
+  auth: telegramBotAuth,
+  name: 'telegram_pin_message',
+  displayName: 'Pin Message',
+  description: 'Pin a message in a Telegram chat.',
+  audience: 'ai',
+  aiMetadata: {
+    description:
+      'Pins an existing message in a chat, targeted by chat_id (a numeric id or @channelusername the bot can reach) and message_id (from a prior send action or the New Message trigger); the bot must be an administrator with pin rights. Use to highlight an announcement or important message; to remove the pin use telegram_unpin_message. Idempotent: pinning an already-pinned message leaves it pinned.',
+    idempotent: true,
+  },
+  outputSchema: telegramPinMessageActionOutputSchema,
+  props: {
+    chat_id: telegramCommons.chatIdProp(),
+    message_id: Property.ShortText({
+      displayName: 'Message Id',
+      description: 'Identifier of the message to pin.',
+      required: true,
+    }),
+    disable_notification: Property.Checkbox({
+      displayName: 'Disable Notification',
+      description:
+        'Pass True if it is not necessary to send a notification to all chat members.',
+      required: false,
+      defaultValue: false,
+    }),
+  },
+  async run(ctx) {
+    return await httpClient.sendRequest<never>({
+      method: HttpMethod.POST,
+      url: telegramCommons.getApiUrl(ctx.auth, 'pinChatMessage'),
+      body: {
+        chat_id: ctx.propsValue.chat_id,
+        message_id: ctx.propsValue.message_id,
+        disable_notification: ctx.propsValue.disable_notification ?? false,
+      },
+    });
+  },
+});