gramio 0.0.31 → 0.0.35

package/README.md

@@ -1,7 +1,46 @@
 # GramIO
 
-Work in progress.
+<div align="center">
 
-Currently support Bot API 7.3
+[![Bot API](https://img.shields.io/badge/Bot%20API-7.3-blue?logo=telegram&style=flat&labelColor=000&color=3b82f6)](https://core.telegram.org/bots/api)
+[![npm](https://img.shields.io/npm/v/gramio?logo=npm&style=flat&labelColor=000&color=3b82f6)](https://www.npmjs.org/package/@gramio/core)
+[![JSR](https://jsr.io/badges/@gramio/core)](https://jsr.io/@gramio/core)
+[![JSR Score](https://jsr.io/badges/@gramio/core/score)](https://jsr.io/@gramio/core)
 
-See [Documentation](https://gramio.netlify.app/)
+</div>
+
+TypeScript/JavaScript Telegram Bot API Framework for create your bots with convenience!
+
+✨ **Extensible** - Our plugin and hook system is awesome
+
+🛡️ **Type-safe** - Written in TypeScript with love ❤️
+
+🌐 **Multi-runtime** - Works on [Node.js](https://nodejs.org/), [Bun](https://bun.sh/) and [Deno](https://deno.com/)\*
+
+⚙️ **Code-generated** - Many parts are code-generated (for example, [code-generated and auto-published Telegram Bot API types](https://github.com/gramiojs/types))
+
+**Deno\*** [windows-specific issue with undici](https://github.com/denoland/deno/issues/19532)
+
+## [Get started](https://gramio.dev/get-started)
+
+To create your new bot, you just need to write it to the console:
+
+```bash [npm]
+npm create gramio ./bot
+```
+
+and GramIO customize your project the way you want it!
+
+### Example
+
+```typescript
+import { Bot } from "gramio";
+
+const bot = new Bot()
+    .command("start", (context) => context.send("Hello!"))
+    .onStart(({ info }) => console.log(`✨ Bot ${info.username} was started!`));
+
+bot.start();
+```
+
+For more, please see [documentation](https://gramio.dev).

package/dist/bot.d.ts

@@ -1,25 +1,71 @@
 import { CallbackData } from "@gramio/callback-data";
 import { type Attachment, type Context, type ContextType, type MaybeArray, type UpdateName } from "@gramio/contexts";
 import type { APIMethodParams, APIMethods, SetMyCommandsParams, TelegramBotCommand, TelegramReactionTypeEmojiEmoji, TelegramUser } from "@gramio/types";
-import { Plugin } from "./plugin";
-import type { BotOptions, DeriveDefinitions, ErrorDefinitions, Handler, Hooks, MaybePromise, SuppressedAPIMethods } from "./types";
+import type { AnyBot, AnyPlugin, BotOptions, DeriveDefinitions, ErrorDefinitions, Handler, Hooks, MaybePromise, SuppressedAPIMethods } from "./types";
 import { Updates } from "./updates";
+/** Bot instance
+ *
+ * @example
+ * ```ts
+ * import { Bot } from "gramio";
+ *
+ * const bot = new Bot("") // put you token here
+ *     .command("start", (context) => context.send("Hi!"))
+ *     .onStart(console.log);
+ *
+ * bot.start();
+ * ```
+ */
 export declare class Bot<Errors extends ErrorDefinitions = {}, Derives extends DeriveDefinitions = DeriveDefinitions> {
-    /** @internal */
+    /** @internal. Remap generic */
     __Derives: Derives;
+    /** Options provided to instance */
     readonly options: BotOptions;
+    /** Bot data (filled in when calling bot.init/bot.start) */
     info: TelegramUser | undefined;
+    /**
+     * Send API Request to Telegram Bot API
+     *
+     * @example
+     * ```ts
+     * const response = await bot.api.sendMessage({
+     *     chat_id: "@gramio_forum",
+     *     text: "some text",
+     * });
+     * ```
+     *
+     * [Documentation](https://gramio.dev/bot-api.html)
+     */
     readonly api: SuppressedAPIMethods;
     private lazyloadPlugins;
     private dependencies;
     private errorsDefinitions;
     private errorHandler;
+    /** This instance handle updates */
     updates: Updates;
     private hooks;
+    /** Create new Bot instance */
     constructor(token: string, options?: Omit<BotOptions, "token">);
     private runHooks;
     private runImmutableHooks;
     private _callApi;
+    /**
+     * Download file
+     *
+     * @example
+     * ```ts
+     * bot.on("message", async (context) => {
+     *     if (!context.document) return;
+     *     // download to ./file-name
+     *     await context.download(context.document.fileName || "file-name");
+     *     // get ArrayBuffer
+     *     const buffer = await context.download();
+     *
+     *     return context.send("Thank you!");
+     * });
+     * ```
+     * [Documentation](https://gramio.dev/files/download.html)
+     */
     downloadFile(attachment: Attachment | {
         file_id: string;
     } | string): Promise<ArrayBuffer>;
@@ -71,30 +117,214 @@ export declare class Bot<Errors extends ErrorDefinitions = {}, Derives extends D
      */
     onError<T extends UpdateName>(updateName: MaybeArray<T>, handler: Hooks.OnError<Errors, ContextType<typeof this, T> & Derives["global"] & Derives[T]>): this;
     onError(handler: Hooks.OnError<Errors, Context<typeof this> & Derives["global"]>): this;
+    /**
+     * Derive some data to handlers
+     *
+     * @example
+     * ```ts
+     * new Bot("token").derive((context) => {
+     * 		return {
+     * 			superSend: () => context.send("Derived method")
+     * 		}
+     * })
+     * ```
+     */
     derive<Handler extends Hooks.Derive<Context<typeof this>>>(handler: Handler): Bot<Errors, Derives & {
         global: Awaited<ReturnType<Handler>>;
     }>;
     derive<Update extends UpdateName, Handler extends Hooks.Derive<ContextType<typeof this, Update>>>(updateName: MaybeArray<Update>, handler: Handler): Bot<Errors, Derives & {
         [K in Update]: Awaited<ReturnType<Handler>>;
     }>;
+    /**
+     * This hook called when the bot is `started`.
+     *
+     * @example
+     * ```typescript
+     * import { Bot } from "gramio";
+     *
+     * const bot = new Bot(process.env.TOKEN!).onStart(
+     *     ({ plugins, info, updatesFrom }) => {
+     *         console.log(`plugin list - ${plugins.join(", ")}`);
+     *         console.log(`bot username is @${info.username}`);
+     * 		   console.log(`updates from ${updatesFrom}`);
+     *     }
+     * );
+     *
+     * bot.start();
+     * ```
+     *
+     * [Documentation](https://gramio.dev/hooks/on-start.html)
+     *  */
     onStart(handler: Hooks.OnStart): this;
+    /**
+     * This hook called when the bot stops.
+     *
+     * @example
+     * ```typescript
+     * import { Bot } from "gramio";
+     *
+     * const bot = new Bot(process.env.TOKEN!).onStop(
+     *     ({ plugins, info, updatesFrom }) => {
+     *         console.log(`plugin list - ${plugins.join(", ")}`);
+     *         console.log(`bot username is @${info.username}`);
+     *     }
+     * );
+     *
+     * bot.start();
+     * bot.stop();
+     * ```
+     *
+     * [Documentation](https://gramio.dev/hooks/on-stop.html)
+     *  */
     onStop(handler: Hooks.OnStop): this;
+    /**
+     * This hook called before sending a request to Telegram Bot API (allows us to impact the sent parameters).
+     *
+     * @example
+     * ```typescript
+     * import { Bot } from "gramio";
+     *
+     * const bot = new Bot(process.env.TOKEN!).preRequest((context) => {
+     *     if (context.method === "sendMessage") {
+     *         context.params.text = "mutate params";
+     *     }
+     *
+     *     return context;
+     * });
+     *
+     * bot.start();
+     * ```
+     *
+     * [Documentation](https://gramio.dev/hooks/pre-request.html)
+     *  */
     preRequest<Methods extends keyof APIMethods, Handler extends Hooks.PreRequest<Methods>>(methods: MaybeArray<Methods>, handler: Handler): this;
     preRequest(handler: Hooks.PreRequest): this;
+    /**
+     * This hook called when API return successful response
+     *
+     * [Documentation](https://gramio.dev/hooks/on-response.html)
+     * */
     onResponse<Methods extends keyof APIMethods, Handler extends Hooks.OnResponse<Methods>>(methods: MaybeArray<Methods>, handler: Handler): this;
     onResponse(handler: Hooks.OnResponse): this;
+    /**
+     * This hook called when API return an error
+     *
+     * [Documentation](https://gramio.dev/hooks/on-response-error.html)
+     * */
     onResponseError<Methods extends keyof APIMethods, Handler extends Hooks.OnResponseError<Methods>>(methods: MaybeArray<Methods>, handler: Handler): this;
     onResponseError(handler: Hooks.OnResponseError): this;
+    /** Register handler to one or many Updates */
     on<T extends UpdateName>(updateName: MaybeArray<T>, handler: Handler<ContextType<typeof this, T> & Derives["global"] & Derives[T]>): this;
+    /** Register handler to any Updates */
     use(handler: Handler<Context<typeof this> & Derives["global"]>): this;
-    extend<NewPlugin extends Plugin<any, any>>(plugin: MaybePromise<NewPlugin>): Bot<Errors & NewPlugin["Errors"], Derives & NewPlugin["Derives"]>;
+    /**
+     * Extend {@link Plugin} logic and types
+     *
+     * @example
+     * ```ts
+     * import { Plugin, Bot } from "gramio";
+     *
+     * export class PluginError extends Error {
+     *     wow: "type" | "safe" = "type";
+     * }
+     *
+     * const plugin = new Plugin("gramio-example")
+     *     .error("PLUGIN", PluginError)
+     *     .derive(() => {
+     *         return {
+     *             some: ["derived", "props"] as const,
+     *         };
+     *     });
+     *
+     * const bot = new Bot(process.env.TOKEN!)
+     *     .extend(plugin)
+     *     .onError(({ context, kind, error }) => {
+     *         if (context.is("message") && kind === "PLUGIN") {
+     *             console.log(error.wow);
+     *         }
+     *     })
+     *     .use((context) => {
+     *         console.log(context.some);
+     *     });
+     * ```
+     */
+    extend<NewPlugin extends AnyPlugin>(plugin: MaybePromise<NewPlugin>): Bot<Errors & NewPlugin["_"]["Errors"], Derives & NewPlugin["_"]["Derives"]>;
+    /**
+     * Register handler to reaction (`message_reaction` update)
+     *
+     * @example
+     * ```ts
+     * new Bot().reaction("👍", async (context) => {
+     *     await context.reply(`Thank you!`);
+     * });
+     * ```
+     * */
     reaction(trigger: MaybeArray<TelegramReactionTypeEmojiEmoji>, handler: (context: ContextType<typeof this, "message_reaction"> & Derives["global"] & Derives["message_reaction"]) => unknown): this;
+    /**
+     * Register handler to `callback_query` event
+     *
+     * @example
+     * ```ts
+     * const someData = new CallbackData("example").number("id");
+     *
+     * new Bot()
+     *     .command("start", (context) =>
+     *         context.send("some", {
+     *             reply_markup: new InlineKeyboard().text(
+     *                 "example",
+     *                 someData.pack({
+     *                     id: 1,
+     *                 })
+     *             ),
+     *         })
+     *     )
+     *     .callbackQuery(someData, (context) => {
+     *         context.queryData; // is type-safe
+     *     });
+     * ```
+     */
     callbackQuery<Trigger extends CallbackData | string | RegExp>(trigger: Trigger, handler: (context: Omit<ContextType<typeof this, "callback_query">, "data"> & Derives["global"] & Derives["callback_query"] & {
         queryData: Trigger extends CallbackData ? ReturnType<Trigger["unpack"]> : RegExpMatchArray | null;
     }) => unknown): this;
+    /** Register handler to `chosen_inline_result` update */
     chosenInlineResult<Ctx = ContextType<typeof this, "chosen_inline_result"> & Derives["global"] & Derives["chosen_inline_result"]>(trigger: RegExp | string | ((context: Ctx) => boolean), handler: (context: Ctx & {
         args: RegExpMatchArray | null;
     }) => unknown): this;
+    /**
+     * Register handler to `inline_query` update
+     *
+     * @example
+     * ```ts
+     * new Bot().inlineQuery(
+     *     /regular expression with (.*)/i,
+     *     async (context) => {
+     *         if (context.args) {
+     *             await context.answer(
+     *                 [
+     *                     InlineQueryResult.article(
+     *                         "id-1",
+     *                         context.args[1],
+     *                         InputMessageContent.text("some"),
+     *                         {
+     *                             reply_markup: new InlineKeyboard().text(
+     *                                 "some",
+     *                                 "callback-data"
+     *                             ),
+     *                         }
+     *                     ),
+     *                 ],
+     *                 {
+     *                     cache_time: 0,
+     *                 }
+     *             );
+     *         }
+     *     },
+     *     {
+     *         onResult: (context) => context.editText("Message edited!"),
+     *     }
+     * );
+     * ```
+     * */
     inlineQuery<Ctx = ContextType<typeof this, "inline_query"> & Derives["global"] & Derives["inline_query"]>(trigger: RegExp | string | ((context: Ctx) => boolean), handler: (context: Ctx & {
         args: RegExpMatchArray | null;
     }) => unknown, options?: {
@@ -102,20 +332,54 @@ export declare class Bot<Errors extends ErrorDefinitions = {}, Derives extends D
             args: RegExpMatchArray | null;
         }) => unknown;
     }): this;
+    /**
+     * Register handler to `message` and `business_message` event
+     *
+     * new Bot().hears(/regular expression with (.*)/i, async (context) => {
+     *     if (context.args) await context.send(`Params ${context.args[1]}`);
+     * });
+     */
     hears<Ctx = ContextType<typeof this, "message"> & Derives["global"] & Derives["message"]>(trigger: RegExp | string | ((context: Ctx) => boolean), handler: (context: Ctx & {
         args: RegExpMatchArray | null;
     }) => unknown): this;
+    /**
+     * Register handler to `message` and `business_message` event when entities contains a command
+     *
+     * new Bot().command("start", async (context) => {
+     *     return context.send(`You message is /start ${context.args}`);
+     * });
+     */
     command(command: string, handler: (context: ContextType<typeof this, "message"> & Derives["global"] & Derives["message"] & {
         args: string | null;
     }) => unknown, options?: Omit<SetMyCommandsParams, "commands"> & Omit<TelegramBotCommand, "command">): this;
     /** Currently not isolated!!! */
-    group(grouped: (bot: typeof this) => Bot<any, any>): typeof this;
+    group(grouped: (bot: typeof this) => AnyBot): typeof this;
+    /**
+     * Init bot. Call it manually only if you doesn't use {@link Bot.start}
+     */
     init(): Promise<void>;
+    /**
+     * Start receive updates via long-polling or webhook
+     *
+     * @example
+     * ```ts
+     * import { Bot } from "gramio";
+     *
+     * const bot = new Bot("") // put you token here
+     *     .command("start", (context) => context.send("Hi!"))
+     *     .onStart(console.log);
+     *
+     * bot.start();
+     * ```
+     */
     start({ webhook, dropPendingUpdates, allowedUpdates, }?: {
         webhook?: Omit<APIMethodParams<"setWebhook">, "drop_pending_updates" | "allowed_updates">;
         dropPendingUpdates?: boolean;
         allowedUpdates?: NonNullable<APIMethodParams<"getUpdates">>["allowed_updates"];
     }): Promise<TelegramUser | undefined>;
-    /** Currently does not implement graceful shutdown */
+    /**
+     * Stops receiving events via long-polling or webhook
+     * Currently does not implement graceful shutdown
+     * */
     stop(): Promise<void>;
 }