@classytic/arc 1.1.0 → 2.1.3

package/dist/integrations/jobs.mjs

@@ -0,0 +1,123 @@
+//#region src/integrations/jobs.ts
+/**
+* Define a background job with typed data and configuration.
+*
+* @example
+* const processImage = defineJob({
+*   name: 'process-image',
+*   handler: async (data: { url: string; width: number }) => {
+*     return await sharp(data.url).resize(data.width).toBuffer();
+*   },
+*   retries: 3,
+*   timeout: 60000,
+* });
+*/
+function defineJob(definition) {
+	return definition;
+}
+const jobsPluginImpl = async (fastify, options) => {
+	const { connection, jobs, prefix = "/jobs", bridgeEvents = true, defaults = {} } = options;
+	let Queue;
+	let Worker;
+	try {
+		const bullmq = await import("bullmq");
+		Queue = bullmq.Queue;
+		Worker = bullmq.Worker;
+	} catch {
+		throw new Error("@classytic/arc/integrations/jobs requires \"bullmq\" package.\nInstall it: npm install bullmq");
+	}
+	const queues = /* @__PURE__ */ new Map();
+	const workers = /* @__PURE__ */ new Map();
+	for (const job of jobs) {
+		const queueName = job.name;
+		const queue = new Queue(queueName, { connection });
+		queues.set(queueName, queue);
+		const worker = new Worker(queueName, async (bullJob) => {
+			const meta = {
+				jobId: bullJob.id,
+				attemptsMade: bullJob.attemptsMade,
+				timestamp: Date.now()
+			};
+			const result = await job.handler(bullJob.data, meta);
+			if (bridgeEvents && fastify.events?.publish) await fastify.events.publish(`job.${queueName}.completed`, {
+				jobId: bullJob.id,
+				data: bullJob.data,
+				result
+			});
+			return result;
+		}, {
+			connection,
+			concurrency: job.concurrency ?? 1,
+			limiter: job.rateLimit ? {
+				max: job.rateLimit.max,
+				duration: job.rateLimit.duration
+			} : void 0
+		});
+		worker.on("failed", async (bullJob, error) => {
+			if (bridgeEvents && fastify.events?.publish) await fastify.events.publish(`job.${queueName}.failed`, {
+				jobId: bullJob?.id,
+				data: bullJob?.data,
+				error: error.message,
+				attemptsMade: bullJob?.attemptsMade
+			});
+		});
+		workers.set(queueName, worker);
+	}
+	const dispatcher = {
+		async dispatch(name, data, opts = {}) {
+			const queue = queues.get(name);
+			if (!queue) throw new Error(`Job queue '${name}' not registered. Available: ${Array.from(queues.keys()).join(", ")}`);
+			const jobDef = jobs.find((j) => j.name === name);
+			return { jobId: (await queue.add(name, data, {
+				delay: opts.delay,
+				priority: opts.priority,
+				jobId: opts.jobId,
+				removeOnComplete: opts.removeOnComplete ?? defaults.removeOnComplete ?? 100,
+				removeOnFail: opts.removeOnFail ?? defaults.removeOnFail ?? 500,
+				attempts: jobDef?.retries ?? defaults.retries ?? 3,
+				backoff: jobDef?.backoff ?? defaults.backoff ?? {
+					type: "exponential",
+					delay: 1e3
+				}
+			})).id };
+		},
+		getQueue(name) {
+			return queues.get(name) ?? null;
+		},
+		async getStats() {
+			const stats = {};
+			for (const [name, queue] of queues) {
+				const counts = await queue.getJobCounts();
+				stats[name] = {
+					waiting: counts.waiting ?? 0,
+					active: counts.active ?? 0,
+					completed: counts.completed ?? 0,
+					failed: counts.failed ?? 0,
+					delayed: counts.delayed ?? 0
+				};
+			}
+			return stats;
+		},
+		async close() {
+			const closePromises = [];
+			for (const worker of workers.values()) closePromises.push(worker.close());
+			for (const queue of queues.values()) closePromises.push(queue.close());
+			await Promise.all(closePromises);
+		}
+	};
+	if (!fastify.hasDecorator("jobs")) fastify.decorate("jobs", dispatcher);
+	fastify.get(`${prefix}/stats`, async () => {
+		return {
+			success: true,
+			data: await dispatcher.getStats()
+		};
+	});
+	fastify.addHook("onClose", async () => {
+		await dispatcher.close();
+	});
+};
+/** Pluggable BullMQ job queue integration for Arc */
+const jobsPlugin = jobsPluginImpl;
+
+//#endregion
+export { jobsPlugin as default, jobsPlugin, defineJob };

package/dist/integrations/streamline.d.mts

@@ -0,0 +1,60 @@
+import { FastifyPluginAsync } from "fastify";
+
+//#region src/integrations/streamline.d.ts
+/** Minimal workflow interface — matches @classytic/streamline's createWorkflow() return */
+interface WorkflowLike {
+  definition: {
+    id: string;
+    name?: string;
+    steps: Record<string, unknown>;
+  };
+  engine: {
+    start(input: unknown, meta?: unknown): Promise<WorkflowRunLike>;
+    execute(runId: string): Promise<WorkflowRunLike>;
+    resume(runId: string, payload?: unknown): Promise<WorkflowRunLike>;
+    cancel(runId: string): Promise<WorkflowRunLike>;
+    pause?(runId: string): Promise<WorkflowRunLike>;
+    rewindTo?(runId: string, stepId: string): Promise<WorkflowRunLike>;
+    get(runId: string): Promise<WorkflowRunLike | null>;
+    shutdown?(): void;
+  };
+  start(input: unknown, meta?: unknown): Promise<WorkflowRunLike>;
+  resume(runId: string, payload?: unknown): Promise<WorkflowRunLike>;
+  cancel(runId: string): Promise<WorkflowRunLike>;
+  get(runId: string): Promise<WorkflowRunLike | null>;
+  shutdown?(): void;
+}
+interface WorkflowRunLike {
+  _id: string;
+  workflowId: string;
+  status: string;
+  context?: unknown;
+  input?: unknown;
+  steps?: Record<string, unknown>;
+  error?: unknown;
+  createdAt?: Date;
+  updatedAt?: Date;
+  [key: string]: unknown;
+}
+interface StreamlinePluginOptions {
+  /** Array of workflows created with createWorkflow() */
+  workflows: WorkflowLike[];
+  /** URL prefix for workflow endpoints (default: '/workflows') */
+  prefix?: string;
+  /** Require authentication for all workflow endpoints (default: true) */
+  auth?: boolean;
+  /** Connect workflow events to Arc's event bus (default: true) */
+  bridgeEvents?: boolean;
+  /** Custom permission check for workflow operations */
+  permissions?: {
+    start?: (request: unknown) => boolean | Promise<boolean>;
+    resume?: (request: unknown) => boolean | Promise<boolean>;
+    cancel?: (request: unknown) => boolean | Promise<boolean>;
+    list?: (request: unknown) => boolean | Promise<boolean>;
+    get?: (request: unknown) => boolean | Promise<boolean>;
+  };
+}
+/** Pluggable streamline integration for Arc */
+declare const streamlinePlugin: FastifyPluginAsync<StreamlinePluginOptions>;
+//#endregion
+export { StreamlinePluginOptions, WorkflowLike, WorkflowRunLike, streamlinePlugin as default, streamlinePlugin };

package/dist/integrations/streamline.mjs

@@ -0,0 +1,125 @@
+//#region src/integrations/streamline.ts
+const streamlinePluginImpl = async (fastify, options) => {
+	const { workflows, prefix = "/workflows", auth = true, bridgeEvents = true, permissions: perms } = options;
+	const registry = /* @__PURE__ */ new Map();
+	for (const wf of workflows) {
+		const id = wf.definition.id;
+		if (registry.has(id)) throw new Error(`Duplicate workflow ID: '${id}'`);
+		registry.set(id, wf);
+	}
+	if (!fastify.hasDecorator("workflows")) fastify.decorate("workflows", registry);
+	if (!fastify.hasDecorator("getWorkflow")) fastify.decorate("getWorkflow", (id) => registry.get(id) ?? null);
+	const authPreHandler = auth && typeof fastify.authenticate === "function" ? [fastify.authenticate] : [];
+	const checkPerm = async (op, request) => {
+		const check = perms?.[op];
+		if (!check) return true;
+		return check(request);
+	};
+	for (const [id, wf] of registry) {
+		const routePrefix = `${prefix}/${id}`;
+		fastify.post(`${routePrefix}/start`, { preHandler: authPreHandler }, async (request, reply) => {
+			if (!await checkPerm("start", request)) return reply.status(403).send({
+				success: false,
+				error: "Forbidden"
+			});
+			const { input, meta } = request.body ?? {};
+			const run = await wf.start(input, meta);
+			if (bridgeEvents && fastify.events?.publish) await fastify.events.publish(`workflow.${id}.started`, {
+				runId: run._id,
+				workflowId: id,
+				status: run.status
+			});
+			return reply.status(201).send({
+				success: true,
+				data: run
+			});
+		});
+		fastify.get(`${routePrefix}/runs/:runId`, { preHandler: authPreHandler }, async (request, reply) => {
+			if (!await checkPerm("get", request)) return reply.status(403).send({
+				success: false,
+				error: "Forbidden"
+			});
+			const { runId } = request.params;
+			const run = await wf.get(runId);
+			if (!run) return reply.status(404).send({
+				success: false,
+				error: "Workflow run not found"
+			});
+			return {
+				success: true,
+				data: run
+			};
+		});
+		fastify.post(`${routePrefix}/runs/:runId/resume`, { preHandler: authPreHandler }, async (request, reply) => {
+			if (!await checkPerm("resume", request)) return reply.status(403).send({
+				success: false,
+				error: "Forbidden"
+			});
+			const { runId } = request.params;
+			const { payload } = request.body ?? {};
+			const run = await wf.resume(runId, payload);
+			if (bridgeEvents && fastify.events?.publish) await fastify.events.publish(`workflow.${id}.resumed`, {
+				runId: run._id,
+				workflowId: id,
+				status: run.status
+			});
+			return {
+				success: true,
+				data: run
+			};
+		});
+		fastify.post(`${routePrefix}/runs/:runId/cancel`, { preHandler: authPreHandler }, async (request, reply) => {
+			if (!await checkPerm("cancel", request)) return reply.status(403).send({
+				success: false,
+				error: "Forbidden"
+			});
+			const { runId } = request.params;
+			const run = await wf.cancel(runId);
+			if (bridgeEvents && fastify.events?.publish) await fastify.events.publish(`workflow.${id}.cancelled`, {
+				runId: run._id,
+				workflowId: id
+			});
+			return {
+				success: true,
+				data: run
+			};
+		});
+		if (wf.engine.pause) fastify.post(`${routePrefix}/runs/:runId/pause`, { preHandler: authPreHandler }, async (request, reply) => {
+			const { runId } = request.params;
+			return {
+				success: true,
+				data: await wf.engine.pause(runId)
+			};
+		});
+		if (wf.engine.rewindTo) fastify.post(`${routePrefix}/runs/:runId/rewind`, { preHandler: authPreHandler }, async (request, reply) => {
+			const { runId } = request.params;
+			const { stepId } = request.body ?? {};
+			if (!stepId) return reply.status(400).send({
+				success: false,
+				error: "stepId is required"
+			});
+			return {
+				success: true,
+				data: await wf.engine.rewindTo(runId, stepId)
+			};
+		});
+	}
+	fastify.get(prefix, { preHandler: authPreHandler }, async () => {
+		return {
+			success: true,
+			data: Array.from(registry.entries()).map(([id, wf]) => ({
+				id,
+				name: wf.definition.name ?? id,
+				steps: Object.keys(wf.definition.steps)
+			}))
+		};
+	});
+	fastify.addHook("onClose", async () => {
+		for (const wf of registry.values()) wf.shutdown?.();
+	});
+};
+/** Pluggable streamline integration for Arc */
+const streamlinePlugin = streamlinePluginImpl;
+
+//#endregion
+export { streamlinePlugin as default, streamlinePlugin };

package/dist/integrations/websocket.d.mts

@@ -0,0 +1,82 @@
+import { FastifyPluginAsync } from "fastify";
+
+//#region src/integrations/websocket.d.ts
+interface WebSocketClient {
+  id: string;
+  socket: {
+    send(data: string): void;
+    close(): void;
+    readyState: number;
+  };
+  subscriptions: Set<string>;
+  userId?: string;
+  organizationId?: string;
+  metadata?: Record<string, unknown>;
+}
+interface WebSocketMessage {
+  type: string;
+  resource?: string;
+  channel?: string;
+  data?: unknown;
+}
+interface WebSocketPluginOptions {
+  /** WebSocket endpoint path (default: '/ws') */
+  path?: string;
+  /** Require authentication for WebSocket connections (default: true) */
+  auth?: boolean;
+  /** Resources to auto-broadcast CRUD events for */
+  resources?: string[];
+  /** Heartbeat interval in ms (default: 30000). Set 0 to disable. */
+  heartbeatInterval?: number;
+  /** Custom authentication function for WebSocket upgrade */
+  authenticate?: (request: unknown) => Promise<{
+    userId?: string;
+    organizationId?: string;
+  } | null>;
+  /** Max clients per resource subscription (default: 10000) */
+  maxClientsPerRoom?: number;
+  /**
+   * Expose a stats endpoint at `{path}/stats`.
+   * - `false` (default): stats endpoint is not registered
+   * - `true`: registered without auth
+   * - `'authenticated'`: guarded by `fastify.authenticate` if available
+   */
+  exposeStats?: boolean | "authenticated";
+  /**
+   * Authorize room subscriptions. Return true to allow, false to deny.
+   * Called before every subscribe. If not provided, all rooms are allowed.
+   */
+  roomPolicy?: (client: WebSocketClient, room: string) => boolean | Promise<boolean>;
+  /** Maximum message size in bytes from client (default: 16384 = 16KB). Messages exceeding this are dropped. */
+  maxMessageBytes?: number;
+  /** Maximum subscriptions per client (default: 100). Prevents resource exhaustion. */
+  maxSubscriptionsPerClient?: number;
+  /** Custom message handler */
+  onMessage?: (client: WebSocketClient, message: WebSocketMessage) => void | Promise<void>;
+  /** Called when a client connects */
+  onConnect?: (client: WebSocketClient) => void | Promise<void>;
+  /** Called when a client disconnects */
+  onDisconnect?: (client: WebSocketClient) => void | Promise<void>;
+}
+declare class RoomManager {
+  private rooms;
+  private clients;
+  private maxPerRoom;
+  constructor(maxPerRoom?: number);
+  addClient(client: WebSocketClient): void;
+  removeClient(clientId: string): void;
+  subscribe(clientId: string, room: string): boolean;
+  unsubscribe(clientId: string, room: string): void;
+  broadcast(room: string, message: string, excludeClientId?: string): void;
+  broadcastToOrg(organizationId: string, room: string, message: string): void;
+  getClient(clientId: string): WebSocketClient | undefined;
+  getStats(): {
+    clients: number;
+    rooms: number;
+    subscriptions: Record<string, number>;
+  };
+}
+/** Pluggable WebSocket integration for Arc */
+declare const websocketPlugin: FastifyPluginAsync<WebSocketPluginOptions>;
+//#endregion
+export { RoomManager, WebSocketClient, WebSocketMessage, WebSocketPluginOptions, websocketPlugin as default, websocketPlugin };

package/dist/integrations/websocket.mjs

@@ -0,0 +1,288 @@
+import fp from "fastify-plugin";
+
+//#region src/integrations/websocket.ts
+var RoomManager = class {
+	rooms = /* @__PURE__ */ new Map();
+	clients = /* @__PURE__ */ new Map();
+	maxPerRoom;
+	constructor(maxPerRoom = 1e4) {
+		this.maxPerRoom = maxPerRoom;
+	}
+	addClient(client) {
+		this.clients.set(client.id, client);
+	}
+	removeClient(clientId) {
+		const client = this.clients.get(clientId);
+		if (!client) return;
+		for (const room of client.subscriptions) {
+			const members = this.rooms.get(room);
+			if (members) {
+				members.delete(clientId);
+				if (members.size === 0) this.rooms.delete(room);
+			}
+		}
+		client.subscriptions.clear();
+		this.clients.delete(clientId);
+	}
+	subscribe(clientId, room) {
+		const client = this.clients.get(clientId);
+		if (!client) return false;
+		const members = this.rooms.get(room);
+		if (members && members.size >= this.maxPerRoom) return false;
+		if (!this.rooms.has(room)) this.rooms.set(room, /* @__PURE__ */ new Set());
+		this.rooms.get(room).add(clientId);
+		client.subscriptions.add(room);
+		return true;
+	}
+	unsubscribe(clientId, room) {
+		const client = this.clients.get(clientId);
+		if (!client) return;
+		const members = this.rooms.get(room);
+		if (members) {
+			members.delete(clientId);
+			if (members.size === 0) this.rooms.delete(room);
+		}
+		client.subscriptions.delete(room);
+	}
+	broadcast(room, message, excludeClientId) {
+		const members = this.rooms.get(room);
+		if (!members) return;
+		for (const clientId of members) {
+			if (clientId === excludeClientId) continue;
+			const client = this.clients.get(clientId);
+			if (client && client.socket.readyState === 1) try {
+				client.socket.send(message);
+			} catch {}
+		}
+	}
+	broadcastToOrg(organizationId, room, message) {
+		const members = this.rooms.get(room);
+		if (!members) return;
+		for (const clientId of members) {
+			const client = this.clients.get(clientId);
+			if (client && client.organizationId === organizationId && client.socket.readyState === 1) try {
+				client.socket.send(message);
+			} catch {}
+		}
+	}
+	getClient(clientId) {
+		return this.clients.get(clientId);
+	}
+	getStats() {
+		const subscriptions = {};
+		for (const [room, members] of this.rooms) subscriptions[room] = members.size;
+		return {
+			clients: this.clients.size,
+			rooms: this.rooms.size,
+			subscriptions
+		};
+	}
+};
+const websocketPluginImpl = async (fastify, options) => {
+	let clientCounter = 0;
+	const { path = "/ws", auth = true, resources = [], heartbeatInterval = 3e4, authenticate: customAuth, maxClientsPerRoom = 1e4, roomPolicy, maxMessageBytes = 16384, maxSubscriptionsPerClient = 100, exposeStats = false, onMessage, onConnect, onDisconnect } = options;
+	if (auth && !customAuth && !fastify.hasDecorator("authenticate")) throw new Error("[arc-websocket] auth is true but fastify.authenticate is not registered. Register an auth plugin before WebSocket, provide a custom authenticate function, or set auth: false.");
+	const rooms = new RoomManager(maxClientsPerRoom);
+	if (!fastify.hasDecorator("ws")) fastify.decorate("ws", {
+		rooms,
+		broadcast: (room, data) => {
+			rooms.broadcast(room, JSON.stringify({
+				type: "broadcast",
+				channel: room,
+				data
+			}));
+		},
+		broadcastToOrg: (orgId, room, data) => {
+			rooms.broadcastToOrg(orgId, room, JSON.stringify({
+				type: "broadcast",
+				channel: room,
+				data
+			}));
+		},
+		getStats: () => rooms.getStats()
+	});
+	const eventUnsubscribers = [];
+	if (resources.length > 0 && fastify.events?.subscribe) for (const resourceName of resources) for (const op of [
+		"created",
+		"updated",
+		"deleted"
+	]) {
+		const unsub = await fastify.events.subscribe(`${resourceName}.${op}`, async (event) => {
+			const room = resourceName;
+			const payload = JSON.stringify({
+				type: `${resourceName}.${op}`,
+				data: event.payload,
+				meta: {
+					timestamp: event.meta?.timestamp,
+					userId: event.meta?.userId,
+					organizationId: event.meta?.organizationId
+				}
+			});
+			if (event.meta?.organizationId) rooms.broadcastToOrg(event.meta.organizationId, room, payload);
+			else rooms.broadcast(room, payload);
+		});
+		eventUnsubscribers.push(unsub);
+	}
+	fastify.get(path, { websocket: true }, async (socket, request) => {
+		const clientId = `ws_${++clientCounter}_${Date.now()}`;
+		let userId;
+		let organizationId;
+		if (auth) if (customAuth) {
+			const result = await customAuth(request);
+			if (!result) {
+				socket.close(4001, "Unauthorized");
+				return;
+			}
+			userId = result.userId;
+			organizationId = result.organizationId;
+		} else {
+			if (fastify.authenticate) try {
+				let rejected = false;
+				const fakeReply = {
+					code(_statusCode) {
+						rejected = true;
+						return fakeReply;
+					},
+					send() {
+						return fakeReply;
+					},
+					sent: false
+				};
+				await fastify.authenticate(request, fakeReply);
+				if (rejected) {
+					socket.close(4001, "Unauthorized");
+					return;
+				}
+			} catch {
+				socket.close(4001, "Unauthorized");
+				return;
+			}
+			if (request.user) {
+				userId = request.user.id ?? request.user.sub;
+				organizationId = request.scope?.organizationId;
+			} else {
+				socket.close(4001, "Unauthorized");
+				return;
+			}
+		}
+		const client = {
+			id: clientId,
+			socket,
+			subscriptions: /* @__PURE__ */ new Set(),
+			userId,
+			organizationId
+		};
+		rooms.addClient(client);
+		await onConnect?.(client);
+		socket.send(JSON.stringify({
+			type: "connected",
+			clientId,
+			resources
+		}));
+		let heartbeatTimer;
+		if (heartbeatInterval > 0) heartbeatTimer = setInterval(() => {
+			if (socket.readyState === 1) socket.send(JSON.stringify({
+				type: "ping",
+				timestamp: Date.now()
+			}));
+		}, heartbeatInterval);
+		socket.on("message", async (raw) => {
+			if ((typeof raw === "string" ? Buffer.byteLength(raw) : raw.length) > maxMessageBytes) {
+				socket.send(JSON.stringify({
+					type: "error",
+					error: "Message too large"
+				}));
+				return;
+			}
+			try {
+				const msg = JSON.parse(typeof raw === "string" ? raw : raw.toString());
+				switch (msg.type) {
+					case "subscribe": {
+						const room = msg.resource ?? msg.channel;
+						if (room) {
+							if (client.subscriptions.size >= maxSubscriptionsPerClient) {
+								socket.send(JSON.stringify({
+									type: "error",
+									channel: room,
+									error: "Subscription limit reached"
+								}));
+								break;
+							}
+							if (roomPolicy) {
+								if (!await roomPolicy(client, room)) {
+									socket.send(JSON.stringify({
+										type: "error",
+										channel: room,
+										error: "Subscription denied"
+									}));
+									break;
+								}
+							}
+							const ok = rooms.subscribe(clientId, room);
+							socket.send(JSON.stringify({
+								type: ok ? "subscribed" : "error",
+								channel: room,
+								...ok ? {} : { error: "Room at capacity" }
+							}));
+						}
+						break;
+					}
+					case "unsubscribe": {
+						const room = msg.resource ?? msg.channel;
+						if (room) {
+							rooms.unsubscribe(clientId, room);
+							socket.send(JSON.stringify({
+								type: "unsubscribed",
+								channel: room
+							}));
+						}
+						break;
+					}
+					case "pong": break;
+					default:
+						await onMessage?.(client, msg);
+						break;
+				}
+			} catch {
+				socket.send(JSON.stringify({
+					type: "error",
+					error: "Invalid message format"
+				}));
+			}
+		});
+		socket.on("close", async () => {
+			if (heartbeatTimer) clearInterval(heartbeatTimer);
+			await onDisconnect?.(client);
+			rooms.removeClient(clientId);
+		});
+		socket.on("error", () => {
+			if (heartbeatTimer) clearInterval(heartbeatTimer);
+			rooms.removeClient(clientId);
+		});
+	});
+	if (exposeStats === true) fastify.get(`${path}/stats`, async () => {
+		return {
+			success: true,
+			data: rooms.getStats()
+		};
+	});
+	else if (exposeStats === "authenticated") if (fastify.hasDecorator("authenticate")) fastify.get(`${path}/stats`, { preHandler: fastify.authenticate }, async () => {
+		return {
+			success: true,
+			data: rooms.getStats()
+		};
+	});
+	else fastify.log.warn("arc-websocket: exposeStats is \"authenticated\" but fastify.authenticate is not registered — stats endpoint skipped");
+	fastify.addHook("onClose", async () => {
+		for (const unsub of eventUnsubscribers) unsub();
+		eventUnsubscribers.length = 0;
+	});
+};
+/** Pluggable WebSocket integration for Arc */
+const websocketPlugin = fp(websocketPluginImpl, {
+	name: "arc-websocket",
+	fastify: "5.x"
+});
+
+//#endregion
+export { RoomManager, websocketPlugin as default, websocketPlugin };