@interactive-inc/flume 0.6.0 → 0.9.1

package/README.md

@@ -4,7 +4,7 @@ Unified notification listener for Discord, Slack, and GitHub. Raw WebSocket + `f
 
 ```
 Discord  ─┐
-Slack    ─┼──▶  Flume  ──start()──▶  FlumeEvent  (one merged stream)
+Slack    ─┼──▶  Flume  ──open()──▶  FlumeEvent  (one merged stream)
 GitHub   ─┘
 ```
 
@@ -24,8 +24,8 @@ import { FlumeDiscordSource } from "@interactive-inc/flume/discord"
 import { FlumeSlackSource } from "@interactive-inc/flume/slack"
 import { FlumeGitHubSource } from "@interactive-inc/flume/github"
 
-const flume = new Flume(
-  [
+const flume = new Flume({
+  sources: [
     new FlumeDiscordSource({ token: process.env.DISCORD_BOT_TOKEN! }),
     new FlumeSlackSource({
       appToken: process.env.SLACK_APP_TOKEN!,
@@ -33,31 +33,31 @@ const flume = new Flume(
     }),
     new FlumeGitHubSource({ token: process.env.GITHUB_TOKEN!, pollInterval: 60 }),
   ],
-  {
-    onEvent: (event) => {
-      console.log(event.source, event.type, event.meta)
-    },
-    onLog: (log) => console.log(`[${log.level}] ${log.source}/${log.action}: ${log.message}`),
-    onStatus: (e) => console.log(`${e.source} → ${e.status}${e.detail ? ` (${e.detail})` : ""}`),
-    reconnect: { maxAttempts: 10 },
+  onEvent: (item) => {
+    // single firehose: events + every log, discriminated by `kind`
+    if (item.kind === "event") console.log(item.event.source, item.event.type)
+    if (item.kind === "log") console.log(`[${item.log.level}] ${item.log.action}`)
   },
-)
+  onError: (log) => Sentry.captureException(log.error ?? new Error(log.message)),
+  reconnect: { maxAttempts: 10 },
+})
+
+const running = await flume.open()
 
-const running = await flume.start()
 if (running instanceof Error) throw running
 
 // later
-await running.stop()
+await running.close()
 ```
 
-`new Flume(sources, options?)` — `sources` is the only required argument. `options` is an object and every field is optional: omit `onEvent` to drop events silently (connection-observation mode), omit `onLog` to disable logging, etc. All three callbacks share the `on*` naming for symmetry: `onEvent` is the business stream, `onLog` is the operational stream, `onStatus` is the connection-state stream.
+`new Flume({ sources, ...options })` — a single options object; `sources` is the only required field, everything else is optional. There is one unified firehose: `onEvent` (push) and `FlumeRunning.stream()` (pull) both deliver the same `FlumeStreamItem` — received events **and** every log (status transitions, errors, debug) merged into one stream. The consumer filters by `item.kind` (`"event"` / `"log"`) and `item.log.level`. This is built for piping the whole picture into an agent (Claude / Codex) so it notices disconnects on its own. `onError` is a convenience filter that additionally receives only the `level: "error"` logs (route it straight to Sentry).
 
 ```ts
 // Minimum: just open the protocols and discard everything.
-const flume = new Flume([new FlumeDiscordSource({ token })])
+const flume = new Flume({ sources: [new FlumeDiscordSource({ token })] })
 
-// Connection-observation only: see when sources reconnect, ignore the payloads.
-const flume = new Flume([new FlumeDiscordSource({ token })], { onLog })
+// Errors-only: forward failures to Sentry, ignore the rest.
+const flume = new Flume({ sources: [new FlumeDiscordSource({ token })], onError })
 ```
 
 ## Lifecycle (type-state FSM)
@@ -65,32 +65,55 @@ const flume = new Flume([new FlumeDiscordSource({ token })], { onLog })
 `Flume` enforces lifecycle correctness through three classes — misuse becomes a compile error.
 
 ```
-Flume  ──start()──▶  FlumeRunning  ──stop()──▶  FlumeStopped
+Flume  ──open()──▶  FlumeRunning  ──close()──▶  FlumeClosed
 (idle)               (running)                  (terminal)
 ```
 
-- `Flume.start()` returns `FlumeRunning | FlumeStartError`. Branch with `instanceof Error`. On partial failure (one source fails while another succeeds), the already-started sources are rolled back and a `FlumeStartError` is returned with per-source detail in `.message`. Calling `start()` a second time on the same `Flume` instance returns `FlumeStartError` at runtime — the type system also rejects calling `start()` on the returned `FlumeRunning`/`FlumeStopped` handles.
-- `FlumeRunning.stop()` returns a `FlumeStopped` snapshot. `stop()` is idempotent and concurrent-safe.
-- `FlumeStopped` exposes only `statuses()` — a frozen snapshot of each source's final state. No `start`, no `stop`, no leaking source references.
-- An `AbortSignal` on `Flume` drives an automatic transition to `FlumeStopped`.
-- `FlumeRunning.kind === "running"` and `FlumeStopped.kind === "stopped"` provide a runtime discriminator when generic code holds the union.
+- `Flume.open()` returns `FlumeRunning | FlumeStartError`. Branch with `instanceof Error`. On partial failure (one source fails while another succeeds), the already-opened sources are rolled back and a `FlumeStartError` is returned with per-source detail in `.message`. Calling `open()` a second time on the same `Flume` instance returns `FlumeStartError` at runtime — the type system also rejects calling `open()` on the returned `FlumeRunning`/`FlumeClosed` handles.
+- `FlumeRunning.close()` returns a `FlumeClosed` snapshot. `close()` is idempotent and concurrent-safe.
+- `FlumeClosed` exposes only `statuses()` — a frozen snapshot of each source's final state. No `open`, no `close`, no leaking source references.
+- An `AbortSignal` on `Flume` drives an automatic transition to `FlumeClosed`.
+- `FlumeRunning.kind === "running"` and `FlumeClosed.kind === "closed"` provide a runtime discriminator when generic code holds the union.
 
 ```ts
-const running = await flume.start()
+const running = await flume.open()
 if (running instanceof Error) {
   console.error(running.message)
-  // "Flume.start: 1 source(s) failed: slack: connect refused"
+  // "Flume.open: 1 source(s) failed: slack: connect refused"
   return
 }
 
-running.start() // type error — `start` is not on FlumeRunning
+running.open() // type error — `open` is not on FlumeRunning
 
-const stopped = await running.stop()
-stopped.stop() // type error
-stopped.start() // type error
-stopped.statuses() // [{ source: "discord", status: "disconnected" }, ...]
+const closed = await running.close()
+closed.close() // type error
+closed.open() // type error
+closed.statuses() // [{ source: "discord", status: "disconnected" }, ...]
 ```
 
+## Dynamic groups
+
+A `Flume` is single-use: its source set is fixed at construction and the FSM is terminal once closed. To add or drop sources at runtime, compose at a higher level with `FlumeConfluence` — it holds many `Flume` instances, merges all their firehoses into one `onEvent`, and lets you `add` / `remove` groups while the others keep running.
+
+```ts
+import { FlumeConfluence } from "@interactive-inc/flume"
+
+const confluence = new FlumeConfluence({
+  onEvent: (item) => {
+    if (item.kind === "event") feedToAgent(item.event)
+    if (item.kind === "log" && item.log.action === "status") noticeDisconnect(item.log)
+  },
+  reconnect: { maxAttempts: 10 },
+})
+
+await confluence.add("team-a", [new FlumeDiscordSource({ token: tokenA })])
+await confluence.add("team-b", [new FlumeSlackSource({ appToken, botToken })]) // existing groups keep running
+await confluence.remove("team-a") // stops only team-a
+await confluence.closeAll()
+```
+
+`add(id, sources)` starts a fresh `Flume` for that group and returns `Error | null` (a duplicate id or a failed start is returned, never thrown). The `id` is just a management handle — the merged stream itself is untagged; identify the origin via the `source` field inside each item. Each group is an independent `Flume`, so a failure in one group never rolls back another. Reconstructing a group (rather than mutating one in place) loses only its reconnect counters, dedup caches, and Discord session resume — acceptable on a deliberate add/remove.
+
 ## Sub-entries
 
 Each source has a dedicated entry — importing one does not pull the others into your bundle. The root entry never loads source-specific code.
@@ -100,16 +123,18 @@ import { Flume, FlumeSource } from "@interactive-inc/flume"
 import { FlumeDiscordSource } from "@interactive-inc/flume/discord"
 import { FlumeSlackSource } from "@interactive-inc/flume/slack"
 import { FlumeGitHubSource } from "@interactive-inc/flume/github"
+import { FlumeTimeSource } from "@interactive-inc/flume/time"
 ```
 
-- `@interactive-inc/flume` — `Flume`, `FlumeRunning`, `FlumeStopped`, `FlumeSource` (abstract base for third-party sources), `createFlumeDefaultDeps`, errors, types
+- `@interactive-inc/flume` — `Flume`, `FlumeConfluence`, `FlumeRunning`, `FlumeClosed`, `FlumeSource` (abstract base for third-party sources), `createFlumeDefaultDeps`, errors, types
 - `@interactive-inc/flume/discord` — `FlumeDiscordSource`, `FlumeDiscordGatewayIntents`, `flumeExtractDiscordMeta`
 - `@interactive-inc/flume/slack` — `FlumeSlackSource`, `flumeExtractSlackMeta`
 - `@interactive-inc/flume/github` — `FlumeGitHubSource`, `flumeExtractGitHubMeta`
+- `@interactive-inc/flume/time` — `FlumeTimeSource`, `parseCron`, `flumeCronNext`
 
 ## Custom sources
 
-Extend `FlumeSource` to plug in any protocol. The base class owns `start`/`stop`/`status`, the per-source event queue, status emission with `onStatus` bridging, and consumed/stopped guards. You implement `connect` (open the protocol, emit events, set status) and `disconnect` (tear it down).
+Extend `FlumeSource` to plug in any protocol. The base class owns `start`/`stop`/`status`, the per-source event queue, status emission (logged on every transition), and consumed/stopped guards. You implement `connect` (open the protocol, emit events, set status) and `disconnect` (tear it down).
 
 ```ts
 import { FlumeSource } from "@interactive-inc/flume"
@@ -153,7 +178,62 @@ class MyWebhookSource extends FlumeSource {
 }
 ```
 
-`this.emit({...})` queues events through the base's serial queue and routes them to `ctx.onEvent` with `attempt()` isolation. `this.setStatus(...)` deduplicates idempotent transitions, logs the change, and forwards it to `ctx.onStatus`. Subclasses never need to write try/catch.
+`this.emit({...})` queues events through the base's serial queue and routes them to `ctx.onEvent` with `attempt()` isolation. `this.setStatus(...)` deduplicates idempotent transitions and logs the change (which is how status surfaces to consumers). Subclasses never need to write try/catch.
+
+## Time source
+
+`FlumeTimeSource` emits a `tick` event on a cron schedule. It holds no external connection, so it reaches `connected` as soon as it starts and is never a reconnect target. Useful as a heartbeat — a fixed marker in the same stream as your real sources.
+
+```ts
+import { FlumeTimeSource } from "@interactive-inc/flume/time"
+
+new Flume({
+  sources: [new FlumeTimeSource({ cron: "0 * * * *" })],
+  onEvent: (item) => console.log(item), // fires at minute 0 of every hour
+})
+```
+
+The cron expression is a standard 5-field spec (`minute hour day-of-month month day-of-week`) evaluated against the wall clock (local time). Supported per field: `*`, `*/n`, `a`, `a-b`, `a-b/n`, and comma lists. Day-of-week accepts `0-7` (`7` and `0` both mean Sunday). When both day-of-month and day-of-week are restricted, a day matches if either matches (standard cron semantics).
+
+`message()` customizes each tick. Omitted fields fall back to the defaults (`type: "tick"`, `data: { firedAt, cron }`, `meta: { cron }`):
+
+```ts
+new FlumeTimeSource({
+  cron: "*/15 * * * *",
+  message: (tick) => ({
+    type: "heartbeat",
+    data: { at: new Date(tick.firedAt).toISOString() },
+    meta: { channel: "ops" },
+  }),
+})
+```
+
+`tick.firedAt` is the scheduled wall-clock time (epoch ms), not the exact `setTimeout` firing instant. A throwing `message()` is isolated and falls back to the defaults. Parse the cron up front with `parseCron(expr)` (returns `FlumeCron | FlumeParseError`) or compute the next fire with `flumeCronNext(cron, afterMs)`.
+
+## Pull stream
+
+`FlumeRunning.stream()` is the pull form of the same firehose as `onEvent` — an async iterator over `FlumeStreamItem`, handy for feeding an agent (Claude / Codex) with `for await`, where backpressure falls out naturally from how fast you pull.
+
+```ts
+type FlumeStreamItem = { kind: "event"; event: FlumeEvent } | { kind: "log"; log: FlumeLog }
+
+const running = await flume.open()
+if (running instanceof Error) throw running
+
+for await (const item of running.stream()) {
+  if (item.kind === "event") await handleWithAgent(item.event)
+  if (item.kind === "log" && item.log.action === "status") noticeDisconnect(item.log)
+}
+// loop ends when the flume stops (running.close() or signal abort)
+```
+
+The iterator ends cleanly when the flume stops; `break`ing out unsubscribes automatically. When a slow consumer lets the buffer overflow, the oldest items are dropped by default:
+
+```ts
+running.stream({ buffer: 5000, onOverflow: "drop-newest" })
+```
+
+`stream()` (pull) and `onEvent` (push) carry the same items — use either or both. Multiple `stream()` consumers each get their own buffer.
 
 ## Event shape
 
@@ -181,8 +261,15 @@ type FlumeGitHubEvent = {
   meta: Record<string, string>
   receivedAt: number
 }
+type FlumeTimeEvent = {
+  source: "time"
+  type: string // "tick" by default, or whatever your message() returns
+  data: Record<string, unknown>
+  meta: Record<string, string>
+  receivedAt: number
+}
 
-type FlumeEvent = FlumeDiscordEvent | FlumeSlackEvent | FlumeGitHubEvent
+type FlumeEvent = FlumeDiscordEvent | FlumeSlackEvent | FlumeGitHubEvent | FlumeTimeEvent
 ```
 
 `meta` is flat string keys tailored per source:
@@ -190,12 +277,13 @@ type FlumeEvent = FlumeDiscordEvent | FlumeSlackEvent | FlumeGitHubEvent
 - discord — `event_type`, `channel_id`, `guild_id`, `user_id`
 - slack — `event_type`, `channel_id`, `user_id`, `thread_ts`, `slack_event_type`
 - github — `event_type`, `reason`, `subject_type`, `repository`, `thread_id`
+- time — `cron` by default, or whatever your `message()` returns
 
 `data` is the raw parsed payload (Zod-validated at the protocol boundary).
 
 ## Observability
 
-Flume never calls a third-party service. Every internal action is reported through the `onLog` callback you pass to `Flume` — there are no silent paths. Each `FlumeLog` is tagged with `source: "flume"`, `source: "discord"`, `source: "slack"`, `source: "github"`, or your custom source's `name`.
+Flume never calls a third-party service. Every internal action is reported through the firehose (`onEvent` push / `stream()` pull) as `{ kind: "log", log }` items — there are no silent paths. Each `FlumeLog` is tagged with `source: "flume"`, `source: "discord"`, `source: "slack"`, `source: "github"`, `source: "time"`, or your custom source's `name`. `onError` is a convenience filter that additionally receives only the `level: "error"` subset (route it straight to Sentry).
 
 ```ts
 type FlumeLog = {
@@ -217,12 +305,14 @@ What gets logged:
 - Parse failures — any Zod schema mismatch emits a `warn` with the field paths and messages. Dropped GitHub notifications carry a per-item `parse.skip` and a `parse.summary` count. Slack envelopes that don't match `FlumeSlackEnvelopeSchema` emit `envelope.parse-fail` with the incoming `type` and the issues. Discord frames with an unknown op emit `ws.unknown-op`.
 - Reconnect — `reconnect.scheduled` (with delay in ms), `reconnect.exhausted` (with attempt count), `reconnect.reset` (on successful connect after retries), `reconnect.cancel` (on stop).
 - Status transitions — `status` action with `previous → next`.
-- Errors — `level: "error"` carries the `error` field so you can `captureException` in your `onLog` callback.
+- Errors — `level: "error"` carries the `error` field; use `onError` for a pre-filtered error sink.
 
-Route it anywhere — Sentry, Datadog, `console`, a file — your choice:
+Route it anywhere — Sentry, Datadog, `console`, a file — your choice. Filter the log items out of the firehose:
 
 ```ts
-onLog: (log) => {
+onEvent: (item) => {
+  if (item.kind !== "log") return
+  const log = item.log
   if (log.level === "error" && log.error) {
     Sentry.captureException(log.error, { tags: { source: log.source, action: log.action } })
   }
@@ -237,7 +327,7 @@ onLog: (log) => {
 
 ```ts
 new Flume(sources, {
-  onEvent: (event) => { ... },
+  onEvent: (item) => { ... },
   reconnect: {
     maxAttempts: 10,
     baseDelay: 1000,   // first backoff
@@ -250,17 +340,17 @@ Exponential backoff with jitter. Discord resumes the session when possible — t
 
 ## Status
 
+There is no dedicated status callback. Connection-state transitions ride the firehose as `status` log entries (`action: "status"`, message `previous → next`, with `detail.from` / `detail.to` / `detail.reason`). This is deliberate: a consumer feeding the firehose to an agent gets work (events) and drops (status logs) in one stream, no third callback.
+
 ```ts
-type FlumeStatusEvent = {
-  source: string
-  status: "disconnected" | "connecting" | "connected" | "reconnecting"
-  detail?: string
+onEvent: (item) => {
+  if (item.kind === "log" && item.log.action === "status") {
+    console.log(`${item.log.source}: ${item.log.message}`) // "github: connected → reconnecting (HTTP 500)"
+  }
 }
-
-onStatus: (event: FlumeStatusEvent) => void
 ```
 
-GitHub populates `detail` with the failure reason (e.g. `"HTTP 500"`, `"network error"`). Discord and Slack leave `detail` undefined.
+The live status of each source is also readable as a snapshot via `running.statuses()` and `closed.statuses()` (`{ source, status }[]`). GitHub populates the transition `reason` with the failure cause (e.g. `"HTTP 500"`, `"network error"`); Discord and Slack leave it null.
 
 ## Cancellation
 
@@ -269,18 +359,20 @@ Pass an `AbortSignal` to `Flume` — it propagates to every source via the auto-
 ```ts
 const controller = new AbortController()
 
-const flume = new Flume([new FlumeDiscordSource({ token })], {
-  onEvent: (event) => { ... },
+const flume = new Flume({
+  sources: [new FlumeDiscordSource({ token })],
+  onEvent: (item) => { ... },
   signal: controller.signal,
 })
 
-const running = await flume.start()
+const running = await flume.open()
+
 if (running instanceof Error) throw running
 
-controller.abort() // FlumeRunning auto-transitions to FlumeStopped
+controller.abort() // FlumeRunning auto-transitions to FlumeClosed
 ```
 
-If the signal is already aborted at `Flume.start()` time, `start` returns a `FlumeStartError` and no source is touched.
+If the signal is already aborted at `Flume.open()` time, `open` returns a `FlumeStartError` and no source is touched.
 
 ## Dependency injection
 
@@ -289,8 +381,9 @@ Every IO boundary (`fetch`, `WebSocket`, `now`, `random`, timers) lives in `Flum
 ```ts
 import { createFlumeDefaultDeps } from "@interactive-inc/flume"
 
-new Flume([new FlumeDiscordSource({ token })], {
-  onEvent: (event) => { ... },
+new Flume({
+  sources: [new FlumeDiscordSource({ token })],
+  onEvent: (item) => { ... },
   deps: {
     ...createFlumeDefaultDeps(),
     fetch: mockFetch,
@@ -301,29 +394,30 @@ new Flume([new FlumeDiscordSource({ token })], {
 
 ## Safety
 
-- Ordering — each source has its own `FlumeSerialQueue` and per-source events are delivered FIFO. Cross-source ordering between events from different sources is undefined (no global serialization). `onEvent` invocations are awaited and run one at a time per source, so async callbacks don't race and `stop()` drains in-flight events before transitioning state.
+- Ordering — each source has its own `FlumeSerialQueue` and per-source events are delivered FIFO. Cross-source ordering between events from different sources is undefined (no global serialization). `onEvent` invocations are awaited and run one at a time per source, so async callbacks don't race and `close()` drains in-flight events before transitioning state.
 - Duplicate suppression — Slack envelopes are deduped by `envelope_id` (`FlumeSlackSeenCache`) to absorb ack retries. GitHub notifications are deduped by `id + updated_at` (`FlumeGitHubSeenCache`). Discord uses session resume so the Gateway does not re-emit dispatches.
-- Partial-failure rollback — if any source fails during `Flume.start()`, the already-started sources are stopped and a `FlumeStartError` is returned with per-source detail.
-- Idempotent stop — `FlumeRunning.stop()` is safe to call concurrently; the first call wins and subsequent callers receive the same `FlumeStopped` snapshot. The same guard exists at source level: a double-`stop()` (e.g. via signal abort racing manual stop) does not re-invoke `disconnect()`.
+- Partial-failure rollback — if any source fails during `Flume.open()`, the already-started sources are stopped and a `FlumeStartError` is returned with per-source detail.
+- Idempotent close — `FlumeRunning.close()` is safe to call concurrently; the first call wins and subsequent callers receive the same `FlumeClosed` snapshot. The same guard exists at source level: a double-`close()` (e.g. via signal abort racing a manual close) does not re-invoke `disconnect()`.
 
 ## Errors
 
-Flume does not throw on protocol/network failures. Every entry point returns `T | Error` — branch with `instanceof Error`. `Flume.start()` returns `FlumeRunning | FlumeStartError`; protocol-layer helpers (`FlumeDiscordGateway.connect()`, etc.) return `T | Error`:
+Flume does not throw on protocol/network failures. Every entry point returns `T | Error` — branch with `instanceof Error`. `Flume.open()` returns `FlumeRunning | FlumeStartError`; protocol-layer helpers (`FlumeDiscordGateway.connect()`, etc.) return `T | Error`:
 
-- `FlumeStartError` — `Flume.start()` refused or failed (already started, signal aborted, partial-failure rollback)
+- `FlumeStartError` — `Flume.open()` refused or failed (already started, signal aborted, partial-failure rollback)
 - `FlumeConnectionError` — WebSocket closed before ready
 - `FlumeHttpError` — HTTP call returned an error payload (e.g. Slack `ok: false`)
 - `FlumeParseError` — Unparseable WebSocket frame
 
 Exceptions thrown from `onEvent` are caught and logged (never rethrown into the protocol loop).
 
-The library guarantees that no exception escapes any public surface — constructors, `start()`, `stop()`, the `onEvent` invocation path, the abort-signal path, and the `onLog` / `onStatus` callbacks all route IO and user-supplied callbacks through internal `safe*` wrappers and the generic `attempt()` helper. A misbehaving `onEvent` / `onLog` / `onStatus` will be logged and isolated rather than crashing the protocol loop.
+The library guarantees that no exception escapes any public surface — constructors, `open()`, `close()`, the `onEvent` invocation path, the `stream()` iterator, the abort-signal path, and the `onError` callback all route IO and user-supplied callbacks through internal `safe*` wrappers and the generic `attempt()` helper. A misbehaving `onEvent` / `onError` will be logged and isolated rather than crashing the protocol loop.
 
 ## Supported sources
 
 - Discord — Gateway WebSocket v10 (JSON), bot token
 - Slack — Socket Mode WebSocket, app token + bot token (both required)
 - GitHub — REST polling `/notifications`, personal access token
+- Time — cron-scheduled ticks, no external connection
 
 GitHub also exposes `gh auth token` if you want to reuse the `gh` CLI's session:
 
@@ -335,9 +429,9 @@ const github = new FlumeGitHubSource({ token })
 
 ## Module layout
 
-- `Flume` / `FlumeRunning` / `FlumeStopped` — type-state FSM merging multiple sources into one stream
+- `Flume` / `FlumeRunning` / `FlumeClosed` — type-state FSM merging multiple sources into one stream
 - `FlumeSource` — abstract base class for any protocol source; extend it to plug in your own
-- `FlumeDiscordSource` / `FlumeSlackSource` / `FlumeGitHubSource` — built-in sources, each extending `FlumeSource`
+- `FlumeDiscordSource` / `FlumeSlackSource` / `FlumeGitHubSource` / `FlumeTimeSource` — built-in sources, each extending `FlumeSource`
 - `FlumeRuntimeDeps` — IO boundary port (`fetch`, `WebSocket`, `now`, `random`, timers); `WebSocket` is nullable for fetch-only runtimes
 - `flumeExtractDiscordMeta` / `flumeExtractSlackMeta` / `flumeExtractGitHubMeta` — pure functions that build `FlumeEvent.meta` from each protocol's payload shape
 - Internal protocol modules (`FlumeDiscordGateway`, `FlumeSlackSocketMode`, `FlumeGitHubPoller`, `FlumeReconnector`, `FlumeLogger`, seen caches, schemas) are not part of the public surface — depend on the high-level Sources only
@@ -353,7 +447,7 @@ bunx vp lint       # lint
 bunx vp fmt        # format
 ```
 
-The library itself is runtime-agnostic. The dev toolchain (build / test / lint) uses Bun + `vite-plus` + `vitest`, but the published `dist/` is plain ESM with TypeScript declarations and runs on Node 22+, Bun, Deno, Cloudflare Workers, or modern browsers. Runtimes without a global `WebSocket` (e.g. fetch-only edge functions) can still use `FlumeGitHubSource`; `FlumeDiscordSource` / `FlumeSlackSource` will return `FlumeStartError` at `start()` time if `deps.WebSocket` is `null`.
+The library itself is runtime-agnostic. The dev toolchain (build / test / lint) uses Bun + `vite-plus` + `vitest`, but the published `dist/` is plain ESM with TypeScript declarations and runs on Node 22+, Bun, Deno, Cloudflare Workers, or modern browsers. Runtimes without a global `WebSocket` (e.g. fetch-only edge functions) can still use `FlumeGitHubSource`; `FlumeDiscordSource` / `FlumeSlackSource` will return `FlumeStartError` at `open()` time if `deps.WebSocket` is `null`.
 
 ## License
 

package/dist/discord.d.ts

@@ -1,4 +1,4 @@
-import { C as FlumeSourceStartContext, r as FlumeDiscordSourceOptions, t as FlumeSource } from "./flume-source-DuUFPhSe.js";
+import { r as FlumeDiscordSourceOptions, t as FlumeSource, w as FlumeSourceStartContext } from "./flume-source.js";
 
 //#region lib/discord/discord-source.d.ts
 declare class FlumeDiscordSource extends FlumeSource {

package/dist/discord.js

@@ -1,7 +1,8 @@
-import { a as FlumeStartError, c as safeNormalizeError, i as safeNow, l as safeErrorMessage, n as safeInvokeCallback, o as FlumeParseError, r as FlumeLogger, s as attempt, t as FlumeSource } from "./flume-source-DUvt9aJt.js";
-import { t as FlumeConnectionError } from "./connection-error-HUO3PC3G.js";
-import { a as safeRandom, i as FlumeReconnector, n as isRecord, r as scheduleFlumeReconnect, t as safeStringify } from "./safe-stringify-DbWQw9qe.js";
-import { t as safeJsonParse } from "./safe-json-parse-CfJjt-RY.js";
+import { a as FlumeStartError, c as safeNormalizeError, i as safeNow, l as safeErrorMessage, n as safeInvokeCallback, o as FlumeParseError, r as FlumeLogger, s as attempt, t as FlumeSource } from "./flume-source.js";
+import { t as FlumeConnectionError } from "./connection-error.js";
+import { i as safeRandom, n as scheduleFlumeReconnect, r as FlumeReconnector, t as safeStringify } from "./safe-stringify.js";
+import { t as isRecord } from "./is-record.js";
+import { t as safeJsonParse } from "./safe-json-parse.js";
 import { z } from "zod/v4";
 //#region lib/discord/discord-gateway-session.ts
 var FlumeDiscordGatewaySession = class FlumeDiscordGatewaySession {

package/dist/{flume-source-DuUFPhSe.d.ts → flume-source.d.ts}

@@ -74,7 +74,7 @@ type FlumeRuntimeDeps = {
   setInterval(fn: () => void, ms: number): FlumeTimerHandle;
   clearInterval(id: FlumeTimerHandle): void;
 };
-type FlumeSourceName = "discord" | "slack" | "github";
+type FlumeSourceName = "discord" | "slack" | "github" | "time";
 type FlumeDiscordEvent = {
   source: "discord";
   type: string;
@@ -96,15 +96,29 @@ type FlumeGitHubEvent = {
   meta: Record<string, string>;
   receivedAt: number;
 };
-type FlumeEvent = FlumeDiscordEvent | FlumeSlackEvent | FlumeGitHubEvent;
+type FlumeTimeEvent = {
+  source: "time";
+  type: string;
+  data: Record<string, unknown>;
+  meta: Record<string, string>;
+  receivedAt: number;
+};
+type FlumeEvent = FlumeDiscordEvent | FlumeSlackEvent | FlumeGitHubEvent | FlumeTimeEvent;
 type FlumeEventHandler = (event: FlumeEvent) => void | Promise<void>;
-type FlumeStatus = "disconnected" | "connecting" | "connected" | "reconnecting";
-type FlumeStatusEvent = {
-  source: string;
-  status: FlumeStatus;
-  detail?: string;
+type FlumeStreamItem = {
+  kind: "event";
+  event: FlumeEvent;
+} | {
+  kind: "log";
+  log: FlumeLog;
+};
+type FlumeStreamHandler = (item: FlumeStreamItem) => void;
+type FlumeStreamOverflow = "drop-oldest" | "drop-newest";
+type FlumeStreamOptions = {
+  /** バッファ上限 (既定 1000)。consumer が遅れて溢れたら onOverflow に従う */buffer?: number; /** バッファ溢れ時の方針 (既定 "drop-oldest") */
+  onOverflow?: FlumeStreamOverflow;
 };
-type FlumeStatusHandler = (event: FlumeStatusEvent) => void;
+type FlumeStatus = "disconnected" | "connecting" | "connected" | "reconnecting";
 type FlumeSourceStatus = {
   /**
    * 多くは `FlumeSourceName` のいずれかだが、`source.name` getter が throw する
@@ -124,6 +138,8 @@ type FlumeLog = {
   timestamp: number;
 };
 type FlumeLogHandler = (log: FlumeLog) => void;
+/** error レベルのログだけを受け取る (Sentry など error 専用の送信先向け) */
+type FlumeErrorHandler = (log: FlumeLog) => void;
 type FlumeLogInput = {
   action: string;
   message: string;
@@ -144,9 +160,17 @@ type FlumeSourceLocalStatusHandler = (status: FlumeStatus, detail?: string) => v
 type FlumeSourceStartContext = {
   onEvent: FlumeEventHandler;
   log: FlumeLogger;
-  deps: FlumeRuntimeDeps;
-  onStatus: FlumeSourceLocalStatusHandler;
+  deps: FlumeRuntimeDeps; /** Source 内部の status 遷移ブリッジ。Flume 公開 API に status callback は無く、遷移は log に出る */
+  onStatus?: FlumeSourceLocalStatusHandler;
   reconnect: FlumeReconnectConfig | null;
+  /**
+   * Flume.start() に渡された signal をそのまま転送する。
+   * source 実装が自前で `fetch(url, { signal })` / `setTimeout` cancel / WS close を
+   * host abort 経由で発火させたい時に使う (Flume 自身は最外殻で runClose を駆動するので
+   * source は signal を無視しても動作的には停止する — 自然な伝播パスが欲しい場合のみ)。
+   * Flume.options.signal が未設定なら省略される。
+   */
+  signal?: AbortSignal;
 };
 type FlumeDiscordSourceOptions = {
   token: string;
@@ -164,6 +188,23 @@ type FlumeGitHubSourceOptions = {
   token: string;
   pollInterval?: number;
 };
+type FlumeTimeTick = {
+  /** cron がマッチした壁時計時刻 (epoch ms)。setTimeout の発火実時刻ではなく予定時刻 */firedAt: number;
+  cron: string;
+};
+/**
+ * tick ごとに emit するイベントの上書き内容。全フィールド optional。
+ * 省略フィールドは既定値 (type: "tick" / data: tick 内容 / meta: { cron }) になる
+ */
+type FlumeTimeMessage = {
+  type?: string;
+  data?: Record<string, unknown>;
+  meta?: Record<string, string>;
+};
+type FlumeTimeSourceOptions = {
+  /** 5 フィールド cron 式 (minute hour day-of-month month day-of-week)。壁時計 (local time) 基準 */cron: string;
+  message?: (tick: FlumeTimeTick) => FlumeTimeMessage;
+};
 type FlumeGatewayMessage = z.infer<typeof FlumeGatewayMessageSchema>;
 type FlumeSlackEnvelope = z.infer<typeof FlumeSlackEnvelopeSchema>;
 type FlumeSlackConnectionResponse = z.infer<typeof FlumeSlackConnectionResponseSchema>;
@@ -225,4 +266,4 @@ declare abstract class FlumeSource {
   protected abstract disconnect(): Promise<void> | void;
 }
 //#endregion
-export { FlumeSourceStartContext as C, FlumeStatusHandler as D, FlumeStatusEvent as E, FlumeTimerHandle as O, FlumeSourceName as S, FlumeStatus as T, FlumeSlackConnectionResponse as _, FlumeEventHandler as a, FlumeSlackSourceOptions as b, FlumeGitHubNotification as c, FlumeLogHandler as d, FlumeLogInput as f, FlumeRuntimeDeps as g, FlumeReconnectOptions as h, FlumeEvent as i, FlumeLogger as k, FlumeGitHubSourceOptions as l, FlumeReconnectConfig as m, FlumeDiscordEvent as n, FlumeGatewayMessage as o, FlumeLogLevel as p, FlumeDiscordSourceOptions as r, FlumeGitHubEvent as s, FlumeSource as t, FlumeLog as u, FlumeSlackEnvelope as v, FlumeSourceStatus as w, FlumeSourceLocalStatusHandler as x, FlumeSlackEvent as y };
+export { FlumeStreamOverflow as A, FlumeSourceName as C, FlumeStreamHandler as D, FlumeStatus as E, FlumeTimerHandle as F, FlumeLogger as I, FlumeTimeMessage as M, FlumeTimeSourceOptions as N, FlumeStreamItem as O, FlumeTimeTick as P, FlumeSourceLocalStatusHandler as S, FlumeSourceStatus as T, FlumeRuntimeDeps as _, FlumeEvent as a, FlumeSlackEvent as b, FlumeGitHubEvent as c, FlumeLog as d, FlumeLogHandler as f, FlumeReconnectOptions as g, FlumeReconnectConfig as h, FlumeErrorHandler as i, FlumeTimeEvent as j, FlumeStreamOptions as k, FlumeGitHubNotification as l, FlumeLogLevel as m, FlumeDiscordEvent as n, FlumeEventHandler as o, FlumeLogInput as p, FlumeDiscordSourceOptions as r, FlumeGatewayMessage as s, FlumeSource as t, FlumeGitHubSourceOptions as u, FlumeSlackConnectionResponse as v, FlumeSourceStartContext as w, FlumeSlackSourceOptions as x, FlumeSlackEnvelope as y };

package/dist/{flume-source-DUvt9aJt.js → flume-source.js}

@@ -298,10 +298,13 @@ var FlumeSource = class {
 	async stop() {
 		if (this.stopped) return;
 		this.stopped = true;
-		await this.disconnect();
-		await this.queue.drain();
-		this.statusEmitter?.set("disconnected");
-		this.ctx = null;
+		try {
+			await this.disconnect();
+		} finally {
+			await this.queue.drain();
+			this.statusEmitter?.set("disconnected");
+			this.ctx = null;
+		}
 	}
 	status() {
 		return this.statusEmitter?.value ?? "disconnected";

package/dist/github.d.ts

@@ -1,4 +1,4 @@
-import { C as FlumeSourceStartContext, c as FlumeGitHubNotification, l as FlumeGitHubSourceOptions, t as FlumeSource } from "./flume-source-DuUFPhSe.js";
+import { l as FlumeGitHubNotification, t as FlumeSource, u as FlumeGitHubSourceOptions, w as FlumeSourceStartContext } from "./flume-source.js";
 
 //#region lib/github/github-source.d.ts
 declare class FlumeGitHubSource extends FlumeSource {

package/dist/github.js

@@ -1,7 +1,7 @@
-import { c as safeNormalizeError, i as safeNow, l as safeErrorMessage, o as FlumeParseError, r as FlumeLogger, s as attempt, t as FlumeSource } from "./flume-source-DUvt9aJt.js";
-import { t as FlumeHttpError } from "./http-error-CPSKoSie.js";
-import { t as safeJsonParse } from "./safe-json-parse-CfJjt-RY.js";
-import { t as safeReadText } from "./safe-read-text-JQd_5vbd.js";
+import { c as safeNormalizeError, i as safeNow, l as safeErrorMessage, o as FlumeParseError, r as FlumeLogger, s as attempt, t as FlumeSource } from "./flume-source.js";
+import { t as FlumeHttpError } from "./http-error.js";
+import { t as safeJsonParse } from "./safe-json-parse.js";
+import { t as safeReadText } from "./safe-read-text.js";
 import { z } from "zod/v4";
 //#region lib/github/extract-github-meta.ts
 function flumeExtractGitHubMeta(notification) {
@@ -43,8 +43,12 @@ var FlumeGitHubSeenCache = class {
 	}
 	trim() {
 		if (this.seen.size <= this.props.maxSize) return;
-		const entries = [...this.seen.entries()];
-		this.seen = new Map(entries.slice(entries.length - this.props.maxSize));
+		let removeCount = this.seen.size - this.props.maxSize;
+		for (const id of this.seen.keys()) {
+			if (removeCount <= 0) break;
+			this.seen.delete(id);
+			removeCount--;
+		}
 	}
 	get size() {
 		return this.seen.size;
@@ -104,6 +108,7 @@ var FlumeGitHubPoller = class {
 		const error = await this.poll();
 		if (error) return error;
 		if (this.isStoppedFlag) return null;
+		if (this.rateLimitTimer !== null) return null;
 		this.scheduleInterval();
 		return null;
 	}
@@ -128,7 +133,7 @@ var FlumeGitHubPoller = class {
 					message: safeErrorMessage({ error }),
 					error
 				});
-			}).catch(() => {});
+			});
 		}, this.effectiveIntervalSec * 1e3));
 		if (intervalResult instanceof Error) {
 			this.log.error({