pi-roundtable-line 0.15.3 → 0.16.0

package/CHANGELOG.md

@@ -5,6 +5,34 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.16.0] - 2026-10-16
+
+### Added
+
+- `LINE.screen(handler)` and the types `LineScreen` and `LineScreenVerdict`: one screen of the webhook, asked for every event of a request whose signature and destination passed, in order and before anything is stored, that answers `"keep"` or `"consume"`. A consumed event is never stored, routed or handed to the subscriber, and a request whose events are all consumed is a `200` that counts as accepted. A screen that throws or answers anything else fails the request with `500` and stores nothing. The screen is handed a deeply frozen copy of the event, so it cannot change what is stored. A second `screen()` while one is attached throws; until one is attached every event is kept.
+- `LINE.api` and the types `LineApiPort`, `LineCallOptions`, `LineProfile`, `LineQuotaStanding` and `LineBotInfo`: LINE's API through the plugin's own token source, timeout and `401` retry. `profile` (a member's or a one-to-one user's display name and picture; undefined for a `404`), `memberCount`, `quota` (the gate's reading with the host's `cap`), `botInfo` (`userId`, `basicId`, name and picture, asked once and kept; callers that ask together share one request and its timeout), `reply` (1 to 5 messages on a reply token), `probeToken` and `onTokenFailure`. Every call takes `{ signal, timeoutMs }`.
+- `onTokenFailure(listener)` on `LINE.api`: told the code (`token_refused`, `token_unreachable`, `token_malformed`) of each failed issue of the channel access token, whichever part of the plugin asked, once per issue however many callers shared it. `probeToken()` issues quietly and tells no listener. A listener that throws, or returns a rejecting promise, is ignored.
+- `senderNameProblem(name, options?)`, the type `SenderNameProblem` (`empty`, `edge_space`, `too_long`, `control_character`, `forbidden_word`), and the values `SENDER_NAME_MAX` and `SENDER_DEFAULTS`: why LINE would refuse a sender name, for a host that checks a name before it queues a push. `validateSender` uses it and keeps its messages.
+- `LineBridgePort.api` and `LineBridgePort.screen`.
+
+### Changed
+
+- `SENDER_DEFAULTS` and its `forbiddenWords` list are frozen, and `senderNameProblem` reads options without a word list as the defaults.
+- A sender name with a C1 control character (U+0080 to U+009F) is now refused as `bad_sender`, like C0 and DEL already were.
+
+## [0.15.4] - 2026-10-15
+
+### Added
+
+- `LineOutboxResultEvent.attempts`: how many tries the push took, the one that ended it included (1 for a push LINE refused at once, 2 after a `5xx` and then a refusal), so a subscriber no longer reads `line_outbox`.
+- Migration `outbox-requested` adds the nullable `line_outbox.requested_at`, set just before a push's request is made and cleared when the push is claimed again.
+
+### Fixed
+
+- A stop no longer gives back an attempt whose request may have reached LINE. A push interrupted by the worker stopping used to be put back with its attempt uncounted even when the request was already out, so the count (and `outbox.maxAttempts`) understated the tries; it is now given back only when the stop came before the request.
+
+The core peer range stays `>=0.15.0 <0.16.0`.
+
 ## [0.15.3] - 2026-10-15
 
 - Release in lockstep with pi-roundtable 0.15.3; no package-specific behavior changes. The core peer range stays `>=0.15.0 <0.16.0`.

package/README.md

@@ -66,13 +66,13 @@ Errors carry a short code (`token_refused`, `api_unreachable`, `http_429`, ...)
 
 | Status | When |
 |---|---|
-| `200` | the events were stored (or there were none: LINE's Verify button) |
+| `200` | the events were stored (or there were none: LINE's Verify button, or a screen consumed them all) |
 | `400` | the body is signed but is not a LINE events object |
 | `401` | `x-line-signature` is missing or is not the HMAC-SHA256 of the raw body under the channel secret |
 | `403` | the body's `destination` is not this bot (checked once the bot's user id is known) |
 | `405` | not a `POST` |
 | `413` | the body is over 1 MiB |
-| `500` | the database could not store the events |
+| `500` | the database could not store the events, or the attached [screen](#screening-events) failed |
 
 The signature is checked on the raw bytes, in constant time, before the body is parsed.
 All events of a request are stored in one transaction, and `200` follows the commit.
@@ -100,11 +100,67 @@ webhooks: {
 ```
 
 They are counts and times only: no body, address or signature is kept, and a request adds one to a counter and nothing else.
-A `405` and a `500` (the database could not store the events) are in no counter.
+A `405` and a `500` (the database could not store the events, or a screen failed) are in no counter.
 A host that watches for a channel whose webhook URL or secret has drifted can alarm on `rejected.signatureForBot` growing while `accepted` does not: a scanner that finds the URL does not know the bot's user id, so a request that fails its signature yet names this bot as its `destination` is far more likely LINE with a wrong channel secret (or a rotated one) than noise.
 To tell, the handler reads the `destination` of a body that failed its signature, only within the 1 MiB limit, and never logs or keeps it; `signatureForBot` also counts in `signature`.
 Until the plugin knows the bot's user id it cannot tell, and `signatureForBot` stays at zero.
 
+## Screening events
+
+A host can look at every event before the plugin stores it, and take some out: a code a person sends to link their account, say, which must reach no inbox, mirror or log.
+`LINE.screen(handler)` attaches the one screen of the webhook and returns the function that detaches it; a second `screen()` while one is attached throws.
+Attach it during setup: the listeners open only after every plugin is set up, so no request arrives before it.
+Until one is attached, and after it is detached, every event is kept.
+
+```ts
+import { definePlugin } from "pi-roundtable";
+import { LINE, type LineScreen } from "pi-roundtable-line";
+
+const screen: LineScreen = async (event) =>
+	isLinkCode(event.raw) ? "consume" : "keep";
+
+export const linkCodes = definePlugin({
+	name: "link-codes",
+	requires: [LINE], // so line() must come before this plugin in `plugins`
+	setup: (context) => {
+		context.services.get(LINE).screen(screen);
+		return {};
+	},
+});
+```
+
+Read `LINE` with `services.get` in `setup`, and declare it in `requires` so the host refuses a plugin list that puts `line()` after it; `services.lazy(LINE)` answers only after every plugin is set up, so it does not suit attaching a screen there.
+
+The screen is asked after the signature and the `destination` passed, and before anything is stored, for every event of the request in order, one at a time (the events of a request that failed before that, a Verify with no events, and a `405` never reach it).
+Every kind of event is asked about, standby and chat-less ones included; the handler filters.
+It gets the `ParsedEvent` with LINE's event as `raw`, and answers `"keep"` or `"consume"`.
+A consumed event is not stored, not routed, not handed to the subscriber and does not record its chat as pending.
+A request whose events are all consumed is a `200` and counts as accepted, like Verify.
+
+A screen that throws, or answers anything else, fails the whole request with `500` and stores nothing, not even the events it had kept; LINE redelivers where it can.
+The log line holds a code, never the event.
+The screen gets a deeply frozen copy of the event, so it cannot change what is stored. It sees what the plugin does not keep for chats that are not connected, so it must not log or keep what it does not consume.
+
+## Calling LINE through the plugin
+
+`LINE.api` calls LINE with the plugin's own token source, timeout and `401` retry, so a host that needs a profile or a reply does not open a second token source.
+Failures throw `LineApiError` (the `status` and an `http_<status>` code) or `LineError` with a short code; no message holds a response body.
+Every call takes `{ signal, timeoutMs }`, where `timeoutMs` replaces the 15-second default.
+
+| Call | Does |
+|---|---|
+| `profile(sourceKey, userId)` | the display name and picture of a group or room member, or of the user of a one-to-one chat; `undefined` when LINE answers `404` (not in the chat), and for someone else in a one-to-one chat without a request |
+| `memberCount(sourceKey)` | how many people a push to the chat reaches (1 for a one-to-one chat), from the quota gate's one-minute reading |
+| `quota()` | `{ limit, used, cap }`: the plan's monthly limit, consumption (at most a minute old; 0 when there is neither a limit nor a `quota.monthlyCap`, which are then not read) and the host's cap |
+| `botInfo()` | the bot's `userId`, `basicId` and, when LINE says, `displayName` and `pictureUrl`; asked once and kept; a call made while the first read is running shares that read and its timeout, so use `signal` to give up sooner |
+| `reply(replyToken, messages)` | answers an event with its single-use reply token: 1 to 5 messages, free of the push quota, not through the outbox |
+| `probeToken()` | `undefined` when a token is held or can be issued now, else the failure's code; tells no failure listener |
+| `onTokenFailure(listener)` | told the code (`token_refused`, `token_unreachable`, `token_malformed`) of each failed issue of the channel access token, whichever part of the plugin asked, once per issue however many callers shared it, never for a probe; returns the function that detaches it |
+
+`senderNameProblem(name, options?)` answers why LINE would refuse a sender name (`empty`, `edge_space`, `too_long`, `control_character`, `forbidden_word`) or `undefined`, so a host can check a name before it queues a push.
+`SENDER_NAME_MAX` and `SENDER_DEFAULTS` are the limit and the default forbidden words it uses.
+A control character is anything in U+0000 to U+001F, U+007F or U+0080 to U+009F.
+
 ## Chats and the allowlist
 
 The first event from a chat the bot has not seen records it as `pending`: its key, when it was first and last seen, and counts.
@@ -184,7 +240,7 @@ The processor that serves it is the package's own; there is no way to read raw i
 | `joined` | `notice`: `"sent"`, `"failed"` or `"unconfirmed"`, truthfully (see [The join notice](#the-join-notice)) |
 | `left` | |
 | `memberJoined`, `memberLeft` | `userIds` |
-| `outboxResult` | `sourceKey`, `originRef`, `status` (`sent`, `dead`, `refused`) and `errorCode` (see [Sending](#sending)) |
+| `outboxResult` | `sourceKey`, `originRef`, `status` (`sent`, `dead`, `refused`), `errorCode` and `attempts` (see [Sending](#sending)) |
 
 Every event but `outboxResult` has `eventId` (LINE's `webhookEventId`, the same on every redelivery), `sourceKey` and `timestamp`; a push is not a webhook event, so `outboxResult` has none of the three.
 No event carries a reply token, a quote token or a URL.
@@ -277,7 +333,8 @@ Message objects hold what you send, so they live in `line_outbox.messages` until
 - **Pushes of at most five objects, per chat and sender.** Objects queued for the same chat and the same sender within `outbox.coalesceMs` (2 seconds, counted from the first object, not from the last) share one push, in the order they were queued; a sixth object starts the next push, and a push that holds five goes at once. Different senders never share a push, and a push is never joined if a later push of the chat exists (that would reorder the chat). The chat's pushes go out strictly in order: a push that is backing off holds the ones behind it (a dead or refused one does not).
 - **A retry key from the start.** Each push gets a UUID the moment its row exists, before any attempt, and every attempt and every retry after a crash sends it as `X-Line-Retry-Key`. LINE keeps a key for 24 hours (`outbox.retryKeyMs`): a push still unsent then is `dead` with `retry_key_expired` and is never sent under a new key.
 - **Outcomes.** `2xx` and `409` (LINE already has this key) are `sent`. `429`, `5xx` and no answer back off (5 seconds doubling to 1 hour, at least `Retry-After`) and retry, up to `outbox.maxAttempts` (12), then `dead` with the last code. Any other `4xx` is `dead` at once with a code: `sender_name_refused` or `sender_icon_refused` when LINE names that property of the request, else `http_<status>`; nothing else of LINE's answer is kept. A push the quota gate refuses is `refused` and is never sent. A push for a chat that stopped being allowed is `dead` with `source_not_allowed`.
-- **Results.** The subscriber hears an `outboxResult` for each push once it has ended, once per distinct `origin` the push carries (once with `originRef: null` when none was given), at least once: a result waits while no subscriber is attached and is told again later, up to 12 times, if the subscriber throws.
+- **Results.** The subscriber hears an `outboxResult` for each push once it has ended, once per distinct `origin` the push carries (once with `originRef: null` when none was given), at least once: a result waits while no subscriber is attached and is told again later, up to 12 times, if the subscriber throws. The event carries `attempts`, how many tries the push took, the one that ended it included (1 for a push LINE refused at once, 2 after a `5xx` and then a refusal), so there is no need to read `line_outbox`.
+- **What counts as a try.** An attempt is counted when a push is taken up and is given back only when the worker stops before the request was made; the migration `outbox-requested` adds `line_outbox.requested_at`, set just before the request goes out. A stop after it cannot say LINE did not take the request, so that try stays counted (and it counts towards `outbox.maxAttempts`).
 - **Crashes.** A push in hand when the process dies has a 2-minute lease; the worker puts it back and sends it again under the same key, which LINE answers with `409` if it had taken the first request.
 - **Service.** The `line-outbox` service runs the worker and counts as `busy` while a push is in flight, so the shutdown waits for it; a push still in flight when the host stops is put back as it was.
 - **Nothing sensitive in logs.** The worker logs push ids, attempt numbers, status words and codes; never message objects, sender names, retry keys or tokens.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-roundtable-line",
-	"version": "0.15.3",
+	"version": "0.16.0",
 	"description": "A LINE Messaging API transport for pi-roundtable: a signed webhook that persists events before it answers, a durable inbox worker, and an allowlist of the groups and chats it mirrors",
 	"type": "module",
 	"license": "MIT",
@@ -33,14 +33,14 @@
 		"test": "bun test"
 	},
 	"peerDependencies": {
-		"pi-roundtable": ">=0.15.0 <0.16.0"
+		"pi-roundtable": ">=0.16.0 <0.17.0"
 	},
 	"devDependencies": {
 		"@biomejs/biome": "2.5.15",
 		"@earendil-works/pi-ai": ">=1.0.0 <2",
 		"@earendil-works/pi-coding-agent": ">=1.0.0 <2",
 		"@types/bun": "1.4.2",
-		"pi-roundtable": "0.15.3",
+		"pi-roundtable": "0.16.0",
 		"typebox": "1.3.34",
 		"typescript": "7.0.2"
 	}

package/src/api-port.ts

@@ -0,0 +1,254 @@
+import type { LineApi, RequestOptions } from "./api.ts";
+import { LineApiError, LineError } from "./errors.ts";
+import { parseSourceKey } from "./events.ts";
+import type { LineOutMessage } from "./outbox.ts";
+import type { QuotaGate } from "./quota.ts";
+import type { TokenSource } from "./token.ts";
+
+export interface LineCallOptions {
+	signal?: AbortSignal;
+	/** Replaces the client's 15-second per-request timeout. */
+	timeoutMs?: number;
+}
+
+/** What LINE shows for a person in a chat. */
+export interface LineProfile {
+	displayName: string;
+	pictureUrl?: string;
+}
+
+/** The month as the quota gate last read it (at most a minute old), and the host's own cap. */
+export interface LineQuotaStanding {
+	/** The plan's monthly limit; undefined for a plan without one. */
+	limit: number | undefined;
+	/** Messages used this month; 0 when there is neither a plan limit nor a `quota.monthlyCap`, which are then not read. */
+	used: number;
+	/** `quota.monthlyCap` from the options; undefined when unset. */
+	cap: number | undefined;
+}
+
+export interface LineBotInfo {
+	userId: string;
+	/** The `@…` basic id. */
+	basicId: string;
+	displayName?: string;
+	pictureUrl?: string;
+}
+
+/**
+ * LINE's API through the plugin's own token source, timeout and 401-retry. Failures throw
+ * `LineApiError` (status and `http_<status>`) or `LineError` with a short code; no message holds a
+ * response body.
+ */
+export interface LineApiPort {
+	/**
+	 * A group or room member's profile (`/v2/bot/{group|room}/{id}/member/{userId}`), or, in a
+	 * one-to-one chat, that user's own (`/v2/bot/profile/{userId}`). Undefined when LINE answers 404
+	 * (not in the chat), and without a request for a one-to-one chat with someone else.
+	 */
+	profile(
+		sourceKey: string,
+		userId: string,
+		options?: LineCallOptions,
+	): Promise<LineProfile | undefined>;
+	/** How many people a push to the chat reaches: the member count, 1 for a one-to-one chat. Shares the quota gate's one-minute reading. */
+	memberCount(sourceKey: string, options?: LineCallOptions): Promise<number>;
+	/** The quota gate's reading, refreshed when older than a minute. */
+	quota(): Promise<LineQuotaStanding>;
+	/** `/v2/bot/info`, asked once and kept (the ids do not change); a failure is asked again next time. */
+	botInfo(options?: LineCallOptions): Promise<LineBotInfo>;
+	/** Answers an event with its single-use reply token: 1 to 5 messages, free of the push quota, not through the outbox. */
+	reply(
+		replyToken: string,
+		messages: readonly LineOutMessage[],
+		options?: LineCallOptions,
+	): Promise<void>;
+	/** Undefined when a token is held or can be issued now, else the failure's code. Tells no failure listener. */
+	probeToken(): Promise<string | undefined>;
+	/**
+	 * Told the code (`token_refused`, `token_unreachable`, `token_malformed`) of each failed issue of
+	 * the channel access token, whichever part of the plugin asked; once per issue however many callers
+	 * shared it; never for a probe. Returns the function that detaches it. It must not throw.
+	 */
+	onTokenFailure(listener: (code: string) => void): () => void;
+}
+
+/** The most message objects one reply holds. */
+const REPLY_MAX_MESSAGES = 5;
+
+export interface LineApiPortDeps {
+	api: LineApi;
+	tokens: TokenSource;
+	quota: QuotaGate;
+}
+
+/** A call's options as the client takes them; a timeout that is not a positive number is refused. */
+function callOf(
+	options: LineCallOptions | undefined,
+): Pick<RequestOptions, "signal" | "timeoutMs"> {
+	if (!options) return {};
+	const { signal, timeoutMs } = options;
+	if (
+		timeoutMs !== undefined &&
+		!(
+			typeof timeoutMs === "number" &&
+			Number.isFinite(timeoutMs) &&
+			timeoutMs > 0
+		)
+	)
+		throw new LineError(
+			"bad_options",
+			"line: timeoutMs is a positive number of milliseconds",
+		);
+	return {
+		...(signal ? { signal } : {}),
+		...(timeoutMs === undefined ? {} : { timeoutMs }),
+	};
+}
+
+const text = (value: unknown): string | undefined =>
+	typeof value === "string" && value !== "" ? value : undefined;
+
+/** The port other plugins call LINE through: the plugin's token source, timeout and 401-retry. */
+export function lineApiPort(deps: LineApiPortDeps): LineApiPort {
+	const { api, tokens, quota } = deps;
+	let botInfo: LineBotInfo | undefined;
+	/** The first read in progress, shared by callers that arrive before it ends. */
+	let asking: Promise<LineBotInfo> | undefined;
+	const readBotInfo = async (
+		call: Pick<RequestOptions, "timeoutMs">,
+	): Promise<LineBotInfo> => {
+		const found = (await api.json("/v2/bot/info", call)) as
+			| {
+					userId?: unknown;
+					basicId?: unknown;
+					displayName?: unknown;
+					pictureUrl?: unknown;
+			  }
+			| undefined;
+		const userId = text(found?.userId);
+		const basicId = text(found?.basicId);
+		if (!userId || !basicId || !/^@\S+$/.test(basicId))
+			throw new LineError(
+				"bot_info_malformed",
+				"line: bot info has no userId or basicId",
+			);
+		const displayName = text(found?.displayName);
+		const pictureUrl = text(found?.pictureUrl);
+		botInfo = {
+			userId,
+			basicId,
+			...(displayName ? { displayName } : {}),
+			...(pictureUrl ? { pictureUrl } : {}),
+		};
+		return botInfo;
+	};
+	return {
+		async profile(sourceKey, userId, options) {
+			const call = callOf(options);
+			const source = parseSourceKey(sourceKey);
+			if (!source)
+				throw new LineError("bad_source_key", "line: not a source key");
+			if (typeof userId !== "string" || userId === "")
+				throw new LineError(
+					"bad_user_id",
+					"line: a user id is a non-empty string",
+				);
+			// A one-to-one chat has one member; LINE is not asked about anyone else in it.
+			if (source.kind === "user" && source.id !== userId) return undefined;
+			const user = encodeURIComponent(userId);
+			const path =
+				source.kind === "user"
+					? `/v2/bot/profile/${user}`
+					: `/v2/bot/${source.kind}/${encodeURIComponent(source.id)}/member/${user}`;
+			const response = await api.exchange(path, call);
+			if (response.status === 404) {
+				await response.body?.cancel().catch(() => undefined);
+				return undefined;
+			}
+			if (!response.ok) {
+				await response.body?.cancel().catch(() => undefined);
+				throw new LineApiError(
+					response.status,
+					`http_${response.status}`,
+					`line: a profile lookup answered ${response.status}`,
+					response.headers.get("x-line-request-id") ?? undefined,
+				);
+			}
+			const found = (await response.json().catch(() => undefined)) as
+				| { displayName?: unknown; pictureUrl?: unknown }
+				| undefined;
+			if (
+				typeof found?.displayName !== "string" ||
+				found.displayName.trim() === ""
+			)
+				throw new LineError(
+					"profile_malformed",
+					"line: the profile has no displayName",
+				);
+			const pictureUrl = text(found.pictureUrl);
+			return {
+				displayName: found.displayName,
+				...(pictureUrl ? { pictureUrl } : {}),
+			};
+		},
+		memberCount: (sourceKey, options) =>
+			quota.recipients(sourceKey, callOf(options)),
+		async quota() {
+			const { limit, used } = await quota.standing();
+			return { limit, used, cap: quota.cap };
+		},
+		async botInfo(options) {
+			const { signal, timeoutMs } = callOf(options);
+			signal?.throwIfAborted();
+			if (botInfo) return { ...botInfo };
+			// Callers that arrive while a read is in progress share it, and so its timeout (the first
+			// caller's); each still hears its own signal.
+			asking ??= readBotInfo(
+				timeoutMs === undefined ? {} : { timeoutMs },
+			).finally(() => {
+				asking = undefined;
+			});
+			const read = asking;
+			if (!signal) return { ...(await read) };
+			let onAbort: (() => void) | undefined;
+			const aborted = new Promise<never>((_, reject) => {
+				onAbort = () => reject(signal.reason);
+				signal.addEventListener("abort", onAbort, { once: true });
+			});
+			try {
+				return { ...(await Promise.race([read, aborted])) };
+			} finally {
+				if (onAbort) signal.removeEventListener("abort", onAbort);
+			}
+		},
+		async reply(replyToken, messages, options) {
+			const call = callOf(options);
+			if (typeof replyToken !== "string" || replyToken === "")
+				throw new LineError(
+					"bad_reply_token",
+					"line: a reply token is a non-empty string",
+				);
+			if (
+				!Array.isArray(messages) ||
+				messages.length === 0 ||
+				messages.length > REPLY_MAX_MESSAGES ||
+				messages.some(
+					(message) =>
+						typeof message !== "object" ||
+						message === null ||
+						Array.isArray(message) ||
+						typeof message.type !== "string" ||
+						message.type === "",
+				)
+			)
+				throw new LineError(
+					"bad_messages",
+					`line: a reply takes 1 to ${REPLY_MAX_MESSAGES} message objects`,
+				);
+			await api.reply(replyToken, messages, call);
+		},
+		probeToken: () => tokens.probe(),
+		onTokenFailure: (listener) => tokens.onFailure(listener),
+	};
+}

package/src/api.ts

@@ -201,21 +201,26 @@ export class LineApi {
 	async reply(
 		replyToken: string,
 		messages: readonly unknown[],
-		signal?: AbortSignal,
+		call: Pick<RequestOptions, "signal" | "timeoutMs"> = {},
 	): Promise<void> {
 		await this.request("/v2/bot/message/reply", {
 			method: "POST",
 			headers: { "content-type": "application/json" },
 			body: JSON.stringify({ replyToken, messages }),
-			...(signal ? { signal } : {}),
+			...call,
 		});
 	}
 
 	/** How many people a push to a chat reaches: the member count of a group or room, else one. */
-	async recipients(kind: SourceKind, id: string): Promise<number> {
+	async recipients(
+		kind: SourceKind,
+		id: string,
+		call: Pick<RequestOptions, "signal" | "timeoutMs"> = {},
+	): Promise<number> {
 		if (kind === "user") return 1;
 		const found = (await this.json(
 			`/v2/bot/${kind}/${encodeURIComponent(id)}/members/count`,
+			call,
 		)) as { count?: unknown };
 		if (typeof found?.count !== "number" || !Number.isInteger(found.count))
 			throw new LineError(

package/src/index.ts

@@ -1,3 +1,10 @@
+export type {
+	LineApiPort,
+	LineBotInfo,
+	LineCallOptions,
+	LineProfile,
+	LineQuotaStanding,
+} from "./api-port.ts";
 export type {
 	LineContentRequest,
 	LineContentResult,
@@ -43,7 +50,17 @@ export type { LineBridgePort } from "./port.ts";
 export { LINE } from "./port.ts";
 export type { QuotaOptions } from "./quota.ts";
 export type { RetentionOptions } from "./retention.ts";
-export type { LineSender, SenderOptions } from "./sender.ts";
+export type { LineScreen, LineScreenVerdict } from "./screen.ts";
+export type {
+	LineSender,
+	SenderNameProblem,
+	SenderOptions,
+} from "./sender.ts";
+export {
+	SENDER_DEFAULTS,
+	SENDER_NAME_MAX,
+	senderNameProblem,
+} from "./sender.ts";
 export type {
 	LineSource,
 	LineSourceSummary,

package/src/messages.ts

@@ -115,6 +115,13 @@ export interface LineOutboxResultEvent {
 	 * `source_not_allowed`); null when it was sent.
 	 */
 	errorCode: string | null;
+	/**
+	 * How many tries the push took, the one that ended it included: 1 for a push LINE refused at once,
+	 * 2 after a `5xx` and then a refusal. A try counts once its request has been made to LINE, also
+	 * when a stop cut it short, and once the worker took the push up only to end it without a request
+	 * (`refused`, `source_not_allowed`); a stop before the request does not count.
+	 */
+	attempts: number;
 }
 
 export type LineEvent =

package/src/migrations.ts

@@ -136,9 +136,21 @@ export const OUTBOX_MIGRATION: Migration = {
 	},
 };
 
+/**
+ * When the request of the push's current attempt was handed to the network. A stop that comes after
+ * it cannot say LINE did not take the request, so the attempt stays counted.
+ */
+export const OUTBOX_REQUESTED_MIGRATION: Migration = {
+	name: "outbox-requested",
+	up: async (sql) => {
+		await sql`ALTER TABLE line_outbox ADD COLUMN IF NOT EXISTS requested_at TIMESTAMPTZ`;
+	},
+};
+
 /** Every migration of the package, in the order they run. */
 export const MIGRATIONS: Migration[] = [
 	INBOX_MIGRATION,
 	MESSAGES_MIGRATION,
 	OUTBOX_MIGRATION,
+	OUTBOX_REQUESTED_MIGRATION,
 ];

package/src/outbox-worker.ts

@@ -138,7 +138,7 @@ export class OutboxWorker {
 				ORDER BY id LIMIT 1`) as { id: string | number }[];
 			if (!head) return undefined;
 			const [claimed] = (await tx`UPDATE line_outbox
-				SET status = 'sending', claimed_at = ${now}, attempts = attempts + 1,
+				SET status = 'sending', claimed_at = ${now}, requested_at = NULL, attempts = attempts + 1,
 					first_attempt_at = COALESCE(first_attempt_at, ${now})
 				WHERE id = (SELECT id FROM line_outbox WHERE id = ${head.id} AND status = 'queued' FOR UPDATE SKIP LOCKED)
 				RETURNING id, source_key, sender_name, sender_icon_url, messages, retry_key, attempts,
@@ -214,6 +214,11 @@ export class OutboxWorker {
 				const messages = row.messages.map((message) =>
 					Object.keys(sender).length > 0 ? { ...message, sender } : message,
 				);
+				// A stop that comes before this leaves the attempt uncounted; one after it cannot say LINE
+				// did not take the request.
+				controller.signal.throwIfAborted();
+				await this.#sql`UPDATE line_outbox SET requested_at = ${this.#now()}
+					WHERE id = ${row.id} AND status = 'sending' AND claimed_at = ${row.claimed_at}`;
 				const pushed = await this.#api.push(
 					source.id,
 					messages,
@@ -245,7 +250,8 @@ export class OutboxWorker {
 				this.#quota.settle(reserved.reservation, sent);
 			}
 		} catch (error) {
-			// Giving up because the worker stops is the restart's doing: the push goes back as it was.
+			// Giving up because the worker stops is the restart's doing: the push goes back as it was,
+			// unless its request had already been made.
 			if (this.#stopping && controller.signal.aborted) {
 				await this.#later(row, 0, "worker_stopped", false);
 				return;
@@ -307,7 +313,8 @@ export class OutboxWorker {
 		counted: boolean,
 	): Promise<void> {
 		await this.#sql`UPDATE line_outbox
-			SET status = 'queued', claimed_at = NULL, attempts = attempts - ${counted ? 0 : 1},
+			SET status = 'queued', claimed_at = NULL,
+				attempts = attempts - CASE WHEN ${counted ? 1 : 0}::int = 0 AND requested_at IS NULL THEN 1 ELSE 0 END,
 				next_attempt_at = ${new Date(this.#now().getTime() + delayMs)}, last_error_code = ${code}
 			WHERE id = ${row.id} AND status = 'sending' AND claimed_at = ${row.claimed_at}`;
 	}
@@ -332,8 +339,9 @@ export class OutboxWorker {
 			last_error_code: string | null;
 			origin_refs: (string | null)[];
 			notify_attempts: number;
+			attempts: number;
 		}[] = await this
-			.#sql`SELECT id, source_key, status, last_error_code, origin_refs, notify_attempts
+			.#sql`SELECT id, source_key, status, last_error_code, origin_refs, notify_attempts, attempts
 			FROM line_outbox
 			WHERE notified_at IS NULL AND status IN ('sent', 'dead', 'refused')
 				AND (notify_after IS NULL OR notify_after <= ${now})
@@ -356,6 +364,7 @@ export class OutboxWorker {
 								originRef,
 								status: row.status,
 								errorCode: row.last_error_code,
+								attempts: row.attempts,
 							},
 							controller.signal,
 						);

package/src/plugin.ts

@@ -4,6 +4,7 @@ import {
 	type RoundtablePlugin,
 } from "pi-roundtable";
 import { LineApi } from "./api.ts";
+import { lineApiPort } from "./api-port.ts";
 import { BotIdentity } from "./bot.ts";
 import { LineConsumer, NO_KEEP } from "./consumer.ts";
 import { MessageContent } from "./content.ts";
@@ -18,6 +19,7 @@ import { OutboxWorker } from "./outbox-worker.ts";
 import { LINE, type LineBridgePort } from "./port.ts";
 import { QuotaGate } from "./quota.ts";
 import { RetentionSweeper } from "./retention.ts";
+import type { LineScreen } from "./screen.ts";
 import { PgSources } from "./sources.ts";
 import { LineSurface } from "./surface.ts";
 import { TokenSource } from "./token.ts";
@@ -135,6 +137,8 @@ export function line(options: LineOptions): RoundtablePlugin {
 				...(options.outbox ? { options: options.outbox } : {}),
 			});
 			const sending = outboxWorker;
+			// The one screen of the webhook; read at each request, so a detach takes effect at once.
+			let screen: LineScreen | undefined;
 			const port: LineBridgePort = {
 				sources,
 				outbox,
@@ -162,6 +166,16 @@ export function line(options: LineOptions): RoundtablePlugin {
 					};
 				},
 				content: (messageId, request) => content.fetch(messageId, request),
+				api: lineApiPort({ api, tokens, quota }),
+				screen: (handler) => {
+					if (typeof handler !== "function")
+						throw new TypeError("line: a screen is a function");
+					if (screen) throw new Error("line: a screen is already attached");
+					screen = handler;
+					return () => {
+						if (screen === handler) screen = undefined;
+					};
+				},
 			};
 			context.services.provide(LINE, port);
 			return {
@@ -215,6 +229,7 @@ export function line(options: LineOptions): RoundtablePlugin {
 							botUserId: () => bot.current(),
 							stored: () => worker.kick(),
 							stats: webhooks,
+							screen: () => screen,
 						}),
 					},
 				],

package/src/port.ts

@@ -1,7 +1,9 @@
 import { serviceKey } from "pi-roundtable";
+import type { LineApiPort } from "./api-port.ts";
 import type { LineContentRequest, LineContentResult } from "./content.ts";
 import type { LineSubscriber } from "./messages.ts";
 import type { LineOutbox } from "./outbox.ts";
+import type { LineScreen } from "./screen.ts";
 import type { LineSources } from "./sources.ts";
 import type { WebhookHealth } from "./webhook.ts";
 
@@ -43,6 +45,14 @@ export interface LineBridgePort {
 		messageId: string,
 		request?: LineContentRequest,
 	): Promise<LineContentResult>;
+	/** LINE's API through the plugin's token; see `LineApiPort`. */
+	readonly api: LineApiPort;
+	/**
+	 * Attaches the one screen of the webhook; a second is refused (throws). Attach it during setup:
+	 * the listeners open only after every plugin is set up, so no request arrives before it. Until one
+	 * is attached, and after it is detached, every event is kept. Returns the function that detaches it.
+	 */
+	screen(handler: LineScreen): () => void;
 }
 
 export const LINE = serviceKey<LineBridgePort>("roundtable.line", {

package/src/quota.ts

@@ -1,4 +1,4 @@
-import type { LineApi } from "./api.ts";
+import type { LineApi, RequestOptions } from "./api.ts";
 import { LineError } from "./errors.ts";
 import { parseSourceKey } from "./events.ts";
 
@@ -90,7 +90,10 @@ export class QuotaGate {
 	}
 
 	/** How many people a push to the chat reaches; a count is trusted for a minute. */
-	async recipients(sourceKey: string): Promise<number> {
+	async recipients(
+		sourceKey: string,
+		call: Pick<RequestOptions, "signal" | "timeoutMs"> = {},
+	): Promise<number> {
 		const source = parseSourceKey(sourceKey);
 		if (!source)
 			throw new LineError("bad_source_key", "line: not a source key");
@@ -98,11 +101,26 @@ export class QuotaGate {
 		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);
+		const n = await this.#api.recipients(source.kind, source.id, call);
 		this.#counts.set(sourceKey, { n, at: now });
 		return n;
 	}
 
+	/**
+	 * The month as the gate last read it, refreshed when older than a minute: the plan's limit
+	 * (undefined without one) and the consumption, which is 0 when there is neither a limit nor a cap
+	 * of our own, because nothing is read then.
+	 */
+	async standing(): Promise<{ limit: number | undefined; used: number }> {
+		const { limit, used } = await this.#read();
+		return { limit, used };
+	}
+
+	/** The `monthlyCap` of the options, if one is set. */
+	get cap(): number | undefined {
+		return this.#cap;
+	}
+
 	async #read(): Promise<Reading> {
 		const now = this.#now().getTime();
 		if (this.#reading && now - this.#reading.at < this.#cacheMs)

package/src/screen.ts

@@ -0,0 +1,14 @@
+import type { ParsedEvent } from "./events.ts";
+
+/** What the webhook does with one signed event of this bot: store it, or drop it unstored. */
+export type LineScreenVerdict = "keep" | "consume";
+
+/**
+ * Asked, in order, for every event of a request whose signature and destination passed, before the
+ * request's events are stored. A consumed event is never stored, routed or handed to the subscriber.
+ * A screen that throws, or answers anything but "keep" or "consume", fails the whole request with
+ * 500 and stores nothing (LINE redelivers where it can). It sees the event's `raw` body: it must not
+ * log or keep what it does not consume. The event is a deeply frozen copy: a screen cannot change
+ * what is stored.
+ */
+export type LineScreen = (event: ParsedEvent) => Promise<LineScreenVerdict>;

package/src/sender.ts

@@ -20,9 +20,9 @@ export interface SenderOptions {
 	forbiddenWords: readonly string[];
 }
 
-export const SENDER_DEFAULTS: SenderOptions = {
-	forbiddenWords: ["LINE", "LY"],
-};
+export const SENDER_DEFAULTS: SenderOptions = Object.freeze({
+	forbiddenWords: Object.freeze(["LINE", "LY"]),
+});
 
 export const SENDER_NAME_MAX = 20;
 export const SENDER_ICON_MAX = 2000;
@@ -51,6 +51,52 @@ export function checkSenderOptions(options: Partial<SenderOptions>): void {
 const WORD =
 	/(?:\p{Script=Latin}|\p{M}|\p{N})+|(?:(?!\p{Script=Latin})\p{L})+/gu;
 
+/** Why LINE would refuse a sender name. */
+export type SenderNameProblem =
+	| "empty"
+	| "edge_space"
+	| "control_character"
+	| "too_long"
+	| "forbidden_word";
+
+/**
+ * Why LINE would refuse `name` as a sender name, or undefined when it would take it. The first
+ * problem found is the one returned, checked in the order `empty`, `edge_space`,
+ * `too_long`, `control_character`, `forbidden_word`. `control_character` covers C0, DEL and C1
+ * (U+0080 to U+009F). Never throws: a value that is not a string is `empty`.
+ */
+export function senderNameProblem(
+	name: string,
+	options: SenderOptions = SENDER_DEFAULTS,
+): SenderNameProblem | undefined {
+	if (typeof name !== "string" || name.trim() === "") return "empty";
+	if (name !== name.trim()) return "edge_space";
+	if (Array.from(name).length > SENDER_NAME_MAX) return "too_long";
+	// biome-ignore lint/suspicious/noControlCharactersInRegex: control characters are what is refused
+	if (/[\u0000-\u001f\u007f-\u009f]/.test(name)) return "control_character";
+	// Full-width letters are the letters they look like.
+	const words = (name.normalize("NFKC").match(WORD) ?? []).map((w) =>
+		w.toLowerCase(),
+	);
+	// An options object without the list (a cast, or untyped JavaScript) means the default list.
+	const forbidden = (
+		Array.isArray(options?.forbiddenWords)
+			? options.forbiddenWords
+			: SENDER_DEFAULTS.forbiddenWords
+	).map((w) => w.normalize("NFKC").toLowerCase());
+	return words.some((w) => forbidden.includes(w))
+		? "forbidden_word"
+		: undefined;
+}
+
+const NAME_PROBLEM_TEXT: Record<SenderNameProblem, string> = {
+	empty: "a sender name is a non-empty string",
+	edge_space: "a sender name has no leading or trailing space",
+	too_long: `a sender name is at most ${SENDER_NAME_MAX} characters`,
+	control_character: "a sender name has no control characters",
+	forbidden_word: "a sender name may not use a word LINE refuses",
+};
+
 /**
  * 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
@@ -71,25 +117,9 @@ export function validateSender(
 		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;
+		const problem = senderNameProblem(name as string, options);
+		if (problem) throw bad(NAME_PROBLEM_TEXT[problem]);
+		checked.name = name as string;
 	}
 	if (iconUrl !== undefined) {
 		if (typeof iconUrl !== "string" || iconUrl.length > SENDER_ICON_MAX)

package/src/token.ts

@@ -1,6 +1,6 @@
 import { createHmac, timingSafeEqual } from "node:crypto";
 import { scrubDiagnostic } from "pi-roundtable/kit";
-import { LineApiError, LineError } from "./errors.ts";
+import { errorCode, LineApiError, LineError } from "./errors.ts";
 
 /** How the package gets the channel access token it calls LINE with. */
 export type TokenMode = "stateless" | { static: string };
@@ -34,6 +34,12 @@ export interface TokenSourceOptions {
 	baseUrl?: string;
 }
 
+/** One issue of a stateless token in progress; `quiet` until a caller other than a probe shares it. */
+interface Flight {
+	promise: Promise<Issued>;
+	quiet: boolean;
+}
+
 interface Issued {
 	token: string;
 	/** Epoch milliseconds after which the token is replaced. */
@@ -44,7 +50,8 @@ interface Issued {
  * Hands out the channel access token. It issues stateless tokens one at a time (concurrent callers
  * share one request), keeps a token in memory only until a minute before it lapses, and forgets
  * one LINE rejected. The token and the secret live in private fields: they are in no log, no error
- * message and no serialized form of this object.
+ * message and no serialized form of this object. A failed issue is told, by its code, to the
+ * listeners of {@link TokenSource.onFailure}.
  */
 export class TokenSource {
 	readonly #id: string;
@@ -54,9 +61,10 @@ export class TokenSource {
 	readonly #now: () => number;
 	readonly #base: string;
 	#current: Issued | undefined;
-	#inflight: Promise<Issued> | undefined;
+	#inflight: Flight | undefined;
 	#issued = 0;
 	#lastFailure: string | undefined;
+	readonly #listeners = new Set<(code: string) => void>();
 
 	constructor(options: TokenSourceOptions) {
 		const {
@@ -118,10 +126,64 @@ export class TokenSource {
 		if (this.#static) return this.#static;
 		const held = this.#current;
 		if (held && held.validUntil > this.#now()) return held.token;
-		this.#inflight ??= this.#issue().finally(() => {
-			this.#inflight = undefined;
-		});
-		return (await this.#inflight).token;
+		return (await this.#join(false)).token;
+	}
+
+	/**
+	 * Undefined when a token is held or can be issued now, else the code of the failure. An issue it
+	 * starts is told to no listener, unless a caller of `token()` shares it meanwhile.
+	 */
+	async probe(): Promise<string | undefined> {
+		if (this.#static) return undefined;
+		const held = this.#current;
+		if (held && held.validUntil > this.#now()) return undefined;
+		try {
+			await this.#join(true);
+			return undefined;
+		} catch (error) {
+			return errorCode(error);
+		}
+	}
+
+	/**
+	 * Calls `listener` with the code of each failed issue (`token_refused`, `token_unreachable`,
+	 * `token_malformed`), once per issue however many callers shared it. Returns the function that
+	 * detaches it. A listener that throws, or returns a promise that rejects, is ignored.
+	 */
+	onFailure(listener: (code: string) => void): () => void {
+		this.#listeners.add(listener);
+		return () => void this.#listeners.delete(listener);
+	}
+
+	/** The issue in progress, started when there is none. A caller that is not a probe makes it audible. */
+	#join(quiet: boolean): Promise<Issued> {
+		if (this.#inflight) {
+			if (!quiet) this.#inflight.quiet = false;
+			return this.#inflight.promise;
+		}
+		const flight: Flight = {
+			quiet,
+			promise: this.#issue()
+				.catch((error: unknown) => {
+					if (!flight.quiet) this.#notify(errorCode(error));
+					throw error;
+				})
+				.finally(() => {
+					this.#inflight = undefined;
+				}),
+		};
+		this.#inflight = flight;
+		return flight.promise;
+	}
+
+	#notify(code: string): void {
+		for (const listener of [...this.#listeners])
+			try {
+				// An async listener that rejects is as harmless as one that throws.
+				void Promise.resolve(listener(code)).catch(() => undefined);
+			} catch {
+				// A listener must not throw; one that does costs the others nothing.
+			}
 	}
 
 	/**

package/src/webhook.ts

@@ -1,8 +1,9 @@
 import type { SQL } from "bun";
 import type { Logger } from "pi-roundtable";
 import { errorCode, LineError } from "./errors.ts";
-import { parseWebhook } from "./events.ts";
+import { type ParsedEvent, parseWebhook } from "./events.ts";
 import { persistEvents } from "./intake.ts";
+import type { LineScreen } from "./screen.ts";
 import type { TokenSource } from "./token.ts";
 
 /** The most a webhook request body may hold: LINE sends far less, and anything near this is not LINE. */
@@ -83,6 +84,8 @@ export interface WebhookOptions {
 	stored: () => void;
 	/** Counts what the webhook answers; the plugin reads it for `LINE.health()`. */
 	stats: WebhookStats;
+	/** The screen attached at the moment of the request, if any; asked about each event before it is stored. */
+	screen?: () => LineScreen | undefined;
 	maxBytes?: number;
 }
 
@@ -140,12 +143,48 @@ function claimedDestination(body: Uint8Array): string | undefined {
 	}
 }
 
+function deepFreeze<T>(value: T): T {
+	if (typeof value === "object" && value !== null) {
+		for (const inner of Object.values(value)) deepFreeze(inner);
+		Object.freeze(value);
+	}
+	return value;
+}
+
+const frozenCopy = (event: ParsedEvent): ParsedEvent =>
+	deepFreeze(structuredClone(event));
+
+/**
+ * The events the screen keeps, asked about each in order. Rejects when the screen throws or answers
+ * anything but "keep" or "consume", so no event of the request is stored on a half-made decision.
+ */
+async function screened(
+	screen: LineScreen,
+	events: readonly ParsedEvent[],
+): Promise<ParsedEvent[]> {
+	const kept: ParsedEvent[] = [];
+	for (const event of events) {
+		// A frozen copy: whatever the screen does to it, the event that is stored is LINE's.
+		const verdict: unknown = await screen(frozenCopy(event));
+		if (verdict === "keep") kept.push(event);
+		else if (verdict !== "consume")
+			throw new LineError(
+				"screen_verdict_invalid",
+				'line: a screen answers "keep" or "consume"',
+			);
+	}
+	return kept;
+}
+
 /**
  * LINE's webhook: the raw body is verified against `x-line-signature` before anything is parsed,
  * every event is stored in one transaction, and only then does it answer `200`. A database that
  * is down answers `500`, which makes LINE's redelivery (if the channel has it on) resend.
- * An empty `events` array (LINE's Verify button) is a `200` that stores nothing. Each answer adds
- * to `options.stats`, which keeps counts and times only.
+ * An empty `events` array (LINE's Verify button) is a `200` that stores nothing. When a screen is
+ * attached it is asked about each event, once the signature and destination have passed, and a
+ * consumed event is never stored; a request whose events are all consumed is a `200` like Verify,
+ * and a screen that fails is a `500` that stores nothing. Each answer adds to `options.stats`,
+ * which keeps counts and times only.
  */
 export function webhookHandler(
 	options: WebhookOptions,
@@ -184,16 +223,26 @@ export function webhookHandler(
 			options.logger.warn("a LINE webhook was refused: it is for another bot");
 			return reply(403, "Forbidden");
 		}
-		if (parsed.events.length === 0) {
+		let events = parsed.events;
+		const screen = options.screen?.();
+		if (screen && events.length > 0) {
+			try {
+				events = await screened(screen, events);
+			} catch (error) {
+				// The code only: the message could quote the event that was screened.
+				options.logger.error(
+					{ code: errorCode(error) },
+					"a LINE event could not be screened; the request was refused",
+				);
+				return reply(500, "Internal Server Error");
+			}
+		}
+		if (events.length === 0) {
 			stats.accept(options.now());
 			return reply(200, "OK");
 		}
 		try {
-			const result = await persistEvents(
-				options.sql,
-				parsed.events,
-				options.now(),
-			);
+			const result = await persistEvents(options.sql, events, options.now());
 			options.logger.info(result, "LINE events stored");
 			if (result.queued > 0) options.stored();
 		} catch (error) {