pi-roundtable-line 0.9.13 → 0.10.0

package/src/quota.ts

@@ -0,0 +1,195 @@
+import type { LineApi } from "./api.ts";
+import { LineError } from "./errors.ts";
+import { parseSourceKey } from "./events.ts";
+
+export interface QuotaOptions {
+	/**
+	 * The most messages this month a push may bring consumption to, however much of the plan's quota is
+	 * left; the gate keeps to the lower of the two. Unset: the plan's quota alone.
+	 */
+	monthlyCap?: number;
+	/**
+	 * How long, in milliseconds, a push that was sent (or may have been) stays reserved when LINE's
+	 * consumption has not grown by its recipients by then. LINE calls its figure approximate and may
+	 * be slow to count; this bounds how long the gate waits for it. Default 10 minutes.
+	 */
+	holdMs?: number;
+}
+
+/** How long a sent push stays reserved if LINE's consumption never shows it. */
+export const QUOTA_HOLD_MS = 10 * 60_000;
+
+/** How long a reading of LINE's quota, consumption and a chat's member count is trusted. */
+export const QUOTA_CACHE_MS = 60_000;
+
+/** A push the gate let through, until it is settled. */
+export interface Reservation {
+	/** The recipients it counts for. */
+	readonly recipients: number;
+}
+
+export type Reserved =
+	| { ok: true; reservation: Reservation }
+	| {
+			ok: false;
+			/** The reading the push was refused on, for the log: counts only. */
+			used: number;
+			reserved: number;
+			recipients: number;
+			cap: number;
+	  };
+
+interface Reading {
+	/** The plan's monthly limit, undefined when it has none. */
+	limit: number | undefined;
+	used: number;
+	/** When the reading began, in milliseconds. */
+	at: number;
+}
+
+export interface QuotaGateDeps {
+	api: LineApi;
+	now: () => Date;
+	options?: QuotaOptions;
+	cacheMs?: number;
+}
+
+/**
+ * Keeps pushes inside the month's budget. A push is let through only while LINE's consumption, what
+ * this process has reserved for pushes it has sent or is sending, and the push's own recipients (one,
+ * or the member count of a group or room) stay within the lower of the plan's quota and `monthlyCap`.
+ *
+ * LINE's quota and consumption are read at most once a minute. LINE calls the figure approximate,
+ * so a reservation for a push that went out (or may have: a timeout or a 5xx) stays counted until
+ * the consumption read has grown by its recipients since the push was sent, or `holdMs` has passed;
+ * one for a push that did not go out is dropped at once. Only this process's reservations are known: with several
+ * processes, set `monthlyCap` below the quota by their share.
+ */
+export class QuotaGate {
+	readonly #api: LineApi;
+	readonly #now: () => Date;
+	readonly #cap: number | undefined;
+	readonly #cacheMs: number;
+	readonly #holdMs: number;
+	#reading: Reading | undefined;
+	#inflight: Promise<Reading> | undefined;
+	readonly #reservations = new Map<
+		Reservation,
+		{ settledAt: number | undefined; unseen: number }
+	>();
+	/** The consumption of the previous reading, to see how much it has grown. */
+	#lastUsed: number | undefined;
+	readonly #counts = new Map<string, { n: number; at: number }>();
+
+	constructor(deps: QuotaGateDeps) {
+		this.#api = deps.api;
+		this.#now = deps.now;
+		this.#cap = deps.options?.monthlyCap;
+		this.#cacheMs = deps.cacheMs ?? QUOTA_CACHE_MS;
+		this.#holdMs = deps.options?.holdMs ?? QUOTA_HOLD_MS;
+	}
+
+	/** How many people a push to the chat reaches; a count is trusted for a minute. */
+	async recipients(sourceKey: string): Promise<number> {
+		const source = parseSourceKey(sourceKey);
+		if (!source)
+			throw new LineError("bad_source_key", "line: not a source key");
+		if (source.kind === "user") return 1;
+		const now = this.#now().getTime();
+		const held = this.#counts.get(sourceKey);
+		if (held && now - held.at < this.#cacheMs) return held.n;
+		const n = await this.#api.recipients(source.kind, source.id);
+		this.#counts.set(sourceKey, { n, at: now });
+		return n;
+	}
+
+	async #read(): Promise<Reading> {
+		const now = this.#now().getTime();
+		if (this.#reading && now - this.#reading.at < this.#cacheMs)
+			return this.#reading;
+		this.#inflight ??= (async () => {
+			const at = this.#now().getTime();
+			const limit = await this.#api.messageQuota();
+			// With no limit and no cap of our own there is nothing to compare with.
+			const used =
+				limit === undefined && this.#cap === undefined
+					? 0
+					: await this.#api.messageConsumption();
+			const reading = { limit, used, at };
+			this.#reading = reading;
+			// What consumption has grown by since the last reading is what LINE has counted of the pushes
+			// sent before this reading began, oldest first; a push is let go once all of it is counted.
+			let grown =
+				this.#lastUsed === undefined ? 0 : Math.max(0, used - this.#lastUsed);
+			this.#lastUsed = used;
+			const counted = [...this.#reservations]
+				.filter(
+					([, state]) => state.settledAt !== undefined && state.settledAt <= at,
+				)
+				.sort(([, a], [, b]) => (a.settledAt ?? 0) - (b.settledAt ?? 0));
+			for (const [reservation, state] of counted) {
+				const take = Math.min(grown, state.unseen);
+				grown -= take;
+				state.unseen -= take;
+				if (state.unseen <= 0) this.#reservations.delete(reservation);
+			}
+			return reading;
+		})().finally(() => {
+			this.#inflight = undefined;
+		});
+		return this.#inflight;
+	}
+
+	/**
+	 * Lets a push of `recipients` through or refuses it. Rejects when LINE's quota cannot be read, so a
+	 * caller waits instead of sending without knowing.
+	 */
+	async reserve(recipients: number): Promise<Reserved> {
+		const reading = await this.#read();
+		this.#expire();
+		const caps = [reading.limit, this.#cap].filter(
+			(cap): cap is number => cap !== undefined,
+		);
+		const cap = caps.length > 0 ? Math.min(...caps) : Number.POSITIVE_INFINITY;
+		const reserved = this.reserved();
+		if (reading.used + reserved + recipients > cap)
+			return { ok: false, used: reading.used, reserved, recipients, cap };
+		const reservation: Reservation = { recipients };
+		this.#reservations.set(reservation, {
+			settledAt: undefined,
+			unseen: recipients,
+		});
+		return { ok: true, reservation };
+	}
+
+	/**
+	 * Ends a reservation: `sent` (also for a push whose outcome is not known) keeps it counted until
+	 * LINE's consumption has grown by its recipients or `holdMs` has passed, otherwise it is dropped
+	 * now.
+	 */
+	settle(reservation: Reservation, sent: boolean): void {
+		const state = this.#reservations.get(reservation);
+		if (!state) return;
+		if (sent) state.settledAt = this.#now().getTime();
+		else this.#reservations.delete(reservation);
+	}
+
+	/** Lets go of pushes that have been reserved for `holdMs` since they were sent. */
+	#expire(): void {
+		const now = this.#now().getTime();
+		for (const [reservation, state] of this.#reservations)
+			if (
+				state.settledAt !== undefined &&
+				now - state.settledAt >= this.#holdMs
+			)
+				this.#reservations.delete(reservation);
+	}
+
+	/** Messages reserved and not yet in LINE's consumption, for tests and status. */
+	reserved(): number {
+		this.#expire();
+		let total = 0;
+		for (const state of this.#reservations.values()) total += state.unseen;
+		return total;
+	}
+}

package/src/retention.ts

@@ -0,0 +1,243 @@
+import type { SQL } from "bun";
+import type { Logger } from "pi-roundtable";
+import { errorCode } from "./errors.ts";
+
+const DAY_MS = 24 * 60 * 60_000;
+
+export interface RetentionOptions {
+	/**
+	 * How long events are kept after they are done, skipped or dead, and how long one that never got
+	 * handled (no subscriber was attached) waits before it is dropped with its payload; default 7 days.
+	 */
+	inboxMs: number;
+	/** How long a message's metadata and tokens, its references and its tombstone are kept; default 7 days. */
+	messagesMs: number;
+	/**
+	 * How long finished pushes (and a push that never got sent), and the record of a join notice, are
+	 * kept; default 7 days. A push loses its message objects when it finishes, long before this.
+	 */
+	outboxMs: number;
+	/**
+	 * How long a ref of an unsent message may wait before the sweep hands it back to the subscriber as
+	 * `unsent`; default 15 minutes. Such a ref is a stray: a handler that outlived its lease kept it
+	 * after the unsend had run.
+	 */
+	strayMs: number;
+	/** How often the sweeper runs; default 1 hour. At most 2_147_483_647. */
+	intervalMs: number;
+}
+
+export const RETENTION_DEFAULTS: RetentionOptions = {
+	inboxMs: 7 * DAY_MS,
+	messagesMs: 7 * DAY_MS,
+	outboxMs: 7 * DAY_MS,
+	strayMs: 15 * 60_000,
+	intervalMs: 60 * 60_000,
+};
+
+/** The longest delay a timer holds. */
+const MAX_TIMER_MS = 2_147_483_647;
+
+/** Refuses a mistake in the retention options, naming the field. */
+export function checkRetention(options: Partial<RetentionOptions>): void {
+	for (const [key, value] of Object.entries(options)) {
+		if (!(key in RETENTION_DEFAULTS))
+			throw new Error(`line: retention.${key} is not a retention option`);
+		if (!Number.isInteger(value) || (value as number) < 1)
+			throw new Error(
+				`line: retention.${key} must be a positive whole number of milliseconds; got ${String(value)}`,
+			);
+	}
+	if ((options.intervalMs ?? 0) > MAX_TIMER_MS)
+		throw new Error(
+			`line: retention.intervalMs must be at most ${MAX_TIMER_MS} milliseconds (about 24 days); got ${String(options.intervalMs)}`,
+		);
+}
+
+/**
+ * One table the sweeper trims. `window` names the retention option that says how old a row may get;
+ * `run` deletes the rows older than `cutoff` and answers how many went.
+ */
+interface RetentionTask {
+	name: string;
+	window: "inboxMs" | "messagesMs" | "outboxMs";
+	run(sql: SQL, cutoff: Date): Promise<number>;
+}
+
+/** Deletes with `DELETE ... RETURNING` and counts the rows that went. */
+async function count(
+	rows: PromiseLike<{ n: number | string }[]>,
+): Promise<number> {
+	return Number((await rows)[0]?.n ?? 0);
+}
+
+const TASKS: readonly RetentionTask[] = [
+	{
+		name: "inbox",
+		window: "inboxMs",
+		run: (sql, cutoff) =>
+			count(sql`WITH gone AS (
+				DELETE FROM line_inbox
+				WHERE status IN ('done', 'skipped', 'dead') AND completed_at < ${cutoff}
+				RETURNING 1) SELECT count(*)::int AS n FROM gone`),
+	},
+	{
+		// Waiting events keep their payload; with no subscriber they would keep it for ever.
+		name: "inbox_waiting",
+		window: "inboxMs",
+		run: (sql, cutoff) =>
+			count(sql`WITH gone AS (
+				DELETE FROM line_inbox WHERE status = 'pending' AND created_at < ${cutoff}
+				RETURNING 1) SELECT count(*)::int AS n FROM gone`),
+	},
+	{
+		name: "messages",
+		window: "messagesMs",
+		run: (sql, cutoff) =>
+			count(sql`WITH gone AS (
+				DELETE FROM line_messages WHERE created_at < ${cutoff}
+				RETURNING 1) SELECT count(*)::int AS n FROM gone`),
+	},
+	{
+		name: "refs",
+		window: "messagesMs",
+		run: (sql, cutoff) =>
+			count(sql`WITH gone AS (
+				DELETE FROM line_message_refs WHERE created_at < ${cutoff}
+				RETURNING 1) SELECT count(*)::int AS n FROM gone`),
+	},
+	{
+		name: "tombstones",
+		window: "messagesMs",
+		run: (sql, cutoff) =>
+			count(sql`WITH gone AS (
+				DELETE FROM line_tombstones WHERE created_at < ${cutoff}
+				RETURNING 1) SELECT count(*)::int AS n FROM gone`),
+	},
+	{
+		// A push that finished, and one that never did (a chat that stopped being allowed, say).
+		name: "outbox",
+		window: "outboxMs",
+		run: (sql, cutoff) =>
+			count(sql`WITH gone AS (
+				DELETE FROM line_outbox
+				WHERE (status IN ('sent', 'dead', 'refused') AND completed_at < ${cutoff})
+					OR (status IN ('queued', 'sending') AND created_at < ${cutoff})
+				RETURNING 1) SELECT count(*)::int AS n FROM gone`),
+	},
+	{
+		name: "notices",
+		window: "outboxMs",
+		run: (sql, cutoff) =>
+			count(sql`WITH gone AS (
+				DELETE FROM line_notices WHERE created_at < ${cutoff}
+				RETURNING 1) SELECT count(*)::int AS n FROM gone`),
+	},
+];
+
+export interface RetentionDeps {
+	sql: SQL;
+	logger: Logger;
+	now: () => Date;
+	options?: Partial<RetentionOptions>;
+	/**
+	 * Hands the refs of unsent messages that nobody took back to the subscriber, those stored before
+	 * `before`; answers how many messages it handed back. Runs first in every sweep, so a stray is
+	 * taken back before retention would forget it.
+	 */
+	strays?: (before: Date) => Promise<number>;
+}
+
+/**
+ * Trims the package's tables once an hour: events that are finished or never handled, and the
+ * metadata, references and tombstones of messages. It logs counts only. A table that cannot be
+ * trimmed is logged by its code and the others go on.
+ */
+export class RetentionSweeper {
+	readonly #sql: SQL;
+	readonly #logger: Logger;
+	readonly #now: () => Date;
+	readonly #strays: ((before: Date) => Promise<number>) | undefined;
+	readonly options: RetentionOptions;
+	#timer: ReturnType<typeof setTimeout> | undefined;
+	#running = false;
+	#sweeping: Promise<Record<string, number>> | undefined;
+
+	constructor(deps: RetentionDeps) {
+		this.#sql = deps.sql;
+		this.#logger = deps.logger;
+		this.#now = deps.now;
+		this.#strays = deps.strays;
+		this.options = { ...RETENTION_DEFAULTS, ...deps.options };
+	}
+
+	/** `"retention"` while a sweep runs, for the shutdown drain. */
+	busy(): string[] {
+		return this.#sweeping ? ["retention"] : [];
+	}
+
+	/** One sweep now; rows older than their window are gone. Returns the count deleted from each table. */
+	sweepOnce(): Promise<Record<string, number>> {
+		this.#sweeping ??= this.#sweep().finally(() => {
+			this.#sweeping = undefined;
+		});
+		return this.#sweeping;
+	}
+
+	async #sweep(): Promise<Record<string, number>> {
+		const counts: Record<string, number> = {};
+		const now = this.#now().getTime();
+		if (this.#strays) {
+			try {
+				counts.strays = await this.#strays(
+					new Date(now - this.options.strayMs),
+				);
+			} catch (error) {
+				counts.strays = 0;
+				this.#logger.warn(
+					{ table: "strays", code: errorCode(error) },
+					"a LINE retention sweep could not hand back stray refs",
+				);
+			}
+		}
+		for (const task of TASKS) {
+			const cutoff = new Date(now - this.options[task.window]);
+			try {
+				counts[task.name] = await task.run(this.#sql, cutoff);
+			} catch (error) {
+				counts[task.name] = 0;
+				this.#logger.warn(
+					{ table: task.name, code: errorCode(error) },
+					"a LINE retention sweep could not trim a table",
+				);
+			}
+		}
+		if (Object.values(counts).some((n) => n > 0))
+			this.#logger.info(counts, "LINE retention removed rows");
+		return counts;
+	}
+
+	/** Sweeps now, then every `intervalMs`. */
+	start(): void {
+		if (this.#running) return;
+		this.#running = true;
+		this.#schedule(0);
+	}
+
+	#schedule(delayMs: number): void {
+		this.#timer = setTimeout(() => {
+			void this.sweepOnce().finally(() => {
+				if (this.#running) this.#schedule(this.options.intervalMs);
+			});
+		}, delayMs);
+		this.#timer.unref?.();
+	}
+
+	/** Stops the schedule and waits for a sweep in progress. */
+	async stop(): Promise<void> {
+		this.#running = false;
+		if (this.#timer) clearTimeout(this.#timer);
+		this.#timer = undefined;
+		await this.#sweeping?.catch(() => undefined);
+	}
+}

package/src/route.ts

@@ -0,0 +1,71 @@
+import type { InboundMessage } from "pi-roundtable";
+import { parseSourceKey } from "./events.ts";
+import type { LineMessageEvent } from "./messages.ts";
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+	typeof value === "object" && value !== null && !Array.isArray(value);
+
+/**
+ * The text of a LINE message with the bot's own mentions cut out, and whether it had any. LINE
+ * names each mention by position and length in the text.
+ */
+export function stripSelfMentions(
+	text: string,
+	message: Record<string, unknown>,
+): { text: string; mentionsBot: boolean } {
+	const mentionees = isRecord(message.mention)
+		? message.mention.mentionees
+		: [];
+	const spans = (Array.isArray(mentionees) ? mentionees : [])
+		.filter(
+			(m): m is Record<string, unknown> => isRecord(m) && m.isSelf === true,
+		)
+		.map((m) => ({ start: Number(m.index), length: Number(m.length) }))
+		.filter(
+			(s) =>
+				Number.isInteger(s.start) &&
+				Number.isInteger(s.length) &&
+				s.start >= 0 &&
+				s.length > 0 &&
+				s.start + s.length <= text.length,
+		)
+		.sort((a, b) => b.start - a.start);
+	let stripped = text;
+	for (const span of spans)
+		stripped =
+			stripped.slice(0, span.start) + stripped.slice(span.start + span.length);
+	return { text: stripped.trim(), mentionsBot: spans.length > 0 };
+}
+
+/**
+ * A text message of an allowed chat as the host's router takes it, or undefined when it is not one
+ * the router can serve: not text, or from a sender LINE did not name, who cannot be resolved to a
+ * person.
+ */
+export function inboundOf(
+	event: LineMessageEvent,
+	message: Record<string, unknown>,
+): InboundMessage | undefined {
+	if (event.body.kind !== "text" || !event.userId) return undefined;
+	const source = parseSourceKey(event.sourceKey);
+	if (!source) return undefined;
+	const { text, mentionsBot } = stripSelfMentions(event.body.text, message);
+	return {
+		channel: `line:${source.kind}:${source.id}`,
+		messageId: event.messageId,
+		actor: {
+			provider: "line",
+			subject: event.userId,
+			name: event.userId,
+			surface: "line",
+		},
+		authorId: event.userId,
+		authorName: event.userId,
+		authorIsBot: false,
+		isDirect: source.kind === "user",
+		mentionsBot,
+		repliesToBot: false,
+		text,
+		attachments: [],
+	};
+}

package/src/sender.ts

@@ -0,0 +1,110 @@
+import { LineError } from "./errors.ts";
+
+/**
+ * The name and icon a push is shown under, in place of the channel's own. LINE shows the name as
+ * "<name> from '<channel>'". Either part may be given; a push with none uses the channel's.
+ */
+export interface LineSender {
+	/** 1 to 20 characters, none of the forbidden words. */
+	name?: string;
+	/** An `https` URL of at most 2000 characters that LINE can fetch. */
+	iconUrl?: string;
+}
+
+export interface SenderOptions {
+	/**
+	 * Words a sender name may not contain, compared without regard to case or width and only as whole words
+	 * (a word is a run of Latin letters and digits, or a run of letters of another script, so "LINE"
+	 * next to kana or hanzi is still the word). Default `["LINE", "LY"]`, the words LINE refuses.
+	 */
+	forbiddenWords: readonly string[];
+}
+
+export const SENDER_DEFAULTS: SenderOptions = {
+	forbiddenWords: ["LINE", "LY"],
+};
+
+export const SENDER_NAME_MAX = 20;
+export const SENDER_ICON_MAX = 2000;
+
+const bad = (message: string): LineError =>
+	new LineError("bad_sender", `line: ${message}`);
+
+/** Refuses a mistake in the sender options, naming the field. */
+export function checkSenderOptions(options: Partial<SenderOptions>): void {
+	for (const key of Object.keys(options))
+		if (key !== "forbiddenWords")
+			throw new Error(`line: sender.${key} is not a sender option`);
+	const words = options.forbiddenWords;
+	if (words === undefined) return;
+	if (
+		!Array.isArray(words) ||
+		words.some((w) => typeof w !== "string" || w.trim() === "")
+	)
+		throw new Error(
+			"line: sender.forbiddenWords must be a list of non-empty words",
+		);
+}
+
+// A word is a run of Latin letters and digits, or a run of letters of another script: a boundary
+// between the two breaks a word, so a name like "LINE" followed by kana still holds the word.
+const WORD =
+	/(?:\p{Script=Latin}|\p{M}|\p{N})+|(?:(?!\p{Script=Latin})\p{L})+/gu;
+
+/**
+ * Checks a sender before anything is queued and returns it as it will be sent. Throws `LineError`
+ * `bad_sender` for a name that is empty, over 20 characters, holds a control character or a
+ * forbidden word, or an icon that is not an `https` URL of at most 2000 characters; the message
+ * names the rule, never the value.
+ */
+export function validateSender(
+	sender: LineSender | undefined,
+	options: SenderOptions = SENDER_DEFAULTS,
+): LineSender | undefined {
+	if (sender === undefined) return undefined;
+	if (typeof sender !== "object" || sender === null || Array.isArray(sender))
+		throw bad("a sender is { name, iconUrl }");
+	const { name, iconUrl, ...rest } = sender as Record<string, unknown>;
+	if (Object.keys(rest).length > 0)
+		throw bad("a sender has a name and an iconUrl, nothing else");
+	if (name === undefined && iconUrl === undefined)
+		throw bad("a sender needs a name or an iconUrl");
+	const checked: LineSender = {};
+	if (name !== undefined) {
+		if (typeof name !== "string" || name.trim() === "")
+			throw bad("a sender name is a non-empty string");
+		if (name !== name.trim())
+			throw bad("a sender name has no leading or trailing space");
+		if (Array.from(name).length > SENDER_NAME_MAX)
+			throw bad(`a sender name is at most ${SENDER_NAME_MAX} characters`);
+		// biome-ignore lint/suspicious/noControlCharactersInRegex: control characters are what is refused
+		if (/[\u0000-\u001f\u007f]/.test(name))
+			throw bad("a sender name has no control characters");
+		// Full-width letters are the letters they look like.
+		const words = (name.normalize("NFKC").match(WORD) ?? []).map((w) =>
+			w.toLowerCase(),
+		);
+		const forbidden = options.forbiddenWords.map((w) =>
+			w.normalize("NFKC").toLowerCase(),
+		);
+		if (words.some((w) => forbidden.includes(w)))
+			throw bad("a sender name may not use a word LINE refuses");
+		checked.name = name;
+	}
+	if (iconUrl !== undefined) {
+		if (typeof iconUrl !== "string" || iconUrl.length > SENDER_ICON_MAX)
+			throw bad(
+				`a sender iconUrl is a string of at most ${SENDER_ICON_MAX} characters`,
+			);
+		let url: URL;
+		try {
+			url = new URL(iconUrl);
+		} catch {
+			throw bad("a sender iconUrl is a URL");
+		}
+		if (url.protocol !== "https:" || url.hostname === "" || url.username)
+			throw bad("a sender iconUrl is an https URL without credentials");
+		checked.iconUrl = iconUrl;
+	}
+	return checked;
+}

package/src/surface.ts

@@ -0,0 +1,76 @@
+import {
+	type ChannelKey,
+	type ChatSurface,
+	type InboundMessage,
+	type OutboundReply,
+	PluginError,
+	parseChannelKey,
+} from "pi-roundtable";
+import { LineError } from "./errors.ts";
+import { parseSourceKey } from "./events.ts";
+import type { LineOutbox, LineOutMessage } from "./outbox.ts";
+
+/** The longest text one LINE message holds. */
+const TEXT_MAX = 5000;
+
+/** `text` cut into pieces LINE takes, never inside a surrogate pair. */
+function pieces(text: string): string[] {
+	const parts: string[] = [];
+	let rest = text;
+	while (rest.length > TEXT_MAX) {
+		let cut = TEXT_MAX;
+		const last = rest.charCodeAt(cut - 1);
+		if (last >= 0xd800 && last <= 0xdbff) cut--;
+		parts.push(rest.slice(0, cut));
+		rest = rest.slice(cut);
+	}
+	if (rest.trim() !== "") parts.push(rest);
+	return parts;
+}
+
+/**
+ * The chats of LINE as a chat surface, under the prefix `line`: the channel of a chat is its source
+ * key, `line:group:<id>`, `line:room:<id>` or `line:user:<id>`. What the host writes in a channel is
+ * queued in the outbox as text messages, one per chunk, and goes out as a push; it reaches only a
+ * chat on the allowlist. Messages come in only when the plugin routes them (`route: true`), as the
+ * text of allowed chats. The surface offers no typing indicator, stop control, progress, files or
+ * approval prompts: LINE has none the bot can show, and an approval would have to be answered by
+ * the people of the chat.
+ */
+export class LineSurface implements ChatSurface {
+	readonly surface = "line";
+	readonly #outbox: LineOutbox;
+	#deliver: ((message: InboundMessage) => void) | undefined;
+
+	constructor(outbox: LineOutbox) {
+		this.#outbox = outbox;
+	}
+
+	async start(deliver: (message: InboundMessage) => void): Promise<void> {
+		this.#deliver = deliver;
+	}
+
+	async stop(): Promise<void> {
+		this.#deliver = undefined;
+	}
+
+	/** Hands a message to the host's router; throws until the host has started the surface. */
+	deliver(message: InboundMessage): void {
+		if (!this.#deliver)
+			throw new LineError(
+				"surface_not_started",
+				"line: the surface has not started; messages are routed once the host runs",
+			);
+		this.#deliver(message);
+	}
+
+	async sendReply(channel: ChannelKey, reply: OutboundReply): Promise<void> {
+		const { surface } = parseChannelKey(channel);
+		if (surface !== this.surface || !parseSourceKey(channel))
+			throw new PluginError(`${channel} is not a LINE chat`);
+		const messages: LineOutMessage[] = reply.chunks
+			.flatMap(pieces)
+			.map((text) => ({ type: "text", text }));
+		if (messages.length > 0) await this.#outbox.enqueue(channel, messages);
+	}
+}