@mtcute/dispatcher 0.18.0-rc.5 → 0.18.0

package/callback-data-builder.d.cts

@@ -0,0 +1,49 @@
+import { BusinessCallbackQuery, CallbackQuery, InlineCallbackQuery, MaybeArray, MaybePromise } from '@mtcute/core';
+import { UpdateFilter } from './filters/types.js';
+/**
+ * Callback data builder, inspired by [aiogram](https://github.com/aiogram/aiogram).
+ *
+ * This can be used to simplify management of different callbacks.
+ *
+ * [Learn more in the docs](/guide/topics/keyboards.html#callback-data-builders)
+ */
+export declare class CallbackDataBuilder<T extends string> {
+    prefix: string;
+    private readonly _fields;
+    sep: string;
+    /**
+     * @param prefix  Prefix for the data. Use something unique across your bot.
+     * @param fields  Field names in the order they will be serialized.
+     */
+    constructor(prefix: string, ...fields: T[]);
+    /**
+     * Build a callback data string
+     *
+     * @param obj  Object containing the data
+     */
+    build(obj: Record<T, string>): string;
+    /**
+     * Parse callback data to object
+     *
+     * @param data  Callback data as string
+     * @param safe  If `true`, will return `null` instead of throwing on invalid data
+     */
+    parse(data: string, safe?: false): Record<T, string>;
+    parse(data: string, safe: true): Record<T, string> | null;
+    /**
+     * Create a filter for this callback data.
+     *
+     * You can either pass an object with field names as keys and values as strings or regexes,
+     * which will be compiled to a RegExp, or a function that will be called with the parsed data.
+     * Note that the strings will be passed to `RegExp` **directly**, so you may want to escape them.
+     *
+     * When using a function, you can either return a boolean, or an object with field names as keys
+     * and values as strings or regexes. In the latter case, the resulting object will be matched
+     * against the parsed data the same way as if you passed it directly.
+     *
+     * @param params
+     */
+    filter<Update extends CallbackQuery | InlineCallbackQuery | BusinessCallbackQuery>(params?: ((upd: Update, parsed: Record<T, string>) => MaybePromise<Partial<Record<T, MaybeArray<string | RegExp>>> | boolean>) | Partial<Record<T, MaybeArray<string | RegExp>>>): UpdateFilter<Update, {
+        match: Record<T, string>;
+    }>;
+}

package/callback-data-builder.test.d.cts

@@ -0,0 +1 @@
+export {};

package/context/base.d.cts

@@ -0,0 +1,9 @@
+import { ParsedUpdate } from '@mtcute/core';
+import { TelegramClient } from '@mtcute/core/client.js';
+export type UpdateContext<T> = T & {
+    client: TelegramClient;
+    _name: Extract<ParsedUpdate, {
+        data: T;
+    }>['name'];
+};
+export type UpdateContextDistributed<T> = T extends never ? never : UpdateContext<T>;

package/context/business-message.d.cts

@@ -0,0 +1,60 @@
+import { Message, OmitInputMessageId, ParametersSkip1, Sticker, BusinessMessage } from '@mtcute/core';
+import { TelegramClient } from '@mtcute/core/client.js';
+import { DeleteMessagesParams, ForwardMessageOptions, SendCopyGroupParams, SendCopyParams } from '@mtcute/core/methods.js';
+import { UpdateContext } from './base.js';
+/**
+ * Context of a business message related update.
+ *
+ * This is a subclass of {@link BusinessMessage}, so all fields
+ * of the message are available.
+ *
+ * For message groups, own fields are related to the last message
+ * in the group. To access all messages, use {@link BusinessMessageContext#messages}.
+ */
+export declare class BusinessMessageContext extends BusinessMessage implements UpdateContext<BusinessMessage> {
+    readonly client: TelegramClient;
+    readonly _name: "new_business_message";
+    /**
+     * List of messages in the message group.
+     *
+     * For other updates, this is a list with a single element (`this`).
+     */
+    readonly messages: BusinessMessageContext[];
+    /** Whether this update is about a message group */
+    readonly isMessageGroup: boolean;
+    constructor(client: TelegramClient, message: BusinessMessage | BusinessMessage[]);
+    /** Get all custom emojis contained in this message (message group), if any */
+    getCustomEmojis(): Promise<Sticker[]>;
+    /** Send a text message to the same chat (and topic, if applicable) as a given message */
+    answerText(...params: ParametersSkip1<TelegramClient['answerText']>): Promise<Message>;
+    /** Send a media to the same chat (and topic, if applicable) as a given message */
+    answerMedia(...params: ParametersSkip1<TelegramClient['answerMedia']>): Promise<Message>;
+    /** Send a media group to the same chat (and topic, if applicable) as a given message */
+    answerMediaGroup(...params: ParametersSkip1<TelegramClient['answerMediaGroup']>): Promise<Message[]>;
+    /** Send a text message in reply to this message */
+    replyText(...params: ParametersSkip1<TelegramClient['replyText']>): Promise<Message>;
+    /** Send a media in reply to this message */
+    replyMedia(...params: ParametersSkip1<TelegramClient['replyMedia']>): Promise<Message>;
+    /** Send a media group in reply to this message */
+    replyMediaGroup(...params: ParametersSkip1<TelegramClient['replyMediaGroup']>): Promise<Message[]>;
+    /** Send a text message in reply to this message */
+    quoteWithText(params: Parameters<TelegramClient['quoteWithText']>[1]): Promise<Message>;
+    /** Send a media in reply to this message */
+    quoteWithMedia(params: Parameters<TelegramClient['quoteWithMedia']>[1]): Promise<Message>;
+    /** Send a media group in reply to this message */
+    quoteWithMediaGroup(params: Parameters<TelegramClient['quoteWithMediaGroup']>[1]): Promise<Message[]>;
+    /** Delete this message (message group) */
+    delete(params?: DeleteMessagesParams): Promise<void>;
+    /** Pin this message */
+    pin(params?: OmitInputMessageId<Parameters<TelegramClient['pinMessage']>[0]>): Promise<Message | null>;
+    /** Unpin this message */
+    unpin(): Promise<void>;
+    /** Edit this message */
+    edit(params: OmitInputMessageId<Parameters<TelegramClient['editMessage']>[0]>): Promise<Message>;
+    /** Forward this message (message group) */
+    forwardTo(params: ForwardMessageOptions): Promise<Message[]>;
+    /** Send a copy of this message (message group) */
+    copy(params: SendCopyParams & SendCopyGroupParams): Promise<Message | Message[]>;
+    /** React to this message */
+    react(params: OmitInputMessageId<Parameters<TelegramClient['sendReaction']>[0]>): Promise<Message | null>;
+}

package/context/callback-query.d.cts

@@ -0,0 +1,62 @@
+import { MaybePromise, Message, BusinessCallbackQuery, CallbackQuery, InlineCallbackQuery } from '@mtcute/core';
+import { TelegramClient } from '@mtcute/core/client.js';
+import { UpdateContext } from './base.js';
+/**
+ * Context of a callback query update.
+ *
+ * This is a subclass of {@link CallbackQuery}, so all its fields are also available.
+ */
+export declare class CallbackQueryContext extends CallbackQuery implements UpdateContext<CallbackQuery> {
+    readonly client: TelegramClient;
+    readonly _name: "callback_query";
+    constructor(client: TelegramClient, query: CallbackQuery);
+    /** Answer to this callback query */
+    answer(params: Parameters<TelegramClient['answerCallbackQuery']>[1]): Promise<void>;
+    /**
+     * Get the message containing the callback button being clicked.
+     *
+     * Note that the message may have been deleted, in which case
+     * `null` will be returned.
+     */
+    getMessage(): Promise<Message | null>;
+    /**
+     * Edit the message that contained the callback button that was clicked.
+     */
+    editMessage(params: Omit<Parameters<TelegramClient['editInlineMessage']>[0], 'messageId'>): Promise<Message>;
+    /**
+     * Shortcut for getting the message and editing it.
+     */
+    editMessageWith(handler: (msg: Message) => MaybePromise<Parameters<CallbackQueryContext['editMessage']>[0]>): Promise<Message | undefined>;
+}
+/**
+ * Context of an inline-originated callback query update.
+ *
+ * This is a subclass of {@link InlineCallbackQuery}, so all its fields are also available.
+ */
+export declare class InlineCallbackQueryContext extends InlineCallbackQuery implements UpdateContext<InlineCallbackQuery> {
+    readonly client: TelegramClient;
+    readonly _name: "inline_callback_query";
+    constructor(client: TelegramClient, query: InlineCallbackQuery);
+    /** Answer to this callback query */
+    answer(params: Parameters<TelegramClient['answerCallbackQuery']>[1]): Promise<void>;
+    /**
+     * Edit the message that contained the callback button that was clicked.
+     */
+    editMessage(params: Omit<Parameters<TelegramClient['editInlineMessage']>[0], 'messageId'>): Promise<void>;
+}
+/**
+ * Context of an callback query update originated from a business connection message
+ *
+ * This is a subclass of {@link BusinessCallbackQuery}, so all its fields are also available.
+ */
+export declare class BusinessCallbackQueryContext extends BusinessCallbackQuery implements UpdateContext<BusinessCallbackQuery> {
+    readonly client: TelegramClient;
+    readonly _name: "business_callback_query";
+    constructor(client: TelegramClient, query: BusinessCallbackQuery);
+    /** Answer to this callback query */
+    answer(params: Parameters<TelegramClient['answerCallbackQuery']>[1]): Promise<void>;
+    /**
+     * Edit the message that contained the callback button that was clicked.
+     */
+    editMessage(params: Omit<Parameters<TelegramClient['editInlineMessage']>[0], 'messageId'>): Promise<Message>;
+}

package/context/chat-join-request.d.cts

@@ -0,0 +1,17 @@
+import { TelegramClient } from '@mtcute/core/client.js';
+import { UpdateContext } from './base.js';
+import { BotChatJoinRequestUpdate } from '@mtcute/core';
+/**
+ * Context of a chat join request update (for bots).
+ *
+ * This is a subclass of {@link BotChatJoinRequestUpdate}, so all its fields are also available.
+ */
+export declare class ChatJoinRequestUpdateContext extends BotChatJoinRequestUpdate implements UpdateContext<BotChatJoinRequestUpdate> {
+    readonly client: TelegramClient;
+    readonly _name: "bot_chat_join_request";
+    constructor(client: TelegramClient, update: BotChatJoinRequestUpdate);
+    /** Approve the request */
+    approve(): Promise<void>;
+    /** Decline the request */
+    decline(): Promise<void>;
+}

package/context/chosen-inline-result.d.cts

@@ -0,0 +1,22 @@
+import { TelegramClient } from '@mtcute/core/client.js';
+import { UpdateContext } from './base.js';
+import { ChosenInlineResult } from '@mtcute/core';
+/**
+ * Context of a chosen inline result update.
+ *
+ * This is a subclass of {@link ChosenInlineResult}, so all its fields are also available.
+ *
+ * > **Note**: To receive these updates, you must enable
+ * > Inline feedback in [@BotFather](//t.me/botfather)
+ */
+export declare class ChosenInlineResultContext extends ChosenInlineResult implements UpdateContext<ChosenInlineResult> {
+    readonly client: TelegramClient;
+    readonly _name: "chosen_inline_result";
+    constructor(client: TelegramClient, result: ChosenInlineResult);
+    /**
+     * Edit the message that was sent when this inline result that was chosen.
+     *
+     * > **Note**: This method can only be used if the message contained a reply markup
+     */
+    editMessage(params: Parameters<TelegramClient['editInlineMessage']>[0]): Promise<void>;
+}

package/context/index.d.cts

@@ -0,0 +1,9 @@
+export * from './base.js';
+export * from './business-message.js';
+export * from './callback-query.js';
+export * from './chat-join-request.js';
+export * from './chosen-inline-result.js';
+export * from './inline-query.js';
+export * from './message.js';
+export type { UpdateContextType } from './parse.js';
+export * from './pre-checkout-query.js';

package/context/inline-query.d.cts

@@ -0,0 +1,15 @@
+import { ParametersSkip1, InlineQuery } from '@mtcute/core';
+import { TelegramClient } from '@mtcute/core/client.js';
+import { UpdateContext } from './base.js';
+/**
+ * Context of an inline query update.
+ *
+ * This is a subclass of {@link InlineQuery}, so all its fields are also available.
+ */
+export declare class InlineQueryContext extends InlineQuery implements UpdateContext<InlineQuery> {
+    readonly client: TelegramClient;
+    readonly _name: "inline_query";
+    constructor(client: TelegramClient, query: InlineQuery);
+    /** Answer to this inline query */
+    answer(...params: ParametersSkip1<TelegramClient['answerInlineQuery']>): Promise<void>;
+}

package/context/message.d.cts

@@ -0,0 +1,82 @@
+import { OmitInputMessageId, ParametersSkip1, Peer, Sticker, Message } from '@mtcute/core';
+import { TelegramClient } from '@mtcute/core/client.js';
+import { DeleteMessagesParams, ForwardMessageOptions, SendCopyGroupParams, SendCopyParams } from '@mtcute/core/methods.js';
+import { UpdateContext } from './base.js';
+/**
+ * Context of a message-related update.
+ *
+ * This is a subclass of {@link Message}, so all fields
+ * of the message are available.
+ *
+ * For message groups, own fields are related to the last message
+ * in the group. To access all messages, use {@link MessageContext#messages}.
+ */
+export declare class MessageContext extends Message implements UpdateContext<Message> {
+    readonly client: TelegramClient;
+    readonly _name: "new_message";
+    /**
+     * List of messages in the message group.
+     *
+     * For other updates, this is a list with a single element (`this`).
+     */
+    readonly messages: MessageContext[];
+    /** Whether this update is about a message group */
+    readonly isMessageGroup: boolean;
+    constructor(client: TelegramClient, message: Message | Message[]);
+    /**
+     * Get complete information about {@link sender}
+     *
+     * Learn more: [Incomplete peers](https://mtcute.dev/guide/topics/peers.html#incomplete-peers)
+     */
+    getCompleteSender(): Promise<Peer>;
+    /**
+     * Get complete information about {@link chat}
+     *
+     * Learn more: [Incomplete peers](https://mtcute.dev/guide/topics/peers.html#incomplete-peers)
+     */
+    getCompleteChat(): Promise<Peer>;
+    /** Get a message that this message is a reply to */
+    getReplyTo(): Promise<Message | null>;
+    /** If this is a channel post, get its automatic forward in the discussion group */
+    getDiscussionMessage(): Promise<Message | null>;
+    /** Get all custom emojis contained in this message (message group), if any */
+    getCustomEmojis(): Promise<Sticker[]>;
+    /** Send a text message to the same chat (and topic, if applicable) as a given message */
+    answerText(...params: ParametersSkip1<TelegramClient['answerText']>): Promise<Message>;
+    /** Send a media to the same chat (and topic, if applicable) as a given message */
+    answerMedia(...params: ParametersSkip1<TelegramClient['answerMedia']>): Promise<Message>;
+    /** Send a media group to the same chat (and topic, if applicable) as a given message */
+    answerMediaGroup(...params: ParametersSkip1<TelegramClient['answerMediaGroup']>): Promise<Message[]>;
+    /** Send a text message in reply to this message */
+    replyText(...params: ParametersSkip1<TelegramClient['replyText']>): Promise<Message>;
+    /** Send a media in reply to this message */
+    replyMedia(...params: ParametersSkip1<TelegramClient['replyMedia']>): Promise<Message>;
+    /** Send a media group in reply to this message */
+    replyMediaGroup(...params: ParametersSkip1<TelegramClient['replyMediaGroup']>): Promise<Message[]>;
+    /** Send a text message in reply to this message */
+    quoteWithText(params: Parameters<TelegramClient['quoteWithText']>[1]): Promise<Message>;
+    /** Send a media in reply to this message */
+    quoteWithMedia(params: Parameters<TelegramClient['quoteWithMedia']>[1]): Promise<Message>;
+    /** Send a media group in reply to this message */
+    quoteWithMediaGroup(params: Parameters<TelegramClient['quoteWithMediaGroup']>[1]): Promise<Message[]>;
+    /** Send a text as a comment to this message */
+    commentText(...params: ParametersSkip1<TelegramClient['commentText']>): Promise<Message>;
+    /** Send a media as a comment to this message */
+    commentMedia(...params: ParametersSkip1<TelegramClient['commentMedia']>): Promise<Message>;
+    /** Send a media group as a comment to this message */
+    commentMediaGroup(...params: ParametersSkip1<TelegramClient['commentMediaGroup']>): Promise<Message[]>;
+    /** Delete this message (message group) */
+    delete(params?: DeleteMessagesParams): Promise<void>;
+    /** Pin this message */
+    pin(params?: OmitInputMessageId<Parameters<TelegramClient['pinMessage']>[0]>): Promise<Message | null>;
+    /** Unpin this message */
+    unpin(): Promise<void>;
+    /** Edit this message */
+    edit(params: OmitInputMessageId<Parameters<TelegramClient['editMessage']>[0]>): Promise<Message>;
+    /** Forward this message (message group) */
+    forwardTo(params: ForwardMessageOptions): Promise<Message[]>;
+    /** Send a copy of this message (message group) */
+    copy(params: SendCopyParams & SendCopyGroupParams): Promise<Message> | Promise<Message[]>;
+    /** React to this message */
+    react(params: OmitInputMessageId<Parameters<TelegramClient['sendReaction']>[0]>): Promise<Message | null>;
+}

package/context/parse.d.cts

@@ -0,0 +1,13 @@
+import { BotReactionCountUpdate, BotReactionUpdate, BotStoppedUpdate, BusinessConnection, ChatJoinRequestUpdate, ChatMemberUpdate, DeleteBusinessMessageUpdate, DeleteMessageUpdate, DeleteStoryUpdate, HistoryReadUpdate, ParsedUpdate, PollUpdate, PollVoteUpdate, StoryUpdate, UserStatusUpdate, UserTypingUpdate } from '@mtcute/core';
+import { TelegramClient } from '@mtcute/core/client.js';
+import { UpdateContextDistributed } from './base.js';
+import { BusinessMessageContext } from './business-message.js';
+import { BusinessCallbackQueryContext, CallbackQueryContext, InlineCallbackQueryContext } from './callback-query.js';
+import { ChatJoinRequestUpdateContext } from './chat-join-request.js';
+import { ChosenInlineResultContext } from './chosen-inline-result.js';
+import { InlineQueryContext } from './inline-query.js';
+import { MessageContext } from './message.js';
+import { PreCheckoutQueryContext } from './pre-checkout-query.js';
+export type UpdateContextType = MessageContext | InlineQueryContext | ChosenInlineResultContext | CallbackQueryContext | InlineCallbackQueryContext | BusinessCallbackQueryContext | ChatJoinRequestUpdateContext | PreCheckoutQueryContext | BusinessMessageContext | UpdateContextDistributed<DeleteMessageUpdate | ChatMemberUpdate | PollUpdate | PollVoteUpdate | UserStatusUpdate | UserTypingUpdate | HistoryReadUpdate | BotStoppedUpdate | ChatJoinRequestUpdate | StoryUpdate | DeleteStoryUpdate | BotReactionUpdate | BotReactionCountUpdate | BusinessConnection | DeleteBusinessMessageUpdate>;
+/** @internal */
+export declare function _parsedUpdateToContext(client: TelegramClient, update: ParsedUpdate): UpdateContextType;

package/context/pre-checkout-query.d.cts

@@ -0,0 +1,17 @@
+import { TelegramClient } from '@mtcute/core/client.js';
+import { UpdateContext } from './base.js';
+import { PreCheckoutQuery } from '@mtcute/core';
+/**
+ * Context of a pre-checkout query update
+ *
+ * This is a subclass of {@link PreCheckoutQuery}, so all its fields are also available.
+ */
+export declare class PreCheckoutQueryContext extends PreCheckoutQuery implements UpdateContext<PreCheckoutQuery> {
+    readonly client: TelegramClient;
+    readonly _name: "pre_checkout_query";
+    constructor(client: TelegramClient, query: PreCheckoutQuery);
+    /** Approve the query */
+    approve(): Promise<void>;
+    /** Decline the query, optionally with an error */
+    decline(error?: string): Promise<void>;
+}

package/context/scene-transition.d.cts

@@ -0,0 +1,24 @@
+import { UpdateContextType } from './parse.js';
+import { BusinessMessageContext } from './business-message.js';
+import { CallbackQueryContext, InlineCallbackQueryContext } from './callback-query.js';
+import { MessageContext } from './message.js';
+/** Update which is dispatched whenever scene is entered or exited */
+export declare class SceneTransitionContext {
+    /** Name of the previous scene, if any */
+    readonly previousScene: string | null;
+    /** Update, handler for which triggered the transition */
+    readonly update: UpdateContextType;
+    constructor(
+    /** Name of the previous scene, if any */
+    previousScene: string | null, 
+    /** Update, handler for which triggered the transition */
+    update: UpdateContextType);
+    /** Get {@link update}, asserting it is a message-related update */
+    get message(): MessageContext;
+    /** Get {@link update}, asserting it is a business message-related update */
+    get businessMessage(): BusinessMessageContext;
+    /** Get {@link update}, asserting it is a callback query update */
+    get callbackQuery(): CallbackQueryContext;
+    /** Get {@link update}, asserting it is an inline callback query update */
+    get inlineCallbackQuery(): InlineCallbackQueryContext;
+}