@gramio/prompt/dist/index.d.cts

Prompt plugin for GramIO

import * as gramio from 'gramio';
import { ContextType, BotLike, FormattableString, Optional, SendMessageParams, MaybePromise, Plugin } from 'gramio';

declare class PromptCancelError extends Error {
    readonly type: "timeout" | "cancel";
    constructor(type: "timeout" | "cancel");
}

declare const events: readonly ["message", "edited_message", "channel_post", "edited_channel_post", "callback_query"];

type TimeoutStrategy = "on-answer" | "on-timer";
interface PromptOptions<GlobalData = never> {
    map?: PromptsType<GlobalData>;
    defaults?: PromptFunctionParams<EventsUnion, GlobalData>;
    /**
     * Strategy for handling timeouts
     * - "on-answer": Checks timeout expiration when user responds. If answer arrives after timeout, throws error
     * - "on-timer": Uses setTimeout to reject automatically when timeout expires, regardless of user response timing
     *
     * @default "on-answer"
     */
    timeoutStrategy?: TimeoutStrategy;
}
type Stringable = string | FormattableString;
type PromptsType<Data = never> = Map<number, PromptData<EventsUnion, Data>>;
type EventsUnion = (typeof events)[number];
type IsNever<T> = [T] extends [never] ? true : false;
interface PromptPluginTypes<GlobalData = never> {
    /**
     * @example
     * ```ts
     * import { Bot, format, bold } from "gramio";
     * import { prompt } from "@gramio/prompt";
     *
     * const bot = new Bot(process.env.token!)
     *     .extend(prompt())
     *     .command("start", async (context) => {
     *         const answer = await context.prompt(
     *             "message",
     *             format`What's your ${bold`name`}?`
     *         );
     *
     *         return context.send(`✨ Your name is ${answer.text}`);
     *     })
     *     .onStart(console.log);
     *
     * bot.start();
     * ```
     */
    prompt: PromptFunction<GlobalData>;
    /**
     * Wait for the next event from the user
     *
     * @example
     * ```ts
     * .command("start", async (context) => {
     *         const answer = await context.wait();
     *
     *         return context.send(`✨ Next message after /start command is ${answer.text}`);
     * })
     * ```
     *  */
    wait: WaitFunction<GlobalData>;
    /**
     * Wait for the next event from the user
     *
     * @example
     * ```ts
     * .command("start", async (context) => {
     *         const [answer, message] = await context.waitWithAction("message", () => context.send("ok"));
     *
     *         return context.send(`✨ Next message after /start command is ${answer.text}`);
     * })
     * ```
     *  */
    waitWithAction: WaitWithActionFunction<GlobalData>;
}
type PromptAnswer<Event extends EventsUnion, Data = never> = IsNever<Data> extends true ? ContextType<BotLike, Event> & PromptPluginTypes : Data;
type ValidateFunction<Event extends EventsUnion> = (context: PromptAnswer<Event, never>) => MaybePromise<boolean>;
type TransformFunction<Event extends EventsUnion, Data> = (context: PromptAnswer<Event, never>) => MaybePromise<Data>;
type OnValidateErrorFunction<Event extends EventsUnion, Data, ActionReturn = never> = (context: PromptAnswer<Event>, ...data: IsNever<ActionReturn> extends true ? [] : [actionReturn: ActionReturn]) => any;
interface PromptData<Event extends EventsUnion, Data = never, ActionReturn = any> {
    resolve: (context: PromptAnswer<Event, Data>) => void;
    reject: (reason?: any) => void;
    timeoutExpiresAt?: number;
    timeoutId?: number;
    events?: Event[];
    validate?: ValidateFunction<Event>;
    onValidateError?: string | OnValidateErrorFunction<Event, Data, ActionReturn>;
    actionReturn?: ActionReturn;
    transform?: TransformFunction<Event, Data>;
    sendParams?: Optional<SendMessageParams, "chat_id" | "text">;
    text?: string;
}
interface PromptFunctionParams<Event extends EventsUnion, Data, ActionReturn = never> extends Optional<SendMessageParams, "chat_id" | "text"> {
    validate?: ValidateFunction<Event>;
    transform?: TransformFunction<Event, Data>;
    onValidateError?: OnValidateErrorFunction<Event, Data, ActionReturn> | (string & {});
    timeout?: number;
}
interface PromptFunction<GlobalData = never> {
    /** Send message and wait answer */
    <Data = GlobalData>(text: Stringable, params?: PromptFunctionParams<EventsUnion, Data>): Promise<PromptAnswer<EventsUnion, Data>>;
    /** Send message and wait answer ignoring events not listed */
    <const Event extends EventsUnion, Data = GlobalData>(event: MaybeArray<Event>, text: Stringable, params?: PromptFunctionParams<Event, Data>): Promise<PromptAnswer<Event, Data>>;
}
interface WaitFunction<GlobalData = never> {
    /** Wait for the next event from the user */
    <Data = GlobalData>(): Promise<PromptAnswer<EventsUnion, Data>>;
    /** Wait for the next event from the user ignoring events not listed */
    <const Event extends EventsUnion, Data = GlobalData>(event: MaybeArray<Event>): Promise<PromptAnswer<Event, Data>>;
    /** Wait for the next event from the user ignoring non validated answers */
    <Data = GlobalData>(validate: ValidateFunction<EventsUnion>): Promise<PromptAnswer<EventsUnion, Data>>;
    /** Wait for the next event from the user ignoring non validated answers and not listed events with transformer */
    <const Event extends EventsUnion, Data = GlobalData>(event: MaybeArray<Event>, options: {
        validate?: ValidateFunction<Event>;
        transform?: TransformFunction<Event, Data>;
    }): Promise<PromptAnswer<Event, Data>>;
    /** Wait for the next event from the user ignoring non validated answers and not listed events */
    <const Event extends EventsUnion, Data = GlobalData>(event: MaybeArray<Event>, validate: ValidateFunction<Event>): Promise<PromptAnswer<Event, Data>>;
}
interface WaitWithActionFunction<GlobalData = never> {
    <const Event extends EventsUnion, Data = GlobalData, ActionReturn = any>(event: MaybeArray<Event>, action: () => MaybePromise<ActionReturn>, validateOrOptions?: ValidateFunction<Event> | {
        validate?: ValidateFunction<Event>;
        transform?: TransformFunction<Event, Data>;
        onValidateError?: string | OnValidateErrorFunction<Event, Data, ActionReturn>;
    }): Promise<[PromptAnswer<Event, Data>, ActionReturn]>;
}
type MaybeArray<T> = T | T[];

/**
 * Prompt plugin
 * @example
 * ```ts
 * import { Bot, format, bold } from "gramio";
 * import { prompt } from "@gramio/prompt";
 *
 * const bot = new Bot(process.env.token!)
 *     .extend(prompt())
 *     .command("start", async (context) => {
 *         const answer = await context.prompt(
 *             "message",
 *             format`What's your ${bold`name`}?`
 *         );
 *
 *         return context.send(`✨ Your name is ${answer.text}`);
 *     })
 *     .onStart(console.log);
 *
 * bot.start();
 * ```
 */
declare function prompt<GlobalData = never>(options?: PromptOptions<GlobalData>): Plugin<{
    "prompt-cancel": PromptCancelError;
}, gramio.DeriveDefinitions & {
    [K in EventsUnion]: PromptPluginTypes<GlobalData>;
}>;

export { type EventsUnion, type MaybeArray, type OnValidateErrorFunction, type PromptAnswer, type PromptFunction, type PromptFunctionParams, type PromptOptions, type PromptPluginTypes, type PromptsType, type Stringable, type TimeoutStrategy, type TransformFunction, type ValidateFunction, type WaitFunction, type WaitWithActionFunction, prompt };