@interactive-inc/flume 0.3.0 → 0.4.0

package/README.md

@@ -1,6 +1,6 @@
 # open-flume
 
-Unified notification listener for Discord, Slack, and GitHub. Raw WebSocket + `fetch` + Zod. Zero SDK dependencies — no `discord.js`, no `@slack/bolt`, no `@slack/web-api`. Runs on Node 18+, Bun, Deno, Cloudflare Workers, or any environment with global `fetch` and `WebSocket`.
+Unified notification listener for Discord, Slack, and GitHub. Raw WebSocket + `fetch` + Zod. Zero SDK dependencies — no `discord.js`, no `@slack/bolt`, no `@slack/web-api`. ESM only (`require()` not supported). Runs on Node 22+, Bun, Deno, Cloudflare Workers, or any environment with global `fetch` and `WebSocket` (the GitHub source only needs `fetch`).
 
 ```
 Discord  ─┐
@@ -29,18 +29,21 @@ const onLog = (log) => console.log(`[${log.level}] ${log.source}/${log.action}:
 const flume = new Flume({
   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 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 result = await flume.start((event) => {
+const running = await flume.start((event) => {
   console.log(event.source, event.type, event.meta)
 })
 
-if (!result.ok) throw result.error
-
-const running = flume.runningState()!
+if (running instanceof Error) throw running
 
 // later
 await running.stop()
@@ -55,27 +58,26 @@ 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`.
+- `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.
 - `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 result = await flume.start(handler)
-if (!result.ok) {
-  console.error(result.error.message)
+const running = await flume.start(handler)
+if (running instanceof Error) {
+  console.error(running.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.stop() // type error
 stopped.start() // type error
-stopped.statuses() // [{ name: "discord", status: "disconnected" }, ...]
+stopped.statuses() // [{ source: "discord", status: "disconnected" }, ...]
 ```
 
 ## Direct source usage
@@ -91,20 +93,22 @@ const source = new FlumeDiscordSource({
   onLog: (log) => console.log(log),
 })
 
-const result = await source.start((event) => { /* ... */ })
-if (!result.ok) throw result.error
+const error = await source.start((event) => {
+  /* ... */
+})
+if (error instanceof Error) throw error
 ```
 
 ## 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.
 
-| 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`                                                     |
+| 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`                                    |
 
 ```ts
 import { Flume } from "@interactive-inc/flume"
@@ -115,24 +119,38 @@ import { FlumeGitHubSource } from "@interactive-inc/flume/github"
 
 ## Event shape
 
-Every source emits the same `FlumeEvent`:
+Every source emits the same `FlumeEvent` — a discriminated union keyed on `source` so `data` narrows automatically:
 
 ```ts
-type FlumeSourceName = "discord" | "slack" | "github"
-
-type FlumeEvent = {
-  source: FlumeSourceName
+type FlumeDiscordEvent = {
+  source: "discord"
+  type: string
+  data: Record<string, unknown>
+  meta: Record<string, string>
+  receivedAt: number
+}
+type FlumeSlackEvent = {
+  source: "slack"
   type: string
-  data: unknown
+  data: Record<string, unknown>
   meta: Record<string, string>
   receivedAt: number
 }
+type FlumeGitHubEvent = {
+  source: "github"
+  type: "notification"
+  data: FlumeGitHubNotification
+  meta: Record<string, string>
+  receivedAt: number
+}
+
+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`      |
@@ -203,7 +221,7 @@ GitHub populates `detail` with the failure reason (e.g. `"HTTP 500"`, `"network
 
 Pass an `AbortSignal` to `Flume` (propagates to every source) or to an individual source.
 
-```ts
+````ts
 const controller = new AbortController()
 
 const flume = new Flume({
@@ -212,15 +230,13 @@ const flume = new Flume({
 })
 
 ```ts
-const result = await flume.start(handler)
-if (!result.ok) throw result.error
-
-const running = flume.runningState()!
+const running = await flume.start(handler)
+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 `{ ok: false, error }` and no source is touched.
+If the signal is already aborted at `Flume.start()` time, `start` returns a `FlumeStartError` and no source is touched.
 
 ## Dependency injection
 
@@ -241,28 +257,31 @@ new FlumeDiscordSource({
 
 ## 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.
+- **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 `{ ok: false, error }` is returned with per-source detail.
+- **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.
 
 ## Errors
 
-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`:
+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`:
 
+- `FlumeStartError` — `Flume.start()` / `Source.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).
 
+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.
+
 ## 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                         |
+| 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                 |
 
 GitHub also exposes `gh auth token` if you want to reuse the `gh` CLI's session:
 
@@ -276,14 +295,9 @@ const github = new FlumeGitHubSource({ token })
 
 - `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
-- `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 (`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)
+- `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
 
 ## Development
 
@@ -296,7 +310,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 18+, Bun, Deno, Cloudflare Workers, or modern browsers.
+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`.
 
 ## License
 

package/dist/connection-error-HUO3PC3G.js

@@ -0,0 +1,16 @@
+//#region lib/errors/connection-error.ts
+/**
+* 接続失敗を表す。Discord Gateway / Slack Socket Mode / その他 WebSocket 系の close で発生。
+* `code` は接続が落ちた際の close code (Discord は 4xxx 帯が再接続可否を示す)
+*/
+var FlumeConnectionError = class extends Error {
+	code;
+	constructor(message, options) {
+		super(message, options?.cause === void 0 ? void 0 : { cause: options.cause });
+		this.name = "FlumeConnectionError";
+		this.code = options?.code ?? null;
+		Object.freeze(this);
+	}
+};
+//#endregion
+export { FlumeConnectionError as t };

package/dist/discord.d.ts

@@ -1,6 +1,4 @@
-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";
+import { C as FlumeSourceStartOptions, T as FlumeStatus, c as FlumeHandler, n as FlumeDiscordSourceOptions } from "./types-D-tO-Mh2.js";
 
 //#region lib/discord/discord-source.d.ts
 declare class FlumeDiscordSource {
@@ -9,78 +7,22 @@ declare class FlumeDiscordSource {
   private gateway;
   private reconnector;
   private handler;
-  private currentStatus;
   private readonly log;
   private readonly deps;
   private readonly queue;
+  private readonly signals;
+  private readonly statusEmitter;
+  private readonly onSignalAbort;
   constructor(options: FlumeDiscordSourceOptions);
-  start(handler: FlumeHandler): Promise<FlumeStartResult>;
+  start(handler: FlumeHandler, options?: FlumeSourceStartOptions): Promise<Error | null>;
   stop(): Promise<void>;
   status(): FlumeStatus;
+  private hasWebSocket;
   private connectInternal;
   private handleDispatch;
+  private safeExtractMeta;
   private handleGatewayStatus;
   private scheduleReconnect;
-  private setStatus;
-}
-//#endregion
-//#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
@@ -108,24 +50,7 @@ declare const FlumeDiscordGatewayIntents: {
   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;
+//#region lib/discord/extract-discord-meta.d.ts
+declare function flumeExtractDiscordMeta(eventName: string, eventData: Record<string, unknown>): Record<string, string>;
 //#endregion
-export { FlumeDiscordGateway, FlumeDiscordGatewayIntents, FlumeDiscordGatewaySession, FlumeDiscordHeartbeat, FlumeDiscordSource, FlumeGatewayMessageSchema, extractDiscordMeta, parseDiscordGatewayMessage };
+export { FlumeDiscordGatewayIntents, FlumeDiscordSource, flumeExtractDiscordMeta };