@yaebal/core 0.0.1

package/lib/format.js

@@ -0,0 +1,57 @@
+/** a piece of text that carries its own entities, used inside `format`. */
+export class Stringable {
+    text;
+    entities;
+    constructor(text, entities = []) {
+        this.text = text;
+        this.entities = entities;
+    }
+}
+function isFormatResult(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        "text" in value &&
+        "entities" in value &&
+        Array.isArray(value.entities));
+}
+/** stitches the literal parts and interpolations into one `{ text, entities }`. */
+export function format(strings, ...subs) {
+    let text = "";
+    const entities = [];
+    for (let i = 0; i < strings.length; i++) {
+        text += strings[i] ?? "";
+        if (i < subs.length) {
+            const sub = subs[i];
+            const offset = text.length;
+            if (isFormatResult(sub)) {
+                text += sub.text;
+                for (const entity of sub.entities) {
+                    entities.push({ ...entity, offset: entity.offset + offset });
+                }
+            }
+            else {
+                text += String(sub);
+            }
+        }
+    }
+    return { text, entities };
+}
+function wrap(type, extra = {}) {
+    return (value) => new Stringable(value, [{ type, offset: 0, length: value.length, ...extra }]);
+}
+export const bold = wrap("bold");
+export const italic = wrap("italic");
+export const underline = wrap("underline");
+export const strikethrough = wrap("strikethrough");
+export const spoiler = wrap("spoiler");
+export const code = wrap("code");
+export const pre = wrap("pre");
+export function link(text, url) {
+    return new Stringable(text, [{ type: "text_link", offset: 0, length: text.length, url }]);
+}
+export function mention(text, user) {
+    return new Stringable(text, [
+        { type: "text_mention", offset: 0, length: text.length, user: user },
+    ]);
+}
+//# sourceMappingURL=format.js.map

package/lib/format.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.js","sourceRoot":"","sources":["../src/format.ts"],"names":[],"mappings":"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"}

package/lib/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @yaebal/core — core of Yet Another tElegram Bot Api Library.
+ *
+ * public surface: the `Bot`, the standalone `Composer`, the `Context`,
+ * the entity-based `format` helpers, the low-level `Api`, and the telegram types.
+ */
+export { Bot, type BotOptions } from "./bot.js";
+export { Composer, compose, matchQuery, type Filter, type FilterQuery, type Filtered, type Middleware, type NextFn, type Plugin, } from "./composer.js";
+export { Context, type ContextOptions } from "./context.js";
+export { media, isMediaSource, type MediaSource } from "./media.js";
+export { webhookCallback, nodeWebhookCallback, type UpdateSink, type WebhookOptions, } from "./webhook.js";
+export { createApi, TelegramError, type Api, type ApiOptions, type FileReader, type BeforeHook, type AfterHook, type ErrorHook, type ErrorAction, } from "./api.js";
+export { format, Stringable, bold, italic, underline, strikethrough, spoiler, code, pre, link, mention, type FormatResult, } from "./format.js";
+export type * from "./telegram-types.js";
+//# sourceMappingURL=index.d.ts.map

package/lib/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,GAAG,EAAE,KAAK,UAAU,EAAE,MAAM,UAAU,CAAC;AAChD,OAAO,EACN,QAAQ,EACR,OAAO,EACP,UAAU,EACV,KAAK,MAAM,EACX,KAAK,WAAW,EAChB,KAAK,QAAQ,EACb,KAAK,UAAU,EACf,KAAK,MAAM,EACX,KAAK,MAAM,GACX,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,OAAO,EAAE,KAAK,cAAc,EAAE,MAAM,cAAc,CAAC;AAC5D,OAAO,EAAE,KAAK,EAAE,aAAa,EAAE,KAAK,WAAW,EAAE,MAAM,YAAY,CAAC;AACpE,OAAO,EACN,eAAe,EACf,mBAAmB,EACnB,KAAK,UAAU,EACf,KAAK,cAAc,GACnB,MAAM,cAAc,CAAC;AACtB,OAAO,EACN,SAAS,EACT,aAAa,EACb,KAAK,GAAG,EACR,KAAK,UAAU,EACf,KAAK,UAAU,EACf,KAAK,UAAU,EACf,KAAK,SAAS,EACd,KAAK,SAAS,EACd,KAAK,WAAW,GAChB,MAAM,UAAU,CAAC;AAClB,OAAO,EACN,MAAM,EACN,UAAU,EACV,IAAI,EACJ,MAAM,EACN,SAAS,EACT,aAAa,EACb,OAAO,EACP,IAAI,EACJ,GAAG,EACH,IAAI,EACJ,OAAO,EACP,KAAK,YAAY,GACjB,MAAM,aAAa,CAAC;AACrB,mBAAmB,qBAAqB,CAAC"}

package/lib/index.js

@@ -0,0 +1,14 @@
+/**
+ * @yaebal/core — core of Yet Another tElegram Bot Api Library.
+ *
+ * public surface: the `Bot`, the standalone `Composer`, the `Context`,
+ * the entity-based `format` helpers, the low-level `Api`, and the telegram types.
+ */
+export { Bot } from "./bot.js";
+export { Composer, compose, matchQuery, } from "./composer.js";
+export { Context } from "./context.js";
+export { media, isMediaSource } from "./media.js";
+export { webhookCallback, nodeWebhookCallback, } from "./webhook.js";
+export { createApi, TelegramError, } from "./api.js";
+export { format, Stringable, bold, italic, underline, strikethrough, spoiler, code, pre, link, mention, } from "./format.js";
+//# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,GAAG,EAAmB,MAAM,UAAU,CAAC;AAChD,OAAO,EACN,QAAQ,EACR,OAAO,EACP,UAAU,GAOV,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,OAAO,EAAuB,MAAM,cAAc,CAAC;AAC5D,OAAO,EAAE,KAAK,EAAE,aAAa,EAAoB,MAAM,YAAY,CAAC;AACpE,OAAO,EACN,eAAe,EACf,mBAAmB,GAGnB,MAAM,cAAc,CAAC;AACtB,OAAO,EACN,SAAS,EACT,aAAa,GAQb,MAAM,UAAU,CAAC;AAClB,OAAO,EACN,MAAM,EACN,UAAU,EACV,IAAI,EACJ,MAAM,EACN,SAAS,EACT,aAAa,EACb,OAAO,EACP,IAAI,EACJ,GAAG,EACH,IAAI,EACJ,OAAO,GAEP,MAAM,aAAa,CAAC"}

package/lib/media.d.ts

@@ -0,0 +1,27 @@
+declare const MEDIA: unique symbol;
+export type MediaSource = {
+    readonly [MEDIA]: true;
+} & ({
+    kind: "path";
+    path: string;
+} | {
+    kind: "url";
+    url: string;
+} | {
+    kind: "buffer";
+    buffer: Uint8Array;
+    filename?: string;
+} | {
+    kind: "fileId";
+    fileId: string;
+});
+/** build a {@link MediaSource}. `media.path("./a.jpg")`, `media.url(...)`, etc. */
+export declare const media: {
+    path: (path: string) => MediaSource;
+    url: (url: string) => MediaSource;
+    buffer: (buffer: Uint8Array, filename?: string) => MediaSource;
+    fileId: (fileId: string) => MediaSource;
+};
+export declare function isMediaSource(x: unknown): x is MediaSource;
+export {};
+//# sourceMappingURL=media.d.ts.map

package/lib/media.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"media.d.ts","sourceRoot":"","sources":["../src/media.ts"],"names":[],"mappings":"AAIA,QAAA,MAAM,KAAK,EAAE,OAAO,MAAmC,CAAC;AAExD,MAAM,MAAM,WAAW,GAAG;IAAE,QAAQ,CAAC,CAAC,KAAK,CAAC,EAAE,IAAI,CAAA;CAAE,GAAG,CACpD;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC9B;IAAE,IAAI,EAAE,KAAK,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAC5B;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,GACzD;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CACpC,CAAC;AAEF,mFAAmF;AACnF,eAAO,MAAM,KAAK;iBACJ,MAAM,KAAG,WAAW;eACtB,MAAM,KAAG,WAAW;qBACd,UAAU,aAAa,MAAM,KAAG,WAAW;qBAM3C,MAAM,KAAG,WAAW;CACrC,CAAC;AAEF,wBAAgB,aAAa,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,IAAI,WAAW,CAE1D"}

package/lib/media.js

@@ -0,0 +1,20 @@
+// media abstraction (the puregram idea): a uniform way to point at a file —
+// local path, URL, in-memory buffer, or an already-uploaded telegram file_id.
+// the api layer turns each into the right wire form (multipart vs plain string).
+const MEDIA = Symbol.for("yaebal.media");
+/** build a {@link MediaSource}. `media.path("./a.jpg")`, `media.url(...)`, etc. */
+export const media = {
+    path: (path) => ({ [MEDIA]: true, kind: "path", path }),
+    url: (url) => ({ [MEDIA]: true, kind: "url", url }),
+    buffer: (buffer, filename) => ({
+        [MEDIA]: true,
+        kind: "buffer",
+        filename,
+        buffer,
+    }),
+    fileId: (fileId) => ({ [MEDIA]: true, kind: "fileId", fileId }),
+};
+export function isMediaSource(x) {
+    return typeof x === "object" && x !== null && MEDIA in x;
+}
+//# sourceMappingURL=media.js.map

package/lib/media.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"media.js","sourceRoot":"","sources":["../src/media.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAC5E,8EAA8E;AAC9E,iFAAiF;AAEjF,MAAM,KAAK,GAAkB,MAAM,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;AASxD,mFAAmF;AACnF,MAAM,CAAC,MAAM,KAAK,GAAG;IACpB,IAAI,EAAE,CAAC,IAAY,EAAe,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;IAC5E,GAAG,EAAE,CAAC,GAAW,EAAe,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC;IACxE,MAAM,EAAE,CAAC,MAAkB,EAAE,QAAiB,EAAe,EAAE,CAAC,CAAC;QAChE,CAAC,KAAK,CAAC,EAAE,IAAI;QACb,IAAI,EAAE,QAAQ;QACd,QAAQ;QACR,MAAM;KACN,CAAC;IACF,MAAM,EAAE,CAAC,MAAc,EAAe,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpF,CAAC;AAEF,MAAM,UAAU,aAAa,CAAC,CAAU;IACvC,OAAO,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,IAAI,IAAI,KAAK,IAAI,CAAC,CAAC;AAC1D,CAAC"}

package/lib/telegram-types.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Telegram Bot API types — re-exported from the code-generated `@yaebal/types`,
+ * the single source of truth (generated from the official schema on every API
+ * release). core only keeps the API-response envelope and the `UpdateName`
+ * helper, which aren't part of the object schema.
+ */
+import type { Update } from "@yaebal/types";
+export type { User, Chat, MessageEntity, Message, CallbackQuery, Update } from "@yaebal/types";
+/** the keys of `Update` that carry a payload (everything except `update_id`). */
+export type UpdateName = Exclude<keyof Update, "update_id" | symbol | number>;
+export interface ApiResponseOk<T> {
+    ok: true;
+    result: T;
+}
+export interface ApiResponseError {
+    ok: false;
+    error_code: number;
+    description: string;
+}
+export type ApiResponse<T> = ApiResponseOk<T> | ApiResponseError;
+//# sourceMappingURL=telegram-types.d.ts.map

package/lib/telegram-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"telegram-types.d.ts","sourceRoot":"","sources":["../src/telegram-types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAE5C,YAAY,EAAE,IAAI,EAAE,IAAI,EAAE,aAAa,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAE/F,iFAAiF;AACjF,MAAM,MAAM,UAAU,GAAG,OAAO,CAAC,MAAM,MAAM,EAAE,WAAW,GAAG,MAAM,GAAG,MAAM,CAAC,CAAC;AAE9E,MAAM,WAAW,aAAa,CAAC,CAAC;IAC/B,EAAE,EAAE,IAAI,CAAC;IACT,MAAM,EAAE,CAAC,CAAC;CACV;AAED,MAAM,WAAW,gBAAgB;IAChC,EAAE,EAAE,KAAK,CAAC;IACV,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,MAAM,WAAW,CAAC,CAAC,IAAI,aAAa,CAAC,CAAC,CAAC,GAAG,gBAAgB,CAAC"}

package/lib/telegram-types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=telegram-types.js.map

package/lib/telegram-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"telegram-types.js","sourceRoot":"","sources":["../src/telegram-types.ts"],"names":[],"mappings":""}

package/lib/webhook.d.ts

@@ -0,0 +1,18 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { Update } from "./telegram-types.js";
+/** anything that can take a single update — i.e. a `Bot`. */
+export interface UpdateSink {
+    handleUpdate(update: Update): Promise<void>;
+}
+export interface WebhookOptions {
+    /** if set, require telegram's `X-Telegram-Bot-Api-Secret-Token` header to match. */
+    secretToken?: string;
+}
+/**
+ * a fetch-style webhook handler — `(Request) => Response`. works on bun, deno,
+ * cloudflare workers, and any runtime with the fetch globals.
+ */
+export declare function webhookCallback(bot: UpdateSink, options?: WebhookOptions): (request: Request) => Promise<Response>;
+/** a node `http` webhook handler — `http.createServer(nodeWebhookCallback(bot))`. */
+export declare function nodeWebhookCallback(bot: UpdateSink, options?: WebhookOptions): (req: IncomingMessage, res: ServerResponse) => void;
+//# sourceMappingURL=webhook.d.ts.map

package/lib/webhook.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhook.d.ts","sourceRoot":"","sources":["../src/webhook.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AACjE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAiBlD,6DAA6D;AAC7D,MAAM,WAAW,UAAU;IAC1B,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5C;AAED,MAAM,WAAW,cAAc;IAC9B,oFAAoF;IACpF,WAAW,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAC9B,GAAG,EAAE,UAAU,EACf,OAAO,GAAE,cAAmB,GAC1B,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CAyBzC;AAED,qFAAqF;AACrF,wBAAgB,mBAAmB,CAClC,GAAG,EAAE,UAAU,EACf,OAAO,GAAE,cAAmB,GAC1B,CAAC,GAAG,EAAE,eAAe,EAAE,GAAG,EAAE,cAAc,KAAK,IAAI,CAkDrD"}

package/lib/webhook.js

@@ -0,0 +1,82 @@
+/** telegram updates are tiny; reject anything wildly larger to avoid memory abuse. */
+const MAX_BODY = 1 << 20; // 1 MiB
+/**
+ * constant-time string compare so the secret-token check can't be timed.
+ * pure js (no node:crypto / Buffer) so it runs on node, bun, deno and edge/web.
+ */
+function safeEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    let diff = 0;
+    for (let i = 0; i < a.length; i++)
+        diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+    return diff === 0;
+}
+/**
+ * a fetch-style webhook handler — `(Request) => Response`. works on bun, deno,
+ * cloudflare workers, and any runtime with the fetch globals.
+ */
+export function webhookCallback(bot, options = {}) {
+    return async (request) => {
+        if (request.method !== "POST")
+            return new Response("method not allowed", { status: 405 });
+        if (options.secretToken &&
+            !safeEqual(request.headers.get("x-telegram-bot-api-secret-token") ?? "", options.secretToken)) {
+            return new Response("unauthorized", { status: 401 });
+        }
+        if (Number(request.headers.get("content-length") ?? 0) > MAX_BODY) {
+            return new Response("payload too large", { status: 413 });
+        }
+        let update;
+        try {
+            update = (await request.json());
+        }
+        catch {
+            return new Response("bad request", { status: 400 });
+        }
+        await bot.handleUpdate(update);
+        return new Response("ok");
+    };
+}
+/** a node `http` webhook handler — `http.createServer(nodeWebhookCallback(bot))`. */
+export function nodeWebhookCallback(bot, options = {}) {
+    return (req, res) => {
+        if (req.method !== "POST") {
+            res.statusCode = 405;
+            res.end();
+            return;
+        }
+        const got = req.headers["x-telegram-bot-api-secret-token"];
+        if (options.secretToken &&
+            !safeEqual(typeof got === "string" ? got : "", options.secretToken)) {
+            res.statusCode = 401;
+            res.end();
+            return;
+        }
+        const chunks = [];
+        let size = 0;
+        req.on("data", (c) => {
+            size += c.length;
+            if (size > MAX_BODY) {
+                res.statusCode = 413;
+                res.end();
+                req.destroy();
+                return;
+            }
+            chunks.push(c);
+        });
+        req.on("end", async () => {
+            try {
+                const update = JSON.parse(Buffer.concat(chunks).toString("utf8"));
+                await bot.handleUpdate(update);
+                res.statusCode = 200;
+                res.end("ok");
+            }
+            catch {
+                res.statusCode = 400;
+                res.end();
+            }
+        });
+    };
+}
+//# sourceMappingURL=webhook.js.map

package/lib/webhook.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhook.js","sourceRoot":"","sources":["../src/webhook.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@yaebal/core",
+  "version": "0.0.1",
+  "description": "yaebal core — type-safe, chainable Telegram Bot API framework.",
+  "type": "module",
+  "main": "./lib/index.js",
+  "types": "./lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "import": "./lib/index.js"
+    }
+  },
+  "files": [
+    "lib",
+    "src"
+  ],
+  "dependencies": {
+    "@yaebal/types": "0.0.1"
+  },
+  "devDependencies": {
+    "@types/node": "latest"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "telegram",
+    "telegram-bot",
+    "bot-api",
+    "framework",
+    "typescript",
+    "yaebal"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/neverlane/yaebal",
+    "directory": "packages/core"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "node --test lib"
+  }
+}

package/src/api.ts

@@ -0,0 +1,276 @@
+import { type MediaSource, isMediaSource } from "./media.js";
+import type { ApiResponse, Message, Update, User } from "./telegram-types.js";
+
+/**
+ * resolve a local `media.path()` into bytes. runtime-specific (node:fs, Bun.file,
+ * Deno.readFile), so it's injected rather than imported — that keeps `@yaebal/core`
+ * free of any `node:` import and loadable on edge/web. the `yaebal` package wires an
+ * auto-detecting default; absent ⇒ `media.path()` throws (e.g. on Cloudflare Workers).
+ */
+export type FileReader = (path: string) => Promise<Uint8Array>;
+
+/** thrown when telegram replies with `ok: false`. */
+export class TelegramError extends Error {
+	readonly method: string;
+	readonly code: number;
+
+	constructor(method: string, code: number, description: string) {
+		super(`[${method}] ${code}: ${description}`);
+
+		this.name = "TelegramError";
+		this.method = method;
+		this.code = code;
+	}
+}
+
+/** inspect/rewrite params before a request. return new params to replace them. */
+export type BeforeHook = (
+	method: string,
+	params: Record<string, unknown> | undefined,
+) => Record<string, unknown> | undefined | Promise<Record<string, unknown> | undefined>;
+
+/** inspect/rewrite the result after a successful request. return a value to replace it. */
+export type AfterHook = (method: string, result: unknown) => unknown | Promise<unknown>;
+
+/** what an error hook can ask the client to do. */
+export interface ErrorAction {
+	/** re-run the same call. */
+	retry?: boolean;
+	/** wait this many ms before retrying. */
+	delayMs?: number;
+}
+
+/** runs when a request throws. `attempt` is the (1-based) attempt that just failed. */
+export type ErrorHook = (
+	method: string,
+	error: unknown,
+	attempt: number,
+) => ErrorAction | undefined | Promise<ErrorAction | undefined>;
+
+/**
+ * the API client. known methods are typed; everything else goes through `call`
+ * (the puregram passthrough — a new Bot API method works before its types ship).
+ * `before` / `after` / `onError` are the extension points plugins hang off of.
+ */
+export interface Api {
+	call<T = unknown>(method: string, params?: Record<string, unknown>): Promise<T>;
+	getMe(): Promise<User>;
+	getUpdates(params?: Record<string, unknown>): Promise<Update[]>;
+	sendMessage(params: Record<string, unknown>): Promise<Message>;
+	answerCallbackQuery(params: Record<string, unknown>): Promise<boolean>;
+	/** build the download URL for a `file_path` from `getFile`. contains the bot token — don't log it. */
+	fileUrl(filePath: string): string;
+	/** register a hook that runs before every request; may rewrite params. */
+	before(hook: BeforeHook): Api;
+	/** register a hook that runs after every successful request; may rewrite the result. */
+	after(hook: AfterHook): Api;
+	/** register a hook that runs when a request throws; may request a retry. */
+	onError(hook: ErrorHook): Api;
+}
+
+export interface ApiOptions {
+	apiRoot?: string;
+	/** resolve `media.path()` to bytes. injected per runtime; absent ⇒ path media throws (e.g. edge). */
+	readFile?: FileReader;
+}
+
+interface EncodedRequest {
+	body: string | FormData | undefined;
+	contentType?: string;
+}
+
+function containsMedia(v: unknown): boolean {
+	if (isMediaSource(v)) return true;
+	if (Array.isArray(v)) return v.some(containsMedia);
+	if (v !== null && typeof v === "object") return Object.values(v).some(containsMedia);
+
+	return false;
+}
+
+/** basename without node:path — keeps core free of node: imports. */
+const baseName = (p: string): string => p.split(/[\\/]/).pop() || "file";
+const toArrayBuffer = (bytes: Uint8Array): ArrayBuffer => {
+	const copy = new Uint8Array(bytes.byteLength);
+	copy.set(bytes);
+
+	return copy.buffer;
+};
+
+async function mediaToBlob(
+	m: MediaSource,
+	readFile?: FileReader,
+): Promise<{ blob: Blob; filename: string }> {
+	if (m.kind === "path") {
+		if (!readFile)
+			throw new Error(
+				"media.path() needs a filesystem — use the `yaebal` package (auto-detects node/bun/deno), " +
+				"pass `readFile` to the Bot, or send media.buffer()/url() instead (e.g. on edge).",
+			);
+
+		const bytes = await readFile(m.path);
+		return { blob: new Blob([toArrayBuffer(bytes)]), filename: baseName(m.path) };
+	}
+
+	if (m.kind === "buffer") {
+		return { blob: new Blob([toArrayBuffer(m.buffer)]), filename: m.filename ?? "file" };
+	}
+
+	throw new Error(`mediaToBlob: ${m.kind} is not an uploadable source`);
+}
+
+/**
+ * encode request params. Plain params (and `url`/`fileId` media) go as JSON;
+ * if any `path`/`buffer` media is present the whole request becomes multipart,
+ * with each upload attached via `attach://`. exported for testing.
+ */
+export async function encodeRequest(
+	params: Record<string, unknown> | undefined,
+	readFile?: FileReader,
+): Promise<EncodedRequest> {
+	if (!params) return { body: undefined, contentType: "application/json" };
+
+	// ponytail: media is only handled at the top level. media nested inside arrays
+	// or objects (e.g. sendMediaGroup's `media[]`) would serialize to garbage, so
+	// fail loud until that method is actually supported.
+	if (Object.values(params).some((v) => !isMediaSource(v) && containsMedia(v))) {
+		throw new Error(
+			"encodeRequest: nested MediaSource (e.g. inside sendMediaGroup) is not supported yet — pass media as a top-level param",
+		);
+	}
+
+	const needsUpload = Object.values(params).some(
+		(v) => isMediaSource(v) && (v.kind === "path" || v.kind === "buffer"),
+	);
+
+	if (!needsUpload) {
+		const inlined: Record<string, unknown> = {};
+
+		for (const [k, v] of Object.entries(params)) {
+			inlined[k] = isMediaSource(v)
+				? v.kind === "url"
+					? v.url
+					: (v as { fileId: string }).fileId
+				: v;
+		}
+
+		return { body: JSON.stringify(inlined), contentType: "application/json" };
+	}
+
+	const form = new FormData();
+	let n = 0;
+
+	for (const [k, v] of Object.entries(params)) {
+		if (v === undefined || v === null) continue;
+
+		if (isMediaSource(v)) {
+			if (v.kind === "fileId") form.set(k, v.fileId);
+			else if (v.kind === "url") form.set(k, v.url);
+			else {
+				const field = `_file${n++}`;
+				const { blob, filename } = await mediaToBlob(v, readFile);
+
+				form.set(field, blob, filename);
+				form.set(k, `attach://${field}`);
+			}
+		} else if (typeof v === "string") {
+			form.set(k, v);
+		} else {
+			form.set(k, JSON.stringify(v));
+		}
+	}
+
+	return { body: form };
+}
+
+/** builds a callable API client with before/after/error hooks. */
+export function createApi(token: string, options: ApiOptions = {}): Api {
+	const apiRoot = options.apiRoot ?? "https://api.telegram.org";
+	const beforeHooks: BeforeHook[] = [];
+	const afterHooks: AfterHook[] = [];
+	const errorHooks: ErrorHook[] = [];
+
+	const rawCall = async <T>(method: string, params?: Record<string, unknown>): Promise<T> => {
+		const { body, contentType } = await encodeRequest(params, options.readFile);
+		const res = await fetch(`${apiRoot}/bot${token}/${method}`, {
+			method: "POST",
+			// for multipart, let fetch set the content-type (with its boundary).
+			headers: contentType ? { "content-type": contentType } : undefined,
+			body,
+		});
+
+		const data = (await res.json()) as ApiResponse<T>;
+		if (!data.ok) throw new TelegramError(method, data.error_code, data.description);
+
+		return data.result;
+	};
+
+	const call = async <T = unknown>(
+		method: string,
+		params?: Record<string, unknown>,
+	): Promise<T> => {
+		let p = params;
+		for (const hook of beforeHooks) {
+			const next = await hook(method, p);
+			if (next !== undefined) p = next;
+		}
+
+		// ponytail: retry loop is bounded by the error hooks themselves (e.g. again caps
+		// attempts). with no hook requesting a retry it throws on the first failure.
+		for (let attempt = 1; ; attempt++) {
+			try {
+				let result = await rawCall<T>(method, p);
+
+				for (const hook of afterHooks) {
+					const next = await hook(method, result);
+					if (next !== undefined) result = next as Awaited<T>;
+				}
+
+				return result;
+			} catch (error) {
+				let retry: ErrorAction | undefined;
+
+				for (const hook of errorHooks) {
+					const action = await hook(method, error, attempt);
+					if (action?.retry) {
+						retry = action;
+						break;
+					}
+				}
+
+				if (!retry) throw error;
+				if (retry.delayMs) await new Promise((r) => setTimeout(r, retry.delayMs));
+			}
+		}
+	};
+
+	const registrar: Record<string, unknown> = {
+		call,
+		fileUrl: (filePath: string) => `${apiRoot}/file/bot${token}/${filePath}`,
+		before(hook: BeforeHook) {
+			beforeHooks.push(hook);
+			return api;
+		},
+		after(hook: AfterHook) {
+			afterHooks.push(hook);
+			return api;
+		},
+		onError(hook: ErrorHook) {
+			errorHooks.push(hook);
+			return api;
+		},
+	};
+
+	const api = new Proxy(registrar, {
+		get(obj, prop: string) {
+			if (prop in obj) return obj[prop];
+
+			// lazily materialise `api.<method>(params)` → call(method, params).
+			const method = (params?: Record<string, unknown>) => call(prop, params);
+			
+			obj[prop] = method;
+			return method;
+		},
+	}) as unknown as Api;
+
+	return api;
+}