@classytic/arc 2.2.5 → 2.4.1

package/dist/index.mjs

@@ -1,48 +1,95 @@
-import { a as DEFAULT_SORT, c as HOOK_OPERATIONS, d as MAX_REGEX_LENGTH, f as MAX_SEARCH_LENGTH, h as SYSTEM_FIELDS, i as DEFAULT_MAX_LIMIT, l as HOOK_PHASES, m as RESERVED_QUERY_PARAMS, n as DEFAULT_ID_FIELD, o as DEFAULT_TENANT_FIELD, p as MUTATION_OPERATIONS, r as DEFAULT_LIMIT, s as DEFAULT_UPDATE_METHOD, t as CRUD_OPERATIONS, u as MAX_FILTER_DEPTH } from "./constants-DdXFXQtN.mjs";
-import { a as createMongooseAdapter, i as MongooseAdapter, r as createPrismaAdapter, t as PrismaAdapter } from "./prisma-DJbMt3yf.mjs";
-import { a as validateResourceConfig, g as BaseController, i as formatValidationErrors, l as pipe, m as getControllerScope, n as defineResource, r as assertValidConfig, t as ResourceDefinition } from "./defineResource-DO9ONe_D.mjs";
-import { n as applyFieldWritePermissions, r as fields, t as applyFieldReadPermissions } from "./fields-CTd_CrKr.mjs";
-import { i as NotFoundError, l as UnauthorizedError, r as ForbiddenError, t as ArcError, u as ValidationError } from "./errors-DBANPbGr.mjs";
-import { t as requestContext } from "./requestContext-xi6OKBL-.mjs";
-import { a as presets_exports, c as readOnly, i as ownerWithAdminBypass, n as authenticated, o as publicRead, r as fullPublic, s as publicReadAdminWrite, t as adminOnly } from "./presets-CeFtfDR8.mjs";
-import { allOf, allowPublic, anyOf, createDynamicPermissionMatrix, createOrgPermissions, denyAll, requireAuth, requireOrgMembership, requireOrgRole, requireOwnership, requireRoles, requireTeamMembership, when } from "./permissions/index.mjs";
-import { n as configureArcLogger, t as arcLog } from "./logger-ByrvQWZO.mjs";
-
-//#region src/pipeline/guard.ts
+import { a as DEFAULT_SORT, c as HOOK_OPERATIONS, d as MAX_REGEX_LENGTH, f as MAX_SEARCH_LENGTH, h as SYSTEM_FIELDS, i as DEFAULT_MAX_LIMIT, l as HOOK_PHASES, m as RESERVED_QUERY_PARAMS, n as DEFAULT_ID_FIELD, o as DEFAULT_TENANT_FIELD, p as MUTATION_OPERATIONS, r as DEFAULT_LIMIT, s as DEFAULT_UPDATE_METHOD, t as CRUD_OPERATIONS, u as MAX_FILTER_DEPTH } from "./constants-Cxde4rpC.mjs";
+import { a as createMongooseAdapter, i as MongooseAdapter, r as createPrismaAdapter, t as PrismaAdapter } from "./adapters-DTC4Ug66.mjs";
+import { t as BaseController } from "./BaseController-CkM5dUh_.mjs";
+import { n as applyFieldWritePermissions, r as fields, t as applyFieldReadPermissions } from "./fields-ipsbIRPK.mjs";
+import { t as requestContext } from "./requestContext-DYtmNpm5.mjs";
+import { i as NotFoundError, l as UnauthorizedError, r as ForbiddenError, t as ArcError, u as ValidationError } from "./errors-rxhfP7Hf.mjs";
+import { a as validateResourceConfig, f as getControllerScope, i as formatValidationErrors, m as pipe, n as defineResource, r as assertValidConfig, t as ResourceDefinition } from "./defineResource-D9aY5Cy6.mjs";
+import { _ as ownerWithAdminBypass, a as createOrgPermissions, b as publicReadAdminWrite, c as requireOrgMembership, d as requireRoles, f as requireTeamMembership, g as fullPublic, h as authenticated, i as createDynamicPermissionMatrix, l as requireOrgRole, m as adminOnly, n as allowPublic, o as denyAll, p as when, r as anyOf, s as requireAuth, t as allOf, u as requireOwnership, v as presets_exports, x as readOnly, y as publicRead } from "./permissions-CA5zg0yK.mjs";
+import { n as configureArcLogger, t as arcLog } from "./logger-Dz3j1ItV.mjs";
+//#region src/middleware/middleware.ts
 /**
-* Create a named guard.
+* Named Middleware — Priority-based, conditional middleware execution.
 *
-* @param name - Guard name (for debugging/introspection)
-* @param handlerOrOptions - Handler function or options object
+* Named middleware replaces flat arrays with structured, inspectable middleware
+* that runs in priority order and supports conditional execution.
+*
+* @example
+* ```typescript
+* import { middleware } from '@classytic/arc';
+*
+* const verifyEmail = middleware('verifyEmail', {
+*   operations: ['create', 'update'],
+*   priority: 5,
+*   when: (req) => !req.user?.emailVerified,
+*   handler: async (req, reply) => {
+*     reply.code(403).send({ error: 'Email verification required' });
+*   },
+* });
+*
+* const rateLimit = middleware('rateLimit', {
+*   priority: 1,
+*   handler: async (req, reply) => {
+*     // rate limit logic
+*   },
+* });
+*
+* const productResource = defineResource({
+*   name: 'product',
+*   adapter,
+*   middlewares: sortMiddlewares([verifyEmail, rateLimit]),
+* });
+* ```
 */
-function guard(name, handlerOrOptions) {
-	const opts = typeof handlerOrOptions === "function" ? { handler: handlerOrOptions } : handlerOrOptions;
+/**
+* Create a named middleware with priority and conditions.
+*/
+function middleware(name, options) {
 	return {
-		_type: "guard",
 		name,
-		operations: opts.operations,
-		handler: opts.handler
+		operations: options.operations,
+		priority: options.priority ?? 10,
+		when: options.when,
+		handler: options.handler
 	};
 }
-
+/**
+* Sort named middlewares by priority (ascending — lower runs first).
+* Returns a MiddlewareConfig map keyed by operation, ready to pass to `defineResource()`.
+*/
+function sortMiddlewares(middlewares) {
+	const sorted = [...middlewares].sort((a, b) => a.priority - b.priority);
+	const operations = CRUD_OPERATIONS;
+	const result = {};
+	for (const op of operations) {
+		const applicable = sorted.filter((m) => !m.operations || m.operations.length === 0 || m.operations.includes(op));
+		if (applicable.length > 0) result[op] = applicable.map((m) => {
+			if (!m.when) return m.handler;
+			const wrapped = async (request, reply) => {
+				if (await m.when?.(request)) return m.handler(request, reply);
+			};
+			return wrapped;
+		});
+	}
+	return result;
+}
 //#endregion
-//#region src/pipeline/transform.ts
+//#region src/pipeline/guard.ts
 /**
-* Create a named transform.
+* Create a named guard.
 *
-* @param name - Transform name (for debugging/introspection)
+* @param name - Guard name (for debugging/introspection)
 * @param handlerOrOptions - Handler function or options object
 */
-function transform(name, handlerOrOptions) {
+function guard(name, handlerOrOptions) {
 	const opts = typeof handlerOrOptions === "function" ? { handler: handlerOrOptions } : handlerOrOptions;
 	return {
-		_type: "transform",
+		_type: "guard",
 		name,
 		operations: opts.operations,
 		handler: opts.handler
 	};
 }
-
 //#endregion
 //#region src/pipeline/intercept.ts
 /**
@@ -60,45 +107,25 @@ function intercept(name, handlerOrOptions) {
 		handler: opts.handler
 	};
 }
-
 //#endregion
-//#region src/middleware/middleware.ts
+//#region src/pipeline/transform.ts
 /**
-* Create a named middleware with priority and conditions.
+* Create a named transform.
+*
+* @param name - Transform name (for debugging/introspection)
+* @param handlerOrOptions - Handler function or options object
 */
-function middleware(name, options) {
+function transform(name, handlerOrOptions) {
+	const opts = typeof handlerOrOptions === "function" ? { handler: handlerOrOptions } : handlerOrOptions;
 	return {
+		_type: "transform",
 		name,
-		operations: options.operations,
-		priority: options.priority ?? 10,
-		when: options.when,
-		handler: options.handler
+		operations: opts.operations,
+		handler: opts.handler
 	};
 }
-/**
-* Sort named middlewares by priority (ascending — lower runs first).
-* Returns a MiddlewareConfig map keyed by operation, ready to pass to `defineResource()`.
-*/
-function sortMiddlewares(middlewares) {
-	const sorted = [...middlewares].sort((a, b) => a.priority - b.priority);
-	const operations = CRUD_OPERATIONS;
-	const result = {};
-	for (const op of operations) {
-		const applicable = sorted.filter((m) => !m.operations || m.operations.length === 0 || m.operations.includes(op));
-		if (applicable.length > 0) result[op] = applicable.map((m) => {
-			if (!m.when) return m.handler;
-			const wrapped = async (request, reply) => {
-				if (await m.when(request)) return m.handler(request, reply);
-			};
-			return wrapped;
-		});
-	}
-	return result;
-}
-
 //#endregion
 //#region src/index.ts
-const version = "__ARC_VERSION__";
-
+const version = "2.4.1";
 //#endregion
-export { ArcError, BaseController, CRUD_OPERATIONS, DEFAULT_ID_FIELD, DEFAULT_LIMIT, DEFAULT_MAX_LIMIT, DEFAULT_SORT, DEFAULT_TENANT_FIELD, DEFAULT_UPDATE_METHOD, ForbiddenError, HOOK_OPERATIONS, HOOK_PHASES, MAX_FILTER_DEPTH, MAX_REGEX_LENGTH, MAX_SEARCH_LENGTH, MUTATION_OPERATIONS, MongooseAdapter, NotFoundError, PrismaAdapter, RESERVED_QUERY_PARAMS, ResourceDefinition, SYSTEM_FIELDS, UnauthorizedError, ValidationError, adminOnly, allOf, allowPublic, anyOf, applyFieldReadPermissions, applyFieldWritePermissions, arcLog, assertValidConfig, authenticated, configureArcLogger, createDynamicPermissionMatrix, createMongooseAdapter, createOrgPermissions, createPrismaAdapter, defineResource, denyAll, fields, formatValidationErrors, fullPublic, getControllerScope, guard, intercept, middleware, ownerWithAdminBypass, presets_exports as permissions, pipe, publicRead, publicReadAdminWrite, readOnly, requestContext, requireAuth, requireOrgMembership, requireOrgRole, requireOwnership, requireRoles, requireTeamMembership, sortMiddlewares, transform, validateResourceConfig, version, when };
+export { ArcError, BaseController, CRUD_OPERATIONS, DEFAULT_ID_FIELD, DEFAULT_LIMIT, DEFAULT_MAX_LIMIT, DEFAULT_SORT, DEFAULT_TENANT_FIELD, DEFAULT_UPDATE_METHOD, ForbiddenError, HOOK_OPERATIONS, HOOK_PHASES, MAX_FILTER_DEPTH, MAX_REGEX_LENGTH, MAX_SEARCH_LENGTH, MUTATION_OPERATIONS, MongooseAdapter, NotFoundError, PrismaAdapter, RESERVED_QUERY_PARAMS, ResourceDefinition, SYSTEM_FIELDS, UnauthorizedError, ValidationError, adminOnly, allOf, allowPublic, anyOf, applyFieldReadPermissions, applyFieldWritePermissions, arcLog, assertValidConfig, authenticated, configureArcLogger, createDynamicPermissionMatrix, createMongooseAdapter, createOrgPermissions, createPrismaAdapter, defineResource, denyAll, fields, formatValidationErrors, fullPublic, getControllerScope, guard, intercept, middleware, ownerWithAdminBypass, presets_exports as permissions, pipe, publicRead, publicReadAdminWrite, readOnly, requestContext, requireAuth, requireOrgMembership, requireOrgRole, requireOwnership, requireRoles, requireTeamMembership, sortMiddlewares, transform, validateResourceConfig, version, when };

package/dist/integrations/event-gateway.d.mts

@@ -1,4 +1,4 @@
-import { t as DomainEvent } from "../EventTransport-BkUDYZEb.mjs";
+import { t as DomainEvent } from "../EventTransport-wc5hSLik.mjs";
 import { WebSocketClient, WebSocketMessage } from "./websocket.mjs";
 import { FastifyPluginAsync, FastifyRequest } from "fastify";
 

package/dist/integrations/event-gateway.mjs

@@ -1,11 +1,10 @@
 import fp from "fastify-plugin";
-
 //#region src/integrations/event-gateway.ts
 const eventGatewayPluginImpl = async (fastify, opts = {}) => {
 	const { auth = true, orgScoped = false, roomPolicy, maxMessageBytes, maxSubscriptionsPerClient, authenticate } = opts;
 	if (auth && !authenticate && !fastify.hasDecorator("authenticate")) throw new Error("[arc-event-gateway] auth is true but fastify.authenticate is not registered. Register an auth plugin first, provide a custom authenticate function, or set auth: false.");
 	if (opts.sse !== false) {
-		const { default: ssePlugin } = await import("../sse-DkqQ1uxb.mjs").then((n) => n.r);
+		const { default: ssePlugin } = await import("../sse-BkViJPlT.mjs").then((n) => n.r);
 		await fastify.register(ssePlugin, {
 			path: opts.sse?.path ?? "/events/stream",
 			requireAuth: auth,
@@ -16,6 +15,12 @@ const eventGatewayPluginImpl = async (fastify, opts = {}) => {
 		});
 	}
 	if (opts.ws !== false) {
+		if (!fastify.hasDecorator("websocketServer")) try {
+			const wsPlugin = await import("@fastify/websocket");
+			await fastify.register(wsPlugin.default ?? wsPlugin);
+		} catch {
+			throw new Error("[arc-event-gateway] WebSocket support requires @fastify/websocket.\nInstall it: npm install @fastify/websocket\nOr disable WebSocket: eventGateway({ ws: false })");
+		}
 		const { websocketPlugin } = await import("./websocket.mjs");
 		await fastify.register(websocketPlugin, {
 			path: opts.ws?.path ?? "/ws",
@@ -38,6 +43,5 @@ const eventGatewayPlugin = fp(eventGatewayPluginImpl, {
 	name: "arc-event-gateway",
 	fastify: "5.x"
 });
-
 //#endregion
-export { eventGatewayPlugin as default, eventGatewayPlugin };
+export { eventGatewayPlugin as default, eventGatewayPlugin };

package/dist/integrations/index.d.mts

@@ -1,5 +1,7 @@
 import { WebSocketClient, WebSocketMessage, WebSocketPluginOptions } from "./websocket.mjs";
 import { EventGatewayOptions } from "./event-gateway.mjs";
-import { StreamlinePluginOptions, WorkflowLike, WorkflowRunLike } from "./streamline.mjs";
 import { JobDefinition, JobDispatchOptions, JobDispatcher, JobMeta, JobsPluginOptions, QueueStats } from "./jobs.mjs";
-export { type EventGatewayOptions, type JobDefinition, type JobDispatchOptions, type JobDispatcher, type JobMeta, type JobsPluginOptions, type QueueStats, type StreamlinePluginOptions, type WebSocketClient, type WebSocketMessage, type WebSocketPluginOptions, type WorkflowLike, type WorkflowRunLike };
+import { c as McpResourceConfig, f as ToolAnnotations, i as CrudOperation, l as PromptDefinition, m as ToolDefinition, n as CallToolResult, o as McpAuthResult, p as ToolContext, r as CreateMcpServerConfig, s as McpPluginOptions, t as BetterAuthHandler } from "../types-BJmgxNbF.mjs";
+import { StreamlinePluginOptions, WorkflowLike, WorkflowRunLike } from "./streamline.mjs";
+import { WebhookDeliveryRecord, WebhookManager, WebhookPluginOptions, WebhookStore, WebhookSubscription } from "./webhooks.mjs";
+export { type BetterAuthHandler, type CallToolResult, type CreateMcpServerConfig, type CrudOperation, type EventGatewayOptions, type JobDefinition, type JobDispatchOptions, type JobDispatcher, type JobMeta, type JobsPluginOptions, type McpAuthResult, type McpPluginOptions, type McpResourceConfig, type PromptDefinition, type QueueStats, type StreamlinePluginOptions, type ToolAnnotations, type ToolContext, type ToolDefinition, type WebSocketClient, type WebSocketMessage, type WebSocketPluginOptions, type WebhookDeliveryRecord, type WebhookManager, type WebhookPluginOptions, type WebhookStore, type WebhookSubscription, type WorkflowLike, type WorkflowRunLike };

package/dist/integrations/index.mjs

@@ -1 +1 @@
-export {  };
+export {};

package/dist/integrations/jobs.d.mts

@@ -10,7 +10,7 @@ interface JobDefinition<TData = unknown, TResult = unknown> {
   retries?: number;
   /** Backoff strategy */
   backoff?: {
-    type: 'exponential' | 'fixed';
+    type: "exponential" | "fixed";
     delay: number;
   };
   /** Job timeout in ms (default: 30000) */
@@ -60,7 +60,7 @@ interface JobsPluginOptions {
   defaults?: {
     retries?: number;
     backoff?: {
-      type: 'exponential' | 'fixed';
+      type: "exponential" | "fixed";
       delay: number;
     };
     timeout?: number;

package/dist/integrations/jobs.mjs

@@ -27,23 +27,49 @@ const jobsPluginImpl = async (fastify, options) => {
 		throw new Error("@classytic/arc/integrations/jobs requires \"bullmq\" package.\nInstall it: npm install bullmq");
 	}
 	const queues = /* @__PURE__ */ new Map();
+	const dlqQueues = /* @__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);
+		let dlqQueue = null;
+		if (job.deadLetterQueue != null) {
+			const dlqName = job.deadLetterQueue || `${queueName}:dead`;
+			dlqQueue = new Queue(dlqName, { connection });
+			dlqQueues.set(dlqName, dlqQueue);
+		}
+		const jobTimeout = job.timeout ?? defaults.timeout;
 		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
-			});
+			let result;
+			if (jobTimeout) {
+				let timer;
+				const timeoutPromise = new Promise((_, reject) => {
+					timer = setTimeout(() => reject(/* @__PURE__ */ new Error(`Job '${queueName}' timed out after ${jobTimeout}ms`)), jobTimeout);
+				});
+				try {
+					result = await Promise.race([job.handler(bullJob.data, meta), timeoutPromise]);
+				} finally {
+					clearTimeout(timer);
+				}
+			} else result = await job.handler(bullJob.data, meta);
+			if (bridgeEvents && fastify.events?.publish) try {
+				await fastify.events.publish(`job.${queueName}.completed`, {
+					jobId: bullJob.id,
+					data: bullJob.data,
+					result
+				});
+			} catch (err) {
+				fastify.log.warn({
+					err,
+					jobId: bullJob.id
+				}, `Failed to publish job.${queueName}.completed event`);
+			}
 			return result;
 		}, {
 			connection,
@@ -54,12 +80,35 @@ const jobsPluginImpl = async (fastify, options) => {
 			} : 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
-			});
+			const maxAttempts = job.retries ?? defaults.retries ?? 3;
+			if (dlqQueue && bullJob && bullJob.attemptsMade >= maxAttempts) try {
+				await dlqQueue.add(`${queueName}:dead`, bullJob.data, {
+					jobId: `${bullJob.id}:dlq`,
+					removeOnComplete: false
+				});
+				fastify.log.warn({
+					jobId: bullJob.id,
+					dlq: job.deadLetterQueue ?? `${queueName}:dead`
+				}, `Job moved to dead-letter queue`);
+			} catch (dlqErr) {
+				fastify.log.error({
+					err: dlqErr,
+					jobId: bullJob.id
+				}, `Failed to move job to DLQ`);
+			}
+			if (bridgeEvents && fastify.events?.publish) try {
+				await fastify.events.publish(`job.${queueName}.failed`, {
+					jobId: bullJob?.id,
+					data: bullJob?.data,
+					error: error.message,
+					attemptsMade: bullJob?.attemptsMade
+				});
+			} catch (err) {
+				fastify.log.warn({
+					err,
+					jobId: bullJob?.id
+				}, `Failed to publish job.${queueName}.failed event`);
+			}
 		});
 		workers.set(queueName, worker);
 	}
@@ -102,6 +151,7 @@ const jobsPluginImpl = async (fastify, options) => {
 			const closePromises = [];
 			for (const worker of workers.values()) closePromises.push(worker.close());
 			for (const queue of queues.values()) closePromises.push(queue.close());
+			for (const dlq of dlqQueues.values()) closePromises.push(dlq.close());
 			await Promise.all(closePromises);
 		}
 	};
@@ -118,6 +168,5 @@ const jobsPluginImpl = async (fastify, options) => {
 };
 /** Pluggable BullMQ job queue integration for Arc */
 const jobsPlugin = jobsPluginImpl;
-
 //#endregion
-export { jobsPlugin as default, jobsPlugin, defineJob };
+export { jobsPlugin as default, jobsPlugin, defineJob };

package/dist/integrations/mcp/index.d.mts

@@ -0,0 +1,219 @@
+import { Lt as ResourceDefinition } from "../../interface-DGmPxakH.mjs";
+import { a as McpAuthResolver, c as McpResourceConfig, d as SessionEntry, f as ToolAnnotations, i as CrudOperation, l as PromptDefinition, m as ToolDefinition, n as CallToolResult, o as McpAuthResult, p as ToolContext, r as CreateMcpServerConfig, s as McpPluginOptions, t as BetterAuthHandler, u as PromptResult } from "../../types-BJmgxNbF.mjs";
+import { FastifyPluginAsync } from "fastify";
+import { z } from "zod";
+
+//#region src/integrations/mcp/createMcpServer.d.ts
+/**
+ * Mutable auth ref — updated per-request by mcpPlugin.
+ * Tool handlers read from this to get the current request's auth context.
+ */
+interface AuthRef {
+  current: McpAuthResult | null;
+}
+/**
+ * Create a configured MCP server from declarative config.
+ *
+ * @param config - Server name, version, tools, prompts
+ * @returns McpServer instance (not yet connected to a transport)
+ */
+declare function createMcpServer(config: CreateMcpServerConfig, authRef?: AuthRef): Promise<McpServerInstance>;
+/** Minimal interface for McpServer — avoids hard SDK type dependency */
+interface McpServerInstance {
+  connect: (transport: unknown) => Promise<void>;
+  registerTool: (name: string, config: Record<string, unknown>, handler: (input: Record<string, unknown>, extra: Record<string, unknown>) => unknown) => unknown;
+  registerPrompt: (name: string, config: Record<string, unknown>, handler: (args: Record<string, unknown>) => unknown) => void;
+  resource: (...args: unknown[]) => void;
+}
+//#endregion
+//#region src/integrations/mcp/definePrompt.d.ts
+/** definePrompt() config */
+interface DefinePromptConfig<TArgs extends Record<string, z.ZodTypeAny>> {
+  description: string;
+  title?: string;
+  /** Flat Zod shape for prompt arguments */
+  args?: TArgs;
+  handler: (args: { [K in keyof TArgs]: z.infer<TArgs[K]> }) => PromptResult;
+}
+/**
+ * Define a type-safe MCP prompt.
+ *
+ * @param name - Prompt name (snake_case recommended)
+ * @param config - Description, args schema, handler
+ */
+declare function definePrompt<TArgs extends Record<string, z.ZodTypeAny>>(name: string, config: DefinePromptConfig<TArgs>): PromptDefinition;
+//#endregion
+//#region src/integrations/mcp/defineTool.d.ts
+/** defineTool() config — uses flat Zod shapes for SDK compatibility */
+interface DefineToolConfig<TInput extends Record<string, z.ZodTypeAny>> {
+  description: string;
+  title?: string;
+  /** Flat Zod shape: `{ name: z.string(), age: z.number() }` */
+  input?: TInput;
+  /** Flat Zod shape for structured output */
+  output?: Record<string, z.ZodTypeAny>;
+  annotations?: ToolAnnotations;
+  handler: (input: { [K in keyof TInput]: z.infer<TInput[K]> }, ctx: ToolContext) => Promise<CallToolResult>;
+}
+/**
+ * Define a type-safe MCP tool.
+ *
+ * @param name - Tool name (snake_case recommended)
+ * @param config - Tool description, input schema, annotations, handler
+ */
+declare function defineTool<TInput extends Record<string, z.ZodTypeAny>>(name: string, config: DefineToolConfig<TInput>): ToolDefinition;
+//#endregion
+//#region src/integrations/mcp/fieldRulesToZod.d.ts
+interface FieldRulesToZodOptions {
+  /** create: required enforced. update: all optional. list: filters + pagination. */
+  mode?: "create" | "update" | "list";
+  /** Fields hidden from all schemas */
+  hiddenFields?: string[];
+  /** Fields excluded from create/update schemas */
+  readonlyFields?: string[];
+  /** Extra fields to hide (e.g., from McpResourceConfig.hideFields) */
+  extraHideFields?: string[];
+  /** Filterable fields — only used in list mode */
+  filterableFields?: readonly string[];
+}
+/** Single field rule entry from Arc's schemaOptions.fieldRules */
+interface FieldRuleEntry {
+  type?: string;
+  required?: boolean;
+  systemManaged?: boolean;
+  hidden?: boolean;
+  immutable?: boolean;
+  immutableAfterCreate?: boolean;
+  optional?: boolean;
+  minLength?: number;
+  maxLength?: number;
+  min?: number;
+  max?: number;
+  enum?: string[];
+  pattern?: string;
+  description?: string;
+  [key: string]: unknown;
+}
+/**
+ * Convert Arc fieldRules to a flat Zod shape.
+ *
+ * @returns Flat shape `Record<string, z.ZodTypeAny>` — pass directly to defineTool() or registerTool()
+ */
+declare function fieldRulesToZod(fieldRules: Record<string, FieldRuleEntry> | undefined, options?: FieldRulesToZodOptions): Record<string, z.ZodTypeAny>;
+//#endregion
+//#region src/integrations/mcp/guards.d.ts
+/** Check if the tool context has an authenticated user (not anonymous/null) */
+declare function isAuthenticated(ctx: ToolContext): boolean;
+/** Check if the tool context has an organization scope */
+declare function hasOrg(ctx: ToolContext): boolean;
+/** Check if the tool context matches a specific org */
+declare function isOrg(ctx: ToolContext, orgId: string): boolean;
+/** Get the current user ID from context (undefined if anonymous/null) */
+declare function getUserId(ctx: ToolContext): string | undefined;
+/** Get the current org ID from context */
+declare function getOrgId(ctx: ToolContext): string | undefined;
+/** Create a denied (isError) CallToolResult */
+declare function denied(reason: string): CallToolResult;
+/** Guard type — checks ToolContext, returns error message or null (pass) */
+type McpGuard = (ctx: ToolContext) => string | null | Promise<string | null>;
+/**
+ * Wrap a tool handler with one or more guards.
+ * If any guard returns a string, the tool returns an error with that message.
+ *
+ * @example
+ * ```ts
+ * defineTool('delete_all', {
+ *   description: 'Delete everything',
+ *   handler: guard(requireAuth, requireOrg, async (input, ctx) => {
+ *     // only runs if authenticated + has org
+ *   }),
+ * });
+ * ```
+ */
+declare function guard(...args: [...McpGuard[], (input: Record<string, unknown>, ctx: ToolContext) => Promise<CallToolResult>]): (input: Record<string, unknown>, ctx: ToolContext) => Promise<CallToolResult>;
+/** Require authenticated user (not anonymous) */
+declare const requireAuth: McpGuard;
+/** Require organization context */
+declare const requireOrg: McpGuard;
+/** Require specific user role (checks session metadata if available) */
+declare function requireRole(...roles: string[]): McpGuard;
+/** Require specific organization */
+declare function requireOrgId(orgId: string): McpGuard;
+/**
+ * Custom guard from a predicate function.
+ *
+ * @example
+ * ```ts
+ * const businessHoursOnly = customGuard(
+ *   (ctx) => new Date().getHours() >= 9 && new Date().getHours() < 17,
+ *   'This tool is only available during business hours (9-5)',
+ * );
+ * ```
+ */
+declare function customGuard(check: (ctx: ToolContext) => boolean | Promise<boolean>, errorMessage: string): McpGuard;
+//#endregion
+//#region src/integrations/mcp/sessionCache.d.ts
+declare class McpSessionCache {
+  private sessions;
+  private ttlMs;
+  private maxSessions;
+  private cleanupTimer;
+  constructor(opts?: {
+    ttlMs?: number;
+    maxSessions?: number;
+  });
+  /** Get an existing session by ID */
+  get(sessionId: string): SessionEntry | undefined;
+  /** Store a new session */
+  set(sessionId: string, entry: SessionEntry): void;
+  /** Refresh the TTL on a session */
+  touch(sessionId: string): void;
+  /** Remove and close a session */
+  remove(sessionId: string): void;
+  /** Remove all expired sessions */
+  cleanup(): void;
+  /** Close all sessions and stop cleanup timer */
+  close(): void;
+  /** Current session count */
+  get size(): number;
+  /** Evict the oldest (least recently accessed) session */
+  private evictOldest;
+  /** Safely close a transport */
+  private closeTransport;
+}
+//#endregion
+//#region src/integrations/mcp/mcpPlugin.d.ts
+declare module "fastify" {
+  interface FastifyInstance {
+    mcp?: {
+      sessions: McpSessionCache | null;
+      toolNames: string[];
+      resourceNames: string[];
+      stateful: boolean;
+    };
+  }
+}
+declare const mcpPlugin: FastifyPluginAsync<McpPluginOptions>;
+//#endregion
+//#region src/integrations/mcp/resourceToTools.d.ts
+interface ResourceToToolsConfig extends McpResourceConfig {
+  toolNamePrefix?: string;
+  /** Per-operation tool name overrides: `{ get: 'get_job_by_id' }` */
+  names?: Partial<Record<CrudOperation, string>>;
+}
+/**
+ * Convert a ResourceDefinition into MCP ToolDefinitions.
+ *
+ * MCP tools call BaseController directly — they bypass HTTP routes entirely.
+ * Therefore `disableDefaultRoutes` does NOT affect MCP tool generation;
+ * only `disabledRoutes` (the per-operation array) controls which ops are skipped.
+ *
+ * If the resource has an adapter but no controller (e.g. `disableDefaultRoutes: true`),
+ * a lightweight BaseController is auto-created from the adapter for MCP use.
+ *
+ * @param resource - Arc resource definition
+ * @param config - Optional overrides (operations, descriptions, hideFields, prefix, names)
+ */
+declare function resourceToTools(resource: ResourceDefinition, config?: ResourceToToolsConfig): ToolDefinition[];
+//#endregion
+export { type AuthRef, type BetterAuthHandler, type CallToolResult, type CreateMcpServerConfig, type CrudOperation, type DefinePromptConfig, type DefineToolConfig, type FieldRuleEntry, type FieldRulesToZodOptions, type McpAuthResolver, type McpAuthResult, type McpGuard, type McpPluginOptions, type McpResourceConfig, type McpServerInstance, type PromptDefinition, type PromptResult, type ResourceToToolsConfig, type ToolAnnotations, type ToolContext, type ToolDefinition, createMcpServer, customGuard, definePrompt, defineTool, denied, fieldRulesToZod, getOrgId, getUserId, guard, hasOrg, isAuthenticated, isOrg, mcpPlugin, requireAuth, requireOrg, requireOrgId, requireRole, resourceToTools };