@yaebal/rich 0.0.1 → 0.0.3

package/src/draft.test.ts

@@ -0,0 +1,167 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { mockApi } from "@yaebal/test";
+import { RichMessageDraft } from "./draft.js";
+
+test("rewrite() pushes a full sendRichMessageDraft snapshot and re-arms the keep-alive timer", async () => {
+	const { api, calls } = mockApi();
+	const draft = new RichMessageDraft(api, 1, 7, { keepAliveMs: 60_000 });
+
+	await draft.rewrite("<tg-thinking>…</tg-thinking>");
+
+	assert.deepEqual(
+		calls.map((c) => ({ method: c.method, params: c.params })),
+		[
+			{
+				method: "sendRichMessageDraft",
+				params: { chat_id: 1, draft_id: 7, rich_message: { html: "<tg-thinking>…</tg-thinking>" } },
+			},
+		],
+	);
+});
+
+test("rewrite() replaces the whole draft — a second call drops the first's content", async () => {
+	const { api, calls } = mockApi();
+	const draft = new RichMessageDraft(api, 1, 1, { keepAliveMs: 60_000 });
+
+	await draft.rewrite("<p>one</p>");
+	await draft.rewrite("<p>two</p>");
+
+	assert.equal(calls.length, 2);
+	assert.deepEqual(calls[1]?.params?.rich_message, { html: "<p>two</p>" });
+});
+
+test("write() appends via string concatenation onto the current draft", async () => {
+	const { api, calls } = mockApi();
+	const draft = new RichMessageDraft(api, 1, 1, { keepAliveMs: 60_000 });
+
+	await draft.rewrite({ html: "<p>hello</p>" });
+	await draft.write({ html: "<hr/>" });
+
+	assert.deepEqual(calls[1]?.params?.rich_message, { html: "<p>hello</p><hr/>" });
+});
+
+test("write() before the first rewrite() throws", async () => {
+	const { api } = mockApi();
+	const draft = new RichMessageDraft(api, 1, 1);
+
+	await assert.rejects(() => draft.write("x"), /write\(\) before the first rewrite\(\)/);
+});
+
+test("write() with a dialect that doesn't match the draft's throws", async () => {
+	const { api } = mockApi();
+	const draft = new RichMessageDraft(api, 1, 1, { keepAliveMs: 60_000 });
+
+	await draft.rewrite({ html: "<p>hi</p>" });
+
+	await assert.rejects(
+		() => draft.write({ markdown: "hi" }),
+		/dialect "markdown" doesn't match the draft's "html"/,
+	);
+});
+
+test("send() with no override auto-assembles from the accumulated rewrite()/write() calls", async () => {
+	const { api, calls } = mockApi();
+	const draft = new RichMessageDraft(api, 1, 1, { keepAliveMs: 60_000 });
+
+	await draft.rewrite({ html: "<p>hello</p>" });
+	await draft.write({ html: "<hr/>" });
+	await draft.send();
+
+	assert.equal(calls[2]?.method, "sendRichMessage");
+	assert.deepEqual(calls[2]?.params, { chat_id: 1, rich_message: { html: "<p>hello</p><hr/>" } });
+	assert.equal(draft.closed, true);
+});
+
+test("send(override) persists the override instead of the accumulated draft", async () => {
+	const { api, calls } = mockApi();
+	const draft = new RichMessageDraft(api, 1, 1, { keepAliveMs: 60_000 });
+
+	await draft.rewrite({ html: "<p>draft text</p>" });
+	await draft.send({ html: "<p>final text</p>" }, { reply_markup: { x: 1 } });
+
+	assert.equal(calls[1]?.method, "sendRichMessage");
+	assert.deepEqual(calls[1]?.params, {
+		chat_id: 1,
+		rich_message: { html: "<p>final text</p>" },
+		reply_markup: { x: 1 },
+	});
+});
+
+test("send() with nothing written and no override throws", async () => {
+	const { api } = mockApi();
+	const draft = new RichMessageDraft(api, 1, 1);
+
+	await assert.rejects(() => draft.send(), /send\(\) with nothing written/);
+});
+
+test("cancel() closes without persisting anything", async () => {
+	const { api, calls } = mockApi();
+	const draft = new RichMessageDraft(api, 1, 2, { keepAliveMs: 60_000 });
+
+	await draft.rewrite("draft text");
+	draft.cancel();
+
+	assert.equal(draft.closed, true);
+	assert.equal(
+		calls.some((c) => c.method === "sendRichMessage"),
+		false,
+	);
+});
+
+test("rewrite()/write() after send()/cancel() throws", async () => {
+	const { api } = mockApi();
+	const draft = new RichMessageDraft(api, 1, 1, { keepAliveMs: 60_000 });
+
+	await draft.rewrite("x");
+	await draft.send();
+
+	await assert.rejects(() => draft.rewrite("late"), /after send\(\)\/cancel\(\)/);
+	await assert.rejects(() => draft.write("late"), /after send\(\)\/cancel\(\)/);
+});
+
+test("messageThreadId routes both the keep-alive pushes and the final send", async () => {
+	const { api, calls } = mockApi();
+	const draft = new RichMessageDraft(api, 1, 1, { keepAliveMs: 60_000, messageThreadId: 42 });
+
+	await draft.rewrite("<p>hi</p>");
+	await draft.send();
+
+	assert.equal(calls[0]?.method, "sendRichMessageDraft");
+	assert.deepEqual(calls[0]?.params, {
+		chat_id: 1,
+		draft_id: 1,
+		rich_message: { html: "<p>hi</p>" },
+		message_thread_id: 42,
+	});
+	assert.equal(calls[1]?.method, "sendRichMessage");
+	assert.deepEqual(calls[1]?.params, {
+		chat_id: 1,
+		rich_message: { html: "<p>hi</p>" },
+		message_thread_id: 42,
+	});
+});
+
+test("businessConnectionId routes only the final send (sendRichMessageDraft has no such param)", async () => {
+	const { api, calls } = mockApi();
+	const draft = new RichMessageDraft(api, 1, 1, {
+		keepAliveMs: 60_000,
+		businessConnectionId: "bc1",
+	});
+
+	await draft.rewrite("<p>hi</p>");
+	await draft.send();
+
+	assert.equal(calls[0]?.params?.business_connection_id, undefined);
+	assert.equal(calls[1]?.params?.business_connection_id, "bc1");
+});
+
+test("preserves is_rtl/skip_entity_detection across write() unless the new push overrides them", async () => {
+	const { api, calls } = mockApi();
+	const draft = new RichMessageDraft(api, 1, 1, { keepAliveMs: 60_000 });
+
+	await draft.rewrite({ html: "<p>a</p>", is_rtl: true });
+	await draft.write({ html: "<p>b</p>" });
+
+	assert.deepEqual(calls[1]?.params?.rich_message, { html: "<p>a</p><p>b</p>", is_rtl: true });
+});

package/src/draft.ts

@@ -1,5 +1,7 @@
 import type { Api, Message } from "@yaebal/core";
 import type { InputRichMessage } from "@yaebal/types";
+import { RichDocument } from "./document.js";
+import type { Dialect } from "./node.js";
 
 export interface RichMessageDraftOptions {
 	/**
@@ -11,6 +13,59 @@ export interface RichMessageDraftOptions {
 	keepAliveMs?: number;
 	/** called when a background keep-alive push fails (e.g. network blip). */
 	onError?: (error: unknown) => void;
+	/**
+	 * the forum topic to stream/send into. sendRichMessageDraft has no
+	 * business_connection_id param (drafts aren't supported in business chats), so only
+	 * the thread id carries through the keep-alive pushes; `send()` additionally accepts
+	 * `businessConnectionId` for the final, non-ephemeral sendRichMessage call.
+	 */
+	messageThreadId?: number;
+	/** routed into the final `send()` only — see {@link messageThreadId}. */
+	businessConnectionId?: string;
+}
+
+interface DraftState {
+	dialect: Dialect;
+	text: string;
+	isRtl?: boolean;
+	skipEntityDetection?: boolean;
+}
+
+type DraftSource = RichDocument | InputRichMessage | string;
+
+function resolve(input: DraftSource, fallbackDialect: Dialect): DraftState {
+	if (typeof input === "string") return { dialect: fallbackDialect, text: input };
+	if (input instanceof RichDocument) return resolve(input.toInputRichMessage(), fallbackDialect);
+
+	if (input.html !== undefined) {
+		return {
+			dialect: "html",
+			text: input.html,
+			isRtl: input.is_rtl,
+			skipEntityDetection: input.skip_entity_detection,
+		};
+	}
+
+	if (input.markdown !== undefined) {
+		return {
+			dialect: "markdown",
+			text: input.markdown,
+			isRtl: input.is_rtl,
+			skipEntityDetection: input.skip_entity_detection,
+		};
+	}
+
+	throw new Error("RichMessageDraft: input must have an `html` or `markdown` field");
+}
+
+function toInputRichMessage(state: DraftState): InputRichMessage {
+	return {
+		[state.dialect]: state.text,
+		...(state.isRtl !== undefined ? { is_rtl: state.isRtl } : {}),
+		...(state.skipEntityDetection !== undefined
+			? { skip_entity_detection: state.skipEntityDetection }
+			: {}),
+	};
 }
 
 /**
@@ -22,15 +77,30 @@ export interface RichMessageDraftOptions {
  *
  * - 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
+ * - refuses to push after `send()`/`cancel()`, so a stray late call can't
  *   resurrect a closed draft;
- * - requires an explicit `commit()` — there is no implicit "last push wins".
+ * - requires an explicit `send()` — there is no implicit "last push wins".
+ *
+ * two ways to grow the draft: `rewrite()` replaces the whole thing (what you want
+ * for a token stream, where each chunk is a longer version of the *same* paragraph),
+ * `write()` appends to it via plain string concatenation (what you want to tack on
+ * a block — a footer, a divider — after content that's already there, without
+ * re-supplying it). a push boundary that lands mid-tag with `write()` is on the
+ * caller, same tradeoff raw concatenation always has.
+ *
+ * `send()` finalizes: with no argument it auto-assembles from the accumulated
+ * `rewrite()`/`write()` calls, so you don't have to re-render the final content —
+ * pass an explicit override when you want the persisted message to differ from the
+ * last draft snapshot.
  *
  * @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)]));
+ * await draft.rewrite(document([thinking("…")]));
+ * for await (const chunk of stream) {
+ *   soFar += chunk;
+ *   await draft.rewrite(document([paragraph(soFar)]));
+ * }
+ * await draft.send();
  */
 export class RichMessageDraft {
 	readonly #api: Api;
@@ -38,9 +108,11 @@ export class RichMessageDraft {
 	readonly #draftId: number;
 	readonly #keepAliveMs: number;
 	readonly #onError?: (error: unknown) => void;
+	readonly #messageThreadId?: number;
+	readonly #businessConnectionId?: string;
 
 	#timer?: ReturnType<typeof setInterval>;
-	#latest: InputRichMessage | undefined;
+	#state: DraftState | undefined;
 	#closed = false;
 
 	constructor(api: Api, chatId: number, draftId: number, options: RichMessageDraftOptions = {}) {
@@ -49,28 +121,65 @@ export class RichMessageDraft {
 		this.#draftId = draftId;
 		this.#keepAliveMs = options.keepAliveMs ?? 20_000;
 		this.#onError = options.onError;
+		this.#messageThreadId = options.messageThreadId;
+		this.#businessConnectionId = options.businessConnectionId;
 	}
 
 	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()");
+	/** replace the whole draft with new content. */
+	async rewrite(input: DraftSource): Promise<void> {
+		this.#assertOpen();
 
-		const resolved = typeof input === "string" ? { html: input } : input;
+		this.#state = resolve(input, this.#state?.dialect ?? "html");
+		await this.#pushCurrent();
+		this.#arm();
+	}
 
-		this.#latest = resolved;
-		await this.#push(resolved);
+	/**
+	 * append to the current draft (plain string concatenation of the resolved text).
+	 * throws if `input`'s dialect doesn't match the draft's, or if nothing has been
+	 * written yet — call `rewrite()` first.
+	 */
+	async write(input: DraftSource): Promise<void> {
+		this.#assertOpen();
+
+		if (!this.#state) {
+			throw new Error("RichMessageDraft: write() before the first rewrite()");
+		}
+
+		const next = resolve(input, this.#state.dialect);
+		if (next.dialect !== this.#state.dialect) {
+			throw new Error(
+				`RichMessageDraft: write() dialect "${next.dialect}" doesn't match the draft's "${this.#state.dialect}"`,
+			);
+		}
+
+		this.#state = {
+			dialect: this.#state.dialect,
+			text: this.#state.text + next.text,
+			isRtl: next.isRtl ?? this.#state.isRtl,
+			skipEntityDetection: next.skipEntityDetection ?? this.#state.skipEntityDetection,
+		};
+		await this.#pushCurrent();
 		this.#arm();
 	}
 
+	#pushCurrent(): Promise<boolean> {
+		const state = this.#state;
+		if (!state) throw new Error("unreachable: #pushCurrent() with no state");
+
+		return this.#push(toInputRichMessage(state));
+	}
+
 	#push(input: InputRichMessage): Promise<boolean> {
 		return this.#api.call<boolean>("sendRichMessageDraft", {
 			chat_id: this.#chatId,
 			draft_id: this.#draftId,
 			rich_message: input,
+			...(this.#messageThreadId === undefined ? {} : { message_thread_id: this.#messageThreadId }),
 		});
 	}
 
@@ -78,26 +187,38 @@ export class RichMessageDraft {
 		clearInterval(this.#timer);
 
 		this.#timer = setInterval(() => {
-			if (!this.#latest) return;
+			if (!this.#state) return;
 
-			this.#push(this.#latest).catch((error: unknown) => this.#onError?.(error));
+			this.#push(toInputRichMessage(this.#state)).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> {
+	/**
+	 * finalize: persist the real message and stop the keep-alive. with no `override`,
+	 * auto-assembles from the accumulated `rewrite()`/`write()` calls. always call this
+	 * or `cancel()`.
+	 */
+	async send(override?: DraftSource, extra: Record<string, unknown> = {}): Promise<Message> {
 		this.#stop();
 
-		const resolved = typeof input === "string" ? { html: input } : input;
+		const state =
+			override !== undefined ? resolve(override, this.#state?.dialect ?? "html") : this.#state;
+
+		if (!state) {
+			throw new Error(
+				"RichMessageDraft: send() with nothing written — call rewrite()/write() first or pass an override",
+			);
+		}
 
 		return this.#api.call<Message>("sendRichMessage", {
 			chat_id: this.#chatId,
-			rich_message: resolved,
+			rich_message: toInputRichMessage(state),
+			...(this.#messageThreadId === undefined ? {} : { message_thread_id: this.#messageThreadId }),
+			...(this.#businessConnectionId === undefined
+				? {}
+				: { business_connection_id: this.#businessConnectionId }),
 			...extra,
 		});
 	}
@@ -113,4 +234,10 @@ export class RichMessageDraft {
 		this.#closed = true;
 		clearInterval(this.#timer);
 	}
+
+	#assertOpen(): void {
+		if (this.#closed) {
+			throw new Error("RichMessageDraft: rewrite()/write() after send()/cancel()");
+		}
+	}
 }

package/src/escape.test.ts

@@ -0,0 +1,38 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { escapeAttr, escapeMarkdown, escapeMarkdownUrl, escapeText } from "./escape.js";
+
+test("escapeText escapes &, <, > with named entities", () => {
+	assert.equal(escapeText("a & b < c > d"), "a &amp; b &lt; c &gt; d");
+});
+
+test("escapeText leaves other characters (including quotes) untouched", () => {
+	assert.equal(escapeText(`"hi" 'there'`), `"hi" 'there'`);
+});
+
+test("escapeAttr additionally escapes double quotes", () => {
+	assert.equal(escapeAttr(`say "hi" & bye`), "say &quot;hi&quot; &amp; bye");
+});
+
+test("escapeMarkdown backslash-escapes rich-markdown specials", () => {
+	assert.equal(
+		escapeMarkdown("a*b_c~d=e|f[g]h(i)j#k!l+m-n`o"),
+		"a\\*b\\_c\\~d\\=e\\|f\\[g\\]h\\(i\\)j\\#k\\!l\\+m\\-n\\`o",
+	);
+});
+
+test("escapeMarkdown numeric-entity-escapes &, <, >", () => {
+	assert.equal(escapeMarkdown("a & b < c > d"), "a &#38; b &#60; c &#62; d");
+});
+
+test("escapeMarkdown leaves plain text untouched", () => {
+	assert.equal(escapeMarkdown("hello world 123"), "hello world 123");
+});
+
+test("escapeMarkdownUrl escapes parens/backslash so a url can't break out of [text](url)", () => {
+	assert.equal(escapeMarkdownUrl("https://x.test/a(b)c\\d"), "https://x.test/a\\(b\\)c\\\\d");
+});
+
+test("escapeMarkdownUrl percent-encodes whitespace", () => {
+	assert.equal(escapeMarkdownUrl("https://x.test/a b"), "https://x.test/a%20b");
+});

package/src/escape.ts

@@ -7,3 +7,23 @@ export function escapeText(value: string): string {
 export function escapeAttr(value: string): string {
 	return escapeText(value).replace(/"/g, """);
 }
+
+// rich-markdown specials. `&`/`<`/`>` become numeric entities (rich-markdown renders
+// `\<` with the backslash showing, but does accept entities — the same trick telegram's
+// classic parse_mode markdown uses); everything else backslash-escapes cleanly.
+const MARKDOWN_SPECIALS = /[\\`*_~=|[\]()#!+\-&<>]/g;
+const MARKDOWN_ENTITY: Record<string, string> = { "&": "&#38;", "<": "&#60;", ">": "&#62;" };
+
+/** escape text so it can never be re-parsed as rich-markdown syntax. */
+export function escapeMarkdown(value: string): string {
+	return value.replace(MARKDOWN_SPECIALS, (ch) => MARKDOWN_ENTITY[ch] ?? `\\${ch}`);
+}
+
+/**
+ * escape a url used as a markdown link destination. `[text](url)` is terminated by `)`
+ * or whitespace, so an attacker-controlled url can't break out of the link — escape the
+ * parens/backslash and percent-encode whitespace.
+ */
+export function escapeMarkdownUrl(value: string): string {
+	return value.replace(/[\\()]/g, "\\$&").replace(/\s/g, (ch) => encodeURIComponent(ch));
+}

package/src/guards.test.ts

@@ -0,0 +1,138 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import type { RichBlock, RichText } from "@yaebal/types";
+import {
+	isAnchorBlock,
+	isAnchorLink,
+	isAnchorText,
+	isAnimation,
+	isAudio,
+	isBankCardNumber,
+	isBlockquote,
+	isBold,
+	isBotCommand,
+	isCashtag,
+	isCodeText,
+	isCollage,
+	isCustomEmoji,
+	isDateTime,
+	isDetails,
+	isDivider,
+	isEmailAddress,
+	isFooter,
+	isHashtag,
+	isHeading,
+	isItalic,
+	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";
+
+const BLOCK_GUARDS: [string, (b: RichBlock) => boolean][] = [
+	["paragraph", isParagraph],
+	["heading", isHeading],
+	["pre", isPreformatted],
+	["footer", isFooter],
+	["divider", isDivider],
+	["mathematical_expression", isMathBlock],
+	["anchor", isAnchorBlock],
+	["list", isList],
+	["blockquote", isBlockquote],
+	["pullquote", isPullquote],
+	["collage", isCollage],
+	["slideshow", isSlideshow],
+	["table", isTable],
+	["details", isDetails],
+	["map", isMap],
+	["animation", isAnimation],
+	["audio", isAudio],
+	["photo", isPhoto],
+	["video", isVideo],
+	["voice_note", isVoiceNote],
+	["thinking", isThinking],
+];
+
+const TEXT_GUARDS: [string, (t: RichText) => boolean][] = [
+	["bold", isBold],
+	["italic", isItalic],
+	["underline", isUnderline],
+	["strikethrough", isStrikethrough],
+	["spoiler", isSpoilerText],
+	["date_time", isDateTime],
+	["text_mention", isTextMention],
+	["subscript", isSubscript],
+	["superscript", isSuperscript],
+	["marked", isMarked],
+	["code", isCodeText],
+	["custom_emoji", isCustomEmoji],
+	["mathematical_expression", isMathText],
+	["url", isUrlText],
+	["email_address", isEmailAddress],
+	["phone_number", isPhoneNumber],
+	["bank_card_number", isBankCardNumber],
+	["mention", isMentionText],
+	["hashtag", isHashtag],
+	["cashtag", isCashtag],
+	["bot_command", isBotCommand],
+	["anchor", isAnchorText],
+	["anchor_link", isAnchorLink],
+	["reference", isReference],
+	["reference_link", isReferenceLink],
+];
+
+test("every RichBlock guard matches its own .type and rejects every other guard's", () => {
+	for (const [type, guard] of BLOCK_GUARDS) {
+		const block = { type } as unknown as RichBlock;
+		assert.equal(guard(block), true, `${type} guard should match its own type`);
+
+		for (const [otherType, otherGuard] of BLOCK_GUARDS) {
+			if (otherType === type) continue;
+			assert.equal(otherGuard(block), false, `${otherType} guard should reject a "${type}" block`);
+		}
+	}
+});
+
+test("every RichText guard matches its own .type and rejects every other guard's", () => {
+	for (const [type, guard] of TEXT_GUARDS) {
+		const text = { type } as unknown as RichText;
+		assert.equal(guard(text), true, `${type} guard should match its own type`);
+
+		for (const [otherType, otherGuard] of TEXT_GUARDS) {
+			if (otherType === type) continue;
+			assert.equal(otherGuard(text), false, `${otherType} guard should reject a "${type}" text`);
+		}
+	}
+});
+
+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);
+});