@interactive-inc/flume 0.4.0 → 0.6.0

package/dist/flume-source-DUvt9aJt.js

@@ -0,0 +1,341 @@
+//#region lib/utils/safe-error-message.ts
+/**
+* 任意の値から人が読めるメッセージ文字列を取り出す。
+* `Error.message` getter / `Symbol.toPrimitive` / `toString` / `valueOf` が throw しても固定文字列に fallback。
+* 自身は決して throw しない
+*/
+function safeErrorMessage(props) {
+	if (props.error instanceof Error) try {
+		const message = props.error.message;
+		if (typeof message === "string") return message;
+		return "<non-string error message>";
+	} catch {
+		return "<unreadable error message>";
+	}
+	try {
+		return String(props.error);
+	} catch {
+		return "<unprintable error>";
+	}
+}
+//#endregion
+//#region lib/utils/safe-normalize-error.ts
+/**
+* 任意の値を `Error` インスタンスへ正規化する。すでに Error ならそのまま返し、
+* それ以外は `safeErrorMessage` で安全な文字列化を経由して new Error する。
+* Error コンストラクタ自体が throw する病的環境でも fallback を返し、決して throw しない
+*/
+function safeNormalizeError(props) {
+	if (props.value instanceof Error) return props.value;
+	const message = safeErrorMessage({ error: props.value });
+	try {
+		return new Error(message);
+	} catch {
+		try {
+			return /* @__PURE__ */ new Error("unknown error");
+		} catch {
+			const fallback = Object.create(Error.prototype);
+			fallback.name = "Error";
+			fallback.message = "unknown error";
+			return fallback;
+		}
+	}
+}
+//#endregion
+//#region lib/utils/attempt.ts
+function attempt(fn) {
+	try {
+		const result = fn();
+		if (result instanceof Promise) return result.catch((err) => safeNormalizeError({ value: err }));
+		return result;
+	} catch (err) {
+		return safeNormalizeError({ value: err });
+	}
+}
+//#endregion
+//#region lib/errors/parse-error.ts
+var FlumeParseError = class extends Error {
+	constructor(message, options) {
+		super(message, options?.cause === void 0 ? void 0 : { cause: options.cause });
+		this.name = "FlumeParseError";
+		Object.freeze(this);
+	}
+};
+//#endregion
+//#region lib/errors/start-error.ts
+var FlumeStartError = class extends Error {
+	constructor(message, options) {
+		super(message, options?.cause === void 0 ? void 0 : { cause: options.cause });
+		this.name = "FlumeStartError";
+		Object.freeze(this);
+	}
+};
+//#endregion
+//#region lib/utils/safe-now.ts
+/**
+* `deps.now()` を保護する。throw / 非数値が返った場合は 0 を返す。
+* IO 境界のため呼び出し側はこの戻り値を信頼できる
+*/
+function safeNow(props) {
+	try {
+		const value = props.deps.now();
+		if (typeof value !== "number" || !Number.isFinite(value)) return 0;
+		return value;
+	} catch {
+		return 0;
+	}
+}
+//#endregion
+//#region lib/logger.ts
+/**
+* 構造化ログを onLog に流す。handler が throw / reject してもループは継続する
+*/
+var FlumeLogger = class FlumeLogger {
+	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);
+	}
+	get handler() {
+		return this.props.handler;
+	}
+	child(source) {
+		return new FlumeLogger({
+			source,
+			handler: this.props.handler,
+			deps: this.props.deps
+		});
+	}
+	emit(level, input) {
+		const handler = this.props.handler;
+		if (!handler) return;
+		const log = {
+			level,
+			source: this.props.source,
+			action: input.action,
+			message: input.message,
+			timestamp: safeNow({ deps: this.props.deps }),
+			error: input.error,
+			detail: input.detail
+		};
+		try {
+			Promise.resolve(handler(log)).catch(() => {});
+		} catch {}
+	}
+};
+//#endregion
+//#region lib/utils/safe-invoke-callback.ts
+/**
+* fire-and-forget でユーザーコールバックを呼び出す。sync throw と async reject のどちらも
+* `onError(Error)` に正規化して通知。`onError` 自身が throw しても外に漏らさない。
+* 戻り値を持たない fire-and-forget 専用のため log/出力先には依存しない (caller が onError で決める)
+*/
+function safeInvokeCallback(props) {
+	try {
+		Promise.resolve(props.fn()).catch((err) => {
+			try {
+				props.onError(safeNormalizeError({ value: err }));
+			} catch {}
+		}).catch(() => {});
+	} catch (err) {
+		try {
+			props.onError(safeNormalizeError({ value: err }));
+		} catch {}
+	}
+}
+//#endregion
+//#region lib/source-helpers/flume-status-emitter.ts
+/**
+* Source の `currentStatus` と `onStatus` 通知を集約する。
+* 同一 (status, detail) の連続遷移は冪等に握り潰し、ユーザーコールバックは `safeInvokeCallback`
+* 経由で例外を隔離する
+*/
+var FlumeStatusEmitter = class {
+	props;
+	currentStatus = "disconnected";
+	currentDetail = null;
+	constructor(props) {
+		this.props = props;
+	}
+	get value() {
+		return this.currentStatus;
+	}
+	set(next, detail) {
+		const normalizedDetail = detail ?? null;
+		if (this.currentStatus === next && this.currentDetail === normalizedDetail) return;
+		const prev = this.currentStatus;
+		const suffix = detail ? ` (${detail})` : "";
+		this.props.log.info({
+			action: "status",
+			message: `${prev} → ${next}${suffix}`,
+			detail: {
+				from: prev,
+				to: next,
+				reason: normalizedDetail
+			}
+		});
+		this.currentStatus = next;
+		this.currentDetail = normalizedDetail;
+		const onStatus = this.props.onStatus;
+		if (!onStatus) return;
+		safeInvokeCallback({
+			fn: detail !== void 0 ? () => onStatus(next, detail) : () => onStatus(next),
+			onError: (error) => {
+				this.props.log.error({
+					action: "onStatus.error",
+					message: safeErrorMessage({ error }),
+					error
+				});
+			}
+		});
+	}
+};
+//#endregion
+//#region lib/utils/serial-queue.ts
+/**
+* 投入順を保ったまま task を直列実行する。各 task は前の完了を待ってから走る。
+* task が throw しても後続には伝播しない (キュー自体は止まらない)。
+* maxDepth を超えた場合は新規 task を drop し onOverflow に通知。
+* cancel() 後の add() は no-op となり drain() は即時 resolve する
+*/
+var FlumeSerialQueue = class {
+	props;
+	chain = Promise.resolve();
+	depth = 0;
+	cancelled = false;
+	constructor(props = {}) {
+		this.props = props;
+	}
+	add(task) {
+		if (this.cancelled) return;
+		if (this.props.maxDepth !== void 0 && this.depth >= this.props.maxDepth) {
+			this.props.onOverflow?.({
+				dropped: 1,
+				depth: this.depth
+			});
+			return;
+		}
+		this.depth++;
+		this.chain = this.chain.then(async () => {
+			try {
+				await task();
+			} catch {} finally {
+				this.depth--;
+			}
+		});
+	}
+	async drain() {
+		await this.chain;
+	}
+	cancel() {
+		this.cancelled = true;
+		this.depth = 0;
+		this.chain = Promise.resolve();
+	}
+	size() {
+		return this.depth;
+	}
+	isCancelled() {
+		return this.cancelled;
+	}
+};
+//#endregion
+//#region lib/flume-source.ts
+/**
+* 全 Source の基底クラス。protocol 固有のロジック (`connect` / `disconnect`) のみ
+* subclass に実装させ、queue / status / handler 安全呼び出しといった共通の
+* cross-cutting concern は base が引き受ける。Flume 側で全 source に注入される
+* `FlumeSourceStartContext` (handler / log / deps / onStatus / reconnect) を
+* `start()` で受け取り、subclass の `connect(ctx)` に手渡す。
+*
+* subclass のテンプレート:
+*
+* ```ts
+* export class MySource extends FlumeSource {
+*   readonly name = "my-source"
+*
+*   constructor(private readonly options: { apiKey: string }) {
+*     super()
+*   }
+*
+*   protected async connect(ctx: FlumeSourceStartContext): Promise<Error | null> {
+*     // 接続して onEvent で this.emit({...}) / 状態遷移で this.setStatus(...)
+*     return null
+*   }
+*
+*   protected disconnect(): void { ... }
+* }
+* ```
+*/
+var FlumeSource = class {
+	consumed = false;
+	stopped = false;
+	ctx = null;
+	statusEmitter = null;
+	queue = new FlumeSerialQueue();
+	async start(ctx) {
+		if (this.consumed) return new FlumeStartError(`${this.name}: already started`);
+		this.consumed = true;
+		this.ctx = ctx;
+		this.statusEmitter = new FlumeStatusEmitter({
+			log: ctx.log,
+			onStatus: ctx.onStatus
+		});
+		return await this.connect(ctx);
+	}
+	async stop() {
+		if (this.stopped) return;
+		this.stopped = true;
+		await this.disconnect();
+		await this.queue.drain();
+		this.statusEmitter?.set("disconnected");
+		this.ctx = null;
+	}
+	status() {
+		return this.statusEmitter?.value ?? "disconnected";
+	}
+	/**
+	* subclass が受信した protocol イベントを `FlumeEvent` として handler へ流す。
+	* handler の throw / async reject は queue 内で catch + log し、後続を止めない
+	*/
+	emit(event) {
+		const ctx = this.ctx;
+		if (!ctx) return;
+		this.queue.add(async () => {
+			const result = await attempt(() => Promise.resolve(ctx.onEvent(event)));
+			if (result instanceof Error) ctx.log.error({
+				action: "onEvent.error",
+				message: safeErrorMessage({ error: result }),
+				error: result
+			});
+		});
+	}
+	/**
+	* subclass が protocol 状態遷移をユーザーに通知する。同一 (status, detail) の連続は冪等
+	*/
+	setStatus(status, detail) {
+		this.statusEmitter?.set(status, detail);
+	}
+	/** subclass が現在の status を読みたい場合 */
+	get currentStatus() {
+		return this.statusEmitter?.value ?? "disconnected";
+	}
+	/** subclass が start ctx を再参照したい場合 (stop 後は null) */
+	get context() {
+		return this.ctx;
+	}
+};
+//#endregion
+export { FlumeStartError as a, safeNormalizeError as c, safeNow as i, safeErrorMessage as l, safeInvokeCallback as n, FlumeParseError as o, FlumeLogger as r, attempt as s, FlumeSource as t };

package/dist/flume-source-DuUFPhSe.d.ts

@@ -0,0 +1,228 @@
+import { z } from "zod/v4";
+
+//#region lib/logger.d.ts
+type Props = {
+  source: string;
+  handler?: FlumeLogHandler;
+  deps: Pick<FlumeRuntimeDeps, "now">;
+};
+/**
+ * 構造化ログを onLog に流す。handler が throw / reject してもループは継続する
+ */
+declare class FlumeLogger {
+  private readonly props;
+  constructor(props: Props);
+  debug(entry: FlumeLogInput): void;
+  info(entry: FlumeLogInput): void;
+  warn(entry: FlumeLogInput): void;
+  error(entry: FlumeLogInput): void;
+  get handler(): FlumeLogHandler | undefined;
+  child(source: string): FlumeLogger;
+  private emit;
+}
+//#endregion
+//#region lib/discord/discord-gateway-message-schema.d.ts
+declare const FlumeGatewayMessageSchema: z.ZodObject<{
+  op: z.ZodNumber;
+  d: z.ZodUnknown;
+  s: z.ZodNullable<z.ZodNumber>;
+  t: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+//#endregion
+//#region lib/github/github-notification-schema.d.ts
+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/slack/slack-connection-response-schema.d.ts
+declare const FlumeSlackConnectionResponseSchema: z.ZodObject<{
+  ok: z.ZodBoolean;
+  url: z.ZodOptional<z.ZodString>;
+  error: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+//#endregion
+//#region lib/slack/slack-envelope-schema.d.ts
+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>;
+//#endregion
+//#region lib/types.d.ts
+type FlumeTimerHandle = unknown;
+type FlumeRuntimeDeps = {
+  fetch(url: string | URL, init?: RequestInit): Promise<Response>;
+  WebSocket: (new (url: string | URL) => WebSocket) | null;
+  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 FlumeDiscordEvent = {
+  source: "discord";
+  type: string;
+  data: Record<string, unknown>;
+  meta: Record<string, string>;
+  receivedAt: number;
+};
+type FlumeSlackEvent = {
+  source: "slack";
+  type: string;
+  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;
+type FlumeEventHandler = (event: FlumeEvent) => void | Promise<void>;
+type FlumeStatus = "disconnected" | "connecting" | "connected" | "reconnecting";
+type FlumeStatusEvent = {
+  source: string;
+  status: FlumeStatus;
+  detail?: string;
+};
+type FlumeStatusHandler = (event: FlumeStatusEvent) => void;
+type FlumeSourceStatus = {
+  /**
+   * 多くは `FlumeSourceName` のいずれかだが、`source.name` getter が throw する
+   * 第三者 FlumeSource 実装に備えて `string` まで広げてある (fallback で `"?"`)
+   */
+  source: string;
+  status: FlumeStatus;
+};
+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 FlumeSourceLocalStatusHandler = (status: FlumeStatus, detail?: string) => void;
+type FlumeSourceStartContext = {
+  onEvent: FlumeEventHandler;
+  log: FlumeLogger;
+  deps: FlumeRuntimeDeps;
+  onStatus: FlumeSourceLocalStatusHandler;
+  reconnect: FlumeReconnectConfig | null;
+};
+type FlumeDiscordSourceOptions = {
+  token: string;
+  intents?: number;
+};
+type FlumeSlackSourceOptions = {
+  appToken: string;
+  /**
+   * Bot token (`xoxb-`). Slack Socket Mode (受信) には不要だが、ホスト側 (返信や
+   * `auth.test` での self 検出) が必ず使うため型で保持を強制する
+   */
+  botToken: string;
+};
+type FlumeGitHubSourceOptions = {
+  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
+//#region lib/flume-source.d.ts
+/**
+ * 全 Source の基底クラス。protocol 固有のロジック (`connect` / `disconnect`) のみ
+ * subclass に実装させ、queue / status / handler 安全呼び出しといった共通の
+ * cross-cutting concern は base が引き受ける。Flume 側で全 source に注入される
+ * `FlumeSourceStartContext` (handler / log / deps / onStatus / reconnect) を
+ * `start()` で受け取り、subclass の `connect(ctx)` に手渡す。
+ *
+ * subclass のテンプレート:
+ *
+ * ```ts
+ * export class MySource extends FlumeSource {
+ *   readonly name = "my-source"
+ *
+ *   constructor(private readonly options: { apiKey: string }) {
+ *     super()
+ *   }
+ *
+ *   protected async connect(ctx: FlumeSourceStartContext): Promise<Error | null> {
+ *     // 接続して onEvent で this.emit({...}) / 状態遷移で this.setStatus(...)
+ *     return null
+ *   }
+ *
+ *   protected disconnect(): void { ... }
+ * }
+ * ```
+ */
+declare abstract class FlumeSource {
+  abstract readonly name: string;
+  private consumed;
+  private stopped;
+  private ctx;
+  private statusEmitter;
+  private readonly queue;
+  start(ctx: FlumeSourceStartContext): Promise<Error | null>;
+  stop(): Promise<void>;
+  status(): FlumeStatus;
+  /**
+   * subclass が受信した protocol イベントを `FlumeEvent` として handler へ流す。
+   * handler の throw / async reject は queue 内で catch + log し、後続を止めない
+   */
+  protected emit(event: FlumeEvent): void;
+  /**
+   * subclass が protocol 状態遷移をユーザーに通知する。同一 (status, detail) の連続は冪等
+   */
+  protected setStatus(status: FlumeStatus, detail?: string): void;
+  /** subclass が現在の status を読みたい場合 */
+  protected get currentStatus(): FlumeStatus;
+  /** subclass が start ctx を再参照したい場合 (stop 後は null) */
+  protected get context(): FlumeSourceStartContext | null;
+  /** protocol 接続。subclass 実装 */
+  protected abstract connect(ctx: FlumeSourceStartContext): Promise<Error | null>;
+  /** protocol 切断。subclass 実装。base が `stop()` 内で必ず呼ぶ */
+  protected abstract disconnect(): Promise<void> | void;
+}
+//#endregion
+export { FlumeSourceStartContext as C, FlumeStatusHandler as D, FlumeStatusEvent as E, FlumeTimerHandle as O, FlumeSourceName as S, FlumeStatus as T, FlumeSlackConnectionResponse as _, FlumeEventHandler as a, FlumeSlackSourceOptions as b, FlumeGitHubNotification as c, FlumeLogHandler as d, FlumeLogInput as f, FlumeRuntimeDeps as g, FlumeReconnectOptions as h, FlumeEvent as i, FlumeLogger as k, FlumeGitHubSourceOptions as l, FlumeReconnectConfig as m, FlumeDiscordEvent as n, FlumeGatewayMessage as o, FlumeLogLevel as p, FlumeDiscordSourceOptions as r, FlumeGitHubEvent as s, FlumeSource as t, FlumeLog as u, FlumeSlackEnvelope as v, FlumeSourceStatus as w, FlumeSourceLocalStatusHandler as x, FlumeSlackEvent as y };

package/dist/github.d.ts

@@ -1,21 +1,13 @@
-import { C as FlumeSourceStartOptions, T as FlumeStatus, c as FlumeHandler, o as FlumeGitHubNotification, s as FlumeGitHubSourceOptions } from "./types-D-tO-Mh2.js";
+import { C as FlumeSourceStartContext, c as FlumeGitHubNotification, l as FlumeGitHubSourceOptions, t as FlumeSource } from "./flume-source-DuUFPhSe.js";
 
 //#region lib/github/github-source.d.ts
-declare class FlumeGitHubSource {
+declare class FlumeGitHubSource extends FlumeSource {
   private readonly options;
   readonly name: "github";
   private poller;
-  private handler;
-  private readonly log;
-  private readonly deps;
-  private readonly queue;
-  private readonly signals;
-  private readonly statusEmitter;
-  private readonly onSignalAbort;
   constructor(options: FlumeGitHubSourceOptions);
-  start(handler: FlumeHandler, options?: FlumeSourceStartOptions): Promise<Error | null>;
-  stop(): Promise<void>;
-  status(): FlumeStatus;
+  protected connect(ctx: FlumeSourceStartContext): Promise<Error | null>;
+  protected disconnect(): void;
   private handleNotifications;
   private safeExtractMeta;
 }