@interactive-inc/flume 0.4.0 → 0.6.0

package/README.md

@@ -4,7 +4,7 @@ Unified notification listener for Discord, Slack, and GitHub. Raw WebSocket + `f
 
 ```
 Discord  ─┐
-Slack    ─┼──▶  Flume  ──start(handler)──▶  FlumeEvent  (one merged stream)
+Slack    ─┼──▶  Flume  ──start()──▶  FlumeEvent  (one merged stream)
 GitHub   ─┘
 ```
 
@@ -24,31 +24,42 @@ import { FlumeDiscordSource } from "@interactive-inc/flume/discord"
 import { FlumeSlackSource } from "@interactive-inc/flume/slack"
 import { FlumeGitHubSource } from "@interactive-inc/flume/github"
 
-const onLog = (log) => console.log(`[${log.level}] ${log.source}/${log.action}: ${log.message}`)
-
-const flume = new Flume({
-  sources: [
-    new FlumeDiscordSource({ token: process.env.DISCORD_BOT_TOKEN!, onLog, reconnect: true }),
+const flume = new Flume(
+  [
+    new FlumeDiscordSource({ token: process.env.DISCORD_BOT_TOKEN! }),
     new FlumeSlackSource({
       appToken: process.env.SLACK_APP_TOKEN!,
       botToken: process.env.SLACK_BOT_TOKEN!,
-      onLog,
-      reconnect: true,
     }),
-    new FlumeGitHubSource({ token: process.env.GITHUB_TOKEN!, onLog, pollInterval: 60 }),
+    new FlumeGitHubSource({ token: process.env.GITHUB_TOKEN!, pollInterval: 60 }),
   ],
-})
-
-const running = await flume.start((event) => {
-  console.log(event.source, event.type, event.meta)
-})
+  {
+    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 },
+  },
+)
 
+const running = await flume.start()
 if (running instanceof Error) throw running
 
 // later
 await running.stop()
 ```
 
+`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.
+
+```ts
+// Minimum: just open the protocols and discard everything.
+const flume = new Flume([new FlumeDiscordSource({ token })])
+
+// Connection-observation only: see when sources reconnect, ignore the payloads.
+const flume = new Flume([new FlumeDiscordSource({ token })], { onLog })
+```
+
 ## Lifecycle (type-state FSM)
 
 `Flume` enforces lifecycle correctness through three classes — misuse becomes a compile error.
@@ -58,14 +69,14 @@ Flume  ──start()──▶  FlumeRunning  ──stop()──▶  FlumeStopped
 (idle)               (running)                  (terminal)
 ```
 
-- `Flume.start(handler)` 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.
+- `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.
 
 ```ts
-const running = await flume.start(handler)
+const running = await flume.start()
 if (running instanceof Error) {
   console.error(running.message)
   // "Flume.start: 1 source(s) failed: slack: connect refused"
@@ -80,43 +91,70 @@ stopped.start() // type error
 stopped.statuses() // [{ source: "discord", status: "disconnected" }, ...]
 ```
 
-## Direct source usage
+## Sub-entries
 
-Sources work standalone — `Flume` is only needed for multi-source orchestration.
+Each source has a dedicated entry — importing one does not pull the others into your bundle. The root entry never loads source-specific code.
 
 ```ts
+import { Flume, FlumeSource } from "@interactive-inc/flume"
 import { FlumeDiscordSource } from "@interactive-inc/flume/discord"
-
-const source = new FlumeDiscordSource({
-  token: process.env.DISCORD_BOT_TOKEN!,
-  reconnect: true,
-  onLog: (log) => console.log(log),
-})
-
-const error = await source.start((event) => {
-  /* ... */
-})
-if (error instanceof Error) throw error
+import { FlumeSlackSource } from "@interactive-inc/flume/slack"
+import { FlumeGitHubSource } from "@interactive-inc/flume/github"
 ```
 
-## Sub-entries
+- `@interactive-inc/flume` — `Flume`, `FlumeRunning`, `FlumeStopped`, `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`
 
-Each source has a dedicated entry — importing one does not pull the others into your bundle. The root entry never loads source-specific code.
+## Custom sources
 
-| sub-entry                        | exports                                                                          |
-| -------------------------------- | -------------------------------------------------------------------------------- |
-| `@interactive-inc/flume`         | `Flume`, `FlumeRunning`, `FlumeStopped`, `createFlumeDefaultDeps`, errors, types |
-| `@interactive-inc/flume/discord` | `FlumeDiscordSource`, `FlumeDiscordGatewayIntents`, `flumeExtractDiscordMeta`    |
-| `@interactive-inc/flume/slack`   | `FlumeSlackSource`, `flumeExtractSlackMeta`                                      |
-| `@interactive-inc/flume/github`  | `FlumeGitHubSource`, `flumeExtractGitHubMeta`                                    |
+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).
 
 ```ts
-import { Flume } 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 { FlumeSource } from "@interactive-inc/flume"
+import type { FlumeSourceStartContext } from "@interactive-inc/flume"
+
+class MyWebhookSource extends FlumeSource {
+  readonly name = "my-webhook"
+
+  private timer: ReturnType<typeof setInterval> | null = null
+
+  constructor(private readonly options: { url: string; pollInterval?: number }) {
+    super()
+  }
+
+  protected async connect(ctx: FlumeSourceStartContext): Promise<Error | null> {
+    this.setStatus("connecting")
+    const interval = (this.options.pollInterval ?? 30) * 1000
+    this.timer = ctx.deps.setInterval(() => this.poll(ctx), interval) as ReturnType<
+      typeof setInterval
+    >
+    this.setStatus("connected")
+    return null
+  }
+
+  protected disconnect(): void {
+    if (this.timer) clearInterval(this.timer)
+    this.timer = null
+  }
+
+  private async poll(ctx: FlumeSourceStartContext): Promise<void> {
+    const res = await ctx.deps.fetch(this.options.url)
+    const payload = await res.json()
+    this.emit({
+      source: this.name as "discord", // declare your own discriminant via FlumeEvent extension
+      type: "webhook",
+      data: payload,
+      meta: { event_type: "webhook" },
+      receivedAt: ctx.deps.now(),
+    })
+  }
+}
 ```
 
+`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.
+
 ## Event shape
 
 Every source emits the same `FlumeEvent` — a discriminated union keyed on `source` so `data` narrows automatically:
@@ -149,17 +187,15 @@ type FlumeEvent = FlumeDiscordEvent | FlumeSlackEvent | FlumeGitHubEvent
 
 `meta` is flat string keys tailored per source:
 
-| source  | meta keys                                                              |
-| ------- | ---------------------------------------------------------------------- |
-| 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`      |
+- 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`
 
 `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` or each source — there are no silent paths.
+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`.
 
 ```ts
 type FlumeLog = {
@@ -175,13 +211,13 @@ type FlumeLog = {
 
 What gets logged:
 
-- **HTTP boundary** — every request URL, response status, and parsed body shape (`http.request` / `http.response` / `http.body`). Slack's `apps.connections.open` call and GitHub's poll request both emit these.
-- **WebSocket boundary** — every inbound frame (`ws.recv`), every outbound frame (`ws.send` / `ws.sent`), with a 200-byte preview and total byte count. Discord op / t / s is decoded into structured `detail`.
-- **Protocol lifecycle** — Discord HELLO / READY / RESUMED / RECONNECT / INVALID_SESSION / HEARTBEAT / HEARTBEAT_ACK, Slack hello / disconnect / envelope ack, GitHub bootstrap / fresh / idle.
-- **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 handler.
+- HTTP boundary — every request URL, response status, and parsed body shape (`http.request` / `http.response` / `http.body`). Slack's `apps.connections.open` call and GitHub's poll request both emit these.
+- WebSocket boundary — every inbound frame (`ws.recv`), every outbound frame (`ws.send` / `ws.sent`), with a 200-byte preview and total byte count. Discord op / t / s is decoded into structured `detail`.
+- Protocol lifecycle — Discord HELLO / READY / RESUMED / RECONNECT / INVALID_SESSION / HEARTBEAT / HEARTBEAT_ACK, Slack hello / disconnect / envelope ack, GitHub bootstrap / fresh / idle.
+- 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.
 
 Route it anywhere — Sentry, Datadog, `console`, a file — your choice:
 
@@ -197,56 +233,64 @@ onLog: (log) => {
 
 ## Reconnect
 
-`reconnect` accepts `true`, an options object, or is omitted (no reconnect).
+`reconnect` on `Flume` is an options object — omit it to disable reconnects entirely.
 
 ```ts
-reconnect: {
-  maxAttempts: 10,
-  baseDelay: 1000,   // first backoff
-  maxDelay: 30000,   // backoff cap
-}
+new Flume(sources, {
+  onEvent: (event) => { ... },
+  reconnect: {
+    maxAttempts: 10,
+    baseDelay: 1000,   // first backoff
+    maxDelay: 30000,   // backoff cap
+  },
+})
 ```
 
-Exponential backoff with jitter. Discord resumes the session when possible — the session id and resume URL are carried across reconnects via `FlumeDiscordGatewaySession`.
+Exponential backoff with jitter. Discord resumes the session when possible — the session id and resume URL are carried across reconnects via `FlumeDiscordGatewaySession`. GitHub polling doesn't need reconnect (it's stateless polling); the option is wired through but ignored.
 
 ## Status
 
 ```ts
-onStatus: (status: "disconnected" | "connecting" | "connected" | "reconnecting", detail?: string) => void
+type FlumeStatusEvent = {
+  source: string
+  status: "disconnected" | "connecting" | "connected" | "reconnecting"
+  detail?: string
+}
+
+onStatus: (event: FlumeStatusEvent) => void
 ```
 
 GitHub populates `detail` with the failure reason (e.g. `"HTTP 500"`, `"network error"`). Discord and Slack leave `detail` undefined.
 
 ## Cancellation
 
-Pass an `AbortSignal` to `Flume` (propagates to every source) or to an individual source.
+Pass an `AbortSignal` to `Flume` — it propagates to every source via the auto-stop pathway.
 
-````ts
+```ts
 const controller = new AbortController()
 
-const flume = new Flume({
-  sources: [new FlumeDiscordSource({ token, signal: controller.signal })],
+const flume = new Flume([new FlumeDiscordSource({ token })], {
+  onEvent: (event) => { ... },
   signal: controller.signal,
 })
 
-```ts
-const running = await flume.start(handler)
+const running = await flume.start()
 if (running instanceof Error) throw running
 
 controller.abort() // FlumeRunning auto-transitions to FlumeStopped
-````
+```
 
 If the signal is already aborted at `Flume.start()` time, `start` returns a `FlumeStartError` and no source is touched.
 
 ## Dependency injection
 
-Every IO boundary (`fetch`, `WebSocket`, `now`, `random`, timers) lives in `FlumeRuntimeDeps`. `deps` is optional on every source — when omitted, `createFlumeDefaultDeps()` wraps the global equivalents. Override only when you need mocks or runtime-specific shims.
+Every IO boundary (`fetch`, `WebSocket`, `now`, `random`, timers) lives in `FlumeRuntimeDeps`. `deps` is optional on `Flume` — when omitted, `createFlumeDefaultDeps()` wraps the global equivalents. Override only when you need mocks or runtime-specific shims. The same `deps` is handed to every source through its start context.
 
 ```ts
 import { createFlumeDefaultDeps } from "@interactive-inc/flume"
 
-new FlumeDiscordSource({
-  token,
+new Flume([new FlumeDiscordSource({ token })], {
+  onEvent: (event) => { ... },
   deps: {
     ...createFlumeDefaultDeps(),
     fetch: mockFetch,
@@ -257,31 +301,29 @@ new FlumeDiscordSource({
 
 ## 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). Handler invocations are awaited and run one at a time per source, so async handlers don't race and `stop()` 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.
+- 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.
+- 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()`.
 
 ## Errors
 
-Flume does not throw on protocol/network failures. Every entry point returns `T | Error` — branch with `instanceof Error`. `Flume.start()` returns `FlumeRunning | FlumeStartError`; `Source.start()` returns `Error | null`; protocol-layer helpers (`FlumeDiscordGateway.connect()`, `obtainSlackUrl()`, …) return `T | Error`:
+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`:
 
-- `FlumeStartError` — `Flume.start()` / `Source.start()` refused or failed (already started, signal aborted, partial-failure rollback)
+- `FlumeStartError` — `Flume.start()` 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
 
-Internal handler exceptions are caught and logged (never rethrown into the protocol loop).
+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 handler invocation path, the abort-signal path, and the `onLog` / `onStatus` callbacks all route IO and user-supplied callbacks through internal `safe*` wrappers (`safeNow`, `safeRandom`, `safeReadText`, `safeNewWebSocket`, `safeWsSend`, `safeWsClose`, `safeInvokeCallback`, `safeAddAbortListener`, `safeRemoveAbortListener`, `safeSourceStatus`). A misbehaving `onStatus` / `onLog` / `handler` will be logged and isolated rather than crashing 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.
 
 ## Supported sources
 
-| source  | transport                     | auth                                  |
-| ------- | ----------------------------- | ------------------------------------- |
-| Discord | Gateway WebSocket v10 (JSON)  | bot token                             |
-| Slack   | Socket Mode WebSocket         | app token + bot token (both required) |
-| GitHub  | REST polling `/notifications` | personal access token                 |
+- Discord — Gateway WebSocket v10 (JSON), bot token
+- Slack — Socket Mode WebSocket, app token + bot token (both required)
+- GitHub — REST polling `/notifications`, personal access token
 
 GitHub also exposes `gh auth token` if you want to reuse the `gh` CLI's session:
 
@@ -294,7 +336,8 @@ const github = new FlumeGitHubSource({ token })
 ## Module layout
 
 - `Flume` / `FlumeRunning` / `FlumeStopped` — type-state FSM merging multiple sources into one stream
-- `FlumeDiscordSource` / `FlumeSlackSource` / `FlumeGitHubSource` — high-level sources (each conforms to the structural `FlumeSource` type)
+- `FlumeSource` — abstract base class for any protocol source; extend it to plug in your own
+- `FlumeDiscordSource` / `FlumeSlackSource` / `FlumeGitHubSource` — 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

package/dist/discord.d.ts

@@ -1,25 +1,17 @@
-import { C as FlumeSourceStartOptions, T as FlumeStatus, c as FlumeHandler, n as FlumeDiscordSourceOptions } from "./types-D-tO-Mh2.js";
+import { C as FlumeSourceStartContext, r as FlumeDiscordSourceOptions, t as FlumeSource } from "./flume-source-DuUFPhSe.js";
 
 //#region lib/discord/discord-source.d.ts
-declare class FlumeDiscordSource {
+declare class FlumeDiscordSource extends FlumeSource {
   private readonly options;
   readonly name: "discord";
   private gateway;
   private reconnector;
-  private handler;
-  private readonly log;
-  private readonly deps;
-  private readonly queue;
-  private readonly signals;
-  private readonly statusEmitter;
-  private readonly onSignalAbort;
   constructor(options: FlumeDiscordSourceOptions);
-  start(handler: FlumeHandler, options?: FlumeSourceStartOptions): Promise<Error | null>;
-  stop(): Promise<void>;
-  status(): FlumeStatus;
+  protected connect(ctx: FlumeSourceStartContext): Promise<Error | null>;
+  protected disconnect(): void;
   private hasWebSocket;
   private connectInternal;
-  private handleDispatch;
+  private dispatch;
   private safeExtractMeta;
   private handleGatewayStatus;
   private scheduleReconnect;

package/dist/discord.js

@@ -1,7 +1,7 @@
-import { a as FlumeParseError, c as safeNormalizeError, i as FlumeStartError, l as safeErrorMessage, n as FlumeLogger, o as createFlumeDefaultDeps, r as safeNow, s as attempt, t as safeInvokeCallback } from "./safe-invoke-callback-EpWXwfwp.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-DUvt9aJt.js";
 import { t as FlumeConnectionError } from "./connection-error-HUO3PC3G.js";
-import { a as FlumeReconnector, i as resolveFlumeReconnectConfig, n as isRecord, o as safeRandom, r as scheduleFlumeReconnect, t as safeStringify } from "./safe-stringify-BWS-uXZP.js";
-import { i as safeJsonParse, n as FlumeStatusEmitter, r as FlumeSignalRegistry, t as FlumeSerialQueue } from "./serial-queue-B9LoBc64.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 { z } from "zod/v4";
 //#region lib/discord/discord-gateway-session.ts
 var FlumeDiscordGatewaySession = class FlumeDiscordGatewaySession {
@@ -647,89 +647,38 @@ function flumeExtractDiscordMeta(eventName, eventData) {
 //#endregion
 //#region lib/discord/discord-source.ts
 const DEFAULT_INTENTS = FlumeDiscordGatewayIntents.Guilds | FlumeDiscordGatewayIntents.GuildMessages | FlumeDiscordGatewayIntents.DirectMessages;
-var FlumeDiscordSource = class {
+var FlumeDiscordSource = class extends FlumeSource {
 	options;
 	name = "discord";
 	gateway = null;
 	reconnector = null;
-	handler = null;
-	log;
-	deps;
-	queue = new FlumeSerialQueue();
-	signals;
-	statusEmitter;
-	onSignalAbort = () => {
-		safeInvokeCallback({
-			fn: () => this.stop(),
-			onError: (error) => {
-				this.log.error({
-					action: "signal.abort.stop.failed",
-					message: safeErrorMessage({ error }),
-					error
-				});
-			}
-		});
-	};
 	constructor(options) {
+		super();
 		this.options = options;
-		this.deps = options.deps ?? createFlumeDefaultDeps();
-		this.log = new FlumeLogger({
-			source: "discord",
-			handler: options.onLog,
-			deps: this.deps
-		});
-		this.signals = new FlumeSignalRegistry({
-			log: this.log,
-			onAbort: this.onSignalAbort
-		});
-		this.statusEmitter = new FlumeStatusEmitter({
-			log: this.log,
-			onStatus: options.onStatus
-		});
-		const rc = resolveFlumeReconnectConfig(options.reconnect);
-		if (rc) this.reconnector = new FlumeReconnector({
-			...rc,
-			log: this.log,
-			deps: this.deps
-		});
 	}
-	async start(handler, options) {
-		if (this.signals.isAnyAborted(this.options.signal) || this.signals.isAnyAborted(options?.signal)) return new FlumeStartError("Discord source: signal already aborted");
-		if (!this.hasWebSocket()) return new FlumeStartError("Discord source: deps.WebSocket is null (no WebSocket runtime available)");
-		this.signals.register(this.options.signal);
-		this.signals.register(options?.signal);
-		this.handler = handler;
-		this.log.info({
-			action: "source.start",
-			message: "starting Discord source"
+	async connect(ctx) {
+		if (!this.hasWebSocket(ctx)) return new FlumeStartError("Discord source: deps.WebSocket is null (no WebSocket runtime available)");
+		if (ctx.reconnect && !this.reconnector) this.reconnector = new FlumeReconnector({
+			...ctx.reconnect,
+			log: ctx.log,
+			deps: ctx.deps
 		});
-		return await this.connectInternal();
+		return await this.connectInternal(ctx);
 	}
-	async stop() {
-		this.signals.unregisterAll();
-		this.log.info({
-			action: "source.stop",
-			message: "stopping Discord source"
-		});
-		if (this.reconnector && !this.reconnector.aborted) this.log.debug({
+	disconnect() {
+		if (this.reconnector && !this.reconnector.aborted) this.context?.log.debug({
 			action: "reconnect.cancel",
 			message: "aborting reconnector"
 		});
 		this.reconnector?.cancel();
 		this.gateway?.disconnect();
-		await this.queue.drain();
 		this.gateway = null;
-		this.handler = null;
-		this.statusEmitter.set("disconnected");
 	}
-	status() {
-		return this.statusEmitter.value;
-	}
-	hasWebSocket() {
-		const result = attempt(() => Boolean(this.deps.WebSocket));
+	hasWebSocket(ctx) {
+		const result = attempt(() => Boolean(ctx.deps.WebSocket));
 		if (result instanceof Error) {
 			const error = safeNormalizeError({ value: result });
-			this.log.error({
+			ctx.log.error({
 				action: "deps.web-socket.read.error",
 				message: safeErrorMessage({ error }),
 				error
@@ -738,55 +687,45 @@ var FlumeDiscordSource = class {
 		}
 		return result;
 	}
-	async connectInternal(resumeUrl) {
-		this.statusEmitter.set("connecting");
+	async connectInternal(ctx, resumeUrl) {
+		this.setStatus("connecting");
 		this.gateway = new FlumeDiscordGateway({
 			token: this.options.token,
 			intents: this.options.intents ?? DEFAULT_INTENTS,
-			onLog: this.options.onLog,
-			deps: this.deps,
-			onDispatch: (eventName, eventData) => this.handleDispatch(eventName, eventData),
-			onStatus: (status) => this.handleGatewayStatus(status)
+			onLog: ctx.log.handler,
+			deps: ctx.deps,
+			onDispatch: (eventName, eventData) => this.dispatch(ctx, eventName, eventData),
+			onStatus: (status) => this.handleGatewayStatus(ctx, status)
 		});
 		const error = await this.gateway.connect(resumeUrl);
 		if (error instanceof FlumeConnectionError) {
-			this.log.error({
+			ctx.log.error({
 				action: "connect.failed",
 				message: safeErrorMessage({ error }),
 				error
 			});
 			if (this.gateway.isStopped || !this.reconnector || this.reconnector.aborted) {
-				this.statusEmitter.set("disconnected");
+				this.setStatus("disconnected");
 				return error;
 			}
-			this.scheduleReconnect();
+			this.scheduleReconnect(ctx);
 		}
 		return null;
 	}
-	handleDispatch(eventName, eventData) {
-		const handler = this.handler;
-		if (!handler) return;
-		this.queue.add(async () => {
-			const event = {
-				source: "discord",
-				type: eventName,
-				data: eventData,
-				meta: this.safeExtractMeta(eventName, eventData),
-				receivedAt: safeNow({ deps: this.deps })
-			};
-			const r = await attempt(() => Promise.resolve(handler(event)));
-			if (r instanceof Error) this.log.error({
-				action: "handler.error",
-				message: safeErrorMessage({ error: r }),
-				error: r
-			});
+	dispatch(ctx, eventName, eventData) {
+		this.emit({
+			source: "discord",
+			type: eventName,
+			data: eventData,
+			meta: this.safeExtractMeta(ctx, eventName, eventData),
+			receivedAt: safeNow({ deps: ctx.deps })
 		});
 	}
-	safeExtractMeta(eventName, eventData) {
+	safeExtractMeta(ctx, eventName, eventData) {
 		const result = attempt(() => flumeExtractDiscordMeta(eventName, eventData));
 		if (result instanceof Error) {
 			const error = safeNormalizeError({ value: result });
-			this.log.warn({
+			ctx.log.warn({
 				action: "meta.extract.error",
 				message: safeErrorMessage({ error }),
 				error,
@@ -796,37 +735,37 @@ var FlumeDiscordSource = class {
 		}
 		return result;
 	}
-	handleGatewayStatus(status) {
+	handleGatewayStatus(ctx, status) {
 		if (status === "connected") {
-			if (this.reconnector && this.reconnector.attempt > 0) this.log.info({
+			if (this.reconnector && this.reconnector.attempt > 0) ctx.log.info({
 				action: "reconnect.reset",
 				message: `cleared ${this.reconnector.attempt} attempts`
 			});
 			this.reconnector?.reset();
-			this.statusEmitter.set("connected");
+			this.setStatus("connected");
 			return;
 		}
 		if (this.gateway?.isStopped) {
-			this.statusEmitter.set("disconnected");
+			this.setStatus("disconnected");
 			return;
 		}
-		this.scheduleReconnect();
+		this.scheduleReconnect(ctx);
 	}
-	scheduleReconnect() {
+	scheduleReconnect(ctx) {
 		const url = this.gateway?.session.resumeUrl ?? void 0;
 		scheduleFlumeReconnect({
 			reconnector: this.reconnector,
-			log: this.log,
-			setStatus: (status) => this.statusEmitter.set(status),
+			log: ctx.log,
+			setStatus: (status) => this.setStatus(status),
 			retry: () => {
-				this.connectInternal(url).catch((err) => {
+				this.connectInternal(ctx, url).catch((err) => {
 					const error = safeNormalizeError({ value: err });
-					this.log.error({
+					ctx.log.error({
 						action: "reconnect.unhandled",
 						message: safeErrorMessage({ error }),
 						error
 					});
-					this.statusEmitter.set("disconnected");
+					this.setStatus("disconnected");
 				});
 			}
 		});