@prajwalshete/telegram-plugin 0.0.0-stage → 0.1.0

package/dist/engine/dispatch/linking.js

@@ -0,0 +1,273 @@
+import { Audience } from "../../contracts/chats.js";
+import { sql } from "../../ports/sql.js";
+import { chatDto, parseJson } from "../rows.js";
+import { parseStartPayload } from "../../telegram/inbound.js";
+import { deliveryFragments } from "../outbox/enqueue.js";
+import { setStateSql } from "../state.js";
+import { helpText } from "./builtins.js";
+import { PENDING_LINK_PREFIX, PENDING_LINK_TTL_MS, hashLinkCode, pendingLinkDto, pendingLinkKey } from "../link-codes.js";
+import { displayName, releaseOtherChatsSql, upsertChatSql } from "./link-chat.js";
+// src/engine/dispatch/linking.ts
+function chatKindOf(type) {
+	return type === "group" || type === "supergroup" || type === "channel" ? type : "private";
+}
+async function consume(ctx, code, chatRefHint) {
+	return await ctx.rt.db.first(sql`UPDATE tg_link_code SET used_at = ${ctx.now}, used_by_chat = ${chatRefHint}
+        WHERE code_hash = ${code.code_hash} AND tenant = ${ctx.rt.tenant} AND used_at IS NULL AND expires_at > ${ctx.now}
+        RETURNING code_hash`) !== null;
+}
+async function loadChat(ctx) {
+	return ctx.rt.db.first(sql`SELECT * FROM tg_chat WHERE tenant = ${ctx.rt.tenant} AND bot_id = ${ctx.bot.id}
+        AND chat_id = ${String(ctx.tgChat?.id ?? "")}`);
+}
+/**
+* An admin invite for someone else's account: the code is used up, but the chat is only parked until the target
+* user confirms in the app (so an admin cannot take on another user's identity in the bot).
+*/
+async function parkPending(ctx, code, userId, name) {
+	const { rt, bot, now, from, tgChat } = ctx;
+	if (!from || !tgChat) return;
+	const chatRef = ctx.chat?.id ?? rt.ids.uuid();
+	if (!await consume(ctx, code, chatRef)) {
+		await ctx.reply(await ctx.t(code.used_at ? "bot.link.used" : "bot.link.expired"));
+		return;
+	}
+	const chatId = String(tgChat.id);
+	const state = {
+		id: rt.ids.uuid(),
+		botId: bot.id,
+		chatId,
+		chatRef,
+		userId,
+		createdBy: code.created_by,
+		tgName: displayName(from.first_name, from.last_name),
+		tgUsername: from.username ?? null,
+		locale: rt.i18n.match(from.language_code) ?? null,
+		createdAt: now,
+		expiresAt: now + PENDING_LINK_TTL_MS
+	};
+	const notify = await rt.db.first(sql`SELECT * FROM tg_chat WHERE tenant = ${rt.tenant} AND bot_id = ${bot.id} AND user_id = ${userId}
+        AND kind = 'private' AND status = 'active' AND chat_id <> ${chatId} ORDER BY linked_at DESC LIMIT 1`);
+	const notice = notify ? await pendingNotice(ctx, notify, code.created_by) : null;
+	await rt.db.batch([
+		sql`DELETE FROM tg_state WHERE tenant = ${rt.tenant} AND key LIKE ${`${PENDING_LINK_PREFIX}%`}
+        AND json_extract(value, '$.botId') = ${bot.id} AND json_extract(value, '$.chatId') = ${chatId}`,
+		setStateSql(rt, pendingLinkKey(state.id), JSON.stringify(state), now),
+		...rt.audit({
+			actor: code.created_by,
+			entity: "telegram_link",
+			entityId: state.id,
+			action: "pending",
+			diff: {
+				userId,
+				botId: bot.id
+			},
+			at: now
+		})
+	]);
+	rt.log.info("tg.link_pending", { botId: bot.id });
+	await ctx.reply(await ctx.t("bot.link.pending_confirm", { name }));
+	if (notice && notify) await rt.db.batch(deliveryFragments(rt, {
+		botId: bot.id,
+		chatRef: notify.id,
+		source: "system",
+		kind: "text",
+		html: notice,
+		dedupeKey: `link-pending:${state.id}`
+	}, now));
+	if (notice) await rt.transport.kick([bot.id]).catch(() => {});
+	const dto = pendingLinkDto(state);
+	await rt.hook("onPendingLink", (fn) => fn(dto, userId));
+}
+/** "You have a pending Telegram link from <admin>" in the invited user's linked chat's language. */
+async function pendingNotice(ctx, chat, createdBy) {
+	const { rt, bot } = ctx;
+	const locale = chat.locale ?? bot.default_locale;
+	const admin = createdBy === null ? null : await rt.actor.forUser(createdBy);
+	const adminName = (admin === null ? null : rt.describe(admin).name) ?? rt.i18n.t(locale, "bot.link.an_admin");
+	return rt.i18n.t(locale, "bot.link.pending_notice", { admin: adminName });
+}
+async function linkPrivate(ctx, code) {
+	const { rt, bot, now, from, tgChat } = ctx;
+	if (!from || !tgChat || code.purpose !== "user" || !code.user_id) {
+		await ctx.reply(await ctx.t("bot.link.expired"));
+		return "handled";
+	}
+	const existing = ctx.chat;
+	if (existing?.status === "active" && existing.user_id === code.user_id) {
+		const info = await ctx.actorInfo();
+		await ctx.reply(await ctx.t("bot.start.already_linked", { name: info?.name ?? "" }));
+		return "handled";
+	}
+	if (existing?.status === "active" && existing.user_id !== null && existing.user_id !== code.user_id) {
+		await ctx.reply(await ctx.t("bot.link.other_account"));
+		return "handled";
+	}
+	const actor = await rt.actor.forUser(code.user_id);
+	if (actor === null) {
+		await ctx.reply(await ctx.t("bot.error.forbidden"));
+		return "handled";
+	}
+	const info = rt.describe(actor);
+	if (code.created_by !== code.user_id) {
+		await parkPending(ctx, code, code.user_id, info.name ?? "");
+		return "handled";
+	}
+	const id = existing?.id ?? rt.ids.uuid();
+	if (!await consume(ctx, code, id)) {
+		await ctx.reply(await ctx.t(code.used_at ? "bot.link.used" : "bot.link.expired"));
+		return "handled";
+	}
+	const locale = rt.i18n.match(from.language_code);
+	await rt.db.batch([
+		...await releaseOtherChatsSql(rt, bot.id, code.user_id, id, now),
+		upsertChatSql(rt, id, {
+			botId: bot.id,
+			chatId: String(tgChat.id),
+			kind: "private",
+			title: displayName(from.first_name, from.last_name),
+			username: from.username ?? null,
+			userId: code.user_id,
+			audienceJson: null,
+			locale,
+			linkedBy: code.user_id
+		}, now),
+		...rt.audit({
+			actor: code.user_id,
+			entity: "telegram_chat",
+			entityId: id,
+			action: "link",
+			diff: {
+				kind: "private",
+				userId: code.user_id,
+				botId: bot.id
+			},
+			at: now
+		})
+	]);
+	ctx.chat = await loadChat(ctx);
+	rt.log.info("tg.linked", {
+		botId: bot.id,
+		chatRef: id,
+		kind: "private"
+	});
+	const role = info.role ?? "";
+	await ctx.reply(`${await ctx.t("bot.start.linked", {
+		name: info.name ?? "",
+		role
+	})}\n\n${await helpText(ctx)}`);
+	if (ctx.chat) {
+		const dto = chatDto(ctx.chat);
+		await rt.hook("onLinked", (fn) => fn(dto, actor));
+	}
+	return "handled";
+}
+async function linkGroup(ctx, code) {
+	const { rt, bot, now, tgChat } = ctx;
+	if (!tgChat || code.purpose !== "group") {
+		await ctx.reply(await ctx.t("bot.link.expired"));
+		return "handled";
+	}
+	const sender = await ctx.senderActor();
+	if (!sender || sender.userId !== code.created_by) {
+		await ctx.reply(await ctx.t("bot.link.not_creator"));
+		return "handled";
+	}
+	const audience = parseJson(code.audience_json, Audience.nullable(), null);
+	if (!audience) {
+		await ctx.reply(await ctx.t("bot.link.expired"));
+		return "handled";
+	}
+	const id = ctx.chat?.id ?? rt.ids.uuid();
+	if (!await consume(ctx, code, id)) {
+		await ctx.reply(await ctx.t(code.used_at ? "bot.link.used" : "bot.link.expired"));
+		return "handled";
+	}
+	await rt.db.batch([upsertChatSql(rt, id, {
+		botId: bot.id,
+		chatId: String(tgChat.id),
+		kind: chatKindOf(tgChat.type),
+		title: tgChat.title?.slice(0, 128) ?? null,
+		username: tgChat.username ?? null,
+		userId: null,
+		audienceJson: JSON.stringify(audience),
+		locale: null,
+		linkedBy: sender.userId
+	}, now), ...rt.audit({
+		actor: sender.userId,
+		entity: "telegram_chat",
+		entityId: id,
+		action: "link",
+		diff: {
+			kind: chatKindOf(tgChat.type),
+			audience,
+			botId: bot.id
+		},
+		at: now
+	})]);
+	ctx.chat = await loadChat(ctx);
+	rt.log.info("tg.linked", {
+		botId: bot.id,
+		chatRef: id,
+		kind: "group"
+	});
+	const locale = await ctx.locale();
+	const who = "role" in audience ? audience.role : rt.i18n.plain(locale, "bot.start.audience_users", { count: audience.users.length });
+	await ctx.reply(rt.i18n.t(locale, "bot.start.group_linked", { audience: who }));
+	const groupActor = await rt.actor.forAudience(audience);
+	if (ctx.chat && groupActor !== null) {
+		const dto = chatDto(ctx.chat);
+		await rt.hook("onLinked", (fn) => fn(dto, groupActor));
+	}
+	return "handled";
+}
+async function groupMuted(ctx, chatRef) {
+	return (await ctx.rt.db.first(sql`SELECT muted FROM tg_subscription WHERE tenant = ${ctx.rt.tenant} AND chat_ref = ${chatRef} AND topic = '*'`))?.muted === 1;
+}
+async function startHandler(ctx) {
+	const cmd = ctx.command;
+	if (ctx.cls !== "command" || cmd?.command !== "start" || cmd.mentionedOther) return "next";
+	const payload = parseStartPayload(cmd);
+	const isPrivate = ctx.tgChat?.type === "private";
+	if (payload === null) {
+		if (cmd.args.length > 0) {
+			await ctx.reply(await ctx.t("bot.link.expired"));
+			return "handled";
+		}
+		if (ctx.chat?.status === "active") {
+			if (!isPrivate && await groupMuted(ctx, ctx.chat.id)) {
+				const sender = await ctx.senderActor();
+				if (!sender || !await ctx.rt.can(sender.actor, "telegram.chats.manage")) {
+					await ctx.reply(await ctx.t("bot.error.forbidden"));
+					return "handled";
+				}
+			}
+			if ((await ctx.rt.db.run(sql`DELETE FROM tg_subscription WHERE tenant = ${ctx.rt.tenant} AND chat_ref = ${ctx.chat.id}
+            AND topic = '*' AND muted = 1`)).changes > 0) {
+				await ctx.reply(await ctx.t("bot.start.unmuted"));
+				return "handled";
+			}
+			const info = await ctx.actorInfo();
+			if (isPrivate && info) {
+				await ctx.reply(`${await ctx.t("bot.start.already_linked", { name: info.name ?? "" })}\n\n${await helpText(ctx)}`);
+				return "handled";
+			}
+			await ctx.reply(await helpText(ctx));
+			return "handled";
+		}
+		if (isPrivate) await ctx.reply(await ctx.t("bot.start.unlinked"));
+		return isPrivate ? "handled" : "ignored";
+	}
+	const code = await ctx.rt.db.first(sql`SELECT * FROM tg_link_code WHERE tenant = ${ctx.rt.tenant} AND code_hash = ${await hashLinkCode(payload)}
+        AND bot_id = ${ctx.bot.id}`);
+	if (!code || code.expires_at <= ctx.now) {
+		await ctx.reply(await ctx.t("bot.link.expired"));
+		return "handled";
+	}
+	if (code.used_at !== null) {
+		await ctx.reply(await ctx.t("bot.link.used"));
+		return "handled";
+	}
+	return isPrivate ? linkPrivate(ctx, code) : linkGroup(ctx, code);
+}
+export { startHandler };

package/dist/engine/errors.d.ts

@@ -0,0 +1,60 @@
+import { TelegramProblem, TelegramProblemCode } from "../contracts/problems.js";
+/** RFC 9457 extension members a problem may carry (each only for the codes named). */
+export interface TelegramProblemExtensions {
+  /** `validation_failed`: field issues (`path` is dotted, for example `body.features.ai`). */
+  issues?: {
+    path: string;
+    message: string;
+  }[];
+  /** `template_invalid` / `template_variable_unknown`: template errors (1-based line/column, locale variant). */
+  errors?: {
+    line: number;
+    column: number;
+    message: string;
+    locale?: string | undefined;
+  }[];
+  /** `rate_limited`: seconds to wait. */
+  retryAfter?: number;
+  /** `send_text_rejected`: which content checks failed (`money`, `url`, `phone`, `email`, `too_long`, `empty`). */
+  reasons?: string[];
+}
+/**
+ * A plugin problem: a stable `code` (one of `TELEGRAM_PROBLEM_CODES`), an HTTP `status` (default from
+ * `PROBLEM_STATUS`), an optional human `detail` (English, safe to log; never secrets or message text) and the
+ * problem `extensions`. `toProblem()` gives the full RFC 9457 body that routes send and `ports.errors` receives.
+ *
+ * Every error leaving the programmatic API is one of these; unexpected failures are wrapped as `internal_error`
+ * with the original error as `cause` (never included in `toProblem()`).
+ */
+export declare class TelegramPluginError extends Error {
+  /** Always `"TelegramPluginError"`. */
+  readonly name = "TelegramPluginError";
+  /** Stable machine code; map it to your own error codes or to `labels.problem.<code>` strings. */
+  readonly code: TelegramProblemCode;
+  /** HTTP status (401, 403, 404, 409, 422, …). */
+  readonly status: number;
+  /** Short English explanation, or undefined. */
+  readonly detail: string | undefined;
+  /** Extension members (`issues`, `errors`, `retryAfter`, `reasons`). Empty object when none. */
+  readonly extensions: TelegramProblemExtensions;
+  constructor(code: TelegramProblemCode, detail?: string, opts?: {
+    status?: number;
+    extensions?: TelegramProblemExtensions;
+    cause?: unknown;
+  });
+  /** `problemTitle(code)`. */
+  get title(): string;
+  /** The full problem+json body (`type`, `title`, `status`, `code`, `detail`, `instance` and the extensions). */
+  toProblem(instance?: string): TelegramProblem;
+}
+/** True for a `TelegramPluginError` (also across duplicate copies of the package, by name and code). */
+export declare function isTelegramPluginError(e: unknown): e is TelegramPluginError;
+/** Any thrown value as a `TelegramPluginError`; anything else becomes `internal_error` with `cause` set. */
+export declare function toPluginError(e: unknown): TelegramPluginError;
+/** A feature that is off (globally, or for this bot). */
+export declare function featureDisabled(feature: string, detail?: string): TelegramPluginError;
+/** Invalid `createTelegramPlugin` options or `define*` input. Thrown synchronously at construction. */
+export declare class TelegramConfigError extends Error {
+  /** Always `"TelegramConfigError"`. */
+  readonly name = "TelegramConfigError";
+}

package/dist/engine/errors.js

@@ -0,0 +1,72 @@
+import { PROBLEM_STATUS } from "../contracts/problems.js";
+// src/engine/errors.ts
+/** The problem+json title for a code (`send_text_rejected` → `send text rejected`). */
+function problemTitle(code) {
+	return code.replaceAll("_", " ");
+}
+/**
+* A plugin problem: a stable `code` (one of `TELEGRAM_PROBLEM_CODES`), an HTTP `status` (default from
+* `PROBLEM_STATUS`), an optional human `detail` (English, safe to log; never secrets or message text) and the
+* problem `extensions`. `toProblem()` gives the full RFC 9457 body that routes send and `ports.errors` receives.
+*
+* Every error leaving the programmatic API is one of these; unexpected failures are wrapped as `internal_error`
+* with the original error as `cause` (never included in `toProblem()`).
+*/
+var TelegramPluginError = class extends Error {
+	/** Always `"TelegramPluginError"`. */
+	name = "TelegramPluginError";
+	/** Stable machine code; map it to your own error codes or to `labels.problem.<code>` strings. */
+	code;
+	/** HTTP status (401, 403, 404, 409, 422, …). */
+	status;
+	/** Short English explanation, or undefined. */
+	detail;
+	/** Extension members (`issues`, `errors`, `retryAfter`, `reasons`). Empty object when none. */
+	extensions;
+	constructor(code, detail, opts = {}) {
+		super(detail ? `${code}: ${detail}` : code, opts.cause === void 0 ? void 0 : { cause: opts.cause });
+		this.code = code;
+		this.status = opts.status ?? PROBLEM_STATUS[code];
+		this.detail = detail;
+		this.extensions = opts.extensions ?? {};
+	}
+	/** `problemTitle(code)`. */
+	get title() {
+		return problemTitle(this.code);
+	}
+	/** The full problem+json body (`type`, `title`, `status`, `code`, `detail`, `instance` and the extensions). */
+	toProblem(instance) {
+		const x = this.extensions;
+		return {
+			type: "about:blank",
+			title: this.title,
+			status: this.status,
+			code: this.code,
+			...this.detail ? { detail: this.detail } : {},
+			...instance ? { instance } : {},
+			...x.issues ? { issues: x.issues } : {},
+			...x.errors ? { errors: x.errors } : {},
+			...x.retryAfter !== void 0 ? { retryAfter: x.retryAfter } : {},
+			...x.reasons ? { reasons: x.reasons } : {}
+		};
+	}
+};
+/** True for a `TelegramPluginError` (also across duplicate copies of the package, by name and code). */
+function isTelegramPluginError(e) {
+	return e instanceof TelegramPluginError || e instanceof Error && e.name === "TelegramPluginError" && typeof e.code === "string" && typeof e.toProblem === "function";
+}
+/** Any thrown value as a `TelegramPluginError`; anything else becomes `internal_error` with `cause` set. */
+function toPluginError(e) {
+	if (isTelegramPluginError(e)) return e;
+	return new TelegramPluginError("internal_error", "unexpected error", { cause: e });
+}
+/** A feature that is off (globally, or for this bot). */
+function featureDisabled(feature, detail) {
+	return new TelegramPluginError("feature_disabled", detail ?? `feature "${feature}" is not enabled`);
+}
+/** Invalid `createTelegramPlugin` options or `define*` input. Thrown synchronously at construction. */
+var TelegramConfigError = class extends Error {
+	/** Always `"TelegramConfigError"`. */
+	name = "TelegramConfigError";
+};
+export { TelegramConfigError, TelegramPluginError, featureDisabled, isTelegramPluginError, problemTitle, toPluginError };

package/dist/engine/events/filters.d.ts

@@ -0,0 +1,5 @@
+import { EventFilter } from "../../contracts/events.js";
+/** One condition. A missing (undefined / null) field only satisfies `ne`. */
+export declare function matchFilter(filter: EventFilter, payload: unknown): boolean;
+/** True when every filter holds (an empty list matches everything). Pure. */
+export declare function matchFilters(filters: readonly EventFilter[], payload: unknown): boolean;

package/dist/engine/events/filters.js

@@ -0,0 +1,82 @@
+// src/engine/events/filters.ts
+const ORDER_OPS = [
+	"gt",
+	"gte",
+	"lt",
+	"lte"
+];
+function isScalar(v) {
+	return typeof v === "string" || typeof v === "number" || typeof v === "boolean";
+}
+/** Strings compare case-insensitively for `contains`; everything else is strict. */
+function containsValue(field, value) {
+	if (typeof field === "string" && isScalar(value)) return field.toLowerCase().includes(String(value).toLowerCase());
+	if (Array.isArray(field)) return field.some((x) => x === value);
+	return false;
+}
+function compare(a, b) {
+	if (typeof a === "number" && typeof b === "number") return a - b;
+	if (typeof a === "string" && typeof b === "string") return a < b ? -1 : a > b ? 1 : 0;
+	return null;
+}
+/** One condition. A missing (undefined / null) field only satisfies `ne`. */
+function matchFilter(filter, payload) {
+	const obj = payload !== null && typeof payload === "object" ? payload : {};
+	const v = Object.hasOwn(obj, filter.field) ? obj[filter.field] : void 0;
+	if (v === void 0 || v === null) return filter.op === "ne";
+	switch (filter.op) {
+		case "eq": return v === filter.value;
+		case "ne": return v !== filter.value;
+		case "in": return Array.isArray(filter.value) && filter.value.some((x) => x === v);
+		case "contains": return containsValue(v, filter.value);
+		default: {
+			const c = compare(v, filter.value);
+			if (c === null) return false;
+			if (filter.op === "gt") return c > 0;
+			if (filter.op === "gte") return c >= 0;
+			if (filter.op === "lt") return c < 0;
+			return c <= 0;
+		}
+	}
+}
+/** True when every filter holds (an empty list matches everything). Pure. */
+function matchFilters(filters, payload) {
+	return filters.every((f) => matchFilter(f, payload));
+}
+/**
+* Save-time check of one filter: the field must be `filterable` and the op/value must fit the field's type.
+* Returns an error message, or null when the filter is fine. `shape` is the payload's top-level object shape.
+*/
+function checkFilter(filter, filterable, shape) {
+	if (!filterable.includes(filter.field)) return `field "${filter.field}" is not filterable for this event`;
+	const field = shape?.kind === "object" ? shape.fields[filter.field] : void 0;
+	const kind = field?.kind ?? "unknown";
+	const value = filter.value;
+	const op = filter.op;
+	if (op === "in") {
+		if (!Array.isArray(value) || value.length === 0) return "`in` needs a non-empty list";
+		if (kind === "number" && !value.every((x) => typeof x === "number")) return "`in` on a number field needs numbers";
+		if ((kind === "string" || kind === "enum") && !value.every((x) => typeof x === "string")) return "`in` on a text field needs strings";
+		if (kind === "boolean" || kind === "array" || kind === "object") return `\`in\` does not apply to a ${kind} field`;
+		return null;
+	}
+	if (Array.isArray(value)) return `\`${op}\` needs a single value`;
+	if (op === "contains") {
+		if (kind === "array") return isScalar(value) ? null : "`contains` needs a value";
+		if (kind === "string" || kind === "enum" || kind === "unknown") return typeof value === "string" ? null : "`contains` on a text field needs a string";
+		return `\`contains\` does not apply to a ${kind} field`;
+	}
+	if (ORDER_OPS.includes(op)) {
+		if (kind === "number") return typeof value === "number" ? null : `\`${op}\` on a number field needs a number`;
+		if (kind === "string" || kind === "date" || kind === "enum") return typeof value === "string" ? null : `\`${op}\` on a text field needs a string`;
+		if (kind === "unknown") return typeof value === "boolean" ? `\`${op}\` needs a number or a string` : null;
+		return `\`${op}\` does not apply to a ${kind} field`;
+	}
+	if (kind === "number" && typeof value !== "number") return `\`${op}\` on a number field needs a number`;
+	if ((kind === "string" || kind === "enum") && typeof value !== "string") return `\`${op}\` on a text field needs a string`;
+	if (kind === "enum" && field?.kind === "enum" && !field.values.includes(value)) return `"${String(value)}" is not one of ${field.values.join(", ")}`;
+	if (kind === "boolean" && typeof value !== "boolean") return `\`${op}\` on a yes/no field needs true or false`;
+	if (kind === "array" || kind === "object" || kind === "record") return `\`${op}\` does not apply to a ${kind} field`;
+	return null;
+}
+export { checkFilter, matchFilter, matchFilters };

package/dist/engine/events/kick.js

@@ -0,0 +1,30 @@
+import { sql } from "../../ports/sql.js";
+import { claimableEvents, runEvents } from "./tick.js";
+import { QUEUE_MARK } from "../outbox/transport.js";
+// src/engine/events/kick.ts
+/** One indexed read: is any event due now? Keeps a plain send-kick from costing a queue message. */
+async function hasDueEvents(rt, now) {
+	return await rt.db.first(sql`SELECT 1 AS ok FROM tg_event WHERE ${claimableEvents(rt, now)} LIMIT 1`) !== null;
+}
+/** Starts event processing now when events are due (queue / DO transports only). Never throws. */
+async function kickEvents(rt) {
+	if (!rt.features.events) return;
+	const name = rt.transport.name;
+	if (name !== "queue" && name !== "do") return;
+	try {
+		if (!await hasDueEvents(rt, rt.clock.now())) return;
+		if (name === "queue" && rt.queue) {
+			const body = {
+				mark: QUEUE_MARK,
+				type: "events",
+				tenant: rt.tenant
+			};
+			await rt.queue.send(body);
+			return;
+		}
+		await runEvents(rt, rt.clock.now());
+	} catch (e) {
+		rt.log.warn("tg.events_kick_failed", { error: e instanceof Error ? e.name : "error" });
+	}
+}
+export { hasDueEvents, kickEvents };

package/dist/engine/events/payload.d.ts

@@ -0,0 +1,3 @@
+import { EventDef } from "../registry.js";
+/** A shallow copy of an object payload without the event's `sensitive` fields (`{}` for non-objects). Pure. */
+export declare function stripSensitive(def: EventDef<unknown>, payload: unknown): Record<string, unknown>;

package/dist/engine/events/payload.js

@@ -0,0 +1,16 @@
+import { hostCan } from "../content/providers.js";
+// src/engine/events/payload.ts
+/** A shallow copy of an object payload without the event's `sensitive` fields (`{}` for non-objects). Pure. */
+function stripSensitive(def, payload) {
+	if (payload === null || typeof payload !== "object" || Array.isArray(payload)) return {};
+	const out = { ...payload };
+	for (const f of def.sensitive) delete out[f];
+	return out;
+}
+/** The payload variables this audience may see. */
+async function payloadVarsFor(rt, def, payload, actor) {
+	if (def.sensitive.length === 0 || payload === null || typeof payload !== "object" || Array.isArray(payload)) return payload !== null && typeof payload === "object" && !Array.isArray(payload) ? { ...payload } : {};
+	if (def.sensitivePermission !== null && await hostCan(rt, actor, def.sensitivePermission)) return { ...payload };
+	return stripSensitive(def, payload);
+}
+export { payloadVarsFor, stripSensitive };