@yaebal/rich 0.0.1

package/src/draft.ts

@@ -0,0 +1,116 @@
+import type { Api, Message } from "@yaebal/core";
+import type { InputRichMessage } from "@yaebal/types";
+
+export interface RichMessageDraftOptions {
+	/**
+	 * how often to re-push the last draft to keep it alive, in ms. telegram drops
+	 * a draft 30s after the last `sendRichMessageDraft` call for its `draft_id`
+	 * ("ephemeral … temporary 30-second preview"); this must stay comfortably
+	 * under that. defaults to 20_000.
+	 */
+	keepAliveMs?: number;
+	/** called when a background keep-alive push fails (e.g. network blip). */
+	onError?: (error: unknown) => void;
+}
+
+/**
+ * a `sendRichMessageDraft` streaming session — the operationally hard part of the
+ * rich-message api. telegram's draft is ephemeral: it vanishes 30s after the last
+ * push, and it never turns into a real message on its own (per the schema:
+ * "once the output is finalized, you must call sendRichMessage with the complete
+ * message to persist it"). this class:
+ *
+ * - re-pushes the latest draft on a timer so a slow generator (e.g. an LLM
+ *   stream) doesn't lose the draft between tokens;
+ * - refuses to push after `commit()`/`cancel()`, so a stray late token can't
+ *   resurrect a closed draft;
+ * - requires an explicit `commit()` — there is no implicit "last push wins".
+ *
+ * @example
+ * const draft = ctx.richMessageDraft(1);
+ * await draft.push(thinking("…"));
+ * for await (const chunk of stream) await draft.push(document([paragraph(soFar)]));
+ * await draft.commit(document([paragraph(finalAnswer)]));
+ */
+export class RichMessageDraft {
+	readonly #api: Api;
+	readonly #chatId: number;
+	readonly #draftId: number;
+	readonly #keepAliveMs: number;
+	readonly #onError?: (error: unknown) => void;
+
+	#timer?: ReturnType<typeof setInterval>;
+	#latest: InputRichMessage | undefined;
+	#closed = false;
+
+	constructor(api: Api, chatId: number, draftId: number, options: RichMessageDraftOptions = {}) {
+		this.#api = api;
+		this.#chatId = chatId;
+		this.#draftId = draftId;
+		this.#keepAliveMs = options.keepAliveMs ?? 20_000;
+		this.#onError = options.onError;
+	}
+
+	get closed(): boolean {
+		return this.#closed;
+	}
+
+	/** push a new partial draft; telegram animates the transition for a shared `draft_id`. */
+	async push(input: InputRichMessage | string): Promise<void> {
+		if (this.#closed) throw new Error("RichMessageDraft: push() after commit()/cancel()");
+
+		const resolved = typeof input === "string" ? { html: input } : input;
+
+		this.#latest = resolved;
+		await this.#push(resolved);
+		this.#arm();
+	}
+
+	#push(input: InputRichMessage): Promise<boolean> {
+		return this.#api.call<boolean>("sendRichMessageDraft", {
+			chat_id: this.#chatId,
+			draft_id: this.#draftId,
+			rich_message: input,
+		});
+	}
+
+	#arm(): void {
+		clearInterval(this.#timer);
+
+		this.#timer = setInterval(() => {
+			if (!this.#latest) return;
+
+			this.#push(this.#latest).catch((error: unknown) => this.#onError?.(error));
+		}, this.#keepAliveMs);
+
+		this.#timer.unref?.();
+	}
+
+	/** finalize: persist the real message and stop the keep-alive. always call this or `cancel()`. */
+	async commit(
+		input: InputRichMessage | string,
+		extra: Record<string, unknown> = {},
+	): Promise<Message> {
+		this.#stop();
+
+		const resolved = typeof input === "string" ? { html: input } : input;
+
+		return this.#api.call<Message>("sendRichMessage", {
+			chat_id: this.#chatId,
+			rich_message: resolved,
+			...extra,
+		});
+	}
+
+	/** abandon the draft without persisting anything — it expires within 30s on its own. */
+	cancel(): void {
+		this.#stop();
+	}
+
+	#stop(): void {
+		if (this.#closed) return;
+
+		this.#closed = true;
+		clearInterval(this.#timer);
+	}
+}

package/src/escape.ts

@@ -0,0 +1,9 @@
+/** escape text so it can never be re-parsed as a tag or entity. */
+export function escapeText(value: string): string {
+	return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+
+/** escape a double-quoted attribute value. */
+export function escapeAttr(value: string): string {
+	return escapeText(value).replace(/"/g, "&quot;");
+}

package/src/guards.ts

@@ -0,0 +1,169 @@
+import type {
+	RichBlock,
+	RichBlockAnchor,
+	RichBlockAnimation,
+	RichBlockAudio,
+	RichBlockBlockQuotation,
+	RichBlockCollage,
+	RichBlockDetails,
+	RichBlockDivider,
+	RichBlockFooter,
+	RichBlockList,
+	RichBlockMap,
+	RichBlockMathematicalExpression,
+	RichBlockParagraph,
+	RichBlockPhoto,
+	RichBlockPreformatted,
+	RichBlockPullQuotation,
+	RichBlockSectionHeading,
+	RichBlockSlideshow,
+	RichBlockTable,
+	RichBlockThinking,
+	RichBlockVideo,
+	RichBlockVoiceNote,
+	RichText,
+	RichTextAnchor,
+	RichTextAnchorLink,
+	RichTextBankCardNumber,
+	RichTextBold,
+	RichTextBotCommand,
+	RichTextCashtag,
+	RichTextCode,
+	RichTextCustomEmoji,
+	RichTextDateTime,
+	RichTextEmailAddress,
+	RichTextHashtag,
+	RichTextItalic,
+	RichTextMarked,
+	RichTextMathematicalExpression,
+	RichTextMention,
+	RichTextPhoneNumber,
+	RichTextReference,
+	RichTextReferenceLink,
+	RichTextSpoiler,
+	RichTextStrikethrough,
+	RichTextSubscript,
+	RichTextSuperscript,
+	RichTextTextMention,
+	RichTextUnderline,
+	RichTextUrl,
+} from "@yaebal/types";
+
+/**
+ * the generated `.type` field is typed as plain `string` (the codegen doesn't turn
+ * telegram's "always X" doc convention into a literal type), so `RichBlock["type"]`
+ * can't discriminate the union on its own — `Extract<RichBlock, { type: "table" }>`
+ * would just be `never`. this lookup map is the narrowing telescope instead: one
+ * entry per `.type` string, hand-matched to its interface.
+ */
+interface RichBlockByType {
+	paragraph: RichBlockParagraph;
+	heading: RichBlockSectionHeading;
+	pre: RichBlockPreformatted;
+	footer: RichBlockFooter;
+	divider: RichBlockDivider;
+	mathematical_expression: RichBlockMathematicalExpression;
+	anchor: RichBlockAnchor;
+	list: RichBlockList;
+	blockquote: RichBlockBlockQuotation;
+	pullquote: RichBlockPullQuotation;
+	collage: RichBlockCollage;
+	slideshow: RichBlockSlideshow;
+	table: RichBlockTable;
+	details: RichBlockDetails;
+	map: RichBlockMap;
+	animation: RichBlockAnimation;
+	audio: RichBlockAudio;
+	photo: RichBlockPhoto;
+	video: RichBlockVideo;
+	voice_note: RichBlockVoiceNote;
+	thinking: RichBlockThinking;
+}
+
+interface RichTextByType {
+	bold: RichTextBold;
+	italic: RichTextItalic;
+	underline: RichTextUnderline;
+	strikethrough: RichTextStrikethrough;
+	spoiler: RichTextSpoiler;
+	date_time: RichTextDateTime;
+	text_mention: RichTextTextMention;
+	subscript: RichTextSubscript;
+	superscript: RichTextSuperscript;
+	marked: RichTextMarked;
+	code: RichTextCode;
+	custom_emoji: RichTextCustomEmoji;
+	mathematical_expression: RichTextMathematicalExpression;
+	url: RichTextUrl;
+	email_address: RichTextEmailAddress;
+	phone_number: RichTextPhoneNumber;
+	bank_card_number: RichTextBankCardNumber;
+	mention: RichTextMention;
+	hashtag: RichTextHashtag;
+	cashtag: RichTextCashtag;
+	bot_command: RichTextBotCommand;
+	anchor: RichTextAnchor;
+	anchor_link: RichTextAnchorLink;
+	reference: RichTextReference;
+	reference_link: RichTextReferenceLink;
+}
+
+function blockGuard<K extends keyof RichBlockByType>(type: K) {
+	return (block: RichBlock): block is RichBlockByType[K] => block.type === type;
+}
+
+function textGuard<K extends keyof RichTextByType>(type: K) {
+	return (text: RichText): text is RichTextByType[K] => text.type === type;
+}
+
+// --- RichBlock (21 variants) — one guard per `.type` discriminant ---
+
+export const isParagraph = blockGuard("paragraph");
+export const isHeading = blockGuard("heading");
+export const isPreformatted = blockGuard("pre");
+export const isFooter = blockGuard("footer");
+export const isDivider = blockGuard("divider");
+export const isMathBlock = blockGuard("mathematical_expression");
+export const isAnchorBlock = blockGuard("anchor");
+export const isList = blockGuard("list");
+export const isBlockquote = blockGuard("blockquote");
+export const isPullquote = blockGuard("pullquote");
+export const isCollage = blockGuard("collage");
+export const isSlideshow = blockGuard("slideshow");
+export const isTable = blockGuard("table");
+export const isDetails = blockGuard("details");
+export const isMap = blockGuard("map");
+export const isAnimation = blockGuard("animation");
+export const isAudio = blockGuard("audio");
+export const isPhoto = blockGuard("photo");
+export const isVideo = blockGuard("video");
+export const isVoiceNote = blockGuard("voice_note");
+export const isThinking = blockGuard("thinking");
+
+// --- RichText (25 variants) ---
+
+export const isBold = textGuard("bold");
+export const isItalic = textGuard("italic");
+export const isUnderline = textGuard("underline");
+export const isStrikethrough = textGuard("strikethrough");
+export const isSpoilerText = textGuard("spoiler");
+export const isDateTime = textGuard("date_time");
+export const isTextMention = textGuard("text_mention");
+export const isSubscript = textGuard("subscript");
+export const isSuperscript = textGuard("superscript");
+export const isMarked = textGuard("marked");
+export const isCodeText = textGuard("code");
+export const isCustomEmoji = textGuard("custom_emoji");
+export const isMathText = textGuard("mathematical_expression");
+export const isUrlText = textGuard("url");
+export const isEmailAddress = textGuard("email_address");
+export const isPhoneNumber = textGuard("phone_number");
+export const isBankCardNumber = textGuard("bank_card_number");
+export const isMentionText = textGuard("mention");
+export const isHashtag = textGuard("hashtag");
+export const isCashtag = textGuard("cashtag");
+export const isBotCommand = textGuard("bot_command");
+export const isAnchorText = textGuard("anchor");
+export const isAnchorLink = textGuard("anchor_link");
+export const isReference = textGuard("reference");
+export const isReferenceLink = textGuard("reference_link");

package/src/index.test.ts

@@ -0,0 +1,201 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { type Api, Composer, Context } from "@yaebal/core";
+import type { RichBlock, RichMessage } from "@yaebal/types";
+import {
+	bold,
+	cell,
+	details,
+	document,
+	heading,
+	html,
+	image,
+	isPhoto,
+	isTable,
+	item,
+	link,
+	list,
+	paragraph,
+	RichMessageDraft,
+	rich,
+	richMessageToPlainText,
+	sendRichMessage,
+	sendRichMessageDraft,
+	table,
+	thinking,
+} from "./index.js";
+
+function mockApi(): Api & { calls: [string, Record<string, unknown> | undefined][] } {
+	const calls: [string, Record<string, unknown> | undefined][] = [];
+
+	return {
+		calls,
+		call: async (method: string, params?: Record<string, unknown>) => {
+			calls.push([method, params]);
+			return {} as never;
+		},
+	} as unknown as Api & { calls: [string, Record<string, unknown> | undefined][] };
+}
+
+test("html template escapes interpolations and splices RichNode subs", () => {
+	const node = html`<p>hi ${"<b>hax</b>"} — ${bold("safe")}</p>`;
+
+	assert.equal(node.html, "<p>hi &lt;b&gt;hax&lt;/b&gt; — <b>safe</b></p>");
+});
+
+test("inline builders emit the documented tags", () => {
+	assert.equal(bold("x").html, "<b>x</b>");
+	assert.equal(link("https://yaeb.al", "docs").html, '<a href="https://yaeb.al">docs</a>');
+});
+
+test("block builders compose into a document", () => {
+	const input = document([
+		heading(1, "title"),
+		paragraph("hello ", bold("world")),
+		list([item(["a"]), item(["b"], { checkbox: true, checked: true })]),
+		details("more", [paragraph("hidden")], { open: false }),
+	]);
+
+	assert.equal(
+		input.html,
+		"<h1>title</h1>" +
+			"<p>hello <b>world</b></p>" +
+			'<ul><li>a</li><li><input type="checkbox" checked/> b</li></ul>' +
+			"<details><summary>more</summary><p>hidden</p></details>",
+	);
+});
+
+test("table() and cell() render alignment attributes telegram's schema documents", () => {
+	const node = table([
+		[cell("a", { header: true, align: "center" }), cell("b", { valign: "middle" })],
+	]);
+
+	assert.equal(
+		node.html,
+		'<table><tr><th align="center">a</th><td valign="middle">b</td></tr></table>',
+	);
+});
+
+test("image() wraps caption/credit in figure/figcaption/cite", () => {
+	const node = image("https://example.com/x.jpg", { caption: "a cat", credit: "photographer" });
+
+	assert.equal(
+		node.html,
+		'<figure><img src="https://example.com/x.jpg"></img><figcaption>a cat<cite>photographer</cite></figcaption></figure>',
+	);
+});
+
+test("thinking() is exposed for draft-only use", () => {
+	assert.equal(thinking("…").html, "<tg-thinking>…</tg-thinking>");
+});
+
+test("sendRichMessage posts chat_id + rich_message to the raw api", async () => {
+	const api = mockApi();
+
+	await sendRichMessage(api, 42, document([paragraph("hi")]), { reply_markup: { x: 1 } });
+
+	assert.deepEqual(api.calls, [
+		[
+			"sendRichMessage",
+			{ chat_id: 42, rich_message: { html: "<p>hi</p>" }, reply_markup: { x: 1 } },
+		],
+	]);
+});
+
+test("sendRichMessageDraft posts draft_id alongside chat_id + rich_message", async () => {
+	const api = mockApi();
+
+	await sendRichMessageDraft(api, 42, 7, "<tg-thinking>…</tg-thinking>");
+
+	assert.deepEqual(api.calls, [
+		[
+			"sendRichMessageDraft",
+			{ chat_id: 42, draft_id: 7, rich_message: { html: "<tg-thinking>…</tg-thinking>" } },
+		],
+	]);
+});
+
+test("rich() plugin decorates ctx.sendRichMessage bound to the current chat", async () => {
+	const api = mockApi();
+	const composer = new Composer().install(rich());
+
+	const ctx = new Context({
+		api,
+		update: {
+			update_id: 1,
+			message: { message_id: 1, date: 0, chat: { id: 5, type: "private" } },
+		} as never,
+		updateType: "message",
+	});
+
+	await composer.toMiddleware()(ctx as never, async () => {});
+
+	const decorated = ctx as unknown as {
+		sendRichMessage: (input: unknown) => Promise<unknown>;
+		richMessageDraft: (draftId: number) => RichMessageDraft;
+	};
+
+	await decorated.sendRichMessage(document([paragraph("hi")]));
+	assert.deepEqual(api.calls[0], [
+		"sendRichMessage",
+		{ chat_id: 5, rich_message: { html: "<p>hi</p>" } },
+	]);
+
+	const draft = decorated.richMessageDraft(1);
+	assert.ok(draft instanceof RichMessageDraft);
+});
+
+test("RichMessageDraft.push() re-arms a keep-alive timer and commit() stops it", async () => {
+	const api = mockApi();
+	const draft = new RichMessageDraft(api, 1, 1, { keepAliveMs: 60_000 });
+
+	await draft.push(thinking("…"));
+	assert.equal(api.calls[0]?.[0], "sendRichMessageDraft");
+
+	await draft.commit(document([paragraph("done")]));
+	assert.equal(api.calls[1]?.[0], "sendRichMessage");
+	assert.equal(draft.closed, true);
+
+	await assert.rejects(() => draft.push("late"), /after commit\(\)\/cancel\(\)/);
+});
+
+test("RichMessageDraft.cancel() closes without persisting", async () => {
+	const api = mockApi();
+	const draft = new RichMessageDraft(api, 1, 2);
+
+	await draft.push("draft text");
+	draft.cancel();
+
+	assert.equal(draft.closed, true);
+	assert.equal(
+		api.calls.some(([method]) => method === "sendRichMessage"),
+		false,
+	);
+});
+
+test("guards narrow RichBlock by .type despite the generated field being `string`", () => {
+	const blocks = [
+		{ type: "table", cells: [[{ text: "x", align: "left", valign: "top" }]] },
+		{ type: "photo", photo: [] },
+	] as unknown as RichBlock[];
+
+	assert.equal(isTable(blocks[0] as RichBlock), true);
+	assert.equal(isPhoto(blocks[1] as RichBlock), true);
+	assert.equal(isTable(blocks[1] as RichBlock), false);
+});
+
+test("richMessageToPlainText flattens a full block tree", () => {
+	const message = {
+		blocks: [
+			{ type: "heading", text: "title", size: 1 },
+			{ type: "paragraph", text: [{ type: "bold", text: "hi" }, " there"] },
+			{ type: "divider" },
+			{
+				type: "list",
+				items: [{ label: "1", blocks: [{ type: "paragraph", text: "one" }] }],
+			},
+		],
+	} as unknown as RichMessage;
+
+	assert.equal(richMessageToPlainText(message), "title\nhi there\n---\n- one");
+});

package/src/index.ts

@@ -0,0 +1,199 @@
+/**
+ * @yaebal/rich — telegram's `sendRichMessage` / `sendRichMessageDraft`.
+ *
+ * unlike classic `parse_mode`/entities (see `@yaebal/fmt`), a rich message is a
+ * block-tree document: you write extended html (or markdown) once, telegram
+ * parses it server-side, and you get the same tree back on `message.rich_message`.
+ * this package covers all three parts of that surface:
+ *
+ * - **write**: `document()` + block builders (blocks.ts) and inline mark builders
+ *   (inline.ts) assemble an `InputRichMessage` without hand-written angle brackets.
+ * - **stream**: `RichMessageDraft` (draft.ts) owns the fiddly part of
+ *   `sendRichMessageDraft` — the draft is ephemeral (telegram drops it 30s after
+ *   the last push) and must be closed with a real `sendRichMessage` or explicitly
+ *   cancelled.
+ * - **read**: type guards (guards.ts) and plain-text flattening (plaintext.ts)
+ *   cover every `RichBlock`/`RichText` variant telegram can hand back.
+ *
+ * a handful of inline/block tags have no "corresponding to the html tag …" note in
+ * the schema (marked, subscript, superscript, date_time, inline math, map,
+ * reference/reference_link, table borders) — those are flagged best-effort in
+ * their doc comments in inline.ts/blocks.ts. everything else is either a
+ * documented tag or (for url/email/phone/bank-card/@mention/#hashtag/$cashtag/
+ * /bot_command) auto-detected from plain text by telegram itself.
+ */
+
+// the full generated rich-message type surface, re-exported so consumers never
+// need to reach into `@yaebal/types` directly for annotations.
+export type {
+	InputRichMessage,
+	InputRichMessageContent,
+	RichBlock,
+	RichBlockAnchor,
+	RichBlockAnimation,
+	RichBlockAudio,
+	RichBlockBlockQuotation,
+	RichBlockCaption,
+	RichBlockCollage,
+	RichBlockDetails,
+	RichBlockDivider,
+	RichBlockFooter,
+	RichBlockList,
+	RichBlockListItem,
+	RichBlockMap,
+	RichBlockMathematicalExpression,
+	RichBlockParagraph,
+	RichBlockPhoto,
+	RichBlockPreformatted,
+	RichBlockPullQuotation,
+	RichBlockSectionHeading,
+	RichBlockSlideshow,
+	RichBlockTable,
+	RichBlockTableCell,
+	RichBlockThinking,
+	RichBlockVideo,
+	RichBlockVoiceNote,
+	RichMessage,
+	RichText,
+	RichTextAnchor,
+	RichTextAnchorLink,
+	RichTextBankCardNumber,
+	RichTextBold,
+	RichTextBotCommand,
+	RichTextCashtag,
+	RichTextCode,
+	RichTextCustomEmoji,
+	RichTextDateTime,
+	RichTextEmailAddress,
+	RichTextHashtag,
+	RichTextItalic,
+	RichTextMarked,
+	RichTextMathematicalExpression,
+	RichTextMention,
+	RichTextPhoneNumber,
+	RichTextReference,
+	RichTextReferenceLink,
+	RichTextSpoiler,
+	RichTextStrikethrough,
+	RichTextSubscript,
+	RichTextSuperscript,
+	RichTextTextMention,
+	RichTextUnderline,
+	RichTextUrl,
+	SendRichMessageDraftParams,
+	SendRichMessageParams,
+} from "@yaebal/types";
+
+export {
+	anchorBlock,
+	audio,
+	blockquote,
+	type Caption,
+	cell,
+	collage,
+	type DetailsOptions,
+	details,
+	divider,
+	footer,
+	heading,
+	image,
+	item,
+	type ListItemOptions,
+	type ListOptions,
+	list,
+	type MapOptions,
+	type MediaOptions,
+	map,
+	mathBlock,
+	paragraph,
+	preformatted,
+	pullquote,
+	slideshow,
+	type TableCellOptions,
+	type TableOptions,
+	table,
+	thinking,
+	video,
+} from "./blocks.js";
+export { RichMessageDraft, type RichMessageDraftOptions } from "./draft.js";
+export {
+	isAnchorBlock,
+	isAnchorLink,
+	isAnchorText,
+	isAnimation,
+	isAudio,
+	isBankCardNumber,
+	isBlockquote,
+	isBold,
+	isBotCommand,
+	isCashtag,
+	isCodeText,
+	isCollage,
+	isCustomEmoji,
+	isDateTime,
+	isDetails,
+	isDivider,
+	isEmailAddress,
+	isFooter,
+	isHashtag,
+	isHeading,
+	isList,
+	isMap,
+	isMarked,
+	isMathBlock,
+	isMathText,
+	isMentionText,
+	isParagraph,
+	isPhoneNumber,
+	isPhoto,
+	isPreformatted,
+	isPullquote,
+	isReference,
+	isReferenceLink,
+	isSlideshow,
+	isSpoilerText,
+	isStrikethrough,
+	isSubscript,
+	isSuperscript,
+	isTable,
+	isTextMention,
+	isThinking,
+	isUnderline,
+	isUrlText,
+	isVideo,
+	isVoiceNote,
+} from "./guards.js";
+export {
+	anchor,
+	anchorLink,
+	bold,
+	code,
+	customEmoji,
+	dateTime,
+	html,
+	type Insertable,
+	isRichNode,
+	italic,
+	link,
+	marked,
+	math,
+	type RichNode,
+	reference,
+	referenceLink,
+	spoiler,
+	strikethrough,
+	subscript,
+	superscript,
+	textMention,
+	toHtml,
+	underline,
+} from "./inline.js";
+export { type DocumentOptions, document, markdown } from "./message.js";
+
+export { richBlockToPlainText, richMessageToPlainText, richTextToPlainText } from "./plaintext.js";
+export {
+	type RichContext,
+	rich,
+	sendRichMessage,
+	sendRichMessageDraft,
+} from "./send.js";