@spinekit/media 0.1.1

package/dist/index.mjs

@@ -0,0 +1,628 @@
+import { FOLDER_CONTENT_TYPE_MAP, IMAGE_SETTINGS, SIZE_VARIANTS } from "./config/media.defaults.mjs";
+import { defineResource, mergeResourceConfig } from "@classytic/arc";
+import { createEngineSlot } from "@spinekit/kit/engine-slot";
+import { resolveSpineTenant } from "@spinekit/kit/tenant";
+import { scopeFirstCtx } from "@classytic/arc/scope";
+import { QueryParser } from "@classytic/mongokit";
+import { createMongooseAdapter } from "@classytic/mongokit/adapter";
+import { allowPublic, requireOrgRole } from "@classytic/arc/permissions";
+import { defineEngineModule } from "@spinekit/kit/engine-module";
+import { MEDIA_TRANSFORM_POLICY_VERSION } from "@classytic/media-transform/policy";
+import { confirmUploadSchema, startWriteSchema } from "@classytic/media-kit/schemas";
+import { createAssetTransform } from "@classytic/media-kit/transforms";
+//#region src/config/transform-policy.ts
+/** Longest edge a size variant occupies, from its width/height box. */
+function edgeOf(variant) {
+	return Math.max(variant.width ?? 0, variant.height ?? 0);
+}
+/**
+* Build the policy document served to clients.
+*
+* Ordering matters and is deliberate: untouched folders are matched FIRST, so a
+* deployment can never accidentally shadow them with a broader imagery rule.
+*/
+function buildTransformPolicy(input = {}) {
+	const derivatives = SIZE_VARIANTS.map((v) => ({
+		name: v.name,
+		maxEdge: edgeOf(v),
+		quality: v.quality !== void 0 ? v.quality / 100 : void 0
+	})).filter((d) => d.maxEdge > 0);
+	const rules = [];
+	if (input.untouchedFolders?.length) rules.push({
+		id: "originals-untouched",
+		when: { folder: [...input.untouchedFolders] },
+		use: false
+	});
+	const avatarFolders = FOLDER_CONTENT_TYPE_MAP.avatar;
+	if (avatarFolders.length > 0) rules.push({
+		id: "avatars",
+		when: { folder: [...avatarFolders] },
+		use: { preset: "avatar" }
+	});
+	return {
+		version: MEDIA_TRANSFORM_POLICY_VERSION,
+		rules,
+		/**
+		* Ordinary imagery — product, category, banner, brand and anything a
+		* deployment adds later. `ecom` keeps zoomable detail; the derivatives are
+		* the server's own declared variants, now produced on the device that
+		* already holds the decoded bitmap.
+		*
+		* A fallback is REQUIRED by the contract, so "no rule matched" can never
+		* mean "client decides".
+		*/
+		fallback: {
+			preset: "ecom",
+			maxEdge: input.maxEdge ?? IMAGE_SETTINGS.defaultMaxWidth,
+			derivatives
+		}
+	};
+}
+//#endregion
+//#region src/cleanup.ts
+/** Count candidates through the repository so tenant scoping still applies. */
+async function countCandidates(repo, filters, options) {
+	const found = await repo.getAll({ filters }, {
+		lean: true,
+		...options
+	});
+	return Array.isArray(found) ? found.length : 0;
+}
+/**
+* The three media purge steps, in the order a full cleanup should run them:
+* stale uploads first (cheapest, unblocks nothing), then expired assets, then
+* the soft-delete backlog.
+*/
+function mediaCleanupSteps(engine, options = {}) {
+	const repo = engine.repositories.media;
+	const ctx = options.ctx;
+	const tenantOpts = () => repo._tenantOpts?.(ctx) ?? {};
+	return [
+		{
+			id: "media.stale-pending",
+			resource: "abandoned media uploads",
+			destructive: true,
+			async estimate(stepCtx) {
+				const cutoff = options.stalePendingOlderThan ?? stepCtx.now;
+				const estimated = await countCandidates(repo, {
+					status: { $in: ["pending", "deleting"] },
+					createdAt: { $lt: cutoff }
+				}, tenantOpts());
+				return {
+					resource: this.resource,
+					estimated,
+					retained: "completed uploads untouched",
+					warnings: ["Removes the storage object as well as the row — irreversible.", "Not chunked: the kernel loads all candidates before deleting, so a cancel lands after this step, not mid-sweep."]
+				};
+			},
+			async execute(stepCtx) {
+				await stepCtx.throwIfCancelled?.();
+				try {
+					const processed = await repo.purgeStalePending(options.stalePendingOlderThan, ctx);
+					await stepCtx.onProgress?.({
+						resource: this.resource,
+						processed
+					});
+					return {
+						resource: this.resource,
+						processed,
+						ok: true
+					};
+				} catch (error) {
+					return {
+						resource: this.resource,
+						processed: 0,
+						ok: false,
+						error: error instanceof Error ? error.message : String(error)
+					};
+				}
+			},
+			async verify(stepCtx) {
+				const cutoff = options.stalePendingOlderThan ?? stepCtx.now;
+				const remaining = await countCandidates(repo, {
+					status: { $in: ["pending", "deleting"] },
+					createdAt: { $lt: cutoff }
+				}, tenantOpts());
+				return [{
+					name: "media.stale-pending.drained",
+					ok: remaining === 0,
+					detail: remaining === 0 ? "no stale uploads remain" : `${remaining} still present`
+				}];
+			}
+		},
+		{
+			id: "media.expired",
+			resource: "expired media assets",
+			destructive: true,
+			async estimate(stepCtx) {
+				const cutoff = options.expiredBefore ?? stepCtx.now;
+				const estimated = await countCandidates(repo, { expiresAt: {
+					$ne: null,
+					$lte: cutoff
+				} }, tenantOpts());
+				return {
+					resource: this.resource,
+					estimated,
+					retained: "assets without an expiry, and those not yet expired",
+					warnings: ["Removes the storage object as well as the row — irreversible."]
+				};
+			},
+			async execute(stepCtx) {
+				await stepCtx.throwIfCancelled?.();
+				try {
+					const result = await repo.purgeExpired(options.expiredBefore, ctx);
+					const processed = result.success.length;
+					await stepCtx.onProgress?.({
+						resource: this.resource,
+						processed
+					});
+					return {
+						resource: this.resource,
+						processed,
+						ok: result.failed.length === 0,
+						...result.failed.length > 0 ? { error: `${result.failed.length} asset(s) failed to purge` } : {}
+					};
+				} catch (error) {
+					return {
+						resource: this.resource,
+						processed: 0,
+						ok: false,
+						error: error instanceof Error ? error.message : String(error)
+					};
+				}
+			},
+			async verify(stepCtx) {
+				const cutoff = options.expiredBefore ?? stepCtx.now;
+				const remaining = await countCandidates(repo, { expiresAt: {
+					$ne: null,
+					$lte: cutoff
+				} }, tenantOpts());
+				return [{
+					name: "media.expired.drained",
+					ok: remaining === 0,
+					detail: remaining === 0 ? "no expired assets remain" : `${remaining} still present`
+				}];
+			}
+		},
+		{
+			id: "media.soft-deleted",
+			resource: "soft-deleted media",
+			destructive: true,
+			async estimate(_stepCtx) {
+				const estimated = options.deletedOlderThan ? await countCandidates(repo, { deletedAt: {
+					$ne: null,
+					$lt: options.deletedOlderThan
+				} }, {
+					includeDeleted: true,
+					...tenantOpts()
+				}) : await countCandidates(repo, { deletedAt: { $ne: null } }, {
+					includeDeleted: true,
+					...tenantOpts()
+				});
+				return {
+					resource: this.resource,
+					estimated,
+					retained: "live media untouched",
+					warnings: [
+						"Removes the storage object as well as the row — irreversible.",
+						...options.deletedOlderThan ? [] : ["No explicit cutoff: the kernel default (softDelete.ttlDays, 30d) applies, so this estimate counts the FULL soft-deleted set and may overstate what is purged. Pass `deletedOlderThan` for an exact preview."],
+						"Not chunked: the kernel loads all candidates before deleting."
+					]
+				};
+			},
+			async execute(stepCtx) {
+				await stepCtx.throwIfCancelled?.();
+				try {
+					const processed = await repo.purgeDeleted(options.deletedOlderThan, ctx);
+					await stepCtx.onProgress?.({
+						resource: this.resource,
+						processed
+					});
+					return {
+						resource: this.resource,
+						processed,
+						ok: true
+					};
+				} catch (error) {
+					return {
+						resource: this.resource,
+						processed: 0,
+						ok: false,
+						error: error instanceof Error ? error.message : String(error)
+					};
+				}
+			},
+			async verify(_stepCtx) {
+				if (!options.deletedOlderThan) return [{
+					name: "media.soft-deleted.swept",
+					ok: true,
+					detail: `${await countCandidates(repo, { deletedAt: { $ne: null } }, {
+						includeDeleted: true,
+						...tenantOpts()
+					})} soft-deleted row(s) remain inside the kernel retention window`
+				}];
+				const remaining = await countCandidates(repo, { deletedAt: {
+					$ne: null,
+					$lt: options.deletedOlderThan
+				} }, {
+					includeDeleted: true,
+					...tenantOpts()
+				});
+				return [{
+					name: "media.soft-deleted.drained",
+					ok: remaining === 0,
+					detail: remaining === 0 ? "no purgeable soft-deleted media remain" : `${remaining} still present`
+				}];
+			}
+		}
+	];
+}
+//#endregion
+//#region src/index.ts
+function createMediaRolePermissions(input) {
+	if (input.view.length === 0 || input.upload.length === 0 || input.manage.length === 0) throw new Error("createMediaRolePermissions: role lists must not be empty");
+	return {
+		view: requireOrgRole(...input.view),
+		upload: requireOrgRole(...input.upload),
+		manage: requireOrgRole(...input.manage)
+	};
+}
+function createMediaEngineSlot() {
+	return createEngineSlot("media");
+}
+/** Actor context from the arc request — the actor is ALWAYS the authenticated user. */
+function ctxOf(req) {
+	const { actorId: userId, organizationId } = scopeFirstCtx(req, { orgHeader: false });
+	return {
+		...userId !== void 0 ? { userId } : {},
+		...organizationId !== void 0 ? { organizationId } : {}
+	};
+}
+/**
+* Parse a command body against a STRICT schema, or 400 with the reason.
+*
+* Replaces per-route `typeof` checks followed by a cast. Those validated the
+* two or three fields someone remembered and passed everything else through
+* untouched — so an invalid `hashStrategy`, a negative dimension, a malformed
+* hash or an unknown key reached kernel code, and Zod's default STRIP would
+* have quietly dropped the unknown one rather than refusing it. For an upload
+* command, dropping a key does not fail; it executes a different instruction
+* than the caller wrote.
+*/
+function parseBody(reply, schema, body) {
+	const result = schema.safeParse(body ?? {});
+	if (!result.success) {
+		badRequest(reply, (result.error?.issues ?? []).slice(0, 4).map((i) => `${i.path.join(".") || "(body)"}: ${i.message}`).join("; ") || "invalid request body");
+		return;
+	}
+	return result.data;
+}
+function badRequest(reply, message) {
+	return reply.code(400).send({
+		code: "media.invalid_input",
+		message,
+		status: 400
+	});
+}
+const DEFAULT_MULTIPART_THRESHOLD = 104857600;
+function createMediaResource(deps) {
+	const { permissions } = deps;
+	const media = deps.engine.repositories.media;
+	const threshold = deps.multipartThresholdBytes ?? DEFAULT_MULTIPART_THRESHOLD;
+	const transformPolicy = deps.transformPolicy ?? buildTransformPolicy();
+	const assetTransform = createAssetTransform({ media: deps.engine });
+	const serveAsset = async (req, reply) => {
+		const params = req.params;
+		const query = Object.fromEntries(Object.entries(req.query).filter((entry) => typeof entry[1] === "string"));
+		const result = await assetTransform.handle({
+			fileId: params.id,
+			...params.variant ? { variant: params.variant } : {},
+			params: req.query,
+			query,
+			...typeof req.headers.accept === "string" ? { accept: req.headers.accept } : {},
+			...typeof req.headers.range === "string" ? { range: req.headers.range } : {},
+			principal: req.user ?? req.scope
+		});
+		reply.code(result.status).headers(result.headers);
+		return reply.send(result.stream);
+	};
+	return defineResource(mergeResourceConfig({
+		name: "media",
+		displayName: "Media",
+		tag: "Media",
+		prefix: deps.prefix ?? "/media",
+		audit: true,
+		tenantField: resolveSpineTenant(deps.engine.config.tenant).resourceTenantField,
+		adapter: createMongooseAdapter({
+			model: deps.engine.models.Media,
+			repository: media
+		}),
+		queryParser: new QueryParser({
+			maxLimit: 100,
+			searchMode: "regex",
+			searchFields: [
+				"filename",
+				"title",
+				"tags"
+			],
+			allowedFilterFields: [
+				"status",
+				"mimeType",
+				"folder",
+				"visibility",
+				"hash",
+				"filename",
+				"tags"
+			],
+			allowedSortFields: [
+				"createdAt",
+				"size",
+				"filename"
+			]
+		}),
+		disabledRoutes: ["create", "update"],
+		permissions: {
+			list: permissions.view,
+			get: permissions.view,
+			delete: permissions.manage
+		},
+		actions: { "signed-url": {
+			handler: async (id, data, req) => {
+				const opts = data ?? {};
+				return { url: await media.getSignedAssetUrl(id, {
+					...opts.variant !== void 0 ? { variant: opts.variant } : {},
+					...opts.expiresIn !== void 0 ? { expiresIn: opts.expiresIn } : {}
+				}, ctxOf(req)) };
+			},
+			permissions: permissions.view
+		} },
+		routes: [
+			{
+				method: "GET",
+				path: "/content/:id",
+				summary: "Serve public media or private media bearing a valid signed URL",
+				permissions: allowPublic(),
+				rawHandler: serveAsset
+			},
+			{
+				method: "GET",
+				path: "/content/:id/:variant",
+				summary: "Serve a named media variant bearing a valid signed URL",
+				permissions: allowPublic(),
+				rawHandler: serveAsset
+			},
+			{
+				method: "POST",
+				path: "/start-write",
+				summary: "Begin a direct-to-storage upload: dedup short-circuit, presigned PUT, or multipart/resumable session",
+				permissions: permissions.upload,
+				rawHandler: async (req, reply) => {
+					const body = parseBody(reply, startWriteSchema, req.body);
+					if (!body) return;
+					const ctx = ctxOf(req);
+					if (typeof body.sha256 === "string" && body.sha256.length > 0) {
+						const hit = await media.existsByHash(body.sha256, ctx, { ...typeof body.size === "number" ? { expectedSize: body.size } : {} });
+						if (hit.exists && hit.media) {
+							const result = {
+								kind: "dedup",
+								media: hit.media
+							};
+							return reply.code(200).send(result);
+						}
+					}
+					if (body.multipart === true || body.partCount !== void 0 || typeof body.size === "number" && body.size >= threshold) {
+						const input = {
+							filename: body.filename,
+							contentType: body.contentType,
+							...body.folder !== void 0 ? { folder: body.folder } : {},
+							...body.partCount !== void 0 ? { partCount: body.partCount } : {},
+							...body.expiresIn !== void 0 ? { expiresIn: body.expiresIn } : {}
+						};
+						const session = await media.initiateMultipartUpload(input, ctx);
+						const result = {
+							kind: session.type,
+							session
+						};
+						return reply.code(201).send(result);
+					}
+					const upload = await media.getSignedUploadUrl(body.filename, body.contentType, {
+						...body.folder !== void 0 ? { folder: body.folder } : {},
+						...body.size !== void 0 ? { size: body.size } : {},
+						...body.expiresIn !== void 0 ? { expiresIn: body.expiresIn } : {}
+					}, ctx);
+					/**
+					* Presign the sizes the client made from the SAME decode.
+					*
+					* Requested in this call rather than a second round trip: the
+					* transform policy already told the client which sizes to make,
+					* and it made them before it had anywhere to put them.
+					*
+					* A failure here FAILS the whole start — not a partial success.
+					* Handing back a primary URL with no derivative URLs would look
+					* identical to "this policy asks for none", and the client would
+					* upload one file believing it had done the job.
+					*/
+					const derivativeUploads = body.derivatives && body.derivatives.length > 0 ? await media.signDerivativeUploads({
+						primaryKey: upload.key,
+						derivatives: body.derivatives,
+						...body.expiresIn !== void 0 ? { expiresIn: body.expiresIn } : {}
+					}, ctx) : void 0;
+					const result = {
+						kind: "presigned",
+						upload,
+						...derivativeUploads?.length ? { derivativeUploads } : {}
+					};
+					return reply.code(201).send(result);
+				}
+			},
+			{
+				method: "GET",
+				path: "/transform-policy",
+				summary: "What a client should do to an upload before sending it (host-owned)",
+				/**
+				* Readable by anyone who can VIEW media, not just uploaders: the
+				* policy is a description of the deployment's own rules, and a
+				* client resolves it before it knows whether it will upload.
+				*/
+				permissions: permissions.view,
+				rawHandler: async (_req, reply) => {
+					/**
+					* Cacheable, and deliberately so — this document changes on
+					* deploy, not per request, and every upload consults it. It is
+					* versioned, so a client that does not understand the version
+					* declines to transform rather than guessing.
+					*/
+					reply.header("cache-control", "public, max-age=300");
+					return reply.code(200).send(transformPolicy);
+				}
+			},
+			{
+				method: "POST",
+				path: "/complete-write",
+				summary: "Confirm a presigned upload — storage-verified (exists/stat/MIME), stores client display hints",
+				permissions: permissions.upload,
+				rawHandler: async (req, reply) => {
+					const body = parseBody(reply, confirmUploadSchema, req.body);
+					if (!body) return;
+					const doc = await media.confirmUpload(body, ctxOf(req));
+					return reply.code(201).send(doc);
+				}
+			},
+			{
+				method: "POST",
+				path: "/sign-parts",
+				summary: "Sign multipart upload part URLs on demand",
+				permissions: permissions.upload,
+				rawHandler: async (req, reply) => {
+					const body = req.body ?? {};
+					if (typeof body.key !== "string" || typeof body.uploadId !== "string") return badRequest(reply, "`key` and `uploadId` are required");
+					if (!Array.isArray(body.partNumbers) || body.partNumbers.length === 0) return badRequest(reply, "`partNumbers` must be a non-empty array");
+					const parts = await media.signUploadParts(body.key, body.uploadId, body.partNumbers, body.expiresIn);
+					return reply.code(200).send({ parts });
+				}
+			},
+			{
+				method: "POST",
+				path: "/complete-multipart",
+				summary: "Assemble uploaded parts and register the asset (storage-verified)",
+				permissions: permissions.upload,
+				rawHandler: async (req, reply) => {
+					const body = req.body ?? {};
+					if (typeof body.key !== "string" || typeof body.uploadId !== "string") return badRequest(reply, "`key` and `uploadId` are required");
+					if (!Array.isArray(body.parts) || body.parts.length === 0) return badRequest(reply, "`parts` must be a non-empty array");
+					if (typeof body.filename !== "string" || typeof body.mimeType !== "string") return badRequest(reply, "`filename` and `mimeType` are required");
+					const doc = await media.completeMultipartUpload(body, ctxOf(req));
+					return reply.code(201).send(doc);
+				}
+			},
+			{
+				method: "POST",
+				path: "/abort-multipart",
+				summary: "Abort an in-flight multipart upload (tenant-guarded)",
+				permissions: permissions.upload,
+				rawHandler: async (req, reply) => {
+					const body = req.body ?? {};
+					if (typeof body.key !== "string" || typeof body.uploadId !== "string") return badRequest(reply, "`key` and `uploadId` are required");
+					await media.abortMultipartUpload(body.key, body.uploadId, ctxOf(req));
+					return reply.code(204).send();
+				}
+			}
+		]
+	}, deps.seams));
+}
+function createMediaModule(deps) {
+	const supplied = deps.source?.kind === "external" ? deps.source.engine : deps.engine;
+	const maintenance = deps.maintenance;
+	const { module } = defineEngineModule({
+		name: "media",
+		...deps.dependsOn ? { dependsOn: [...deps.dependsOn] } : {},
+		...supplied ? { supplied } : {},
+		...deps.slot ? { slot: deps.slot } : {},
+		boot: async () => {
+			if (deps.source?.kind === "blueprint") {
+				const rt = typeof deps.source.runtime === "function" ? await deps.source.runtime() : deps.source.runtime;
+				return await deps.source.blueprint.bind(deps.source.connection, rt);
+			}
+			throw new Error("createMediaModule: supply a blueprint source or a live engine");
+		},
+		close: (engine) => engine.close(),
+		resources: (engine) => {
+			const { seams: seamsInput, source: _source, slot: _slot, ...resourceDeps } = deps;
+			const seams = typeof seamsInput === "function" ? seamsInput(engine) : seamsInput;
+			return [createMediaResource({
+				...resourceDeps,
+				engine,
+				...seams ? { seams } : {}
+			})];
+		},
+		...deps.afterResources ? { afterResources: deps.afterResources } : {},
+		extend: (get) => maintenance === false ? {} : { scheduledJobs: () => mediaMaintenanceSchedules(get(), maintenance) }
+	});
+	return module;
+}
+/**
+* Maintenance schedule definitions for arc's `schedulesPlugin` — drop into
+* the host's schedule table (with a `lock` for multi-replica leader safety):
+*
+* ```ts
+* await app.register(schedulesPlugin, {
+*   lock: createMongoLockAdapter({ connection }),
+*   schedules: [...mediaMaintenanceSchedules(engine), ...otherJobs],
+* });
+* ```
+*
+* ## What these sweeps do NOT cover — read before relying on them
+*
+* An abandoned TWO-PHASE upload leaves **no database row at all**. `start-write`
+* only signs a URL; the record is created by `complete-write`. So a client that
+* presigns and then never confirms leaves an object in the bucket that nothing
+* here can see, let alone reclaim.
+*
+* This docblock previously said those uploads "leave `pending` docs that these
+* sweeps reclaim", and treated bucket lifecycle as belt-and-braces. That was
+* backwards, and it is the dangerous direction to be wrong in: a deployment
+* reading it would skip the lifecycle rule and accumulate unreferenced objects
+* it is still paying to store, with a maintenance job reporting success the
+* whole time.
+*
+* **A bucket lifecycle expiry on incomplete/unreferenced keys is REQUIRED, not
+* optional.** See media-kit's README ("Orphaned storage objects").
+*
+* What these sweeps genuinely reclaim: rows that DO exist and are stuck —
+* `pending` records from the buffered upload path, soft-deleted docs past their
+* retention window, and expired assets.
+*/
+function mediaMaintenanceSchedules(engine, options = {}) {
+	const media = engine.repositories.media;
+	return [
+		{
+			name: "media.purge.stale-pending",
+			every: options.stalePendingEvery ?? 36e5,
+			leaseMs: Math.floor((options.stalePendingEvery ?? 36e5) * .9),
+			jitterMs: 6e4,
+			handler: async () => {
+				await media.purgeStalePending();
+			}
+		},
+		{
+			name: "media.purge.deleted",
+			every: options.purgeDeletedEvery ?? 864e5,
+			leaseMs: Math.floor((options.purgeDeletedEvery ?? 864e5) * .9),
+			jitterMs: 3e5,
+			handler: async () => {
+				await media.purgeDeleted();
+			}
+		},
+		{
+			name: "media.purge.expired",
+			every: options.purgeExpiredEvery ?? 36e5,
+			leaseMs: Math.floor((options.purgeExpiredEvery ?? 36e5) * .9),
+			jitterMs: 6e4,
+			handler: async () => {
+				await media.purgeExpired();
+			}
+		}
+	];
+}
+//#endregion
+export { createMediaEngineSlot, createMediaModule, createMediaResource, createMediaRolePermissions, mediaCleanupSteps, mediaMaintenanceSchedules };

package/dist/providers/media-provider.config.d.mts

@@ -0,0 +1,66 @@
+import { StorageDriver } from "@classytic/media-kit";
+//#region src/providers/media-provider.config.d.ts
+type StorageDriverLike = import('@classytic/media-kit').StorageDriver;
+interface S3ProviderConfig {
+  kind: 's3';
+  bucket: string;
+  region: string;
+  accessKeyId: string;
+  secretAccessKey: string;
+  publicUrl?: string;
+  acl?: string;
+}
+interface GcsProviderConfig {
+  kind: 'gcs';
+  bucket: string;
+  projectId?: string;
+  keyFilename?: string;
+  credentials?: Record<string, unknown>;
+  publicUrl?: string;
+}
+interface CloudflareImagesProviderConfig {
+  kind: 'cloudflare-images';
+  accountId: string;
+  apiToken: string;
+  deliveryUrl?: string;
+}
+interface CloudinaryProviderConfig {
+  kind: 'cloudinary';
+  cloudName: string;
+  apiKey: string;
+  apiSecret: string;
+}
+interface ImageKitProviderConfig {
+  kind: 'imagekit';
+  publicKey: string;
+  privateKey: string;
+  urlEndpoint: string;
+}
+interface ImgbbProviderConfig {
+  kind: 'imgbb';
+  apiKey: string;
+}
+interface LocalProviderConfig {
+  kind: 'local';
+  basePath: string;
+  publicUrl?: string;
+}
+/** No credentials, nothing persisted. Dev and tests only — never a production fallback. */
+interface MemoryProviderConfig {
+  kind: 'memory';
+}
+type MediaProviderConfig = S3ProviderConfig | GcsProviderConfig | CloudflareImagesProviderConfig | CloudinaryProviderConfig | ImageKitProviderConfig | ImgbbProviderConfig | LocalProviderConfig | MemoryProviderConfig;
+interface ResolveMediaProviderOptions {
+  /**
+   * Driver to use when `config` is absent or incomplete.
+   *
+   * EXPLICIT opt-in. Without it an incomplete config throws, because a silent fallback
+   * means uploads that appear to succeed and vanish.
+   */
+  fallback?: () => Promise<StorageDriverLike> | StorageDriverLike;
+}
+/** Which required fields are missing. Exported so a host can pre-flight its own config. */
+declare function missingProviderFields(config: MediaProviderConfig): string[];
+declare function resolveMediaProvider(config: MediaProviderConfig | undefined, options?: ResolveMediaProviderOptions): Promise<StorageDriverLike>;
+//#endregion
+export { CloudflareImagesProviderConfig, CloudinaryProviderConfig, GcsProviderConfig, ImageKitProviderConfig, ImgbbProviderConfig, LocalProviderConfig, MediaProviderConfig, MemoryProviderConfig, ResolveMediaProviderOptions, S3ProviderConfig, type StorageDriver, missingProviderFields, resolveMediaProvider };