maxbot-api-client-ts 1.0.0

package/dist/api.d.mts

@@ -0,0 +1,723 @@
+interface ClientConfig {
+    base_url?: string;
+    token: string;
+    timeout?: number;
+    globalRPS?: number;
+}
+interface RequestOptions {
+    query?: Record<string, any>;
+    payload?: any;
+    body?: BodyInit;
+    headers?: Record<string, string>;
+}
+declare class APIClient {
+    private base_url;
+    private token;
+    private timeout;
+    private rateLimiter;
+    constructor(cfg: ClientConfig);
+    request<T>(method: string, path: string, opts?: RequestOptions): Promise<T>;
+    setGlobalRateLimit(rps: number): void;
+    getTimeout(): number;
+}
+
+declare enum AttachmentType {
+    Image = "image",
+    Video = "video",
+    Audio = "audio",
+    File = "file",
+    Sticker = "sticker",
+    Contact = "contact",
+    Keyboard = "inline_keyboard",
+    Share = "share",
+    Location = "location"
+}
+declare enum ChatType {
+    Channel = "channel",
+    Chat = "chat",
+    Dialog = "dialog"
+}
+declare enum UploadType {
+    Image = "image",
+    Video = "video",
+    Audio = "audio",
+    File = "file"
+}
+declare enum ChatStatus {
+    Active = "active",
+    Closed = "closed",
+    Left = "left",
+    Removed = "removed"
+}
+declare enum MarkupType {
+    MarkupStrong = "strong",
+    MarkupEmphasized = "emphasized",
+    MarkupMonospaced = "monospaced",
+    MarkupLink = "link",
+    MarkupStrikethrough = "strikethrough",
+    MarkupUnderline = "underline",
+    MarkupUser = "user_mention"
+}
+declare enum Format {
+    HTML = "html",
+    Markdown = "markdown"
+}
+declare enum UpdateType {
+    TypeBotAdded = "bot_added",
+    TypeBotRemoved = "bot_removed",
+    TypeBotStarted = "bot_started",
+    TypeBotStopped = "bot_stopped",
+    TypeChatTitleChanged = "chat_title_changed",
+    TypeDialogMuted = "dialog_muted",
+    TypeDialogUnmuted = "dialog_unmuted",
+    TypeDialogCleared = "dialog_cleared",
+    TypeDialogRemoved = "dialog_removed",
+    TypeMessageCreated = "message_created",
+    TypeMessageCallback = "message_callback",
+    TypeMessageEdited = "message_edited",
+    TypeMessageRemoved = "message_removed",
+    TypeUserAdded = "user_added",
+    TypeUserRemoved = "user_removed"
+}
+declare enum LinkedMessageType {
+    forward = "forward",
+    reply = "reply"
+}
+declare enum SenderAction {
+    typing_on = "typing_on",
+    typing_off = "typing_off",
+    sending_photo = "sending_photo",
+    sending_video = "sending_video",
+    sending_audio = "sending_audio",
+    sending_file = "sending_file",
+    mark_seen = "mark_seen"
+}
+declare enum ChatAdminPermission {
+    read_all_messages = "read_all_messages",
+    add_remove_members = "add_remove_members",
+    add_admins = "add_admins",
+    change_chat_info = "change_chat_info",
+    pin_message = "pin_message",
+    write = "write",
+    edit_link = "edit_link"
+}
+
+interface Attachment {
+    type: AttachmentType;
+    payload?: any;
+    latitude?: number;
+    longitude?: number;
+}
+interface PhotoAttachmentPayload {
+    photo_id?: number;
+    token?: string;
+    url?: string;
+}
+interface User {
+    user_id: number;
+    first_name: string;
+    last_name?: string;
+    username?: string;
+    is_bot: boolean;
+    last_activity_time: number;
+}
+interface BotCommand {
+    name: string;
+    description?: string;
+}
+interface BotInfo extends User {
+    description?: string;
+    avatar_url?: string;
+    full_avatar_url?: string;
+    commands?: BotCommand[];
+}
+interface BotPatch {
+    name?: string;
+    username?: string;
+    description?: string;
+    commands?: BotCommand[];
+    photo?: PhotoAttachmentPayload;
+}
+interface Image {
+    url: string;
+}
+interface DialogWithUser extends User {
+    description?: string;
+    avatar_url: string;
+    full_avatar_url: string;
+}
+interface MessageStat {
+    views: number;
+}
+interface LinkedMessage {
+    type: LinkedMessageType;
+    sender?: User;
+    chat_id?: number;
+    message?: MessageBody;
+}
+interface MessageBody {
+    mid: string;
+    seq: number;
+    text?: string;
+    attachments?: Attachment[];
+    markup?: MarkupElement[];
+}
+interface Recipient {
+    chat_id?: number;
+    chat_type: ChatType;
+    user_id?: number;
+}
+interface Message {
+    sender: User;
+    recipient: Recipient;
+    timestamp: number;
+    link?: LinkedMessage;
+    body: MessageBody;
+    stat?: MessageStat;
+    url?: string;
+}
+interface Chat {
+    chat_id: number;
+    type: ChatType;
+    status: ChatStatus;
+    title?: string;
+    icon?: Image;
+    last_event_time: number;
+    participants_count: number;
+    owner_id?: number;
+    participants?: Record<string, number>;
+    is_public: boolean;
+    link?: string;
+    description?: string;
+    dialog_with_user?: DialogWithUser;
+    chat_message_id: string;
+    pinned_message?: Message;
+}
+interface ChatMember extends DialogWithUser {
+    last_access_time: number;
+    is_owner: boolean;
+    is_admin: boolean;
+    join_time: number;
+    permissions: ChatAdminPermission[];
+    alias?: string;
+}
+interface ChatAdmin {
+    user_id: number;
+    permissions: ChatAdminPermission[];
+    alias?: string;
+}
+interface MessagesList {
+    messages: Message[];
+}
+interface MarkupElement {
+    type: MarkupType;
+    from: number;
+    length: number;
+}
+interface VideoUrls {
+    mp4_1080?: string;
+    mp4_720?: string;
+    mp4_480?: string;
+    mp4_360?: string;
+    mp4_240?: string;
+    mp4_144?: string;
+    hls?: string;
+}
+interface NewMessageLink {
+    type: LinkedMessageType;
+    mid: string;
+}
+interface NewMessageBody {
+    text?: string;
+    attachments?: Attachment[];
+    link?: NewMessageLink;
+    notify?: boolean;
+    format?: Format;
+}
+interface Callback {
+    timestamp: number;
+    callback_id: string;
+    payload?: string;
+    user: User;
+}
+interface Update {
+    update_type: UpdateType;
+    timestamp: number;
+    callback?: Callback;
+    message: Message;
+    message_id?: string;
+    chat_id?: number;
+    user_id?: number;
+    muted_until?: number;
+    user_locale?: string;
+    is_channel?: boolean;
+}
+interface Subscription {
+    url: string;
+    time: number;
+    update_types?: UpdateType[];
+}
+interface ChatInfo {
+    chat_id: number;
+    type: ChatType;
+    status: ChatStatus;
+    title?: string;
+    icon?: Image;
+    last_event_time: number;
+    participants_count?: number;
+    owner_id?: number;
+    participants?: Record<string, number>;
+    is_public: boolean;
+    link?: string;
+    description?: string;
+    dialog_with_user?: DialogWithUser[];
+    chat_message_id?: string;
+    pinned_message?: Message[];
+}
+
+declare class BotsService {
+    private client;
+    constructor(client: APIClient);
+    /**
+     * GetBot returns information about the current bot (ID, name, description).
+     * @returns Promise<BotInfo>
+     * @example
+     * const response = await bot.bots.getBot();
+     * console.log("Connected as:", info.first_name);
+     */
+    getBot(): Promise<BotInfo>;
+    /**
+     * PatchBot updates bot information.
+     * Fill in only the fields you want to change.
+     * @param req - The bot data to update.
+     * @returns Promise<BotInfo>
+     * @example
+     * const response = await bot.bots.patchBot({
+     * name: "New Name",
+     * description: "New description"
+     * });
+     */
+    patchBot(req: BotPatch): Promise<BotInfo>;
+}
+
+interface GetChatsReq {
+    count?: number;
+    marker?: number;
+}
+interface GetChatsResp {
+    chats: Chat[];
+    marker?: number;
+}
+interface GetChatReq {
+    chat_id: number;
+}
+interface EditChatReq {
+    chat_id: number;
+    icon?: Image;
+    title?: string;
+    pin?: string;
+    notify?: boolean;
+}
+interface DeleteChatReq {
+    chat_id: number;
+}
+interface SendActionReq {
+    chat_id: number;
+    action: SenderAction;
+}
+interface PinMessageReq {
+    chat_id: number;
+    message_id: string;
+    notify?: boolean;
+}
+interface UnpinMessageReq {
+    chat_id: number;
+}
+interface GetPinnedMessageReq {
+    chat_id: number;
+}
+interface GetChatMembershipReq {
+    chat_id: number;
+}
+interface LeaveChatReq {
+    chat_id: number;
+}
+interface GetChatAdminsReq {
+    chat_id: number;
+}
+interface GetChatAdminsResp {
+    members: ChatMember[];
+    marker?: number;
+}
+interface SetChatAdminsReq {
+    chat_id: number;
+    admins: ChatAdmin[];
+    marker?: number;
+}
+interface DeleteAdminReq {
+    chat_id: number;
+    user_id: number;
+}
+interface GetChatMembersReq {
+    chat_id: number;
+    user_ids?: number[];
+    marker?: number;
+    count?: number;
+}
+interface AddMembersReq {
+    chat_id: number;
+    user_ids?: number[];
+}
+interface AddMembersResp extends SimpleQueryResult {
+    failed_user_ids?: number[];
+    failed_user_details?: FailedUserDetails[];
+}
+interface FailedUserDetails {
+    error_code: string;
+    user_ids: number[];
+}
+interface DeleteMemberReq {
+    chat_id: number;
+    user_id: number;
+    block?: boolean;
+}
+interface GetSubscriptionsResp {
+    subscriptions: Subscription[];
+}
+interface SubscribeReq {
+    url: string;
+    update_types?: UpdateType[];
+    secret?: string;
+}
+interface UnsubscribeReq {
+    url: string;
+}
+interface GetUpdatesReq {
+    limit?: number;
+    timeout?: number;
+    marker?: number;
+    types?: UpdateType[];
+}
+interface GetUpdatesResp {
+    updates: Update[];
+    marker: number;
+}
+interface UploadFileReq {
+    type: UploadType;
+    upload_url?: string;
+    file_path: string;
+}
+interface UploadedInfo {
+    file_id?: number;
+    token?: string;
+}
+interface GetMessagesReq {
+    chat_id?: number;
+    message_ids?: string[];
+    from?: number;
+    to?: number;
+    count?: number;
+}
+interface SendMessageReq {
+    user_id?: number;
+    chat_id?: number;
+    text?: string;
+    format?: Format;
+    notify?: boolean;
+    attachments?: Attachment[];
+    link?: NewMessageLink;
+    disable_link_preview?: boolean;
+}
+interface SendMessageResp {
+    message: Message;
+}
+interface EditMessageReq {
+    message_id: string;
+    text?: string;
+    attachments?: Attachment[];
+    link?: NewMessageLink;
+    notify?: boolean;
+    format?: Format;
+}
+interface DeleteMessageReq {
+    message_id: string;
+}
+interface GetMessageReq {
+    message_id: string;
+}
+interface GetVideoInfoReq {
+    video_token: string;
+}
+interface GetVideoInfoResp {
+    token: string;
+    urls?: VideoUrls;
+    thumbnail?: PhotoAttachmentPayload;
+    width?: number;
+    height?: number;
+    duration?: number;
+}
+interface AnswerCallbackReq {
+    callback_id: string;
+    message?: NewMessageBody;
+    notification?: string;
+}
+interface SimpleQueryResult {
+    success: boolean;
+    message?: string;
+}
+interface SendFileReq {
+    user_id?: number;
+    chat_id?: number;
+    text?: string;
+    format?: Format;
+    notify?: boolean;
+    file_source: string;
+    link?: NewMessageLink;
+    disable_link_preview?: boolean;
+    attachments?: Attachment[];
+}
+
+declare class ChatsService {
+    private client;
+    constructor(client: APIClient);
+    /**
+     * GetChats returns a list of group chats in which the bot participated.
+     * @param req - Filter parameters for chats.
+     * @example
+     * const response = await bot.chats.getChats({ limit: 10 });
+     */
+    getChats(req: GetChatsReq): Promise<GetChatsResp>;
+    /**
+     * GetChat returns information about a group chat by its ID.
+     * @param req - Object containing the chat_id.
+     * @example
+     * const response = await bot.chats.getChat({ chat_id: 123456789 });
+     */
+    getChat(req: GetChatReq): Promise<ChatInfo>;
+    /**
+     * EditChat allows you to edit information about a group chat.
+     * @param req - Chat edit parameters.
+     * @example
+     * await bot.chats.editChat({ chat_id: 123456789, title: "New Title" });
+     */
+    editChat(req: EditChatReq): Promise<ChatInfo>;
+    /**
+     * DeleteChat deletes a group chat for all participants.
+     * @example
+     * await bot.chats.deleteChat({ chat_id: 123456789 });
+     */
+    deleteChat(req: DeleteChatReq): Promise<SimpleQueryResult>;
+    /**
+     * SendAction allows sending bot actions to a group chat (e.g., "typing").
+     * @example
+     * await bot.chats.sendAction({ chat_id: 123456789, action: "typing" });
+     */
+    sendAction(req: SendActionReq): Promise<SimpleQueryResult>;
+    /**
+     * GetPinnedMessage returns the pinned message in a chat.
+     * @example
+     * const response = await bot.chats.getPinnedMessage({ chat_id: 123456789 });
+     */
+    getPinnedMessage(req: GetPinnedMessageReq): Promise<Message>;
+    /**
+     * PinMessage pins a message in a group chat.
+     * @example
+     * await bot.chats.pinMessage({ chat_id: 123456789, message_id: "456" });
+     */
+    pinMessage(req: PinMessageReq): Promise<SimpleQueryResult>;
+    /**
+     * UnpinMessage removes the pinned message in a group chat.
+     * @example
+     * await bot.chats.unpinMessage({ chat_id: 123456789 });
+     */
+    unpinMessage(req: UnpinMessageReq): Promise<SimpleQueryResult>;
+    /**
+     * GetChatMembership returns the bot's membership details in a group chat.
+     * @example
+     * const response = await bot.chats.getChatMembership({ chat_id: 123456789 });
+     */
+    getChatMembership(req: GetChatMembershipReq): Promise<ChatMember>;
+    /**
+     * LeaveChat removes the bot from a group chat.
+     * @example
+     * await bot.chats.leaveChat({ chat_id: 123456789 });
+     */
+    leaveChat(req: LeaveChatReq): Promise<SimpleQueryResult>;
+    /**
+     * GetChatAdmins returns a list of all group chat administrators.
+     * @example
+     * const response = await bot.chats.getChatAdmins({ chat_id: 123456789 });
+     */
+    getChatAdmins(req: GetChatAdminsReq): Promise<GetChatAdminsResp>;
+    /**
+     * SetChatAdmins assigns a group member as an administrator.
+     * @example
+     * await bot.chats.setChatAdmins({ chat_id: 123456789, user_id: 456 });
+     */
+    setChatAdmins(req: SetChatAdminsReq): Promise<SimpleQueryResult>;
+    /**
+     * DeleteAdmin revokes the user's administrator rights in a group chat.
+     * @example
+     * await bot.chats.deleteAdmin({ chat_id: 123456789, user_id: 456 });
+     */
+    deleteAdmin(req: DeleteAdminReq): Promise<SimpleQueryResult>;
+    /**
+     * GetChatMembers returns a list of participants in a group chat.
+     * @example
+     * const response = await bot.chats.getChatMembers({ chat_id: 123456789, limit: 50 });
+     */
+    getChatMembers(req: GetChatMembersReq): Promise<GetChatAdminsResp>;
+    /**
+     * AddMembers adds participants to a group chat.
+     * @example
+     * await bot.chats.addMembers({ chat_id: 123456789, user_ids: [456, 789] });
+     */
+    addMembers(req: AddMembersReq): Promise<AddMembersResp>;
+    /**
+     * DeleteMember removes a participant from a group chat.
+     * @example
+     * await bot.chats.deleteMember({ chat_id: 123456789, user_id: 456 });
+     */
+    deleteMember(req: DeleteMemberReq): Promise<SimpleQueryResult>;
+}
+
+declare class HelpersService {
+    private client;
+    constructor(client: APIClient);
+    /**
+     * SendFile simplifies file sending by automatically determining if the source is a URL or a local path.
+     * @param req - File send request parameters.
+     * @example
+     * await bot.helpers.sendFile({ chat_id: 123, file_source: "./photo.jpg" });
+     * await bot.helpers.sendFile({ chat_id: 123, file_source: "https://site.com/image.png" });
+     */
+    sendFile(req: SendFileReq): Promise<Message>;
+    /**
+     * SendFileByUrl sends a file using a direct URL. If the file is not an image,
+     * it will be downloaded to a temporary directory and uploaded to MAX servers.
+     * @param req - File send request with a URL in file_source.
+     */
+    sendFileByUrl(req: SendFileReq): Promise<Message>;
+    /**
+     * SendFileByUpload uploads a local file to MAX servers and sends it to the chat.
+     * @param req - File send request with a local path in file_source.
+     */
+    sendFileByUpload(req: SendFileReq): Promise<Message>;
+    private sendInternal;
+    private isURL;
+    private getExtension;
+    private determineUploadType;
+    private buildAttachmentFromToken;
+    private downloadTempFile;
+}
+
+declare class MessagesService {
+    private client;
+    constructor(client: APIClient);
+    /**
+     * GetMessages returns information about a message or an array of messages from a chat.
+     * @param req - Query parameters (chat_id, user_id, limit, etc.).
+     * @example
+     * const response = await bot.messages.getMessages({ chat_id: 123, limit: 10 });
+     */
+    getMessages(req: GetMessagesReq): Promise<MessagesList>;
+    /**
+     * SendMessage sends a text or media message to a specified user or chat.
+     * @param req - Message parameters including text and attachments.
+     * @example
+     * await bot.messages.sendMessage({ user_id: 123, text: "Hello!" });
+     */
+    sendMessage(req: SendMessageReq): Promise<SendMessageResp>;
+    /**
+     * EditMessage edits the text or media of a previously sent message.
+     * @param req - Edit parameters (message_id, new text, etc.).
+     * @example
+     * await bot.messages.editMessage({ message_id: 456, text: "Updated text" });
+     */
+    editMessage(req: EditMessageReq): Promise<SimpleQueryResult>;
+    /**
+     * DeleteMessage deletes a message from a chat.
+     * @example
+     * await bot.messages.deleteMessage({ chat_id: 123, message_id: 456 });
+     */
+    deleteMessage(req: DeleteMessageReq): Promise<SimpleQueryResult>;
+    /**
+     * GetMessage extracts the content and metadata of a specific message by its ID.
+     * @example
+     * const response = await bot.messages.getMessage({ message_id: 456 });
+     */
+    getMessage(req: GetMessageReq): Promise<Message>;
+    /**
+     * GetVideoInfo returns detailed information about an attached video.
+     * @example
+     * const response = await bot.messages.getVideoInfo({ video_token: "video123" });
+     */
+    getVideoInfo(req: GetVideoInfoReq): Promise<GetVideoInfoResp>;
+    /**
+     * AnswerCallback sends a response after a user clicks a button.
+     * @example
+     * await bot.messages.answerCallback({ callback_id: "cb123", text: "Got it!" });
+     */
+    answerCallback(req: AnswerCallbackReq): Promise<SimpleQueryResult>;
+}
+
+declare class SubscriptionsService {
+    private client;
+    constructor(client: APIClient);
+    /**
+     * GetSubscriptions returns a list of webhook notification subscriptions.
+     * @example
+     * const response = await bot.subscriptions.getSubscriptions();
+     */
+    getSubscriptions(): Promise<GetSubscriptionsResp>;
+    /**
+     * Subscribe configures the delivery of bot events via a webhook.
+     * @param req - Subscription parameters (url, types).
+     * @example
+     * await bot.subscriptions.subscribe({ url: "https://my.site/webhook", types: ["message.created"] });
+     */
+    subscribe(req: SubscribeReq): Promise<SimpleQueryResult>;
+    /**
+     * Unsubscribe cancels the bot's subscription to receiving updates via webhook.
+     * @example
+     * await bot.subscriptions.unsubscribe({ url: "https://my.site/webhook" });
+     */
+    unsubscribe(req: UnsubscribeReq): Promise<SimpleQueryResult>;
+    /**
+     * GetUpdates retrieves incoming updates (Long-polling).
+     * @param req - Polling parameters (marker, timeout, limit).
+     * @example
+     * const response = await bot.subscriptions.getUpdates({ timeout: 25 });
+     */
+    getUpdates(req: GetUpdatesReq): Promise<GetUpdatesResp>;
+}
+
+declare class UploadsService {
+    private client;
+    constructor(client: APIClient);
+    /**
+     * UploadFile uploads a file to MAX servers for subsequent transmission.
+     * It handles both the initial request for an upload URL and the actual multipart upload.
+     * @param req - Upload parameters (type, file_path).
+     * @returns Promise<UploadedInfo> containing the file token.
+     * @example
+     * const response = await bot.uploads.uploadFile({ type: "image", file_path: "./corgi.png" });
+     * console.log("File token:", file.token);
+     */
+    uploadFile(req: UploadFileReq): Promise<UploadedInfo>;
+    private getupload_url;
+    private uploadMultipart;
+}
+
+declare class MaxBotAPI {
+    bots: BotsService;
+    chats: ChatsService;
+    helpers: HelpersService;
+    messages: MessagesService;
+    subscriptions: SubscriptionsService;
+    uploads: UploadsService;
+    client: APIClient;
+    constructor(cfg: ClientConfig);
+}
+
+export { MaxBotAPI };