@yaebal/rich 0.0.1 → 0.0.3

package/src/index.test.ts

@@ -1,122 +1,64 @@
 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 { Composer, Context } from "@yaebal/core";
+import { mockApi } from "@yaebal/test";
 import {
 	bold,
-	cell,
-	details,
 	document,
-	heading,
-	html,
-	image,
-	isPhoto,
-	isTable,
-	item,
-	link,
-	list,
+	md,
 	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][] = [];
+// integration-level coverage for the parts that tie the package together: the raw
+// send/draft functions, and the `rich()` plugin's ctx decoration. per-builder output
+// (blocks.test.ts/inline.test.ts/markdown.test.ts), guards (guards.test.ts),
+// plaintext flattening (plaintext.test.ts), and RichMessageDraft's rewrite/write/send
+// state machine (draft.test.ts) all have their own dedicated test files.
 
-	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" });
+test("sendRichMessage posts chat_id + rich_message to the raw api", async () => {
+	const { api, calls } = mockApi();
 
-	assert.equal(
-		node.html,
-		'<figure><img src="https://example.com/x.jpg"></img><figcaption>a cat<cite>photographer</cite></figcaption></figure>',
-	);
-});
+	await sendRichMessage(api, 42, document([paragraph("hi")]), { reply_markup: { x: 1 } });
 
-test("thinking() is exposed for draft-only use", () => {
-	assert.equal(thinking("…").html, "<tg-thinking>…</tg-thinking>");
+	assert.equal(calls[0]?.method, "sendRichMessage");
+	assert.deepEqual(calls[0]?.params, {
+		chat_id: 42,
+		rich_message: { html: "<p>hi</p>" },
+		reply_markup: { x: 1 },
+	});
 });
 
-test("sendRichMessage posts chat_id + rich_message to the raw api", async () => {
-	const api = mockApi();
+test("sendRichMessage unwraps a markdown RichDocument with its fluent flags", async () => {
+	const { api, calls } = mockApi();
 
-	await sendRichMessage(api, 42, document([paragraph("hi")]), { reply_markup: { x: 1 } });
+	await sendRichMessage(api, 42, md`# hi ${bold("there")}`.rtl());
 
-	assert.deepEqual(api.calls, [
-		[
-			"sendRichMessage",
-			{ chat_id: 42, rich_message: { html: "<p>hi</p>" }, reply_markup: { x: 1 } },
-		],
-	]);
+	assert.equal(calls[0]?.method, "sendRichMessage");
+	assert.deepEqual(calls[0]?.params, {
+		chat_id: 42,
+		rich_message: { markdown: "# hi **there**", is_rtl: true },
+	});
 });
 
 test("sendRichMessageDraft posts draft_id alongside chat_id + rich_message", async () => {
-	const api = mockApi();
+	const { api, calls } = 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>" } },
-		],
-	]);
+	assert.equal(calls[0]?.method, "sendRichMessageDraft");
+	assert.deepEqual(calls[0]?.params, {
+		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();
+test("rich() plugin decorates ctx.sendRichMessage/ctx.richMessageDraft bound to the current chat", async () => {
+	const { api, calls } = mockApi();
 	const composer = new Composer().install(rich());
 
 	const ctx = new Context({
@@ -136,66 +78,63 @@ test("rich() plugin decorates ctx.sendRichMessage bound to the current chat", as
 	};
 
 	await decorated.sendRichMessage(document([paragraph("hi")]));
-	assert.deepEqual(api.calls[0], [
-		"sendRichMessage",
-		{ chat_id: 5, rich_message: { html: "<p>hi</p>" } },
-	]);
+	assert.equal(calls[0]?.method, "sendRichMessage");
+	assert.deepEqual(calls[0]?.params, { 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);
+test("rich() plugin routes ctx.sendRichMessage through the business connection/topic", async () => {
+	const { api, calls } = mockApi();
+	const composer = new Composer().install(rich());
 
-	await assert.rejects(() => draft.push("late"), /after commit\(\)\/cancel\(\)/);
-});
+	const ctx = new Context({
+		api,
+		update: {
+			update_id: 1,
+			business_message: {
+				message_id: 1,
+				date: 0,
+				chat: { id: 5, type: "private" },
+				business_connection_id: "bc1",
+				message_thread_id: 9,
+			},
+		} as never,
+		updateType: "business_message",
+	});
 
-test("RichMessageDraft.cancel() closes without persisting", async () => {
-	const api = mockApi();
-	const draft = new RichMessageDraft(api, 1, 2);
+	await composer.toMiddleware()(ctx as never, async () => {});
 
-	await draft.push("draft text");
-	draft.cancel();
+	const decorated = ctx as unknown as { sendRichMessage: (input: unknown) => Promise<unknown> };
+	await decorated.sendRichMessage(document([paragraph("hi")]));
 
-	assert.equal(draft.closed, true);
-	assert.equal(
-		api.calls.some(([method]) => method === "sendRichMessage"),
-		false,
-	);
+	assert.equal(calls[0]?.method, "sendRichMessage");
+	assert.deepEqual(calls[0]?.params, {
+		chat_id: 5,
+		rich_message: { html: "<p>hi</p>" },
+		business_connection_id: "bc1",
+		message_thread_id: 9,
+	});
 });
 
-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[];
+test("sendRichMessage()/richMessageDraft() reject when the update has no chat", async () => {
+	const { api } = mockApi();
+	const composer = new Composer().install(rich());
 
-	assert.equal(isTable(blocks[0] as RichBlock), true);
-	assert.equal(isPhoto(blocks[1] as RichBlock), true);
-	assert.equal(isTable(blocks[1] as RichBlock), false);
-});
+	const ctx = new Context({
+		api,
+		update: { update_id: 1 } as never,
+		updateType: "message",
+	});
 
-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;
+	await composer.toMiddleware()(ctx as never, async () => {});
+
+	const decorated = ctx as unknown as {
+		sendRichMessage: (input: unknown) => Promise<unknown>;
+		richMessageDraft: (draftId: number) => RichMessageDraft;
+	};
 
-	assert.equal(richMessageToPlainText(message), "title\nhi there\n---\n- one");
+	await assert.rejects(() => decorated.sendRichMessage("x"), /no chat in this update/);
+	assert.throws(() => decorated.richMessageDraft(1), /no chat in this update/);
 });

package/src/index.ts

@@ -6,12 +6,17 @@
  * 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.
+ * - **write**: one dual-dialect builder set. every builder (`bold`, `paragraph`,
+ *   `table`, …) returns a dialect-agnostic `RichNode`; the `html`/`md` template
+ *   tags (or `document()`) pick the wire dialect once, at the edge, and emit a
+ *   `RichDocument` — the `rich_message` envelope with fluent `.rtl()` /
+ *   `.noEntityDetection()` flags. interpolated text is always dialect-escaped,
+ *   so user input can never inject markup in either dialect.
  * - **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.
+ *   the last push) and must be closed with a real `sendRichMessage` (`send()`) or
+ *   explicitly `cancel()`led. `rewrite()` replaces the whole draft, `write()`
+ *   appends to it.
  * - **read**: type guards (guards.ts) and plain-text flattening (plaintext.ts)
  *   cover every `RichBlock`/`RichText` variant telegram can hand back.
  *
@@ -95,9 +100,17 @@ export {
 	details,
 	divider,
 	footer,
+	h1,
+	h2,
+	h3,
+	h4,
+	h5,
+	h6,
 	heading,
 	image,
 	item,
+	join,
+	type ListItem,
 	type ListItemOptions,
 	type ListOptions,
 	list,
@@ -109,13 +122,16 @@ export {
 	preformatted,
 	pullquote,
 	slideshow,
+	type TableCell,
 	type TableCellOptions,
 	type TableOptions,
 	table,
 	thinking,
 	video,
 } from "./blocks.js";
+export { RichDocument } from "./document.js";
 export { RichMessageDraft, type RichMessageDraftOptions } from "./draft.js";
+export { escapeMarkdown, escapeMarkdownUrl } from "./escape.js";
 export {
 	isAnchorBlock,
 	isAnchorLink,
@@ -137,6 +153,7 @@ export {
 	isFooter,
 	isHashtag,
 	isHeading,
+	isItalic,
 	isList,
 	isMap,
 	isMarked,
@@ -167,17 +184,14 @@ export {
 	anchor,
 	anchorLink,
 	bold,
+	br,
 	code,
 	customEmoji,
 	dateTime,
-	html,
-	type Insertable,
-	isRichNode,
 	italic,
 	link,
 	marked,
 	math,
-	type RichNode,
 	reference,
 	referenceLink,
 	spoiler,
@@ -185,15 +199,16 @@ export {
 	subscript,
 	superscript,
 	textMention,
-	toHtml,
 	underline,
 } from "./inline.js";
-export { type DocumentOptions, document, markdown } from "./message.js";
-
+export { type Dialect, isRichNode, type Level, RichError, type RichNode } from "./node.js";
 export { richBlockToPlainText, richMessageToPlainText, richTextToPlainText } from "./plaintext.js";
+export { escapeFor, type Insertable, render } from "./render.js";
 export {
 	type RichContext,
+	type RichSource,
 	rich,
 	sendRichMessage,
 	sendRichMessageDraft,
 } from "./send.js";
+export { type DocumentOptions, document, html, md, type RichTemplate } from "./template.js";

package/src/inline.test.ts

@@ -0,0 +1,125 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import {
+	anchor,
+	anchorLink,
+	bold,
+	br,
+	code,
+	customEmoji,
+	dateTime,
+	italic,
+	link,
+	marked,
+	math,
+	reference,
+	referenceLink,
+	spoiler,
+	strikethrough,
+	subscript,
+	superscript,
+	textMention,
+	underline,
+} from "./inline.js";
+import type { RichNode } from "./node.js";
+
+// every inline builder is dual-dialect: one node, two renders.
+function both(node: RichNode): [html: string, md: string] {
+	return [node.render("html"), node.render("markdown")];
+}
+
+test("wrapper marks render their token pair in each dialect", () => {
+	assert.deepEqual(both(bold("x")), ["<b>x</b>", "**x**"]);
+	assert.deepEqual(both(italic("x")), ["<i>x</i>", "*x*"]);
+	assert.deepEqual(both(strikethrough("x")), ["<s>x</s>", "~~x~~"]);
+	assert.deepEqual(both(spoiler("x")), ["<tg-spoiler>x</tg-spoiler>", "||x||"]);
+	assert.deepEqual(both(code("x")), ["<code>x</code>", "`x`"]);
+	assert.deepEqual(both(marked("x")), ["<mark>x</mark>", "==x=="]);
+});
+
+test("marks with no markdown token embed the raw html tag in both dialects", () => {
+	assert.deepEqual(both(underline("x")), ["<u>x</u>", "<u>x</u>"]);
+	assert.deepEqual(both(subscript("x")), ["<sub>x</sub>", "<sub>x</sub>"]);
+	assert.deepEqual(both(superscript("x")), ["<sup>x</sup>", "<sup>x</sup>"]);
+});
+
+test("string children are escaped per dialect, so user input cannot inject markup", () => {
+	assert.equal(bold("<i>&</i>").render("html"), "<b>&lt;i&gt;&amp;&lt;/i&gt;</b>");
+	assert.equal(bold("a*b_c").render("markdown"), "**a\\*b\\_c**");
+	// html-significant chars become numeric entities in markdown (a backslash would show).
+	assert.equal(bold("<&>").render("markdown"), "**&#60;&#38;&#62;**");
+});
+
+test("nested nodes render into the chosen dialect; siblings concatenate", () => {
+	const node = bold("a ", italic("b"), " c");
+
+	assert.equal(node.render("html"), "<b>a <i>b</i> c</b>");
+	assert.equal(node.render("markdown"), "**a *b* c**");
+});
+
+test("null/undefined/false children render as nothing — `cond && node` composes", () => {
+	const cond = false as boolean;
+
+	assert.equal(bold("a", null, undefined, cond && italic("b")).render("html"), "<b>a</b>");
+});
+
+test("array children are flattened and concatenated", () => {
+	assert.equal(bold(["a", ["b", italic("c")]]).render("html"), "<b>ab<i>c</i></b>");
+});
+
+test("number and bigint children are stringified then escaped", () => {
+	assert.equal(bold(42, "|", 10n).render("markdown"), "**42\\|10**");
+});
+
+test("br() is a hard newline in markdown, <br/> in html", () => {
+	assert.deepEqual(both(br()), ["<br/>", "\n"]);
+});
+
+test("link() escapes the url per dialect so a hostile url cannot break out", () => {
+	assert.equal(
+		link('https://x.dev/?a=1&b="2"', "t").render("html"),
+		'<a href="https://x.dev/?a=1&amp;b=&quot;2&quot;">t</a>',
+	);
+	assert.equal(link("https://x.dev/a) b", "t").render("markdown"), "[t](https://x.dev/a\\)%20b)");
+});
+
+test("textMention() links tg://user?id=… in both dialects", () => {
+	assert.deepEqual(both(textMention({ id: 7 }, "dave")), [
+		'<a href="tg://user?id=7">dave</a>',
+		"[dave](tg://user?id=7)",
+	]);
+});
+
+test("anchor()/anchorLink() — jump target and #link", () => {
+	assert.deepEqual(both(anchor("top")), ['<a name="top"></a>', '<a name="top"></a>']);
+	assert.deepEqual(both(anchorLink("top", "up")), ['<a href="#top">up</a>', "[up](#top)"]);
+});
+
+test("customEmoji() — tg-emoji tag / tg://emoji image link", () => {
+	assert.deepEqual(both(customEmoji("5368324170671202286", "👍")), [
+		'<tg-emoji emoji-id="5368324170671202286">👍</tg-emoji>',
+		"![👍](tg://emoji?id=5368324170671202286)",
+	]);
+});
+
+test("math() keeps LaTeX raw in markdown, html-escapes it in html", () => {
+	assert.deepEqual(both(math("a_1 < b")), ["<tg-math>a_1 &lt; b</tg-math>", "$a_1 < b$"]);
+});
+
+test("dateTime() — best-effort <time> / tg://time image link", () => {
+	assert.deepEqual(both(dateTime(1735689600, "R", "soon")), [
+		'<time datetime="1735689600" data-format="R">soon</time>',
+		"![soon](tg://time?unix=1735689600&format=R)",
+	]);
+});
+
+test("reference()/referenceLink() — tg-reference tags / markdown footnote syntax", () => {
+	assert.deepEqual(both(reference("1", "the fine print")), [
+		'<tg-reference name="1">the fine print</tg-reference>',
+		"[^1]: the fine print",
+	]);
+	assert.deepEqual(both(referenceLink("1", "see note")), [
+		'<tg-reference-link name="1">see note</tg-reference-link>',
+		"[^1]",
+	]);
+});