@classytic/arc 1.1.0 → 2.1.2

package/dist/integrations/streamline.mjs

@@ -0,0 +1,126 @@
+//#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 };
+//# sourceMappingURL=streamline.mjs.map

package/dist/integrations/streamline.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"streamline.mjs","names":[],"sources":["../../src/integrations/streamline.ts"],"sourcesContent":["/**\n * @classytic/arc — Streamline Integration\n *\n * Pluggable adapter that wires @classytic/streamline workflows into Arc's\n * Fastify application. Provides REST endpoints for workflow management,\n * auto-connects to Arc's event bus, and respects Arc's auth/permissions.\n *\n * This is a SEPARATE subpath import — only loaded when explicitly used:\n *   import { streamlinePlugin } from '@classytic/arc/integrations/streamline';\n *\n * Requires: @classytic/streamline (peer dependency)\n *\n * @example\n * ```typescript\n * import { streamlinePlugin } from '@classytic/arc/integrations/streamline';\n * import { orderWorkflow } from './workflows/order.js';\n *\n * await fastify.register(streamlinePlugin, {\n *   workflows: [orderWorkflow],\n *   prefix: '/api/workflows',\n *   auth: true, // require authentication for workflow endpoints\n * });\n *\n * // Starts the workflow\n * // POST /api/workflows/order/start { input }\n * // GET  /api/workflows/order/runs/:runId\n * // POST /api/workflows/order/runs/:runId/resume { payload }\n * // POST /api/workflows/order/runs/:runId/cancel\n * // GET  /api/workflows/order/runs (list runs)\n * ```\n */\nimport type { FastifyInstance, FastifyPluginAsync } from 'fastify';\n\n// ============================================================================\n// Types (defined here so we don't import streamline at module level)\n// ============================================================================\n\n/** Minimal workflow interface — matches @classytic/streamline's createWorkflow() return */\nexport interface WorkflowLike {\n  definition: { id: string; name?: string; steps: Record<string, unknown> };\n  engine: {\n    start(input: unknown, meta?: unknown): Promise<WorkflowRunLike>;\n    execute(runId: string): Promise<WorkflowRunLike>;\n    resume(runId: string, payload?: unknown): Promise<WorkflowRunLike>;\n    cancel(runId: string): Promise<WorkflowRunLike>;\n    pause?(runId: string): Promise<WorkflowRunLike>;\n    rewindTo?(runId: string, stepId: string): Promise<WorkflowRunLike>;\n    get(runId: string): Promise<WorkflowRunLike | null>;\n    shutdown?(): void;\n  };\n  start(input: unknown, meta?: unknown): Promise<WorkflowRunLike>;\n  resume(runId: string, payload?: unknown): Promise<WorkflowRunLike>;\n  cancel(runId: string): Promise<WorkflowRunLike>;\n  get(runId: string): Promise<WorkflowRunLike | null>;\n  shutdown?(): void;\n}\n\nexport interface WorkflowRunLike {\n  _id: string;\n  workflowId: string;\n  status: string;\n  context?: unknown;\n  input?: unknown;\n  steps?: Record<string, unknown>;\n  error?: unknown;\n  createdAt?: Date;\n  updatedAt?: Date;\n  [key: string]: unknown;\n}\n\nexport interface StreamlinePluginOptions {\n  /** Array of workflows created with createWorkflow() */\n  workflows: WorkflowLike[];\n  /** URL prefix for workflow endpoints (default: '/workflows') */\n  prefix?: string;\n  /** Require authentication for all workflow endpoints (default: true) */\n  auth?: boolean;\n  /** Connect workflow events to Arc's event bus (default: true) */\n  bridgeEvents?: boolean;\n  /** Custom permission check for workflow operations */\n  permissions?: {\n    start?: (request: unknown) => boolean | Promise<boolean>;\n    resume?: (request: unknown) => boolean | Promise<boolean>;\n    cancel?: (request: unknown) => boolean | Promise<boolean>;\n    list?: (request: unknown) => boolean | Promise<boolean>;\n    get?: (request: unknown) => boolean | Promise<boolean>;\n  };\n}\n\n// ============================================================================\n// Plugin Implementation\n// ============================================================================\n\nconst streamlinePluginImpl: FastifyPluginAsync<StreamlinePluginOptions> = async (\n  fastify: FastifyInstance,\n  options: StreamlinePluginOptions\n) => {\n  const {\n    workflows,\n    prefix = '/workflows',\n    auth = true,\n    bridgeEvents = true,\n    permissions: perms,\n  } = options;\n\n  // Registry: workflowId → workflow instance\n  const registry = new Map<string, WorkflowLike>();\n\n  for (const wf of workflows) {\n    const id = wf.definition.id;\n    if (registry.has(id)) {\n      throw new Error(`Duplicate workflow ID: '${id}'`);\n    }\n    registry.set(id, wf);\n  }\n\n  // Decorate fastify with workflow accessor\n  if (!fastify.hasDecorator('workflows')) {\n    fastify.decorate('workflows', registry);\n  }\n  if (!fastify.hasDecorator('getWorkflow')) {\n    fastify.decorate('getWorkflow', (id: string) => registry.get(id) ?? null);\n  }\n\n  // Build auth preHandler if needed\n  const authPreHandler = auth && typeof fastify.authenticate === 'function'\n    ? [fastify.authenticate]\n    : [];\n\n  // Permission check helper\n  const checkPerm = async (\n    op: keyof NonNullable<StreamlinePluginOptions['permissions']>,\n    request: unknown\n  ): Promise<boolean> => {\n    const check = perms?.[op];\n    if (!check) return true;\n    return check(request);\n  };\n\n  // Register routes per workflow\n  for (const [id, wf] of registry) {\n    const routePrefix = `${prefix}/${id}`;\n\n    // POST /:workflowId/start — Start a new workflow run\n    fastify.post(`${routePrefix}/start`, {\n      preHandler: authPreHandler,\n    }, async (request, reply) => {\n      if (!(await checkPerm('start', request))) {\n        return reply.status(403).send({ success: false, error: 'Forbidden' });\n      }\n      const { input, meta } = (request.body ?? {}) as { input?: unknown; meta?: unknown };\n      const run = await wf.start(input, meta);\n\n      // Bridge event to Arc's event bus\n      if (bridgeEvents && fastify.events?.publish) {\n        await fastify.events.publish(`workflow.${id}.started`, {\n          runId: run._id,\n          workflowId: id,\n          status: run.status,\n        });\n      }\n\n      return reply.status(201).send({ success: true, data: run });\n    });\n\n    // GET /:workflowId/runs/:runId — Get a workflow run\n    fastify.get(`${routePrefix}/runs/:runId`, {\n      preHandler: authPreHandler,\n    }, async (request, reply) => {\n      if (!(await checkPerm('get', request))) {\n        return reply.status(403).send({ success: false, error: 'Forbidden' });\n      }\n      const { runId } = request.params as { runId: string };\n      const run = await wf.get(runId);\n      if (!run) {\n        return reply.status(404).send({ success: false, error: 'Workflow run not found' });\n      }\n      return { success: true, data: run };\n    });\n\n    // POST /:workflowId/runs/:runId/resume — Resume a waiting workflow\n    fastify.post(`${routePrefix}/runs/:runId/resume`, {\n      preHandler: authPreHandler,\n    }, async (request, reply) => {\n      if (!(await checkPerm('resume', request))) {\n        return reply.status(403).send({ success: false, error: 'Forbidden' });\n      }\n      const { runId } = request.params as { runId: string };\n      const { payload } = (request.body ?? {}) as { payload?: unknown };\n      const run = await wf.resume(runId, payload);\n\n      if (bridgeEvents && fastify.events?.publish) {\n        await fastify.events.publish(`workflow.${id}.resumed`, {\n          runId: run._id,\n          workflowId: id,\n          status: run.status,\n        });\n      }\n\n      return { success: true, data: run };\n    });\n\n    // POST /:workflowId/runs/:runId/cancel — Cancel a workflow run\n    fastify.post(`${routePrefix}/runs/:runId/cancel`, {\n      preHandler: authPreHandler,\n    }, async (request, reply) => {\n      if (!(await checkPerm('cancel', request))) {\n        return reply.status(403).send({ success: false, error: 'Forbidden' });\n      }\n      const { runId } = request.params as { runId: string };\n      const run = await wf.cancel(runId);\n\n      if (bridgeEvents && fastify.events?.publish) {\n        await fastify.events.publish(`workflow.${id}.cancelled`, {\n          runId: run._id,\n          workflowId: id,\n        });\n      }\n\n      return { success: true, data: run };\n    });\n\n    // POST /:workflowId/runs/:runId/pause — Pause a running workflow (if supported)\n    if (wf.engine.pause) {\n      fastify.post(`${routePrefix}/runs/:runId/pause`, {\n        preHandler: authPreHandler,\n      }, async (request, reply) => {\n        const { runId } = request.params as { runId: string };\n        const run = await wf.engine.pause!(runId);\n        return { success: true, data: run };\n      });\n    }\n\n    // POST /:workflowId/runs/:runId/rewind — Rewind to a step (if supported)\n    if (wf.engine.rewindTo) {\n      fastify.post(`${routePrefix}/runs/:runId/rewind`, {\n        preHandler: authPreHandler,\n      }, async (request, reply) => {\n        const { runId } = request.params as { runId: string };\n        const { stepId } = (request.body ?? {}) as { stepId: string };\n        if (!stepId) {\n          return reply.status(400).send({ success: false, error: 'stepId is required' });\n        }\n        const run = await wf.engine.rewindTo!(runId, stepId);\n        return { success: true, data: run };\n      });\n    }\n  }\n\n  // List all registered workflows\n  fastify.get(prefix, {\n    preHandler: authPreHandler,\n  }, async () => {\n    const list = Array.from(registry.entries()).map(([id, wf]) => ({\n      id,\n      name: wf.definition.name ?? id,\n      steps: Object.keys(wf.definition.steps),\n    }));\n    return { success: true, data: list };\n  });\n\n  // Graceful shutdown\n  fastify.addHook('onClose', async () => {\n    for (const wf of registry.values()) {\n      wf.shutdown?.();\n    }\n  });\n};\n\n/** Pluggable streamline integration for Arc */\nexport const streamlinePlugin: FastifyPluginAsync<StreamlinePluginOptions> = streamlinePluginImpl;\nexport default streamlinePlugin;\n"],"mappings":"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"}

package/dist/integrations/websocket.d.mts

@@ -0,0 +1,83 @@
+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 };
+//# sourceMappingURL=websocket.d.mts.map

package/dist/integrations/websocket.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"websocket.d.mts","names":[],"sources":["../../src/integrations/websocket.ts"],"mappings":";;;UAwCiB,eAAA;EACf,EAAA;EACA,MAAA;IAAU,IAAA,CAAK,IAAA;IAAqB,KAAA;IAAe,UAAA;EAAA;EACnD,aAAA,EAAe,GAAA;EACf,MAAA;EACA,cAAA;EACA,QAAA,GAAW,MAAA;AAAA;AAAA,UAGI,gBAAA;EACf,IAAA;EACA,QAAA;EACA,OAAA;EACA,IAAA;AAAA;AAAA,UAGe,sBAAA;EAYA;EAVf,IAAA;EAYA;EAVA,IAAA;EAsBA;EApBA,SAAA;EAqBE;EAnBF,iBAAA;EAqBe;EAnBf,YAAA,IACE,OAAA,cACG,OAAA;IAAU,MAAA;IAAiB,cAAA;EAAA;EAwB9B;EAtBF,iBAAA;EAuBE;;;;;;EAhBF,WAAA;EAqBwB;;;;EAhBxB,UAAA,IACE,MAAA,EAAQ,eAAA,EACR,IAAA,uBACa,OAAA;EAoBJ;EAlBX,eAAA;;EAEA,yBAAA;EA6G6B;EA3G7B,SAAA,IACE,MAAA,EAAQ,eAAA,EACR,OAAA,EAAS,gBAAA,YACC,OAAA;EA+GW;EA7GvB,SAAA,IAAa,MAAA,EAAQ,eAAA,YAA2B,OAAA;EAUxC;EARR,YAAA,IAAgB,MAAA,EAAQ,eAAA,YAA2B,OAAA;AAAA;AAAA,cAOxC,WAAA;EAAA,QACH,KAAA;EAAA,QACA,OAAA;EAAA,QACA,UAAA;cAEI,UAAA;EAIZ,SAAA,CAAU,MAAA,EAAQ,eAAA;EAIlB,YAAA,CAAa,QAAA;EAiBb,SAAA,CAAU,QAAA,UAAkB,IAAA;EAc5B,WAAA,CAAY,QAAA,UAAkB,IAAA;EAY9B,SAAA,CAAU,IAAA,UAAc,OAAA,UAAiB,eAAA;EAiBzC,cAAA,CAAe,cAAA,UAAwB,IAAA,UAAc,OAAA;EAoBrD,SAAA,CAAU,QAAA,WAAmB,eAAA;EAI7B,QAAA,CAAA;IACE,OAAA;IACA,KAAA;IACA,aAAA,EAAe,MAAA;EAAA;AAAA;;cAoUN,eAAA,EAGP,kBAAA,CAAmB,sBAAA"}

package/dist/integrations/websocket.mjs

@@ -0,0 +1,289 @@
+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 };
+//# sourceMappingURL=websocket.mjs.map

package/dist/integrations/websocket.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"websocket.mjs","names":[],"sources":["../../src/integrations/websocket.ts"],"sourcesContent":["/**\n * @classytic/arc — WebSocket Integration\n *\n * Pluggable adapter that wires @fastify/websocket into Arc's resource system.\n * Provides room-based subscriptions, auto-broadcasts resource CRUD events,\n * and respects Arc's auth/org scoping.\n *\n * This is a SEPARATE subpath import — only loaded when explicitly used:\n *   import { websocketPlugin } from '@classytic/arc/integrations/websocket';\n *\n * Requires: @fastify/websocket (peer dependency)\n *\n * NOTE: WebSocket requires persistent connections. This does NOT work on\n * serverless platforms (Lambda, Vercel). Only use on persistent runtimes\n * (Docker, VPS, K8s, Cloud Run with min-instances > 0).\n *\n * @example\n * ```typescript\n * import { websocketPlugin } from '@classytic/arc/integrations/websocket';\n *\n * await fastify.register(websocketPlugin, {\n *   path: '/ws',\n *   auth: true,\n *   resources: ['product', 'order'], // Auto-broadcast CRUD events\n *   heartbeatInterval: 30000,\n * });\n *\n * // Client connects to ws://localhost:3000/ws\n * // Server pushes: { type: 'product.created', data: { ... } }\n * // Client sends:  { type: 'subscribe', resource: 'product' }\n * // Client sends:  { type: 'unsubscribe', resource: 'product' }\n * ```\n */\nimport type { FastifyInstance, FastifyPluginAsync } from \"fastify\";\nimport fp from \"fastify-plugin\";\n\n// ============================================================================\n// Types\n// ============================================================================\n\nexport interface WebSocketClient {\n  id: string;\n  socket: { send(data: string): void; close(): void; readyState: number };\n  subscriptions: Set<string>;\n  userId?: string;\n  organizationId?: string;\n  metadata?: Record<string, unknown>;\n}\n\nexport interface WebSocketMessage {\n  type: string;\n  resource?: string;\n  channel?: string;\n  data?: unknown;\n}\n\nexport interface WebSocketPluginOptions {\n  /** WebSocket endpoint path (default: '/ws') */\n  path?: string;\n  /** Require authentication for WebSocket connections (default: true) */\n  auth?: boolean;\n  /** Resources to auto-broadcast CRUD events for */\n  resources?: string[];\n  /** Heartbeat interval in ms (default: 30000). Set 0 to disable. */\n  heartbeatInterval?: number;\n  /** Custom authentication function for WebSocket upgrade */\n  authenticate?: (\n    request: unknown,\n  ) => Promise<{ userId?: string; organizationId?: string } | null>;\n  /** Max clients per resource subscription (default: 10000) */\n  maxClientsPerRoom?: number;\n  /**\n   * Expose a stats endpoint at `{path}/stats`.\n   * - `false` (default): stats endpoint is not registered\n   * - `true`: registered without auth\n   * - `'authenticated'`: guarded by `fastify.authenticate` if available\n   */\n  exposeStats?: boolean | \"authenticated\";\n  /**\n   * Authorize room subscriptions. Return true to allow, false to deny.\n   * Called before every subscribe. If not provided, all rooms are allowed.\n   */\n  roomPolicy?: (\n    client: WebSocketClient,\n    room: string,\n  ) => boolean | Promise<boolean>;\n  /** Maximum message size in bytes from client (default: 16384 = 16KB). Messages exceeding this are dropped. */\n  maxMessageBytes?: number;\n  /** Maximum subscriptions per client (default: 100). Prevents resource exhaustion. */\n  maxSubscriptionsPerClient?: number;\n  /** Custom message handler */\n  onMessage?: (\n    client: WebSocketClient,\n    message: WebSocketMessage,\n  ) => void | Promise<void>;\n  /** Called when a client connects */\n  onConnect?: (client: WebSocketClient) => void | Promise<void>;\n  /** Called when a client disconnects */\n  onDisconnect?: (client: WebSocketClient) => void | Promise<void>;\n}\n\n// ============================================================================\n// Room Manager — manages subscriptions efficiently\n// ============================================================================\n\nexport class RoomManager {\n  private rooms = new Map<string, Set<string>>(); // room → clientIds\n  private clients = new Map<string, WebSocketClient>(); // clientId → client\n  private maxPerRoom: number;\n\n  constructor(maxPerRoom = 10000) {\n    this.maxPerRoom = maxPerRoom;\n  }\n\n  addClient(client: WebSocketClient): void {\n    this.clients.set(client.id, client);\n  }\n\n  removeClient(clientId: string): void {\n    const client = this.clients.get(clientId);\n    if (!client) return;\n\n    // Remove from all rooms\n    for (const room of client.subscriptions) {\n      const members = this.rooms.get(room);\n      if (members) {\n        members.delete(clientId);\n        if (members.size === 0) this.rooms.delete(room);\n      }\n    }\n\n    client.subscriptions.clear();\n    this.clients.delete(clientId);\n  }\n\n  subscribe(clientId: string, room: string): boolean {\n    const client = this.clients.get(clientId);\n    if (!client) return false;\n\n    // Check room capacity\n    const members = this.rooms.get(room);\n    if (members && members.size >= this.maxPerRoom) return false;\n\n    if (!this.rooms.has(room)) this.rooms.set(room, new Set());\n    this.rooms.get(room)!.add(clientId);\n    client.subscriptions.add(room);\n    return true;\n  }\n\n  unsubscribe(clientId: string, room: string): void {\n    const client = this.clients.get(clientId);\n    if (!client) return;\n\n    const members = this.rooms.get(room);\n    if (members) {\n      members.delete(clientId);\n      if (members.size === 0) this.rooms.delete(room);\n    }\n    client.subscriptions.delete(room);\n  }\n\n  broadcast(room: string, message: string, excludeClientId?: string): void {\n    const members = this.rooms.get(room);\n    if (!members) return;\n\n    for (const clientId of members) {\n      if (clientId === excludeClientId) continue;\n      const client = this.clients.get(clientId);\n      if (client && client.socket.readyState === 1) {\n        try {\n          client.socket.send(message);\n        } catch {\n          // Client disconnected, will be cleaned up\n        }\n      }\n    }\n  }\n\n  broadcastToOrg(organizationId: string, room: string, message: string): void {\n    const members = this.rooms.get(room);\n    if (!members) return;\n\n    for (const clientId of members) {\n      const client = this.clients.get(clientId);\n      if (\n        client &&\n        client.organizationId === organizationId &&\n        client.socket.readyState === 1\n      ) {\n        try {\n          client.socket.send(message);\n        } catch {\n          // Client disconnected\n        }\n      }\n    }\n  }\n\n  getClient(clientId: string): WebSocketClient | undefined {\n    return this.clients.get(clientId);\n  }\n\n  getStats(): {\n    clients: number;\n    rooms: number;\n    subscriptions: Record<string, number>;\n  } {\n    const subscriptions: Record<string, number> = {};\n    for (const [room, members] of this.rooms) {\n      subscriptions[room] = members.size;\n    }\n    return {\n      clients: this.clients.size,\n      rooms: this.rooms.size,\n      subscriptions,\n    };\n  }\n}\n\n// ============================================================================\n// Plugin Implementation\n// ============================================================================\n\nconst websocketPluginImpl: FastifyPluginAsync<WebSocketPluginOptions> = async (\n  fastify: FastifyInstance,\n  options: WebSocketPluginOptions,\n) => {\n  // Instance-scoped counter — no global leak across test runs or multiple app instances\n  let clientCounter = 0;\n  const {\n    path = \"/ws\",\n    auth = true,\n    resources = [],\n    heartbeatInterval = 30000,\n    authenticate: customAuth,\n    maxClientsPerRoom = 10000,\n    roomPolicy,\n    maxMessageBytes = 16384,\n    maxSubscriptionsPerClient = 100,\n    exposeStats = false,\n    onMessage,\n    onConnect,\n    onDisconnect,\n  } = options;\n\n  // Fail-closed: throw early if auth required but no authenticator available\n  if (auth && !customAuth && !fastify.hasDecorator(\"authenticate\")) {\n    throw new Error(\n      \"[arc-websocket] auth is true but fastify.authenticate is not registered. \" +\n        \"Register an auth plugin before WebSocket, provide a custom authenticate function, or set auth: false.\",\n    );\n  }\n\n  const rooms = new RoomManager(maxClientsPerRoom);\n\n  // Decorate fastify with room manager for external access\n  if (!fastify.hasDecorator(\"ws\")) {\n    fastify.decorate(\"ws\", {\n      rooms,\n      broadcast: (room: string, data: unknown) => {\n        rooms.broadcast(\n          room,\n          JSON.stringify({ type: \"broadcast\", channel: room, data }),\n        );\n      },\n      broadcastToOrg: (orgId: string, room: string, data: unknown) => {\n        rooms.broadcastToOrg(\n          orgId,\n          room,\n          JSON.stringify({ type: \"broadcast\", channel: room, data }),\n        );\n      },\n      getStats: () => rooms.getStats(),\n    });\n  }\n\n  // Wire into Arc's event bus for auto-broadcasting resource events\n  // Track unsubscribe handles so we can clean up on server close\n  const eventUnsubscribers: Array<() => void> = [];\n\n  if (resources.length > 0 && fastify.events?.subscribe) {\n    for (const resourceName of resources) {\n      for (const op of [\"created\", \"updated\", \"deleted\"] as const) {\n        const unsub = await fastify.events.subscribe(\n          `${resourceName}.${op}`,\n          async (event: any) => {\n            const room = resourceName;\n            const payload = JSON.stringify({\n              type: `${resourceName}.${op}`,\n              data: event.payload,\n              meta: {\n                timestamp: event.meta?.timestamp,\n                userId: event.meta?.userId,\n                organizationId: event.meta?.organizationId,\n              },\n            });\n\n            // If org-scoped, only broadcast to clients in same org\n            if (event.meta?.organizationId) {\n              rooms.broadcastToOrg(event.meta.organizationId, room, payload);\n            } else {\n              rooms.broadcast(room, payload);\n            }\n          },\n        );\n        eventUnsubscribers.push(unsub);\n      }\n    }\n  }\n\n  // Register WebSocket route\n  // Requires @fastify/websocket to be registered beforehand\n  fastify.get(\n    path,\n    { websocket: true } as any,\n    async (socket: any, request: any) => {\n      const clientId = `ws_${++clientCounter}_${Date.now()}`;\n\n      // Authentication\n      let userId: string | undefined;\n      let organizationId: string | undefined;\n\n      if (auth) {\n        if (customAuth) {\n          const result = await customAuth(request);\n          if (!result) {\n            socket.close(4001, \"Unauthorized\");\n            return;\n          }\n          userId = result.userId;\n          organizationId = result.organizationId;\n        } else {\n          // Run fastify.authenticate to parse token and populate request.user\n          // during the WebSocket handshake. Without this, request.user is never\n          // set and all authenticated WS connections are rejected.\n          if (fastify.authenticate) {\n            try {\n              // Create a minimal reply-like object for authenticate()\n              // that captures the status code without sending a real HTTP response\n              let rejected = false;\n              const fakeReply = {\n                code(_statusCode: number) { rejected = true; return fakeReply; },\n                send() { return fakeReply; },\n                sent: false,\n              };\n              await (fastify.authenticate as any)(request, fakeReply);\n              if (rejected) {\n                socket.close(4001, \"Unauthorized\");\n                return;\n              }\n            } catch {\n              socket.close(4001, \"Unauthorized\");\n              return;\n            }\n          }\n\n          if (request.user) {\n            userId = (request.user as any).id ?? (request.user as any).sub;\n            organizationId = (request.scope as any)?.organizationId;\n          } else {\n            socket.close(4001, \"Unauthorized\");\n            return;\n          }\n        }\n      }\n\n      const client: WebSocketClient = {\n        id: clientId,\n        socket,\n        subscriptions: new Set(),\n        userId,\n        organizationId,\n      };\n\n      rooms.addClient(client);\n      await onConnect?.(client);\n\n      // Send connection confirmation\n      socket.send(\n        JSON.stringify({\n          type: \"connected\",\n          clientId,\n          resources: resources,\n        }),\n      );\n\n      // Heartbeat\n      let heartbeatTimer: ReturnType<typeof setInterval> | undefined;\n      if (heartbeatInterval > 0) {\n        heartbeatTimer = setInterval(() => {\n          if (socket.readyState === 1) {\n            socket.send(\n              JSON.stringify({ type: \"ping\", timestamp: Date.now() }),\n            );\n          }\n        }, heartbeatInterval);\n      }\n\n      // Handle incoming messages\n      socket.on(\"message\", async (raw: Buffer | string) => {\n        // Message size cap — drop oversized messages\n        const rawSize = typeof raw === \"string\" ? Buffer.byteLength(raw) : raw.length;\n        if (rawSize > maxMessageBytes) {\n          socket.send(\n            JSON.stringify({ type: \"error\", error: \"Message too large\" }),\n          );\n          return;\n        }\n\n        try {\n          const msg: WebSocketMessage = JSON.parse(\n            typeof raw === \"string\" ? raw : raw.toString(),\n          );\n\n          switch (msg.type) {\n            case \"subscribe\": {\n              const room = msg.resource ?? msg.channel;\n              if (room) {\n                // Subscription limit per client\n                if (client.subscriptions.size >= maxSubscriptionsPerClient) {\n                  socket.send(\n                    JSON.stringify({\n                      type: \"error\",\n                      channel: room,\n                      error: \"Subscription limit reached\",\n                    }),\n                  );\n                  break;\n                }\n\n                // Room authorization policy\n                if (roomPolicy) {\n                  const allowed = await roomPolicy(client, room);\n                  if (!allowed) {\n                    socket.send(\n                      JSON.stringify({\n                        type: \"error\",\n                        channel: room,\n                        error: \"Subscription denied\",\n                      }),\n                    );\n                    break;\n                  }\n                }\n\n                const ok = rooms.subscribe(clientId, room);\n                socket.send(\n                  JSON.stringify({\n                    type: ok ? \"subscribed\" : \"error\",\n                    channel: room,\n                    ...(ok ? {} : { error: \"Room at capacity\" }),\n                  }),\n                );\n              }\n              break;\n            }\n\n            case \"unsubscribe\": {\n              const room = msg.resource ?? msg.channel;\n              if (room) {\n                rooms.unsubscribe(clientId, room);\n                socket.send(\n                  JSON.stringify({ type: \"unsubscribed\", channel: room }),\n                );\n              }\n              break;\n            }\n\n            case \"pong\":\n              // Heartbeat response, ignore\n              break;\n\n            default:\n              // Forward to custom handler\n              await onMessage?.(client, msg);\n              break;\n          }\n        } catch {\n          socket.send(\n            JSON.stringify({ type: \"error\", error: \"Invalid message format\" }),\n          );\n        }\n      });\n\n      // Cleanup on disconnect\n      socket.on(\"close\", async () => {\n        if (heartbeatTimer) clearInterval(heartbeatTimer);\n        await onDisconnect?.(client);\n        rooms.removeClient(clientId);\n      });\n\n      socket.on(\"error\", () => {\n        if (heartbeatTimer) clearInterval(heartbeatTimer);\n        rooms.removeClient(clientId);\n      });\n    },\n  );\n\n  // Stats endpoint (opt-in)\n  if (exposeStats === true) {\n    fastify.get(`${path}/stats`, async () => {\n      return { success: true, data: rooms.getStats() };\n    });\n  } else if (exposeStats === \"authenticated\") {\n    if (fastify.hasDecorator(\"authenticate\")) {\n      fastify.get(\n        `${path}/stats`,\n        { preHandler: fastify.authenticate } as any,\n        async () => {\n          return { success: true, data: rooms.getStats() };\n        },\n      );\n    } else {\n      fastify.log.warn(\n        'arc-websocket: exposeStats is \"authenticated\" but fastify.authenticate is not registered — stats endpoint skipped',\n      );\n    }\n  }\n\n  // Cleanup on server close — unsubscribe event handlers to prevent leaks\n  fastify.addHook(\"onClose\", async () => {\n    for (const unsub of eventUnsubscribers) {\n      unsub();\n    }\n    eventUnsubscribers.length = 0;\n  });\n};\n\n/** Pluggable WebSocket integration for Arc */\nexport const websocketPlugin = fp(websocketPluginImpl, {\n  name: \"arc-websocket\",\n  fastify: \"5.x\",\n}) as FastifyPluginAsync<WebSocketPluginOptions>;\nexport default websocketPlugin;\n"],"mappings":"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"}

package/dist/interface-B01JvPVc.d.mts

@@ -0,0 +1,78 @@
+//#region src/idempotency/stores/interface.d.ts
+/**
+ * Idempotency Store Interface
+ *
+ * Defines the contract for idempotency key storage backends.
+ * Implement this interface for custom stores (Redis, DynamoDB, etc.)
+ */
+interface IdempotencyResult {
+  /** The idempotency key */
+  key: string;
+  /** HTTP status code of the cached response */
+  statusCode: number;
+  /** Response headers to replay */
+  headers: Record<string, string>;
+  /** Response body */
+  body: unknown;
+  /** When this entry was created */
+  createdAt: Date;
+  /** When this entry expires */
+  expiresAt: Date;
+}
+interface IdempotencyLock {
+  /** The idempotency key being locked */
+  key: string;
+  /** Request ID that holds the lock */
+  requestId: string;
+  /** When the lock was acquired */
+  lockedAt: Date;
+  /** When the lock expires (auto-release) */
+  expiresAt: Date;
+}
+interface IdempotencyStore {
+  /** Store name for logging */
+  readonly name: string;
+  /**
+   * Get a cached result for an idempotency key.
+   * Returns undefined if not found or expired.
+   */
+  get(key: string): Promise<IdempotencyResult | undefined>;
+  /**
+   * Store a result for an idempotency key.
+   * TTL is handled by the store implementation.
+   */
+  set(key: string, result: Omit<IdempotencyResult, 'key'>): Promise<void>;
+  /**
+   * Try to acquire a lock for processing a key.
+   * Returns true if lock acquired, false if already locked.
+   */
+  tryLock(key: string, requestId: string, ttlMs: number): Promise<boolean>;
+  /** Release a lock after processing complete */
+  unlock(key: string, requestId: string): Promise<void>;
+  /** Check if a key is currently locked */
+  isLocked(key: string): Promise<boolean>;
+  /** Delete a cached result by exact key */
+  delete(key: string): Promise<void>;
+  /**
+   * Delete all cached results whose key starts with the given prefix.
+   * Used by invalidate() to clear entries by raw idempotency key
+   * regardless of fingerprint.
+   * Returns the number of entries deleted.
+   */
+  deleteByPrefix(prefix: string): Promise<number>;
+  /**
+   * Find the first cached result whose key starts with the given prefix.
+   * Used by has() to check if any entry exists for a raw idempotency key.
+   * Returns undefined if no matching entry found.
+   */
+  findByPrefix(prefix: string): Promise<IdempotencyResult | undefined>;
+  /** Close the store (cleanup connections) */
+  close?(): Promise<void>;
+}
+/**
+ * Helper to create a result object
+ */
+declare function createIdempotencyResult(statusCode: number, body: unknown, headers: Record<string, string>, ttlMs: number): Omit<IdempotencyResult, 'key'>;
+//#endregion
+export { createIdempotencyResult as i, IdempotencyResult as n, IdempotencyStore as r, IdempotencyLock as t };
+//# sourceMappingURL=interface-B01JvPVc.d.mts.map

package/dist/interface-B01JvPVc.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"interface-B01JvPVc.d.mts","names":[],"sources":["../src/idempotency/stores/interface.ts"],"mappings":";;AAOA;;;;;UAAiB,iBAAA;EAYA;EAVf,GAAA;EAAA;EAEA,UAAA;EAEA;EAAA,OAAA,EAAS,MAAA;EAET;EAAA,IAAA;EAEW;EAAX,SAAA,EAAW,IAAA;EAEA;EAAX,SAAA,EAAW,IAAA;AAAA;AAAA,UAGI,eAAA;EAAe;EAE9B,GAAA;EAMe;EAJf,SAAA;EAAA;EAEA,QAAA,EAAU,IAAA;EAAA;EAEV,SAAA,EAAW,IAAA;AAAA;AAAA,UAGI,gBAAA;EAHA;EAAA,SAKN,IAAA;EAFsB;;;;EAQ/B,GAAA,CAAI,GAAA,WAAc,OAAA,CAAQ,iBAAA;EAMD;;;;EAAzB,GAAA,CAAI,GAAA,UAAa,MAAA,EAAQ,IAAA,CAAK,iBAAA,WAA4B,OAAA;EAerC;;;;EATrB,OAAA,CAAQ,GAAA,UAAa,SAAA,UAAmB,KAAA,WAAgB,OAAA;EA2BvC;EAxBjB,MAAA,CAAO,GAAA,UAAa,SAAA,WAAoB,OAAA;EArB/B;EAwBT,QAAA,CAAS,GAAA,WAAc,OAAA;EAlBnB;EAqBJ,MAAA,CAAO,GAAA,WAAc,OAAA;EArBK;;;;;;EA6B1B,cAAA,CAAe,MAAA,WAAiB,OAAA;EAjBhC;;;;;EAwBA,YAAA,CAAa,MAAA,WAAiB,OAAA,CAAQ,iBAAA;EArB/B;EAwBP,KAAA,KAAU,OAAA;AAAA;;;;iBAMI,uBAAA,CACd,UAAA,UACA,IAAA,WACA,OAAA,EAAS,MAAA,kBACT,KAAA,WACC,IAAA,CAAK,iBAAA"}