@interactive-inc/flume 0.1.0 → 0.3.0

package/README.md

@@ -4,11 +4,11 @@ Unified notification listener for Discord, Slack, and GitHub. Raw WebSocket + `f
 
 ```
 Discord  ─┐
-Slack    ─┼──→  FlumeSource.start(handler)  ──→  FlumeEvent
+Slack    ─┼──▶  Flume  ──start(handler)──▶  FlumeEvent  (one merged stream)
 GitHub   ─┘
 ```
 
-Flume only **receives**. It opens the WebSocket / polls the API, parses the payload with Zod, and hands you a typed event. Sending replies is out of scope — bring your own HTTP call.
+Flume only **receives**. It opens the WebSocket / polls the API, parses the payload with Zod, serializes events through a per-source queue, and hands you a typed event. Sending replies is out of scope — bring your own HTTP call.
 
 ## Install
 
@@ -19,62 +19,100 @@ npm add @interactive-inc/flume
 ## Quick start
 
 ```ts
-import { Flume, createFlumeDefaultDeps } from "@interactive-inc/flume"
+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"
+
+const onLog = (log) => console.log(`[${log.level}] ${log.source}/${log.action}: ${log.message}`)
 
 const flume = new Flume({
-  deps: createFlumeDefaultDeps(),
-  onLog: (log) => console.log(`[${log.level}] ${log.source}/${log.action}: ${log.message}`),
-  onStatus: (status, detail) => console.log(`status: ${status} ${detail ?? ""}`),
-  reconnect: { maxAttempts: 10, baseDelay: 1000, maxDelay: 30000 },
+  sources: [
+    new FlumeDiscordSource({ token: process.env.DISCORD_BOT_TOKEN!, onLog, reconnect: true }),
+    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 }),
+  ],
 })
 
-const discord = flume.discord({ token: process.env.DISCORD_BOT_TOKEN! })
-const slack = flume.slack({ appToken: process.env.SLACK_APP_TOKEN! })
-const github = flume.github({ token: process.env.GITHUB_TOKEN!, pollInterval: 60 })
-
-await discord.start((event) => {
+const result = await flume.start((event) => {
   console.log(event.source, event.type, event.meta)
 })
 
-await slack.start((event) => { /* ... */ })
-await github.start((event) => { /* ... */ })
+if (!result.ok) throw result.error
+
+const running = flume.runningState()!
+
+// later
+await running.stop()
+```
+
+## Lifecycle (type-state FSM)
+
+`Flume` enforces lifecycle correctness through three classes — misuse becomes a compile error.
+
+```
+Flume  ──start()──▶  FlumeRunning  ──stop()──▶  FlumeStopped
+(idle)               (running)                  (terminal)
+```
+
+- `Flume.start(handler)` returns `FlumeStartResult` — a discriminated union `{ ok: true } | { ok: false; error: Error }`. On `ok: true`, the `FlumeRunning` instance is reachable via `flume.runningState()`. On partial failure (one source fails while another succeeds), the already-started sources are rolled back and `ok: false` is returned with per-source detail in `error.message`.
+- `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`.
+
+```ts
+const result = await flume.start(handler)
+if (!result.ok) {
+  console.error(result.error.message)
+  // "Flume.start: 1 source(s) failed: slack: connect refused"
+  return
+}
+
+const running = flume.runningState()!
+
+running.start() // type error — `start` is not on FlumeRunning
+
+const stopped = await running.stop()
+stopped.stop()  // type error
+stopped.start() // type error
+stopped.statuses() // [{ name: "discord", status: "disconnected" }, ...]
 ```
 
 ## Direct source usage
 
-Skip the `Flume` container and instantiate a source directly:
+Sources work standalone — `Flume` is only needed for multi-source orchestration.
 
 ```ts
-import { FlumeDiscordSource, createFlumeDefaultDeps } from "@interactive-inc/flume"
+import { FlumeDiscordSource } from "@interactive-inc/flume/discord"
 
 const source = new FlumeDiscordSource({
   token: process.env.DISCORD_BOT_TOKEN!,
-  deps: createFlumeDefaultDeps(),
   reconnect: true,
   onLog: (log) => console.log(log),
 })
 
-await source.start((event) => { /* ... */ })
+const result = await source.start((event) => { /* ... */ })
+if (!result.ok) throw result.error
 ```
 
 ## Sub-entries
 
-Each source is also importable on its own. Use this to keep Slack's Socket Mode code out of a Discord-only bundle, or vice versa.
+Each source has a dedicated entry — importing one does not pull the others into your bundle. The root entry never loads source-specific code.
 
-| sub-entry             | exports                                                           |
-|-----------------------|-------------------------------------------------------------------|
-| `@interactive-inc/flume/discord`  | `FlumeDiscordSource`                                              |
-| `@interactive-inc/flume/slack`    | `FlumeSlackSource`                                                |
-| `@interactive-inc/flume/github`   | `FlumeGitHubSource`                                               |
+| sub-entry                          | exports                                                                                                                                                                   |
+|------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `@interactive-inc/flume`           | `Flume`, `FlumeRunning`, `FlumeStopped`, `FlumeLogger`, `FlumeReconnector`, `createFlumeDefaultDeps`, errors, types                          |
+| `@interactive-inc/flume/discord`   | `FlumeDiscordSource`, `FlumeDiscordGateway`, `FlumeDiscordGatewayIntents`, `FlumeDiscordHeartbeat`, `FlumeDiscordGatewaySession`, `parseDiscordGatewayMessage`, `extractDiscordMeta`, `FlumeGatewayMessageSchema` |
+| `@interactive-inc/flume/slack`     | `FlumeSlackSource`, `FlumeSlackSocketMode`, `FlumeSlackSeenCache`, `obtainSlackUrl`, `extractSlackMeta`, `FlumeSlackEnvelopeSchema`, `FlumeSlackConnectionResponseSchema`   |
+| `@interactive-inc/flume/github`    | `FlumeGitHubSource`, `FlumeGitHubPoller`, `FlumeGitHubSeenCache`, `extractGitHubMeta`, `FlumeGitHubNotificationSchema`                                                     |
 
 ```ts
-import { FlumeSlackSource } from "@interactive-inc/flume/slack"
+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"
 ```
 
-The root entry exports the `Flume` container, every source class, every protocol class (`FlumeDiscordGateway`, `FlumeSlackSocketMode`, `FlumeGitHubPoller`), `FlumeReconnector`, `FlumeLogger`, `createFlumeDefaultDeps`, every Zod schema, every error class, and all public types.
-
 ## Event shape
 
 Every source emits the same `FlumeEvent`:
@@ -163,36 +201,54 @@ GitHub populates `detail` with the failure reason (e.g. `"HTTP 500"`, `"network
 
 ## Cancellation
 
-Pass an `AbortSignal` to any source. Aborting prevents start and triggers `stop()`:
+Pass an `AbortSignal` to `Flume` (propagates to every source) or to an individual source.
 
 ```ts
 const controller = new AbortController()
-const flume = new Flume({ signal: controller.signal, deps: createFlumeDefaultDeps() })
-// ...
-controller.abort() // all sources stop
+
+const flume = new Flume({
+  sources: [new FlumeDiscordSource({ token, signal: controller.signal })],
+  signal: controller.signal,
+})
+
+```ts
+const result = await flume.start(handler)
+if (!result.ok) throw result.error
+
+const running = flume.runningState()!
+
+controller.abort() // FlumeRunning auto-transitions to FlumeStopped
 ```
 
+If the signal is already aborted at `Flume.start()` time, `start` returns `{ ok: false, error }` and no source is touched.
+
 ## Dependency injection
 
-Every IO boundary (`fetch`, `WebSocket`, `now`, `random`, timers) lives in `FlumeRuntimeDeps`. The default factory wraps the global equivalents; tests pass mocks:
+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.
 
 ```ts
 import { createFlumeDefaultDeps } from "@interactive-inc/flume"
 
-const deps = {
-  ...createFlumeDefaultDeps(),
-  fetch: mockFetch,
-  WebSocket: MockWebSocket,
-  now: () => 1_000,
-  random: () => 0.5,
-}
+new FlumeDiscordSource({
+  token,
+  deps: {
+    ...createFlumeDefaultDeps(),
+    fetch: mockFetch,
+    now: () => 1_000,
+  },
+})
 ```
 
-`Flume` accepts `Partial<FlumeRuntimeDeps>` and merges over the defaults — override only what you need.
+## Safety
+
+- **Backpressure** — each source has its own `FlumeSerialQueue`. 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 `{ ok: false, error }` 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.
 
 ## Errors
 
-Flume does not throw on protocol/network failures. Connection methods return `T | Error` and you check `instanceof`:
+Flume does not throw on protocol/network failures. `Source.start()` and `Flume.start()` return `FlumeStartResult` (`{ ok: true } | { ok: false; error: Error }`) — branch on `result.ok`. Protocol-layer helpers (`FlumeDiscordGateway.connect()`, `obtainSlackUrl()`, …) return `T | Error` and you check `instanceof`:
 
 - `FlumeConnectionError` — WebSocket closed before ready
 - `FlumeHttpError` — HTTP call returned an error payload (e.g. Slack `ok: false`)
@@ -205,7 +261,7 @@ Internal handler exceptions are caught and logged (never rethrown into the proto
 | source  | transport                         | auth                                          |
 |---------|----------------------------------|-----------------------------------------------|
 | Discord | Gateway WebSocket v10 (JSON)     | bot token                                     |
-| Slack   | Socket Mode WebSocket            | app token (`botToken` optional, for future)  |
+| 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:
@@ -213,18 +269,21 @@ GitHub also exposes `gh auth token` if you want to reuse the `gh` CLI's session:
 ```ts
 import { execSync } from "node:child_process"
 const token = execSync("gh auth token").toString().trim()
-const github = flume.github({ token })
+const github = new FlumeGitHubSource({ token })
 ```
 
 ## Module layout
 
-- `Flume` — DI container; `.discord()` / `.slack()` / `.github()` build sources with shared deps
-- `FlumeDiscordSource` / `FlumeSlackSource` / `FlumeGitHubSource` — high-level sources
+- `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)
 - `FlumeDiscordGateway` / `FlumeSlackSocketMode` / `FlumeGitHubPoller` — protocol layer
-- `FlumeReconnector` — exponential backoff with jitter
+- `FlumeDiscordGatewaySession` — immutable session value object (id / seq / resume URL) carried across Discord reconnects
+- `FlumeSlackSeenCache` / `FlumeGitHubSeenCache` — per-source duplicate suppression
+- `FlumeReconnector` — exponential backoff with jitter (the internal `scheduleFlumeReconnect` helper is not exported; sources wire it themselves)
 - `FlumeLogger` — structured log emitter (feeds `onLog`)
-- `FlumeRuntimeDeps` — IO boundary port
-- Zod schemas for every external boundary: `FlumeGatewayMessageSchema`, `FlumeSlackEnvelopeSchema`, `FlumeSlackConnectionResponseSchema`, `FlumeGitHubNotificationSchema`
+- `FlumeRuntimeDeps` — IO boundary port (`fetch`, `WebSocket`, `now`, `random`, timers)
+- `extractDiscordMeta` / `extractSlackMeta` / `extractGitHubMeta` — pure functions that build `FlumeEvent.meta` from each protocol's payload shape
+- Per-source Zod schemas: `FlumeGatewayMessageSchema` (discord), `FlumeSlackEnvelopeSchema` / `FlumeSlackConnectionResponseSchema` (slack), `FlumeGitHubNotificationSchema` (github)
 
 ## Development
 

package/dist/connection-error-BOk97djj.d.ts

@@ -0,0 +1,6 @@
+//#region lib/errors/connection-error.d.ts
+declare class FlumeConnectionError extends Error {
+  constructor(message: string);
+}
+//#endregion
+export { FlumeConnectionError as t };

package/dist/discord.d.ts

@@ -1,16 +1,20 @@
-import { o as FlumeHandler, t as FlumeDiscordSourceOptions, y as FlumeStatus } from "./types-BVQSU336.js";
+import { A as FlumeGatewayMessageSchema, C as FlumeStartResult, c as FlumeLogHandler, o as FlumeHandler, p as FlumeRuntimeDeps, r as FlumeGatewayMessage, t as FlumeDiscordSourceOptions, w as FlumeStatus } from "./types-Bm9uKUQz.js";
+import { t as FlumeConnectionError } from "./connection-error-BOk97djj.js";
+import { t as FlumeParseError } from "./parse-error-BAiCLRmk.js";
 
 //#region lib/discord/discord-source.d.ts
 declare class FlumeDiscordSource {
   private readonly options;
+  readonly name: "discord";
   private gateway;
   private reconnector;
   private handler;
   private currentStatus;
   private readonly log;
   private readonly deps;
+  private readonly queue;
   constructor(options: FlumeDiscordSourceOptions);
-  start(handler: FlumeHandler): Promise<void>;
+  start(handler: FlumeHandler): Promise<FlumeStartResult>;
   stop(): Promise<void>;
   status(): FlumeStatus;
   private connectInternal;
@@ -18,7 +22,110 @@ declare class FlumeDiscordSource {
   private handleGatewayStatus;
   private scheduleReconnect;
   private setStatus;
-  static extractMeta(eventName: string, eventData: Record<string, unknown>): Record<string, string>;
 }
 //#endregion
-export { FlumeDiscordSource };
+//#region lib/discord/extract-discord-meta.d.ts
+declare function extractDiscordMeta(eventName: string, eventData: Record<string, unknown>): Record<string, string>;
+//#endregion
+//#region lib/discord/discord-gateway-session.d.ts
+type Props$2 = {
+  sessionId: string | null;
+  resumeUrl: string | null;
+  seq: number | null;
+};
+declare class FlumeDiscordGatewaySession {
+  readonly sessionId: string | null;
+  readonly resumeUrl: string | null;
+  readonly seq: number | null;
+  constructor(props: Props$2);
+  static empty(): FlumeDiscordGatewaySession;
+  canResume(): boolean;
+  withSeq(seq: number): FlumeDiscordGatewaySession;
+  withReady(sessionId: string, resumeUrl: string): FlumeDiscordGatewaySession;
+  withReset(): FlumeDiscordGatewaySession;
+}
+//#endregion
+//#region lib/discord/discord-gateway.d.ts
+type Deps = Pick<FlumeRuntimeDeps, "WebSocket" | "setInterval" | "clearInterval" | "setTimeout" | "random" | "now">;
+type Props$1 = {
+  token: string;
+  intents: number;
+  onDispatch: (event: string, data: Record<string, unknown>) => void;
+  onStatus: (status: "connected" | "disconnected") => void;
+  onLog?: FlumeLogHandler;
+  deps: Deps;
+};
+declare class FlumeDiscordGateway {
+  private readonly props;
+  private readonly log;
+  private ws;
+  private heartbeat;
+  session: FlumeDiscordGatewaySession;
+  stopped: boolean;
+  private pendingResolve;
+  private pendingResolved;
+  constructor(props: Props$1);
+  connect(url?: string): Promise<FlumeConnectionError | null>;
+  disconnect(): void;
+  isConnected(): boolean;
+  private completeConnect;
+  private onMessage;
+  private onHello;
+  private onHeartbeatAck;
+  private onHeartbeatRequest;
+  private onReconnectRequest;
+  private onInvalidSession;
+  private onDispatch;
+  private onClose;
+  private onError;
+  private send;
+  private sendIdentify;
+  private sendResume;
+}
+//#endregion
+//#region lib/discord/discord-gateway-intents.d.ts
+declare const FlumeDiscordGatewayIntents: {
+  readonly Guilds: number;
+  readonly GuildMembers: number;
+  readonly GuildModeration: number;
+  readonly GuildExpressions: number;
+  readonly GuildIntegrations: number;
+  readonly GuildWebhooks: number;
+  readonly GuildInvites: number;
+  readonly GuildVoiceStates: number;
+  readonly GuildPresences: number;
+  readonly GuildMessages: number;
+  readonly GuildMessageReactions: number;
+  readonly GuildMessageTyping: number;
+  readonly DirectMessages: number;
+  readonly DirectMessageReactions: number;
+  readonly DirectMessageTyping: number;
+  readonly MessageContent: number;
+  readonly GuildScheduledEvents: number;
+  readonly AutoModerationConfiguration: number;
+  readonly AutoModerationExecution: number;
+  readonly GuildMessagePolls: number;
+  readonly DirectMessagePolls: number;
+};
+//#endregion
+//#region lib/discord/discord-heartbeat.d.ts
+type Props = {
+  onSend: () => void;
+  onZombie: () => void;
+  deps: Pick<FlumeRuntimeDeps, "setInterval" | "clearInterval">;
+};
+declare class FlumeDiscordHeartbeat {
+  private readonly props;
+  private timer;
+  private ackReceived;
+  constructor(props: Props);
+  start(intervalMs: number): void;
+  stop(): void;
+  ack(): void;
+  isRunning(): boolean;
+}
+//#endregion
+//#region lib/discord/parse-discord-gateway-message.d.ts
+declare function parseDiscordGatewayMessage(raw: string): FlumeGatewayMessage | FlumeParseError;
+//#endregion
+export { FlumeDiscordGateway, FlumeDiscordGatewayIntents, FlumeDiscordGatewaySession, FlumeDiscordHeartbeat, FlumeDiscordSource, FlumeGatewayMessageSchema, extractDiscordMeta, parseDiscordGatewayMessage };