@prajwalshete/telegram-plugin 0.0.0-stage → 0.1.0

package/dist/telegram/update.js

@@ -0,0 +1,129 @@
+import { z } from "zod";
+// src/telegram/update.ts
+/** Bot API `User` (loose: unknown keys pass through). */
+const TgUser = z.looseObject({
+	id: z.number().int(),
+	is_bot: z.boolean(),
+	first_name: z.string(),
+	last_name: z.string().optional(),
+	username: z.string().optional(),
+	language_code: z.string().optional()
+});
+/** Bot API `Chat` (loose). */
+const TgChat = z.looseObject({
+	id: z.number().int(),
+	/** `private` | `group` | `supergroup` | `channel` (open for future types). */
+	type: z.string(),
+	title: z.string().optional(),
+	username: z.string().optional(),
+	first_name: z.string().optional(),
+	last_name: z.string().optional(),
+	is_forum: z.boolean().optional()
+});
+/** Bot API `MessageEntity` (offsets/lengths in UTF-16 code units). */
+const TgMessageEntity = z.looseObject({
+	type: z.string(),
+	offset: z.number().int(),
+	length: z.number().int(),
+	url: z.string().optional(),
+	user: TgUser.optional(),
+	language: z.string().optional(),
+	custom_emoji_id: z.string().optional()
+});
+/** Bot API `PhotoSize` (one size of a photo). */
+const TgPhotoSize = z.looseObject({
+	file_id: z.string(),
+	file_unique_id: z.string(),
+	width: z.number().int(),
+	height: z.number().int(),
+	file_size: z.number().int().optional()
+});
+/** Bot API `Document` (`file_size` in bytes). */
+const TgDocument = z.looseObject({
+	file_id: z.string(),
+	file_unique_id: z.string(),
+	file_name: z.string().optional(),
+	mime_type: z.string().optional(),
+	file_size: z.number().int().optional()
+});
+/** Bot API `ForumTopicCreated` service message. */
+const TgForumTopicCreated = z.looseObject({
+	name: z.string(),
+	icon_color: z.number().int().optional(),
+	icon_custom_emoji_id: z.string().optional()
+});
+/** Message (also used for MaybeInaccessibleMessage: `date: 0` means the bot can no longer read it). */
+const TgMessage = z.looseObject({
+	message_id: z.number().int(),
+	/** Unix seconds. */
+	date: z.number().int(),
+	chat: TgChat,
+	from: TgUser.optional(),
+	sender_chat: TgChat.optional(),
+	message_thread_id: z.number().int().optional(),
+	is_topic_message: z.boolean().optional(),
+	text: z.string().optional(),
+	entities: z.array(TgMessageEntity).optional(),
+	caption: z.string().optional(),
+	caption_entities: z.array(TgMessageEntity).optional(),
+	photo: z.array(TgPhotoSize).optional(),
+	document: TgDocument.optional(),
+	/** Only the fields a reply check needs; the nested message is not parsed further. */
+	reply_to_message: z.looseObject({
+		message_id: z.number().int(),
+		from: TgUser.optional()
+	}).optional(),
+	migrate_to_chat_id: z.number().int().optional(),
+	migrate_from_chat_id: z.number().int().optional(),
+	new_chat_members: z.array(TgUser).optional(),
+	left_chat_member: TgUser.optional(),
+	group_chat_created: z.literal(true).optional(),
+	supergroup_chat_created: z.literal(true).optional(),
+	forum_topic_created: TgForumTopicCreated.optional()
+});
+/** Bot API `CallbackQuery` (an inline button tap; `data` ≤ 64 bytes). */
+const TgCallbackQuery = z.looseObject({
+	id: z.string(),
+	from: TgUser,
+	chat_instance: z.string(),
+	message: TgMessage.optional(),
+	inline_message_id: z.string().optional(),
+	data: z.string().optional()
+});
+/** `creator` | `administrator` | `member` | `restricted` | `left` | `kicked`. */
+const TgChatMember = z.looseObject({
+	status: z.string(),
+	user: TgUser
+});
+/** Bot API `ChatMemberUpdated` (`my_chat_member` / `chat_member`); `date` is Unix seconds. */
+const TgChatMemberUpdated = z.looseObject({
+	chat: TgChat,
+	from: TgUser,
+	date: z.number().int(),
+	old_chat_member: TgChatMember,
+	new_chat_member: TgChatMember
+});
+/** Bot API `Update`, only the update types the plugin handles (others parse but are ignored). */
+const TgUpdate = z.looseObject({
+	update_id: z.number().int(),
+	message: TgMessage.optional(),
+	edited_message: TgMessage.optional(),
+	callback_query: TgCallbackQuery.optional(),
+	my_chat_member: TgChatMemberUpdated.optional(),
+	chat_member: TgChatMemberUpdated.optional()
+});
+/** Validates an inbound webhook / getUpdates body. Never throws; `issues` hold paths only (no message text). */
+function parseUpdate(input) {
+	const r = TgUpdate.safeParse(input);
+	if (r.success) return {
+		ok: true,
+		update: r.data
+	};
+	const raw = typeof input === "object" && input !== null ? input.update_id : void 0;
+	return {
+		ok: false,
+		updateId: typeof raw === "number" && Number.isInteger(raw) ? raw : null,
+		issues: r.error.issues.map((i) => `${i.path.join(".") || "(root)"}: ${i.code}`)
+	};
+}
+export { TgCallbackQuery, TgChat, TgChatMember, TgChatMemberUpdated, TgDocument, TgForumTopicCreated, TgMessage, TgMessageEntity, TgPhotoSize, TgUpdate, TgUser, parseUpdate };

package/dist/testing/fake-html.d.ts

@@ -0,0 +1,9 @@
+/** Result of {@link checkTelegramHtml}. */
+export interface HtmlCheck {
+  /** Plain text after entity parsing (what Telegram counts and returns). */
+  text: string;
+  /** Telegram-style error description, or null when valid. */
+  error: string | null;
+}
+/** Validates HTML the way Telegram's `parse_mode: HTML` does (allowed tags, nesting, entities); returns its visible text. */
+export declare function checkTelegramHtml(html: string): HtmlCheck;

package/dist/testing/fake-html.js

@@ -0,0 +1,83 @@
+// src/testing/fake-html.ts
+const ALLOWED = /* @__PURE__ */ new Set([
+	"b",
+	"strong",
+	"i",
+	"em",
+	"u",
+	"ins",
+	"s",
+	"strike",
+	"del",
+	"span",
+	"tg-spoiler",
+	"a",
+	"code",
+	"pre",
+	"blockquote",
+	"tg-emoji",
+	"tg-time"
+]);
+const NAMED = /* @__PURE__ */ new Map([
+	["lt", "<"],
+	["gt", ">"],
+	["amp", "&"],
+	["quot", "\""]
+]);
+const TOKEN_RE = /<(\/?)([A-Za-z][A-Za-z0-9-]*)([^<>]*)>|<|&(#x[0-9A-Fa-f]+|#[0-9]+|[A-Za-z]+);/g;
+function byteOffset(s, index) {
+	return new TextEncoder().encode(s.slice(0, index)).length;
+}
+/** Validates HTML the way Telegram's `parse_mode: HTML` does (allowed tags, nesting, entities); returns its visible text. */
+function checkTelegramHtml(html) {
+	const stack = [];
+	let text = "";
+	let last = 0;
+	for (const m of html.matchAll(TOKEN_RE)) {
+		const idx = m.index;
+		text += html.slice(last, idx);
+		last = idx + m[0].length;
+		const [whole, closing, rawTag, , entity] = m;
+		if (entity !== void 0) {
+			if (entity.startsWith("#")) {
+				const code = entity.startsWith("#x") ? Number.parseInt(entity.slice(2), 16) : Number(entity.slice(1));
+				text += String.fromCodePoint(code);
+			} else {
+				const ch = NAMED.get(entity);
+				if (ch === void 0) return {
+					text,
+					error: `Bad Request: can't parse entities: Unsupported HTML entity "&${entity};"`
+				};
+				text += ch;
+			}
+			continue;
+		}
+		if (whole === "<" || rawTag === void 0) return {
+			text,
+			error: `Bad Request: can't parse entities: Unsupported start tag "" at byte offset ${byteOffset(html, idx)}`
+		};
+		const tag = rawTag.toLowerCase();
+		if (!ALLOWED.has(tag)) return {
+			text,
+			error: `Bad Request: can't parse entities: Unsupported ${closing ? "end" : "start"} tag "${tag}" at byte offset ${byteOffset(html, idx)}`
+		};
+		if (closing) {
+			const open = stack.at(-1);
+			if (open !== tag) return {
+				text,
+				error: `Bad Request: can't parse entities: Unmatched end tag at byte offset ${byteOffset(html, idx)}, expected "</${open ?? ""}>", found "</${tag}>"`
+			};
+			stack.pop();
+		} else stack.push(tag);
+	}
+	text += html.slice(last);
+	if (stack.length > 0) return {
+		text,
+		error: `Bad Request: can't parse entities: Can't find end tag corresponding to start tag "${stack.at(-1)}"`
+	};
+	return {
+		text,
+		error: null
+	};
+}
+export { checkTelegramHtml };

package/dist/testing/fake-telegram.d.ts

@@ -0,0 +1,206 @@
+import { TgUpdate } from "../telegram/update.js";
+import { BotCommand } from "../telegram/types.js";
+type Json = Record<string, unknown>;
+/** Options for {@link FakeTelegram.addBot}; omitted fields get generated values. */
+export interface FakeBotInit {
+  token?: string;
+  id?: number;
+  username?: string;
+  firstName?: string;
+}
+/** A fake bot's identity (its token works against `fake.fetch`). */
+export interface FakeBotInfo {
+  token: string;
+  id: number;
+  username: string;
+  firstName: string;
+}
+/** Selects a bot by token, username or id. Default: the first bot. */
+export type BotRef = string | number | undefined;
+/** How a fake chat treats the bot: `blocked`/`deactivated`/`not_started`/`kicked`/`left` make sends fail with Telegram's real 403 texts. */
+export type FakeChatStatus = "member" | "administrator" | "blocked" | "deactivated" | "not_started" | "kicked" | "left";
+/** Options for {@link FakeTelegram.setChat}. */
+export interface FakeChatInit {
+  type?: "private" | "group" | "supergroup" | "channel";
+  title?: string;
+  username?: string;
+  firstName?: string;
+  isForum?: boolean;
+  /** Existing forum topic ids (sends to other thread ids fail when `isForum`). */
+  topics?: number[];
+  status?: FakeChatStatus;
+  /** Group was upgraded: sends fail with 400 + `migrate_to_chat_id`. */
+  migratedTo?: number;
+  /** `getChatMember` statuses by user id. */
+  members?: Record<number, string>;
+}
+interface ChatState {
+  id: number;
+  type: "private" | "group" | "supergroup" | "channel";
+  title?: string | undefined;
+  username?: string | undefined;
+  firstName?: string | undefined;
+  isForum: boolean;
+  topics: Set<number>;
+  status: FakeChatStatus;
+  migratedTo?: number | undefined;
+  members: Map<number, string>;
+  lastSendAt?: number;
+  recentSends: number[];
+  nextMessageId: number;
+}
+/** A failure injected with {@link FakeTelegram.failNext}. */
+export interface FakeFailure {
+  /** HTTP status and `error_code` (default 400). */
+  status?: number;
+  description?: string;
+  /** Seconds, sent as `parameters.retry_after`. */
+  retryAfter?: number;
+  migrateToChatId?: number;
+  /** Throw like a failed fetch (the error text contains the URL, to prove the client drops it). */
+  network?: boolean;
+  /** Never answer; resolves only when the request is aborted (timeout tests). */
+  hang?: boolean;
+  /** How many calls fail (default 1). */
+  times?: number;
+  /** Only for this bot. */
+  bot?: BotRef;
+}
+/** One recorded Bot API call (`at` = epoch ms from the fake clock). */
+export interface FakeCall {
+  botId: number;
+  method: string;
+  params: Json;
+  ok: boolean;
+  errorCode?: number;
+  at: number;
+}
+/** A text message the fake accepted (`chatId` as text, `at` epoch ms). */
+export interface FakeSentMessage {
+  botId: number;
+  chatId: string;
+  messageId: number;
+  threadId: number | undefined;
+  /** As sent (HTML when `parseMode` is HTML). */
+  text: string;
+  /** Latest text after edits. */
+  currentText: string;
+  parseMode: string | undefined;
+  replyMarkup: unknown;
+  params: Json;
+  edits: number;
+  deleted: boolean;
+  at: number;
+}
+/** A document or photo the fake accepted (`size` in bytes). */
+export interface FakeSentFile {
+  botId: number;
+  chatId: string;
+  messageId: number;
+  kind: "document" | "photo";
+  fileId: string;
+  fileName: string;
+  mime: string;
+  size: number;
+  /** Uploaded bytes (null when sent by file_id / URL). */
+  bytes: Uint8Array | null;
+  caption: string | undefined;
+  /** Uploaded with multipart (false: file_id or URL). */
+  uploaded: boolean;
+  params: Json;
+  at: number;
+}
+/** The webhook registered with `setWebhook`. */
+export interface FakeWebhook {
+  url: string;
+  secretToken: string | undefined;
+  allowedUpdates: string[] | undefined;
+  maxConnections: number;
+  dropPendingUpdates: boolean;
+}
+/** Options for `new FakeTelegram()`. */
+export interface FakeTelegramOptions {
+  /** Epoch ms clock (for `date` fields and rate limits). */
+  now?: () => number;
+  /** Return 429 when a chat gets more than 1 msg/s (private) or 20 msg/min (groups). */
+  rateLimit?: boolean;
+  /** Unknown chats give "chat not found" instead of being created on first send. */
+  strictChats?: boolean;
+  /** Create no default bot. */
+  noDefaultBot?: boolean;
+}
+/** In-memory Telegram Bot API. */
+export declare class FakeTelegram {
+  #private;
+  /** Every call, in order. */
+  readonly calls: FakeCall[];
+  /** Every text message sent. */
+  readonly messages: FakeSentMessage[];
+  /** Every document and photo sent. */
+  readonly files: FakeSentFile[];
+  /** Every `answerCallbackQuery`. */
+  readonly callbackAnswers: {
+    botId: number;
+    params: Json;
+  }[];
+  /** Every `sendChatAction`. */
+  readonly chatActions: {
+    botId: number;
+    chatId: string;
+    action: string;
+  }[];
+  constructor(opts?: FakeTelegramOptions);
+  /** Use as `fetchTelegram({ fetch: fake.fetch })`. */
+  readonly fetch: (input: Request | string | URL, init?: RequestInit) => Promise<Response>;
+  /** The first bot (created by default). */
+  get defaultBot(): FakeBotInfo;
+  /** All bots, in creation order. */
+  get bots(): FakeBotInfo[];
+  /** Adds a bot; returns its token, id and username. */
+  addBot(init?: FakeBotInit): FakeBotInfo;
+  /** Revokes a token (later calls get 401), like `/revoke` in BotFather. */
+  revokeToken(bot?: BotRef): void;
+  /** Creates or changes a chat known to a bot. */
+  setChat(chatId: number, init?: FakeChatInit, bot?: BotRef): void;
+  /** Current state of a chat as the fake sees it, or undefined. */
+  chat(chatId: number | string, bot?: BotRef): Readonly<ChatState> | undefined;
+  /** The next matching call(s) fail. */
+  failNext(method: string, failure?: FakeFailure): void;
+  /** Stores a file the bot can `getFile` + download (for inbound photo / document tests). */
+  addFile(bytes: Uint8Array | string, o?: {
+    name?: string;
+    mime?: string;
+    bot?: BotRef;
+  }): string;
+  /** Queues an update for `getUpdates`. */
+  pushUpdate(update: TgUpdate, bot?: BotRef): void;
+  /** Updates queued for `getUpdates` and not yet confirmed. */
+  pendingUpdates(bot?: BotRef): readonly TgUpdate[];
+  /** The registered webhook, or null. */
+  webhook(bot?: BotRef): FakeWebhook | null;
+  /** Makes getWebhookInfo report a delivery error. */
+  setWebhookError(message: string | null, bot?: BotRef): void;
+  /** The POST Telegram would send to the registered webhook (with the secret header). */
+  webhookRequest(update: TgUpdate, o?: {
+    bot?: BotRef;
+    url?: string;
+    secret?: string | null;
+  }): Request;
+  /** Commands set for a scope + language (exact match, like getMyCommands). */
+  commands(o?: {
+    scope?: Json;
+    language?: string;
+    bot?: BotRef;
+  }): BotCommand[] | undefined;
+  /** Recorded calls to one method (case-insensitive). */
+  callsTo(method: string): FakeCall[];
+  /** Text messages sent to a chat (optionally by one bot). */
+  messagesTo(chatId: number | string, bot?: BotRef): FakeSentMessage[];
+  /** Documents sent to a chat. */
+  documentsTo(chatId: number | string, bot?: BotRef): FakeSentFile[];
+  /** Photos sent to a chat. */
+  photosTo(chatId: number | string, bot?: BotRef): FakeSentFile[];
+  /** Clears recorded calls, messages and failures (bots, chats and webhooks stay). */
+  reset(): void;
+}
+export {};