@yaebal/rich 0.0.1

package/src/inline.ts

@@ -0,0 +1,152 @@
+import type { User } from "@yaebal/core";
+import { escapeAttr, escapeText } from "./escape.js";
+
+/**
+ * a fragment of the extended html telegram parses into a `RichMessage` (see
+ * `InputRichMessage.html`). unlike `@yaebal/fmt`'s `FormatResult` (a flat
+ * `{ text, entities }` pair), rich messages are a block tree parsed server-side —
+ * there is nothing to build client-side except this html string.
+ */
+export interface RichNode {
+	readonly html: string;
+}
+
+export type Insertable = RichNode | string | number | bigint | boolean | null | undefined;
+
+export function isRichNode(value: unknown): value is RichNode {
+	return (
+		typeof value === "object" && value !== null && typeof (value as RichNode).html === "string"
+	);
+}
+
+/** render one interpolation: a `RichNode` is spliced raw, anything else is escaped text. */
+export function toHtml(value: Insertable): string {
+	if (isRichNode(value)) return value.html;
+	return value == null ? "" : escapeText(String(value));
+}
+
+function join(children: Insertable[]): string {
+	return children.map(toHtml).join("");
+}
+
+function wrap(tag: string) {
+	return (...children: Insertable[]): RichNode => ({ html: `<${tag}>${join(children)}</${tag}>` });
+}
+
+/**
+ * an extended-html template: interpolations are auto-escaped (never re-parsed as
+ * markup), and a nested `RichNode` (from these builders, or another `html`
+ * template) is spliced in raw. mirrors `@yaebal/fmt`'s `html` tag, but for the
+ * rich-message dialect instead of the classic entity one.
+ */
+export function html(strings: TemplateStringsArray, ...subs: Insertable[]): RichNode {
+	let out = "";
+
+	for (let i = 0; i < strings.length; i++) {
+		out += strings[i] ?? "";
+		if (i < subs.length) out += toHtml(subs[i]);
+	}
+
+	return { html: out };
+}
+
+// --- inline marks — confirmed tags (same dialect as classic parse_mode html) ---
+
+/** `RichTextBold`, `<b>`. */
+export const bold = wrap("b");
+/** `RichTextItalic`, `<i>`. */
+export const italic = wrap("i");
+/** `RichTextUnderline`, `<u>`. */
+export const underline = wrap("u");
+/** `RichTextStrikethrough`, `<s>`. */
+export const strikethrough = wrap("s");
+/** `RichTextSpoiler`, `<tg-spoiler>`. */
+export const spoiler = wrap("tg-spoiler");
+/** `RichTextCode`, `<code>`. */
+export const code = wrap("code");
+
+/**
+ * `RichTextCustomEmoji`, `<tg-emoji emoji-id="…">`. same custom tag classic
+ * `parse_mode: "HTML"` uses for custom emoji — telegram documents it as reused
+ * verbatim here. `fallback` is the plain emoji shown where custom emoji can't render.
+ */
+export function customEmoji(emojiId: string, fallback: string): RichNode {
+	return { html: `<tg-emoji emoji-id="${escapeAttr(emojiId)}">${escapeText(fallback)}</tg-emoji>` };
+}
+
+/**
+ * `RichTextTextMention`, a mention of a user who may have no `@username` — same
+ * `tg://user?id=…` link telegram's classic html dialect uses for `text_mention`.
+ * for `@username` mentions (`RichTextMention`), just write `@username` as plain
+ * text — the schema lists it as auto-detected (see `skipEntityDetection`).
+ */
+export function textMention(user: Pick<User, "id">, ...children: Insertable[]): RichNode {
+	return { html: `<a href="tg://user?id=${user.id}">${join(children)}</a>` };
+}
+
+/** `RichTextUrl`, an explicit link. for a bare auto-linked url, just write it as plain text. */
+export function link(url: string, ...children: Insertable[]): RichNode {
+	return { html: `<a href="${escapeAttr(url)}">${join(children)}</a>` };
+}
+
+/** `RichTextAnchor` (inline form) — a named jump target, `<a name="…">`. */
+export function anchor(name: string): RichNode {
+	return { html: `<a name="${escapeAttr(name)}"></a>` };
+}
+
+/**
+ * `RichTextAnchorLink`, a link to an `anchor()` elsewhere in the message —
+ * `<a href="#name">`. an empty `name` jumps back to the top (per the schema).
+ */
+export function anchorLink(name: string, ...children: Insertable[]): RichNode {
+	return { html: `<a href="#${escapeAttr(name)}">${join(children)}</a>` };
+}
+
+// --- inline marks — best-effort tags ---
+//
+// telegram's schema names these types and their fields, but (as scraped) does not
+// state an explicit "corresponding to the html tag …" for them the way it does for
+// bold/italic/code/etc above. the guesses below follow telegram's own pattern of
+// reusing standard html5 semantics (sub/sup/mark/time) or its `tg-*` custom-tag
+// convention — verify against the live "rich message formatting options" docs
+// before depending on the exact tag/attribute spelling in production.
+
+/** `RichTextMarked`, best-effort `<mark>` (standard html5 highlight). */
+export const marked = wrap("mark");
+/** `RichTextSubscript`, best-effort `<sub>`. */
+export const subscript = wrap("sub");
+/** `RichTextSuperscript`, best-effort `<sup>`. */
+export const superscript = wrap("sup");
+
+/**
+ * `RichTextMathematicalExpression` (inline), best-effort `<tg-math>` (the block
+ * form is confirmed as `<tg-math-block>` — see `mathBlock` in blocks.ts).
+ */
+export function math(expression: string): RichNode {
+	return { html: `<tg-math>${escapeText(expression)}</tg-math>` };
+}
+
+/**
+ * `RichTextDateTime`, best-effort `<time>`. `format` is telegram's date-time
+ * entity format string; attribute name is a guess (`data-format`).
+ */
+export function dateTime(unixTime: number, format: string, ...children: Insertable[]): RichNode {
+	return {
+		html: `<time datetime="${unixTime}" data-format="${escapeAttr(format)}">${join(children)}</time>`,
+	};
+}
+
+/**
+ * `RichTextReference`, a footnote definition. no tag is documented anywhere in
+ * the scraped schema — this is a from-scratch `tg-*`-style guess.
+ */
+export function reference(name: string, ...children: Insertable[]): RichNode {
+	return { html: `<tg-reference name="${escapeAttr(name)}">${join(children)}</tg-reference>` };
+}
+
+/** `RichTextReferenceLink`, a link to a `reference()`. same caveat as `reference`. */
+export function referenceLink(name: string, ...children: Insertable[]): RichNode {
+	return {
+		html: `<tg-reference-link name="${escapeAttr(name)}">${join(children)}</tg-reference-link>`,
+	};
+}

package/src/message.ts

@@ -0,0 +1,45 @@
+import type { InputRichMessage } from "@yaebal/types";
+import type { Insertable } from "./inline.js";
+import { toHtml } from "./inline.js";
+
+export interface DocumentOptions {
+	/** `InputRichMessage.is_rtl` — show the message right-to-left. */
+	rtl?: boolean;
+	/**
+	 * `InputRichMessage.skip_entity_detection` — turn off auto-detection of urls,
+	 * emails, `@mentions`, `#hashtags`, `$cashtags`, `/bot_commands`, and phone
+	 * numbers in plain text.
+	 */
+	skipEntityDetection?: boolean;
+}
+
+/**
+ * assemble top-level blocks (from blocks.ts) into an `InputRichMessage.html`
+ * payload. pass the result straight to `sendRichMessage`/`sendRichMessageDraft`
+ * or a `RichMessageDraft`.
+ */
+export function document(blocks: Insertable[], options: DocumentOptions = {}): InputRichMessage {
+	return {
+		html: blocks.map(toHtml).join(""),
+		...(options.rtl !== undefined ? { is_rtl: options.rtl } : {}),
+		...(options.skipEntityDetection !== undefined
+			? { skip_entity_detection: options.skipEntityDetection }
+			: {}),
+	};
+}
+
+/**
+ * a raw markdown payload — telegram parses `InputRichMessage.markdown` the same
+ * way as `html`, but the extended block syntax (tables, `tg-thinking`, …) is not
+ * documented in markdown form, so unlike `document()` this has no builder: pass a
+ * literal string.
+ */
+export function markdown(source: string, options: DocumentOptions = {}): InputRichMessage {
+	return {
+		markdown: source,
+		...(options.rtl !== undefined ? { is_rtl: options.rtl } : {}),
+		...(options.skipEntityDetection !== undefined
+			? { skip_entity_detection: options.skipEntityDetection }
+			: {}),
+	};
+}

package/src/plaintext.ts

@@ -0,0 +1,143 @@
+import type {
+	RichBlock,
+	RichBlockAnimation,
+	RichBlockAudio,
+	RichBlockBlockQuotation,
+	RichBlockCaption,
+	RichBlockCollage,
+	RichBlockDetails,
+	RichBlockFooter,
+	RichBlockList,
+	RichBlockMap,
+	RichBlockMathematicalExpression,
+	RichBlockParagraph,
+	RichBlockPhoto,
+	RichBlockPreformatted,
+	RichBlockPullQuotation,
+	RichBlockSectionHeading,
+	RichBlockSlideshow,
+	RichBlockTable,
+	RichBlockThinking,
+	RichBlockVideo,
+	RichBlockVoiceNote,
+	RichMessage,
+	RichText,
+	RichTextCustomEmoji,
+	RichTextMathematicalExpression,
+} from "@yaebal/types";
+
+/**
+ * the schema documents `RichText` fields as "either a String for plain text, an
+ * Array of RichText, or" one of the marked-up variants — but the generated
+ * `RichText` type only lists the object variants. widen locally so plain-string
+ * leaves (by far the common case) don't need a cast at every call site.
+ */
+type RichTextLike = RichText | string | RichTextLike[] | undefined;
+
+/**
+ * every generated `.type` field is plain `string`, not a literal — so unlike a
+ * normal discriminated union, `switch (x.type)` narrows the *string*, not `x`
+ * itself, and (worse) several `RichBlock`/`RichText` interfaces are structurally
+ * identical (e.g. `RichBlockParagraph`/`RichBlockFooter`/`RichBlockThinking` are
+ * all just `{ type; text }`), which makes typescript's guard-based negative
+ * narrowing collapse to `never` if you lean on it across a chain. so: switch on
+ * the string, cast once per case instead of narrowing.
+ */
+function as<T>(value: unknown): T {
+	return value as T;
+}
+
+/** flatten a `RichText` field (bold/link/spoiler/…) down to its plain characters. */
+export function richTextToPlainText(text: RichTextLike): string {
+	if (text === undefined) return "";
+	if (typeof text === "string") return text;
+	if (Array.isArray(text)) return text.map(richTextToPlainText).join("");
+
+	switch (text.type) {
+		case "custom_emoji":
+			return as<RichTextCustomEmoji>(text).alternative_text;
+		case "mathematical_expression":
+			return as<RichTextMathematicalExpression>(text).expression;
+		case "anchor":
+			return "";
+		// every remaining variant wraps a nested `text` field (bold, italic, url,
+		// mention, hashtag, date_time, reference, anchor_link, text_mention, …).
+		default:
+			return richTextToPlainText(as<{ text?: RichTextLike }>(text).text);
+	}
+}
+
+function captionToPlainText(caption: RichBlockCaption | undefined): string {
+	if (!caption) return "";
+
+	const credit = caption.credit ? ` (${richTextToPlainText(caption.credit)})` : "";
+	return `${richTextToPlainText(caption.text)}${credit}\n`;
+}
+
+/** flatten one `RichBlock` (and its nested blocks) down to plain text, one block per line. */
+export function richBlockToPlainText(block: RichBlock): string {
+	switch (block.type) {
+		case "paragraph":
+			return `${richTextToPlainText(as<RichBlockParagraph>(block).text)}\n`;
+		case "heading":
+			return `${richTextToPlainText(as<RichBlockSectionHeading>(block).text)}\n`;
+		case "pre":
+			return `${richTextToPlainText(as<RichBlockPreformatted>(block).text)}\n`;
+		case "footer":
+			return `${richTextToPlainText(as<RichBlockFooter>(block).text)}\n`;
+		case "thinking":
+			return `${richTextToPlainText(as<RichBlockThinking>(block).text)}\n`;
+		case "divider":
+			return "---\n";
+		case "anchor":
+			return "";
+		case "mathematical_expression":
+			return `${as<RichBlockMathematicalExpression>(block).expression}\n`;
+		case "list": {
+			const { items } = as<RichBlockList>(block);
+			return `${items
+				.map((entry) => `- ${entry.blocks.map(richBlockToPlainText).join("").trim()}`)
+				.join("\n")}\n`;
+		}
+		case "blockquote": {
+			const { blocks, credit } = as<RichBlockBlockQuotation>(block);
+			return `${blocks.map(richBlockToPlainText).join("")}${credit ? ` — ${richTextToPlainText(credit)}` : ""}\n`;
+		}
+		case "pullquote": {
+			const { text, credit } = as<RichBlockPullQuotation>(block);
+			return `${richTextToPlainText(text)}${credit ? ` — ${richTextToPlainText(credit)}` : ""}\n`;
+		}
+		case "collage":
+		case "slideshow": {
+			const { blocks, caption } = as<RichBlockCollage | RichBlockSlideshow>(block);
+			return `${blocks.map(richBlockToPlainText).join("")}${captionToPlainText(caption)}`;
+		}
+		case "table": {
+			const { cells } = as<RichBlockTable>(block);
+			return `${cells.map((row) => row.map((c) => richTextToPlainText(c.text)).join(" | ")).join("\n")}\n`;
+		}
+		case "details": {
+			const { summary, blocks } = as<RichBlockDetails>(block);
+			return `${richTextToPlainText(summary)}\n${blocks.map(richBlockToPlainText).join("")}`;
+		}
+		case "map":
+			return captionToPlainText(as<RichBlockMap>(block).caption);
+		case "animation":
+		case "audio":
+		case "photo":
+		case "video":
+		case "voice_note": {
+			const { caption } = as<
+				RichBlockAnimation | RichBlockAudio | RichBlockPhoto | RichBlockVideo | RichBlockVoiceNote
+			>(block);
+			return captionToPlainText(caption);
+		}
+		default:
+			return "";
+	}
+}
+
+/** flatten a whole `RichMessage.blocks` tree to plain text — search indices, logs, notifications. */
+export function richMessageToPlainText(message: RichMessage): string {
+	return message.blocks.map(richBlockToPlainText).join("").trim();
+}

package/src/send.ts

@@ -0,0 +1,81 @@
+import type { Api, Context, Message, Plugin } from "@yaebal/core";
+import type { InputRichMessage } from "@yaebal/types";
+import { RichMessageDraft, type RichMessageDraftOptions } from "./draft.js";
+
+function toInput(input: InputRichMessage | string): InputRichMessage {
+	return typeof input === "string" ? { html: input } : input;
+}
+
+/**
+ * `sendRichMessage` — standalone, no plugin install required (the `@yaebal/fmt` /
+ * `@yaebal/keyboard` "pure helper" style). `extra` covers the rest of
+ * `SendRichMessageParams`: `reply_markup`, `reply_parameters`,
+ * `message_effect_id`, `disable_notification`, `protect_content`,
+ * `business_connection_id`, `message_thread_id`, `direct_messages_topic_id`,
+ * `allow_paid_broadcast`, `suggested_post_parameters`.
+ */
+export function sendRichMessage(
+	api: Api,
+	chatId: number | string,
+	input: InputRichMessage | string,
+	extra: Record<string, unknown> = {},
+): Promise<Message> {
+	return api.call<Message>("sendRichMessage", {
+		chat_id: chatId,
+		rich_message: toInput(input),
+		...extra,
+	});
+}
+
+/**
+ * `sendRichMessageDraft` — a single ephemeral (30s-ttl) push. private chats
+ * only. most callers want `RichMessageDraft` (draft.ts) instead, which keeps the
+ * ttl alive across a stream and forces a final `sendRichMessage` commit.
+ */
+export function sendRichMessageDraft(
+	api: Api,
+	chatId: number,
+	draftId: number,
+	input: InputRichMessage | string,
+	extra: Record<string, unknown> = {},
+): Promise<boolean> {
+	return api.call<boolean>("sendRichMessageDraft", {
+		chat_id: chatId,
+		draft_id: draftId,
+		rich_message: toInput(input),
+		...extra,
+	});
+}
+
+export interface RichContext {
+	/** `ctx.send`-flavored `sendRichMessage`, bound to the current chat. */
+	sendRichMessage(
+		input: InputRichMessage | string,
+		extra?: Record<string, unknown>,
+	): Promise<Message>;
+	/** open a `RichMessageDraft` streaming session bound to the current chat. */
+	richMessageDraft(draftId: number, options?: RichMessageDraftOptions): RichMessageDraft;
+}
+
+/** `bot.install(rich())` — adds `ctx.sendRichMessage` / `ctx.richMessageDraft`. */
+export function rich(): Plugin<Context, RichContext> {
+	return (composer) =>
+		composer.decorate<RichContext>({
+			sendRichMessage(this: Context, input, extra = {}) {
+				const chatId = this.chat?.id;
+				if (chatId === undefined) {
+					return Promise.reject(new Error("sendRichMessage(): no chat in this update"));
+				}
+
+				return sendRichMessage(this.api, chatId, input, extra);
+			},
+			richMessageDraft(this: Context, draftId, options) {
+				const chatId = this.chat?.id;
+				if (chatId === undefined) {
+					throw new Error("richMessageDraft(): no chat in this update");
+				}
+
+				return new RichMessageDraft(this.api, chatId, draftId, options);
+			},
+		});
+}