@classytic/arc 2.10.3 → 2.11.0

package/dist/pipeline/index.d.mts

@@ -0,0 +1,62 @@
+import { Ct as OperationFilter, Dt as Transform, Et as PipelineStep, St as NextFunction, Tt as PipelineContext, _t as IControllerResponse, bt as Guard, wt as PipelineConfig, xt as Interceptor } from "../index-Cm0vUrr_.mjs";
+
+//#region src/pipeline/guard.d.ts
+interface GuardOptions {
+  operations?: OperationFilter;
+  handler: (ctx: PipelineContext) => boolean | Promise<boolean>;
+}
+/**
+ * Create a named guard.
+ *
+ * @param name - Guard name (for debugging/introspection)
+ * @param handlerOrOptions - Handler function or options object
+ */
+declare function guard(name: string, handlerOrOptions: ((ctx: PipelineContext) => boolean | Promise<boolean>) | GuardOptions): Guard;
+//#endregion
+//#region src/pipeline/intercept.d.ts
+interface InterceptOptions {
+  operations?: OperationFilter;
+  handler: (ctx: PipelineContext, next: NextFunction) => Promise<IControllerResponse<unknown>>;
+}
+/**
+ * Create a named interceptor.
+ *
+ * @param name - Interceptor name (for debugging/introspection)
+ * @param handlerOrOptions - Handler function or options object
+ */
+declare function intercept(name: string, handlerOrOptions: ((ctx: PipelineContext, next: NextFunction) => Promise<IControllerResponse<unknown>>) | InterceptOptions): Interceptor;
+//#endregion
+//#region src/pipeline/pipe.d.ts
+/**
+ * Compose pipeline steps into an ordered array.
+ * Accepts guards, transforms, and interceptors in any order.
+ */
+declare function pipe(...steps: PipelineStep[]): PipelineStep[];
+/**
+ * Execute a pipeline against a request context.
+ *
+ * This is the core runtime that createCrudRouter uses to execute pipelines.
+ * External usage is not needed — this is wired automatically when `pipe` is set.
+ *
+ * @param steps - Pipeline steps to execute
+ * @param ctx - The pipeline context (extends IRequestContext)
+ * @param handler - The actual controller method to call
+ * @param operation - The CRUD operation name
+ * @returns The controller response (possibly modified by interceptors)
+ */
+declare function executePipeline(steps: PipelineStep[], ctx: PipelineContext, handler: (ctx: PipelineContext) => Promise<IControllerResponse<unknown>>, operation: string): Promise<IControllerResponse<unknown>>;
+//#endregion
+//#region src/pipeline/transform.d.ts
+interface TransformOptions {
+  operations?: OperationFilter;
+  handler: (ctx: PipelineContext) => PipelineContext | undefined | Promise<PipelineContext | undefined>;
+}
+/**
+ * Create a named transform.
+ *
+ * @param name - Transform name (for debugging/introspection)
+ * @param handlerOrOptions - Handler function or options object
+ */
+declare function transform(name: string, handlerOrOptions: ((ctx: PipelineContext) => PipelineContext | undefined | Promise<PipelineContext | undefined>) | TransformOptions): Transform;
+//#endregion
+export { type Guard, type Interceptor, type NextFunction, type OperationFilter, type PipelineConfig, type PipelineContext, type PipelineStep, type Transform, executePipeline, guard, intercept, pipe, transform };

package/dist/pipeline/index.mjs

@@ -0,0 +1,53 @@
+import { n as pipe, t as executePipeline } from "../pipe-DVoIheVC.mjs";
+//#region src/pipeline/guard.ts
+/**
+* Create a named guard.
+*
+* @param name - Guard name (for debugging/introspection)
+* @param handlerOrOptions - Handler function or options object
+*/
+function guard(name, handlerOrOptions) {
+	const opts = typeof handlerOrOptions === "function" ? { handler: handlerOrOptions } : handlerOrOptions;
+	return {
+		_type: "guard",
+		name,
+		operations: opts.operations,
+		handler: opts.handler
+	};
+}
+//#endregion
+//#region src/pipeline/intercept.ts
+/**
+* Create a named interceptor.
+*
+* @param name - Interceptor name (for debugging/introspection)
+* @param handlerOrOptions - Handler function or options object
+*/
+function intercept(name, handlerOrOptions) {
+	const opts = typeof handlerOrOptions === "function" ? { handler: handlerOrOptions } : handlerOrOptions;
+	return {
+		_type: "interceptor",
+		name,
+		operations: opts.operations,
+		handler: opts.handler
+	};
+}
+//#endregion
+//#region src/pipeline/transform.ts
+/**
+* Create a named transform.
+*
+* @param name - Transform name (for debugging/introspection)
+* @param handlerOrOptions - Handler function or options object
+*/
+function transform(name, handlerOrOptions) {
+	const opts = typeof handlerOrOptions === "function" ? { handler: handlerOrOptions } : handlerOrOptions;
+	return {
+		_type: "transform",
+		name,
+		operations: opts.operations,
+		handler: opts.handler
+	};
+}
+//#endregion
+export { executePipeline, guard, intercept, pipe, transform };

package/dist/plugins/index.d.mts

@@ -1,7 +1,8 @@
-import { W as ResourceRegistry, at as PresetHook, dn as AnyRecord, gt as RouteSchemaOptions, nt as MiddlewareConfig, pt as RouteDefinition, tn as HookSystem } from "../index-Cl0uoKd5.mjs";
-import { t as ExternalOpenApiPaths } from "../externalPaths-BQ8QijNH.mjs";
-import { _ as CachingRule, a as VersioningOptions, c as MetricEntry, d as _default$4, f as metricsPlugin, g as CachingOptions, h as ssePlugin, i as errorHandlerPlugin, l as MetricsCollector, m as _default$6, n as ErrorMapper, o as _default$7, p as SSEOptions, r as defaultIsDuplicateKeyError, s as versioningPlugin, t as ErrorHandlerOptions, u as MetricsOptions, v as _default$1, y as cachingPlugin } from "../errorHandler-DRQ3EqfL.mjs";
-import { t as TracingOptions } from "../tracing-65B51Dw3.mjs";
+import { Pt as AnyRecord, Q as MiddlewareConfig, ft as RouteSchemaOptions, gn as HookSystem, lt as RouteDefinition, tt as PresetHook, z as ResourceRegistry } from "../index-Cm0vUrr_.mjs";
+import { t as ExternalOpenApiPaths } from "../externalPaths-Bapitwvd.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-M9lNLhO8.mjs";
+import { i as errorHandlerPlugin, n as ErrorMapper, r as defaultIsDuplicateKeyError, t as ErrorHandlerOptions } from "../errorHandler-Co3lnVmJ.mjs";
+import { t as TracingOptions } from "../tracing-DokiEsuz.mjs";
 import { FastifyInstance, FastifyPluginAsync } from "fastify";
 import * as _$node_stream0 from "node:stream";
 
@@ -34,7 +35,26 @@ interface ArcCore {
 }
 declare module "fastify" {
   interface FastifyInstance {
-    arc: ArcCore;
+    /**
+     * Arc core decorator. Optional because:
+     *
+     * 1. Consumers who import any `@classytic/arc/*` subpath get this module
+     *    augmentation merged into every `FastifyInstance` they see — even
+     *    instances on apps that never register {@link arcCorePlugin}. Making
+     *    it required would force those apps to assert or guard every
+     *    property access.
+     * 2. Hosts that extend `FastifyInstance` to narrow `arc` to their own
+     *    type (`interface X extends FastifyInstance { arc?: MyArc }`) were
+     *    previously blocked because non-optional `arc: ArcCore` conflicts
+     *    with the re-declaration. An optional field lets hosts re-declare
+     *    with a compatible subtype without fighting TS.
+     *
+     * Inside Arc's own code, any call site that runs *after* `arcCorePlugin`
+     * has registered treats this as non-null — see the call sites in
+     * `factory/registerAuth.ts` and `factory/createApp.ts` which assert
+     * with `fastify.arc!` or narrow explicitly.
+     */
+    arc?: ArcCore;
   }
 }
 declare const arcCorePlugin: FastifyPluginAsync<ArcCorePluginOptions>;

package/dist/plugins/index.mjs

@@ -1,15 +1,15 @@
 import { p as MUTATION_OPERATIONS } from "../constants-BhY1OHoH.mjs";
 import { o as getOrgId } from "../types-AOD8fxIw.mjs";
-import { t as requestContext } from "../requestContext-xHIKedG6.mjs";
-import { t as hasEvents } from "../typeGuards-Cj5Rgvlg.mjs";
-import { t as HookSystem } from "../HookSystem-BNYKnrXF.mjs";
-import { t as ResourceRegistry } from "../ResourceRegistry-BPd6NQDm.mjs";
-import { n as caching_default, t as cachingPlugin } from "../caching-CBpK_SCM.mjs";
-import { n as errorHandlerPlugin, t as defaultIsDuplicateKeyError } from "../errorHandler-Bb49BvPD.mjs";
-import { n as metrics_default, t as metricsPlugin } from "../metrics-DuhiSEZI.mjs";
-import { t as replyHelpersPlugin } from "../replyHelpers-CXtJDAZ0.mjs";
-import { n as sse_default, t as ssePlugin } from "../sse-yBCgOLGu.mjs";
-import { n as versioning_default, t as versioningPlugin } from "../versioning-C2U_bLY0.mjs";
+import { t as requestContext } from "../requestContext-CfRkaxwf.mjs";
+import { t as hasEvents } from "../typeGuards-CcFZXgU7.mjs";
+import { t as HookSystem } from "../HookSystem-CGsMd6oK.mjs";
+import { t as ResourceRegistry } from "../ResourceRegistry-DkAeAuTX.mjs";
+import { n as caching_default, t as cachingPlugin } from "../caching-CheW3m-S.mjs";
+import { n as errorHandlerPlugin, t as defaultIsDuplicateKeyError } from "../errorHandler-BQm8ZxTK.mjs";
+import { n as metrics_default, t as metricsPlugin } from "../metrics-Csh4nsvv.mjs";
+import { t as replyHelpersPlugin } from "../replyHelpers-ByllIXXV.mjs";
+import { n as sse_default, t as ssePlugin } from "../sse-V7aXc3bW.mjs";
+import { n as versioning_default, t as versioningPlugin } from "../versioning-CGPjkqAg.mjs";
 import { randomUUID } from "node:crypto";
 import fp from "fastify-plugin";
 //#region src/core/arcCorePlugin.ts

package/dist/plugins/response-cache.mjs

@@ -1,4 +1,4 @@
-import { t as hasEvents } from "../typeGuards-Cj5Rgvlg.mjs";
+import { t as hasEvents } from "../typeGuards-CcFZXgU7.mjs";
 import fp from "fastify-plugin";
 //#region src/plugins/response-cache.ts
 /**

package/dist/plugins/tracing-entry.d.mts

@@ -1,2 +1,2 @@
-import { a as traced, i as isTracingAvailable, n as _default, r as createSpan, t as TracingOptions } from "../tracing-65B51Dw3.mjs";
+import { a as traced, i as isTracingAvailable, n as _default, r as createSpan, t as TracingOptions } from "../tracing-DokiEsuz.mjs";
 export { type TracingOptions, createSpan, isTracingAvailable, traced, _default as tracingPlugin };

package/dist/plugins/tracing-entry.mjs

@@ -14,6 +14,20 @@ import fp from "fastify-plugin";
 *   serviceName: 'my-api',
 *   exporterUrl: 'http://localhost:4318/v1/traces', // OTLP endpoint
 * });
+*
+* ## Type strategy
+*
+* `@opentelemetry/api` is the stable surface — its types are type-only
+* imported here so hook handlers, `createSpan`, and `traced` don't hand
+* out `any` for Tracer / Span. Only the runtime-loaded module BODIES
+* (`trace.getTracer`, `context.with`, etc.) go through the optional-require
+* path; everything downstream keeps its shape through the plugin.
+*
+* The SDK-side factories (`NodeTracerProvider`, `BatchSpanProcessor`,
+* `OTLPTraceExporter`) aren't in @classytic/arc's devDeps and aren't
+* type-importable without adding install weight, so those retain
+* minimal constructor-style `unknown`-valued boxes. If a future refactor
+* moves SDK types into devDependencies we can tighten further.
 */
 const require = createRequire(import.meta.url);
 let trace;
@@ -33,8 +47,8 @@ try {
 	NodeTracerProvider = sdkNode.NodeTracerProvider;
 	BatchSpanProcessor = sdkNode.BatchSpanProcessor;
 	OTLPTraceExporter = require("@opentelemetry/exporter-trace-otlp-http").OTLPTraceExporter;
-	require("@opentelemetry/instrumentation-http").HttpInstrumentation;
-	require("@opentelemetry/instrumentation-mongodb").MongoDBInstrumentation;
+	require("@opentelemetry/instrumentation-http");
+	require("@opentelemetry/instrumentation-mongodb");
 	getNodeAutoInstrumentations = require("@opentelemetry/auto-instrumentations-node").getNodeAutoInstrumentations;
 	isAvailable = true;
 } catch (_e) {}
@@ -42,9 +56,9 @@ try {
 * Create a tracer provider
 */
 function createTracerProvider(options) {
-	if (!isAvailable) return null;
+	if (!isAvailable || !NodeTracerProvider || !BatchSpanProcessor || !OTLPTraceExporter) return null;
 	const { serviceName = "@classytic/arc", serviceVersion, exporterUrl = "http://localhost:4318/v1/traces" } = options;
-	const resolvedVersion = serviceVersion ?? "2.10.3";
+	const resolvedVersion = serviceVersion ?? "2.11.0";
 	const exporter = new OTLPTraceExporter({ url: exporterUrl });
 	const provider = new NodeTracerProvider({ resource: { attributes: {
 		"service.name": serviceName,
@@ -59,11 +73,14 @@ function createTracerProvider(options) {
 */
 async function tracingPlugin(fastify, options = {}) {
 	const { serviceName = "@classytic/arc", autoInstrumentation = true, sampleRate = 1 } = options;
-	if (!isAvailable) {
+	if (!isAvailable || !trace || !context || !SpanStatusCode) {
 		fastify.log.warn("OpenTelemetry not installed. Tracing disabled.");
 		fastify.log.warn("Install: npm install @opentelemetry/api @opentelemetry/sdk-node");
 		return;
 	}
+	const otelTrace = trace;
+	const otelContext = context;
+	const otelStatus = SpanStatusCode;
 	if (!createTracerProvider(options)) return;
 	if (autoInstrumentation && getNodeAutoInstrumentations) {
 		const instrumentations = getNodeAutoInstrumentations({
@@ -73,7 +90,7 @@ async function tracingPlugin(fastify, options = {}) {
 		for (const instrumentation of instrumentations) instrumentation.enable();
 		fastify.log.debug("OpenTelemetry auto-instrumentation enabled");
 	}
-	const tracer = trace.getTracer(serviceName);
+	const tracer = otelTrace.getTracer(serviceName);
 	fastify.decorateRequest("tracer", void 0);
 	fastify.addHook("onRequest", async (request, _reply) => {
 		if (Math.random() > sampleRate) return;
@@ -92,7 +109,7 @@ async function tracingPlugin(fastify, options = {}) {
 			tracer,
 			currentSpan: span
 		};
-		context.with(trace.setSpan(context.active(), span), () => {});
+		otelContext.with(otelTrace.setSpan(otelContext.active(), span), () => {});
 	});
 	fastify.addHook("onResponse", async (request, reply) => {
 		if (!request.tracer?.currentSpan) return;
@@ -101,11 +118,11 @@ async function tracingPlugin(fastify, options = {}) {
 			"http.status_code": reply.statusCode,
 			"http.response_content_length": reply.getHeader("content-length")
 		});
-		if (reply.statusCode >= 500) span.setStatus({
-			code: SpanStatusCode.ERROR,
+		const status = reply.statusCode >= 500 ? {
+			code: otelStatus.ERROR,
 			message: `HTTP ${reply.statusCode}`
-		});
-		else span.setStatus({ code: SpanStatusCode.OK });
+		} : { code: otelStatus.OK };
+		span.setStatus(status);
 		span.end();
 	});
 	fastify.addHook("onError", async (request, _reply, error) => {
@@ -113,7 +130,7 @@ async function tracingPlugin(fastify, options = {}) {
 		const span = request.tracer.currentSpan;
 		span.recordException(error);
 		span.setStatus({
-			code: SpanStatusCode.ERROR,
+			code: otelStatus.ERROR,
 			message: error.message
 		});
 	});
@@ -133,22 +150,23 @@ async function tracingPlugin(fastify, options = {}) {
 * }
 */
 function createSpan(request, name, fn, attributes) {
-	if (!request.tracer) return fn(null);
+	if (!request.tracer || !trace || !context || !SpanStatusCode) return fn(null);
+	const otelTrace = trace;
+	const otelContext = context;
+	const otelStatus = SpanStatusCode;
 	const { tracer, currentSpan } = request.tracer;
-	const span = tracer.startSpan(name, {
-		parent: currentSpan,
-		attributes: attributes || {}
-	}, trace.setSpan(context.active(), currentSpan));
-	return context.with(trace.setSpan(context.active(), span), async () => {
+	const span = tracer.startSpan(name, { attributes: attributes ?? {} }, otelTrace.setSpan(otelContext.active(), currentSpan));
+	return otelContext.with(otelTrace.setSpan(otelContext.active(), span), async () => {
 		try {
 			const result = await fn(span);
-			span.setStatus({ code: SpanStatusCode.OK });
+			span.setStatus({ code: otelStatus.OK });
 			return result;
 		} catch (error) {
-			span.recordException(error);
+			const err = error;
+			span.recordException(err);
 			span.setStatus({
-				code: SpanStatusCode.ERROR,
-				message: error.message
+				code: otelStatus.ERROR,
+				message: err.message
 			});
 			throw error;
 		} finally {
@@ -171,9 +189,9 @@ function traced(spanName) {
 	return (target, propertyKey, descriptor) => {
 		const originalMethod = descriptor.value;
 		descriptor.value = async function(...args) {
-			const request = args.find((arg) => arg?.tracer);
+			const request = args.find((arg) => !!(arg && typeof arg === "object" && "tracer" in arg && arg.tracer));
 			if (!request?.tracer) return originalMethod.apply(this, args);
-			return createSpan(request, spanName || `${target.constructor.name}.${propertyKey}`, async (span) => {
+			return createSpan(request, spanName ?? `${target.constructor.name}.${propertyKey}`, async (span) => {
 				if (span) {
 					span.setAttribute("db.operation", propertyKey);
 					span.setAttribute("db.system", "mongodb");

package/dist/presets/filesUpload.d.mts

@@ -1,7 +1,7 @@
-import { r as RequestScope } from "../types-BD85MlEK.mjs";
-import { c as PermissionCheck } from "../fields-Lo1VUDpt.mjs";
-import { ot as PresetResult } from "../index-Cl0uoKd5.mjs";
-import { a as StorageReadResult, i as StorageReadRange, n as StorageContext, o as StorageUploadInput, r as StorageFile, t as Storage } from "../storage-CVk_SEn2.mjs";
+import { nt as PresetResult } from "../index-Cm0vUrr_.mjs";
+import { r as RequestScope } from "../types-tgR4Pt8F.mjs";
+import { c as PermissionCheck } from "../fields-C8Y0XLAu.mjs";
+import { a as StorageReadResult, i as StorageReadRange, n as StorageContext, o as StorageUploadInput, r as StorageFile, t as Storage } from "../storage-BwGQXUpd.mjs";
 
 //#region src/presets/filesUpload.d.ts
 interface FilesUploadPresetRoutes {

package/dist/presets/filesUpload.mjs

@@ -1,2 +1,256 @@
-import { t as filesUploadPreset } from "../filesUpload-t21LS-py.mjs";
+import { o as getOrgId, p as getUserId } from "../types-AOD8fxIw.mjs";
+import { C as requireAuth, y as allowPublic } from "../permissions-B4vU9L0Q.mjs";
+import { i as NotFoundError, u as ValidationError } from "../errors-D5c-5BJL.mjs";
+import { t as multipartBody } from "../multipartBody-CvTR1Un6.mjs";
+//#region src/presets/filesUpload.ts
+const DEFAULT_FIELD_NAME = "file";
+const DEFAULT_MAX_FILE_SIZE = 10 * 1024 * 1024;
+function defaultContextFrom(scope) {
+	if (!scope) return {};
+	const userId = getUserId(scope);
+	const organizationId = getOrgId(scope);
+	const ctx = {};
+	if (userId !== void 0) ctx.userId = userId;
+	if (organizationId !== void 0) ctx.organizationId = organizationId;
+	return ctx;
+}
+function buildStorageContext(request, contextFrom) {
+	const scope = request.scope;
+	return {
+		scope: contextFrom(scope),
+		requestId: request.id
+	};
+}
+/**
+* Parse a single-range `Range: bytes=start-end` header.
+*
+* Returns `undefined` when the header is missing or unparseable. Only
+* satisfiable single ranges are supported — multi-range requests fall through
+* to the full-object response (per RFC 7233 §4.1 a server MAY ignore ranges).
+*/
+function parseRangeHeader(header, totalSize) {
+	if (!header || !header.startsWith("bytes=")) return void 0;
+	const spec = header.slice(6).split(",")[0]?.trim();
+	if (!spec) return void 0;
+	const dashIndex = spec.indexOf("-");
+	if (dashIndex === -1) return void 0;
+	const startRaw = spec.slice(0, dashIndex);
+	const endRaw = spec.slice(dashIndex + 1);
+	if (startRaw === "") {
+		if (totalSize === void 0) return void 0;
+		const suffix = Number(endRaw);
+		if (!Number.isFinite(suffix) || suffix <= 0) return void 0;
+		return {
+			start: Math.max(0, totalSize - suffix),
+			end: totalSize - 1
+		};
+	}
+	const start = Number(startRaw);
+	if (!Number.isFinite(start) || start < 0) return void 0;
+	if (endRaw === "") {
+		if (totalSize === void 0) return void 0;
+		return {
+			start,
+			end: totalSize - 1
+		};
+	}
+	const end = Number(endRaw);
+	if (!Number.isFinite(end) || end < start) return void 0;
+	if (totalSize !== void 0 && end >= totalSize) return {
+		start,
+		end: totalSize - 1
+	};
+	return {
+		start,
+		end
+	};
+}
+/**
+* Strict policy — rejects filenames that could escape a storage root or
+* confuse a filesystem. Safe default for disk/S3 adapters that compose
+* `${prefix}/${filename}` or `path.join(root, filename)`.
+*/
+function strictFilenamePolicy(filename) {
+	if (filename.length === 0) throw new ValidationError("Upload filename is empty");
+	if (filename.length > 255) throw new ValidationError("Upload filename exceeds 255 characters");
+	if (filename.includes("\0")) throw new ValidationError("Upload filename contains a NUL byte");
+	if (filename.includes("/") || filename.includes("\\")) throw new ValidationError("Upload filename contains a path separator");
+	if (filename === "." || filename === "..") throw new ValidationError("Upload filename is a path traversal component");
+	return filename;
+}
+/** Resolve the user-supplied policy option into a concrete validator. */
+function resolveFilenamePolicy(policy) {
+	if (policy === void 0 || policy === true) return strictFilenamePolicy;
+	if (policy === false || policy === "*") return (f) => f;
+	if (typeof policy === "function") return (filename) => {
+		const result = policy(filename);
+		if (result === false) throw new ValidationError(`Upload filename rejected: ${filename}`);
+		if (typeof result === "string") return result;
+		return filename;
+	};
+	return strictFilenamePolicy;
+}
+function makeUploadHandler(deps) {
+	return async function uploadHandler(request, reply) {
+		const file = (request.body?._files)?.[deps.fieldName];
+		if (!file) throw new ValidationError(`Missing file field '${deps.fieldName}' in multipart body`);
+		const filename = deps.applyFilenamePolicy(file.filename);
+		const ctx = buildStorageContext(request, deps.contextFrom);
+		const result = await deps.storage.upload({
+			buffer: file.buffer,
+			filename,
+			mimeType: file.mimetype,
+			size: file.size
+		}, ctx);
+		return reply.code(201).send({
+			success: true,
+			data: toResponseFile(result)
+		});
+	};
+}
+function toResponseFile(file) {
+	const payload = {
+		id: file.id,
+		url: file.url,
+		pathname: file.pathname,
+		contentType: file.contentType,
+		bytes: file.bytes
+	};
+	if (file.metadata !== void 0) payload.metadata = file.metadata;
+	return payload;
+}
+function makeReadHandler(deps) {
+	return async function readHandler(request, reply) {
+		const { id } = request.params;
+		const ctx = buildStorageContext(request, deps.contextFrom);
+		reply.header("Accept-Ranges", "bytes");
+		const rangeHeader = request.headers.range;
+		let result;
+		try {
+			const parsed = rangeHeader ? parseRangeHeader(rangeHeader, void 0) : void 0;
+			result = await deps.storage.read(id, ctx, parsed);
+		} catch (err) {
+			throw toNotFound(err, "File", id);
+		}
+		if (result.kind === "buffer") return sendBuffer(reply, result, rangeHeader);
+		return sendStream(reply, result, rangeHeader);
+	};
+}
+function sendBuffer(reply, result, rangeHeader) {
+	reply.type(result.contentType);
+	const total = result.totalBytes ?? result.buffer.length;
+	if (result.range) {
+		const { start, end } = result.range;
+		reply.code(206);
+		reply.header("Content-Range", `bytes ${start}-${end}/${total}`);
+		reply.header("Content-Length", String(result.buffer.length));
+		return reply.send(result.buffer);
+	}
+	if (rangeHeader) {
+		const parsed = parseRangeHeader(rangeHeader, total);
+		if (parsed) {
+			const slice = result.buffer.subarray(parsed.start, parsed.end + 1);
+			reply.code(206);
+			reply.header("Content-Range", `bytes ${parsed.start}-${parsed.end}/${total}`);
+			reply.header("Content-Length", String(slice.length));
+			return reply.send(slice);
+		}
+	}
+	reply.header("Content-Length", String(result.buffer.length));
+	return reply.send(result.buffer);
+}
+function sendStream(reply, result, rangeHeader) {
+	reply.type(result.contentType);
+	if (result.range && result.bytes !== void 0) {
+		const { start, end } = result.range;
+		reply.code(206);
+		reply.header("Content-Range", `bytes ${start}-${end}/${result.bytes}`);
+		reply.header("Content-Length", String(end - start + 1));
+	} else if (result.bytes !== void 0) {
+		reply.header("Content-Length", String(result.bytes));
+		if (rangeHeader) reply.request.log.debug({ url: reply.request.url }, "filesUploadPreset: adapter returned unsliced stream for a range request — sending full object");
+	}
+	return reply.send(result.stream);
+}
+function makeDeleteHandler(deps) {
+	return async function deleteHandler(request, reply) {
+		const { id } = request.params;
+		const ctx = buildStorageContext(request, deps.contextFrom);
+		if (!await deps.storage.delete(id, ctx)) throw new NotFoundError("File", id);
+		return reply.code(204).send();
+	};
+}
+function toNotFound(err, resource, id) {
+	if (err instanceof NotFoundError) return err;
+	const maybe = err;
+	if (maybe?.statusCode === 404 || maybe?.code === "NOT_FOUND") return new NotFoundError(resource, id);
+	if (typeof maybe?.message === "string" && /not\s*found/i.test(maybe.message)) return new NotFoundError(resource, id);
+	return err;
+}
+/**
+* Create a files-upload preset bound to a `Storage` adapter.
+*
+* The preset uses `raw: true` routes so binary responses bypass arc's JSON
+* envelope. Upload still returns the standard `{ success: true, data }`
+* envelope manually because the response is structured metadata, not bytes.
+*/
+function filesUploadPreset(options) {
+	if (!options?.storage) throw new Error("filesUploadPreset: `storage` is required");
+	const deps = {
+		storage: options.storage,
+		fieldName: options.fieldName ?? DEFAULT_FIELD_NAME,
+		contextFrom: options.contextFrom ?? defaultContextFrom,
+		applyFilenamePolicy: resolveFilenamePolicy(options.sanitizeFilename)
+	};
+	const maxFileSize = options.maxFileSize ?? DEFAULT_MAX_FILE_SIZE;
+	const allowedMimeTypes = options.allowedMimeTypes;
+	const includeRoutes = {
+		upload: options.includeRoutes?.upload ?? true,
+		read: options.includeRoutes?.read ?? true,
+		delete: options.includeRoutes?.delete ?? true
+	};
+	return {
+		name: "filesUpload",
+		routes: (permissions) => {
+			const routes = [];
+			if (includeRoutes.upload) routes.push({
+				method: "POST",
+				path: "/upload",
+				operation: "filesUpload.upload",
+				summary: "Upload a file",
+				description: "Accepts a multipart/form-data request and persists the bytes via the configured Storage adapter.",
+				permissions: options.permissions?.upload ?? permissions.create ?? requireAuth(),
+				preHandler: [multipartBody({
+					maxFileSize,
+					allowedMimeTypes,
+					requiredFields: [deps.fieldName]
+				})],
+				raw: true,
+				handler: makeUploadHandler(deps)
+			});
+			if (includeRoutes.read) routes.push({
+				method: "GET",
+				path: "/:id",
+				operation: "filesUpload.read",
+				summary: "Download a file",
+				description: "Streams the stored bytes. Supports single-range `Range: bytes=start-end`.",
+				permissions: options.permissions?.read ?? permissions.get ?? allowPublic(),
+				raw: true,
+				handler: makeReadHandler(deps),
+				mcp: false
+			});
+			if (includeRoutes.delete) routes.push({
+				method: "DELETE",
+				path: "/:id",
+				operation: "filesUpload.delete",
+				summary: "Delete a file",
+				permissions: options.permissions?.delete ?? permissions.delete ?? requireAuth(),
+				raw: true,
+				handler: makeDeleteHandler(deps)
+			});
+			return routes;
+		}
+	};
+}
+//#endregion
 export { filesUploadPreset };

package/dist/presets/index.d.mts

@@ -1,4 +1,4 @@
-import { St as IRequestContext, dn as AnyRecord, lt as ResourceConfig, ot as PresetResult, u as PaginationResult, xt as IControllerResponse } from "../index-Cl0uoKd5.mjs";
+import { Pt as AnyRecord, _t as IControllerResponse, at as ResourceConfig, d as PaginationResult, nt as PresetResult, vt as IRequestContext } from "../index-Cm0vUrr_.mjs";
 import { FilesUploadPresetOptions, FilesUploadPresetPermissions, FilesUploadPresetRoutes, filesUploadPreset } from "./filesUpload.mjs";
 import { MultiTenantOptions, TenantFieldSpec, multiTenantPreset } from "./multiTenant.mjs";
 import { SearchHandler, SearchPresetOptions, SearchRouteConfig, searchPreset } from "./search.mjs";

package/dist/presets/index.mjs

@@ -1,5 +1,5 @@
 import { multiTenantPreset } from "./multiTenant.mjs";
-import { a as registerPreset, c as auditedPreset, d as ownedByUserPreset, i as getPreset, l as softDeletePreset, n as flexibleMultiTenantPreset, o as treePreset, r as getAvailablePresets, s as bulkPreset, t as applyPresets, u as slugLookupPreset } from "../presets-fLJVXdVn.mjs";
-import { t as filesUploadPreset } from "../filesUpload-t21LS-py.mjs";
+import { a as registerPreset, c as auditedPreset, d as ownedByUserPreset, i as getPreset, l as softDeletePreset, n as flexibleMultiTenantPreset, o as treePreset, r as getAvailablePresets, s as bulkPreset, t as applyPresets, u as slugLookupPreset } from "../presets-k604Lj99.mjs";
+import { filesUploadPreset } from "./filesUpload.mjs";
 import { searchPreset } from "./search.mjs";
 export { applyPresets, auditedPreset, bulkPreset, filesUploadPreset, flexibleMultiTenantPreset, getAvailablePresets, getPreset, multiTenantPreset, ownedByUserPreset, registerPreset, searchPreset, slugLookupPreset, softDeletePreset, treePreset };

package/dist/presets/multiTenant.d.mts

@@ -1,4 +1,4 @@
-import { Q as CrudRouteKey, ot as PresetResult } from "../index-Cl0uoKd5.mjs";
+import { J as CrudRouteKey, nt as PresetResult } from "../index-Cm0vUrr_.mjs";
 
 //#region src/presets/multiTenant.d.ts
 /**