appos 0.3.5-0 → 0.3.7-0

package/dist/exports/api/storage.mjs

@@ -1,833 +0,0 @@
-import { orm_exports } from "./orm.mjs";
-import { extractBlobMetadata } from "./workflows/extract-blob-metadata.mjs";
-import { generateImageVariant } from "./workflows/generate-image-variant.mjs";
-import { generatePreview } from "./workflows/generate-preview.mjs";
-import { purgeAttachment } from "./workflows/purge-attachment.mjs";
-import { join } from "node:path";
-import { mkdtemp, rm, writeFile } from "node:fs/promises";
-import { createHash, createHmac, randomBytes, timingSafeEqual } from "node:crypto";
-import { tmpdir } from "node:os";
-import { DriveManager } from "flydrive";
-import { FSDriver } from "flydrive/drivers/fs";
-import { S3Driver } from "flydrive/drivers/s3";
-
-//#region src/api/storage.ts
-/**
-* Creates an S3 disk configuration with common boilerplate handled.
-*
-* Algorithm:
-* 1. Build base config with bucket, region, visibility
-* 2. If endpoint provided, add endpoint + forcePathStyle
-* 3. If credentials provided, add credentials object
-*
-* @example
-* ```typescript
-* defineS3Disk({
-*   bucket: "my-bucket",
-*   region: "us-east-1",
-*   endpoint: "http://localhost:4566",
-*   credentials: {
-*     accessKeyId: "test",
-*     secretAccessKey: "test",
-*   },
-* })
-* ```
-*/
-function defineS3Disk(opts) {
-	return {
-		bucket: opts.bucket,
-		region: opts.region,
-		visibility: opts.visibility ?? "private",
-		...opts.endpoint && {
-			endpoint: opts.endpoint,
-			forcePathStyle: true
-		},
-		...opts.credentials && { credentials: opts.credentials }
-	};
-}
-/**
-* Calculate checksum for a buffer.
-*/
-function calculateChecksum(buffer) {
-	return createHash("md5").update(buffer).digest("hex");
-}
-/**
-* Generate deterministic variant key.
-*/
-function generateVariantKey(blobId, transformations) {
-	return `variants/${blobId}/${createHash("sha256").update(JSON.stringify({
-		blobId,
-		transformations
-	})).digest("hex")}`;
-}
-/**
-* Generate a secure key for blob storage.
-*/
-function generateKey(prefix) {
-	const key = `${Date.now()}-${randomBytes(16).toString("hex")}`;
-	return prefix ? `${prefix}/${key}` : key;
-}
-/**
-* Define storage service with FlyDrive.
-* @template TDisks - Record of disk configurations keyed by disk name
-* @template TDb - Database type for table name extraction
-* @template TAttachments - Mapping of table names to valid attachment names
-*/
-function defineStorage(opts) {
-	if (!opts.default) throw new Error("Storage: 'default' disk must be specified");
-	if (!opts.disks || Object.keys(opts.disks).length === 0) throw new Error("Storage: At least one disk must be configured");
-	const defaultDisk = opts.default;
-	const operationalServices = {};
-	const signedUrlServices = {};
-	for (const [name, diskConfig] of Object.entries(opts.disks)) {
-		const config = diskConfig;
-		if ("driver" in config) {
-			if (config.driver === "fs") {
-				const fsDriver = () => new FSDriver(config);
-				operationalServices[name] = fsDriver;
-				signedUrlServices[name] = fsDriver;
-			} else if (config.driver === "s3") {
-				operationalServices[name] = () => new S3Driver(config);
-				if (opts.publicEndpoint) signedUrlServices[name] = () => new S3Driver({
-					...config,
-					endpoint: opts.publicEndpoint
-				});
-				else signedUrlServices[name] = () => new S3Driver(config);
-			}
-		} else if ("location" in config) {
-			const fsDriver = () => new FSDriver(config);
-			operationalServices[name] = fsDriver;
-			signedUrlServices[name] = fsDriver;
-		} else if ("bucket" in config) {
-			operationalServices[name] = () => new S3Driver(config);
-			if (opts.publicEndpoint) {
-				const signedUrlConfig = {
-					...config,
-					endpoint: opts.publicEndpoint
-				};
-				signedUrlServices[name] = () => new S3Driver(signedUrlConfig);
-			} else signedUrlServices[name] = () => new S3Driver(config);
-		}
-	}
-	const operationalDrive = new DriveManager({
-		default: defaultDisk,
-		services: operationalServices
-	});
-	const signedUrlDrive = new DriveManager({
-		default: defaultDisk,
-		services: signedUrlServices
-	});
-	return new StorageService(operationalDrive, opts.database, defaultDisk, signedUrlDrive, opts.purgeCron, opts.secret);
-}
-/**
-* Storage service for blob operations.
-*
-* This service uses a dual-drive architecture when configured:
-* - `drive`: For actual file operations (upload, delete, read) using internal endpoints
-* - `signedUrlDrive`: For generating browser-accessible signed URLs with public endpoints
-*
-* This allows containers to use fast internal network for operations while
-* generating URLs that work in end-user browsers.
-*
-* @template TDiskNames - Union of disk names (e.g., "private" | "public")
-* @template TTableNames - Union of table names for type-safe attachment methods
-* @template TAttachments - Mapping of table names to valid attachment names
-*/
-var StorageService = class {
-	/**
-	* The drive manager for file operations.
-	*/
-	drive;
-	/**
-	* The database instance with storage schema and relations.
-	*/
-	db;
-	/**
-	* The default disk name.
-	*/
-	defaultDisk;
-	/**
-	* Cron expression for unattached blob purge schedule.
-	*
-	* @default "0 0 * * *"
-	*/
-	purgeCron;
-	/**
-	* Secret key for signing blob IDs.
-	*/
-	secret;
-	/**
-	* Drive manager for generating signed URLs (public endpoint).
-	*/
-	signedUrlDrive;
-	constructor(drive, db, defaultDisk, signedUrlDrive, purgeCron, secret) {
-		this.drive = drive;
-		this.db = db;
-		this.defaultDisk = defaultDisk;
-		this.signedUrlDrive = signedUrlDrive;
-		this.purgeCron = purgeCron;
-		this.secret = secret;
-	}
-	/**
-	* Create a blob record and upload file.
-	*/
-	async createBlob(file, options) {
-		const key = generateKey(options.prefix);
-		const buffer = Buffer.from(file);
-		const checksum = calculateChecksum(buffer);
-		const serviceName = options.serviceName || this.defaultDisk;
-		await (options.serviceName ? this.drive.use(options.serviceName) : this.drive.use()).put(key, buffer, { contentType: options.contentType });
-		const [blob] = await this.db.insert(this.db._.fullSchema.storageBlobs).values({
-			key,
-			filename: options.filename,
-			contentType: options.contentType,
-			metadata: options.metadata,
-			serviceName,
-			byteSize: buffer.byteLength,
-			checksum
-		}).returning();
-		return blob;
-	}
-	/**
-	* Get blob by ID.
-	*/
-	async getBlob(id) {
-		const [blob] = await this.db.select().from(this.db._.fullSchema.storageBlobs).where((0, orm_exports.eq)(this.db._.fullSchema.storageBlobs.id, id));
-		return blob || null;
-	}
-	/**
-	* Download blob content.
-	*/
-	async downloadBlob(id) {
-		const blob = await this.getBlob(id);
-		if (!blob) return null;
-		const content = await this.drive.use(blob.serviceName).getBytes(blob.key);
-		return Buffer.from(content);
-	}
-	/**
-	* Delete blob and its content.
-	*/
-	async deleteBlob(id) {
-		const blob = await this.getBlob(id);
-		if (!blob) return false;
-		await this.drive.use(blob.serviceName).delete(blob.key);
-		await this.db.delete(this.db._.fullSchema.storageBlobs).where((0, orm_exports.eq)(this.db._.fullSchema.storageBlobs.id, id));
-		return true;
-	}
-	/**
-	* Get signed URL for blob. If blob is on public service, returns permanent
-	* URL instead.
-	*/
-	async getSignedUrl(id, options = {}) {
-		const blob = await this.getBlob(id);
-		if (!blob) return null;
-		if (blob.serviceName === "public") return this.getPublicUrl(id);
-		const disk = this.signedUrlDrive.use(blob.serviceName);
-		try {
-			const signedUrlOptions = { expiresIn: options.expiresIn || 3600 };
-			if (options.disposition) {
-				const filename = options.filename || blob.filename;
-				signedUrlOptions.contentDisposition = options.disposition === "attachment" ? `attachment; filename="${filename}"` : `inline; filename="${filename}"`;
-			}
-			return await disk.getSignedUrl(blob.key, signedUrlOptions);
-		} catch (error) {
-			const baseUrl = `/storage/${blob.id}`;
-			if (options.disposition) return `${baseUrl}?${new URLSearchParams({
-				disposition: options.disposition,
-				...options.filename && { filename: options.filename }
-			}).toString()}`;
-			return baseUrl;
-		}
-	}
-	/**
-	* Get permanent public URL (no expiration).
-	* Works for blobs on public storage service.
-	*/
-	async getPublicUrl(id) {
-		const blob = await this.getBlob(id);
-		if (!blob) return null;
-		const disk = this.drive.use(blob.serviceName);
-		if (blob.serviceName === "public") try {
-			if ("getUrl" in disk && typeof disk.getUrl === "function") return await disk.getUrl(blob.key);
-		} catch {}
-		return `/storage/${blob.id}`;
-	}
-	/**
-	* Create attachment between a record and blob.
-	*
-	* @param recordType - The table name (e.g., 'users')
-	* @param recordId - The record ID
-	* @param blobId - The blob ID to attach
-	* @param name - The attachment name (e.g., 'avatar')
-	* @param replaceExisting - If true, replaces existing attachment with same name (for one-to-one)
-	*/
-	async createAttachment(recordType, recordId, blobId, name, replaceExisting = false) {
-		if (replaceExisting) {
-			const lockKey = `${recordType}:${recordId}:${name}`;
-			const lockId = Array.from(lockKey).reduce((hash, char) => (hash << 5) - hash + char.charCodeAt(0) | 0, 0);
-			return await this.db.transaction(async (tx) => {
-				await tx.execute(orm_exports.sql`SELECT pg_advisory_xact_lock(${lockId})`);
-				await tx.delete(this.db._.fullSchema.storageAttachments).where((0, orm_exports.and)((0, orm_exports.eq)(this.db._.fullSchema.storageAttachments.recordType, recordType), (0, orm_exports.eq)(this.db._.fullSchema.storageAttachments.recordId, recordId), (0, orm_exports.eq)(this.db._.fullSchema.storageAttachments.name, name)));
-				const [attachment$1] = await tx.insert(this.db._.fullSchema.storageAttachments).values({
-					recordType,
-					recordId,
-					blobId,
-					name
-				}).returning();
-				return attachment$1;
-			});
-		}
-		const [attachment] = await this.db.insert(this.db._.fullSchema.storageAttachments).values({
-			recordType,
-			recordId,
-			blobId,
-			name
-		}).returning();
-		return attachment;
-	}
-	/**
-	* Get attachments for a record with their associated blobs.
-	*/
-	async getAttachments(recordType, recordId, name) {
-		return this.db.query.storageAttachments.findMany({
-			where: {
-				recordType,
-				recordId,
-				...name && { name }
-			},
-			with: { blob: true }
-		});
-	}
-	/**
-	* Get attachments by their IDs with associated blobs.
-	*
-	* @param attachmentIds - Array of attachment IDs to fetch.
-	*/
-	async getAttachmentsByIds(attachmentIds) {
-		if (attachmentIds.length === 0) return [];
-		return this.db.query.storageAttachments.findMany({
-			where: { id: { in: attachmentIds } },
-			with: { blob: true }
-		});
-	}
-	/**
-	* Delete a single attachment by ID.
-	*/
-	async deleteAttachment(attachmentId) {
-		return ((await this.db.delete(this.db._.fullSchema.storageAttachments).where((0, orm_exports.eq)(this.db._.fullSchema.storageAttachments.id, attachmentId))).rowCount ?? 0) > 0;
-	}
-	/**
-	* Delete attachments for a record (without deleting the blobs).
-	*/
-	async deleteAttachments(recordType, recordId, name) {
-		const whereClause = name ? (0, orm_exports.and)((0, orm_exports.eq)(this.db._.fullSchema.storageAttachments.recordType, recordType), (0, orm_exports.eq)(this.db._.fullSchema.storageAttachments.recordId, recordId), (0, orm_exports.eq)(this.db._.fullSchema.storageAttachments.name, name)) : (0, orm_exports.and)((0, orm_exports.eq)(this.db._.fullSchema.storageAttachments.recordType, recordType), (0, orm_exports.eq)(this.db._.fullSchema.storageAttachments.recordId, recordId));
-		return (await this.db.delete(this.db._.fullSchema.storageAttachments).where(whereClause)).rowCount ?? 0;
-	}
-	/**
-	* Get direct upload credentials (for S3). Also creates a pending blob record
-	* that will be finalized after upload.
-	*/
-	async getDirectUploadUrl(options) {
-		const serviceName = options.serviceName || this.defaultDisk;
-		const disk = this.drive.use(serviceName);
-		try {
-			const key = generateKey();
-			if ("putSignedUrl" in disk) {
-				const uploadUrl = await disk.putSignedUrl(key, {
-					expiresIn: options.expiresIn || 3600,
-					contentType: options.contentType
-				});
-				const [blob] = await this.db.insert(this.db._.fullSchema.storageBlobs).values({
-					key,
-					filename: options.filename,
-					contentType: options.contentType,
-					metadata: {
-						...options.metadata,
-						pending: true
-					},
-					serviceName,
-					byteSize: 0,
-					checksum: ""
-				}).returning();
-				return {
-					url: uploadUrl,
-					key,
-					blobId: blob.id,
-					headers: { "Content-Type": options.contentType || "application/octet-stream" }
-				};
-			}
-		} catch {}
-		return null;
-	}
-	/**
-	* Finalize a direct upload by updating blob metadata. Call this after the
-	* client has uploaded to S3.
-	*/
-	async finalizeDirectUpload(blobId, actualSize) {
-		const blob = await this.getBlob(blobId);
-		if (!blob) throw new Error(`Blob ${blobId} not found`);
-		const newMetadata = blob.metadata && typeof blob.metadata === "object" ? { ...blob.metadata } : {};
-		delete newMetadata.pending;
-		await this.db.update(this.db._.fullSchema.storageBlobs).set({
-			byteSize: actualSize,
-			metadata: newMetadata
-		}).where((0, orm_exports.eq)(this.db._.fullSchema.storageBlobs.id, blobId));
-	}
-	/**
-	* Update blob metadata (for automatic extraction).
-	*/
-	async updateBlobMetadata(blobId, metadata) {
-		const blob = await this.getBlob(blobId);
-		if (!blob) throw new Error(`Blob ${blobId} not found`);
-		const newMetadata = {
-			...blob.metadata && typeof blob.metadata === "object" ? blob.metadata : {},
-			...metadata
-		};
-		await this.db.update(this.db._.fullSchema.storageBlobs).set({ metadata: newMetadata }).where((0, orm_exports.eq)(this.db._.fullSchema.storageBlobs.id, blobId));
-	}
-	/**
-	* Get existing variant or return null.
-	*/
-	async getVariant(blobId, transformations) {
-		const variationDigest = createHash("sha256").update(JSON.stringify(transformations)).digest("hex");
-		const [variantRecord] = await this.db.query.storageVariantRecords.findMany({
-			where: {
-				blobId,
-				variationDigest
-			},
-			with: { blob: true },
-			limit: 1
-		});
-		return variantRecord?.blob || null;
-	}
-	/**
-	* Create variant blob and record.
-	*/
-	async createVariant(blobId, transformations, variantBuffer) {
-		const blob = await this.getBlob(blobId);
-		if (!blob) throw new Error(`Blob ${blobId} not found`);
-		const key = generateVariantKey(blobId, transformations);
-		const checksum = calculateChecksum(variantBuffer);
-		await this.drive.use(blob.serviceName).put(key, variantBuffer, { contentType: blob.contentType || "application/octet-stream" });
-		const [variantBlob] = await this.db.insert(this.db._.fullSchema.storageBlobs).values({
-			key,
-			filename: blob.filename,
-			contentType: blob.contentType,
-			metadata: {
-				sourceBlob: blobId,
-				transformations
-			},
-			serviceName: blob.serviceName,
-			byteSize: variantBuffer.byteLength,
-			checksum
-		}).returning();
-		const variationDigest = createHash("sha256").update(JSON.stringify(transformations)).digest("hex");
-		await this.db.insert(this.db._.fullSchema.storageVariantRecords).values({
-			blobId,
-			variationDigest,
-			id: variantBlob.id
-		});
-		return variantBlob;
-	}
-	/**
-	* Get blobs that have no attachments (orphaned). Useful for cleanup jobs.
-	*/
-	async getUnattachedBlobs(options = {}) {
-		const olderThan = options.olderThan || (/* @__PURE__ */ new Date(Date.now() - 2880 * 60 * 1e3)).toISOString();
-		const limit = options.limit || 1e3;
-		return (await this.db.select({ blob: this.db._.fullSchema.storageBlobs }).from(this.db._.fullSchema.storageBlobs).leftJoin(this.db._.fullSchema.storageAttachments, (0, orm_exports.eq)(this.db._.fullSchema.storageBlobs.id, this.db._.fullSchema.storageAttachments.blobId)).where((0, orm_exports.and)((0, orm_exports.isNull)(this.db._.fullSchema.storageAttachments.id), (0, orm_exports.lt)(this.db._.fullSchema.storageBlobs.createdAt, olderThan))).limit(limit)).map((row) => row.blob);
-	}
-	/**
-	* Get pending blobs that were never finalized (stuck direct uploads).
-	*/
-	async getPendingBlobs(olderThan = (/* @__PURE__ */ new Date(Date.now() - 1440 * 60 * 1e3)).toISOString()) {
-		return await this.db.select().from(this.db._.fullSchema.storageBlobs).where((0, orm_exports.and)((0, orm_exports.lt)(this.db._.fullSchema.storageBlobs.createdAt, olderThan), orm_exports.sql`${this.db._.fullSchema.storageBlobs.metadata}->>'pending' = 'true'`));
-	}
-	/**
-	* Purge unattached blobs.
-	*/
-	async purgeUnattached(olderThan) {
-		const blobs = await this.getUnattachedBlobs({ olderThan });
-		let purgedCount = 0;
-		for (const blob of blobs) try {
-			await this.deleteBlob(blob.id);
-			purgedCount++;
-		} catch (error) {
-			console.error(`Failed to purge blob ${blob.id}:`, error);
-		}
-		return purgedCount;
-	}
-	/**
-	* Create a signed, tamper-proof reference to a blob.
-	* Use findSigned() to resolve back to blob.
-	*
-	* Algorithm:
-	* 1. Create payload with blobId and expiration timestamp
-	* 2. JSON stringify and base64url encode the payload
-	* 3. Create HMAC-SHA256 signature of the encoded payload
-	* 4. Return payload.signature format
-	*/
-	signedId(blobId, expiresIn = 3600) {
-		if (!this.secret) throw new Error("Storage secret not configured");
-		const payload = {
-			blobId,
-			exp: Math.floor(Date.now() / 1e3) + expiresIn
-		};
-		const data = JSON.stringify(payload);
-		const signature = createHmac("sha256", this.secret).update(data).digest("base64url");
-		return `${Buffer.from(data).toString("base64url")}.${signature}`;
-	}
-	/**
-	* Find blob by signed ID. Returns null if invalid or expired.
-	* Uses constant-time comparison to prevent timing attacks.
-	*
-	* Algorithm:
-	* 1. Split signed ID into payload and signature
-	* 2. Decode and recompute expected signature
-	* 3. Use timingSafeEqual for constant-time comparison
-	* 4. Check expiration timestamp
-	* 5. Return blob if valid, null otherwise
-	*/
-	async findSigned(signedId) {
-		if (!this.secret) throw new Error("Storage secret not configured");
-		try {
-			const [encodedPayload, signature] = signedId.split(".");
-			if (!encodedPayload || !signature) return null;
-			const data = Buffer.from(encodedPayload, "base64url").toString();
-			const expectedSignature = createHmac("sha256", this.secret).update(data).digest("base64url");
-			const sigBuffer = Buffer.from(signature, "base64url");
-			const expectedBuffer = Buffer.from(expectedSignature, "base64url");
-			if (sigBuffer.length !== expectedBuffer.length || !timingSafeEqual(sigBuffer, expectedBuffer)) return null;
-			const payload = JSON.parse(data);
-			if (payload.exp && payload.exp < Math.floor(Date.now() / 1e3)) return null;
-			return this.getBlob(payload.blobId);
-		} catch {
-			return null;
-		}
-	}
-	/**
-	* Get a single attachment handle (one-to-one relationship).
-	* Similar to Rails' `has_one_attached :avatar`.
-	*
-	* Algorithm:
-	* Returns an object with methods to manage a single attachment:
-	* - attach(): Replace existing attachment with new blob
-	* - get(): Get attached blob or null
-	* - url(): Get signed URL
-	* - variant(): Get/generate image variant
-	* - purge(): Delete attachment and blob
-	*
-	* @template TTable - The table name (must be in TTableNames)
-	*/
-	one(recordType, recordId, name) {
-		const storage = this;
-		const attachmentName = name;
-		return {
-			async attach(blobId) {
-				if (!await storage.getBlob(blobId)) throw new Error(`Blob ${blobId} not found`);
-				const attachment = await storage.createAttachment(recordType, recordId, blobId, attachmentName, true);
-				await extractBlobMetadata.start({ blobId });
-				return attachment;
-			},
-			async get() {
-				return (await storage.getAttachments(recordType, recordId, attachmentName))[0]?.blob ?? null;
-			},
-			async attached() {
-				return await this.get() !== null;
-			},
-			async url(options) {
-				const blob = await this.get();
-				if (!blob) return null;
-				return storage.getSignedUrl(blob.id, options);
-			},
-			async publicUrl() {
-				const blob = await this.get();
-				if (!blob) return null;
-				return storage.getPublicUrl(blob.id);
-			},
-			async metadata() {
-				return (await this.get())?.metadata ?? null;
-			},
-			async analyzed() {
-				return (await this.metadata())?.analyzed === true;
-			},
-			async representable() {
-				const blob = await this.get();
-				if (!blob?.contentType) return false;
-				return [
-					"image/",
-					"video/",
-					"application/pdf"
-				].some((t) => blob.contentType?.startsWith(t));
-			},
-			async variant(transformations, expiresIn = 3600) {
-				const blob = await this.get();
-				if (!blob) return null;
-				const existing = await storage.getVariant(blob.id, transformations);
-				if (existing) return storage.getSignedUrl(existing.id, { expiresIn });
-				await generateImageVariant.start({
-					blobId: blob.id,
-					transformations
-				});
-				return null;
-			},
-			async preview(expiresIn = 3600, timeInSeconds = 1) {
-				const blob = await this.get();
-				if (!blob) return null;
-				const existing = await storage.getVariant(blob.id, { preview: true });
-				if (existing) return storage.getSignedUrl(existing.id, { expiresIn });
-				await generatePreview.start({
-					blobId: blob.id,
-					timeInSeconds
-				});
-				return null;
-			},
-			async detach() {
-				return await storage.deleteAttachments(recordType, recordId, attachmentName) > 0;
-			},
-			async purge() {
-				const results = await storage.getAttachments(recordType, recordId, attachmentName);
-				if (results.length === 0) return false;
-				const blob = results[0].blob;
-				if (!blob) return false;
-				await storage.deleteAttachments(recordType, recordId, attachmentName);
-				await storage.deleteBlob(blob.id);
-				return true;
-			},
-			async purgeLater() {
-				const results = await storage.getAttachments(recordType, recordId, attachmentName);
-				if (results.length === 0) return false;
-				await purgeAttachment.start({ attachmentIds: [results[0].id] });
-				return true;
-			},
-			async download() {
-				const blob = await this.get();
-				if (!blob) return null;
-				return storage.downloadBlob(blob.id);
-			},
-			async open(callback) {
-				const blob = await this.get();
-				if (!blob) return null;
-				const buffer = await storage.downloadBlob(blob.id);
-				if (!buffer) return null;
-				const tempDir = await mkdtemp(join(tmpdir(), "attachment-"));
-				const tempPath = join(tempDir, blob.filename);
-				try {
-					await writeFile(tempPath, buffer);
-					return await callback(tempPath);
-				} finally {
-					await rm(tempDir, {
-						recursive: true,
-						force: true
-					});
-				}
-			},
-			async representation(transformations, expiresIn = 3600) {
-				const blob = await this.get();
-				if (!blob) return null;
-				if (blob.contentType?.startsWith("image/")) return this.variant(transformations, expiresIn);
-				return this.preview(expiresIn);
-			},
-			async byteSize() {
-				return (await this.get())?.byteSize ?? null;
-			},
-			async contentType() {
-				return (await this.get())?.contentType ?? null;
-			},
-			async filename() {
-				return (await this.get())?.filename ?? null;
-			},
-			async signedId(expiresIn = 3600) {
-				const blob = await this.get();
-				if (!blob) return null;
-				return storage.signedId(blob.id, expiresIn);
-			}
-		};
-	}
-	/**
-	* Get a multiple attachment handle (one-to-many relationship).
-	* Similar to Rails' `has_many_attached :images`.
-	*
-	* Algorithm:
-	* Returns an object with methods to manage multiple attachments:
-	* - attach(): Add blobs (doesn't replace existing)
-	* - list(): Get all attached blobs
-	* - urls(): Get signed URLs for all
-	* - variants(): Get/generate variants for all
-	* - purge(): Delete all or specific attachment
-	*
-	* @template TTable - The table name (must be in TTableNames)
-	*/
-	many(recordType, recordId, name) {
-		const storage = this;
-		const attachmentName = name;
-		return {
-			async attach(blobIds) {
-				const ids = Array.isArray(blobIds) ? blobIds : [blobIds];
-				const blobs = await Promise.all(ids.map((id) => storage.getBlob(id)));
-				const missing = ids.filter((_, i) => !blobs[i]);
-				if (missing.length > 0) throw new Error(`Blobs not found: ${missing.join(", ")}`);
-				const attachments = await Promise.all(ids.map((id) => storage.createAttachment(recordType, recordId, id, attachmentName)));
-				await Promise.all(ids.map((id) => extractBlobMetadata.start({ blobId: id })));
-				return attachments;
-			},
-			async list() {
-				return (await storage.getAttachments(recordType, recordId, attachmentName)).map((r) => r.blob).filter((b) => b !== null);
-			},
-			async count() {
-				return (await this.list()).length;
-			},
-			async urls(options) {
-				const blobs = await this.list();
-				return (await Promise.all(blobs.map((b) => storage.getSignedUrl(b.id, options)))).filter((u) => u !== null);
-			},
-			async publicUrls() {
-				const blobs = await this.list();
-				return Promise.all(blobs.map((b) => storage.getPublicUrl(b.id)));
-			},
-			async metadata() {
-				return (await this.list()).map((b) => b.metadata ?? null);
-			},
-			async analyzed() {
-				return (await this.metadata()).map((m) => m?.analyzed === true);
-			},
-			async representable() {
-				return (await this.list()).map((b) => {
-					if (!b.contentType) return false;
-					return [
-						"image/",
-						"video/",
-						"application/pdf"
-					].some((t) => b.contentType?.startsWith(t));
-				});
-			},
-			async variants(transformations, expiresIn = 3600) {
-				const blobs = await this.list();
-				return Promise.all(blobs.map(async (blob) => {
-					const existing = await storage.getVariant(blob.id, transformations);
-					if (existing) return storage.getSignedUrl(existing.id, { expiresIn });
-					await generateImageVariant.start({
-						blobId: blob.id,
-						transformations
-					});
-					return null;
-				}));
-			},
-			async previews(expiresIn = 3600, timeInSeconds = 1) {
-				const blobs = await this.list();
-				return Promise.all(blobs.map(async (blob) => {
-					const existing = await storage.getVariant(blob.id, { preview: true });
-					if (existing) return storage.getSignedUrl(existing.id, { expiresIn });
-					await generatePreview.start({
-						blobId: blob.id,
-						timeInSeconds
-					});
-					return null;
-				}));
-			},
-			async detach(blobId) {
-				if (blobId) {
-					const attachment = (await storage.getAttachments(recordType, recordId, attachmentName)).find((r) => r.blob?.id === blobId);
-					if (attachment) {
-						await storage.deleteAttachment(attachment.id);
-						return 1;
-					}
-					return 0;
-				}
-				return storage.deleteAttachments(recordType, recordId, attachmentName);
-			},
-			async purge(blobId) {
-				const results = await storage.getAttachments(recordType, recordId, attachmentName);
-				if (blobId) {
-					const attachment = results.find((r) => r.blob?.id === blobId);
-					if (!attachment) return 0;
-					await storage.deleteAttachment(attachment.id);
-					await storage.deleteBlob(blobId);
-					return 1;
-				}
-				let count = 0;
-				for (const r of results) {
-					await storage.deleteAttachment(r.id);
-					if (r.blob) {
-						await storage.deleteBlob(r.blob.id);
-						count++;
-					}
-				}
-				return count;
-			},
-			async purgeLater(blobId) {
-				const results = await storage.getAttachments(recordType, recordId, attachmentName);
-				if (blobId) {
-					const attachment = results.find((r) => r.blob?.id === blobId);
-					if (!attachment) return 0;
-					await purgeAttachment.start({ attachmentIds: [attachment.id] });
-					return 1;
-				}
-				if (results.length > 0) await purgeAttachment.start({ attachmentIds: results.map((r) => r.id) });
-				return results.length;
-			},
-			async download() {
-				const blobs = await this.list();
-				const buffers = [];
-				for (const blob of blobs) {
-					const buffer = await storage.downloadBlob(blob.id);
-					if (buffer) buffers.push(buffer);
-				}
-				return buffers;
-			},
-			async open(callback) {
-				const blobs = await this.list();
-				const results = [];
-				for (const blob of blobs) {
-					const buffer = await storage.downloadBlob(blob.id);
-					if (!buffer) continue;
-					const tempDir = await mkdtemp(join(tmpdir(), "attachment-"));
-					const tempPath = join(tempDir, blob.filename);
-					try {
-						await writeFile(tempPath, buffer);
-						results.push(await callback(tempPath, blob));
-					} finally {
-						await rm(tempDir, {
-							recursive: true,
-							force: true
-						});
-					}
-				}
-				return results;
-			},
-			async representations(transformations, expiresIn = 3600) {
-				const blobs = await this.list();
-				return Promise.all(blobs.map(async (blob) => {
-					if (blob.contentType?.startsWith("image/")) {
-						const existing = await storage.getVariant(blob.id, transformations);
-						if (existing) return storage.getSignedUrl(existing.id, { expiresIn });
-						await generateImageVariant.start({
-							blobId: blob.id,
-							transformations
-						});
-						return null;
-					}
-					const preview = await storage.getVariant(blob.id, { preview: true });
-					if (preview) return storage.getSignedUrl(preview.id, { expiresIn });
-					await generatePreview.start({ blobId: blob.id });
-					return null;
-				}));
-			},
-			async byteSizes() {
-				return (await this.list()).map((b) => b.byteSize);
-			},
-			async contentTypes() {
-				return (await this.list()).map((b) => b.contentType);
-			},
-			async filenames() {
-				return (await this.list()).map((b) => b.filename);
-			},
-			async signedIds(expiresIn = 3600) {
-				return (await this.list()).map((b) => storage.signedId(b.id, expiresIn));
-			}
-		};
-	}
-};
-
-//#endregion
-export { StorageService, defineS3Disk, defineStorage };