@classytic/arc 2.15.0 → 2.15.3

package/README.md

@@ -155,6 +155,50 @@ Custom checks return `{ granted, reason?, filters?, scope? }` — `filters` prop
 
 ---
 
+## Aggregations
+
+Add `aggregations: { … }` to a resource and arc registers `GET /:prefix/aggregations/:name` per entry. Each runs a portable `$match → $group → $project → $sort → $limit` pipeline against the kit's `repo.aggregate(req, options)` — same shape across mongokit / sqlitekit / prismakit, so dashboards work unchanged across backends.
+
+```typescript
+import { defineResource, defineAggregation } from '@classytic/arc';
+
+defineResource({
+  name: 'transaction',
+  adapter,
+  presets: [multiTenantPreset({ tenantField: 'organizationId' })],
+  permissions: { list: canViewRevenue() },
+
+  aggregations: {
+    byPaymentMethod: defineAggregation({
+      groupBy: 'method',
+      measures: { total: 'sum:amount', count: 'count' },
+      sort: { total: -1 },
+      cache: { staleTime: 60, swr: true, tags: ['revenue'] },
+      permissions: canViewRevenue(),
+    }),
+    byDay: defineAggregation({
+      dateBuckets: { day: { field: 'createdAt', interval: 'day' } },
+      groupBy: 'flow',
+      measures: { total: 'sum:amount', count: 'count' },
+      requireDateRange: { field: 'createdAt', maxRangeDays: 365 },
+      cache: { staleTime: 60, swr: true, tags: ['revenue'] },
+      permissions: canViewRevenue(),
+    }),
+  },
+});
+```
+
+Caller filters via query string compose with the declaration:
+
+```
+GET /api/transactions/aggregations/byPaymentMethod?status=verified
+GET /api/transactions/aggregations/byDay?createdAt[gte]=2026-01-01&createdAt[lt]=2026-02-01
+```
+
+Tenant scope flows through `repo.aggregate(req, options)` — the kit's multi-tenant plugin handles type-coercion (string → ObjectId for mongokit `fieldType: 'objectId'`, UUID/text for sqlitekit, etc.). Arc itself stays out of the filter slot because it's DB-agnostic. Safety guards on the declaration: `requireFilters`, `requireDateRange { maxRangeDays }`, `maxGroups`. SWR cache + tag invalidation tie aggregations to CRUD writes. Every aggregation auto-exports as an MCP tool with the same permissions and filter validation.
+
+---
+
 ## Authentication
 
 Discriminated union on `type`:

package/dist/{BaseController-Cn8KykUn.mjs → BaseController-dx3m2J8V.mjs}

@@ -701,6 +701,7 @@ var BaseCrudController = class {
 		if (presetFields && typeof presetFields === "object") {
 			for (const [key, value] of Object.entries(presetFields)) if (value != null && out[key] == null) out[key] = value;
 		}
+		if (this.tenantField && out[this.tenantField] == null && scope && isElevated(scope)) out.bypassTenant = true;
 		const userId = getUserId(req.user);
 		if (userId) out.userId = userId;
 		if (req.user) out.user = req.user;

package/dist/{buildHandler-jSZ6Fdvi.mjs → buildHandler-CcFOpJLh.mjs}

@@ -78,10 +78,8 @@ function adapterSupportsAggregate(repo) {
 }
 /** Compile to canonical `AggRequest` for `repo.aggregate()` at request time. */
 function compileAggRequest(normalized, callerFilter, tenantOptions) {
-	const baseFilter = normalized.compiled.filter ?? {};
 	const filter = {
-		...extractTenantFilter(tenantOptions),
-		...baseFilter,
+		...normalized.compiled.filter ?? {},
 		...callerFilter
 	};
 	const executionHints = buildExecutionHints(normalized.base);
@@ -374,21 +372,6 @@ function assertFieldAllowed(context, ref, input) {
 	}
 	if (blockedFields.has(ref)) throw new ArcAggregationConfigError(`Resource "${resourceName}" aggregation "${aggregationName}" references field "${ref}" in ${context}, but the field is blocked from aggregation (\`hidden: true\` or \`aggregable: false\` in schemaOptions.fieldRules). Aggregating hidden fields would leak cardinality information.`);
 }
-function extractTenantFilter(tenantOptions) {
-	const out = {};
-	const optionOnlyKeys = new Set([
-		"userId",
-		"user",
-		"session",
-		"requestId"
-	]);
-	for (const [key, value] of Object.entries(tenantOptions)) {
-		if (optionOnlyKeys.has(key)) continue;
-		if (value === void 0 || value === null) continue;
-		out[key] = value;
-	}
-	return out;
-}
 //#endregion
 //#region src/core/aggregation/buildHandler.ts
 /**
@@ -444,7 +427,7 @@ async function executeAggregation(normalized, deps, ctx) {
 	};
 	let result;
 	try {
-		result = await repo.aggregate(aggReq);
+		result = await repo.aggregate(aggReq, tenantOptions);
 	} catch (err) {
 		return mapAggregateError(err, aggregationName);
 	}

package/dist/core/index.mjs

@@ -1,5 +1,5 @@
 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 BulkMixin, c as collectReadBlockedFields, d as AccessControl, i as SlugMixin, l as isFieldReadable, n as TreeMixin, o as BaseCrudController, r as SoftDeleteMixin, s as QueryResolver, t as BaseController, u as BodySanitizer } from "../BaseController-Cn8KykUn.mjs";
+import { a as BulkMixin, c as collectReadBlockedFields, d as AccessControl, i as SlugMixin, l as isFieldReadable, n as TreeMixin, o as BaseCrudController, r as SoftDeleteMixin, s as QueryResolver, t as BaseController, u as BodySanitizer } from "../BaseController-dx3m2J8V.mjs";
 import { _ as getControllerContext, g as createRequestContext, h as createFastifyHandler, m as createCrudHandlers, v as getControllerScope, y as sendControllerResponse } from "../routerShared-DrOa-26E.mjs";
-import { a as defineResource, c as createPermissionMiddleware, i as defineResourceVariants, l as defineAggregation, n as getEntityIdField, o as ResourceDefinition, r as getEntityQuery, s as createCrudRouter, t as getEntityId } from "../core--_Dnl7n-.mjs";
+import { a as defineResource, c as createPermissionMiddleware, i as defineResourceVariants, l as defineAggregation, n as getEntityIdField, o as ResourceDefinition, r as getEntityQuery, s as createCrudRouter, t as getEntityId } from "../core-CvmOqEms.mjs";
 export { AccessControl, BaseController, BaseCrudController, BodySanitizer, BulkMixin, CRUD_OPERATIONS, DEFAULT_ID_FIELD, DEFAULT_LIMIT, DEFAULT_MAX_LIMIT, DEFAULT_SORT, DEFAULT_TENANT_FIELD, DEFAULT_UPDATE_METHOD, HOOK_OPERATIONS, HOOK_PHASES, MAX_FILTER_DEPTH, MAX_REGEX_LENGTH, MAX_SEARCH_LENGTH, MUTATION_OPERATIONS, QueryResolver, RESERVED_QUERY_PARAMS, ResourceDefinition, SYSTEM_FIELDS, SlugMixin, SoftDeleteMixin, TreeMixin, collectReadBlockedFields, createCrudHandlers, createCrudRouter, createFastifyHandler, createPermissionMiddleware, createRequestContext, defineAggregation, defineResource, defineResourceVariants, getControllerContext, getControllerScope, getEntityId, getEntityIdField, getEntityQuery, isFieldReadable, sendControllerResponse };

package/dist/{core--_Dnl7n-.mjs → core-CvmOqEms.mjs}

@@ -1,7 +1,7 @@
 import { s as DEFAULT_UPDATE_METHOD, t as CRUD_OPERATIONS } from "./constants-Cxde4rpC.mjs";
 import { arcLog } from "./logger/index.mjs";
 import { A as assertValidConfig, l as getDefaultCrudSchemas } from "./utils-_h9B3c57.mjs";
-import { t as BaseController } from "./BaseController-Cn8KykUn.mjs";
+import { t as BaseController } from "./BaseController-dx3m2J8V.mjs";
 import { t as applyPresets } from "./presets-BbkjdPeH.mjs";
 import { n as convertRouteSchema, t as convertOpenApiSchemas } from "./schemaConverter-De34B1ZG.mjs";
 import { t as hasEvents } from "./typeGuards-BzkXkvVv.mjs";
@@ -840,6 +840,7 @@ function normalizeListQuerySchema(listQuerySchema) {
 		for (const key of Object.keys(normalizedProps)) normalizedProps[key] = NORMALIZED_PROPS[key] ?? {};
 	}
 	return {
+		type: "object",
 		...listQuerySchema,
 		...normalizedProps ? { properties: normalizedProps } : {},
 		additionalProperties: listQuerySchema.additionalProperties ?? true
@@ -997,7 +998,7 @@ function buildResourcePlugin(resource) {
 				});
 			}
 			if (resource.aggregations && Object.keys(resource.aggregations).length > 0) {
-				const { createAggregationRouter } = await import("./createAggregationRouter-DhR-Ofiz.mjs");
+				const { createAggregationRouter } = await import("./createAggregationRouter-B0bPDf5b.mjs");
 				const repoForAgg = resource.controller?.repository;
 				const buildOptions = (req) => {
 					const ctrl = resource.controller;
@@ -1014,7 +1015,8 @@ function buildResourcePlugin(resource) {
 					permissions: resource.permissions,
 					routeGuards: resource.routeGuards,
 					repository: repoForAgg,
-					buildOptions
+					buildOptions,
+					middlewares: resource.middlewares?.aggregations
 				});
 			}
 			if (resource.events && Object.keys(resource.events).length > 0) typedInstance.log?.debug?.(`Resource '${resource.name}' defined ${Object.keys(resource.events).length} events`);

package/dist/{createAggregationRouter-DhR-Ofiz.mjs → createAggregationRouter-B0bPDf5b.mjs}

@@ -1,13 +1,13 @@
 import { f as createError, l as UnauthorizedError, r as ForbiddenError } from "./errors-j4aJm1Wg.mjs";
 import { c as buildPreHandlerChain, f as resolveRouterPluginMw, i as buildAuthMiddleware, l as buildRateLimitConfig, p as selectPluginMw, r as buildArcDecorator } from "./routerShared-DrOa-26E.mjs";
-import { r as validateAggregations, t as buildAggregationHandler } from "./buildHandler-jSZ6Fdvi.mjs";
+import { r as validateAggregations, t as buildAggregationHandler } from "./buildHandler-CcFOpJLh.mjs";
 //#region src/core/aggregation/createAggregationRouter.ts
 /**
 * Register one Fastify route per aggregation. No-op when the map is
 * empty — same convention `createActionRouter` follows.
 */
 function createAggregationRouter(fastify, config) {
-	const { tag, resourceName, aggregations, fields: fieldPermissions, schemaOptions, permissions: resourcePermissions, routeGuards = [], repository, buildOptions } = config;
+	const { tag, resourceName, aggregations, fields: fieldPermissions, schemaOptions, permissions: resourcePermissions, routeGuards = [], repository, buildOptions, middlewares = [] } = config;
 	if (!aggregations || Object.keys(aggregations).length === 0) return;
 	const normalized = validateAggregations(resourceName, aggregations, schemaOptions);
 	const arcDecorator = buildArcDecorator({
@@ -23,7 +23,8 @@ function createAggregationRouter(fastify, config) {
 		arcDecorator,
 		routeGuards,
 		repository,
-		buildOptions
+		buildOptions,
+		middlewares
 	});
 	fastify.log?.debug?.({
 		aggregations: normalized.map((a) => a.name),
@@ -31,7 +32,7 @@ function createAggregationRouter(fastify, config) {
 	}, `[createAggregationRouter] registered ${normalized.length} aggregation route(s)`);
 }
 function registerOne(fastify, normalized, ctx) {
-	const { tag, arcDecorator, routeGuards, repository, buildOptions } = ctx;
+	const { tag, arcDecorator, routeGuards, repository, buildOptions, middlewares } = ctx;
 	const { name } = normalized;
 	const config = normalized.base;
 	const authMw = buildAuthMiddleware(fastify, config.permissions);
@@ -50,7 +51,8 @@ function registerOne(fastify, normalized, ctx) {
 		authMw,
 		permissionMw,
 		pluginMw: selectPluginMw("GET", resolveRouterPluginMw(fastify, false)),
-		routeGuards
+		routeGuards,
+		customMws: middlewares
 	});
 	const rateLimitConfig = buildRateLimitConfig(config.rateLimit ? {
 		max: config.rateLimit.max,

package/dist/{createApp-BarYhXCZ.mjs → createApp-PFegs47-.mjs}

@@ -230,8 +230,9 @@ async function registerArcPlugins(fastify, config, trackPlugin, modules) {
 		trackPlugin("arc-request-id");
 	}
 	if (config.arcPlugins?.health !== false) {
-		await fastify.register(healthPlugin);
-		trackPlugin("arc-health");
+		const healthOpts = typeof config.arcPlugins?.health === "object" && config.arcPlugins.health !== null ? config.arcPlugins.health : {};
+		await fastify.register(healthPlugin, healthOpts);
+		trackPlugin("arc-health", healthOpts);
 	}
 	if (config.arcPlugins?.gracefulShutdown !== false) {
 		await fastify.register(gracefulShutdownPlugin);
@@ -707,9 +708,65 @@ async function registerUtilityPlugins(fastify, config) {
 */
 var createApp_exports = /* @__PURE__ */ __exportAll({
 	ArcFactory: () => ArcFactory,
-	createApp: () => createApp
+	DEFAULT_LOGGER_REDACT_PATHS: () => DEFAULT_LOGGER_REDACT_PATHS,
+	createApp: () => createApp,
+	resolveLoggerConfig: () => resolveLoggerConfig
 });
 const MEMORY_STORE_NAMES = new Set(["memory", "memory-cache"]);
+/**
+* Default redact paths layered into Fastify's pino logger when the host
+* doesn't supply a `logger.redact` of their own. Covers the common token /
+* cookie / password leak surfaces — `Authorization` and `Cookie` headers
+* (and their case-variants because Node lower-cases incoming headers but
+* outgoing logs may carry either), API-key headers, and any nested
+* `password` / `token` / `secret` / `apiKey` fields anywhere in the log
+* tree.
+*
+* Hosts that need NO redaction (test fixtures, security audits) opt out
+* with `logger: { redact: [] }`. Hosts that need MORE redaction supply
+* their own `redact` and arc steps aside — this default never overrides
+* an explicit setting. (2.15.1)
+*/
+const DEFAULT_LOGGER_REDACT_PATHS = [
+	"req.headers.authorization",
+	"req.headers[\"x-api-key\"]",
+	"req.headers[\"x-internal-api-key\"]",
+	"req.headers.cookie",
+	"req.headers[\"set-cookie\"]",
+	"res.headers[\"set-cookie\"]",
+	"*.password",
+	"*.passwordHash",
+	"*.token",
+	"*.accessToken",
+	"*.refreshToken",
+	"*.secret",
+	"*.apiKey"
+];
+/**
+* Resolve the host's `logger` option, layering safe redact defaults
+* when the host hasn't supplied any. Returns the value Fastify expects
+* for its `logger` server option.
+*
+* Three branches:
+*   - `logger === false` → pass through (no logger).
+*   - `logger === undefined` → enable with default redact paths.
+*   - `logger === true` → enable with default redact paths.
+*   - `logger` is an object → respect explicit `redact` (host wins);
+*     otherwise inject defaults.
+*/
+function resolveLoggerConfig(logger) {
+	if (logger === false) return false;
+	if (logger === true || logger === void 0) return { redact: [...DEFAULT_LOGGER_REDACT_PATHS] };
+	if (typeof logger === "object" && logger !== null) {
+		const objLogger = logger;
+		if (objLogger.redact !== void 0) return logger;
+		return {
+			...objLogger,
+			redact: [...DEFAULT_LOGGER_REDACT_PATHS]
+		};
+	}
+	return logger;
+}
 function validateAuthOptions(options) {
 	const authConfig = options.auth;
 	if (authConfig === false || !authConfig) return;
@@ -766,14 +823,17 @@ async function createApp(options) {
 		...options
 	};
 	const fastify = Fastify({
-		logger: config.logger ?? true,
+		logger: resolveLoggerConfig(config.logger),
 		trustProxy: config.trustProxy ?? false,
 		pluginTimeout: config.pluginTimeout ?? 1e4,
+		...config.bodyLimit !== void 0 ? { bodyLimit: config.bodyLimit } : {},
+		allowErrorHandlerOverride: true,
 		routerOptions: { querystringParser: (str) => qs.parse(str) },
 		ajv: { customOptions: {
 			coerceTypes: true,
 			useDefaults: true,
 			removeAdditional: false,
+			strictTypes: false,
 			keywords: ["example", ...config.ajv?.keywords ?? []]
 		} }
 	});

package/dist/factory/index.d.mts

@@ -1,5 +1,5 @@
-import { a as CustomPluginAuthOption, c as RawBodyOptions, d as ResourceLike, f as ResourceModule, i as CustomAuthenticatorOption, l as UnderPressureOptions, n as BetterAuthOption, o as JwtAuthOption, p as loadResources, r as CreateAppOptions, s as MultipartOptions, t as AuthOption, u as LoadResourcesOptions } from "../types-3YTpuLZ1.mjs";
-import { FastifyInstance } from "fastify";
+import { a as CustomPluginAuthOption, c as RawBodyOptions, d as ResourceLike, f as ResourceModule, i as CustomAuthenticatorOption, l as UnderPressureOptions, n as BetterAuthOption, o as JwtAuthOption, p as loadResources, r as CreateAppOptions, s as MultipartOptions, t as AuthOption, u as LoadResourcesOptions } from "../types-DrBaUwyV.mjs";
+import { FastifyInstance, FastifyServerOptions } from "fastify";
 
 //#region src/factory/createApp.d.ts
 /**

package/dist/factory/index.mjs

@@ -1,4 +1,4 @@
-import { a as edgePreset, c as testingPreset, i as developmentPreset, n as createApp, o as getPreset, s as productionPreset, t as ArcFactory } from "../createApp-BarYhXCZ.mjs";
+import { a as edgePreset, c as testingPreset, i as developmentPreset, n as createApp, o as getPreset, s as productionPreset, t as ArcFactory } from "../createApp-PFegs47-.mjs";
 import { t as loadResources } from "../loadResources-DBMQg_Aj.mjs";
 //#region src/factory/edge.ts
 /**

package/dist/index.mjs

@@ -1,11 +1,11 @@
 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 { d as createDomainError, i as NotFoundError, l as UnauthorizedError, r as ForbiddenError, t as ArcError, u as ValidationError } from "./errors-j4aJm1Wg.mjs";
 import { t as getUserId } from "./utils-_h9B3c57.mjs";
-import { a as BulkMixin, i as SlugMixin, n as TreeMixin, o as BaseCrudController, r as SoftDeleteMixin, t as BaseController } from "./BaseController-Cn8KykUn.mjs";
+import { a as BulkMixin, i as SlugMixin, n as TreeMixin, o as BaseCrudController, r as SoftDeleteMixin, t as BaseController } from "./BaseController-dx3m2J8V.mjs";
 import { C as allowPublic, D as requireAuth, O as requireOwnership, S as allOf, T as denyAll, _ as requireOrgMembership, a as presets_exports, b as requireServiceScope, c as readOnly, d as applyFieldWritePermissions, f as fields, g as requireOrgInScope, h as createOrgPermissions, i as ownerWithAdminBypass, j as when, k as requireRoles, m as createDynamicPermissionMatrix, n as authenticated, o as publicRead, r as fullPublic, s as publicReadAdminWrite, t as adminOnly, u as applyFieldReadPermissions, v as requireOrgRole, w as anyOf, x as requireTeamMembership, y as requireScopeContext } from "./permissions-ohQyv50e.mjs";
 import { v as getControllerScope } from "./routerShared-DrOa-26E.mjs";
-import { a as defineResource, i as defineResourceVariants, l as defineAggregation, o as ResourceDefinition } from "./core--_Dnl7n-.mjs";
+import { a as defineResource, i as defineResourceVariants, l as defineAggregation, o as ResourceDefinition } from "./core-CvmOqEms.mjs";
 //#region src/index.ts
-const version = "2.15.0";
+const version = "2.15.3";
 //#endregion
 export { ArcError, BaseController, BaseCrudController, BulkMixin, 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, NotFoundError, RESERVED_QUERY_PARAMS, ResourceDefinition, SYSTEM_FIELDS, SlugMixin, SoftDeleteMixin, TreeMixin, UnauthorizedError, ValidationError, adminOnly, allOf, allowPublic, anyOf, applyFieldReadPermissions, applyFieldWritePermissions, authenticated, createDomainError, createDynamicPermissionMatrix, createOrgPermissions, defineAggregation, defineResource, defineResourceVariants, denyAll, fields, fullPublic, getControllerScope, getUserId, ownerWithAdminBypass, presets_exports as permissions, publicRead, publicReadAdminWrite, readOnly, requireAuth, requireOrgInScope, requireOrgMembership, requireOrgRole, requireOwnership, requireRoles, requireScopeContext, requireServiceScope, requireTeamMembership, version, when };

package/dist/integrations/mcp/index.mjs

@@ -1,4 +1,4 @@
-import { n as fieldRulesToZod, r as createMcpServer, t as resourceToTools } from "../../resourceToTools-D4pWzVGA.mjs";
+import { n as fieldRulesToZod, r as createMcpServer, t as resourceToTools } from "../../resourceToTools-tFYUNmM0.mjs";
 import { createHash, randomUUID } from "node:crypto";
 import fp from "fastify-plugin";
 //#region src/integrations/mcp/defineTool.ts

package/dist/integrations/mcp/testing.mjs

@@ -1,4 +1,4 @@
-import { r as createMcpServer, t as resourceToTools } from "../../resourceToTools-D4pWzVGA.mjs";
+import { r as createMcpServer, t as resourceToTools } from "../../resourceToTools-tFYUNmM0.mjs";
 //#region src/integrations/mcp/testing.ts
 /**
 * @classytic/arc/mcp/testing — MCP Test Utilities

package/dist/plugins/index.d.mts

@@ -1,6 +1,6 @@
 import { On as HookSystem, Q as MiddlewareConfig, Wt as AnyRecord, ft as RouteSchemaOptions, lt as RouteDefinition, tt as PresetHook, z as ResourceRegistry } from "../index-BswOSJCE.mjs";
 import { t as ExternalOpenApiPaths } from "../externalPaths-BD5nw6St.mjs";
-import { a as MetricsCollector, c as metricsPlugin, d as ssePlugin, f as CachingOptions, h as cachingPlugin, i as MetricEntry, l as SSEOptions, m as _default$1, n as _default$7, o as MetricsOptions, p as CachingRule, r as versioningPlugin, s as _default$4, t as VersioningOptions, u as _default$6 } from "../versioning-DTTvc80y.mjs";
+import { _ as HealthOptions, a as MetricsCollector, c as metricsPlugin, d as ssePlugin, f as CachingOptions, g as HealthCheck, h as cachingPlugin, i as MetricEntry, l as SSEOptions, m as _default$1, n as _default$7, o as MetricsOptions, p as CachingRule, r as versioningPlugin, s as _default$4, t as VersioningOptions, u as _default$6, v as _default$3, y as healthPlugin } from "../versioning-hmkPcDlX.mjs";
 import { i as errorHandlerPlugin, n as ErrorMapper, r as defaultIsDuplicateKeyError, t as ErrorHandlerOptions } from "../errorHandler-DFr45ZG4.mjs";
 import { t as TracingOptions } from "../tracing-QJVprktp.mjs";
 import { PaginatedResult } from "@classytic/repo-core/pagination";
@@ -137,39 +137,6 @@ declare module "fastify" {
 }
 declare const _default$2: FastifyPluginAsync<GracefulShutdownOptions>;
 //#endregion
-//#region src/plugins/health.d.ts
-declare module "fastify" {
-  interface FastifyRequest {
-    _startTime?: number;
-  }
-}
-interface HealthCheck {
-  /** Name of the dependency */
-  name: string;
-  /** Function that returns true if healthy, false otherwise */
-  check: () => Promise<boolean> | boolean;
-  /** Optional timeout in ms (default: 5000) */
-  timeout?: number;
-  /** Whether this check is critical for readiness (default: true) */
-  critical?: boolean;
-}
-interface HealthOptions {
-  /** Route prefix (default: '/_health') */
-  prefix?: string;
-  /** Health check dependencies */
-  checks?: HealthCheck[];
-  /** Enable metrics endpoint (default: false) */
-  metrics?: boolean;
-  /** Custom metrics collector function */
-  metricsCollector?: () => Promise<string> | string;
-  /** Version info to include in responses */
-  version?: string;
-  /** Collect HTTP request metrics (default: true if metrics enabled) */
-  collectHttpMetrics?: boolean;
-}
-declare const healthPlugin: FastifyPluginAsync<HealthOptions>;
-declare const _default$3: FastifyPluginAsync<HealthOptions>;
-//#endregion
 //#region src/plugins/replyHelpers.d.ts
 declare module "fastify" {
   interface FastifyReply {

package/dist/plugins/tracing-entry.mjs

@@ -58,7 +58,7 @@ try {
 function createTracerProvider(options) {
 	if (!isAvailable || !NodeTracerProvider || !BatchSpanProcessor || !OTLPTraceExporter) return null;
 	const { serviceName = "@classytic/arc", serviceVersion, exporterUrl = "http://localhost:4318/v1/traces" } = options;
-	const resolvedVersion = serviceVersion ?? "2.15.0";
+	const resolvedVersion = serviceVersion ?? "2.15.3";
 	const exporter = new OTLPTraceExporter({ url: exporterUrl });
 	const provider = new NodeTracerProvider({ resource: { attributes: {
 		"service.name": serviceName,

package/dist/presets/multiTenant.mjs

@@ -185,7 +185,8 @@ function multiTenantPreset(options = {}) {
 			get: [getFilter("get")],
 			create: [tenantInjection],
 			update: [getFilter("update"), tenantInjection],
-			delete: [getFilter("delete")]
+			delete: [getFilter("delete")],
+			aggregations: [strictTenantFilter]
 		}
 	};
 }

package/dist/{resourceToTools-D4pWzVGA.mjs → resourceToTools-tFYUNmM0.mjs}

@@ -1,9 +1,9 @@
 import { p as isArcError } from "./errors-j4aJm1Wg.mjs";
-import { t as BaseController } from "./BaseController-Cn8KykUn.mjs";
+import { t as BaseController } from "./BaseController-dx3m2J8V.mjs";
 import { L as normalizePermissionResult } from "./permissions-ohQyv50e.mjs";
 import { t as executePipeline } from "./pipe-Zr0KXjQe.mjs";
 import { u as resolvePipelineSteps } from "./routerShared-DrOa-26E.mjs";
-import { n as executeAggregation, r as validateAggregations } from "./buildHandler-jSZ6Fdvi.mjs";
+import { n as executeAggregation, r as validateAggregations } from "./buildHandler-CcFOpJLh.mjs";
 import { t as resolveActionPermission } from "./actionPermissions-CyUkQu6O.mjs";
 import { i as shouldRejectAdditionalProperties, r as schemaIRToZodShape, t as normalizeSchemaIR } from "./schemaIR-lYhC2gE5.mjs";
 import { t as pluralize } from "./pluralize-DQgqgifU.mjs";

package/dist/testing/index.d.mts

@@ -1,5 +1,5 @@
 import { V as ResourceDefinition, Wt as AnyRecord } from "../index-BswOSJCE.mjs";
-import { d as ResourceLike, r as CreateAppOptions } from "../types-3YTpuLZ1.mjs";
+import { d as ResourceLike, r as CreateAppOptions } from "../types-DrBaUwyV.mjs";
 import { StorageContractSetup, StorageContractSetupResult, runStorageContract } from "./storageContract.mjs";
 import { FastifyInstance, FastifyServerOptions } from "fastify";
 import { Mock } from "vitest";

package/dist/testing/index.mjs

@@ -1070,7 +1070,7 @@ function pickDefaultAuth(authMode, callerAuth) {
 	};
 }
 async function createTestApp(options = {}) {
-	const { createApp } = await import("../createApp-BarYhXCZ.mjs").then((n) => n.r);
+	const { createApp } = await import("../createApp-PFegs47-.mjs").then((n) => n.r);
 	const { resources = [], db = "in-memory", connectMongoose = false, authMode = "jwt", defaultOrgId, plugins, auth: callerAuth, ...appOptions } = options;
 	let dbHandle;
 	let dbUri;

package/dist/{types-3YTpuLZ1.d.mts → types-DrBaUwyV.d.mts}

@@ -5,7 +5,7 @@ import { a as EventTransport } from "./EventTransport-CT_52aWU.mjs";
 import { t as ExternalOpenApiPaths } from "./externalPaths-BD5nw6St.mjs";
 import { r as QueryCachePluginOptions } from "./queryCachePlugin-CqMdLI2-.mjs";
 import { t as EventPluginOptions } from "./eventPlugin-qXpqTebY.mjs";
-import { f as CachingOptions, l as SSEOptions, o as MetricsOptions, t as VersioningOptions } from "./versioning-DTTvc80y.mjs";
+import { _ as HealthOptions, f as CachingOptions, l as SSEOptions, o as MetricsOptions, t as VersioningOptions } from "./versioning-hmkPcDlX.mjs";
 import { t as ErrorHandlerOptions } from "./errorHandler-DFr45ZG4.mjs";
 import { r as IdempotencyStore } from "./interface-DfLGcus7.mjs";
 import { FastifyInstance, FastifyPluginAsync, FastifyReply, FastifyRequest, FastifyServerOptions } from "fastify";
@@ -488,6 +488,16 @@ interface CreateAppOptions {
   trustProxy?: boolean;
   /** Fastify plugin/onReady timeout in ms (default: 10_000). Raise for slow boot work (index materialisation, WAL replay, external warm-up). */
   pluginTimeout?: number;
+  /**
+   * Maximum JSON body size in bytes. Pass-through to Fastify's
+   * server-level `bodyLimit` option; default is Fastify's 1 MiB
+   * (1_048_576 bytes). Raise for hosts shipping bulk-import / CSV ingest
+   * / JSON-RPC batch endpoints — without this, Fastify rejects oversized
+   * payloads with `FST_ERR_CTP_BODY_TOO_LARGE` (413) before any route
+   * handler runs. File uploads on `multipart` routes are governed
+   * separately by `multipart.limits.fileSize`. (2.15.1)
+   */
+  bodyLimit?: number;
   /**
    * Auth configuration
    *
@@ -578,8 +588,34 @@ interface CreateAppOptions {
   rawBody?: RawBodyOptions | false;
   /** Enable Arc plugins (requestId, health, gracefulShutdown, events, caching, sse) */
   arcPlugins?: {
-    /** Request ID tracking (default: true) */requestId?: boolean; /** Health endpoints (default: true) */
-    health?: boolean; /** Graceful shutdown handling (default: true) */
+    /** Request ID tracking (default: true) */requestId?: boolean;
+    /**
+     * Health endpoints (default: true).
+     *
+     * Three forms:
+     *   - `true` (default) — register Arc's health plugin with no extra checks
+     *     (`/_health/live` always 200, `/_health/ready` 200 unless explicit
+     *     readiness probes are added later).
+     *   - `false` — disable Arc's health plugin entirely; the host registers
+     *     its own (or none).
+     *   - `{ checks: HealthCheck[] }` — register Arc's health plugin AND
+     *     attach the supplied readiness probes (Mongo connectivity, engine
+     *     warmup, queue connectivity, etc.). Closes the pre-2.15.1 hole
+     *     where adding checks meant `health: false` + manual re-registration.
+     *
+     * @example
+     * ```typescript
+     * arcPlugins: {
+     *   health: {
+     *     checks: [
+     *       { name: 'mongo', check: async () => mongoose.connection.readyState === 1 },
+     *       { name: 'catalog-engine', check: async () => catalog.isReady() },
+     *     ],
+     *   },
+     * }
+     * ```
+     */
+    health?: boolean | HealthOptions; /** Graceful shutdown handling (default: true) */
     gracefulShutdown?: boolean; /** Emit events for CRUD operations (default: true) */
     emitEvents?: boolean;
     /**

package/dist/{versioning-DTTvc80y.d.mts → versioning-hmkPcDlX.d.mts}

@@ -1,6 +1,39 @@
 import { n as DomainEvent } from "./EventTransport-CT_52aWU.mjs";
 import { FastifyPluginAsync, FastifyRequest } from "fastify";
 
+//#region src/plugins/health.d.ts
+declare module "fastify" {
+  interface FastifyRequest {
+    _startTime?: number;
+  }
+}
+interface HealthCheck {
+  /** Name of the dependency */
+  name: string;
+  /** Function that returns true if healthy, false otherwise */
+  check: () => Promise<boolean> | boolean;
+  /** Optional timeout in ms (default: 5000) */
+  timeout?: number;
+  /** Whether this check is critical for readiness (default: true) */
+  critical?: boolean;
+}
+interface HealthOptions {
+  /** Route prefix (default: '/_health') */
+  prefix?: string;
+  /** Health check dependencies */
+  checks?: HealthCheck[];
+  /** Enable metrics endpoint (default: false) */
+  metrics?: boolean;
+  /** Custom metrics collector function */
+  metricsCollector?: () => Promise<string> | string;
+  /** Version info to include in responses */
+  version?: string;
+  /** Collect HTTP request metrics (default: true if metrics enabled) */
+  collectHttpMetrics?: boolean;
+}
+declare const healthPlugin: FastifyPluginAsync<HealthOptions>;
+declare const _default$4: FastifyPluginAsync<HealthOptions>;
+//#endregion
 //#region src/plugins/caching.d.ts
 interface CachingRule {
   /** Path prefix to match (e.g., '/api/products') */
@@ -114,4 +147,4 @@ declare module "fastify" {
 declare const versioningPlugin: FastifyPluginAsync<VersioningOptions>;
 declare const _default: FastifyPluginAsync<VersioningOptions>;
 //#endregion
-export { MetricsCollector as a, metricsPlugin as c, ssePlugin as d, CachingOptions as f, cachingPlugin as h, MetricEntry as i, SSEOptions as l, _default$3 as m, _default as n, MetricsOptions as o, CachingRule as p, versioningPlugin as r, _default$1 as s, VersioningOptions as t, _default$2 as u };
+export { HealthOptions as _, MetricsCollector as a, metricsPlugin as c, ssePlugin as d, CachingOptions as f, HealthCheck as g, cachingPlugin as h, MetricEntry as i, SSEOptions as l, _default$3 as m, _default as n, MetricsOptions as o, CachingRule as p, versioningPlugin as r, _default$1 as s, VersioningOptions as t, _default$2 as u, _default$4 as v, healthPlugin as y };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classytic/arc",
-  "version": "2.15.0",
+  "version": "2.15.3",
   "description": "Resource-oriented backend framework for Fastify - clean, minimal, powerful, tree-shakable",
   "type": "module",
   "exports": {
@@ -246,7 +246,7 @@
   },
   "peerDependencies": {
     "@classytic/primitives": ">=0.4.0",
-    "@classytic/repo-core": ">=0.4.0",
+    "@classytic/repo-core": ">=0.4.1",
     "@classytic/streamline": ">=2.3.0",
     "@fastify/cors": ">=11.0.0",
     "@fastify/helmet": ">=13.0.0",
@@ -357,10 +357,10 @@
     "@better-auth/mongo-adapter": "^1.6.9",
     "@biomejs/biome": "^2.4.11",
     "@classytic/dev-tools": "^0.2.0",
-    "@classytic/mongokit": "^3.13.0",
+    "@classytic/mongokit": "^3.13.2",
     "@classytic/primitives": "^0.4.0",
-    "@classytic/repo-core": "^0.4.0",
-    "@classytic/sqlitekit": "^0.3.0",
+    "@classytic/repo-core": "^0.4.1",
+    "@classytic/sqlitekit": "^0.3.1",
     "@classytic/streamline": "^2.3.0",
     "@fastify/cors": "^11.2.0",
     "@fastify/helmet": "^13.0.2",

package/skills/arc/SKILL.md

@@ -639,6 +639,83 @@ defineResource({
 
 MCP auto-derives `filterableFields` from `queryParser`.
 
+## Aggregations — dashboards in declarative form
+
+Add `aggregations: { … }` to a resource and Arc registers `GET
+/{prefix}/aggregations/:name` per entry. Each runs a portable `$match
+→ $group → $project → $sort → $limit` pipeline against the kit's
+`repo.aggregate(req, options)` — same shape across mongokit /
+sqlitekit / prismakit, so dashboards work unchanged across backends.
+
+```typescript
+import { defineResource, defineAggregation } from '@classytic/arc';
+
+defineResource({
+  name: 'transaction',
+  adapter,
+  presets: [multiTenantPreset({ tenantField: 'organizationId' })],
+  permissions: { list: canViewRevenue() },
+
+  aggregations: {
+    byPaymentMethod: defineAggregation({
+      groupBy: 'method',
+      measures: { total: 'sum:amount', count: 'count' },
+      sort: { total: -1 },
+      cache: { staleTime: 60, swr: true, tags: ['revenue'] },
+      permissions: canViewRevenue(),
+    }),
+    byFlow: defineAggregation({
+      groupBy: 'flow',
+      measures: { total: 'sum:amount', count: 'count' },
+      cache: { staleTime: 60, swr: true, tags: ['revenue'] },
+      permissions: canViewRevenue(),
+    }),
+    byDay: defineAggregation({
+      dateBuckets: { day: { field: 'createdAt', interval: 'day' } },
+      groupBy: 'flow',
+      measures: { total: 'sum:amount', count: 'count' },
+      sort: { day: 1 },
+      requireDateRange: { field: 'createdAt', maxRangeDays: 365 },
+      cache: { staleTime: 60, swr: true, tags: ['revenue'] },
+      permissions: canViewRevenue(),
+    }),
+  },
+});
+```
+
+**Tenant scope flows through the second arg, NOT the filter.** Arc is
+DB-agnostic — type-coercion (string → ObjectId for mongokit
+`fieldType: 'objectId'`, UUID/text for sqlitekit, etc.) belongs to the
+kit. Arc threads `tenantOptions` to `repo.aggregate(req, options)`;
+the kit's multi-tenant plugin reads `context.organizationId`, casts
+correctly, and merges into the request. Authors never inject the
+tenant key into `aggReq.filter` themselves.
+
+**Caller filters via query string compose with `groupBy` / measures:**
+
+```
+GET /api/transactions/aggregations/byPaymentMethod?status=verified
+GET /api/transactions/aggregations/byDay?createdAt[gte]=2026-01-01&createdAt[lt]=2026-02-01
+```
+
+**Safety guards on the declaration:**
+- `requireDateRange: { field, maxRangeDays }` — bounded range mandatory; kills accidental all-time scans
+- `requireFilters: ['orgId']` — mandatory scope keys
+- `maxGroups: 1000` — post-execution row cap; 422 on overflow
+
+**Cache invalidation:** writes through resource CRUD bump the
+matching tag. Aggregations cached with the same `tags` invalidate
+together. SWR mode serves stale immediately while revalidating in
+background.
+
+**MCP auto-export:** every aggregation surfaces as an MCP tool
+named `{resource}_aggregations_{name}` with the same permission gate
+and filter validation as the HTTP route.
+
+For backends without `repo.aggregate` (custom adapters), declare a
+`materialized` hook on the aggregation — Arc routes through it
+instead of the kit and returns the same `{ rows }` envelope.
+
 ## QueryCache
 
 TanStack Query-style server cache, stale-while-revalidate, auto-invalidation on mutations.

package/skills/arc-code-review/references/anti-patterns.md

@@ -894,6 +894,49 @@ Then check whether the hook body sets headers (`reply.header(`, `reply.headers[`
 
 ---
 
+## §33. Hand-rolled aggregation routes when `aggregations: { … }` would do 🟠
+
+**Detection:**
+```
+pattern: "Model\\.aggregate\\(\\["
+output_mode: content
+```
+Also: `\\.aggregate\\(\\s*\\[`, `\\$group\\b`, `\\$match\\b` inside resource handler files. Plus inline mongoose pipeline imports inside route handlers (vs. inside the kit's repository).
+
+**Anti-pattern:**
+```typescript
+// In a custom GET /aggregate/byPaymentMethod route:
+const orgId = getOrgId(getScope(req));
+const rows = await Transaction.aggregate([
+  { $match: { organizationId: new mongoose.Types.ObjectId(orgId), status: 'verified' } },
+  { $group: { _id: '$method', total: { $sum: '$amount' }, count: { $sum: 1 } } },
+  { $sort: { total: -1 } },
+]);
+return reply.send({ rows });
+```
+
+**Why high:** loses every cross-cutting feature arc's aggregation router gives for free — per-aggregation permissions, OpenAPI schema, MCP tool export, SWR cache + tag invalidation, `requireFilters` / `requireDateRange` safety guards, `maxGroups` cap, multi-tenant scope without manual `ObjectId` casting. The hand-rolled version also drifts: every new bucket needs a new route, no central declaration, no unified shape across kits.
+
+**Fix:** declare `aggregations: { name: defineAggregation({ groupBy, measures, sort, cache, permissions }) }` on the resource. Arc registers `GET /:prefix/aggregations/:name` per entry, threads `tenantOptions` to `repo.aggregate(req, options)`, and the kit's multi-tenant plugin handles type-coercion. Type-coercion (string → ObjectId / UUID / text) is **the kit's responsibility, not the framework's** — never inject the tenant key into `aggReq.filter` from arc-host code.
+
+```typescript
+import { defineAggregation } from '@classytic/arc';
+
+aggregations: {
+  byPaymentMethod: defineAggregation({
+    groupBy: 'method',
+    measures: { total: 'sum:amount', count: 'count' },
+    sort: { total: -1 },
+    cache: { staleTime: 60, swr: true, tags: ['revenue'] },
+    permissions: canViewRevenue(),
+  }),
+}
+```
+
+For backends without `repo.aggregate`, declare a `materialized` hook on the aggregation — the router calls it instead of the kit and keeps the same `{ rows }` envelope, permission gate, and cache contract.
+
+---
+
 ## Detection checklist (run-order)
 
 Run sweeps in this order — early hits often invalidate later context:
@@ -909,3 +952,4 @@ Run sweeps in this order — early hits often invalidate later context:
 9. §14, §18, §19 — preset adoption + custom controller wiring
 10. §11, §12, §13, §29, §30, §31 — style and edges
 11. §32a–§32g — canonical-contract drift (pagination / events / tenant / errors / adapter imports), missing `requireOrgId` accessors, missing `schemaGenerator`, kit-specific adapter imports from arc (3.0 break)
+12. §33 — hand-rolled `Model.aggregate([...])` in resource routes vs declarative `aggregations: { … }`

package/skills/arc-code-review/references/arc-cheatsheet.md

@@ -246,6 +246,33 @@ Modes: `memory` (default) | `distributed` (`stores.queryCache: RedisCacheStore`)
 
 ---
 
+## Aggregations (declarative dashboards)
+
+```typescript
+import { defineAggregation } from '@classytic/arc';
+
+aggregations: {
+  byMethod: defineAggregation({
+    groupBy: 'method',
+    measures: { total: 'sum:amount', count: 'count' },
+    sort: { total: -1 },
+    cache: { staleTime: 60, swr: true, tags: ['revenue'] },
+    permissions: canViewRevenue(),
+  }),
+  byDay: defineAggregation({
+    dateBuckets: { day: { field: 'createdAt', interval: 'day' } },
+    groupBy: 'flow',
+    measures: { total: 'sum:amount' },
+    requireDateRange: { field: 'createdAt', maxRangeDays: 365 },
+    permissions: canViewRevenue(),
+  }),
+}
+```
+
+Registers `GET /:prefix/aggregations/:name` per entry. Same permissions, OpenAPI, MCP tool, cache + tag invalidation as CRUD. Tenant flows via the kit's multi-tenant plugin (string → ObjectId casting handled by the kit, **not** by hand). Caller filters via query string (`?status=verified&createdAt[gte]=...`) compose with the declaration. Safety: `requireFilters`, `requireDateRange`, `maxGroups`. **Anti-pattern:** custom routes calling `Model.aggregate([...])` directly — see anti-patterns §33.
+
+---
+
 ## CLI
 
 ```bash