@prajwalshete/telegram-plugin 0.0.0-stage → 0.1.0

package/dist/core/template/parse.js

@@ -0,0 +1,369 @@
+import { ENTITY_RE } from "../html/escape.js";
+import { pathText } from "./ast.js";
+import { parseExpr, parsePath } from "./expr.js";
+import { ALLOWED_TAGS, checkAttrs, isAllowedTag } from "./tags.js";
+// src/core/template/parse.ts
+const OPEN_RE = /<([A-Za-z][A-Za-z0-9-]*)/y;
+const CLOSE_RE = /<\/([A-Za-z][A-Za-z0-9-]*)\s*>/y;
+const ATTR_NAME_RE = /[A-Za-z][A-Za-z0-9-]*/y;
+/** Parses a template (`{{…}}` tags inside the allowed Telegram HTML) into an AST. Never throws; errors carry 1-based positions. */
+function parseTemplate(src) {
+	const lineStarts = [0];
+	for (let k = 0; k < src.length; k++) if (src[k] === "\n") lineStarts.push(k + 1);
+	const pos = (at) => {
+		let lo = 0;
+		let hi = lineStarts.length - 1;
+		while (lo < hi) {
+			const mid = lo + hi + 1 >> 1;
+			if ((lineStarts[mid] ?? 0) <= at) lo = mid;
+			else hi = mid - 1;
+		}
+		return {
+			line: lo + 1,
+			column: at - (lineStarts[lo] ?? 0) + 1
+		};
+	};
+	const errors = [];
+	const fail = (code, at, message) => errors.push({
+		code,
+		message,
+		...pos(at)
+	});
+	const ast = {
+		type: "root",
+		children: []
+	};
+	const stack = [ast];
+	const top = () => stack[stack.length - 1] ?? ast;
+	const rejected = /* @__PURE__ */ new Map();
+	let buf = "";
+	let bufStart = 0;
+	const append = (s, at) => {
+		if (!buf) bufStart = at;
+		buf += s;
+	};
+	const flush = () => {
+		if (buf) top().children.push({
+			type: "text",
+			value: buf,
+			...pos(bufStart)
+		});
+		buf = "";
+	};
+	const push = (node) => {
+		flush();
+		top().children.push(node);
+	};
+	/** A section/comment tag alone on its line removes the whole line (as in Mustache). Returns the resume index. */
+	const standalone = (start, end) => {
+		let ls = start;
+		while (ls > 0 && (src[ls - 1] === " " || src[ls - 1] === "	")) ls--;
+		if (ls > 0 && src[ls - 1] !== "\n") return null;
+		let le = end;
+		while (le < src.length && (src[le] === " " || src[le] === "	")) le++;
+		if (le < src.length && src[le] !== "\n" && !(src[le] === "\r" && src[le + 1] === "\n")) return null;
+		buf = buf.replace(/[ \t]*$/, "");
+		return le >= src.length ? src.length : le + (src[le] === "\r" ? 2 : 1);
+	};
+	const varNode = (inner, innerStart, at) => {
+		const e = parseExpr(inner);
+		if ("message" in e) {
+			fail("syntax", innerStart + e.offset, e.message);
+			return null;
+		}
+		return {
+			type: "var",
+			path: e.path,
+			filters: e.filters.map((f, k) => ({
+				...f,
+				...pos(innerStart + (e.filterOffsets[k] ?? 0))
+			})),
+			...pos(at)
+		};
+	};
+	const mustache = (i) => {
+		if (src[i + 2] === "{") {
+			fail("raw_not_allowed", i, "{{{raw}}} output is not allowed; every value is escaped");
+			const end = src.indexOf("}}}", i + 3);
+			return end < 0 ? src.length : end + 3;
+		}
+		const end = src.indexOf("}}", i + 2);
+		if (end < 0) {
+			fail("syntax", i, "unclosed {{");
+			return src.length;
+		}
+		const raw = src.slice(i + 2, end);
+		const lead = raw.length - raw.trimStart().length;
+		const sigil = raw.trimStart()[0] ?? "";
+		const body = raw.trimStart().slice(1);
+		const tagEnd = end + 2;
+		switch (sigil) {
+			case "!": return standalone(i, tagEnd) ?? tagEnd;
+			case "#":
+			case "^": {
+				const path = parsePath(body);
+				if (path === null || path.length === 0) {
+					fail("syntax", i + 2 + lead + 1, `expected a variable name after {{${sigil}`);
+					return tagEnd;
+				}
+				const next = standalone(i, tagEnd);
+				const node = {
+					type: sigil === "#" ? "section" : "inverted",
+					path,
+					children: [],
+					...pos(i)
+				};
+				push(node);
+				stack.push(node);
+				return next ?? tagEnd;
+			}
+			case "/": {
+				const path = parsePath(body);
+				if (path === null) {
+					fail("syntax", i + 2 + lead + 1, "expected a variable name after {{/");
+					return tagEnd;
+				}
+				const next = standalone(i, tagEnd);
+				flush();
+				closeSection(pathText(path), i);
+				return next ?? tagEnd;
+			}
+			case "&":
+				fail("raw_not_allowed", i, "{{&raw}} output is not allowed; every value is escaped");
+				return tagEnd;
+			case ">":
+				fail("syntax", i, "partials ({{>name}}) are not supported");
+				return tagEnd;
+			case "=":
+				fail("syntax", i, "changing delimiters is not supported");
+				return tagEnd;
+			default: {
+				const node = varNode(raw, i + 2, i);
+				if (node) push(node);
+				return tagEnd;
+			}
+		}
+	};
+	const closeSection = (name, at) => {
+		let k = stack.length - 1;
+		while (k > 0) {
+			const c = stack[k];
+			if (c && (c.type === "section" || c.type === "inverted") && pathText(c.path) === name) break;
+			k--;
+		}
+		if (k === 0) {
+			fail("syntax", at, `{{/${name}}} has no matching {{#${name}}}`);
+			return;
+		}
+		while (stack.length - 1 > k) {
+			const c = stack.pop();
+			if (c?.type === "element") fail("nesting_invalid", at, `<${c.name}> must be closed before {{/${name}}}`);
+			else if (c && c.type !== "root") fail("unclosed", at, `{{#${pathText(c.path)}}} must be closed before {{/${name}}}`);
+		}
+		stack.pop();
+	};
+	const closeTag = (name, at) => {
+		let k = stack.length - 1;
+		while (k > 0) {
+			const c = stack[k];
+			if (c?.type !== "element") break;
+			if (c.name === name) break;
+			k--;
+		}
+		const c = stack[k];
+		if (k === 0 || !c || c.type !== "element" || c.name !== name) {
+			const inSection = stack.some((s) => s.type === "element" && s.name === name);
+			fail("nesting_invalid", at, inSection ? `</${name}> must close inside the same {{#section}} it opened in` : `</${name}> has no opening tag`);
+			return;
+		}
+		while (stack.length - 1 > k) {
+			const inner = stack.pop();
+			if (inner?.type === "element") fail("unclosed", at, `<${inner.name}> is not closed before </${name}>`);
+		}
+		stack.pop();
+	};
+	const nestingError = (name) => {
+		const parent = top();
+		for (const c of stack) {
+			if (c.type !== "element") continue;
+			if (c.name === "code") return "no tags are allowed inside <code>";
+			if (name === "blockquote" && c.name === "blockquote") return "<blockquote> cannot be nested";
+			if (name === "a" && c.name === "a") return "<a> cannot be nested";
+		}
+		if (parent.type === "element" && parent.name === "pre" && name !== "code") return "<pre> may contain only <code>";
+		return null;
+	};
+	/** Parses `<tag …>` at i. Returns the resume index. */
+	const openTag = (i) => {
+		OPEN_RE.lastIndex = i;
+		const rawName = OPEN_RE.exec(src)?.[1] ?? "";
+		let j = i + 1 + rawName.length;
+		const attrs = [];
+		for (;;) {
+			while (j < src.length && /\s/.test(src[j] ?? "")) j++;
+			if (j >= src.length) {
+				fail("syntax", i, `unclosed <${rawName}`);
+				return src.length;
+			}
+			if (src[j] === ">") break;
+			if (src[j] === "/" && src[j + 1] === ">") {
+				fail("syntax", i, "self-closing tags are not supported");
+				j++;
+				break;
+			}
+			ATTR_NAME_RE.lastIndex = j;
+			const an = ATTR_NAME_RE.exec(src)?.[0];
+			if (!an) {
+				fail("syntax", j, `unexpected "${src[j]}" in <${rawName}>`);
+				const close = src.indexOf(">", j);
+				return close < 0 ? src.length : close + 1;
+			}
+			j += an.length;
+			while (j < src.length && /\s/.test(src[j] ?? "")) j++;
+			if (src[j] !== "=") {
+				attrs.push({
+					name: an.toLowerCase(),
+					value: null
+				});
+				continue;
+			}
+			j++;
+			while (j < src.length && /\s/.test(src[j] ?? "")) j++;
+			const q = src[j];
+			if (q !== "\"" && q !== "'") {
+				fail("attr_invalid", j, "attribute values must be quoted");
+				const close = src.indexOf(">", j);
+				return close < 0 ? src.length : close + 1;
+			}
+			j++;
+			const parts = [];
+			let text = "";
+			while (j < src.length && src[j] !== q) {
+				if (src.startsWith("{{", j)) {
+					const end = src.indexOf("}}", j + 2);
+					if (end < 0) {
+						fail("syntax", j, "unclosed {{");
+						return src.length;
+					}
+					const inner = src.slice(j + 2, end);
+					const s = inner.trimStart()[0] ?? "";
+					if (src[j + 2] === "{" || "#^/!&>=".includes(s)) fail(src[j + 2] === "{" ? "raw_not_allowed" : "syntax", j, "only {{variables}} are allowed in attributes");
+					else {
+						const node = varNode(inner, j + 2, j);
+						if (node) {
+							if (text) parts.push({
+								type: "text",
+								value: text
+							});
+							text = "";
+							parts.push(node);
+						}
+					}
+					j = end + (src[end + 2] === "}" ? 3 : 2);
+					continue;
+				}
+				const c = src[j] ?? "";
+				if (c === "&") {
+					ENTITY_RE.lastIndex = j;
+					const e = ENTITY_RE.exec(src);
+					if (e) {
+						text += e[0];
+						j += e[0].length;
+						continue;
+					}
+					text += "&amp;";
+				} else if (c === "<") text += "&lt;";
+				else if (c === ">") text += "&gt;";
+				else text += c;
+				j++;
+			}
+			if (j >= src.length) {
+				fail("syntax", i, `unclosed attribute in <${rawName}>`);
+				return src.length;
+			}
+			if (text) parts.push({
+				type: "text",
+				value: text
+			});
+			attrs.push({
+				name: an.toLowerCase(),
+				value: parts
+			});
+			j++;
+		}
+		const end = j + 1;
+		const name = rawName.toLowerCase();
+		if (rawName !== name) {
+			fail("tag_not_allowed", i, `write tags in lowercase: <${name}>`);
+			rejected.set(rawName, (rejected.get(rawName) ?? 0) + 1);
+			return end;
+		}
+		if (!isAllowedTag(name)) {
+			fail("tag_not_allowed", i, `<${name}> is not allowed; Telegram supports ${ALLOWED_TAGS.join(", ")}`);
+			rejected.set(name, (rejected.get(name) ?? 0) + 1);
+			return end;
+		}
+		for (const msg of checkAttrs(name, attrs)) fail(msg.includes("href") ? "url_invalid" : "attr_invalid", i, msg);
+		const nest = nestingError(name);
+		if (nest) fail("nesting_invalid", i, nest);
+		const node = {
+			type: "element",
+			name,
+			attrs,
+			children: [],
+			...pos(i)
+		};
+		push(node);
+		stack.push(node);
+		return end;
+	};
+	let i = 0;
+	while (i < src.length) {
+		const c = src[i] ?? "";
+		if (c === "{" && src[i + 1] === "{") i = mustache(i);
+		else if (c === "<" && /[A-Za-z]/.test(src[i + 1] ?? "")) i = openTag(i);
+		else if (c === "<" && src[i + 1] === "/") {
+			CLOSE_RE.lastIndex = i;
+			const m = CLOSE_RE.exec(src);
+			if (!m) {
+				fail("syntax", i, "invalid closing tag");
+				append("&lt;", i);
+				i++;
+				continue;
+			}
+			const raw = m[1] ?? "";
+			const left = rejected.get(raw) ?? 0;
+			if (left > 0) rejected.set(raw, left - 1);
+			else if (!isAllowedTag(raw)) fail("tag_not_allowed", i, `</${raw}> is not allowed`);
+			else {
+				flush();
+				closeTag(raw, i);
+			}
+			i += m[0].length;
+		} else if (c === "&") {
+			ENTITY_RE.lastIndex = i;
+			const m = ENTITY_RE.exec(src);
+			append(m ? m[0] : "&amp;", i);
+			i += m ? m[0].length : 1;
+		} else {
+			append(c === "<" ? "&lt;" : c === ">" ? "&gt;" : c, i);
+			i++;
+		}
+	}
+	flush();
+	for (let k = stack.length - 1; k > 0; k--) {
+		const c = stack[k];
+		if (!c || c.type === "root") continue;
+		errors.push({
+			code: "unclosed",
+			message: c.type === "element" ? `<${c.name}> is not closed` : `{{#${pathText(c.path)}}} is not closed`,
+			line: c.line,
+			column: c.column
+		});
+	}
+	return {
+		ast,
+		errors
+	};
+}
+export { parseTemplate };

package/dist/core/template/render.d.ts

@@ -0,0 +1,17 @@
+import { CoreTemplateError, TemplateAst } from "./ast.js";
+import { FilterContext, FilterRegistry } from "./filters.js";
+/** Data and formatting context for {@link renderTemplate}. */
+export interface RenderContext extends FilterContext {
+  /** Root variables object. */
+  vars: unknown;
+  /** Host filters (override built-ins). */
+  filters?: FilterRegistry | undefined;
+}
+/** Result of {@link renderTemplate}. */
+export interface RenderResult {
+  html: string;
+  /** Filter failures and dropped links (rendering never throws on data). */
+  warnings: CoreTemplateError[];
+}
+/** Renders an AST to Telegram HTML. Values are escaped; never throws on data (problems become `warnings`). */
+export declare function renderTemplate(ast: TemplateAst, ctx: RenderContext): RenderResult;

package/dist/core/template/render.js

@@ -0,0 +1,118 @@
+import { escapeHtml } from "../html/escape.js";
+import { renderedAttrOk } from "./tags.js";
+import { resolveFilter } from "./filters.js";
+// src/core/template/render.ts
+/** Own-property lookup only, so `{{constructor}}` or `{{__proto__}}` never reach prototypes. */
+function get(obj, key) {
+	if (obj === null || typeof obj !== "object") return void 0;
+	if (Array.isArray(obj) && key === "length") return obj.length;
+	return Object.hasOwn(obj, key) ? obj[key] : void 0;
+}
+function lookup(path, stack) {
+	if (path.length === 0) return stack[stack.length - 1];
+	const [head, ...rest] = path;
+	if (head === void 0) return void 0;
+	let value;
+	for (let k = stack.length - 1; k >= 0; k--) {
+		const scope = stack[k];
+		if (scope !== null && typeof scope === "object" && Object.hasOwn(scope, head)) {
+			value = get(scope, head);
+			break;
+		}
+	}
+	for (const key of rest) value = get(value, key);
+	return value;
+}
+function isFalsy(v) {
+	return v === void 0 || v === null || v === false || v === "" || v === 0 || Number.isNaN(v) || Array.isArray(v) && v.length === 0;
+}
+function stringify(v) {
+	if (v === null || v === void 0) return "";
+	if (typeof v === "string") return v;
+	if (typeof v === "number") return Number.isFinite(v) ? String(v) : "";
+	if (typeof v === "boolean" || typeof v === "bigint") return String(v);
+	if (Array.isArray(v)) return v.map(stringify).filter(Boolean).join(", ");
+	return "";
+}
+/** Renders an AST to Telegram HTML. Values are escaped; never throws on data (problems become `warnings`). */
+function renderTemplate(ast, ctx) {
+	const warnings = [];
+	const value = (node, stack) => {
+		let v = lookup(node.path, stack);
+		for (const call of node.filters) {
+			const f = resolveFilter(call.name, ctx.filters);
+			if (!f) {
+				warnings.push({
+					code: "filter_unknown",
+					message: `unknown filter "${call.name}"`,
+					line: call.line,
+					column: call.column
+				});
+				continue;
+			}
+			try {
+				v = f.apply(v, call.args, ctx);
+			} catch (e) {
+				const msg = e instanceof Error ? e.message : "failed";
+				warnings.push({
+					code: "render",
+					message: `filter "${call.name}": ${msg}`,
+					line: call.line,
+					column: call.column
+				});
+				v = "";
+			}
+		}
+		return escapeHtml(stringify(v));
+	};
+	const element = (node, stack) => {
+		let attrs = "";
+		for (const a of node.attrs) {
+			if (a.value === null) {
+				attrs += ` ${a.name}`;
+				continue;
+			}
+			const text = a.value.map((p) => p.type === "text" ? p.value : value(p, stack)).join("");
+			if (!renderedAttrOk(node.name, a.name, text)) {
+				warnings.push({
+					code: "url_invalid",
+					message: `<${node.name} ${a.name}> rendered an unsafe value; the tag was dropped`,
+					line: node.line,
+					column: node.column
+				});
+				return nodes(node.children, stack);
+			}
+			attrs += ` ${a.name}="${text}"`;
+		}
+		return `<${node.name}${attrs}>${nodes(node.children, stack)}</${node.name}>`;
+	};
+	const nodes = (list, stack) => {
+		let out = "";
+		for (const node of list) switch (node.type) {
+			case "text":
+				out += node.value;
+				break;
+			case "var":
+				out += value(node, stack);
+				break;
+			case "element":
+				out += element(node, stack);
+				break;
+			case "section": {
+				const v = lookup(node.path, stack);
+				if (isFalsy(v)) break;
+				if (Array.isArray(v)) for (const item of v) out += nodes(node.children, [...stack, item]);
+				else if (v === true) out += nodes(node.children, stack);
+				else out += nodes(node.children, [...stack, v]);
+				break;
+			}
+			case "inverted": if (isFalsy(lookup(node.path, stack))) out += nodes(node.children, stack);
+		}
+		return out;
+	};
+	return {
+		html: nodes(ast.children, [ctx.vars]),
+		warnings
+	};
+}
+export { isFalsy, renderTemplate };

package/dist/core/template/shape.d.ts

@@ -0,0 +1,28 @@
+/** Simplified type of template variables (from {@link zodToShape}), used to check paths and sections. */
+export type Shape = {
+  kind: "object";
+  fields: Readonly<Record<string, Shape>>;
+  optional: boolean;
+} | {
+  kind: "array";
+  item: Shape;
+  optional: boolean;
+} | {
+  kind: "enum";
+  values: readonly string[];
+  optional: boolean;
+} | {
+  kind: "string" | "number" | "boolean" | "date" | "record" | "unknown";
+  optional: boolean;
+};
+/** Zod 4 schema (objects, arrays, optional, nullable, default, primitives, enums, literals, unions) → `Shape`. */
+export declare function zodToShape(schema: unknown, depth?: number): Shape;
+/** One variable path offered by a {@link Shape} (see {@link shapeVariables}). */
+export interface ShapeVariable {
+  /** Dotted path; list items use `[]` (`projects[].name`). */
+  path: string;
+  kind: Shape["kind"];
+  optional: boolean;
+}
+/** Every variable a schema offers, for UI variable pickers. */
+export declare function shapeVariables(shape: Shape, prefix?: string, out?: ShapeVariable[]): ShapeVariable[];

package/dist/core/template/shape.js

@@ -0,0 +1,151 @@
+// src/core/template/shape.ts
+function isZodLike(v) {
+	if (v === null || typeof v !== "object" || !("_zod" in v)) return false;
+	const z = v._zod;
+	return z !== null && typeof z === "object" && "def" in z;
+}
+const OPTIONAL_WRAPPERS = /* @__PURE__ */ new Set([
+	"optional",
+	"nullable",
+	"nullish"
+]);
+const TRANSPARENT_WRAPPERS = /* @__PURE__ */ new Set([
+	"default",
+	"prefault",
+	"readonly",
+	"catch",
+	"nonoptional",
+	"success"
+]);
+function withOptional(s, optional) {
+	return optional && !s.optional ? {
+		...s,
+		optional: true
+	} : s;
+}
+/** Zod 4 schema (objects, arrays, optional, nullable, default, primitives, enums, literals, unions) → `Shape`. */
+function zodToShape(schema, depth = 0) {
+	if (!isZodLike(schema) || depth > 32) return {
+		kind: "unknown",
+		optional: false
+	};
+	const def = schema._zod.def;
+	const t = def.type;
+	if (OPTIONAL_WRAPPERS.has(t) && def.innerType) return withOptional(zodToShape(def.innerType, depth + 1), true);
+	if (TRANSPARENT_WRAPPERS.has(t) && def.innerType) {
+		const inner = zodToShape(def.innerType, depth + 1);
+		return t === "nonoptional" ? {
+			...inner,
+			optional: false
+		} : inner;
+	}
+	switch (t) {
+		case "object": {
+			const fields = {};
+			for (const [k, v] of Object.entries(def.shape ?? {})) fields[k] = zodToShape(v, depth + 1);
+			return {
+				kind: "object",
+				fields,
+				optional: false
+			};
+		}
+		case "array": return {
+			kind: "array",
+			item: zodToShape(def.element, depth + 1),
+			optional: false
+		};
+		case "string":
+		case "number":
+		case "boolean":
+		case "date": return {
+			kind: t,
+			optional: false
+		};
+		case "int":
+		case "bigint": return {
+			kind: "number",
+			optional: false
+		};
+		case "enum": return {
+			kind: "enum",
+			values: Object.values(def.entries ?? {}).map(String),
+			optional: false
+		};
+		case "literal": {
+			const vals = def.values ?? [];
+			if (vals.every((v) => typeof v === "boolean")) return {
+				kind: "boolean",
+				optional: false
+			};
+			if (vals.every((v) => typeof v === "number")) return {
+				kind: "number",
+				optional: false
+			};
+			return {
+				kind: "enum",
+				values: vals.map(String),
+				optional: false
+			};
+		}
+		case "record":
+		case "map": return {
+			kind: "record",
+			optional: false
+		};
+		case "pipe": return zodToShape(def.out?._zod.def.type === "transform" ? def.in : def.out, depth + 1);
+		case "union": return unionShape((def.options ?? []).map((o) => zodToShape(o, depth + 1)));
+		case "null":
+		case "undefined":
+		case "void": return {
+			kind: "unknown",
+			optional: true
+		};
+		default: return {
+			kind: "unknown",
+			optional: false
+		};
+	}
+}
+/** Unions of objects merge their fields (fields not in every option become optional). */
+function unionShape(options) {
+	const optional = options.some((o) => o.optional);
+	const real = options.filter((o) => !(o.kind === "unknown" && o.optional));
+	if (real.length === 1 && real[0]) return withOptional(real[0], optional);
+	if (real.length > 0 && real.every((o) => o.kind === "object")) {
+		const fields = {};
+		for (const o of real) {
+			if (o.kind !== "object") continue;
+			for (const [k, v] of Object.entries(o.fields)) fields[k] ??= v;
+		}
+		for (const k of Object.keys(fields)) {
+			const inAll = real.every((o) => o.kind === "object" && Object.hasOwn(o.fields, k));
+			const f = fields[k];
+			if (f && !inAll) fields[k] = withOptional(f, true);
+		}
+		return {
+			kind: "object",
+			fields,
+			optional
+		};
+	}
+	if (new Set(real.map((o) => o.kind)).size === 1 && real[0] && real[0].kind !== "object" && real[0].kind !== "array") return withOptional(real[0], optional);
+	return {
+		kind: "unknown",
+		optional
+	};
+}
+/** Every variable a schema offers, for UI variable pickers. */
+function shapeVariables(shape, prefix = "", out = []) {
+	if (shape.kind === "object") for (const [k, v] of Object.entries(shape.fields)) {
+		const path = prefix ? `${prefix}.${k}` : k;
+		out.push({
+			path,
+			kind: v.kind,
+			optional: v.optional
+		});
+		shapeVariables(v, path, out);
+	}
+	else if (shape.kind === "array") shapeVariables(shape.item, `${prefix}[]`, out);
+	return out;
+}
+export { shapeVariables, zodToShape };