@interactive-inc/flume 0.2.0 → 0.3.0

package/README.md

@@ -29,16 +29,18 @@ 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!, 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 running = await flume.start((event) => {
+const result = await flume.start((event) => {
   console.log(event.source, event.type, event.meta)
 })
 
-if (running instanceof Error) throw running
+if (!result.ok) throw result.error
+
+const running = flume.runningState()!
 
 // later
 await running.stop()
@@ -53,19 +55,21 @@ Flume  ──start()──▶  FlumeRunning  ──stop()──▶  FlumeStopped
 (idle)               (running)                  (terminal)
 ```
 
-- `Flume.start(handler)` returns `FlumeRunning | Error`. On partial failure (one source fails while another succeeds), the already-started sources are rolled back and an `Error` is returned with per-source detail.
+- `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 running = await flume.start(handler)
-if (running instanceof Error) {
-  console.error(running.message)
+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()
@@ -87,8 +91,8 @@ const source = new FlumeDiscordSource({
   onLog: (log) => console.log(log),
 })
 
-const error = await source.start((event) => { /* ... */ })
-if (error instanceof Error) throw error
+const result = await source.start((event) => { /* ... */ })
+if (!result.ok) throw result.error
 ```
 
 ## Sub-entries
@@ -97,7 +101,7 @@ Each source has a dedicated entry — importing one does not pull the others int
 
 | sub-entry                          | exports                                                                                                                                                                   |
 |------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| `@interactive-inc/flume`           | `Flume`, `FlumeRunning`, `FlumeStopped`, `FlumeLogger`, `FlumeReconnector`, `scheduleFlumeReconnect`, `createFlumeDefaultDeps`, errors, types                              |
+| `@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`                                                     |
@@ -207,13 +211,16 @@ const flume = new Flume({
   signal: controller.signal,
 })
 
-const running = await flume.start(handler)
-if (running instanceof Error) throw running
+```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 an `Error` and no source is touched.
+If the signal is already aborted at `Flume.start()` time, `start` returns `{ ok: false, error }` and no source is touched.
 
 ## Dependency injection
 
@@ -236,12 +243,12 @@ new FlumeDiscordSource({
 
 - **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 an `Error` is returned with per-source detail.
+- **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`)
@@ -254,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:
@@ -272,7 +279,7 @@ const github = new FlumeGitHubSource({ token })
 - `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` + `scheduleFlumeReconnect` — exponential backoff with jitter + shared reconnect scheduler
+- `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

package/dist/discord.d.ts

@@ -1,4 +1,4 @@
-import { D as FlumeGatewayMessageSchema, c as FlumeLogHandler, o as FlumeHandler, p as FlumeRuntimeDeps, r as FlumeGatewayMessage, t as FlumeDiscordSourceOptions, x as FlumeStatus } from "./types-tnOPBc1p.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";
 
@@ -14,7 +14,7 @@ declare class FlumeDiscordSource {
   private readonly deps;
   private readonly queue;
   constructor(options: FlumeDiscordSourceOptions);
-  start(handler: FlumeHandler): Promise<void | Error>;
+  start(handler: FlumeHandler): Promise<FlumeStartResult>;
   stop(): Promise<void>;
   status(): FlumeStatus;
   private connectInternal;

package/dist/discord.js

@@ -1,7 +1,7 @@
 import { n as createFlumeDefaultDeps, t as FlumeLogger } from "./logger-CpGB9WO_.js";
-import { a as FlumeConnectionError, i as FlumeParseError, n as FlumeReconnector, r as resolveFlumeReconnectConfig, t as scheduleFlumeReconnect } from "./schedule-reconnect-DSxZJG3h.js";
+import { i as FlumeConnectionError, n as resolveFlumeReconnectConfig, r as FlumeParseError, t as FlumeReconnector } from "./reconnector-BDoJ1xNX.js";
 import { t as FlumeSerialQueue } from "./serial-queue-ExmlnpzQ.js";
-import { n as isRecord, t as safeJsonParse } from "./safe-json-parse-WCg_x1JS.js";
+import { n as isRecord, r as scheduleFlumeReconnect, t as safeJsonParse } from "./safe-json-parse-BWlzGOLl.js";
 import { z } from "zod/v4";
 //#region lib/discord/extract-discord-meta.ts
 function extractDiscordMeta(eventName, eventData) {
@@ -429,14 +429,22 @@ var FlumeDiscordSource = class {
 		});
 	}
 	async start(handler) {
-		if (this.options.signal?.aborted) return /* @__PURE__ */ new Error("Discord source: signal already aborted");
+		if (this.options.signal?.aborted) return {
+			ok: false,
+			error: /* @__PURE__ */ new Error("Discord source: signal already aborted")
+		};
 		this.options.signal?.addEventListener("abort", () => this.stop(), { once: true });
 		this.handler = handler;
 		this.log.info({
 			action: "start",
 			message: "starting Discord source"
 		});
-		return this.connectInternal();
+		const result = await this.connectInternal();
+		if (result instanceof Error) return {
+			ok: false,
+			error: result
+		};
+		return { ok: true };
 	}
 	async stop() {
 		this.log.info({
@@ -480,6 +488,7 @@ var FlumeDiscordSource = class {
 			}
 			this.scheduleReconnect();
 		}
+		return null;
 	}
 	handleDispatch(eventName, eventData) {
 		const event = {

package/dist/github.d.ts

@@ -1,4 +1,4 @@
-import { E as FlumeGitHubNotificationSchema, a as FlumeGitHubSourceOptions, c as FlumeLogHandler, i as FlumeGitHubNotification, o as FlumeHandler, p as FlumeRuntimeDeps, x as FlumeStatus } from "./types-tnOPBc1p.js";
+import { C as FlumeStartResult, a as FlumeGitHubSourceOptions, c as FlumeLogHandler, i as FlumeGitHubNotification, k as FlumeGitHubNotificationSchema, o as FlumeHandler, p as FlumeRuntimeDeps, w as FlumeStatus } from "./types-Bm9uKUQz.js";
 
 //#region lib/github/github-source.d.ts
 declare class FlumeGitHubSource {
@@ -10,7 +10,7 @@ declare class FlumeGitHubSource {
   private readonly deps;
   private readonly queue;
   constructor(options: FlumeGitHubSourceOptions);
-  start(handler: FlumeHandler): Promise<void | Error>;
+  start(handler: FlumeHandler): Promise<FlumeStartResult>;
   stop(): Promise<void>;
   status(): FlumeStatus;
   private handleNotifications;

package/dist/github.js

@@ -229,7 +229,10 @@ var FlumeGitHubSource = class {
 		});
 	}
 	async start(handler) {
-		if (this.options.signal?.aborted) return /* @__PURE__ */ new Error("GitHub source: signal already aborted");
+		if (this.options.signal?.aborted) return {
+			ok: false,
+			error: /* @__PURE__ */ new Error("GitHub source: signal already aborted")
+		};
 		this.options.signal?.addEventListener("abort", () => this.stop(), { once: true });
 		this.log.info({
 			action: "start",
@@ -255,8 +258,12 @@ var FlumeGitHubSource = class {
 				error: err
 			});
 			this.setStatus("disconnected");
-			return err;
+			return {
+				ok: false,
+				error: err
+			};
 		}
+		return { ok: true };
 	}
 	async stop() {
 		this.log.info({

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { C as FlumeTimerHandle, S as FlumeStatusHandler, _ as FlumeSource, a as FlumeGitHubSourceOptions, b as FlumeSourceStatus, c as FlumeLogHandler, d as FlumeReconnectConfig, f as FlumeReconnectOptions, g as FlumeSlackSourceOptions, h as FlumeSlackEnvelope, i as FlumeGitHubNotification, l as FlumeLogInput, m as FlumeSlackConnectionResponse, n as FlumeEvent, o as FlumeHandler, p as FlumeRuntimeDeps, r as FlumeGatewayMessage, s as FlumeLog, t as FlumeDiscordSourceOptions, u as FlumeLogLevel, v as FlumeSourceName, x as FlumeStatus, y as FlumeSourceOptions } from "./types-tnOPBc1p.js";
+import { C as FlumeStartResult, E as FlumeTimerHandle, S as FlumeStartOk, T as FlumeStatusHandler, _ as FlumeSource, a as FlumeGitHubSourceOptions, b as FlumeSourceStatus, c as FlumeLogHandler, d as FlumeReconnectConfig, f as FlumeReconnectOptions, g as FlumeSlackSourceOptions, h as FlumeSlackEnvelope, i as FlumeGitHubNotification, l as FlumeLogInput, m as FlumeSlackConnectionResponse, n as FlumeEvent, o as FlumeHandler, p as FlumeRuntimeDeps, r as FlumeGatewayMessage, s as FlumeLog, t as FlumeDiscordSourceOptions, u as FlumeLogLevel, v as FlumeSourceName, w as FlumeStatus, x as FlumeStartErr, y as FlumeSourceOptions } from "./types-Bm9uKUQz.js";
 import { t as FlumeConnectionError } from "./connection-error-BOk97djj.js";
 import { t as FlumeParseError } from "./parse-error-BAiCLRmk.js";
 import { t as FlumeHttpError } from "./http-error-K-Ym4lfK.js";
@@ -7,14 +7,14 @@ import { t as FlumeHttpError } from "./http-error-K-Ym4lfK.js";
 declare function createFlumeDefaultDeps(): FlumeRuntimeDeps;
 //#endregion
 //#region lib/logger.d.ts
-type Props$5 = {
+type Props$4 = {
   source: string;
   handler?: FlumeLogHandler;
   deps: Pick<FlumeRuntimeDeps, "now">;
 };
 declare class FlumeLogger {
   private readonly props;
-  constructor(props: Props$5);
+  constructor(props: Props$4);
   debug(entry: FlumeLogInput): void;
   info(entry: FlumeLogInput): void;
   warn(entry: FlumeLogInput): void;
@@ -26,7 +26,7 @@ declare class FlumeLogger {
 declare function resolveFlumeReconnectConfig(input: boolean | FlumeReconnectOptions | undefined): FlumeReconnectConfig | null;
 //#endregion
 //#region lib/reconnector.d.ts
-type Props$4 = {
+type Props$3 = {
   maxAttempts: number;
   baseDelay: number;
   maxDelay: number;
@@ -37,26 +37,13 @@ declare class FlumeReconnector {
   attempt: number;
   aborted: boolean;
   private timer;
-  constructor(props: Props$4);
+  constructor(props: Props$3);
   schedule(fn: () => void): number;
   reset(): void;
   cancel(): void;
   private nextDelay;
 }
 //#endregion
-//#region lib/schedule-reconnect.d.ts
-type Props$3 = {
-  reconnector: FlumeReconnector | null;
-  log: FlumeLogger;
-  setStatus: (status: FlumeStatus) => void;
-  retry: () => void;
-};
-/**
- * 接続が落ちた際の共通再接続スケジューラ。reconnector の状態を見て次回試行を予約し、
- * 試行回数が尽きていれば disconnected に落とす
- */
-declare function scheduleFlumeReconnect(props: Props$3): void;
-//#endregion
 //#region lib/flume-stopped.d.ts
 type Props$2 = {
   finalStatuses: ReadonlyArray<FlumeSourceStatus>;
@@ -100,7 +87,9 @@ declare class Flume {
   private readonly props;
   private consumed;
   constructor(props: Props);
-  start(handler: FlumeHandler): Promise<FlumeRunning | Error>;
+  start(handler: FlumeHandler): Promise<FlumeStartResult>;
+  private running;
+  runningState(): FlumeRunning | null;
 }
 //#endregion
-export { Flume, FlumeConnectionError, type FlumeDiscordSourceOptions, type FlumeEvent, type FlumeGatewayMessage, type FlumeGitHubNotification, type FlumeGitHubSourceOptions, type FlumeHandler, FlumeHttpError, type FlumeLog, type FlumeLogHandler, type FlumeLogInput, type FlumeLogLevel, FlumeLogger, FlumeParseError, type FlumeReconnectConfig, type FlumeReconnectOptions, FlumeReconnector, FlumeRunning, type FlumeRuntimeDeps, type FlumeSlackConnectionResponse, type FlumeSlackEnvelope, type FlumeSlackSourceOptions, type FlumeSource, type FlumeSourceName, type FlumeSourceOptions, type FlumeSourceStatus, type FlumeStatus, type FlumeStatusHandler, FlumeStopped, type FlumeTimerHandle, createFlumeDefaultDeps, resolveFlumeReconnectConfig, scheduleFlumeReconnect };
+export { Flume, FlumeConnectionError, type FlumeDiscordSourceOptions, type FlumeEvent, type FlumeGatewayMessage, type FlumeGitHubNotification, type FlumeGitHubSourceOptions, type FlumeHandler, FlumeHttpError, type FlumeLog, type FlumeLogHandler, type FlumeLogInput, type FlumeLogLevel, FlumeLogger, FlumeParseError, type FlumeReconnectConfig, type FlumeReconnectOptions, FlumeReconnector, FlumeRunning, type FlumeRuntimeDeps, type FlumeSlackConnectionResponse, type FlumeSlackEnvelope, type FlumeSlackSourceOptions, type FlumeSource, type FlumeSourceName, type FlumeSourceOptions, type FlumeSourceStatus, type FlumeStartErr, type FlumeStartOk, type FlumeStartResult, type FlumeStatus, type FlumeStatusHandler, FlumeStopped, type FlumeTimerHandle, createFlumeDefaultDeps, resolveFlumeReconnectConfig };

package/dist/index.js

@@ -1,5 +1,5 @@
 import { n as createFlumeDefaultDeps, t as FlumeLogger } from "./logger-CpGB9WO_.js";
-import { a as FlumeConnectionError, i as FlumeParseError, n as FlumeReconnector, r as resolveFlumeReconnectConfig, t as scheduleFlumeReconnect } from "./schedule-reconnect-DSxZJG3h.js";
+import { i as FlumeConnectionError, n as resolveFlumeReconnectConfig, r as FlumeParseError, t as FlumeReconnector } from "./reconnector-BDoJ1xNX.js";
 import { t as FlumeHttpError } from "./http-error-BtXonO-W.js";
 //#region lib/flume-stopped.ts
 /**
@@ -63,8 +63,14 @@ var Flume = class {
 		this.props = props;
 	}
 	async start(handler) {
-		if (this.consumed) return /* @__PURE__ */ new Error("Flume.start: already started");
-		if (this.props.signal?.aborted) return /* @__PURE__ */ new Error("Flume.start: signal already aborted");
+		if (this.consumed) return {
+			ok: false,
+			error: /* @__PURE__ */ new Error("Flume.start: already started")
+		};
+		if (this.props.signal?.aborted) return {
+			ok: false,
+			error: /* @__PURE__ */ new Error("Flume.start: signal already aborted")
+		};
 		this.consumed = true;
 		const settled = await Promise.allSettled(this.props.sources.map((source) => source.start(handler)));
 		const failures = [];
@@ -79,26 +85,37 @@ var Flume = class {
 					name: source.name,
 					error: reason instanceof Error ? reason : new Error(String(reason))
 				});
-			} else if (result.value instanceof Error) failures.push({
+			} else if (!result.value.ok) failures.push({
 				name: source.name,
-				error: result.value
+				error: result.value.error
 			});
 			else started.push(source);
 		}
 		if (failures.length > 0) {
 			await Promise.allSettled(started.map((source) => source.stop()));
 			const detail = failures.map((f) => `${f.name}: ${f.error.message}`).join("; ");
-			return /* @__PURE__ */ new Error(`Flume.start: ${failures.length} source(s) failed: ${detail}`);
+			return {
+				ok: false,
+				error: /* @__PURE__ */ new Error(`Flume.start: ${failures.length} source(s) failed: ${detail}`)
+			};
 		}
 		if (this.props.signal?.aborted) {
 			await Promise.allSettled(this.props.sources.map((source) => source.stop()));
-			return /* @__PURE__ */ new Error("Flume.start: aborted during start");
+			return {
+				ok: false,
+				error: /* @__PURE__ */ new Error("Flume.start: aborted during start")
+			};
 		}
-		return new FlumeRunning({
+		this.running = new FlumeRunning({
 			sources: this.props.sources,
 			signal: this.props.signal
 		});
+		return { ok: true };
+	}
+	running = null;
+	runningState() {
+		return this.running;
 	}
 };
 //#endregion
-export { Flume, FlumeConnectionError, FlumeHttpError, FlumeLogger, FlumeParseError, FlumeReconnector, FlumeRunning, FlumeStopped, createFlumeDefaultDeps, resolveFlumeReconnectConfig, scheduleFlumeReconnect };
+export { Flume, FlumeConnectionError, FlumeHttpError, FlumeLogger, FlumeParseError, FlumeReconnector, FlumeRunning, FlumeStopped, createFlumeDefaultDeps, resolveFlumeReconnectConfig };

package/dist/{schedule-reconnect-DSxZJG3h.js → reconnector-BDoJ1xNX.js}

@@ -64,30 +64,4 @@ var FlumeReconnector = class {
 	}
 };
 //#endregion
-//#region lib/schedule-reconnect.ts
-/**
-* 接続が落ちた際の共通再接続スケジューラ。reconnector の状態を見て次回試行を予約し、
-* 試行回数が尽きていれば disconnected に落とす
-*/
-function scheduleFlumeReconnect(props) {
-	if (!props.reconnector || props.reconnector.aborted) {
-		props.setStatus("disconnected");
-		return;
-	}
-	props.setStatus("reconnecting");
-	const delay = props.reconnector.schedule(props.retry);
-	if (delay === -1) {
-		props.log.error({
-			action: "reconnect.exhausted",
-			message: `gave up after ${props.reconnector.attempt} attempts`
-		});
-		props.setStatus("disconnected");
-		return;
-	}
-	props.log.info({
-		action: "reconnect.scheduled",
-		message: `next attempt in ${Math.round(delay)}ms`
-	});
-}
-//#endregion
-export { FlumeConnectionError as a, FlumeParseError as i, FlumeReconnector as n, resolveFlumeReconnectConfig as r, scheduleFlumeReconnect as t };
+export { FlumeConnectionError as i, resolveFlumeReconnectConfig as n, FlumeParseError as r, FlumeReconnector as t };

package/dist/safe-json-parse-BWlzGOLl.js

@@ -0,0 +1,41 @@
+//#region lib/schedule-reconnect.ts
+/**
+* 接続が落ちた際の共通再接続スケジューラ。reconnector の状態を見て次回試行を予約し、
+* 試行回数が尽きていれば disconnected に落とす
+*/
+function scheduleFlumeReconnect(props) {
+	if (!props.reconnector || props.reconnector.aborted) {
+		props.setStatus("disconnected");
+		return;
+	}
+	props.setStatus("reconnecting");
+	const delay = props.reconnector.schedule(props.retry);
+	if (delay === -1) {
+		props.log.error({
+			action: "reconnect.exhausted",
+			message: `gave up after ${props.reconnector.attempt} attempts`
+		});
+		props.setStatus("disconnected");
+		return;
+	}
+	props.log.info({
+		action: "reconnect.scheduled",
+		message: `next attempt in ${Math.round(delay)}ms`
+	});
+}
+//#endregion
+//#region lib/utils/is-record.ts
+function isRecord(value) {
+	return typeof value === "object" && value !== null;
+}
+//#endregion
+//#region lib/utils/safe-json-parse.ts
+function safeJsonParse(raw) {
+	try {
+		return JSON.parse(raw);
+	} catch {
+		return null;
+	}
+}
+//#endregion
+export { isRecord as n, scheduleFlumeReconnect as r, safeJsonParse as t };

package/dist/slack.d.ts

@@ -1,4 +1,4 @@
-import { T as FlumeSlackConnectionResponseSchema, c as FlumeLogHandler, g as FlumeSlackSourceOptions, h as FlumeSlackEnvelope, o as FlumeHandler, p as FlumeRuntimeDeps, w as FlumeSlackEnvelopeSchema, x as FlumeStatus } from "./types-tnOPBc1p.js";
+import { C as FlumeStartResult, D as FlumeSlackEnvelopeSchema, O as FlumeSlackConnectionResponseSchema, c as FlumeLogHandler, g as FlumeSlackSourceOptions, h as FlumeSlackEnvelope, o as FlumeHandler, p as FlumeRuntimeDeps, w as FlumeStatus } from "./types-Bm9uKUQz.js";
 import { t as FlumeConnectionError } from "./connection-error-BOk97djj.js";
 import { t as FlumeHttpError } from "./http-error-K-Ym4lfK.js";
 
@@ -15,7 +15,7 @@ declare class FlumeSlackSource {
   private readonly queue;
   private readonly seen;
   constructor(options: FlumeSlackSourceOptions);
-  start(handler: FlumeHandler): Promise<void | Error>;
+  start(handler: FlumeHandler): Promise<FlumeStartResult>;
   stop(): Promise<void>;
   status(): FlumeStatus;
   private connectInternal;

package/dist/slack.js

@@ -1,8 +1,8 @@
 import { n as createFlumeDefaultDeps, t as FlumeLogger } from "./logger-CpGB9WO_.js";
-import { a as FlumeConnectionError, i as FlumeParseError, n as FlumeReconnector, r as resolveFlumeReconnectConfig, t as scheduleFlumeReconnect } from "./schedule-reconnect-DSxZJG3h.js";
+import { i as FlumeConnectionError, n as resolveFlumeReconnectConfig, r as FlumeParseError, t as FlumeReconnector } from "./reconnector-BDoJ1xNX.js";
 import { t as FlumeHttpError } from "./http-error-BtXonO-W.js";
 import { t as FlumeSerialQueue } from "./serial-queue-ExmlnpzQ.js";
-import { n as isRecord, t as safeJsonParse } from "./safe-json-parse-WCg_x1JS.js";
+import { n as isRecord, r as scheduleFlumeReconnect, t as safeJsonParse } from "./safe-json-parse-BWlzGOLl.js";
 import { t as safeFetch } from "./safe-fetch-30ZzOKHL.js";
 import { z } from "zod/v4";
 //#region lib/slack/extract-slack-meta.ts
@@ -325,14 +325,22 @@ var FlumeSlackSource = class {
 		});
 	}
 	async start(handler) {
-		if (this.options.signal?.aborted) return /* @__PURE__ */ new Error("Slack source: signal already aborted");
+		if (this.options.signal?.aborted) return {
+			ok: false,
+			error: /* @__PURE__ */ new Error("Slack source: signal already aborted")
+		};
 		this.options.signal?.addEventListener("abort", () => this.stop(), { once: true });
 		this.handler = handler;
 		this.log.info({
 			action: "start",
 			message: "starting Slack source"
 		});
-		return this.connectInternal();
+		const result = await this.connectInternal();
+		if (result instanceof Error) return {
+			ok: false,
+			error: result
+		};
+		return { ok: true };
 	}
 	async stop() {
 		this.log.info({
@@ -385,6 +393,7 @@ var FlumeSlackSource = class {
 			}
 			this.scheduleReconnect();
 		}
+		return null;
 	}
 	handleMessage(envelope) {
 		if (this.seen.has(envelope.envelope_id)) {

package/dist/{types-tnOPBc1p.d.ts → types-Bm9uKUQz.d.ts}

@@ -62,9 +62,17 @@ type FlumeEvent = {
   receivedAt: number;
 };
 type FlumeHandler = (event: FlumeEvent) => void | Promise<void>;
+type FlumeStartOk = {
+  ok: true;
+};
+type FlumeStartErr = {
+  ok: false;
+  error: Error;
+};
+type FlumeStartResult = FlumeStartOk | FlumeStartErr;
 type FlumeSource = {
   readonly name: FlumeSourceName;
-  start(handler: FlumeHandler): Promise<void | Error>;
+  start(handler: FlumeHandler): Promise<FlumeStartResult>;
   stop(): Promise<void>;
   status(): FlumeStatus;
 };
@@ -114,7 +122,14 @@ type FlumeDiscordSourceOptions = FlumeSourceOptions & {
 };
 type FlumeSlackSourceOptions = FlumeSourceOptions & {
   appToken: string;
-  botToken?: string;
+  /**
+   * Bot token (`xoxb-`). Required — used by the host (e.g. funnel) to call
+   * `auth.test` for self-detection and to post replies. Flume's Socket Mode
+   * transport only needs `appToken` to open the socket, but every realistic
+   * consumer needs the bot token too, so the type forces it to be present
+   * rather than leaving it optional and failing at runtime.
+   */
+  botToken: string;
 };
 type FlumeGitHubSourceOptions = FlumeSourceOptions & {
   token: string;
@@ -125,4 +140,4 @@ type FlumeSlackEnvelope = z.infer<typeof FlumeSlackEnvelopeSchema>;
 type FlumeSlackConnectionResponse = z.infer<typeof FlumeSlackConnectionResponseSchema>;
 type FlumeGitHubNotification = z.infer<typeof FlumeGitHubNotificationSchema>;
 //#endregion
-export { FlumeTimerHandle as C, FlumeGatewayMessageSchema as D, FlumeGitHubNotificationSchema as E, FlumeStatusHandler as S, FlumeSlackConnectionResponseSchema as T, FlumeSource as _, FlumeGitHubSourceOptions as a, FlumeSourceStatus as b, FlumeLogHandler as c, FlumeReconnectConfig as d, FlumeReconnectOptions as f, FlumeSlackSourceOptions as g, FlumeSlackEnvelope as h, FlumeGitHubNotification as i, FlumeLogInput as l, FlumeSlackConnectionResponse as m, FlumeEvent as n, FlumeHandler as o, FlumeRuntimeDeps as p, FlumeGatewayMessage as r, FlumeLog as s, FlumeDiscordSourceOptions as t, FlumeLogLevel as u, FlumeSourceName as v, FlumeSlackEnvelopeSchema as w, FlumeStatus as x, FlumeSourceOptions as y };
+export { FlumeGatewayMessageSchema as A, FlumeStartResult as C, FlumeSlackEnvelopeSchema as D, FlumeTimerHandle as E, FlumeSlackConnectionResponseSchema as O, FlumeStartOk as S, FlumeStatusHandler as T, FlumeSource as _, FlumeGitHubSourceOptions as a, FlumeSourceStatus as b, FlumeLogHandler as c, FlumeReconnectConfig as d, FlumeReconnectOptions as f, FlumeSlackSourceOptions as g, FlumeSlackEnvelope as h, FlumeGitHubNotification as i, FlumeGitHubNotificationSchema as k, FlumeLogInput as l, FlumeSlackConnectionResponse as m, FlumeEvent as n, FlumeHandler as o, FlumeRuntimeDeps as p, FlumeGatewayMessage as r, FlumeLog as s, FlumeDiscordSourceOptions as t, FlumeLogLevel as u, FlumeSourceName as v, FlumeStatus as w, FlumeStartErr as x, FlumeSourceOptions as y };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@interactive-inc/flume",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Unified notification listener for Discord, Slack, and GitHub. Raw WebSocket + fetch + Zod. No SDK dependencies.",
   "keywords": [
     "discord",

package/dist/safe-json-parse-WCg_x1JS.js

@@ -1,15 +0,0 @@
-//#region lib/utils/is-record.ts
-function isRecord(value) {
-	return typeof value === "object" && value !== null;
-}
-//#endregion
-//#region lib/utils/safe-json-parse.ts
-function safeJsonParse(raw) {
-	try {
-		return JSON.parse(raw);
-	} catch {
-		return null;
-	}
-}
-//#endregion
-export { isRecord as n, safeJsonParse as t };