pi-roundtable-line 0.0.0-stage → 0.9.13

package/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [Unreleased]
+
+## [0.9.13] - 2026-10-13
+
+### Added
+
+- First slice of the package: `line(options)`, the `LINE` service, a signed webhook that stores every event before it answers, an allowlist of chats, and a durable inbox worker. Stateless channel access tokens (`client_credentials` with the channel id and secret) are issued on demand, kept in memory and never logged. The inbox claims with `FOR UPDATE SKIP LOCKED` per chat, recovers expired leases, retries with backoff and sets an event aside as dead after 12 attempts. Delivery is at least once: a claim is renewed while its handler runs and fences every write that ends it, edits and unsends of one message run strictly in order and wait for an original that is backing off, and nothing of a blocked chat is handed out again. A handler is bounded by `maxHandleMs` (10 minutes: its signal is aborted and the event fails with `handler_timeout`), the worker refills free slots on a kick, a poll or a finished handler while others are still running, and what a chat the bot left still has waiting is dropped with its payload, apart from `unsend` events, which are still delivered so a message the customer took back is taken down. The processor's signal is also aborted when the worker stops or loses the event's lease, the processor is looked up after the claim, and `maxHandleMs`, `leaseMs` and `pollMs` above 2147483647 ms are refused.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 wayne930242
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,146 @@
-# Temporary Holding Version
+# pi-roundtable-line
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A LINE Messaging API transport for [pi-roundtable][roundtable].
+It receives the events of a LINE Official Account's group chats on the host's HTTP listener, stores each one before it answers, and hands the stored events of the chats you allow to one consumer, in order and at least once.
+Source lives in [`packages/line`][source] in the pi-roundtable repository and releases in lockstep with the core.
+
+[roundtable]: https://www.npmjs.com/package/pi-roundtable
+[source]: https://github.com/wayne930242/pi-roundtable/tree/master/packages/line
+
+This first slice covers intake: the credentials and token source, the webhook, the allowlist of chats, and the inbox worker.
+Mirroring messages to a consumer, sending, quota and the join notice follow in later releases of this package.
+
+## Requirements
+
+- Bun 1.3 or later, and pi-roundtable `>=0.9.0 <0.10.0` as a peer dependency.
+- PostgreSQL, which the host already needs.
+- An HTTP listener on the host that LINE can reach over HTTPS (the webhook URL is set in the channel's settings).
+- A Messaging API channel: its channel id and channel secret.
+
+## Install
+
+```sh
+bun add pi-roundtable-line
+```
+
+```ts
+import type { RoundtableConfig } from "pi-roundtable";
+import { line } from "pi-roundtable-line";
+
+export default {
+	// ...
+	http: { port: 3000, hostname: "127.0.0.1" },
+	plugins: [
+		line({
+			credentials: {
+				channelId: process.env.LINE_CHANNEL_ID ?? "",
+				channelSecret: process.env.LINE_CHANNEL_SECRET ?? "",
+			},
+		}),
+	],
+} satisfies RoundtableConfig;
+```
+
+Point the channel's webhook URL at `https://<your host>/line/webhook` and turn the webhook on.
+The route attaches to the `public` listener; set `listener` for another, and `webhookPath` to move it.
+
+## Credentials
+
+The channel id and secret are all a stateless setup needs.
+The package asks LINE for a channel access token (`POST /oauth2/v3/token`, `grant_type=client_credentials`), keeps it in memory until a minute before it lapses (about 15 minutes), asks again on demand, and asks again once when LINE answers a call with `401`.
+Concurrent callers share one request.
+
+```ts
+credentials: { channelId, channelSecret, token: "stateless" } // the default
+credentials: { channelId, channelSecret, token: { static: longLivedToken } } // a token a console issued
+```
+
+A static token cannot be replaced, so a `401` on it is final.
+The channel secret also verifies the webhook signature.
+
+Neither the secret nor a token is written to disk, logged, or put in an error message, and neither shows in `JSON.stringify` or `console.log` of the objects that hold them.
+Errors carry a short code (`token_refused`, `api_unreachable`, `http_429`, ...) and LINE's request id, never a response body.
+
+## The webhook
+
+`POST /line/webhook` answers:
+
+| Status | When |
+|---|---|
+| `200` | the events were stored (or there were none: LINE's Verify button) |
+| `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 |
+
+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.
+An event with a `webhookEventId` already stored is not stored again, so LINE's redelivery (a channel setting of its own) is safe.
+
+The bot's user id comes from `GET /v2/bot/info` when the host starts.
+If LINE cannot be reached then, the plugin logs a warning with a code and keeps trying (at most every 30 seconds, when a webhook arrives); until it knows the id a webhook is vouched for by its signature alone.
+
+## 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.
+Nothing a member wrote is stored, and the event's payload is dropped.
+A chat is a key `line:group:<id>`, `line:room:<id>` or `line:user:<id>`.
+
+```ts
+import { LINE } from "pi-roundtable-line";
+
+const { sources } = context.services.get(LINE);
+await sources.pending(); // chats waiting for a decision
+await sources.allow("line:group:C...");
+await sources.block("line:group:C...");
+await sources.summary("line:group:C..."); // adds the group's name, asked of LINE
+```
+
+| Status | Meaning |
+|---|---|
+| `pending` | seen, not decided; events are dropped unread |
+| `allowed` | events are stored and handed to the consumer |
+| `blocked` | events are dropped; `block` also drops what was waiting |
+| `left` | the bot was removed; a `join` makes it `pending` again, because a new group needs a new decision |
+
+The `join` and `leave` events carry no customer text and are kept for every chat that is not blocked.
+Allowing a chat does not recover earlier events: they were dropped unread.
+This package never creates anything for a chat; what a chat becomes is the consumer's business.
+
+## The inbox worker
+
+Stored events wait in `line_inbox`.
+The worker runs inside the host as the `line-inbox` service and hands events to the processor attached through the service:
+
+```ts
+const detach = context.services.get(LINE).attachProcessor(async (event) => {
+	// event.type, event.sourceKey, event.messageId, event.timestamp, event.payload
+	// return nothing when done, or { retryInMs } to look at it again later
+});
+```
+
+Until a processor is attached, events stay in the inbox with their payload.
+
+- Delivery is at least once. A handler that outlives its lease (its process died, or it could not renew) may run again for the same event, so a processor must be idempotent.
+- A claim is `FOR UPDATE SKIP LOCKED` under a per-chat lock: while leases are kept no chat has two events in hand at once, across workers and processes, and events of a chat go out in order of LINE's event time among those that are due. An event that is backing off does not hold the ones behind it.
+- A claimed event has a 2-minute lease that the worker renews every 40 seconds while the handler runs, so a slow handler is not taken for a crashed one. Every write that ends a handling is fenced by its claim: a handler that lost the event cannot change what the next claim wrote. The worker puts back events whose lease ran out when it starts and every minute after, other than ones it is handling itself, and that counts as a handing out, so an event that keeps crashing its worker ends up dead.
+- A handler runs for at most `maxHandleMs` (10 minutes). The processor receives an `AbortSignal` as its second argument that is aborted then; the lease is no longer renewed and the event fails with `handler_timeout` like any thrown error, so a handler that never settles cannot hold its chat or the shutdown. What it settles with later is ignored. The signal is also aborted when the worker stops (`signal.reason` has the code `worker_stopped`; a handler that then throws the reason or an abort error puts the event back without counting as a failure, while any other error it throws counts) and when the worker finds the event is no longer its own (`lease_lost`). Only a handler that honours the signal gives up: one that ignores it may still be running while the same chat's next event, or the event's own retry, is handed out, so a processor must be safe against its own overlap. To give up, throw (for example `throw signal.reason`) or return `{ retryInMs }`: a handler that returns `undefined` has handled the event, and it is marked done. The processor is looked up again just before it is called, so one detached or replaced while the event waited gets nothing. `maxHandleMs`, `leaseMs` and `pollMs` are at most 2147483647 (about 24 days), the longest delay a timer holds.
+- The worker looks at the inbox on a kick, on every poll and whenever a handler ends, also while handlers are running, so a slow handler holds one of the `concurrency` slots and nothing else; expired leases are put back on the same schedule.
+- A thrown error retries with exponential backoff and jitter (5 seconds doubling to 1 hour); after 12 handings out the event is `dead`. Only the error's lower-case `code` word is stored, never its message, because messages may quote what a customer wrote.
+- An `unsend` or `messageEdited` event runs strictly after the message it acts on and after the earlier events on that message: it waits, however long, while any of them is still pending, being handled or backing off, and goes to the processor once they are done or dead. The wait does not count against `maxRequeues`. It waits until the soonest of them is due again, and at least `dependencyRetryMs` (5 seconds). A message that has not reached the inbox at all is waited for up to 10 minutes.
+- Only events of `allowed` chats, and the `join`, `leave` and `unsend` of a chat that is not blocked, are handed out. When a chat is blocked, what it still has waiting is dropped with its payload, and an event that was in hand at that moment is dropped instead of retried. The same goes for a chat the bot left: when its `leave` is applied, what else it has waiting is dropped with its payload, and an event of a `left` or undecided chat is dropped at the claim, so nothing surfaces after a rejoin. An `unsend` is the exception, because it carries no content and only takes a mirrored message down: it is kept and delivered even after the bot left, while `block` drops it like anything else.
+- A finished event keeps its row and loses its payload. U+0000 and lone surrogates in an event are replaced with U+FFFD when it is stored, so one odd event never costs the others of its request.
+
+Options tune the worker: `inbox: { leaseMs, maxHandleMs, maxAttempts, backoffBaseMs, backoffCapMs, concurrency, pollMs, ... }`.
+
+## Safety
+
+Do not admit a `line` surface through the core's `everyone` access: anyone who can add the bot to a group would reach the assistant.
+This slice contributes no surface and starts no turn.
+
+## Tests
+
+PostgreSQL-backed tests run when `ROUNDTABLE_TEST_DATABASE_URL` is set and are skipped otherwise.
+No test reaches LINE: the plugin takes a `fetch` option, and the tests inject a fake.

package/package.json

@@ -1,6 +1,47 @@
 {
-  "name": "pi-roundtable-line",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "pi-roundtable-line",
+	"version": "0.9.13",
+	"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",
+	"engines": {
+		"bun": ">=1.3.0"
+	},
+	"exports": {
+		".": "./src/index.ts"
+	},
+	"files": [
+		"src",
+		"!src/**/*.test.ts",
+		"!src/testing",
+		"LICENSE",
+		"README.md",
+		"CHANGELOG.md"
+	],
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/wayne930242/pi-roundtable.git",
+		"directory": "packages/line"
+	},
+	"publishConfig": {
+		"access": "public",
+		"provenance": true
+	},
+	"scripts": {
+		"typecheck": "tsc --noEmit",
+		"lint": "biome check .",
+		"test": "bun test"
+	},
+	"peerDependencies": {
+		"pi-roundtable": ">=0.9.0 <0.10.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.9.13",
+		"typebox": "1.3.34",
+		"typescript": "7.0.2"
+	}
+}

package/src/api.ts

@@ -0,0 +1,101 @@
+import { LineApiError, LineError } from "./errors.ts";
+import { LINE_API, type TokenSource } from "./token.ts";
+
+export interface LineApiOptions {
+	tokens: TokenSource;
+	fetch?: typeof fetch;
+	baseUrl?: string;
+	/** Per-request timeout in milliseconds; default 15 seconds. */
+	timeoutMs?: number;
+}
+
+export interface RequestOptions {
+	method?: string;
+	headers?: Record<string, string>;
+	body?: string | Uint8Array;
+}
+
+/**
+ * LINE's API with the channel access token on every call. A `401` makes the token source forget
+ * the token and the call is repeated once with a new one; a second `401` is an error. The error
+ * says the status and LINE's request id, never the response body.
+ */
+export class LineApi {
+	readonly #tokens: TokenSource;
+	readonly #fetch: typeof fetch;
+	readonly #base: string;
+	readonly #timeoutMs: number;
+
+	constructor(options: LineApiOptions) {
+		this.#tokens = options.tokens;
+		this.#fetch = options.fetch ?? fetch;
+		this.#base = options.baseUrl ?? LINE_API;
+		this.#timeoutMs = options.timeoutMs ?? 15_000;
+	}
+
+	/** The response of a successful call; its body is the caller's to read. */
+	async request(path: string, options: RequestOptions = {}): Promise<Response> {
+		for (let attempt = 0; ; attempt++) {
+			const token = await this.#tokens.token();
+			let response: Response;
+			try {
+				response = await this.#fetch(`${this.#base}${path}`, {
+					method: options.method ?? "GET",
+					headers: { ...options.headers, authorization: `Bearer ${token}` },
+					...(options.body === undefined ? {} : { body: options.body }),
+					signal: AbortSignal.timeout(this.#timeoutMs),
+				});
+			} catch (error) {
+				throw new LineError(
+					"api_unreachable",
+					`line: ${path} did not answer (${this.#tokens.redact(
+						error instanceof Error ? error.message : String(error),
+					)})`,
+				);
+			}
+			if (
+				response.status === 401 &&
+				attempt === 0 &&
+				this.#tokens.reject(token)
+			) {
+				await response.body?.cancel().catch(() => undefined);
+				continue;
+			}
+			if (!response.ok) {
+				await response.body?.cancel().catch(() => undefined);
+				throw new LineApiError(
+					response.status,
+					`http_${response.status}`,
+					`line: ${options.method ?? "GET"} ${path} answered ${response.status}`,
+					response.headers.get("x-line-request-id") ?? undefined,
+				);
+			}
+			return response;
+		}
+	}
+
+	async json(path: string, options?: RequestOptions): Promise<unknown> {
+		return (await this.request(path, options)).json();
+	}
+
+	/** The bot's user id, which a webhook's `destination` must equal. */
+	async botUserId(): Promise<string> {
+		const info = (await this.json("/v2/bot/info")) as { userId?: unknown };
+		if (typeof info?.userId !== "string" || info.userId === "")
+			throw new LineError("bot_info_malformed", "line: bot info has no userId");
+		return info.userId;
+	}
+
+	/** The name LINE shows for a group. */
+	async groupName(groupId: string): Promise<string> {
+		const summary = (await this.json(
+			`/v2/bot/group/${encodeURIComponent(groupId)}/summary`,
+		)) as { groupName?: unknown };
+		if (typeof summary?.groupName !== "string")
+			throw new LineError(
+				"group_summary_malformed",
+				"line: group summary has no name",
+			);
+		return summary.groupName;
+	}
+}

package/src/bot.ts

@@ -0,0 +1,64 @@
+import type { Logger } from "pi-roundtable";
+import type { LineApi } from "./api.ts";
+import { errorCode } from "./errors.ts";
+
+/** A failed lookup is not repeated sooner than this, however many webhooks ask. */
+const RETRY_MS = 30_000;
+
+export interface BotIdentityOptions {
+	api: LineApi;
+	logger: Logger;
+	now: () => Date;
+}
+
+/**
+ * The bot's user id, which every webhook's `destination` must equal. It is read from LINE when the
+ * host starts and again, at most every 30 seconds, while it is still unknown and a webhook asks.
+ * Until it is known a webhook is vouched for by its signature alone: the channel secret is the
+ * only thing that can produce one.
+ */
+export class BotIdentity {
+	readonly #api: LineApi;
+	readonly #logger: Logger;
+	readonly #now: () => Date;
+	#id: string | undefined;
+	#inflight: Promise<void> | undefined;
+	#lastTry = Number.NEGATIVE_INFINITY;
+
+	constructor(options: BotIdentityOptions) {
+		this.#api = options.api;
+		this.#logger = options.logger;
+		this.#now = options.now;
+	}
+
+	/** The id, or undefined while it is unknown; asking also starts a lookup when one is due. */
+	current(): string | undefined {
+		if (
+			this.#id === undefined &&
+			this.#now().getTime() - this.#lastTry >= RETRY_MS
+		)
+			void this.refresh();
+		return this.#id;
+	}
+
+	/** Asks LINE; a failure is logged by its code and leaves the id unknown. Never rejects. */
+	refresh(): Promise<void> {
+		this.#inflight ??= this.#ask().finally(() => {
+			this.#inflight = undefined;
+		});
+		return this.#inflight;
+	}
+
+	async #ask(): Promise<void> {
+		this.#lastTry = this.#now().getTime();
+		try {
+			this.#id = await this.#api.botUserId();
+			this.#logger.info("the LINE bot identity is known");
+		} catch (error) {
+			this.#logger.warn(
+				{ code: errorCode(error) },
+				"the LINE bot identity could not be read; webhooks are checked by signature alone until it can",
+			);
+		}
+	}
+}

package/src/errors.ts

@@ -0,0 +1,43 @@
+/** A failure of this package, named by a short code that is safe to store and log. */
+export class LineError extends Error {
+	override name = "LineError";
+	readonly code: string;
+
+	constructor(code: string, message: string) {
+		super(message);
+		this.code = code;
+	}
+}
+
+/** LINE answered a request with a status that is not a success. The message never holds a response body. */
+export class LineApiError extends LineError {
+	override name = "LineApiError";
+	readonly status: number;
+	/** `x-line-request-id` of the failed call, for LINE's support. */
+	readonly requestId: string | undefined;
+
+	constructor(
+		status: number,
+		code: string,
+		message: string,
+		requestId?: string,
+	) {
+		super(code, message);
+		this.status = status;
+		this.requestId = requestId;
+	}
+}
+
+const CODE = /^[a-z][a-z0-9_]{0,63}$/;
+
+/**
+ * The code to store for a failure: its own when it is a `LineError` or carries a lower-case `code`
+ * word, else `handler_error`. The message is never stored, because it may quote what a customer wrote.
+ */
+export function errorCode(error: unknown): string {
+	if (typeof error === "object" && error !== null && "code" in error) {
+		const code = (error as { code: unknown }).code;
+		if (typeof code === "string" && CODE.test(code)) return code;
+	}
+	return "handler_error";
+}

package/src/events.ts

@@ -0,0 +1,104 @@
+import { LineError } from "./errors.ts";
+
+export type SourceKind = "group" | "room" | "user";
+
+const ID = /^[A-Za-z0-9_-]{1,64}$/;
+
+/** `line:<group|room|user>:<id>`, the channel key's tail every other part of the package names a chat by. */
+export function sourceKeyOf(kind: SourceKind, id: string): string {
+	return `line:${kind}:${id}`;
+}
+
+/** The kind and id inside a source key, or undefined when the text is not one. */
+export function parseSourceKey(
+	key: string,
+): { kind: SourceKind; id: string } | undefined {
+	const match = /^line:(group|room|user):([A-Za-z0-9_-]{1,64})$/.exec(key);
+	return match
+		? { kind: match[1] as SourceKind, id: match[2] as string }
+		: undefined;
+}
+
+/** One webhook event, reduced to what the inbox keeps in columns; the event itself is `raw`. */
+export interface ParsedEvent {
+	/** LINE's `webhookEventId`, or a digest of the event when it has none. */
+	id: string;
+	type: string;
+	timestamp: number;
+	/** Null when the event names no chat the package knows. */
+	sourceKey: string | null;
+	messageId: string | null;
+	/** False for events of a bot in standby mode, which are never mirrored. */
+	active: boolean;
+	raw: Record<string, unknown>;
+}
+
+export interface ParsedWebhook {
+	destination: string | null;
+	events: ParsedEvent[];
+}
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+	typeof value === "object" && value !== null && !Array.isArray(value);
+
+const text = (value: unknown): string | null =>
+	typeof value === "string" && value !== "" ? value : null;
+
+/** The key of the chat an event's `source` names. */
+function sourceOf(source: unknown): string | null {
+	if (!isRecord(source)) return null;
+	for (const [kind, field] of [
+		["group", "groupId"],
+		["room", "roomId"],
+		["user", "userId"],
+	] as const) {
+		if (source.type !== kind) continue;
+		const id = text(source[field]);
+		return id && ID.test(id) ? sourceKeyOf(kind, id) : null;
+	}
+	return null;
+}
+
+async function digest(value: string): Promise<string> {
+	const bytes = new TextEncoder().encode(value);
+	const hash = await crypto.subtle.digest("SHA-256", bytes);
+	return Buffer.from(hash).toString("hex");
+}
+
+/**
+ * Reads a webhook body. Throws `LineError("bad_webhook")` when it is not JSON or has no `events`
+ * array; an event of an unexpected shape is kept (as an event with no chat) rather than refused,
+ * so one odd event never costs the others of its request.
+ */
+export async function parseWebhook(body: Uint8Array): Promise<ParsedWebhook> {
+	let value: unknown;
+	try {
+		value = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(body));
+	} catch {
+		throw new LineError("bad_webhook", "line: the webhook body is not JSON");
+	}
+	if (!isRecord(value) || !Array.isArray(value.events))
+		throw new LineError(
+			"bad_webhook",
+			"line: the webhook body has no events array",
+		);
+	const events: ParsedEvent[] = [];
+	for (const raw of value.events) {
+		if (!isRecord(raw)) continue;
+		const message = isRecord(raw.message) ? raw.message : undefined;
+		const unsend = isRecord(raw.unsend) ? raw.unsend : undefined;
+		const timestamp = Number(raw.timestamp);
+		events.push({
+			id:
+				text(raw.webhookEventId) ??
+				`derived:${await digest(JSON.stringify(raw))}`,
+			type: text(raw.type) ?? "unknown",
+			timestamp: Number.isSafeInteger(timestamp) ? timestamp : 0,
+			sourceKey: sourceOf(raw.source),
+			messageId: text(message?.id) ?? text(unsend?.messageId),
+			active: raw.mode === undefined || raw.mode === "active",
+			raw,
+		});
+	}
+	return { destination: text(value.destination), events };
+}