@prajwalshete/telegram-plugin 0.0.0-stage → 0.1.1

package/dist/contracts/templates.js

@@ -0,0 +1,174 @@
+import { EpochMs, Id, JsonObject, Key, Locale, LocalizedText } from "./common.js";
+import { TemplateError } from "./problems.js";
+import { z } from "zod";
+// src/contracts/templates.ts
+/** `message` renders chat text; `report` renders a file (PDF/CSV) with a caption. */
+const TEMPLATE_KINDS = ["message", "report"];
+/** Zod enum of {@link TEMPLATE_KINDS}. */
+const TemplateKind = z.enum(TEMPLATE_KINDS);
+/** Body syntax: Telegram HTML subset, or plain text (escaped on send). */
+const TEMPLATE_FORMATS = ["html", "text"];
+/** Zod enum of {@link TEMPLATE_FORMATS}. */
+const TemplateFormat = z.enum(TEMPLATE_FORMATS);
+/** Report file formats with built-in renderers. */
+const REPORT_FORMATS = ["pdf", "csv"];
+/** Zod enum of {@link REPORT_FORMATS}. */
+const ReportFormat = z.enum(REPORT_FORMATS);
+/** Optional inline button styles. */
+const BUTTON_STYLES = [
+	"primary",
+	"success",
+	"danger"
+];
+/** Zod enum of {@link BUTTON_STYLES}. */
+const ButtonStyle = z.enum(BUTTON_STYLES);
+/** One inline button in a template. Exactly one of `action` or `url`. Params may hold `{{variables}}`. */
+const ButtonSpec = z.object({
+	text: LocalizedText,
+	/** Registered action key (`defineAction`) run on tap. */
+	action: Key.optional(),
+	params: JsonObject.optional(),
+	url: z.string().max(2048).optional(),
+	style: ButtonStyle.optional(),
+	/** Shown but not tappable. */
+	disabled: z.boolean().optional()
+}).refine((b) => b.action === void 0 !== (b.url === void 0), "exactly one of action or url");
+/** Rows of buttons (Telegram: ≤ 8 per row, ≤ 100 total). */
+const ButtonRows = z.array(z.array(ButtonSpec).min(1).max(8)).max(12);
+/** How a `report` template renders its file. */
+const ReportSpec = z.object({
+	/** Default file format. */
+	renderer: ReportFormat,
+	/** File name template, for example `daily-{{date|date}}.pdf`. */
+	fileName: z.string().min(1).max(128),
+	/** Renderer-specific layout; the built-ins read {@link ReportLayout}. */
+	layout: JsonObject.optional()
+});
+/** Bot API send options: `silent` = `disable_notification`, `protectContent`, `linkPreview` (default off). */
+const TemplateOptions = z.object({
+	silent: z.boolean().optional(),
+	protectContent: z.boolean().optional(),
+	linkPreview: z.boolean().optional()
+});
+/** A saved template (`/admin/templates`, permission `telegram.templates.manage`). */
+const TemplateDto = z.object({
+	id: Id,
+	key: Key,
+	name: z.string(),
+	kind: TemplateKind,
+	/** Data provider key that supplies the template variables, or null. */
+	provider: Key.nullable(),
+	/** Fixed params passed to the provider, or null. */
+	providerParams: JsonObject.nullable(),
+	/** Template source per locale. */
+	body: LocalizedText,
+	format: TemplateFormat,
+	report: ReportSpec.nullable(),
+	buttons: ButtonRows.nullable(),
+	options: TemplateOptions,
+	/** Increments on every save; older versions are kept. */
+	version: z.number().int().min(1),
+	/** Host user id of the last editor, or null. */
+	updatedBy: z.string().nullable(),
+	updatedAt: EpochMs
+});
+/** `POST`/`PUT /admin/templates` body (defaults: `message`, `html`, no provider, no buttons). Invalid source fails with `template_invalid`. */
+const TemplateSave = z.object({
+	key: Key,
+	name: z.string().trim().min(1).max(120),
+	kind: TemplateKind.default("message"),
+	provider: Key.nullable().default(null),
+	providerParams: JsonObject.nullable().default(null),
+	body: LocalizedText,
+	format: TemplateFormat.default("html"),
+	report: ReportSpec.nullable().default(null),
+	buttons: ButtonRows.nullable().default(null),
+	options: TemplateOptions.default({})
+});
+/** One saved version (`GET /admin/templates/:id/versions`; restore with `POST …/restore/:version`). */
+const TemplateVersionDto = z.object({
+	templateId: Id,
+	version: z.number().int().min(1),
+	body: LocalizedText,
+	report: ReportSpec.nullable(),
+	buttons: ButtonRows.nullable(),
+	savedBy: z.string().nullable(),
+	savedAt: EpochMs
+});
+/** Preview as a role or a user, so the admin sees exactly what that audience gets. */
+const PreviewAs = z.union([z.strictObject({ role: z.string().min(1) }), z.strictObject({ userId: z.string().min(1) })]);
+/** `POST /admin/templates/preview`: render a saved template (`templateId`) or unsaved `source`. */
+const TemplatePreviewRequest = z.object({
+	templateId: Id.optional(),
+	/** Unsaved template source for `locale`. */
+	source: z.string().max(2e4).optional(),
+	buttons: ButtonRows.optional(),
+	format: TemplateFormat.optional(),
+	provider: Key.optional(),
+	params: JsonObject.optional(),
+	as: PreviewAs,
+	locale: Locale,
+	/** Use the provider's `sample()` instead of live data. */
+	sample: z.boolean().optional()
+}).refine((r) => r.templateId === void 0 !== (r.source === void 0), "exactly one of templateId or source");
+/** A rendered inline button (callback data is not exposed in previews). */
+const PreviewButton = z.object({
+	text: z.string(),
+	kind: z.enum(["action", "url"]),
+	url: z.string().nullable(),
+	style: ButtonStyle.nullable(),
+	disabled: z.boolean()
+});
+/** A file a preview would attach (`size` in bytes, null if unknown). */
+const PreviewFile = z.object({
+	name: z.string(),
+	mime: z.string(),
+	size: z.number().int().nullable()
+});
+/** Rendered preview; `warnings` are non-fatal template issues. */
+const TemplatePreviewResponse = z.object({
+	/** Telegram HTML, one entry per message part (≤ 4096 chars each). */
+	parts: z.array(z.string()),
+	buttons: z.array(z.array(PreviewButton)).nullable(),
+	file: PreviewFile.nullable(),
+	warnings: z.array(TemplateError)
+});
+/** Cell formats. `money` reads integer minor units; `date`/`datetime` read epoch ms (or ISO) in the report's zone. */
+const REPORT_COLUMN_FORMATS = [
+	"text",
+	"number",
+	"money",
+	"date",
+	"datetime",
+	"yesno"
+];
+/** Zod enum of {@link REPORT_COLUMN_FORMATS}. */
+const ReportColumnFormat = z.enum(REPORT_COLUMN_FORMATS);
+/** One report column: a field of each row (dotted path), its header and how the value is written. */
+const ReportColumn = z.object({
+	key: z.string().regex(/^[A-Za-z_][A-Za-z0-9_]*(\.[A-Za-z_][A-Za-z0-9_]*)*$/, "path"),
+	label: z.union([LocalizedText, z.string().min(1).max(128)]),
+	format: ReportColumnFormat.default("text")
+});
+/**
+* `report_json.layout` for the built-in renderers: `rows` names the provider variable holding the row array
+* (default: the first array variable); `columns` picks and labels fields (default: every field of the first row).
+*/
+const ReportLayout = z.object({
+	rows: z.string().regex(/^[A-Za-z_][A-Za-z0-9_]*(\.[A-Za-z_][A-Za-z0-9_]*)*$/, "path").optional(),
+	columns: z.array(ReportColumn).min(1).max(100).optional(),
+	/** Report heading, per locale. */
+	title: LocalizedText.optional()
+});
+/** Filters for `GET /admin/templates`. */
+const TemplateQuery = z.object({ kind: TemplateKind.optional() });
+/** `POST /admin/reports/render`: the same file the bot would send, as a download. */
+const ReportRenderRequest = z.object({
+	/** Report template key. */
+	template: Key,
+	params: JsonObject.optional(),
+	as: PreviewAs,
+	format: ReportFormat.optional(),
+	locale: Locale.optional()
+});
+export { BUTTON_STYLES, ButtonRows, ButtonSpec, ButtonStyle, PreviewAs, PreviewButton, PreviewFile, REPORT_COLUMN_FORMATS, REPORT_FORMATS, ReportColumn, ReportColumnFormat, ReportFormat, ReportLayout, ReportRenderRequest, ReportSpec, TEMPLATE_FORMATS, TEMPLATE_KINDS, TemplateDto, TemplateFormat, TemplateKind, TemplateOptions, TemplatePreviewRequest, TemplatePreviewResponse, TemplateQuery, TemplateSave, TemplateVersionDto };

package/dist/contracts/users.d.ts

@@ -0,0 +1,15 @@
+import { z } from "zod";
+/** `GET /admin/users?q=`: search the host's users for linking screens (needs `ports.users.search`). */
+export declare const UserQuery: z.ZodObject<{
+  q: z.ZodString;
+  limit: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+}, z.core.$strip>;
+export type UserQuery = z.infer<typeof UserQuery>;
+/** One app user as the linking screen shows it (from `UsersPort`). */
+export declare const UserDto: z.ZodObject<{
+  id: z.ZodString;
+  name: z.ZodString;
+  role: z.ZodNullable<z.ZodString>;
+  locale: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type UserDto = z.infer<typeof UserDto>;

package/dist/contracts/users.js

@@ -0,0 +1,19 @@
+import { z } from "zod";
+// src/contracts/users.ts
+/** `GET /admin/users?q=`: search the host's users for linking screens (needs `ports.users.search`). */
+const UserQuery = z.object({
+	/** Name, phone, e-mail or id fragment, as the host's `UsersPort.search` understands it. */
+	q: z.string().trim().min(1).max(100),
+	/** Max results. Default 20, at most 50. */
+	limit: z.coerce.number().int().min(1).max(50).default(20)
+});
+/** One app user as the linking screen shows it (from `UsersPort`). */
+const UserDto = z.object({
+	id: z.string().min(1),
+	name: z.string(),
+	/** The user's host role, or null. */
+	role: z.string().nullable(),
+	/** Preferred locale, if the host knows it. */
+	locale: z.string().optional()
+});
+export { UserDto, UserQuery };

package/dist/core/guards.d.ts

@@ -0,0 +1,22 @@
+/** Why {@link checkAiText} rejected a text (reported in `send_text_rejected` problems as `reasons`). */
+export type AiTextReason = "empty" | "too_long" | "money" | "url" | "phone" | "email";
+/** Options for {@link checkAiText}. */
+export interface AiTextOptions {
+  /** May the audience see money? When false, money-like text is rejected. */
+  audienceSeesMoney: boolean;
+  /** Allow phone numbers and emails (host setting). */
+  allowContacts?: boolean;
+  /** The app's own domains (`app.example.com`); links to them (and subdomains) are allowed. */
+  appDomains?: readonly string[];
+  /** Max length (default {@link AI_TEXT_MAX}). */
+  maxLength?: number;
+}
+/** Result of {@link checkAiText}. */
+export type AiTextCheck = {
+  ok: true;
+} | {
+  ok: false;
+  reasons: AiTextReason[];
+};
+/** Conservative content check for AI-written text: empty/too long, foreign links, contacts, and money unless the audience may see it. */
+export declare function checkAiText(text: string, opts: AiTextOptions): AiTextCheck;

package/dist/core/guards.js

@@ -0,0 +1,47 @@
+// src/core/guards.ts
+/** Default max length (UTF-16 units) of AI-written text. */
+const AI_TEXT_MAX = 1e3;
+const D = "[0-9०-९]";
+const MONEY_PATTERNS = [
+	/[₹$€£¥]/u,
+	/(?<![A-Za-z])(?:rs|inr|usd|eur|gbp)\.?(?![A-Za-z])/iu,
+	new RegExp(`${D}\\s*/-`, "u"),
+	/(?<![A-Za-z])(?:lakh|lakhs|lac|lacs|crore|crores)(?![A-Za-z])/iu,
+	/लाख|कोटी|करोड|रुपये|रुपया|रु\./u,
+	new RegExp(`(?<!${D})${D}{1,3}(?:,${D}{2,3})+(?:\\.${D}+)?(?!${D})`, "u"),
+	new RegExp(`${D}+(?:\\.${D}+)?\\s*(?:k|K|L|cr|Cr|CR)(?![A-Za-z])`, "u")
+];
+const URL_RE = /\b(?:https?:\/\/|www\.)[^\s<>"]+|\b(?:[a-z0-9-]+\.)+(?:com|in|net|org|io|app|dev|co|me|ly|xyz|info|biz|link|site|online|page|ai)\b(?:\/[^\s<>"]*)?|\bt\.me\/[^\s]+/giu;
+const EMAIL_RE = /[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}/u;
+const PHONE_RE = new RegExp(`(?<![0-9०-९])\\+?(?:${D}[\\s\\-.()]?){9,12}${D}(?![0-9०-९])`, "u");
+function hostOf(raw) {
+	return (raw.replace(/^https?:\/\//i, "").replace(/^www\./i, "").split(/[/?#:]/)[0] ?? "").toLowerCase();
+}
+function allowedHost(host, domains) {
+	return domains.some((d) => {
+		const dom = d.toLowerCase().replace(/^\.+/, "");
+		return host === dom || host.endsWith(`.${dom}`);
+	});
+}
+/** Conservative content check for AI-written text: empty/too long, foreign links, contacts, and money unless the audience may see it. */
+function checkAiText(text, opts) {
+	const reasons = [];
+	const t = text.normalize("NFC");
+	if (t.trim().length === 0) reasons.push("empty");
+	if (t.length > (opts.maxLength ?? 1e3)) reasons.push("too_long");
+	const withoutEmails = t.replace(new RegExp(EMAIL_RE.source, "gu"), " ");
+	for (const m of withoutEmails.matchAll(URL_RE)) if (!allowedHost(hostOf(m[0]), opts.appDomains ?? [])) {
+		reasons.push("url");
+		break;
+	}
+	if (!opts.allowContacts) {
+		if (EMAIL_RE.test(t)) reasons.push("email");
+		if (PHONE_RE.test(withoutEmails)) reasons.push("phone");
+	}
+	if (!opts.audienceSeesMoney && MONEY_PATTERNS.some((re) => re.test(withoutEmails))) reasons.push("money");
+	return reasons.length === 0 ? { ok: true } : {
+		ok: false,
+		reasons
+	};
+}
+export { AI_TEXT_MAX, checkAiText };

package/dist/core/html/escape.d.ts

@@ -0,0 +1,2 @@
+/** Escapes `& < > "` so a value is safe in Telegram HTML text and in double-quoted attributes. */
+export declare function escapeHtml(value: string): string;

package/dist/core/html/escape.js

@@ -0,0 +1,36 @@
+// src/core/html/escape.ts
+const ESCAPES = {
+	"&": "&",
+	"<": "&lt;",
+	">": "&gt;",
+	"\"": "&quot;"
+};
+/** Escapes `& < > "` so a value is safe in Telegram HTML text and in double-quoted attributes. */
+function escapeHtml(value) {
+	return value.replace(/[&<>"]/g, (c) => ESCAPES[c] ?? c);
+}
+const NAMED = {
+	lt: "<",
+	gt: ">",
+	amp: "&",
+	quot: "\""
+};
+/** Matches one entity Telegram accepts. */
+const ENTITY_RE = /&(?:lt|gt|amp|quot|#\d{1,7}|#[xX][0-9a-fA-F]{1,6});/y;
+/** Decodes one entity (`&amp;`, `&#128077;`, `&#x1F44D;`). Unknown input is returned unchanged. */
+function decodeEntity(entity) {
+	const body = entity.slice(1, -1);
+	const named = NAMED[body];
+	if (named !== void 0) return named;
+	if (body.startsWith("#")) {
+		const hex = body[1] === "x" || body[1] === "X";
+		const code = Number.parseInt(body.slice(hex ? 2 : 1), hex ? 16 : 10);
+		if (Number.isFinite(code) && code >= 0 && code <= 1114111) return String.fromCodePoint(code);
+	}
+	return entity;
+}
+/** Decodes every entity in a text run. */
+function decodeEntities(text) {
+	return text.replace(/&(?:lt|gt|amp|quot|#\d{1,7}|#[xX][0-9a-fA-F]{1,6});/g, decodeEntity);
+}
+export { ENTITY_RE, decodeEntities, decodeEntity, escapeHtml };

package/dist/core/html/tokenize.js

@@ -0,0 +1,65 @@
+import { ENTITY_RE, decodeEntity } from "./escape.js";
+// src/core/html/tokenize.ts
+const TAG_RE = /<(\/?)([a-zA-Z][a-zA-Z0-9-]*)((?:\s+[a-zA-Z-]+(?:\s*=\s*(?:"[^"]*"|'[^']*'))?)*)\s*>/y;
+const ATTR_RE = /([a-zA-Z-]+)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'))?/g;
+function parseAttrs(src) {
+	const out = {};
+	for (const m of src.matchAll(ATTR_RE)) {
+		const name = m[1];
+		if (name !== void 0) out[name.toLowerCase()] = m[2] ?? m[3] ?? "";
+	}
+	return out;
+}
+function tokenizeHtml(html) {
+	const out = [];
+	let text = "";
+	const flush = () => {
+		if (text) out.push({
+			type: "text",
+			raw: text
+		});
+		text = "";
+	};
+	let i = 0;
+	while (i < html.length) {
+		const c = html[i];
+		if (c === "<") {
+			TAG_RE.lastIndex = i;
+			const m = TAG_RE.exec(html);
+			if (m) {
+				flush();
+				const name = (m[2] ?? "").toLowerCase();
+				out.push(m[1] === "/" ? {
+					type: "close",
+					raw: m[0],
+					name
+				} : {
+					type: "open",
+					raw: m[0],
+					name,
+					attrs: parseAttrs(m[3] ?? "")
+				});
+				i += m[0].length;
+				continue;
+			}
+		} else if (c === "&") {
+			ENTITY_RE.lastIndex = i;
+			const m = ENTITY_RE.exec(html);
+			if (m) {
+				flush();
+				out.push({
+					type: "entity",
+					raw: m[0],
+					text: decodeEntity(m[0])
+				});
+				i += m[0].length;
+				continue;
+			}
+		}
+		text += c;
+		i++;
+	}
+	flush();
+	return out;
+}
+export { tokenizeHtml };

package/dist/core/index.d.ts

@@ -0,0 +1,18 @@
+import { RandomFill } from "./random.js";
+import { Attr, AttrPart, CoreTemplateError, ElementNode, FilterArg, FilterCall, Node, Pos, SectionNode, TemplateAst, TemplateErrorCode, TextNode, VarNode } from "./template/ast.js";
+import { FormatContext, Numerals } from "./template/format.js";
+import { BUILTIN_FILTERS, FilterContext, FilterDef, FilterFn, FilterRegistry, defineFilter } from "./template/filters.js";
+import { AiTextCheck, AiTextOptions, AiTextReason, checkAiText } from "./guards.js";
+import { escapeHtml } from "./html/escape.js";
+import { describeRule } from "./schedule/describe.js";
+import { RuleCheck, ScheduleErrorCode, nextRuns, validateRule } from "./schedule/rule.js";
+import { isValidTimeZone } from "./schedule/tz.js";
+import { toPlainText } from "./split/plain.js";
+import { CAPTION_LIMIT, SplitOptions, TEXT_LIMIT, splitMessage, visibleLength } from "./split/split.js";
+import { ValidateOptions, validateTemplate } from "./template/validate.js";
+import { ParseResult, parseTemplate } from "./template/parse.js";
+import { RenderContext, RenderResult, renderTemplate } from "./template/render.js";
+import { Shape, ShapeVariable, shapeVariables, zodToShape } from "./template/shape.js";
+import { VariableRef, listVariables } from "./template/variables.js";
+import { CompileResult, compileTemplate } from "./template/index.js";
+export { AiTextCheck, AiTextOptions, AiTextReason, Attr, AttrPart, BUILTIN_FILTERS, CAPTION_LIMIT, CompileResult, CoreTemplateError, ElementNode, FilterArg, FilterCall, FilterContext, FilterDef, FilterFn, FilterRegistry, FormatContext, Node, Numerals, ParseResult, Pos, RandomFill, RenderContext, RenderResult, RuleCheck, ScheduleErrorCode, SectionNode, Shape, ShapeVariable, SplitOptions, TEXT_LIMIT, TemplateAst, TemplateErrorCode, TextNode, ValidateOptions, VarNode, VariableRef, checkAiText, compileTemplate, defineFilter, describeRule, escapeHtml, isValidTimeZone, listVariables, nextRuns, parseTemplate, renderTemplate, shapeVariables, splitMessage, toPlainText, validateRule, validateTemplate, visibleLength, zodToShape };

package/dist/core/pacing.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/core/pacing.js

@@ -0,0 +1,86 @@
+// src/core/pacing.ts
+const BACKOFF_BASE_MS = 5e3;
+const BACKOFF_CAP_MS = 36e5;
+/**
+* Delay before retry number `attempt` (0-based): 5 s · 2^attempt, ±20 % jitter, capped at 1 h.
+* `rand` returns [0, 1) (inject `Math.random` or a seeded source in tests).
+*/
+function nextBackoff(attempt, rand) {
+	const exp = BACKOFF_BASE_MS * 2 ** Math.max(0, Math.min(30, Math.floor(attempt)));
+	const jitter = 1 + (Math.min(1, Math.max(0, rand())) * 2 - 1) * .2;
+	return Math.min(BACKOFF_CAP_MS, Math.round(exp * jitter));
+}
+const PACING_DEFAULTS = {
+	/** Per bot (Telegram allows ~30/s). */
+	perBotPerSec: 25,
+	/** Per chat: one message every 1.1 s. */
+	perChatIntervalMs: 1100,
+	/** Groups, supergroups and channels: 18 per minute (Telegram allows 20). */
+	perGroupPerMin: 18
+};
+/** Token bucket: `ratePerSec` refill, `burst` capacity (default = rate). A null state starts full. */
+function takeToken(state, now, cfg) {
+	const burst = cfg.burst ?? cfg.ratePerSec;
+	const prev = state ?? {
+		tokens: burst,
+		at: now
+	};
+	const tokens = Math.min(burst, prev.tokens + Math.max(0, now - prev.at) * cfg.ratePerSec / 1e3);
+	if (tokens >= 1) return {
+		ok: true,
+		state: {
+			tokens: tokens - 1,
+			at: now
+		}
+	};
+	return {
+		ok: false,
+		state: {
+			tokens,
+			at: now
+		},
+		waitMs: Math.ceil((1 - tokens) * 1e3 / cfg.ratePerSec)
+	};
+}
+/** Can this chat get a message now? Private chats: interval only. Groups/channels: interval + per-minute window. */
+function takeChatSlot(state, now, kind, limits = {}) {
+	const interval = limits.perChatIntervalMs ?? PACING_DEFAULTS.perChatIntervalMs;
+	const perMin = limits.perGroupPerMin ?? PACING_DEFAULTS.perGroupPerMin;
+	if (state.nextAllowedAt !== null && state.nextAllowedAt > now) return {
+		ok: false,
+		state,
+		waitMs: state.nextAllowedAt - now
+	};
+	let windowStart = state.windowStart;
+	let windowCount = state.windowCount;
+	if (kind !== "private") {
+		if (windowStart === null || now - windowStart >= 6e4) {
+			windowStart = now;
+			windowCount = 0;
+		}
+		if (windowCount >= perMin) return {
+			ok: false,
+			state,
+			waitMs: windowStart + 6e4 - now
+		};
+		windowCount++;
+	}
+	return {
+		ok: true,
+		state: {
+			nextAllowedAt: now + interval,
+			windowStart,
+			windowCount
+		}
+	};
+}
+/** Throttle key for an event rule: `thr:<ruleId>:<key value or *>`. */
+function throttleKey(ruleId, throttle, payload) {
+	let v = "*";
+	if (throttle.key && payload !== null && typeof payload === "object" && Object.hasOwn(payload, throttle.key)) {
+		const raw = payload[throttle.key];
+		if (raw !== void 0 && raw !== null) v = String(raw);
+	}
+	return `thr:${ruleId}:${v}`;
+}
+export { PACING_DEFAULTS, nextBackoff, takeChatSlot, takeToken, throttleKey };

package/dist/core/random.d.ts

@@ -0,0 +1,2 @@
+/** Fills the buffer with cryptographically random bytes (in place). */
+export type RandomFill = (buf: Uint8Array) => unknown;

package/dist/core/random.js

@@ -0,0 +1,38 @@
+// src/core/random.ts
+const B64URL = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
+const B62 = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
+/** `length` chars of `[A-Za-z0-9_-]` (6 random bits each). Default 32: link codes (`/start <code>`, ≤ 64). */
+function randomCode(rand, length = 32) {
+	const bytes = new Uint8Array(length);
+	rand(bytes);
+	let out = "";
+	for (const b of bytes) out += B64URL[b & 63];
+	return out;
+}
+/** `length` chars of base62 with rejection sampling (no modulo bias). Default 10: action ids (`a:<id>`). */
+function shortId(rand, length = 10) {
+	let out = "";
+	const bytes = new Uint8Array(Math.max(16, length * 2));
+	while (out.length < length) {
+		rand(bytes);
+		for (const b of bytes) {
+			if (b >= 248) continue;
+			out += B62[b % 62];
+			if (out.length === length) break;
+		}
+	}
+	return out;
+}
+/** Webhook secret: 64 chars `[A-Za-z0-9_-]` (Telegram allows 1–256). */
+function webhookSecret(rand) {
+	return randomCode(rand, 64);
+}
+/** Lowercase hex SHA-256 of a UTF-8 string or bytes (link codes are stored hashed). */
+async function sha256Hex(subtle, input) {
+	const data = typeof input === "string" ? new TextEncoder().encode(input) : input;
+	const digest = new Uint8Array(await subtle.digest("SHA-256", data));
+	let hex = "";
+	for (const b of digest) hex += b.toString(16).padStart(2, "0");
+	return hex;
+}
+export { randomCode, sha256Hex, shortId, webhookSecret };

package/dist/core/recipients.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/core/recipients.js

@@ -0,0 +1,86 @@
+import { quietUntil } from "./schedule/policy.js";
+// src/core/recipients.ts
+function planRecipients(specs) {
+	const plan = {
+		destinations: [],
+		chats: [],
+		users: [],
+		roles: [],
+		allLinked: false,
+		audiences: {}
+	};
+	const add = (list, v) => {
+		if (!list.includes(v)) list.push(v);
+	};
+	for (const s of specs) if ("destination" in s) add(plan.destinations, s.destination);
+	else if ("chat" in s) add(plan.chats, s.chat);
+	else if ("user" in s) add(plan.users, s.user);
+	else if ("role" in s) add(plan.roles, s.role);
+	else if ("allLinked" in s) plan.allLinked = true;
+	else {
+		const refs = plan.audiences[s.audience] ?? [];
+		add(refs, s.ref);
+		plan.audiences[s.audience] = refs;
+	}
+	return plan;
+}
+/** One entry per (chat, topic thread), keeping the first and merging `via`. */
+function dedupeChats(chats) {
+	const byKey = /* @__PURE__ */ new Map();
+	for (const c of chats) {
+		const key = `${c.chatRef}#${c.messageThreadId ?? ""}`;
+		const prev = byKey.get(key);
+		if (!prev) byKey.set(key, {
+			...c,
+			via: [...c.via]
+		});
+		else for (const v of c.via) if (!prev.via.includes(v)) prev.via.push(v);
+	}
+	return [...byKey.values()];
+}
+/** `*` matches every topic. */
+function topicMatches(pattern, topic) {
+	return pattern === "*" || pattern === topic;
+}
+/** The subscription that applies to a chat for a topic: an exact topic wins over `*`. */
+function subscriptionFor(subs, chatRef, topic) {
+	let wildcard;
+	for (const s of subs) {
+		if (s.chatRef !== chatRef || !topicMatches(s.topic, topic)) continue;
+		if (s.topic === topic) return s;
+		wildcard ??= s;
+	}
+	return wildcard;
+}
+/**
+* Applies mute and quiet hours for a topic. `tzOf` gives each chat's zone (chat → user → bot/host default); a
+* quiet window with its own `tz` uses that instead.
+*/
+function applySubscriptions(chats, subs, opts) {
+	const out = {
+		send: [],
+		held: [],
+		muted: []
+	};
+	for (const chat of chats) {
+		const sub = subscriptionFor(subs, chat.chatRef, opts.topic);
+		if (sub?.muted) {
+			out.muted.push(chat);
+			continue;
+		}
+		const until = quietUntil(sub?.quiet, chat.timezone ?? opts.defaultTz, opts.now);
+		if (until !== null) out.held.push({
+			chat,
+			until
+		});
+		else out.send.push(chat);
+	}
+	return out;
+}
+/** Subscription topics, as stored in `tg_subscription.topic`. */
+const topics = {
+	schedule: (scheduleId) => `schedule:${scheduleId}`,
+	event: (eventKey) => `event:${eventKey}`,
+	broadcast: () => "broadcast"
+};
+export { applySubscriptions, dedupeChats, planRecipients, subscriptionFor, topicMatches, topics };

package/dist/core/schedule/describe.d.ts

@@ -0,0 +1,3 @@
+import { ScheduleRule } from "../../contracts/schedules.js";
+/** Human sentence for a schedule rule in `en` or `mr` (other locales fall back to `en`), for example "Every day at 09:00". */
+export declare function describeRule(rule: ScheduleRule, locale?: string): string;