@classytic/arc 2.3.0 → 2.4.2

package/dist/types/index.mjs

@@ -1,5 +1,4 @@
-import { a as getTeamId, c as isElevated, i as getOrgRoles, l as isMember, n as PUBLIC_SCOPE, o as hasOrgAccess, r as getOrgId, s as isAuthenticated, t as AUTHENTICATED_SCOPE } from "../types-Beqn1Un7.mjs";
-
+import { a as getTeamId, c as hasOrgAccess, d as isMember, i as getOrgRoles, l as isAuthenticated, n as PUBLIC_SCOPE, r as getOrgId, t as AUTHENTICATED_SCOPE, u as isElevated } from "../types-C6TQjtdi.mjs";
 //#region src/types/index.ts
 /**
 * Extract user ID from a user object (supports both id and _id)
@@ -9,6 +8,5 @@ function getUserId(user) {
 	const id = user.id ?? user._id;
 	return id ? String(id) : void 0;
 }
-
 //#endregion
-export { AUTHENTICATED_SCOPE, PUBLIC_SCOPE, getOrgId, getOrgRoles, getTeamId, getUserId, hasOrgAccess, isAuthenticated, isElevated, isMember };
+export { AUTHENTICATED_SCOPE, PUBLIC_SCOPE, getOrgId, getOrgRoles, getTeamId, getUserId, hasOrgAccess, isAuthenticated, isElevated, isMember };

package/dist/types-BJmgxNbF.d.mts

@@ -0,0 +1,275 @@
+import { Lt as ResourceDefinition } from "./interface-DGmPxakH.mjs";
+import { z } from "zod";
+
+//#region src/integrations/mcp/types.d.ts
+/** Behavioral hints for MCP clients (tool annotations per MCP spec) */
+interface ToolAnnotations {
+  /** Tool only reads data, no side effects */
+  readOnlyHint?: boolean;
+  /** Tool may perform destructive/irreversible actions */
+  destructiveHint?: boolean;
+  /** Tool can be safely retried with same input */
+  idempotentHint?: boolean;
+  /** Tool interacts with external systems beyond this server */
+  openWorldHint?: boolean;
+}
+/** Context passed to tool handlers at invocation time */
+interface ToolContext {
+  /** Session identity — null in no-auth mode */
+  session: McpAuthResult | null;
+  /** Log to MCP client (best-effort, non-blocking) */
+  log: (level: "info" | "warning" | "error" | "debug", message: string) => Promise<void>;
+  /** Raw MCP SDK extra context (for advanced use) */
+  extra: Record<string, unknown>;
+}
+/**
+ * MCP CallToolResult — return type from tool handlers.
+ *
+ * `content` follows the MCP spec: at minimum a text item, optionally other
+ * resource/image content types. The fallback union member allows future
+ * MCP spec additions without breaking existing handlers.
+ *
+ * @example
+ * ```typescript
+ * return { content: [{ type: 'text', text: JSON.stringify(result) }] };
+ * return { content: [{ type: 'text', text: 'Not found' }], isError: true };
+ * ```
+ */
+interface CallToolResult {
+  content: Array<{
+    type: "text";
+    text: string;
+  } | {
+    type: "resource";
+    resource: {
+      uri: string;
+      mimeType?: string;
+      text?: string;
+    };
+  } | {
+    type: string;
+    [key: string]: unknown;
+  }>;
+  isError?: boolean;
+  /** Structured output for typed tool results (MCP spec extension) */
+  structuredContent?: unknown;
+}
+/**
+ * Output of defineTool() — plain data, not yet registered on a server.
+ *
+ * `inputSchema` is a flat Zod shape `{ name: z.string(), age: z.number() }` —
+ * the SDK wraps it in z.object() internally. Do NOT pass z.object() here.
+ */
+interface ToolDefinition {
+  name: string;
+  description: string;
+  title?: string;
+  /** Flat Zod shape: `{ field: z.string() }`. NOT z.object(). */
+  inputSchema?: Record<string, z.ZodTypeAny>;
+  /** Flat Zod shape for structured output validation */
+  outputSchema?: Record<string, z.ZodTypeAny>;
+  annotations?: ToolAnnotations;
+  handler: (input: Record<string, unknown>, ctx: ToolContext) => Promise<CallToolResult>;
+}
+/** Output of definePrompt() — plain data, not yet registered */
+interface PromptDefinition {
+  name: string;
+  description: string;
+  title?: string;
+  /** Flat Zod shape for prompt arguments */
+  argsSchema?: Record<string, z.ZodTypeAny>;
+  handler: (args: Record<string, unknown>) => PromptResult;
+}
+/** Prompt handler return type */
+interface PromptResult {
+  messages: Array<{
+    role: "user" | "assistant";
+    content: {
+      type: "text";
+      text: string;
+    } | {
+      type: string;
+      [key: string]: unknown;
+    };
+  }>;
+}
+/** Per-resource MCP configuration overrides */
+interface McpResourceConfig {
+  /** Which CRUD operations to expose (default: all enabled on the resource) */
+  operations?: CrudOperation[];
+  /** Override tool descriptions per operation */
+  descriptions?: Partial<Record<CrudOperation, string>>;
+  /** Fields to hide from MCP tool schemas (beyond schemaOptions.hiddenFields) */
+  hideFields?: string[];
+  /** Per-operation tool name overrides: `{ get: 'get_job_by_id' }` */
+  names?: Partial<Record<CrudOperation, string>>;
+  /** Per-resource tool name prefix (overrides global `toolNamePrefix`): `'db'` → `db_list_jobs` */
+  toolNamePrefix?: string;
+}
+/**
+ * Auth resolver function — user provides their own auth logic.
+ * Receives request headers, returns identity or null (unauthorized).
+ *
+ * @example
+ * ```ts
+ * // API key auth
+ * auth: async (headers) => {
+ *   if (headers['x-api-key'] !== process.env.MCP_API_KEY) return null;
+ *   return { userId: 'service-account', organizationId: 'org-123' };
+ * },
+ *
+ * // Static org (trusted internal network)
+ * auth: async () => ({ userId: 'internal', organizationId: 'org-main' }),
+ *
+ * // Gateway-validated JWT (token already verified by API gateway)
+ * auth: async (headers) => {
+ *   const userId = headers['x-user-id'];
+ *   const orgId = headers['x-org-id'];
+ *   return userId ? { userId, organizationId: orgId } : null;
+ * },
+ * ```
+ */
+type McpAuthResolver = (headers: Record<string, string | undefined>) => Promise<McpAuthResult | null> | McpAuthResult | null;
+/**
+ * mcpPlugin() options — Fastify plugin config.
+ *
+ * @example
+ * ```ts
+ * // No auth (dev/testing)
+ * await app.register(mcpPlugin, { resources, auth: false });
+ *
+ * // Better Auth OAuth 2.1
+ * await app.register(mcpPlugin, { resources, auth: getAuth() });
+ *
+ * // Custom auth function (API key, gateway headers, etc.)
+ * await app.register(mcpPlugin, {
+ *   resources,
+ *   auth: async (headers) => {
+ *     if (headers['x-api-key'] !== process.env.MCP_KEY) return null;
+ *     return { userId: 'bot', organizationId: 'org-1' };
+ *   },
+ * });
+ * ```
+ */
+interface McpPluginOptions {
+  /** Arc resources to expose as MCP tools */
+  resources: ResourceDefinition[];
+  /**
+   * Auth mode:
+   * - `false` — no auth, anonymous access (default)
+   * - `BetterAuthHandler` — OAuth 2.1 via Better Auth's mcp() plugin
+   * - `McpAuthResolver` — custom function that resolves identity from headers
+   */
+  auth?: BetterAuthHandler | McpAuthResolver | false;
+  /** MCP endpoint path (default: '/mcp') */
+  prefix?: string;
+  /** Server identity */
+  serverName?: string;
+  serverVersion?: string;
+  /** Instructions for the LLM — guidance on tool usage, constraints */
+  instructions?: string;
+  /** Resources to exclude by name (ignored if `include` is set) */
+  exclude?: string[];
+  /** Resources to include by name — only these get MCP tools. Takes priority over `exclude`. */
+  include?: string[];
+  /** Tool name prefix: 'crm' → 'crm_list_products' */
+  toolNamePrefix?: string;
+  /** Per-resource overrides (operations, descriptions, hideFields, names, toolNamePrefix) */
+  overrides?: Record<string, McpResourceConfig>;
+  /** Hand-written tools added alongside auto-generated ones */
+  extraTools?: ToolDefinition[];
+  /** Custom prompts */
+  extraPrompts?: PromptDefinition[];
+  /**
+   * Session mode:
+   * - `false` (default) — stateless, fresh server per request. Best for production, scaling, serverless.
+   * - `true` — stateful, sessions cached with TTL. Use for server-initiated notifications or long-lived connections.
+   */
+  stateful?: boolean;
+  /** Session TTL in ms (default: 1800000 = 30 min). Only used when stateful: true. */
+  sessionTtlMs?: number;
+  /** Max concurrent sessions (default: 1000). Only used when stateful: true. */
+  maxSessions?: number;
+  /**
+   * Auth cache TTL in ms for stateless mode (default: 5000 = 5 sec).
+   * Caches auth resolver results briefly to avoid redundant DB lookups
+   * across initialize → tools/list → tools/call sequences.
+   * Set to `0` to disable.
+   */
+  authCacheTtlMs?: number;
+}
+/** Minimal Better Auth handler interface for MCP session validation */
+interface BetterAuthHandler {
+  api: {
+    getMcpSession: (opts: {
+      headers: Record<string, string | undefined>;
+    }) => Promise<McpSession | null>;
+  };
+  handler: (request: Request) => Promise<Response>;
+}
+/** Session from Better Auth's getMcpSession() */
+interface McpSession {
+  userId: string;
+  clientId: string;
+  scopes: string;
+  activeOrganizationId?: string;
+  accessToken: string;
+  accessTokenExpiresAt: string;
+  refreshToken: string;
+  refreshTokenExpiresAt: string;
+}
+/** Resolved auth identity for a single MCP request */
+interface McpAuthResult {
+  userId: string;
+  organizationId?: string;
+  /** User roles (global) — used by guard helpers like requireRole() */
+  roles?: string[];
+  /** Org-level roles — used by guard helpers */
+  orgRoles?: string[];
+  /** Any extra metadata from the auth resolver */
+  [key: string]: unknown;
+}
+/** Internal session entry */
+interface SessionEntry {
+  transport: {
+    handleRequest: (req: unknown, res: unknown, body?: unknown) => Promise<void>;
+    close: () => void;
+  };
+  lastAccessed: number;
+  organizationId: string;
+  auth: McpAuthResult | null;
+  /** Mutable ref updated per-request — tool handler closures read from this */
+  authRef: {
+    current: McpAuthResult | null;
+  };
+}
+/**
+ * Configuration for createMcpServer() — Level 2 declarative factory.
+ *
+ * @example
+ * ```ts
+ * const server = await createMcpServer({
+ *   name: 'my-api',
+ *   version: '1.0.0',
+ *   instructions: 'Use list_users to browse users.',
+ *   tools: [
+ *     defineTool('greet', {
+ *       description: 'Say hello',
+ *       input: { name: z.string() },
+ *       handler: async ({ name }) => ({ content: [{ type: 'text', text: `Hello ${name}` }] }),
+ *     }),
+ *   ],
+ * });
+ * ```
+ */
+interface CreateMcpServerConfig {
+  name: string;
+  version?: string;
+  instructions?: string;
+  tools?: ToolDefinition[];
+  prompts?: PromptDefinition[];
+}
+/** CRUD operation type */
+type CrudOperation = "list" | "get" | "create" | "update" | "delete";
+//#endregion
+export { McpAuthResolver as a, McpResourceConfig as c, SessionEntry as d, ToolAnnotations as f, CrudOperation as i, PromptDefinition as l, ToolDefinition as m, CallToolResult as n, McpAuthResult as o, ToolContext as p, CreateMcpServerConfig as r, McpPluginOptions as s, BetterAuthHandler as t, PromptResult as u };

package/dist/{types-RLkFVgaw.d.mts → types-BNUccdcf.d.mts}

@@ -29,7 +29,7 @@ declare function getUserRoles(user: UserBase | null | undefined): string[];
 /**
  * Context passed to permission check functions
  */
-interface PermissionContext<TDoc = any> {
+interface PermissionContext<TDoc = Record<string, unknown>> {
   /** Authenticated user or null if unauthenticated */
   user: UserBase | null;
   /** Fastify request object */
@@ -80,7 +80,7 @@ interface PermissionResult {
  * };
  * ```
  */
-type PermissionCheck<TDoc = any> = ((context: PermissionContext<TDoc>) => boolean | PermissionResult | Promise<boolean | PermissionResult>) & PermissionCheckMeta;
+type PermissionCheck<TDoc = Record<string, unknown>> = ((context: PermissionContext<TDoc>) => boolean | PermissionResult | Promise<boolean | PermissionResult>) & PermissionCheckMeta;
 /**
  * Optional metadata attached to permission check functions.
  * Used for OpenAPI docs, introspection, and route-level auth decisions.

package/dist/{types-Beqn1Un7.mjs → types-C6TQjtdi.mjs}

@@ -29,10 +29,38 @@ function getOrgRoles(scope) {
 function getTeamId(scope) {
 	if (scope.kind === "member") return scope.teamId;
 }
+/**
+* Get userId from scope (available on authenticated, member, elevated).
+*
+* @example
+* ```typescript
+* import { getUserId } from '@classytic/arc/scope';
+* const userId = getUserId(request.scope);
+* ```
+*/
+function getUserId(scope) {
+	if (scope.kind === "public") return void 0;
+	return scope.userId;
+}
+/**
+* Get global user roles from scope (available on authenticated and member).
+* These are user-level roles (e.g. superadmin, finance-admin) distinct from
+* org-level roles (scope.orgRoles).
+*
+* @example
+* ```typescript
+* import { getUserRoles } from '@classytic/arc/scope';
+* const globalRoles = getUserRoles(request.scope);
+* ```
+*/
+function getUserRoles(scope) {
+	if (scope.kind === "authenticated") return scope.userRoles ?? [];
+	if (scope.kind === "member") return scope.userRoles;
+	return [];
+}
 /** Default public scope — used as initial decoration value */
 const PUBLIC_SCOPE = Object.freeze({ kind: "public" });
 /** Default authenticated scope — used when user is logged in but no org */
 const AUTHENTICATED_SCOPE = Object.freeze({ kind: "authenticated" });
-
 //#endregion
-export { getTeamId as a, isElevated as c, getOrgRoles as i, isMember as l, PUBLIC_SCOPE as n, hasOrgAccess as o, getOrgId as r, isAuthenticated as s, AUTHENTICATED_SCOPE as t };
+export { getTeamId as a, hasOrgAccess as c, isMember as d, getOrgRoles as i, isAuthenticated as l, PUBLIC_SCOPE as n, getUserId as o, getOrgId as r, getUserRoles as s, AUTHENTICATED_SCOPE as t, isElevated as u };

package/dist/{types-tKwaViYB.d.mts → types-Dt0-AI6E.d.mts}

@@ -1,18 +1,26 @@
-import { n as ElevationOptions } from "./elevation-DGo5shaX.mjs";
-import { Authenticator } from "./types/index.mjs";
-import { t as ExternalOpenApiPaths } from "./externalPaths-SyPF2tgK.mjs";
-import { i as CacheStore } from "./interface-DTbsvIWe.mjs";
-import { r as QueryCachePluginOptions } from "./queryCachePlugin-Q6SYuHZ6.mjs";
-import { i as EventTransport } from "./EventTransport-BkUDYZEb.mjs";
-import { t as EventPluginOptions } from "./eventPlugin-H6wDDjGO.mjs";
-import { o as CachingOptions, r as SSEOptions, t as ErrorHandlerOptions } from "./errorHandler-CW3OOeYq.mjs";
-import { r as IdempotencyStore } from "./interface-CSNjltAc.mjs";
+import { n as ElevationOptions } from "./elevation-Ca_yveIO.mjs";
+import { h as Authenticator } from "./interface-DGmPxakH.mjs";
+import { t as ExternalOpenApiPaths } from "./externalPaths-DpO-s7r8.mjs";
+import { i as CacheStore } from "./interface-D_BWALyZ.mjs";
+import { r as QueryCachePluginOptions } from "./queryCachePlugin-DcmETvcB.mjs";
+import { i as EventTransport } from "./EventTransport-wc5hSLik.mjs";
+import { t as EventPluginOptions } from "./eventPlugin-iGrSEmwJ.mjs";
+import { c as MetricsOptions, d as SSEOptions, m as CachingOptions, r as VersioningOptions, t as ErrorHandlerOptions } from "./errorHandler-Do4vVQ1f.mjs";
+import { r as IdempotencyStore } from "./interface-B4awm1RJ.mjs";
 import { FastifyInstance, FastifyPluginAsync, FastifyReply, FastifyRequest, FastifyServerOptions } from "fastify";
-import { FastifyCorsOptions } from "@fastify/cors";
-import { FastifyHelmetOptions } from "@fastify/helmet";
-import { RateLimitOptions } from "@fastify/rate-limit";
 
 //#region src/factory/types.d.ts
+type CorsOptions = Record<string, unknown> & {
+  origin?: unknown;
+  credentials?: boolean;
+  methods?: string[];
+  allowedHeaders?: string[];
+};
+type HelmetOptions = Record<string, unknown>;
+type RateLimitOpts = Record<string, unknown> & {
+  max?: number;
+  timeWindow?: string | number;
+};
 /**
  * Arc's built-in JWT auth
  *
@@ -44,7 +52,7 @@ import { RateLimitOptions } from "@fastify/rate-limit";
  * ```
  */
 interface JwtAuthOption {
-  type: 'jwt';
+  type: "jwt";
   /**
    * JWT configuration (optional but recommended)
    * If provided, jwt utilities are available in authenticator context
@@ -82,6 +90,18 @@ interface JwtAuthOption {
    * Property name to store user on request (default: 'user')
    */
   userProperty?: string;
+  /**
+   * Token revocation check — called after JWT verification.
+   * Return `true` to reject the token (fail-closed: errors also reject).
+   *
+   * @example
+   * ```typescript
+   * isRevoked: async (decoded) => {
+   *   return revokedTokens.has(decoded.jti as string);
+   * },
+   * ```
+   */
+  isRevoked?: (decoded: Record<string, unknown>) => boolean | Promise<boolean>;
 }
 /**
  * Better Auth adapter integration
@@ -100,7 +120,7 @@ interface JwtAuthOption {
  * ```
  */
 interface BetterAuthOption {
-  type: 'betterAuth';
+  type: "betterAuth";
   /** Better Auth adapter — pass the result of createBetterAuthAdapter() */
   betterAuth: {
     plugin: FastifyPluginAsync;
@@ -126,7 +146,7 @@ interface BetterAuthOption {
  * ```
  */
 interface CustomPluginAuthOption {
-  type: 'custom';
+  type: "custom";
   /** Custom Fastify plugin that sets up authentication */
   plugin: FastifyPluginAsync;
 }
@@ -151,7 +171,7 @@ interface CustomPluginAuthOption {
  * ```
  */
 interface CustomAuthenticatorOption {
-  type: 'authenticator';
+  type: "authenticator";
   /** Authenticate function — decorates fastify.authenticate directly */
   authenticate: (request: FastifyRequest, reply: FastifyReply) => Promise<void>;
   /**
@@ -215,14 +235,17 @@ type AuthOption = false | JwtAuthOption | BetterAuthOption | CustomPluginAuthOpt
  */
 interface CreateAppOptions {
   /** Environment preset: 'production', 'development', 'testing', or 'edge' */
-  preset?: 'production' | 'development' | 'testing' | 'edge';
+  preset?: "production" | "development" | "testing" | "edge";
   /**
    * Runtime profile for store backends.
    * - 'memory' (default): Uses in-memory stores. Suitable for single-instance deployments.
-   * - 'distributed': Requires Redis-compatible adapters for cache, events, idempotency.
-   *   Startup fails fast if any required distributed adapter is missing.
+   * - 'distributed': Requires durable adapters for events, and for any enabled
+   *   shared subsystems such as caching/queryCache/rate limiting.
+   *   Idempotency remains per-resource opt-in: memory-backed stores are rejected,
+   *   while a missing idempotency store emits a startup warning because dedupe
+   *   would be instance-local.
    */
-  runtime?: 'memory' | 'distributed';
+  runtime?: "memory" | "distributed";
   /**
    * Store and transport instances for runtime profile validation.
    * When `runtime` is `'distributed'`, Arc validates that these are
@@ -235,7 +258,7 @@ interface CreateAppOptions {
     queryCache?: CacheStore;
   };
   /** Fastify logger configuration */
-  logger?: FastifyServerOptions['logger'];
+  logger?: FastifyServerOptions["logger"];
   /**
    * Enable Arc debug logging.
    *
@@ -332,11 +355,11 @@ interface CreateAppOptions {
    */
   elevation?: ElevationOptions | false;
   /** Helmet security headers. Set to false to disable. */
-  helmet?: FastifyHelmetOptions | false;
+  helmet?: HelmetOptions | false;
   /** CORS configuration. Set to false to disable. */
-  cors?: FastifyCorsOptions | false;
+  cors?: CorsOptions | false;
   /** Rate limiting. Set to false to disable. */
-  rateLimit?: RateLimitOptions | false;
+  rateLimit?: RateLimitOpts | false;
   /** Under pressure health monitoring. Set to false to disable. */
   underPressure?: UnderPressureOptions | false;
   /** @fastify/sensible (HTTP helpers). Set to false to disable. */
@@ -378,7 +401,7 @@ interface CreateAppOptions {
      * });
      * ```
      */
-    events?: Omit<EventPluginOptions, 'transport'> | boolean;
+    events?: Omit<EventPluginOptions, "transport"> | boolean;
     /**
      * Caching headers (ETag + Cache-Control). Default: false (opt-in).
      * Set to true for defaults, or pass CachingOptions for fine control.
@@ -396,6 +419,16 @@ interface CreateAppOptions {
      * Requires per-resource `cache` config on defineResource().
      */
     queryCache?: QueryCachePluginOptions | boolean;
+    /**
+     * Metrics endpoint (Prometheus-compatible). Default: false (opt-in).
+     * Set to true for defaults (/_metrics), or pass MetricsOptions for custom path/prefix.
+     */
+    metrics?: MetricsOptions | boolean;
+    /**
+     * API versioning (header or prefix-based). Default: false (opt-in).
+     * Pass VersioningOptions to enable.
+     */
+    versioning?: VersioningOptions;
   };
   /**
    * Type provider for schema inference.
@@ -416,7 +449,7 @@ interface CreateAppOptions {
    * // Now route schemas built with Type.* give full TS inference
    * ```
    */
-  typeProvider?: 'typebox';
+  typeProvider?: "typebox";
   /**
    * Error handler plugin. Normalizes AJV, Mongoose, and ArcError responses
    * into a consistent JSON envelope. Enabled by default.
@@ -448,21 +481,29 @@ interface CreateAppOptions {
   onClose?: (fastify: FastifyInstance) => void | Promise<void>;
 }
 interface UnderPressureOptions {
+  /** Expose `/_status` route for health checks (default: false) */
   exposeStatusRoute?: boolean;
+  /** Event loop lag threshold in ms — requests rejected above this (default: 1000) */
   maxEventLoopDelay?: number;
+  /** V8 heap usage threshold in bytes — requests rejected above this */
   maxHeapUsedBytes?: number;
+  /** RSS memory threshold in bytes — requests rejected above this */
   maxRssBytes?: number;
 }
 interface MultipartOptions {
   limits?: {
-    fileSize?: number;
+    /** Max file size in bytes (default: Fastify default ~1MB) */fileSize?: number; /** Max number of files per request */
     files?: number;
   };
 }
 interface RawBodyOptions {
+  /** Body field name to store raw body on (default: 'rawBody') */
   field?: string;
+  /** Apply to all routes globally (default: false) */
   global?: boolean;
+  /** Encoding for raw body string (default: 'utf8') */
   encoding?: string;
+  /** Parse raw body before other parsers (default: false) */
   runFirst?: boolean;
 }
 //#endregion

package/dist/{types-DelU6kln.mjs → types-ZUu_h0jp.mjs}

@@ -20,6 +20,5 @@ function getUserRoles(user) {
 	if (!user) return [];
 	return normalizeRoles(user.role);
 }
-
 //#endregion
-export { normalizeRoles as n, getUserRoles as t };
+export { normalizeRoles as n, getUserRoles as t };