@classytic/arc 2.3.0 → 2.4.2

package/dist/integrations/mcp/testing.mjs

@@ -0,0 +1,104 @@
+import { r as createMcpServer, t as resourceToTools } from "../../resourceToTools-PMFE8HIv.mjs";
+//#region src/integrations/mcp/testing.ts
+/**
+* @classytic/arc/mcp/testing — MCP Test Utilities
+*
+* Helpers for testing MCP tool integration without raw JSON-RPC parsing.
+* Uses the MCP SDK's InMemoryTransport for fast, in-process testing.
+*
+* @example
+* ```typescript
+* import { createTestMcpClient } from '@classytic/arc/mcp/testing';
+*
+* const client = await createTestMcpClient({
+*   pluginOptions: { resources: [productResource] },
+*   auth: { userId: 'test-user', organizationId: 'org-1' },
+* });
+*
+* const tools = await client.listTools();
+* const result = await client.callTool('list_products', { limit: 5 });
+* await client.close();
+* ```
+*/
+/**
+* Create an in-process MCP test client connected to an Arc MCP server.
+*
+* Pass resources and tools directly — no running Fastify server needed.
+* For HTTP-level integration tests against a running server, use `app.inject()` instead.
+*
+* @example
+* ```typescript
+* const client = await createTestMcpClient({
+*   pluginOptions: { resources: [productResource], extraTools: [myTool] },
+*   auth: { userId: 'test-user', organizationId: 'org-1' },
+* });
+*
+* const tools = await client.listTools();
+* expect(tools.map(t => t.name)).toContain('list_products');
+*
+* const result = await client.callTool('list_products', { limit: 5 });
+* expect(result.isError).toBeFalsy();
+*
+* await client.close();
+* ```
+*/
+async function createTestMcpClient(options = {}) {
+	const { InMemoryTransport } = await import("@modelcontextprotocol/sdk/inMemory.js");
+	const { Client } = await import("@modelcontextprotocol/sdk/client/index.js");
+	const pluginOpts = {
+		resources: [],
+		...options.pluginOptions
+	};
+	const auth = options.auth ?? { userId: "test-user" };
+	const serverName = options.serverName ?? "test-mcp";
+	const overrides = pluginOpts.overrides ?? {};
+	let enabledResources = pluginOpts.resources ?? [];
+	if (pluginOpts.include) {
+		const includeSet = new Set(pluginOpts.include);
+		enabledResources = enabledResources.filter((r) => includeSet.has(r.name));
+	} else if (pluginOpts.exclude) {
+		const excludeSet = new Set(pluginOpts.exclude);
+		enabledResources = enabledResources.filter((r) => !excludeSet.has(r.name));
+	}
+	const tools = enabledResources.flatMap((r) => {
+		const resOverrides = overrides[r.name] ?? {};
+		return resourceToTools(r, {
+			...resOverrides,
+			toolNamePrefix: resOverrides.toolNamePrefix ?? pluginOpts.toolNamePrefix
+		});
+	});
+	if (pluginOpts.extraTools) tools.push(...pluginOpts.extraTools);
+	const authRef = { current: auth };
+	const server = await createMcpServer({
+		name: serverName,
+		version: "1.0.0",
+		instructions: pluginOpts.instructions,
+		tools,
+		prompts: pluginOpts.extraPrompts
+	}, authRef);
+	const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+	const client = new Client({
+		name: "test-client",
+		version: "1.0"
+	});
+	await Promise.all([client.connect(clientTransport), server.connect(serverTransport)]);
+	return {
+		async listTools() {
+			return (await client.listTools()).tools.map((t) => ({
+				name: t.name,
+				description: t.description
+			}));
+		},
+		async callTool(name, args) {
+			return await client.callTool({
+				name,
+				arguments: args ?? {}
+			});
+		},
+		async close() {
+			await client.close();
+		}
+	};
+}
+//#endregion
+export { createTestMcpClient };

package/dist/integrations/streamline.mjs

@@ -24,11 +24,18 @@ const streamlinePluginImpl = async (fastify, options) => {
 			});
 			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
-			});
+			if (bridgeEvents && fastify.events?.publish) try {
+				await fastify.events.publish(`workflow.${id}.started`, {
+					runId: run._id,
+					workflowId: id,
+					status: run.status
+				});
+			} catch (err) {
+				fastify.log.warn({
+					err,
+					workflowId: id
+				}, "Failed to publish workflow.started event");
+			}
 			return reply.status(201).send({
 				success: true,
 				data: run
@@ -58,11 +65,18 @@ const streamlinePluginImpl = async (fastify, options) => {
 			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
-			});
+			if (bridgeEvents && fastify.events?.publish) try {
+				await fastify.events.publish(`workflow.${id}.resumed`, {
+					runId: run._id,
+					workflowId: id,
+					status: run.status
+				});
+			} catch (err) {
+				fastify.log.warn({
+					err,
+					workflowId: id
+				}, "Failed to publish workflow.resumed event");
+			}
 			return {
 				success: true,
 				data: run
@@ -75,20 +89,27 @@ const streamlinePluginImpl = async (fastify, options) => {
 			});
 			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
-			});
+			if (bridgeEvents && fastify.events?.publish) try {
+				await fastify.events.publish(`workflow.${id}.cancelled`, {
+					runId: run._id,
+					workflowId: id
+				});
+			} catch (err) {
+				fastify.log.warn({
+					err,
+					workflowId: id
+				}, "Failed to publish workflow.cancelled event");
+			}
 			return {
 				success: true,
 				data: run
 			};
 		});
-		if (wf.engine.pause) fastify.post(`${routePrefix}/runs/:runId/pause`, { preHandler: authPreHandler }, async (request, reply) => {
+		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)
+				data: await wf.engine.pause?.(runId)
 			};
 		});
 		if (wf.engine.rewindTo) fastify.post(`${routePrefix}/runs/:runId/rewind`, { preHandler: authPreHandler }, async (request, reply) => {
@@ -100,7 +121,7 @@ const streamlinePluginImpl = async (fastify, options) => {
 			});
 			return {
 				success: true,
-				data: await wf.engine.rewindTo(runId, stepId)
+				data: await wf.engine.rewindTo?.(runId, stepId)
 			};
 		});
 	}
@@ -120,6 +141,5 @@ const streamlinePluginImpl = async (fastify, options) => {
 };
 /** Pluggable streamline integration for Arc */
 const streamlinePlugin = streamlinePluginImpl;
-
 //#endregion
-export { streamlinePlugin as default, streamlinePlugin };
+export { streamlinePlugin as default, streamlinePlugin };

package/dist/integrations/webhooks.d.mts

@@ -0,0 +1,56 @@
+import { FastifyPluginAsync } from "fastify";
+
+//#region src/integrations/webhooks.d.ts
+interface WebhookSubscription {
+  /** Unique subscription ID */
+  id: string;
+  /** Delivery URL */
+  url: string;
+  /** Event patterns (e.g., 'order.created', 'order.*', '*') */
+  events: string[];
+  /** Shared secret for HMAC-SHA256 signing */
+  secret: string;
+  /** Optional metadata */
+  metadata?: Record<string, unknown>;
+}
+interface WebhookDeliveryRecord {
+  subscriptionId: string;
+  eventType: string;
+  success: boolean;
+  status?: number;
+  error?: string;
+  timestamp: Date;
+}
+/** Pluggable persistence — memory for dev, bring your own DB for prod */
+interface WebhookStore {
+  readonly name: string;
+  getAll(): Promise<WebhookSubscription[]>;
+  save(sub: WebhookSubscription): Promise<void>;
+  remove(id: string): Promise<void>;
+}
+interface WebhookPluginOptions {
+  /** Custom store for persistent subscriptions (default: in-memory) */
+  store?: WebhookStore;
+  /** Custom fetch (for testing) */
+  fetch?: typeof globalThis.fetch;
+  /** Delivery timeout in ms (default: 10000) */
+  timeout?: number;
+  /** Max delivery log entries kept in memory (default: 1000) */
+  maxLogEntries?: number;
+}
+interface WebhookManager {
+  register(sub: WebhookSubscription): Promise<void> | void;
+  unregister(id: string): Promise<void> | void;
+  list(): WebhookSubscription[];
+  deliveryLog(limit?: number): WebhookDeliveryRecord[];
+}
+declare module "fastify" {
+  interface FastifyInstance {
+    webhooks: WebhookManager;
+  }
+}
+declare function signPayload(payload: string, secret: string): string;
+declare const webhookPlugin: FastifyPluginAsync<WebhookPluginOptions>;
+declare const _default: FastifyPluginAsync<WebhookPluginOptions>;
+//#endregion
+export { WebhookDeliveryRecord, WebhookManager, WebhookPluginOptions, WebhookStore, WebhookSubscription, _default as default, signPayload, webhookPlugin };

package/dist/integrations/webhooks.mjs

@@ -0,0 +1,139 @@
+import { createHmac } from "node:crypto";
+import fp from "fastify-plugin";
+//#region src/integrations/webhooks.ts
+/**
+* @classytic/arc — Webhook Outbound Integration
+*
+* Fastify plugin that auto-dispatches Arc events to registered webhook
+* endpoints with HMAC-SHA256 signing, delivery logging, and pluggable
+* persistence via WebhookStore.
+*
+* This is a SEPARATE subpath import — only loaded when explicitly used:
+*   import { webhookPlugin } from '@classytic/arc/integrations/webhooks';
+*
+* @example
+* ```typescript
+* import { webhookPlugin } from '@classytic/arc/integrations/webhooks';
+*
+* await fastify.register(webhookPlugin);
+*
+* // Register a customer webhook
+* app.webhooks.register({
+*   id: 'wh-1',
+*   url: 'https://customer.com/webhook',
+*   events: ['order.created', 'order.shipped'],
+*   secret: 'whsec_abc123',
+* });
+*
+* // Events auto-dispatch — no manual wiring needed
+* await app.events.publish('order.created', { orderId: '123' });
+* // → POST https://customer.com/webhook with HMAC signature
+* ```
+*/
+function signPayload(payload, secret) {
+	const hmac = createHmac("sha256", secret);
+	hmac.update(payload);
+	return `sha256=${hmac.digest("hex")}`;
+}
+function matchesPattern(patterns, eventType) {
+	for (const pattern of patterns) {
+		if (pattern === "*") return true;
+		if (pattern === eventType) return true;
+		if (pattern.endsWith(".*")) {
+			const prefix = pattern.slice(0, -2);
+			if (eventType.startsWith(`${prefix}.`)) return true;
+		}
+	}
+	return false;
+}
+var MemoryWebhookStore = class {
+	name = "memory";
+	subs = /* @__PURE__ */ new Map();
+	async getAll() {
+		return [...this.subs.values()];
+	}
+	async save(sub) {
+		this.subs.set(sub.id, sub);
+	}
+	async remove(id) {
+		this.subs.delete(id);
+	}
+};
+const webhookPlugin = async (fastify, opts = {}) => {
+	const store = opts.store ?? new MemoryWebhookStore();
+	const fetchFn = opts.fetch ?? globalThis.fetch;
+	const timeout = opts.timeout ?? 1e4;
+	const maxLogEntries = opts.maxLogEntries ?? 1e3;
+	let subscriptions = [];
+	const log = [];
+	subscriptions = await store.getAll();
+	async function dispatchEvent(event) {
+		const matching = subscriptions.filter((s) => matchesPattern(s.events, event.type));
+		if (matching.length === 0) return;
+		const body = JSON.stringify({
+			type: event.type,
+			payload: event.payload,
+			meta: event.meta
+		});
+		for (const sub of matching) {
+			const record = {
+				subscriptionId: sub.id,
+				eventType: event.type,
+				success: false,
+				timestamp: /* @__PURE__ */ new Date()
+			};
+			try {
+				const signature = signPayload(body, sub.secret);
+				const controller = new AbortController();
+				const timer = setTimeout(() => controller.abort(), timeout);
+				try {
+					const response = await fetchFn(sub.url, {
+						method: "POST",
+						headers: {
+							"content-type": "application/json",
+							"x-webhook-signature": signature,
+							"x-webhook-id": event.meta.id,
+							"x-webhook-event": event.type
+						},
+						body,
+						signal: controller.signal
+					});
+					record.success = response.ok;
+					record.status = response.status;
+				} finally {
+					clearTimeout(timer);
+				}
+			} catch (err) {
+				record.error = err instanceof Error ? err.message : String(err);
+			}
+			log.push(record);
+			if (log.length > maxLogEntries) log.splice(0, log.length - maxLogEntries);
+		}
+	}
+	if (fastify.events) await fastify.events.subscribe("*", dispatchEvent);
+	fastify.decorate("webhooks", {
+		async register(sub) {
+			await store.save(sub);
+			subscriptions = subscriptions.filter((s) => s.id !== sub.id);
+			subscriptions.push(sub);
+		},
+		async unregister(id) {
+			await store.remove(id);
+			subscriptions = subscriptions.filter((s) => s.id !== id);
+		},
+		list() {
+			return [...subscriptions];
+		},
+		deliveryLog(limit) {
+			if (limit) return log.slice(-limit);
+			return [...log];
+		}
+	});
+};
+var webhooks_default = fp(webhookPlugin, {
+	name: "arc-webhooks",
+	fastify: "5.x",
+	dependencies: ["arc-events"]
+});
+//#endregion
+export { webhooks_default as default, signPayload, webhookPlugin };

package/dist/integrations/websocket-redis.d.mts

@@ -0,0 +1,46 @@
+import { WebSocketAdapter } from "./websocket.mjs";
+
+//#region src/integrations/websocket-redis.d.ts
+interface RedisLike {
+  publish(channel: string, message: string): Promise<number>;
+  subscribe(...channels: string[]): Promise<unknown>;
+  on(event: string, handler: (...args: unknown[]) => void): unknown;
+  duplicate(): RedisLike;
+  quit(): Promise<unknown>;
+}
+interface RedisWebSocketAdapterOptions {
+  /**
+   * Redis channel for WebSocket broadcasts.
+   * @default 'arc-ws'
+   */
+  channel?: string;
+  /**
+   * Unique instance ID to prevent echo (receiving own broadcasts).
+   * Auto-generated if not provided.
+   */
+  instanceId?: string;
+}
+/**
+ * Redis Pub/Sub adapter for cross-instance WebSocket broadcast.
+ *
+ * Architecture:
+ * 1. Instance A calls broadcastWithAdapter('products', message)
+ * 2. RoomManager broadcasts locally + calls adapter.publish()
+ * 3. Adapter publishes to Redis channel: { room, message, instanceId }
+ * 4. All instances (including A) receive the Redis message
+ * 5. Each instance checks instanceId — skips if it's own message (prevents double delivery)
+ * 6. Other instances call RoomManager.broadcast() to deliver to their local clients
+ */
+declare class RedisWebSocketAdapter implements WebSocketAdapter {
+  readonly name = "redis";
+  private pub;
+  private sub;
+  private channel;
+  private instanceId;
+  constructor(redis: RedisLike, options?: RedisWebSocketAdapterOptions);
+  publish(room: string, message: string): Promise<void>;
+  subscribe(callback: (room: string, message: string) => void): Promise<void>;
+  close(): Promise<void>;
+}
+//#endregion
+export { RedisLike, RedisWebSocketAdapter, RedisWebSocketAdapter as default, RedisWebSocketAdapterOptions };

package/dist/integrations/websocket-redis.mjs

@@ -0,0 +1,50 @@
+//#region src/integrations/websocket-redis.ts
+/**
+* Redis Pub/Sub adapter for cross-instance WebSocket broadcast.
+*
+* Architecture:
+* 1. Instance A calls broadcastWithAdapter('products', message)
+* 2. RoomManager broadcasts locally + calls adapter.publish()
+* 3. Adapter publishes to Redis channel: { room, message, instanceId }
+* 4. All instances (including A) receive the Redis message
+* 5. Each instance checks instanceId — skips if it's own message (prevents double delivery)
+* 6. Other instances call RoomManager.broadcast() to deliver to their local clients
+*/
+var RedisWebSocketAdapter = class {
+	name = "redis";
+	pub;
+	sub;
+	channel;
+	instanceId;
+	constructor(redis, options = {}) {
+		const { channel = "arc-ws", instanceId } = options;
+		this.channel = channel;
+		this.instanceId = instanceId ?? `arc-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+		this.pub = redis;
+		this.sub = redis.duplicate();
+	}
+	async publish(room, message) {
+		const envelope = JSON.stringify({
+			room,
+			message,
+			instanceId: this.instanceId
+		});
+		await this.pub.publish(this.channel, envelope);
+	}
+	async subscribe(callback) {
+		this.sub.on("message", (...args) => {
+			const [, raw] = args;
+			try {
+				const envelope = JSON.parse(raw);
+				if (envelope.instanceId === this.instanceId) return;
+				callback(envelope.room, envelope.message);
+			} catch {}
+		});
+		await this.sub.subscribe(this.channel);
+	}
+	async close() {
+		await this.sub.quit();
+	}
+};
+//#endregion
+export { RedisWebSocketAdapter, RedisWebSocketAdapter as default };

package/dist/integrations/websocket.d.mts

@@ -51,24 +51,90 @@ interface WebSocketPluginOptions {
   maxMessageBytes?: number;
   /** Maximum subscriptions per client (default: 100). Prevents resource exhaustion. */
   maxSubscriptionsPerClient?: number;
+  /**
+   * Periodic re-authentication interval in ms (default: 0 = disabled).
+   * When set, the server periodically re-validates the client's auth token.
+   * If the token is expired/revoked, the client is disconnected with code 4003.
+   *
+   * Recommended: 300000 (5 minutes) for production.
+   *
+   * @example
+   * ```typescript
+   * websocketPlugin({ reauthInterval: 5 * 60 * 1000 }) // re-check every 5 min
+   * ```
+   */
+  reauthInterval?: 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>;
+  /**
+   * Cross-instance broadcast adapter (default: LocalWebSocketAdapter — single-instance only).
+   * Provide a RedisWebSocketAdapter for multi-instance deployments.
+   *
+   * @example
+   * ```typescript
+   * import { RedisWebSocketAdapter } from '@classytic/arc/integrations/websocket';
+   * adapter: new RedisWebSocketAdapter(redis, { channel: 'arc-ws' })
+   * ```
+   */
+  adapter?: WebSocketAdapter;
+}
+/**
+ * Adapter interface for cross-instance WebSocket broadcast.
+ *
+ * - `publish()`: Send a message to all instances (via Redis, NATS, etc.)
+ * - `subscribe()`: Receive messages from other instances
+ * - `close()`: Clean up connections
+ *
+ * The adapter is NOT used for local broadcasts — RoomManager handles those.
+ * The adapter only handles the cross-instance relay.
+ */
+interface WebSocketAdapter {
+  /** Adapter name for logging */
+  readonly name: string;
+  /** Publish a room broadcast to all other instances */
+  publish(room: string, message: string): Promise<void>;
+  /** Subscribe to broadcasts from other instances */
+  subscribe(callback: (room: string, message: string) => void): Promise<void>;
+  /** Close adapter connections */
+  close(): Promise<void>;
+}
+/**
+ * Default adapter — no cross-instance broadcast (single-instance only).
+ * All methods are no-ops. Used when no adapter is configured.
+ */
+declare class LocalWebSocketAdapter implements WebSocketAdapter {
+  readonly name = "local";
+  publish(): Promise<void>;
+  subscribe(): Promise<void>;
+  close(): Promise<void>;
 }
 declare class RoomManager {
   private rooms;
   private clients;
   private maxPerRoom;
-  constructor(maxPerRoom?: number);
+  private adapter?;
+  constructor(maxPerRoom?: number, adapter?: WebSocketAdapter);
   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;
+  /**
+   * Broadcast locally AND through adapter (for cross-instance delivery).
+   * Use this instead of broadcast() when multi-instance is possible.
+   */
+  broadcastWithAdapter(room: string, message: string, excludeClientId?: string): Promise<void>;
+  /**
+   * Org-scoped broadcast locally AND through adapter.
+   * Uses a namespaced room key for the adapter so other instances
+   * can filter by org when delivering locally.
+   */
+  broadcastToOrgWithAdapter(organizationId: string, room: string, message: string): Promise<void>;
   getClient(clientId: string): WebSocketClient | undefined;
   getStats(): {
     clients: number;
@@ -79,4 +145,4 @@ declare class RoomManager {
 /** Pluggable WebSocket integration for Arc */
 declare const websocketPlugin: FastifyPluginAsync<WebSocketPluginOptions>;
 //#endregion
-export { RoomManager, WebSocketClient, WebSocketMessage, WebSocketPluginOptions, websocketPlugin as default, websocketPlugin };
+export { LocalWebSocketAdapter, RoomManager, WebSocketAdapter, WebSocketClient, WebSocketMessage, WebSocketPluginOptions, websocketPlugin as default, websocketPlugin };