@interactive-inc/flume 0.1.0

package/dist/logger-B9E8zvgj.js

@@ -0,0 +1,69 @@
+import { z } from "zod/v4";
+//#region lib/schema.ts
+const FlumeGatewayMessageSchema = z.object({
+	op: z.number(),
+	d: z.record(z.string(), z.unknown()).nullable(),
+	s: z.number().nullable(),
+	t: z.string().nullable()
+});
+const FlumeSlackEnvelopeSchema = z.object({
+	envelope_id: z.string(),
+	type: z.string(),
+	payload: z.record(z.string(), z.unknown()),
+	accepts_response_payload: z.boolean().optional(),
+	retry_attempt: z.number().optional(),
+	retry_reason: z.string().optional()
+});
+const FlumeSlackConnectionResponseSchema = z.object({
+	ok: z.boolean(),
+	url: z.string().optional(),
+	error: z.string().optional()
+});
+const FlumeGitHubNotificationSchema = z.object({
+	id: z.string(),
+	reason: z.string(),
+	unread: z.boolean(),
+	updated_at: z.string(),
+	subject: z.object({
+		title: z.string(),
+		url: z.string().nullable(),
+		type: z.string()
+	}),
+	repository: z.object({ full_name: z.string() })
+});
+//#endregion
+//#region lib/logger.ts
+var FlumeLogger = class {
+	props;
+	constructor(props) {
+		this.props = props;
+		Object.freeze(this);
+	}
+	debug(entry) {
+		this.emit("debug", entry);
+	}
+	info(entry) {
+		this.emit("info", entry);
+	}
+	warn(entry) {
+		this.emit("warn", entry);
+	}
+	error(entry) {
+		this.emit("error", entry);
+	}
+	emit(level, input) {
+		if (!this.props.handler) return;
+		const log = {
+			level,
+			source: this.props.source,
+			action: input.action,
+			message: input.message,
+			timestamp: this.props.deps.now(),
+			error: input.error,
+			detail: input.detail
+		};
+		this.props.handler(log);
+	}
+};
+//#endregion
+export { FlumeSlackEnvelopeSchema as a, FlumeSlackConnectionResponseSchema as i, FlumeGatewayMessageSchema as n, FlumeGitHubNotificationSchema as r, FlumeLogger as t };

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

@@ -0,0 +1,81 @@
+//#region lib/errors/connection-error.ts
+var FlumeConnectionError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "FlumeConnectionError";
+		Object.freeze(this);
+	}
+};
+//#endregion
+//#region lib/errors/parse-error.ts
+var FlumeParseError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "FlumeParseError";
+		Object.freeze(this);
+	}
+};
+//#endregion
+//#region lib/reconnect-config.ts
+const DEFAULTS = {
+	maxAttempts: Infinity,
+	baseDelay: 1e3,
+	maxDelay: 3e4
+};
+function resolveFlumeReconnectConfig(input) {
+	if (input === false || input === void 0) return null;
+	if (input === true) return { ...DEFAULTS };
+	return {
+		...DEFAULTS,
+		...input
+	};
+}
+//#endregion
+//#region lib/reconnector.ts
+var FlumeReconnector = class {
+	props;
+	attempt = 0;
+	aborted = false;
+	timer = null;
+	constructor(props) {
+		this.props = props;
+	}
+	schedule(fn) {
+		if (this.aborted) return 0;
+		if (this.attempt >= this.props.maxAttempts) return -1;
+		const delay = this.nextDelay();
+		this.timer = this.props.deps.setTimeout(fn, delay);
+		return delay;
+	}
+	reset() {
+		this.attempt = 0;
+	}
+	cancel() {
+		this.aborted = true;
+		if (this.timer !== null) {
+			this.props.deps.clearTimeout(this.timer);
+			this.timer = null;
+		}
+	}
+	nextDelay() {
+		const jitter = Math.min(this.props.baseDelay * 2 ** this.attempt, this.props.maxDelay) * (.5 + this.props.deps.random() * .5);
+		this.attempt++;
+		return jitter;
+	}
+};
+//#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 { FlumeParseError as a, resolveFlumeReconnectConfig as i, isRecord as n, FlumeConnectionError as o, FlumeReconnector as r, safeJsonParse as t };

package/dist/slack-source-CszepStG.js

@@ -0,0 +1,400 @@
+import { a as FlumeSlackEnvelopeSchema, i as FlumeSlackConnectionResponseSchema, t as FlumeLogger } from "./logger-B9E8zvgj.js";
+import { a as FlumeParseError, i as resolveFlumeReconnectConfig, n as isRecord, o as FlumeConnectionError, r as FlumeReconnector, t as safeJsonParse } from "./safe-json-parse-D8t_4Vm_.js";
+//#region lib/errors/http-error.ts
+var FlumeHttpError = class extends Error {
+	status;
+	constructor(props) {
+		super(props.message);
+		this.name = "FlumeHttpError";
+		this.status = props.status;
+		Object.freeze(this);
+	}
+};
+//#endregion
+//#region lib/slack/obtain-slack-url.ts
+async function obtainSlackUrl(props) {
+	const log = new FlumeLogger({
+		source: "slack.url",
+		handler: props.onLog,
+		deps: props.deps
+	});
+	const url = "https://slack.com/api/apps.connections.open";
+	log.debug({
+		action: "http.request",
+		message: `POST ${url}`
+	});
+	const response = await safeFetch(props, url, log);
+	if (response instanceof FlumeHttpError) return response;
+	log.debug({
+		action: "http.response",
+		message: `POST ${response.status}`,
+		detail: {
+			status: response.status,
+			url
+		}
+	});
+	const raw = await response.json();
+	log.debug({
+		action: "http.body",
+		message: "apps.connections.open response",
+		detail: {
+			ok: isOk(raw),
+			error: errorField(raw)
+		}
+	});
+	const parsed = FlumeSlackConnectionResponseSchema.safeParse(raw);
+	if (!parsed.success) {
+		log.warn({
+			action: "parse.fail",
+			message: "apps.connections.open: invalid response shape",
+			detail: { issues: parsed.error.issues.map((i) => ({
+				path: i.path,
+				message: i.message
+			})) }
+		});
+		return new FlumeHttpError({
+			message: "apps.connections.open: invalid response shape",
+			status: response.status
+		});
+	}
+	if (!parsed.data.ok || !parsed.data.url) {
+		log.warn({
+			action: "api.fail",
+			message: `apps.connections.open failed: ${parsed.data.error ?? "no url"}`
+		});
+		return new FlumeHttpError({
+			message: `apps.connections.open failed: ${parsed.data.error ?? "no url"}`,
+			status: response.status
+		});
+	}
+	log.info({
+		action: "url.obtained",
+		message: "WSS URL obtained"
+	});
+	return parsed.data.url;
+}
+function isOk(raw) {
+	return raw?.ok;
+}
+function errorField(raw) {
+	return raw?.error;
+}
+async function safeFetch(props, url, log) {
+	try {
+		return await props.deps.fetch(url, {
+			method: "POST",
+			headers: { Authorization: `Bearer ${props.appToken}` }
+		});
+	} catch (error) {
+		const err = error instanceof Error ? error : new Error(String(error));
+		log.error({
+			action: "http.error",
+			message: `network error: ${err.message}`,
+			error: err
+		});
+		return new FlumeHttpError({
+			message: err.message,
+			status: 0
+		});
+	}
+}
+//#endregion
+//#region lib/slack/slack-socket-mode.ts
+function framePreview(raw) {
+	return raw.length > 200 ? `${raw.slice(0, 200)}... (${raw.length} bytes)` : raw;
+}
+var FlumeSlackSocketMode = class {
+	props;
+	log;
+	ws = null;
+	stopped = false;
+	pendingResolve = null;
+	pendingResolved = false;
+	constructor(props) {
+		this.props = props;
+		this.log = new FlumeLogger({
+			source: "slack.socket-mode",
+			handler: props.onLog,
+			deps: props.deps
+		});
+	}
+	async connect() {
+		this.log.info({
+			action: "connect.start",
+			message: "opening WebSocket connection"
+		});
+		const url = await obtainSlackUrl({
+			appToken: this.props.appToken,
+			onLog: this.props.onLog,
+			deps: this.props.deps
+		});
+		if (url instanceof FlumeHttpError) {
+			this.log.error({
+				action: "http.error",
+				message: url.message,
+				error: url
+			});
+			return url;
+		}
+		this.log.info({
+			action: "url.obtained",
+			message: "WebSocket URL obtained"
+		});
+		return this.openSocket(url);
+	}
+	disconnect() {
+		this.log.info({
+			action: "disconnect",
+			message: "stopping socket mode"
+		});
+		this.stopped = true;
+		if (this.ws) {
+			this.ws.close();
+			this.ws = null;
+		}
+	}
+	isConnected() {
+		return this.ws !== null && this.ws.readyState === WebSocket.OPEN;
+	}
+	openSocket(url) {
+		this.pendingResolved = false;
+		return new Promise((resolve) => {
+			this.pendingResolve = resolve;
+			const socket = new this.props.deps.WebSocket(url);
+			this.ws = socket;
+			socket.addEventListener("message", (ev) => this.onMessage(String(ev.data), socket));
+			socket.addEventListener("close", (ev) => this.onClose(ev));
+			socket.addEventListener("error", () => this.onError());
+		});
+	}
+	completeConnect(error) {
+		if (this.pendingResolved || !this.pendingResolve) return;
+		this.pendingResolved = true;
+		this.pendingResolve(error);
+	}
+	onMessage(raw, socket) {
+		this.log.debug({
+			action: "ws.recv",
+			message: framePreview(raw)
+		});
+		const json = safeJsonParse(raw);
+		if (!isRecord(json)) {
+			this.log.error({
+				action: "ws.parse-error",
+				message: "invalid JSON",
+				error: new FlumeParseError(raw.slice(0, 200))
+			});
+			return;
+		}
+		if (json.type === "hello") {
+			this.log.info({
+				action: "ws.hello",
+				message: "connection ready"
+			});
+			this.props.onConnected();
+			this.completeConnect(null);
+			return;
+		}
+		if (json.type === "disconnect") {
+			const reason = typeof json.reason === "string" ? json.reason : "unknown";
+			this.log.info({
+				action: "ws.disconnect-requested",
+				message: `reason=${reason}`,
+				detail: { reason }
+			});
+			socket.close();
+			return;
+		}
+		if (typeof json.envelope_id === "string") {
+			this.log.debug({
+				action: "ws.ack",
+				message: `envelope_id=${json.envelope_id}`
+			});
+			const ack = JSON.stringify({ envelope_id: json.envelope_id });
+			socket.send(ack);
+			this.log.debug({
+				action: "ws.send",
+				message: framePreview(ack)
+			});
+		}
+		const envelope = FlumeSlackEnvelopeSchema.safeParse(json);
+		if (envelope.success) {
+			this.log.debug({
+				action: "envelope.recv",
+				message: `type=${envelope.data.type} envelope_id=${envelope.data.envelope_id}`,
+				detail: {
+					type: envelope.data.type,
+					envelopeId: envelope.data.envelope_id
+				}
+			});
+			this.props.onMessage(envelope.data);
+			return;
+		}
+		this.log.warn({
+			action: "envelope.parse-fail",
+			message: "unrecognised envelope shape, dropping",
+			detail: {
+				type: typeof json.type === "string" ? json.type : "unknown",
+				issues: envelope.error.issues.map((i) => ({
+					path: i.path,
+					message: i.message
+				}))
+			}
+		});
+	}
+	onClose(ev) {
+		this.log.info({
+			action: "ws.close",
+			message: `code=${ev.code} reason=${ev.reason || "none"}`
+		});
+		this.ws = null;
+		this.props.onDisconnected();
+		this.completeConnect(new FlumeConnectionError(`WebSocket closed before hello (code=${ev.code})`));
+	}
+	onError() {
+		this.log.error({
+			action: "ws.error",
+			message: "WebSocket error event"
+		});
+		this.completeConnect(new FlumeConnectionError("WebSocket connection error"));
+	}
+};
+//#endregion
+//#region lib/slack/slack-source.ts
+var FlumeSlackSource = class FlumeSlackSource {
+	options;
+	socket = null;
+	reconnector = null;
+	handler = null;
+	currentStatus = "disconnected";
+	log;
+	deps;
+	constructor(options) {
+		this.options = options;
+		this.deps = options.deps;
+		this.log = new FlumeLogger({
+			source: "slack",
+			handler: options.onLog,
+			deps: this.deps
+		});
+		const rc = resolveFlumeReconnectConfig(options.reconnect);
+		if (rc) this.reconnector = new FlumeReconnector({
+			...rc,
+			deps: this.deps
+		});
+	}
+	async start(handler) {
+		if (this.options.signal?.aborted) return;
+		this.options.signal?.addEventListener("abort", () => this.stop(), { once: true });
+		this.handler = handler;
+		this.log.info({
+			action: "start",
+			message: "starting Slack source"
+		});
+		await this.connectInternal();
+	}
+	async stop() {
+		this.log.info({
+			action: "stop",
+			message: "stopping Slack source"
+		});
+		if (this.reconnector && !this.reconnector.aborted) this.log.debug({
+			action: "reconnect.cancel",
+			message: "aborting reconnector"
+		});
+		this.reconnector?.cancel();
+		this.socket?.disconnect();
+		this.socket = null;
+		this.handler = null;
+		this.setStatus("disconnected");
+	}
+	status() {
+		return this.currentStatus;
+	}
+	async connectInternal() {
+		this.setStatus("connecting");
+		this.socket = new FlumeSlackSocketMode({
+			appToken: this.options.appToken,
+			onLog: this.options.onLog,
+			deps: this.deps,
+			onMessage: (envelope) => this.handleMessage(envelope),
+			onConnected: () => {
+				if (this.reconnector && this.reconnector.attempt > 0) this.log.info({
+					action: "reconnect.reset",
+					message: `cleared ${this.reconnector.attempt} attempts`
+				});
+				this.reconnector?.reset();
+				this.setStatus("connected");
+			},
+			onDisconnected: () => {
+				if (!this.socket?.stopped) this.scheduleReconnect();
+			}
+		});
+		const error = await this.socket.connect();
+		if (error instanceof Error) {
+			this.log.error({
+				action: "connect.failed",
+				message: error.message,
+				error
+			});
+			this.scheduleReconnect();
+		}
+	}
+	handleMessage(envelope) {
+		const event = {
+			source: "slack",
+			type: envelope.type,
+			data: envelope.payload,
+			meta: FlumeSlackSource.extractMeta(envelope),
+			receivedAt: this.deps.now()
+		};
+		try {
+			this.handler?.(event);
+		} catch (err) {
+			this.log.error({
+				action: "handler.error",
+				message: "user handler threw",
+				error: err instanceof Error ? err : new Error(String(err))
+			});
+		}
+	}
+	scheduleReconnect() {
+		if (!this.reconnector || this.reconnector.aborted) {
+			this.setStatus("disconnected");
+			return;
+		}
+		this.setStatus("reconnecting");
+		const delay = this.reconnector.schedule(() => this.connectInternal());
+		if (delay === -1) {
+			this.log.error({
+				action: "reconnect.exhausted",
+				message: `gave up after ${this.reconnector.attempt} attempts`
+			});
+			this.setStatus("disconnected");
+		} else this.log.info({
+			action: "reconnect.scheduled",
+			message: `next attempt in ${Math.round(delay)}ms`
+		});
+	}
+	setStatus(next) {
+		if (this.currentStatus === next) return;
+		this.log.info({
+			action: "status",
+			message: `${this.currentStatus} → ${next}`
+		});
+		this.currentStatus = next;
+		this.options.onStatus?.(next);
+	}
+	static extractMeta(envelope) {
+		const meta = { event_type: envelope.type };
+		const eventPayload = isRecord(envelope.payload.event) ? envelope.payload.event : null;
+		if (!eventPayload) return meta;
+		if (typeof eventPayload.channel === "string") meta.channel_id = eventPayload.channel;
+		if (typeof eventPayload.user === "string") meta.user_id = eventPayload.user;
+		if (typeof eventPayload.thread_ts === "string") meta.thread_ts = eventPayload.thread_ts;
+		if (typeof eventPayload.type === "string") meta.slack_event_type = eventPayload.type;
+		return meta;
+	}
+};
+//#endregion
+export { FlumeHttpError as i, FlumeSlackSocketMode as n, obtainSlackUrl as r, FlumeSlackSource as t };

package/dist/slack.d.ts

@@ -0,0 +1,23 @@
+import { g as FlumeSlackSourceOptions, h as FlumeSlackEnvelope, o as FlumeHandler, y as FlumeStatus } from "./types-BVQSU336.js";
+
+//#region lib/slack/slack-source.d.ts
+declare class FlumeSlackSource {
+  private readonly options;
+  private socket;
+  private reconnector;
+  private handler;
+  private currentStatus;
+  private readonly log;
+  private readonly deps;
+  constructor(options: FlumeSlackSourceOptions);
+  start(handler: FlumeHandler): Promise<void>;
+  stop(): Promise<void>;
+  status(): FlumeStatus;
+  private connectInternal;
+  private handleMessage;
+  private scheduleReconnect;
+  private setStatus;
+  static extractMeta(envelope: FlumeSlackEnvelope): Record<string, string>;
+}
+//#endregion
+export { FlumeSlackSource };

package/dist/slack.js

@@ -0,0 +1,2 @@
+import { t as FlumeSlackSource } from "./slack-source-CszepStG.js";
+export { FlumeSlackSource };

package/dist/types-BVQSU336.d.ts

@@ -0,0 +1,112 @@
+import { z } from "zod/v4";
+
+//#region lib/schema.d.ts
+declare const FlumeGatewayMessageSchema: z.ZodObject<{
+  op: z.ZodNumber;
+  d: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+  s: z.ZodNullable<z.ZodNumber>;
+  t: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+declare const FlumeSlackEnvelopeSchema: z.ZodObject<{
+  envelope_id: z.ZodString;
+  type: z.ZodString;
+  payload: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+  accepts_response_payload: z.ZodOptional<z.ZodBoolean>;
+  retry_attempt: z.ZodOptional<z.ZodNumber>;
+  retry_reason: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+declare const FlumeSlackConnectionResponseSchema: z.ZodObject<{
+  ok: z.ZodBoolean;
+  url: z.ZodOptional<z.ZodString>;
+  error: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+declare const FlumeGitHubNotificationSchema: z.ZodObject<{
+  id: z.ZodString;
+  reason: z.ZodString;
+  unread: z.ZodBoolean;
+  updated_at: z.ZodString;
+  subject: z.ZodObject<{
+    title: z.ZodString;
+    url: z.ZodNullable<z.ZodString>;
+    type: z.ZodString;
+  }, z.core.$strip>;
+  repository: z.ZodObject<{
+    full_name: z.ZodString;
+  }, z.core.$strip>;
+}, z.core.$strip>;
+//#endregion
+//#region lib/types.d.ts
+type FlumeTimerHandle = ReturnType<typeof setTimeout>;
+type FlumeRuntimeDeps = {
+  fetch(url: string | URL, init?: RequestInit): Promise<Response>;
+  WebSocket: new (url: string | URL) => WebSocket;
+  now(): number;
+  random(): number;
+  setTimeout(fn: () => void, ms: number): FlumeTimerHandle;
+  clearTimeout(id: FlumeTimerHandle): void;
+  setInterval(fn: () => void, ms: number): FlumeTimerHandle;
+  clearInterval(id: FlumeTimerHandle): void;
+};
+type FlumeSourceName = "discord" | "slack" | "github";
+type FlumeEvent = {
+  source: FlumeSourceName;
+  type: string;
+  data: unknown;
+  meta: Record<string, string>;
+  receivedAt: number;
+};
+type FlumeHandler = (event: FlumeEvent) => void | Promise<void>;
+type FlumeStatus = "disconnected" | "connecting" | "connected" | "reconnecting";
+type FlumeStatusHandler = (status: FlumeStatus, detail?: string) => void;
+type FlumeLogLevel = "debug" | "info" | "warn" | "error";
+type FlumeLog = {
+  level: FlumeLogLevel;
+  source: string;
+  action: string;
+  message: string;
+  error?: Error;
+  detail?: Record<string, unknown>;
+  timestamp: number;
+};
+type FlumeLogHandler = (log: FlumeLog) => void;
+type FlumeLogInput = {
+  action: string;
+  message: string;
+  error?: Error;
+  detail?: Record<string, unknown>;
+};
+type FlumeReconnectOptions = {
+  maxAttempts?: number;
+  baseDelay?: number;
+  maxDelay?: number;
+};
+type FlumeReconnectConfig = {
+  maxAttempts: number;
+  baseDelay: number;
+  maxDelay: number;
+};
+type FlumeSourceOptions = {
+  reconnect?: boolean | FlumeReconnectOptions;
+  onStatus?: FlumeStatusHandler;
+  onLog?: FlumeLogHandler;
+  signal?: AbortSignal;
+  deps: FlumeRuntimeDeps;
+};
+type FlumeDiscordSourceOptions = FlumeSourceOptions & {
+  token: string;
+  intents?: number;
+};
+type FlumeSlackSourceOptions = FlumeSourceOptions & {
+  appToken: string;
+  botToken?: string;
+};
+type FlumeGitHubSourceOptions = FlumeSourceOptions & {
+  token: string;
+  pollInterval?: number;
+};
+type FlumeGatewayMessage = z.infer<typeof FlumeGatewayMessageSchema>;
+type FlumeSlackEnvelope = z.infer<typeof FlumeSlackEnvelopeSchema>;
+type FlumeSlackConnectionResponse = z.infer<typeof FlumeSlackConnectionResponseSchema>;
+type FlumeGitHubNotification = z.infer<typeof FlumeGitHubNotificationSchema>;
+//#endregion
+export { FlumeGitHubNotificationSchema as C, FlumeGatewayMessageSchema as S, FlumeSlackEnvelopeSchema as T, FlumeSourceName as _, FlumeGitHubSourceOptions as a, FlumeStatusHandler 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, FlumeSourceOptions as v, FlumeSlackConnectionResponseSchema as w, FlumeTimerHandle as x, FlumeStatus as y };