@classytic/arc 2.8.3 → 2.8.5

package/dist/presets/index.d.mts

@@ -1,4 +1,5 @@
-import { Ht as IControllerResponse, Ut as IRequestContext, m as AnyRecord, on as PaginationResult, tt as PresetResult, ut as ResourceConfig } from "../interface-BVuMfeVv.mjs";
+import { Ht as IControllerResponse, Ut as IRequestContext, m as AnyRecord, on as PaginationResult, tt as PresetResult, ut as ResourceConfig } from "../interface-CMRutPfe.mjs";
+import { FilesUploadPresetOptions, FilesUploadPresetPermissions, FilesUploadPresetRoutes, filesUploadPreset } from "./filesUpload.mjs";
 import { MultiTenantOptions, TenantFieldSpec, multiTenantPreset } from "./multiTenant.mjs";
 
 //#region src/presets/ownedByUser.d.ts
@@ -271,4 +272,4 @@ type PresetInput = string | PresetResult | {
  */
 declare function applyPresets<TDoc = AnyRecord>(config: ResourceConfig<TDoc>, presets?: PresetInput[]): ResourceConfig<TDoc>;
 //#endregion
-export { type AuditedPresetOptions, type BulkOperation, type BulkPresetOptions, type IAuditedPreset, type IMultiTenantPreset, type IOwnedByUserPreset, type IPresetController, type ISlugLookupController, type ISoftDeleteController, type ITreeController, type MultiTenantOptions, type OwnedByUserOptions, type SlugLookupOptions, type TenantFieldSpec, type TreeOptions, applyPresets, auditedPreset, bulkPreset, flexibleMultiTenantPreset, getAvailablePresets, getPreset, multiTenantPreset, ownedByUserPreset, registerPreset, slugLookupPreset, softDeletePreset, treePreset };
+export { type AuditedPresetOptions, type BulkOperation, type BulkPresetOptions, type FilesUploadPresetOptions, type FilesUploadPresetPermissions, type FilesUploadPresetRoutes, type IAuditedPreset, type IMultiTenantPreset, type IOwnedByUserPreset, type IPresetController, type ISlugLookupController, type ISoftDeleteController, type ITreeController, type MultiTenantOptions, type OwnedByUserOptions, type SlugLookupOptions, type TenantFieldSpec, type TreeOptions, applyPresets, auditedPreset, bulkPreset, filesUploadPreset, flexibleMultiTenantPreset, getAvailablePresets, getPreset, multiTenantPreset, ownedByUserPreset, registerPreset, slugLookupPreset, softDeletePreset, treePreset };

package/dist/presets/index.mjs

@@ -1,3 +1,4 @@
 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-C2xgzW6x.mjs";
-export { applyPresets, auditedPreset, bulkPreset, flexibleMultiTenantPreset, getAvailablePresets, getPreset, multiTenantPreset, ownedByUserPreset, registerPreset, slugLookupPreset, softDeletePreset, treePreset };
+import { t as filesUploadPreset } from "../filesUpload-C7r7HIeA.mjs";
+export { applyPresets, auditedPreset, bulkPreset, filesUploadPreset, flexibleMultiTenantPreset, getAvailablePresets, getPreset, multiTenantPreset, ownedByUserPreset, registerPreset, slugLookupPreset, softDeletePreset, treePreset };

package/dist/presets/multiTenant.d.mts

@@ -1,4 +1,4 @@
-import { E as CrudRouteKey, tt as PresetResult } from "../interface-BVuMfeVv.mjs";
+import { E as CrudRouteKey, tt as PresetResult } from "../interface-CMRutPfe.mjs";
 
 //#region src/presets/multiTenant.d.ts
 /**

package/dist/{queryCachePlugin-CnTZZTC5.d.mts → queryCachePlugin-BJJGBTlu.d.mts}

@@ -1,4 +1,4 @@
-import { i as CacheStore } from "./interface-DplgQO2e.mjs";
+import { i as CacheStore } from "./interface-4y979v99.mjs";
 import { FastifyPluginAsync } from "fastify";
 
 //#region src/cache/QueryCache.d.ts

package/dist/redis-BM00zaPB.d.mts

@@ -0,0 +1,115 @@
+import { n as IdempotencyResult, r as IdempotencyStore } from "./interface-DfLGcus7.mjs";
+
+//#region src/idempotency/stores/redis.d.ts
+interface RedisClient {
+  get(key: string): Promise<string | null>;
+  set(key: string, value: string, options?: {
+    EX?: number;
+    NX?: boolean;
+  }): Promise<string | null>;
+  del(key: string | string[]): Promise<number>;
+  exists(key: string | string[]): Promise<number>;
+  /** SCAN command — compatible with node-redis and ioredis varargs signatures. */
+  scan?(cursor: string | number, ...args: (string | number)[]): Promise<[string | number, string[]]>;
+  quit?(): Promise<string>;
+  disconnect?(): Promise<void>;
+}
+interface RedisIdempotencyStoreOptions {
+  /** Redis client instance */
+  client: RedisClient;
+  /** Key prefix (default: 'idem:') */
+  prefix?: string;
+  /** Lock key prefix (default: 'idem:lock:') */
+  lockPrefix?: string;
+  /** Default TTL in ms (default: 86400000 = 24 hours) */
+  ttlMs?: number;
+}
+declare class RedisIdempotencyStore implements IdempotencyStore {
+  readonly name = "redis";
+  private client;
+  private prefix;
+  private lockPrefix;
+  private ttlMs;
+  constructor(options: RedisIdempotencyStoreOptions);
+  private resultKey;
+  private lockKey;
+  get(key: string): Promise<IdempotencyResult | undefined>;
+  set(key: string, result: Omit<IdempotencyResult, "key">): Promise<void>;
+  tryLock(key: string, requestId: string, ttlMs: number): Promise<boolean>;
+  unlock(key: string, requestId: string): Promise<void>;
+  isLocked(key: string): Promise<boolean>;
+  delete(key: string): Promise<void>;
+  deleteByPrefix(prefix: string): Promise<number>;
+  findByPrefix(prefix: string): Promise<IdempotencyResult | undefined>;
+  /** Scan Redis keys matching a prefix pattern. Falls back to empty if SCAN unavailable. */
+  private scanByPrefix;
+  close(): Promise<void>;
+}
+/** Minimal ioredis shape we depend on — keeps this file peer-dep-free. */
+interface IoredisLike {
+  get(key: string): Promise<string | null>;
+  set(...args: unknown[]): Promise<string | null>;
+  del(...keys: string[]): Promise<number>;
+  exists(...keys: string[]): Promise<number>;
+  scan(cursor: string | number, ...args: (string | number)[]): Promise<[string, string[]]>;
+  eval?(script: string, numKeys: number, ...args: (string | number)[]): Promise<unknown>;
+  quit?(): Promise<string>;
+  disconnect?(): void;
+}
+/**
+ * Wrap an ioredis instance as the arc idempotency `RedisClient`.
+ *
+ * Arc's idempotency store expects node-redis-v4 style option objects
+ * (`{ EX, NX }`). ioredis uses positional flags. This adapter lets users
+ * plug an ioredis instance in without writing the bridge themselves.
+ *
+ * @example
+ * ```typescript
+ * import Redis from 'ioredis';
+ * import { RedisIdempotencyStore, ioredisAsIdempotencyClient }
+ *   from '@classytic/arc/idempotency/redis';
+ *
+ * const redis = new Redis(process.env.REDIS_URL);
+ * const store = new RedisIdempotencyStore({
+ *   client: ioredisAsIdempotencyClient(redis),
+ * });
+ * ```
+ */
+declare function ioredisAsIdempotencyClient(client: IoredisLike): RedisClient & {
+  eval?: (script: string, numkeys: number, ...args: (string | number)[]) => Promise<unknown>;
+};
+/** Minimal `@upstash/redis` shape we depend on (REST client, edge-safe). */
+interface UpstashRedisLike {
+  get(key: string): Promise<string | null | unknown>;
+  set(key: string, value: unknown, opts?: Record<string, unknown>): Promise<unknown>;
+  del(...keys: string[]): Promise<number>;
+  exists(...keys: string[]): Promise<number>;
+  scan(cursor: number | string, opts?: {
+    match?: string;
+    count?: number;
+  }): Promise<[number, string[]] | [string, string[]]>;
+  eval?(script: string, keys: string[], args: (string | number)[]): Promise<unknown>;
+}
+/**
+ * Wrap an `@upstash/redis` REST client as an idempotency `RedisClient`.
+ *
+ * Enables running arc's idempotency store on Cloudflare Workers, Vercel Edge
+ * and Deno Deploy — runtimes that don't support raw TCP (ioredis).
+ *
+ * @example
+ * ```typescript
+ * import { Redis } from '@upstash/redis';
+ * import { RedisIdempotencyStore, upstashAsIdempotencyClient }
+ *   from '@classytic/arc/idempotency/redis';
+ *
+ * const redis = Redis.fromEnv();
+ * const store = new RedisIdempotencyStore({
+ *   client: upstashAsIdempotencyClient(redis),
+ * });
+ * ```
+ */
+declare function upstashAsIdempotencyClient(client: UpstashRedisLike): RedisClient & {
+  eval?: (script: string, numkeys: number, ...args: (string | number)[]) => Promise<unknown>;
+};
+//#endregion
+export { UpstashRedisLike as a, RedisIdempotencyStoreOptions as i, RedisClient as n, ioredisAsIdempotencyClient as o, RedisIdempotencyStore as r, upstashAsIdempotencyClient as s, IoredisLike as t };

package/dist/{redis-stream-D54N5oXs.d.mts → redis-stream-CrsfUmPt.d.mts}

@@ -1,4 +1,4 @@
-import { i as EventTransport, n as EventHandler, r as EventLogger, t as DomainEvent } from "./EventTransport-CinyO7zQ.mjs";
+import { i as EventTransport, n as EventHandler, r as EventLogger, t as DomainEvent } from "./EventTransport-BXja8NOc.mjs";
 
 //#region src/events/transports/redis-stream.d.ts
 interface RedisStreamLike {

package/dist/registry/index.d.mts

@@ -1,4 +1,4 @@
-import { Gt as RegisterOptions, H as IntrospectionPluginOptions, Kt as ResourceRegistry } from "../interface-BVuMfeVv.mjs";
+import { Gt as RegisterOptions, H as IntrospectionPluginOptions, Kt as ResourceRegistry } from "../interface-CMRutPfe.mjs";
 import { FastifyPluginAsync } from "fastify";
 
 //#region src/registry/introspectionPlugin.d.ts

package/dist/registry/index.mjs

@@ -1,3 +1,3 @@
-import { n as introspectionPlugin_default, t as introspectionPlugin } from "../registry-B0Wl7uVV.mjs";
-import { t as ResourceRegistry } from "../ResourceRegistry-Dq3_zBQP.mjs";
+import { n as introspectionPlugin_default, t as introspectionPlugin } from "../registry-BiTKT1Dg.mjs";
+import { t as ResourceRegistry } from "../ResourceRegistry-C6uXlWe3.mjs";
 export { ResourceRegistry, introspectionPlugin_default as introspectionPlugin, introspectionPlugin as introspectionPluginFn };

package/dist/{resourceToTools-O_HwWXFa.mjs → resourceToTools-8s-EsCCe.mjs}

@@ -1,6 +1,6 @@
 import { t as BaseController } from "./BaseController-DAGGc5Xn.mjs";
 import { n as normalizePermissionResult } from "./applyPermissionResult-D6GPMsvh.mjs";
-import { t as pluralize } from "./pluralize-A0tWEl1K.mjs";
+import { t as pluralize } from "./pluralize-CWP6MB39.mjs";
 import { z } from "zod";
 //#region src/integrations/mcp/createMcpServer.ts
 /**

package/dist/rpc/index.d.mts

@@ -1,4 +1,4 @@
-import { r as CircuitBreakerOptions } from "../circuitBreaker-CvXkjfrW.mjs";
+import { r as CircuitBreakerOptions } from "../circuitBreaker-dTtG-UyS.mjs";
 
 //#region src/rpc/serviceClient.d.ts
 interface RetryConfig {

package/dist/{schemaConverter-OxfCshus.mjs → schemaConverter-Y7nCYaLJ.mjs}

@@ -1,4 +1,8 @@
 //#region src/utils/schemaConverter.ts
+/** Default target for Fastify-consumed schemas (matches Fastify v5's default AJV draft). */
+const DEFAULT_FASTIFY_TARGET = "draft-7";
+/** Default target for OpenAPI document generation (matches arc's emitted OpenAPI version). */
+const DEFAULT_OPENAPI_TARGET = "openapi-3.0";
 let _toJSONSchema = null;
 import("zod").then(({ z }) => {
 	if (typeof z?.toJSONSchema === "function") _toJSONSchema = (schema, opts) => z.toJSONSchema(schema, opts);
@@ -26,17 +30,23 @@ function isZodSchema(input) {
 * Detection order:
 * 1. `null`/`undefined` → `undefined`
 * 2. Already JSON Schema → pass through as-is (zero overhead)
-* 3. Zod v4 schema → `z.toJSONSchema(schema, { target: 'openapi-3.0' })`
+* 3. Zod v4 schema → `z.toJSONSchema(schema, { target })`
 * 4. Unrecognized object → return as-is (treat as opaque schema)
+*
+* @param input Schema (Zod, plain JSON Schema, or opaque object)
+* @param target Output target — defaults to `draft-7` for Fastify compatibility.
+*               Pass `openapi-3.0`/`openapi-3.1` for OpenAPI document generation.
 */
-function toJsonSchema(input) {
+function toJsonSchema(input, target = DEFAULT_FASTIFY_TARGET) {
 	if (input == null) return void 0;
 	if (typeof input !== "object") return void 0;
 	if (isJsonSchema(input)) return input;
 	if (isZodSchema(input)) {
 		if (!_toJSONSchema) return input;
 		try {
-			return _toJSONSchema(input, { target: "openapi-3.0" });
+			const converted = _toJSONSchema(input, { target });
+			if ("$schema" in converted) delete converted.$schema;
+			return converted;
 		} catch {
 			return { type: "object" };
 		}
@@ -46,8 +56,11 @@ function toJsonSchema(input) {
 /**
 * Convert all schema fields in an OpenApiSchemas object.
 * JSON Schema values pass through unchanged. Only Zod schemas are converted.
+*
+* Defaults to the `openapi-3.0` target since this function feeds OpenAPI doc
+* generation, not Fastify route validation.
 */
-function convertOpenApiSchemas(schemas) {
+function convertOpenApiSchemas(schemas, target = DEFAULT_OPENAPI_TARGET) {
 	const result = {};
 	const schemaFields = [
 		"entity",
@@ -59,7 +72,7 @@ function convertOpenApiSchemas(schemas) {
 	];
 	for (const field of schemaFields) {
 		const value = schemas[field];
-		if (value !== void 0) result[field] = toJsonSchema(value) ?? value;
+		if (value !== void 0) result[field] = toJsonSchema(value, target) ?? value;
 	}
 	for (const [key, value] of Object.entries(schemas)) if (!schemaFields.includes(key)) result[key] = value;
 	return result;
@@ -73,19 +86,22 @@ function convertOpenApiSchemas(schemas) {
 * JSON Schema values pass through unchanged. Only Zod schemas are converted.
 *
 * Used for both additionalRoutes and customSchemas (CRUD overrides).
+*
+* Defaults to `draft-7` so Fastify v5's bundled AJV 8 accepts the output.
+* Pass `openapi-3.0` (or `openapi-3.1`) when generating OpenAPI documents.
 */
-function convertRouteSchema(schema) {
+function convertRouteSchema(schema, target = DEFAULT_FASTIFY_TARGET) {
 	const result = { ...schema };
 	for (const field of [
 		"body",
 		"querystring",
 		"params",
 		"headers"
-	]) if (result[field] !== void 0) result[field] = toJsonSchema(result[field]) ?? result[field];
+	]) if (result[field] !== void 0) result[field] = toJsonSchema(result[field], target) ?? result[field];
 	if (result.response !== void 0 && typeof result.response === "object" && result.response !== null) {
 		const responseObj = result.response;
 		const convertedResponse = {};
-		for (const [statusCode, responseSchema] of Object.entries(responseObj)) convertedResponse[statusCode] = toJsonSchema(responseSchema) ?? responseSchema;
+		for (const [statusCode, responseSchema] of Object.entries(responseObj)) convertedResponse[statusCode] = toJsonSchema(responseSchema, target) ?? responseSchema;
 		result.response = convertedResponse;
 	}
 	return result;

package/dist/scope/index.d.mts

@@ -1,5 +1,5 @@
-import { _ as isAuthenticated, a as getClientId, b as isOrgInScope, c as getOrgRoles, d as getScopeContextMap, f as getServiceScopes, g as hasOrgAccess, h as getUserRoles, i as getAncestorOrgIds, l as getRequestScope, m as getUserId, n as PUBLIC_SCOPE, o as getOrgContext, p as getTeamId, r as RequestScope, s as getOrgId, t as AUTHENTICATED_SCOPE, u as getScopeContext, v as isElevated, x as isService, y as isMember } from "../types-C72d3NDn.mjs";
-import { i as elevationPlugin, n as ElevationOptions, r as _default, t as ElevationEvent } from "../elevation-s5ykdNHr.mjs";
+import { _ as isAuthenticated, a as getClientId, b as isOrgInScope, c as getOrgRoles, d as getScopeContextMap, f as getServiceScopes, g as hasOrgAccess, h as getUserRoles, i as getAncestorOrgIds, l as getRequestScope, m as getUserId, n as PUBLIC_SCOPE, o as getOrgContext, p as getTeamId, r as RequestScope, s as getOrgId, t as AUTHENTICATED_SCOPE, u as getScopeContext, v as isElevated, x as isService, y as isMember } from "../types-BD85MlEK.mjs";
+import { i as elevationPlugin, n as ElevationOptions, r as _default, t as ElevationEvent } from "../elevation-B6S5csVA.mjs";
 import { FastifyReply, FastifyRequest } from "fastify";
 
 //#region src/scope/rateLimitKey.d.ts

package/dist/scope/index.mjs

@@ -1,6 +1,6 @@
 import { _ as isElevated, a as getOrgContext, b as isService, c as getRequestScope, d as getServiceScopes, f as getTeamId, g as isAuthenticated, h as hasOrgAccess, i as getClientId, l as getScopeContext, m as getUserRoles, n as PUBLIC_SCOPE, o as getOrgId, p as getUserId, r as getAncestorOrgIds, s as getOrgRoles, t as AUTHENTICATED_SCOPE, u as getScopeContextMap, v as isMember, y as isOrgInScope } from "../types-AOD8fxIw.mjs";
 import { n as normalizeRoles } from "../types-ZUu_h0jp.mjs";
-import { n as elevation_default, t as elevationPlugin } from "../elevation-BBGFjzIP.mjs";
+import { n as elevation_default, t as elevationPlugin } from "../elevation-DtFxrG0s.mjs";
 //#region src/scope/rateLimitKey.ts
 function createTenantKeyGenerator(opts) {
 	if (opts?.strategy) return opts.strategy;

package/dist/{sse-CJpt7LGI.mjs → sse-Ad7ypl9e.mjs}

@@ -1,6 +1,6 @@
 import { t as __exportAll } from "./chunk-BpYLSNr0.mjs";
 import { n as PUBLIC_SCOPE, o as getOrgId } from "./types-AOD8fxIw.mjs";
-import { t as arcLog } from "./logger-CDjpjySd.mjs";
+import { t as arcLog } from "./logger-D1YrIImS.mjs";
 import fp from "fastify-plugin";
 //#region src/plugins/sse.ts
 var sse_exports = /* @__PURE__ */ __exportAll({

package/dist/storage-Dfzt4VTl.d.mts

@@ -0,0 +1,146 @@
+//#region src/types/storage.d.ts
+/**
+ * Arc's minimal backend-agnostic storage contract.
+ *
+ * Implementations live OUTSIDE arc core. This interface is deliberately
+ * small — no variants, no hashing, no CDN transforms, no multi-tenancy
+ * policy. Those are adapter concerns.
+ *
+ * Adapter authors should verify their implementation with
+ * `runStorageContract()` from `@classytic/arc/testing/storage` —
+ * passing the contract guarantees compatibility with every arc preset
+ * that consumes `Storage`.
+ *
+ * @example
+ * ```typescript
+ * import type { Storage } from '@classytic/arc/types/storage';
+ *
+ * export function memoryStorage(): Storage {
+ *   const rows = new Map<string, { buffer: Buffer; contentType: string }>();
+ *   return {
+ *     async upload(input) {
+ *       const id = crypto.randomUUID();
+ *       rows.set(id, { buffer: input.buffer, contentType: input.mimeType });
+ *       return { id, url: `memory://${id}`, pathname: id, contentType: input.mimeType, bytes: input.size };
+ *     },
+ *     async read(id) {
+ *       const row = rows.get(id);
+ *       if (!row) throw new Error('Not found');
+ *       return { kind: 'buffer', buffer: row.buffer, contentType: row.contentType };
+ *     },
+ *     async delete(id) { return rows.delete(id); },
+ *   };
+ * }
+ * ```
+ */
+/**
+ * Input passed to `Storage.upload()`.
+ * The preset populates this from the parsed multipart file.
+ */
+interface StorageUploadInput {
+  /** File bytes. */
+  buffer: Buffer;
+  /** Original filename from the client. */
+  filename: string;
+  /** IANA media type — preset validates via `multipartBody`. */
+  mimeType: string;
+  /** Size in bytes. Equals `buffer.length`. */
+  size: number;
+}
+/**
+ * Context threaded through every storage call.
+ * Adapters decide which keys they care about.
+ */
+interface StorageContext {
+  /**
+   * App-defined scope. Arc populates this from `RequestScope` via the preset's
+   * `contextFrom` option so adapters can isolate per-tenant / per-user / per-project.
+   */
+  scope?: Record<string, unknown>;
+  /** Optional request correlation id for logging. */
+  requestId?: string;
+}
+/**
+ * Handle returned by `Storage.upload()`.
+ * The adapter owns the id namespace and URL format.
+ */
+interface StorageFile {
+  /** Stable ID — the adapter owns the namespace. Used as the route param for GET/DELETE. */
+  id: string;
+  /** Public or signed URL — what the frontend stores in an `<img src>`. */
+  url: string;
+  /** Storage-side path / key. Opaque to arc; useful for admin tooling. */
+  pathname: string;
+  /** IANA media type — usually echoed from `input.mimeType`. */
+  contentType: string;
+  /** Size in bytes. */
+  bytes: number;
+  /** Adapter-defined metadata passed through to the response body. */
+  metadata?: Record<string, unknown>;
+}
+/**
+ * Optional byte range for partial reads.
+ * End-inclusive, matching HTTP `Range: bytes=start-end` semantics and
+ * media-kit's `StorageDriver.read()` contract.
+ */
+interface StorageReadRange {
+  /** First byte offset (inclusive). */
+  start: number;
+  /** Last byte offset (inclusive). */
+  end: number;
+}
+/**
+ * Result of `Storage.read()`.
+ * Adapters pick whichever shape is natural; the preset handler branches on `kind`.
+ * Large/remote backends should return a stream; small/in-memory backends can
+ * return a buffer without wrapping it in a `PassThrough` for no reason.
+ */
+type StorageReadResult = {
+  kind: "stream";
+  stream: NodeJS.ReadableStream;
+  contentType: string; /** Total size of the full object (NOT the ranged slice). Required for `Content-Range`. */
+  bytes?: number; /** Actual byte range returned when the caller passed `range`. */
+  range?: StorageReadRange;
+} | {
+  kind: "buffer";
+  buffer: Buffer;
+  contentType: string; /** Total size of the full object. Used for `Content-Range` on partial reads. */
+  totalBytes?: number; /** Actual byte range returned when the caller passed `range`. */
+  range?: StorageReadRange;
+};
+/**
+ * Minimal storage contract consumed by `filesUploadPreset`.
+ *
+ * Adapters are ~50–100 LOC wrappers around S3, GCS, local FS, GridFS,
+ * media-kit, or a provider Files API. Ship zero reference adapters in
+ * arc core — the one you'd pick is always the wrong default.
+ */
+interface Storage {
+  /** Write bytes, return a stable handle. */
+  upload(input: StorageUploadInput, ctx: StorageContext): Promise<StorageFile>;
+  /**
+   * Read bytes by id. Streaming preferred; Buffer fine for small files.
+   *
+   * If `range` is provided, implementations SHOULD return only the requested
+   * slice and set `range` on the result. Implementations that cannot range
+   * (e.g. trivial in-memory adapters) MAY return the full object and let the
+   * preset slice it — the preset handles both cases.
+   */
+  read(id: string, ctx: StorageContext, range?: StorageReadRange): Promise<StorageReadResult>;
+  /**
+   * Remove bytes by id. MAY be a soft delete — the interface doesn't
+   * dictate lifecycle. Return `false` when the id was already absent.
+   */
+  delete(id: string, ctx: StorageContext): Promise<boolean>;
+  /** Optional — fast existence check without a full read. */
+  exists?(id: string, ctx: StorageContext): Promise<boolean>;
+  /**
+   * Optional — return a fresh URL for an existing id. Called by the preset
+   * when the stored `url` may have expired (signed URLs, rotated buckets).
+   * Default behavior when omitted: the preset falls back to the url stored
+   * on the original `upload()` result.
+   */
+  resolveUrl?(id: string, ctx: StorageContext): Promise<string>;
+}
+//#endregion
+export { StorageReadResult as a, StorageReadRange as i, StorageContext as n, StorageUploadInput as o, StorageFile as r, Storage as t };

package/dist/testing/index.d.mts

@@ -1,5 +1,6 @@
-import { Zt as CrudRepository, m as AnyRecord, qt as ResourceDefinition } from "../interface-BVuMfeVv.mjs";
-import { d as ResourceLike, r as CreateAppOptions } from "../types-Bg2X42_m.mjs";
+import { Zt as CrudRepository, m as AnyRecord, qt as ResourceDefinition } from "../interface-CMRutPfe.mjs";
+import { d as ResourceLike, r as CreateAppOptions } from "../types-Ch9pTQbf.mjs";
+import { StorageContractSetup, StorageContractSetupResult, runStorageContract } from "./storageContract.mjs";
 import Fastify, { FastifyInstance, FastifyServerOptions } from "fastify";
 import { Connection } from "mongoose";
 import { Mock } from "vitest";
@@ -921,4 +922,4 @@ declare class TestDataLoader {
   cleanup(): Promise<void>;
 }
 //#endregion
-export { type AuthProvider, type AuthResponse, type BetterAuthTestHelpers, type BetterAuthTestHelpersOptions, type CreateTestAppOptions, DatabaseSnapshot, TestFixtures as DbTestFixtures, type GenerateTestFileOptions, HttpTestHarness, type HttpTestHarnessOptions, InMemoryDatabase, type OrgResponse, type SetupBetterAuthOrgOptions, type SetupUserConfig, type TestAppResult, TestDataLoader, TestDatabase, type TestFixtures$1 as TestFixtures, TestHarness, type TestHarnessOptions, type TestOrgContext, TestRequestBuilder, TestSeeder, TestTransaction, type TestUserContext, createBetterAuthProvider, createBetterAuthTestHelpers, createConfigTestSuite, createDataFactory, createHttpTestHarness, createJwtAuthProvider, createMinimalTestApp, createMockController, createMockReply, createMockRepository, createMockRequest, createMockUser, createSnapshotMatcher, createSpy, createTestApp, createTestAuth, createTestHarness, createTestTimer, generateTestFile, preloadResources, preloadResourcesAsync, request, safeParseBody, setupBetterAuthOrg, waitFor, withTestDb };
+export { type AuthProvider, type AuthResponse, type BetterAuthTestHelpers, type BetterAuthTestHelpersOptions, type CreateTestAppOptions, DatabaseSnapshot, TestFixtures as DbTestFixtures, type GenerateTestFileOptions, HttpTestHarness, type HttpTestHarnessOptions, InMemoryDatabase, type OrgResponse, type SetupBetterAuthOrgOptions, type SetupUserConfig, type StorageContractSetup, type StorageContractSetupResult, type TestAppResult, TestDataLoader, TestDatabase, type TestFixtures$1 as TestFixtures, TestHarness, type TestHarnessOptions, type TestOrgContext, TestRequestBuilder, TestSeeder, TestTransaction, type TestUserContext, createBetterAuthProvider, createBetterAuthTestHelpers, createConfigTestSuite, createDataFactory, createHttpTestHarness, createJwtAuthProvider, createMinimalTestApp, createMockController, createMockReply, createMockRepository, createMockRequest, createMockUser, createSnapshotMatcher, createSpy, createTestApp, createTestAuth, createTestHarness, createTestTimer, generateTestFile, preloadResources, preloadResourcesAsync, request, runStorageContract, safeParseBody, setupBetterAuthOrg, waitFor, withTestDb };

package/dist/testing/index.mjs

@@ -1,5 +1,6 @@
 import { t as CRUD_OPERATIONS } from "../constants-Cxde4rpC.mjs";
 import { n as applyFieldWritePermissions, t as applyFieldReadPermissions } from "../fields-ipsbIRPK.mjs";
+import { runStorageContract } from "./storageContract.mjs";
 import Fastify from "fastify";
 import mongoose from "mongoose";
 import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
@@ -1796,7 +1797,7 @@ function runEventTests(resourceName, displayName, events) {
 * ```
 */
 async function createTestApp(options = {}) {
-	const { createApp } = await import("../createApp-BOYjBgdI.mjs").then((n) => n.r);
+	const { createApp } = await import("../createApp-B1EY8zxa.mjs").then((n) => n.r);
 	const { useInMemoryDb = true, mongoUri: providedMongoUri, ...appOptions } = options;
 	const defaultAuth = {
 		type: "jwt",
@@ -1994,4 +1995,4 @@ var TestDataLoader = class {
 	}
 };
 //#endregion
-export { DatabaseSnapshot, TestFixtures as DbTestFixtures, HttpTestHarness, InMemoryDatabase, TestDataLoader, TestDatabase, TestHarness, TestRequestBuilder, TestSeeder, TestTransaction, createBetterAuthProvider, createBetterAuthTestHelpers, createConfigTestSuite, createDataFactory, createHttpTestHarness, createJwtAuthProvider, createMinimalTestApp, createMockController, createMockReply, createMockRepository, createMockRequest, createMockUser, createSnapshotMatcher, createSpy, createTestApp, createTestAuth, createTestHarness, createTestTimer, generateTestFile, preloadResources, preloadResourcesAsync, request, safeParseBody, setupBetterAuthOrg, waitFor, withTestDb };
+export { DatabaseSnapshot, TestFixtures as DbTestFixtures, HttpTestHarness, InMemoryDatabase, TestDataLoader, TestDatabase, TestHarness, TestRequestBuilder, TestSeeder, TestTransaction, createBetterAuthProvider, createBetterAuthTestHelpers, createConfigTestSuite, createDataFactory, createHttpTestHarness, createJwtAuthProvider, createMinimalTestApp, createMockController, createMockReply, createMockRepository, createMockRequest, createMockUser, createSnapshotMatcher, createSpy, createTestApp, createTestAuth, createTestHarness, createTestTimer, generateTestFile, preloadResources, preloadResourcesAsync, request, runStorageContract, safeParseBody, setupBetterAuthOrg, waitFor, withTestDb };

package/dist/testing/storageContract.d.mts

@@ -0,0 +1,26 @@
+import { t as Storage } from "../storage-Dfzt4VTl.mjs";
+
+//#region src/testing/storageContract.d.ts
+interface StorageContractSetupResult {
+  storage: Storage;
+  teardown: () => Promise<void>;
+}
+type StorageContractSetup = () => Promise<StorageContractSetupResult>;
+/**
+ * Register the storage contract suite under the caller's name.
+ *
+ * Assertions covered:
+ *  1. upload() returns a StorageFile with every required field populated
+ *  2. read(upload.id) round-trips the exact bytes
+ *  3. delete() returns true on first call
+ *  4. delete() returns false (or throws) on a missing id
+ *  5. exists() (if implemented) agrees with upload/delete state
+ *  6. resolveUrl() (if implemented) returns a non-empty URL for an existing id
+ *  7. Two isolated scopes don't collide (scope threading)
+ *  8. Full lifecycle: upload → read → delete → read rejects
+ *  9. Both `kind: "stream"` and `kind: "buffer"` read results deliver correct bytes
+ * 10. Ranged reads (if adapter supports them) slice correctly
+ */
+declare function runStorageContract(name: string, setup: StorageContractSetup): void;
+//#endregion
+export { StorageContractSetup, StorageContractSetupResult, runStorageContract };