pi-roundtable-line 0.9.13 → 0.11.0

package/CHANGELOG.md

@@ -5,6 +5,31 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.11.0] - 2026-10-13
+
+- Release in lockstep with pi-roundtable 0.11.0; no package-specific behavior changes. The core peer range moves to `>=0.11.0 <0.12.0`.
+
+## [0.10.0] - 2026-10-13
+
+### Added
+
+- The consumer. `LINE.subscribe(handler)` takes the one subscriber (a second is refused; the returned function detaches it) and the package's own inbox processor hands it typed events: `message` (text, image, video, audio, file, sticker, location, and `unsupported` for a type it does not know), `edited`, `unsent`, `joined` (`notice` says whether the join notice went out), `left`, `memberJoined`, `memberLeft`, and `outboxResult`. A `message` is answered with `{ refs }` (anything else fails with `bad_refs`), opaque references stored one to many in `line_message_refs` and given back on `edited` and `unsent`; a redelivery of a recorded message is not handed out again and stores nothing twice. The subscriber's third argument has `keep(ref)`, to store the reference of each post as it lands under the same lock and tombstone check as the final store (a ref kept after an unsend is handed back as `unsent` at once and `keep` resolves `{ unsent: true }`); a handler that throws after keeping some refs leaves them stored for the retry and for a later `unsend`.
+- Tombstones. An `unsend` writes a tombstone, nulls every inbox payload of the message and deletes its metadata in one transaction under a per-message lock, then hands the refs to the subscriber and forgets them once it returns. A `message` checks the tombstone before it calls the subscriber and again wherever its refs are stored (`keep` or the final store); an unsend that lands meanwhile has the new refs handed straight back. Only a crash between a post and its `keep` can leave a post the package does not know of. Edits arrive out of order and the latest one wins.
+- `LINE.content(messageId, { kind, signal })`: message content into memory only, capped by `media.maxBytes` (default 10 MiB) and answered as `{ bytes, contentType }`, `{ tooLarge }` or `{ expired, reason }`; a video or audio waits for `/content/transcoding` for at most `media.transcodingMaxMs` in all, requests included (each request is given what is left of the wait). It uses the content host, reissues the token once on a `401`, stops on the signal, and never fetches a message that was unsent.
+- Reply and quote tokens are kept per message in `line_messages` for a later reply mode, never logged or handed to the subscriber, and deleted with the message.
+- The `line-retention` service and the `retention` option: inbox events that are done, skipped, dead or never handled, and message metadata, refs and tombstones, are removed after 7 days by default; it logs counts only. A subscriber that stays detached longer than the window loses the unsends and refs that waited for it. New migration `messages` (the released `inbox` migration is untouched).
+
+- The outbox. `LINE.outbox.enqueue(sourceKey, messages, { sender?, origin? })` queues message objects for a chat on the allowlist. `sender` (`{ name, iconUrl }`) is validated before anything is queued: a name of 1 to 20 characters without a forbidden word (`sender.forbiddenWords`, default `LINE` and `LY`, whole words in any case and width, where a change of script between Latin and other letters ends a word; LINE still has the last word), an `https` icon URL of at most 2000 characters. Objects of one chat and sender queued within `outbox.coalesceMs` (2 seconds) share a push of at most five, in order; the pushes of a chat go out in order. Every push has a UUID retry key stored when its row is created, reused on every attempt for 24 hours and never replaced (a push still unsent then is `dead`, counted from its first request even if a stop cut that request short). `2xx` and `409` are `sent`, `429`, `5xx` and no answer back off and retry (up to `outbox.maxAttempts`), any other `4xx` is `dead` with a code (`sender_name_refused`, `sender_icon_refused`, or `http_<status>`). A quota gate reads LINE's quota and consumption (cached 60 seconds), counts the recipients (1, or the member count of a group or room) and this process's reservations, and refuses a push that would pass the lower of the quota and `quota.monthlyCap`. LINE calls its consumption figure approximate, so a sent push (or one whose outcome is unknown) stays reserved until consumption has grown by its recipients or `quota.holdMs` (10 minutes) has passed; keep `monthlyCap` below the quota with headroom. The subscriber hears an `outboxResult` (`sent`, `dead`, `refused`) per `origin`, at least once. The `line-outbox` service, migration `outbox` (tables `line_outbox` and `line_notices`) and `retention.outboxMs` (7 days) are new; message objects are nulled when a push finishes.
+- The join notice. `joinNotice: { text, sha256 }` answers a `join` with one Reply, on the event's reply token, only when the SHA-256 of the text's UTF-8 bytes equals `sha256`, in any chat the bot joins, allowlisted or not; never as a push. A malformed digest throws when the plugin is made; a digest that does not match sends nothing. `joined.notice` is now `"sent"`, `"failed"` (LINE refused the Reply, its token lapsed, or the digest did not match) or `"unconfirmed"` (no notice configured, the Reply got no answer, or the first try was cut short), and the outcome is recorded before the Reply so a redelivered join never replies twice. `digestOf(text)` is exported.
+- `route: true` hands the text of messages of allowed chats to the host's router as messages of the `line` surface, inside the transaction that records the message and never for one unsent meanwhile (at least once: only a failed commit right after the hand-over can repeat it) (off by default; the README warns never to admit `line` through `everyone`).
+- The `line` chat surface (channel = source key), which queues what the host writes as text pushes and passes `describeSurfaceContract`, and `senderIconRoute: { path, png }`, which serves fixed PNG bytes with a one-year cache header so a sender can name a stable `iconUrl`.
+- The retention sweep hands strays back first: refs stored for a message that has a tombstone, more than `retention.strayMs` (default 15 minutes) ago, whose tombstone is that old too, go to the subscriber as `unsent` until they are gone. A handler that outlived its lease could keep a ref after the unsend had run and its take-back was refused, and nothing else would have handed the ref over.
+
+### Changed
+
+- A ref a handler kept and also returns at the end is no longer handed back a second time when the message was unsent meanwhile.
+- **Breaking (published in 0.9.13):** `LINE.attachProcessor` is removed in favour of `LINE.subscribe`: a raw processor could read events without the tombstone rules. There is no deprecated shim. Code that attached a processor must subscribe instead; the next lockstep release is 0.10.0. `InboxProcessor` and its types stay exported for the inbox options.
+
 ## [0.9.13] - 2026-10-13
 
 ### Added

package/README.md

@@ -1,18 +1,17 @@
 # pi-roundtable-line
 
 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.
+It receives the events of a LINE Official Account's group chats on the host's HTTP listener, stores each one before it answers, hands the stored events of the chats you allow to one consumer, in order and at least once, and sends pushes back to those chats under a sender name, a retry key and a monthly budget.
 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.
+It covers intake (the credentials and token source, the webhook, the allowlist of chats, and the inbox worker), the consumer side (typed events for one subscriber, tombstones for unsent messages, message content, and retention) and the sending side: an outbox with per-chat ordering and coalescing, sender names, persisted retry keys and a quota gate, the join notice, an optional router delivery, a `line` chat surface and a route that serves a sender icon.
 
 ## Requirements
 
-- Bun 1.3 or later, and pi-roundtable `>=0.9.0 <0.10.0` as a peer dependency.
+- Bun 1.3 or later, and pi-roundtable `>=0.11.0 <0.12.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.
@@ -105,28 +104,20 @@ await sources.summary("line:group:C..."); // adds the group's name, asked of LIN
 | `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.
+The `join` and `leave` events carry no customer text and are kept for every chat that is not blocked. An `unsend` is stored only while its chat is allowed, but one that is already stored is still delivered after the bot has left the chat (see [The inbox worker](#the-inbox-worker)).
 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:
+The worker runs inside the host as the `line-inbox` service and hands each event to the package's own processor, which turns it into a typed event for the one subscriber (see [The consumer](#the-consumer)).
+Until a subscriber is attached, events stay in the inbox with their payload, are not counted as handed out, and are removed by retention if they wait past its window.
 
-```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.
+- 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 subscriber 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.
+- A handler runs for at most `maxHandleMs` (10 minutes). The processor (and so the subscriber) 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 subscriber must be safe against its own overlap. To give up, throw (for example `throw signal.reason`): a handler that returns has handled the event, and it is marked done. A subscriber's result is never read as a retry request; a `message` answer that is neither nothing nor `{ refs }` (a `{ retryInMs }`, say) fails with `bad_refs`. The subscriber 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.
@@ -135,10 +126,203 @@ Until a processor is attached, events stay in the inbox with their payload.
 
 Options tune the worker: `inbox: { leaseMs, maxHandleMs, maxAttempts, backoffBaseMs, backoffCapMs, concurrency, pollMs, ... }`.
 
+## The consumer
+
+```ts
+const detach = context.services.get(LINE).subscribe(async (event, signal, line) => {
+	switch (event.type) {
+		case "message": {
+			// mirror event.body; keep the opaque reference of each post as it lands
+			await line.keep("discord-message-1");
+			await line.keep("discord-message-2");
+			return { refs: ["discord-message-1", "discord-message-2"] };
+		}
+		case "edited": // event.text, event.refs (the original's)
+		case "unsent": // event.refs: take these down; may be heard more than once
+		case "joined": // event.notice: "sent" | "unconfirmed" | "failed"
+		case "left":
+		case "memberJoined": // event.userIds
+		case "memberLeft":
+		case "outboxResult": // how a push you queued ended
+	}
+});
+```
+
+There is exactly one subscriber: a second `subscribe` throws, and the function it returns detaches the first.
+With none attached the inbox worker claims nothing (events wait, uncounted).
+The processor that serves it is the package's own; there is no way to read raw inbox events through the service, so the rules below cannot be bypassed.
+
+| Event | What it carries |
+|---|---|
+| `message` | `messageId`, `userId`, `quotedMessageId`, and a `body`: `text`, `image`, `video`, `audio` (with `durationMs`), `file` (`fileName`, `fileSize`), `sticker` (`packageId`, `stickerId`, `keywords`), `location` (`title`, `address`, `latitude`, `longitude`), or `unsupported` for a type this version does not know, so nothing disappears silently |
+| `edited` | the new `text` and the `refs` of the original, in the order the subscriber gave them; groups only, and only text can be edited |
+| `unsent` | the `refs` to take down |
+| `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)) |
+
+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.
+
+A `message` is answered with `{ refs }`: opaque strings of at most 512 characters (at most 100 per message, kept and answered together) that the package stores one to many in `line_message_refs`, in order, and gives back on `edited` and `unsent`.
+Answering nothing is allowed; the message is then still recorded as mirrored. Any other answer (an object without `refs`, a `{ retryInMs }`) fails the event with `bad_refs`; to give up, throw.
+A redelivery of a message that is already recorded is not handed to the subscriber again.
+
+One message may become several posts (a long text is cut into chunks, media and text are posted apart), and the last one can fail.
+So the third argument of the subscriber, `line`, has `keep(ref)`: call it as each post lands.
+It stores the reference at once, under the same per-message lock and tombstone check as the answer at the end, and resolves `{ unsent }`.
+Refs answered at the end merge with the kept ones (one already stored keeps its place), so keeping and answering the same ref is fine; a ref that was kept is never handed back a second time because it is answered again.
+A handler that throws after keeping some refs leaves them stored: the retry mirrors the message again, and an `unsent` hands over the posts of every attempt, so none is left behind.
+If the sender had already taken the message back, `keep` stores the ref, hands it to the subscriber as `unsent` at once (the same take-back the final store does) and resolves `{ unsent: true }`: stop posting.
+Keep each post as it lands, and throw to give up.
+Only a crash between a post and its `keep` can leave a post the package does not know of; the message is then mirrored again, and the subscriber should deduplicate on `eventId` if that matters.
+
+### Unsent messages
+
+An `unsend` event writes a tombstone for the message, nulls the stored payload of every event that mentions the message (its own, edits of it), and deletes the message's metadata, tokens included, in one transaction under a per-message lock.
+Only then are the stored refs handed to the subscriber as `unsent`; they are forgotten once it has returned, so a subscriber that failed halfway is handed the same refs again.
+
+- A `message` checks the tombstone before it calls the subscriber: an unsent message is never mirrored. Refs left over from a mirror that was cut short are still handed back.
+- The refs a subscriber keeps or returns are stored under the same lock and the tombstone is checked again there. If the sender took the message back while the subscriber was working, the new refs are stored, handed straight back as `unsent` (at the `keep` for a kept ref, at the end for the rest), and the message record is not written.
+- An `unsend` for a message the package never saw (it arrived first, or is older than retention) still writes the tombstone and is heard with `refs: []`.
+- An edit of a message that was unsent, was never mirrored, or is older than the last edit applied is skipped; edits arrive out of order, and the one with the latest time wins.
+
+## Message content
+
+```ts
+const result = await context.services.get(LINE).content(event.messageId, {
+	kind: event.body.kind === "text" ? undefined : event.body.kind,
+	signal,
+});
+if ("bytes" in result) upload(result.bytes, result.contentType);
+else if ("tooLarge" in result) placeholder("too large");
+else placeholder(result.reason); // "expired" | "unsent" | "transcoding_failed"
+```
+
+The content is read into memory, never to disk, never logged, and never exposed at a URL.
+`media: { maxBytes }` (default 10 MiB) caps it: a `content-length` over the cap is refused before reading, and a body without one is counted as it streams and dropped past the cap, giving `{ tooLarge: true }`.
+LINE keeps content for a limited time; a missing one is `{ expired: true }`.
+Pass the event's `kind` for a video or audio: the call then polls `/v2/bot/message/{id}/content/transcoding` (every `media.transcodingPollMs`, 2 seconds, until `media.transcodingMaxMs`, 60 seconds, have passed since the call began: a real deadline, so each request gets only what is left of it) until it has `succeeded`; `failed` is `{ expired: true, reason: "transcoding_failed" }` and running out of time is a `transcoding_timeout` error, which the inbox retries.
+The call uses the same token source as every other call (a `401` reissues the token once) and the content host `api-data.line.me`.
+Pass the handler's `signal` and an aborted event stops the download.
+A message that was unsent is never fetched.
+
+## Reply and quote tokens
+
+The reply token and the quote token of a mirrored message are kept in `line_messages` (`reply_token`, `reply_token_at`, `quote_token`) for a later reply mode.
+They are never logged and never passed to the subscriber, and they are deleted with the message when it is unsent or when retention runs.
+
+## Retention
+
+The `line-retention` service sweeps once at start and every hour (`retention.intervalMs`):
+
+| What | Removed after (option) |
+|---|---|
+| inbox events that are `done`, `skipped` or `dead` | 7 days (`retention.inboxMs`) |
+| inbox events still `pending`, which no subscriber handled | 7 days (`retention.inboxMs`), payload and all |
+| message metadata and tokens, refs, tombstones | 7 days (`retention.messagesMs`) |
+| pushes that finished, pushes that never got sent, join notice records | 7 days (`retention.outboxMs`) |
+
+Before it trims, every sweep hands back strays: refs still stored for a message that has a tombstone, where both the ref and the tombstone are more than `retention.strayMs` (15 minutes) old, go to the subscriber as `unsent`, and are forgotten once it returns.
+A stray happens when a handler that outlived its lease keeps a ref after its message was unsent and the take-back is refused, so nobody else would hand the ref over.
+A take-back that fails is logged by its code and retried at the next sweep, until the ref is gone; with no subscriber attached the refs wait.
+
+A subscriber that stays detached longer than the window loses what was waiting for it: an `unsend` still pending is removed with the rest, and the refs of the message it names are removed too, so that mirror can no longer be taken back. Keep a subscriber attached, or raise `retention.inboxMs` and `retention.messagesMs` beyond the longest outage.
+
+It logs counts only, never ids, text or tokens, and counts as `busy` while a sweep runs so the shutdown waits for it.
+A table that cannot be trimmed is logged by its code and the others go on.
+
+## Sending
+
+```ts
+const { outbox } = context.services.get(LINE);
+await outbox.enqueue(
+	"line:group:C...",
+	[{ type: "text", text: "On it." }],
+	{
+		sender: { name: "Ada | Support", iconUrl: "https://example.com/line/staff-icon.png" },
+		origin: "draft-42", // your own reference, given back in the outboxResult
+	},
+);
+```
+
+`enqueue` queues LINE message objects for a chat on the allowlist; it throws before queuing anything when the sender is one LINE would refuse (`bad_sender`), an object cannot be sent (`bad_messages`: not an object with a `type`, an empty or over-long text, a `sender` of its own, over 50,000 bytes, more than 100 in one call), the key is not a source key (`bad_source_key`), or the chat is not allowed (`source_not_allowed`).
+Message objects hold what you send, so they live in `line_outbox.messages` until the push finishes and are then set to null; the row itself goes after the retention window.
+
+- **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.
+- **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.
+
+### Senders
+
+A sender is `{ name?, iconUrl? }`, shown by LINE as "<name> from '<channel>'".
+It is checked when you enqueue: the name is 1 to 20 characters (counted as characters, so an emoji is one), has no leading or trailing space or control character, and contains none of the forbidden words (`sender.forbiddenWords`, default `["LINE", "LY"]`, compared case-insensitively, with full-width letters read as plain ones, and as whole words, where a word is a run of Latin letters and digits or a run of letters of another script, so "Online" and "Sally" pass while "LINE" next to kana or hanzi does not); the icon is an `https` URL of at most 2000 characters without credentials.
+LINE has the last word: a name it refuses anyway comes back as a dead push with `sender_name_refused`.
+
+### Quota
+
+Before a push is sent the gate reads LINE's monthly limit (`/v2/bot/message/quota`) and consumption (`/v2/bot/message/quota/consumption`), cached for 60 seconds, and counts the push's recipients: 1 for a user chat, the member count (`/members/count`, cached for 60 seconds) for a group or room.
+The push goes only if consumption, plus what this process has already reserved for pushes it sent or is sending, plus its own recipients, stays within the lower of the plan's quota and `quota.monthlyCap`; otherwise it is `refused` with `quota_exhausted`.
+A reservation for a push that went out stays counted until the consumption LINE reports has grown by at least the push's recipients since it was sent, or until `quota.holdMs` (10 minutes by default) has passed. A push whose outcome is unknown (a timeout, no answer, or a `5xx`) is held as if it had been sent; one LINE refused with a `4xx` or `429` is dropped at once. When the quota cannot be read the push backs off and retries; it is not refused and not sent blind.
+This rests on an assumption: LINE calls its consumption figure approximate, and the gate treats it as approximate. It may count late, so keep `monthlyCap` below the plan's quota with some headroom, and keep it lower still when other processes, or the LINE Official Account Manager, send too. Only this process's reservations are known, and they are lost on a restart.
+
+```ts
+line({ credentials, quota: { monthlyCap: 400 } })
+```
+
+## The join notice
+
+```ts
+line({
+	credentials,
+	joinNotice: { text: NOTICE_TEXT, sha256: NOTICE_SHA256 },
+})
+```
+
+When the bot joins a chat the package answers the `join` event with **one Reply**, using the event's reply token, if and only if the SHA-256 of the text's UTF-8 bytes (lower-case hex) equals `joinNotice.sha256`.
+`digestOf(text)` computes it. A digest that is not 64 lower-case hex digits, or a text over 5000 characters, throws when the plugin is made; a well-formed digest that does not match the text does not stop the host, but nothing is ever sent and every join is `failed` (and a warning is logged once at start).
+Without `joinNotice` nothing is ever sent.
+
+- It applies to any chat the bot joins that is not blocked, allowlisted or not.
+- It is never a push. When LINE refuses the Reply, or its token has lapsed (reply tokens live a short time), the notice is `failed` and nothing is sent in its place. When the Reply gets no answer (a timeout or an unreachable LINE) nobody knows whether LINE took it, so the notice is `unconfirmed` and is not tried again.
+- The subscriber's `joined` event says what happened: `"sent"`, `"failed"`, or `"unconfirmed"` (no notice configured, or the Reply got no answer, or the first try was cut short, and nobody knows whether LINE got the Reply). The outcome is recorded before the Reply is made, so a join that is handed out again never replies twice.
+- The inbox worker only runs while a subscriber is attached (or `route` is on), so attach one before the bot can be added to chats; a join that waits past its reply token's life is `failed`.
+
+## Router delivery
+
+`route: true` hands the text of messages of allowed chats to the host's router, as messages of the `line` surface (channel `line:group:<id>`, author the LINE user id, `mentionsBot` when the bot is @mentioned, with the bot's mention cut out of the text), after the subscriber has mirrored them, and never for a message that was unsent meanwhile.
+The hand-over happens in the same transaction that records the message, so a router that throws makes the event retry and a failed store hands over nothing. Delivery is at least once: only a failure of the commit itself, right after the router took the text, can hand the same text over a second time.
+Images, stickers and other kinds are not routed, nor are messages LINE did not name a sender for.
+It is off by default.
+**Never admit `line` through the core's `everyone` access**: anyone who can add the bot to a group, or write in a chat you allow, would reach the assistant. Admit only identities you have linked to a person.
+With `route` on the inbox is served even when no subscriber is attached.
+
+## The `line` chat surface
+
+The plugin contributes a chat surface under the prefix `line`; its channel is a source key (`line:group:<id>`, `line:room:<id>`, `line:user:<id>`).
+What the host writes there (`sendReply`) is queued as text objects, one per chunk (a chunk over 5000 characters is cut, never inside a surrogate pair), and goes out as a push with no sender; it reaches only a chat on the allowlist.
+The surface shows no typing indicator, stop control, progress, files or approval prompts: LINE has none the bot can show.
+It passes `describeSurfaceContract` (`pi-roundtable/testing`).
+
+## The sender icon route
+
+```ts
+line({ credentials, senderIconRoute: { path: "/line/staff-icon.png", png: readFileSync("staff-icon.png") } })
+```
+
+Serves fixed PNG bytes at `path` to `GET` and `HEAD` with `cache-control: public, max-age=31536000, immutable`, on the same listener as the webhook, so the host can give LINE a stable `iconUrl` (`https://<your host>/line/staff-icon.png`) without another service.
+The bytes are copied when the plugin is made and checked: they must be a PNG of at most 1 MiB, and `path` must differ from `webhookPath`.
+
 ## 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.
+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 (see [Router delivery](#router-delivery)).
+A push goes only to a chat on the allowlist, under a sender that was checked before it was queued, inside the month's budget.
+The access token, the channel secret, reply and quote tokens, retry keys and message text appear in no log line and no error.
 
 ## Tests
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-roundtable-line",
-	"version": "0.9.13",
+	"version": "0.11.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.9.0 <0.10.0"
+		"pi-roundtable": ">=0.11.0 <0.12.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",
+		"pi-roundtable": "0.11.0",
 		"typebox": "1.3.34",
 		"typescript": "7.0.2"
 	}

package/src/api.ts

@@ -1,10 +1,49 @@
 import { LineApiError, LineError } from "./errors.ts";
+import type { SourceKind } from "./events.ts";
 import { LINE_API, type TokenSource } from "./token.ts";
 
+/** The host LINE serves message content from; every other call goes to {@link LINE_API}. */
+const LINE_DATA_API = "https://api-data.line.me";
+
+/** How a push ended, as far as the caller needs to act on it. */
+export type PushOutcome =
+	| { outcome: "sent"; duplicate: boolean; requestId: string | undefined }
+	| {
+			outcome: "failed";
+			status: number;
+			/** A short lower-case word: `http_<status>`, or the property LINE refused when it names one. */
+			code: string;
+			requestId: string | undefined;
+			retryAfterMs?: number;
+	  };
+
+/**
+ * The code to keep for a refused push. LINE names the property it refused in `details`; the ones a
+ * sender can cause are named so the channel can say what to fix, everything else is the status.
+ */
+function refusalCode(status: number, detail: unknown): string {
+	const details =
+		typeof detail === "object" && detail !== null && "details" in detail
+			? (detail as { details: unknown }).details
+			: undefined;
+	if (Array.isArray(details))
+		for (const item of details) {
+			const property =
+				typeof item === "object" && item !== null && "property" in item
+					? String((item as { property: unknown }).property)
+					: "";
+			if (/sender\.name/i.test(property)) return "sender_name_refused";
+			if (/sender\.iconUrl/i.test(property)) return "sender_icon_refused";
+		}
+	return `http_${status}`;
+}
+
 export interface LineApiOptions {
 	tokens: TokenSource;
 	fetch?: typeof fetch;
 	baseUrl?: string;
+	/** Where message content is fetched from; default `https://api-data.line.me`. */
+	dataBaseUrl?: string;
 	/** Per-request timeout in milliseconds; default 15 seconds. */
 	timeoutMs?: number;
 }
@@ -13,6 +52,12 @@ export interface RequestOptions {
 	method?: string;
 	headers?: Record<string, string>;
 	body?: string | Uint8Array;
+	/** `"data"` calls the content host; default `"api"`. */
+	host?: "api" | "data";
+	/** Aborts the call; an aborted call rejects with the signal's reason, not with a wrapped error. */
+	signal?: AbortSignal;
+	/** Replaces the client's per-request timeout, which also bounds reading the body. */
+	timeoutMs?: number;
 }
 
 /**
@@ -24,28 +69,60 @@ export class LineApi {
 	readonly #tokens: TokenSource;
 	readonly #fetch: typeof fetch;
 	readonly #base: string;
+	readonly #dataBase: string;
 	readonly #timeoutMs: number;
 
 	constructor(options: LineApiOptions) {
 		this.#tokens = options.tokens;
 		this.#fetch = options.fetch ?? fetch;
 		this.#base = options.baseUrl ?? LINE_API;
+		this.#dataBase = options.dataBaseUrl ?? LINE_DATA_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> {
+		const response = await this.exchange(path, options);
+		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;
+	}
+
+	/**
+	 * The response of a call whatever its status, for a caller that acts on the status itself. A
+	 * `401` is repeated once with a new token first. The body is the caller's to read or cancel.
+	 */
+	async exchange(
+		path: string,
+		options: RequestOptions = {},
+	): Promise<Response> {
 		for (let attempt = 0; ; attempt++) {
+			options.signal?.throwIfAborted();
 			const token = await this.#tokens.token();
 			let response: Response;
+			const timeout = AbortSignal.timeout(options.timeoutMs ?? this.#timeoutMs);
 			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),
-				});
+				response = await this.#fetch(
+					`${options.host === "data" ? this.#dataBase : this.#base}${path}`,
+					{
+						method: options.method ?? "GET",
+						headers: { ...options.headers, authorization: `Bearer ${token}` },
+						...(options.body === undefined ? {} : { body: options.body }),
+						signal: options.signal
+							? AbortSignal.any([options.signal, timeout])
+							: timeout,
+					},
+				);
 			} catch (error) {
+				// The caller gave up: it hears its own reason, which the inbox worker knows how to read.
+				if (options.signal?.aborted) throw options.signal.reason;
 				throw new LineError(
 					"api_unreachable",
 					`line: ${path} did not answer (${this.#tokens.redact(
@@ -61,15 +138,6 @@ export class LineApi {
 				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;
 		}
 	}
@@ -86,6 +154,102 @@ export class LineApi {
 		return info.userId;
 	}
 
+	/**
+	 * Pushes up to five message objects to a chat under a retry key. A `2xx` is `sent`; a `409` says
+	 * LINE already accepted a request with this key, which is `sent` too. Any other status comes back
+	 * as `failed` with the status, a code (LINE's own refusal of a sender is named) and, for a `429`
+	 * or `5xx`, how long LINE asked to wait. A call that gets no answer rejects with `api_unreachable`.
+	 * No part of LINE's answer is kept but those.
+	 */
+	async push(
+		to: string,
+		messages: readonly unknown[],
+		retryKey: string,
+		signal?: AbortSignal,
+	): Promise<PushOutcome> {
+		const response = await this.exchange("/v2/bot/message/push", {
+			method: "POST",
+			headers: {
+				"content-type": "application/json",
+				"x-line-retry-key": retryKey,
+			},
+			body: JSON.stringify({ to, messages }),
+			...(signal ? { signal } : {}),
+		});
+		const requestId = response.headers.get("x-line-request-id") ?? undefined;
+		if (response.ok || response.status === 409) {
+			await response.body?.cancel().catch(() => undefined);
+			return { outcome: "sent", duplicate: response.status === 409, requestId };
+		}
+		const detail = await response
+			.text()
+			.then((text) => JSON.parse(text.slice(0, 8192)) as unknown)
+			.catch(() => undefined);
+		const retryAfter = Number(response.headers.get("retry-after"));
+		return {
+			outcome: "failed",
+			status: response.status,
+			code: refusalCode(response.status, detail),
+			requestId,
+			...(Number.isFinite(retryAfter) && retryAfter > 0
+				? { retryAfterMs: Math.min(retryAfter, 3600) * 1000 }
+				: {}),
+		};
+	}
+
+	/** Answers an event with its reply token; the token is single use and short lived. */
+	async reply(
+		replyToken: string,
+		messages: readonly unknown[],
+		signal?: AbortSignal,
+	): Promise<void> {
+		await this.request("/v2/bot/message/reply", {
+			method: "POST",
+			headers: { "content-type": "application/json" },
+			body: JSON.stringify({ replyToken, messages }),
+			...(signal ? { signal } : {}),
+		});
+	}
+
+	/** 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> {
+		if (kind === "user") return 1;
+		const found = (await this.json(
+			`/v2/bot/${kind}/${encodeURIComponent(id)}/members/count`,
+		)) as { count?: unknown };
+		if (typeof found?.count !== "number" || !Number.isInteger(found.count))
+			throw new LineError(
+				"member_count_malformed",
+				"line: the member count has no count",
+			);
+		return Math.max(1, found.count);
+	}
+
+	/** The monthly message limit of the plan, or undefined when the plan has none. */
+	async messageQuota(): Promise<number | undefined> {
+		const found = (await this.json("/v2/bot/message/quota")) as {
+			type?: unknown;
+			value?: unknown;
+		};
+		if (found?.type === "none") return undefined;
+		if (found?.type !== "limited" || typeof found.value !== "number")
+			throw new LineError("quota_malformed", "line: the quota is malformed");
+		return found.value;
+	}
+
+	/** How many messages this month has used. */
+	async messageConsumption(): Promise<number> {
+		const found = (await this.json("/v2/bot/message/quota/consumption")) as {
+			totalUsage?: unknown;
+		};
+		if (typeof found?.totalUsage !== "number")
+			throw new LineError(
+				"consumption_malformed",
+				"line: the consumption has no totalUsage",
+			);
+		return found.totalUsage;
+	}
+
 	/** The name LINE shows for a group. */
 	async groupName(groupId: string): Promise<string> {
 		const summary = (await this.json(