gramio 0.0.10 → 0.0.12

package/README.md

@@ -1,7 +1,7 @@
-# GramIO
-
-Work in progress
-
-Currently support Bot API 7.1
-
-See [Documentation](https://gramio.netlify.app/)
+# GramIO
+
+Work in progress
+
+Currently support Bot API 7.1
+
+See [Documentation](https://gramio.netlify.app/)

package/dist/bot.d.ts

@@ -1,11 +1,65 @@
+import { Context } from "@gramio/contexts";
 import type { APIMethods } from "@gramio/types";
 import "reflect-metadata";
-import { BotOptions } from "./types";
+import { Plugin } from "#plugin";
+import { BotOptions, ErrorDefinitions, Handler, Hooks } from "./types";
 import { Updates } from "./updates";
-export declare class Bot {
+export declare class Bot<Errors extends ErrorDefinitions = {}, Derives = {}> {
     readonly options: BotOptions;
     readonly api: APIMethods;
+    private errorsDefinitions;
+    private errorHandler;
     updates: Updates;
+    private hooks;
     constructor(token: string, options?: Omit<BotOptions, "token">);
+    private runHooks;
+    private runImmutableHooks;
     private _callApi;
+    /**
+     * Register custom class-error for type-safe catch in `onError` hook
+     *
+     * @example
+     * ```ts
+     * export class NoRights extends Error {
+     *     needRole: "admin" | "moderator";
+     *
+     *     constructor(role: "admin" | "moderator") {
+     *         super();
+     *         this.needRole = role;
+     *     }
+     * }
+     *
+     * const bot = new Bot(process.env.TOKEN!)
+     *     .error("NO_RIGHTS", NoRights)
+     *     .onError(({ context, kind, error }) => {
+     *         if (context.is("message") && kind === "NO_RIGHTS")
+     *             return context.send(
+     *                 format`You don't have enough rights! You need to have an «${bold(
+     *                     error.needRole
+     *                 )}» role.`
+     *             );
+     *     });
+     *
+     * bot.updates.on("message", (context) => {
+     *     if (context.text === "bun") throw new NoRights("admin");
+     * });
+     * ```
+     */
+    error<Name extends string, NewError extends {
+        new (...args: any): any;
+        prototype: Error;
+    }>(kind: Name, error: NewError): Bot<Errors & { [name in Name]: InstanceType<NewError>; }, {}>;
+    /**
+     * Set error handler.
+     * @example
+     * ```ts
+     * bot.updates.onError(({ context, kind, error }) => {
+     * 	if(context.is("message")) return context.send(`${kind}: ${error.message}`);
+     * })
+     * ```
+     */
+    onError(handler: Hooks.OnError<Errors>): this;
+    derive<Handler extends (context: Context) => object>(handler: Handler): Bot<Errors, Derives & ReturnType<Handler>>;
+    use(handler: Handler<Context & Derives>): this;
+    extend<NewPlugin extends Plugin>(plugin: NewPlugin): Bot<Errors & NewPlugin["Errors"], Derives & NewPlugin["Derives"]>;
 }

package/dist/bot.js

@@ -13,27 +13,69 @@ const form_data_encoder_1 = require("form-data-encoder");
 const inspectable_1 = require("inspectable");
 require("reflect-metadata");
 const undici_1 = require("undici");
-const TelegramError_1 = require("./TelegramError");
+const errors_1 = require("./errors");
 const updates_1 = require("./updates");
 let Bot = class Bot {
     options = {};
     api = new Proxy({}, {
         get: (_target, method) => (args) => this._callApi(method, args),
     });
-    updates = new updates_1.Updates(this);
+    errorsDefinitions = {
+        TELEGRAM: errors_1.TelegramError,
+    };
+    errorHandler(context, error) {
+        return this.runImmutableHooks("onError", {
+            context,
+            //@ts-expect-error ErrorKind exists if user register error-class with .error("kind", SomeError);
+            kind: error.constructor[errors_1.ErrorKind] ?? "UNKNOWN",
+            error: error,
+        });
+    }
+    updates = new updates_1.Updates(this, this.errorHandler.bind(this));
+    hooks = {
+        preRequest: [
+            (ctx) => {
+                if (!ctx.params)
+                    return ctx;
+                const formattable = format_1.FormattableMap[ctx.method];
+                // @ts-ignore add AnyTelegramMethod to @gramio/format
+                if (formattable)
+                    ctx.params = formattable(ctx.params);
+                return ctx;
+            },
+        ],
+        onError: [],
+    };
     constructor(token, options) {
         this.options = { ...options, token };
     }
+    async runHooks(type, context) {
+        let data = context;
+        for await (const hook of this.hooks[type]) {
+            data = await hook(data);
+        }
+        return data;
+    }
+    async runImmutableHooks(type, context) {
+        for await (const hook of this.hooks[type]) {
+            await hook(context);
+        }
+    }
     async _callApi(method, params = {}) {
         const url = `https://api.telegram.org/bot${this.options.token}/${method}`;
         const reqOptions = {
             method: "POST",
             duplex: "half",
         };
-        const formattable = format_1.FormattableMap[method];
-        // biome-ignore lint/style/noParameterAssign: mutate formattable
-        if (formattable && params)
-            params = formattable(params);
+        const context = await this.runHooks("preRequest", 
+        // TODO: fix type error
+        // @ts-expect-error
+        {
+            method,
+            params,
+        });
+        // biome-ignore lint/style/noParameterAssign: mutate params
+        params = context.params;
         if (params && (0, files_1.isMediaUpload)(method, params)) {
             const formData = await (0, files_1.convertJsonToFormData)(method, params);
             const encoder = new form_data_encoder_1.FormDataEncoder(formData);
@@ -49,9 +91,81 @@ let Bot = class Bot {
         const response = await (0, undici_1.fetch)(url, reqOptions);
         const data = (await response.json());
         if (!data.ok)
-            throw new TelegramError_1.TelegramError(data, method, params);
+            throw new errors_1.TelegramError(data, method, params);
         return data.result;
     }
+    /**
+     * Register custom class-error for type-safe catch in `onError` hook
+     *
+     * @example
+     * ```ts
+     * export class NoRights extends Error {
+     *     needRole: "admin" | "moderator";
+     *
+     *     constructor(role: "admin" | "moderator") {
+     *         super();
+     *         this.needRole = role;
+     *     }
+     * }
+     *
+     * const bot = new Bot(process.env.TOKEN!)
+     *     .error("NO_RIGHTS", NoRights)
+     *     .onError(({ context, kind, error }) => {
+     *         if (context.is("message") && kind === "NO_RIGHTS")
+     *             return context.send(
+     *                 format`You don't have enough rights! You need to have an «${bold(
+     *                     error.needRole
+     *                 )}» role.`
+     *             );
+     *     });
+     *
+     * bot.updates.on("message", (context) => {
+     *     if (context.text === "bun") throw new NoRights("admin");
+     * });
+     * ```
+     */
+    error(kind, error) {
+        //@ts-expect-error Set ErrorKind
+        error[errors_1.ErrorKind] = kind;
+        this.errorsDefinitions[kind] = error;
+        return this;
+    }
+    /**
+     * Set error handler.
+     * @example
+     * ```ts
+     * bot.updates.onError(({ context, kind, error }) => {
+     * 	if(context.is("message")) return context.send(`${kind}: ${error.message}`);
+     * })
+     * ```
+     */
+    onError(handler) {
+        this.hooks.onError.push(handler);
+        return this;
+    }
+    derive(handler) {
+        this.updates.use((context, next) => {
+            for (const [key, value] of Object.entries(handler(context))) {
+                context[key] = value;
+            }
+            next();
+        });
+        return this;
+    }
+    use(handler) {
+        this.updates.use(handler);
+        return this;
+    }
+    extend(plugin) {
+        for (const [key, value] of Object.entries(plugin.errorsDefinitions)) {
+            if (this.errorsDefinitions[key])
+                this.errorsDefinitions[key] = value;
+        }
+        for (const derive of plugin.derives) {
+            this.derive(derive);
+        }
+        return this;
+    }
 };
 exports.Bot = Bot;
 exports.Bot = Bot = __decorate([

package/dist/{TelegramError.d.ts → errors.d.ts}

@@ -1,4 +1,5 @@
 import { APIMethodParams, APIMethods, TelegramAPIResponseError, TelegramResponseParameters } from "@gramio/types";
+export declare const ErrorKind: unique symbol;
 export declare class TelegramError<T extends keyof APIMethods> extends Error {
     method: T;
     params: APIMethodParams<T>;

package/dist/{TelegramError.js → errors.js}

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.TelegramError = void 0;
+exports.TelegramError = exports.ErrorKind = void 0;
+exports.ErrorKind = Symbol("ErrorKind");
 class TelegramError extends Error {
     method;
     params;
@@ -17,3 +18,5 @@ class TelegramError extends Error {
     }
 }
 exports.TelegramError = TelegramError;
+//@ts-expect-error
+TelegramError.constructor[exports.ErrorKind] = "TELEGRAM";

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 export * from "./bot";
-export * from "./TelegramError";
+export * from "./errors";
 export * from "./types";
+export * from "./plugin";
 export * from "@gramio/contexts";
 export * from "@gramio/files";
 export * from "@gramio/keyboards";

package/dist/index.js

@@ -15,8 +15,9 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./bot"), exports);
-__exportStar(require("./TelegramError"), exports);
+__exportStar(require("./errors"), exports);
 __exportStar(require("./types"), exports);
+__exportStar(require("./plugin"), exports);
 __exportStar(require("@gramio/contexts"), exports);
 __exportStar(require("@gramio/files"), exports);
 __exportStar(require("@gramio/keyboards"), exports);

package/dist/plugin.d.ts

@@ -0,0 +1,21 @@
+import { Context } from "@gramio/contexts";
+import { ErrorDefinitions } from "types";
+export declare class Plugin<Errors extends ErrorDefinitions = {}, Derives = {}> {
+    Errors: Errors;
+    Derives: Derives;
+    derives: ((context: Context) => object)[];
+    name: string;
+    errorsDefinitions: Record<string, {
+        new (...args: any): any;
+        prototype: Error;
+    }>;
+    constructor(name: string);
+    /**
+     * Register custom class-error in plugin
+     **/
+    error<Name extends string, NewError extends {
+        new (...args: any): any;
+        prototype: Error;
+    }>(kind: Name, error: NewError): Plugin<Errors & { [name in Name]: InstanceType<NewError>; }, {}>;
+    derive<Handler extends (context: Context) => object>(handler: Handler): Plugin<Errors, Derives & ReturnType<Handler>>;
+}

package/dist/plugin.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Plugin = void 0;
+const _errors_1 = require("#errors");
+class Plugin {
+    // TODO: fix that dump error. https://www.typescriptlang.org/play?#code/KYDwDg9gTgLgBDAnmYcCiUrQCLAGYCWAdgTAREQM5wC8cASsAMbQAmAPAFACQlMUxAOYAaHhixROAPgDcnTqEiw4TADYBDStQAKqgK6Di7cdGqgYwIq2omouQiTIVqdAN4BfKXFc8i6gLbAAFxwfAJEgnI8wJim9sSk5FQhjCxQHDy8-EKi3NyucETAAO5wABQAdFXqUIKUIepEiACUDU0ycGBYMBBIKCG2cO48Xm7uUdwsVPx6TD1QZX6BIWFCzd6ZMAAWBJQVS6h0B3LcwzwA9ABUlzxwlwzAhnwxKnp8EP4qGloAtDEScGInX0hiIt2u52isSgXDyADkAqhzJZrKFshFctw4SVBsirNQCkVSpVqrV6nBGi02ogOl1er1kMF0NChrkpGUANbEVghBGBYRwf7QXk46HrHx5c7nAACMEof3AzBgfxZAGVgPBbABpbmZIVQADa2u5AF1aHAuVYTtxNjs9vrKPFHElKAbLawzXR9RNuFANXooEQEHaKdQ9EQOUQIMUg5o4LoDEZMtxbNQAGTeOAGg6AoN84AmkIASWmjSYwAAKoz2NjirYvMM8rIeMMzgpwNB4GpNNQAEK9YzQswgCz45kSJ2JZzmjxeHzybh4ji1hOgwUjlE6EFGSlSdmZMDbogi4qr4i5VpwFdH9ej1FnojsYh4F4P1NeAD8cH7MEHEnT8ZHu+cAhNsuwbHkfowAGQZgdQcaUicrbyO2Shdt81BwhA9AEIIWxyrem7jtAEFFMArD0BAqhMgAROorD+MQNFwAAPnANH+BArAxOo8w0RMUxhLM8xlFg1EhHRDFMax7GcdxUC8dANHipklB6CgCzNNacH7MA5GUdR5picASGcGcgnwBYfDmkSgGJkQZQ0TAykVPqjlwgA8gA+vQRYAOIABIVqqNEClhOF4XKWnyBZcAAEa9DZJTfr0ZTNDwrkblYZRWTAzRAA
+    Errors;
+    Derives;
+    derives = [];
+    name;
+    errorsDefinitions = {};
+    constructor(name) {
+        this.name = name;
+    }
+    /**
+     * Register custom class-error in plugin
+     **/
+    error(kind, error) {
+        //@ts-expect-error Set ErrorKind
+        error[_errors_1.ErrorKind] = kind;
+        this.errorsDefinitions[kind] = error;
+        return this;
+    }
+    derive(handler) {
+        this.derives.push(handler);
+        return this;
+    }
+}
+exports.Plugin = Plugin;

package/dist/types.d.ts

@@ -1,12 +1,12 @@
 import { Context } from "@gramio/contexts";
-import { APIMethods } from "@gramio/types";
+import { APIMethodParams, APIMethods } from "@gramio/types";
 import { NextMiddleware } from "middleware-io";
-import { TelegramError } from "./TelegramError";
+import { TelegramError } from "./errors";
 export interface BotOptions {
     token?: string;
 }
 export type Handler<T> = (context: T, next: NextMiddleware) => unknown;
-interface ErrorHandlerParams<Kind extends string, Err extends Error> {
+interface ErrorHandlerParams<Kind extends string, Err> {
     context: Context;
     kind: Kind;
     error: Err;
@@ -14,5 +14,24 @@ interface ErrorHandlerParams<Kind extends string, Err extends Error> {
 type AnyTelegramError = {
     [APIMethod in keyof APIMethods]: TelegramError<APIMethod>;
 }[keyof APIMethods];
-export type ErrorHandler = (options: ErrorHandlerParams<"TELEGRAM", AnyTelegramError> | ErrorHandlerParams<"UNKNOWN", Error>) => unknown;
+type AnyTelegramMethod = {
+    [APIMethod in keyof APIMethods]: {
+        method: APIMethod;
+        params: APIMethodParams<APIMethod>;
+    };
+}[keyof APIMethods];
+type MaybePromise<T> = T | Promise<T>;
+export declare namespace Hooks {
+    type PreRequestContext = AnyTelegramMethod;
+    type PreRequest = (ctx: PreRequestContext) => MaybePromise<PreRequestContext>;
+    type OnErrorContext<T extends ErrorDefinitions> = ErrorHandlerParams<"TELEGRAM", AnyTelegramError> | ErrorHandlerParams<"UNKNOWN", Error> | {
+        [K in keyof T]: ErrorHandlerParams<K & string, T[K & string]>;
+    }[keyof T];
+    type OnError<T extends ErrorDefinitions> = (options: OnErrorContext<T>) => unknown;
+    interface Store<T extends ErrorDefinitions> {
+        preRequest: PreRequest[];
+        onError: OnError<T>[];
+    }
+}
+export type ErrorDefinitions = Record<string, Error>;
 export {};

package/dist/updates.d.ts

@@ -1,19 +1,19 @@
 import { Context, UpdateName, contextsMappings } from "@gramio/contexts";
 import type { TelegramUpdate } from "@gramio/types";
+import { CaughtMiddlewareHandler } from "middleware-io";
 import type { Bot } from "./bot";
-import { ErrorHandler, Handler } from "./types";
+import { Handler } from "./types";
 export declare class Updates {
     private readonly bot;
     private isStarted;
     private offset;
     private composer;
-    private errorHandler;
-    constructor(bot: Bot);
+    private onError;
+    constructor(bot: Bot<any, any>, onError: CaughtMiddlewareHandler<Context>);
     on<T extends UpdateName>(updateName: T, handler: Handler<InstanceType<(typeof contextsMappings)[T]>>): this;
-    use(handler: Handler<Context>): this;
+    use(handler: Handler<Context & any>): this;
     handleUpdate(data: TelegramUpdate): Promise<void>;
     startPolling(): Promise<void>;
     startFetchLoop(): Promise<void>;
     stopPolling(): void;
-    onError(handler: ErrorHandler): void;
 }

package/dist/updates.js

@@ -3,15 +3,15 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.Updates = void 0;
 const contexts_1 = require("@gramio/contexts");
 const middleware_io_1 = require("middleware-io");
-const _TelegramError_1 = require("#TelegramError");
 class Updates {
     bot;
     isStarted = false;
     offset = 0;
     composer = middleware_io_1.Composer.builder();
-    errorHandler;
-    constructor(bot) {
+    onError;
+    constructor(bot, onError) {
         this.bot = bot;
+        this.onError = onError;
     }
     on(updateName, handler) {
         return this.use(async (context, next) => {
@@ -23,21 +23,7 @@ class Updates {
         });
     }
     use(handler) {
-        this.composer
-            .caught((ctx, error) => {
-            if (error instanceof _TelegramError_1.TelegramError)
-                return this.errorHandler?.({
-                    context: ctx,
-                    kind: "TELEGRAM",
-                    error: error,
-                });
-            this.errorHandler?.({
-                context: ctx,
-                kind: "UNKNOWN",
-                error: error,
-            });
-        })
-            .use(handler);
+        this.composer.caught(this.onError).use(handler);
         return this;
     }
     async handleUpdate(data) {
@@ -99,8 +85,5 @@ class Updates {
     stopPolling() {
         this.isStarted = false;
     }
-    onError(handler) {
-        this.errorHandler = handler;
-    }
 }
 exports.Updates = Updates;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "gramio",
-    "version": "0.0.10",
+    "version": "0.0.12",
     "description": "WIP",
     "main": "./dist/index.js",
     "types": "./dist/index.d.ts",
@@ -14,13 +14,14 @@
     "license": "ISC",
     "devDependencies": {
         "@biomejs/biome": "1.5.3",
-        "@gramio/types": "^7.1.1",
-        "@types/node": "^20.11.19"
+        "@gramio/types": "^7.1.2",
+        "@types/node": "^20.11.19",
+        "typescript": "^5.3.3"
     },
     "dependencies": {
         "@gramio/contexts": "^0.0.2",
         "@gramio/files": "^0.0.3",
-        "@gramio/format": "^0.0.7",
+        "@gramio/format": "^0.0.8",
         "@gramio/keyboards": "^0.1.6",
         "form-data-encoder": "^4.0.2",
         "inspectable": "^2.1.0",