@btst/stack 2.8.1 → 2.9.1

package/src/plugins/media/__tests__/query-key-defs.test.ts

@@ -0,0 +1,54 @@
+import { describe, it, expect, beforeEach } from "vitest";
+import { createMemoryAdapter } from "@btst/adapter-memory";
+import { defineDb } from "@btst/db";
+import type { DBAdapter as Adapter } from "@btst/db";
+import { mediaSchema } from "../db";
+import { listAssets } from "../api/getters";
+import {
+	MEDIA_QUERY_KEYS,
+	assetListDiscriminator,
+} from "../api/query-key-defs";
+
+const createTestAdapter = (): Adapter => {
+	const db = defineDb({}).use(mediaSchema);
+	return createMemoryAdapter(db)({});
+};
+
+const makeAsset = (index: number) => ({
+	filename: `asset-${index}.jpg`,
+	originalName: `Asset ${index}.jpg`,
+	mimeType: "image/jpeg",
+	size: 1024 + index,
+	url: `https://example.com/${index}.jpg`,
+	createdAt: new Date(Date.now() + index),
+});
+
+describe("media asset list query keys", () => {
+	let adapter: Adapter;
+
+	beforeEach(() => {
+		adapter = createTestAdapter();
+	});
+
+	it("distinguishes unbounded and explicit first-page pagination", async () => {
+		for (let i = 0; i < 25; i++) {
+			await adapter.create({
+				model: "mediaAsset",
+				data: makeAsset(i),
+			});
+		}
+
+		const unbounded = await listAssets(adapter);
+		const paginated = await listAssets(adapter, { limit: 20, offset: 0 });
+
+		expect(unbounded.items).toHaveLength(25);
+		expect(paginated.items).toHaveLength(20);
+
+		expect(assetListDiscriminator()).not.toEqual(
+			assetListDiscriminator({ limit: 20, offset: 0 }),
+		);
+		expect(MEDIA_QUERY_KEYS.assetsList()).not.toEqual(
+			MEDIA_QUERY_KEYS.assetsList({ limit: 20, offset: 0 }),
+		);
+	});
+});

package/src/plugins/media/__tests__/storage-adapters.test.ts

@@ -0,0 +1,351 @@
+import { describe, it, expect, vi, afterEach } from "vitest";
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import * as os from "node:os";
+
+// Top-level vi.mock calls are hoisted by Vitest before any imports.
+// Factories are used so the packages do not need to be installed as devDependencies.
+
+const mockSend = vi.fn().mockResolvedValue({});
+const mockS3Client = vi.fn(() => ({ send: mockSend }));
+const mockPutObjectCommand = vi.fn((input: unknown) => ({
+	input,
+	__type: "PutObjectCommand",
+}));
+const mockDeleteObjectCommand = vi.fn((input: unknown) => ({
+	input,
+	__type: "DeleteObjectCommand",
+}));
+const mockGetSignedUrl = vi
+	.fn()
+	.mockResolvedValue("https://s3.example.com/signed-url");
+
+const mockHandleUpload = vi.fn().mockResolvedValue({
+	type: "blob.generate-client-token",
+	clientToken: "tok123",
+});
+const mockDel = vi.fn().mockResolvedValue(undefined);
+
+vi.mock("@aws-sdk/client-s3", () => ({
+	S3Client: mockS3Client,
+	PutObjectCommand: mockPutObjectCommand,
+	DeleteObjectCommand: mockDeleteObjectCommand,
+}));
+
+vi.mock("@aws-sdk/s3-request-presigner", () => ({
+	getSignedUrl: mockGetSignedUrl,
+}));
+
+vi.mock("@vercel/blob/client", () => ({
+	handleUpload: mockHandleUpload,
+}));
+
+vi.mock("@vercel/blob", () => ({
+	del: mockDel,
+}));
+
+import { localAdapter } from "../api/adapters/local";
+
+// ── Local adapter ─────────────────────────────────────────────────────────────
+
+describe("localAdapter", () => {
+	let tmpDir: string;
+
+	afterEach(async () => {
+		if (tmpDir) {
+			await fs.rm(tmpDir, { recursive: true, force: true });
+		}
+		vi.clearAllMocks();
+	});
+
+	async function makeTmpDir() {
+		tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "btst-media-test-"));
+		return tmpDir;
+	}
+
+	it("uploads a file and returns a public URL", async () => {
+		const uploadDir = await makeTmpDir();
+		const adapter = localAdapter({ uploadDir, publicPath: "/uploads" });
+
+		const buffer = Buffer.from("hello world");
+		const { url } = await adapter.upload(buffer, {
+			filename: "test.txt",
+			mimeType: "text/plain",
+			size: buffer.byteLength,
+		});
+
+		expect(url).toMatch(/^\/uploads\/test-[a-f0-9]{16}\.txt$/);
+
+		const storedFilename = url.split("/").pop()!;
+		const storedPath = path.join(uploadDir, storedFilename);
+		const storedContent = await fs.readFile(storedPath);
+		expect(storedContent.toString()).toBe("hello world");
+	});
+
+	it("creates the upload directory if it does not exist", async () => {
+		const uploadDir = path.join(await makeTmpDir(), "nested", "uploads");
+		const adapter = localAdapter({ uploadDir, publicPath: "/uploads" });
+
+		const buffer = Buffer.from("data");
+		await adapter.upload(buffer, {
+			filename: "file.txt",
+			mimeType: "text/plain",
+			size: buffer.byteLength,
+		});
+
+		const stat = await fs.stat(uploadDir);
+		expect(stat.isDirectory()).toBe(true);
+	});
+
+	it("generates a unique filename for each upload", async () => {
+		const uploadDir = await makeTmpDir();
+		const adapter = localAdapter({ uploadDir, publicPath: "/uploads" });
+
+		const buf = Buffer.from("data");
+		const options = {
+			filename: "same.jpg",
+			mimeType: "image/jpeg",
+			size: buf.byteLength,
+		};
+		const { url: url1 } = await adapter.upload(buf, options);
+		const { url: url2 } = await adapter.upload(buf, options);
+
+		expect(url1).not.toBe(url2);
+	});
+
+	it("deletes a previously uploaded file", async () => {
+		const uploadDir = await makeTmpDir();
+		const adapter = localAdapter({ uploadDir, publicPath: "/uploads" });
+
+		const buffer = Buffer.from("delete me");
+		const { url } = await adapter.upload(buffer, {
+			filename: "todelete.txt",
+			mimeType: "text/plain",
+			size: buffer.byteLength,
+		});
+
+		const storedFilename = url.split("/").pop()!;
+		const storedPath = path.join(uploadDir, storedFilename);
+
+		await adapter.delete(url);
+		await expect(fs.stat(storedPath)).rejects.toThrow();
+	});
+
+	it("does not throw when deleting a file that does not exist", async () => {
+		const uploadDir = await makeTmpDir();
+		const adapter = localAdapter({ uploadDir, publicPath: "/uploads" });
+
+		await expect(
+			adapter.delete("/uploads/nonexistent-file.jpg"),
+		).resolves.not.toThrow();
+	});
+
+	it("uses default uploadDir and publicPath", async () => {
+		const adapter = localAdapter();
+		expect(adapter.type).toBe("local");
+	});
+});
+
+// ── S3 adapter ────────────────────────────────────────────────────────────────
+
+describe("s3Adapter", () => {
+	afterEach(() => {
+		vi.clearAllMocks();
+	});
+
+	it("generates a presigned PUT URL token", async () => {
+		const { s3Adapter } = await import("../api/adapters/s3");
+		const adapter = s3Adapter({
+			bucket: "my-bucket",
+			region: "us-east-1",
+			accessKeyId: "ACCESS_KEY",
+			secretAccessKey: "SECRET_KEY",
+			publicBaseUrl: "https://assets.example.com",
+		});
+
+		const token = await adapter.generateUploadToken({
+			filename: "photo.jpg",
+			mimeType: "image/jpeg",
+			size: 4096,
+		});
+
+		expect(token.type).toBe("presigned-url");
+		expect(token.payload).toMatchObject({
+			uploadUrl: "https://s3.example.com/signed-url",
+			publicUrl: "https://assets.example.com/photo.jpg",
+			key: "photo.jpg",
+			method: "PUT",
+			headers: { "Content-Type": "image/jpeg" },
+		});
+		expect(mockPutObjectCommand).toHaveBeenCalledWith(
+			expect.objectContaining({
+				Bucket: "my-bucket",
+				Key: "photo.jpg",
+				ContentType: "image/jpeg",
+			}),
+		);
+		expect(mockGetSignedUrl).toHaveBeenCalledWith(
+			expect.any(Object),
+			expect.any(Object),
+			{ expiresIn: 300 },
+		);
+	});
+
+	it("includes folderId in the S3 key", async () => {
+		const { s3Adapter } = await import("../api/adapters/s3");
+		const adapter = s3Adapter({
+			bucket: "my-bucket",
+			region: "us-east-1",
+			accessKeyId: "ACCESS_KEY",
+			secretAccessKey: "SECRET_KEY",
+			publicBaseUrl: "https://assets.example.com",
+		});
+
+		const token = await adapter.generateUploadToken({
+			filename: "image.png",
+			mimeType: "image/png",
+			size: 1000,
+			folderId: "folder-abc",
+		});
+
+		expect((token.payload as Record<string, unknown>).key).toBe(
+			"folder-abc/image.png",
+		);
+		expect((token.payload as Record<string, unknown>).publicUrl).toBe(
+			"https://assets.example.com/folder-abc/image.png",
+		);
+	});
+
+	it("calls DeleteObjectCommand with the correct key when deleting by public URL", async () => {
+		const { s3Adapter } = await import("../api/adapters/s3");
+		const adapter = s3Adapter({
+			bucket: "my-bucket",
+			region: "us-east-1",
+			accessKeyId: "ACCESS_KEY",
+			secretAccessKey: "SECRET_KEY",
+			publicBaseUrl: "https://assets.example.com",
+		});
+
+		await adapter.delete("https://assets.example.com/photos/cat.jpg");
+
+		expect(mockDeleteObjectCommand).toHaveBeenCalledWith({
+			Bucket: "my-bucket",
+			Key: "photos/cat.jpg",
+		});
+		expect(mockSend).toHaveBeenCalled();
+	});
+
+	it("respects the custom expiresIn option", async () => {
+		const { s3Adapter } = await import("../api/adapters/s3");
+		const adapter = s3Adapter({
+			bucket: "my-bucket",
+			region: "us-east-1",
+			accessKeyId: "ACCESS_KEY",
+			secretAccessKey: "SECRET_KEY",
+			publicBaseUrl: "https://assets.example.com",
+			expiresIn: 600,
+		});
+
+		await adapter.generateUploadToken({
+			filename: "file.jpg",
+			mimeType: "image/jpeg",
+			size: 100,
+		});
+
+		expect(mockGetSignedUrl).toHaveBeenCalledWith(
+			expect.any(Object),
+			expect.any(Object),
+			{ expiresIn: 600 },
+		);
+	});
+});
+
+// ── Vercel Blob adapter ───────────────────────────────────────────────────────
+
+describe("vercelBlobAdapter", () => {
+	afterEach(() => {
+		vi.clearAllMocks();
+	});
+
+	it("calls handleUpload with the request and body", async () => {
+		const { vercelBlobAdapter } = await import("../api/adapters/vercel-blob");
+		const adapter = vercelBlobAdapter();
+
+		const body = {
+			type: "blob.generate-client-token",
+			payload: { pathname: "photo.jpg" },
+		};
+		const request = new Request("https://example.com/api/upload", {
+			method: "POST",
+			body: JSON.stringify(body),
+			headers: { "Content-Type": "application/json" },
+		});
+
+		const result = await adapter.handleRequest(request, {});
+
+		expect(mockHandleUpload).toHaveBeenCalledWith(
+			expect.objectContaining({
+				body,
+				request,
+			}),
+		);
+		expect(result).toEqual({
+			type: "blob.generate-client-token",
+			clientToken: "tok123",
+		});
+	});
+
+	it("passes the onBeforeGenerateToken callback to handleUpload", async () => {
+		const { vercelBlobAdapter } = await import("../api/adapters/vercel-blob");
+		const adapter = vercelBlobAdapter();
+
+		const onBeforeGenerateToken = vi.fn().mockResolvedValue(undefined);
+		const body = {
+			type: "blob.generate-client-token",
+			payload: { pathname: "test.jpg" },
+		};
+		const request = new Request("https://example.com/api/upload", {
+			method: "POST",
+			body: JSON.stringify(body),
+			headers: { "Content-Type": "application/json" },
+		});
+
+		await adapter.handleRequest(request, { onBeforeGenerateToken });
+
+		// Verify that handleUpload received an onBeforeGenerateToken callback
+		const callArgs = mockHandleUpload.mock.calls[0]![0] as Record<
+			string,
+			unknown
+		>;
+		expect(callArgs.onBeforeGenerateToken).toBeTypeOf("function");
+
+		// Invoke the callback directly to verify it proxies to our hook
+		const cb = callArgs.onBeforeGenerateToken as Function;
+		await cb("test.jpg", null);
+		expect(onBeforeGenerateToken).toHaveBeenCalledWith("test.jpg", null);
+	});
+
+	it("calls del when deleting a blob by URL", async () => {
+		const { vercelBlobAdapter } = await import("../api/adapters/vercel-blob");
+		const adapter = vercelBlobAdapter();
+
+		await adapter.delete("https://public.blob.vercel-storage.com/photo.jpg");
+
+		expect(mockDel).toHaveBeenCalledWith(
+			"https://public.blob.vercel-storage.com/photo.jpg",
+			undefined,
+		);
+	});
+
+	it("passes the token option to del when provided", async () => {
+		const { vercelBlobAdapter } = await import("../api/adapters/vercel-blob");
+		const adapter = vercelBlobAdapter({ token: "my-custom-token" });
+
+		await adapter.delete("https://public.blob.vercel-storage.com/file.jpg");
+
+		expect(mockDel).toHaveBeenCalledWith(
+			"https://public.blob.vercel-storage.com/file.jpg",
+			{ token: "my-custom-token" },
+		);
+	});
+});

package/src/plugins/media/api/adapters/local.ts

@@ -0,0 +1,79 @@
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import * as crypto from "node:crypto";
+import type { DirectStorageAdapter, UploadOptions } from "../storage-adapter";
+
+export interface LocalStorageAdapterOptions {
+	/**
+	 * Absolute path to the directory where uploaded files are stored.
+	 * @default "./public/uploads"
+	 */
+	uploadDir?: string;
+	/**
+	 * URL prefix used to build the public URL for uploaded files.
+	 * @default "/uploads"
+	 */
+	publicPath?: string;
+}
+
+/**
+ * Create a local filesystem storage adapter.
+ * Files are written to `uploadDir` and served at `publicPath`.
+ * Suitable for development and self-hosted deployments.
+ *
+ * @example
+ * ```ts
+ * mediaBackendPlugin({
+ *   storageAdapter: localAdapter({ uploadDir: "./public/uploads", publicPath: "/uploads" })
+ * })
+ * ```
+ */
+export function localAdapter(
+	options: LocalStorageAdapterOptions = {},
+): DirectStorageAdapter {
+	const uploadDir = options.uploadDir ?? "./public/uploads";
+	const publicPath = options.publicPath ?? "/uploads";
+
+	return {
+		type: "local" as const,
+
+		async upload(
+			buffer: Buffer,
+			{ filename }: UploadOptions,
+		): Promise<{ url: string }> {
+			await fs.mkdir(uploadDir, { recursive: true });
+
+			const ext = path.extname(filename);
+			const base = path.basename(filename, ext);
+			const unique = crypto.randomBytes(8).toString("hex");
+			const storedFilename = `${base}-${unique}${ext}`;
+			const filePath = path.join(uploadDir, storedFilename);
+
+			await fs.writeFile(filePath, buffer);
+
+			// Percent-encode the filename segment so the returned URL is always a
+			// valid URL — e.g. spaces become %20. The raw storedFilename is used for
+			// the filesystem path; the encoded form is what gets stored in the DB and
+			// served to clients.
+			const url = `${publicPath.replace(/\/$/, "")}/${encodeURIComponent(storedFilename)}`;
+			return { url };
+		},
+
+		async delete(url: string): Promise<void> {
+			// The stored URL has an encoded filename (e.g. "my%20file.png"); decode
+			// it back to the raw filesystem name before building the file path.
+			const encodedFilename = url.split("/").pop();
+			if (!encodedFilename) return;
+			const filename = decodeURIComponent(encodedFilename);
+
+			const filePath = path.join(uploadDir, filename);
+			try {
+				await fs.unlink(filePath);
+			} catch (err: unknown) {
+				if ((err as NodeJS.ErrnoException).code !== "ENOENT") {
+					throw err;
+				}
+			}
+		},
+	};
+}

package/src/plugins/media/api/adapters/s3.ts

@@ -0,0 +1,198 @@
+import type {
+	S3StorageAdapter,
+	S3UploadToken,
+	UploadOptions,
+} from "../storage-adapter";
+
+export interface S3StorageAdapterOptions {
+	/**
+	 * The S3 bucket name.
+	 */
+	bucket: string;
+	/**
+	 * AWS region (e.g. `"us-east-1"`).
+	 */
+	region: string;
+	/**
+	 * AWS access key ID.
+	 */
+	accessKeyId: string;
+	/**
+	 * AWS secret access key.
+	 */
+	secretAccessKey: string;
+	/**
+	 * Custom endpoint URL for S3-compatible providers (Cloudflare R2, MinIO, etc.).
+	 * @example "https://<account-id>.r2.cloudflarestorage.com"
+	 */
+	endpoint?: string;
+	/**
+	 * Base URL used to construct the final public asset URL after upload.
+	 * @example "https://assets.example.com" or "https://pub-<id>.r2.dev"
+	 */
+	publicBaseUrl: string;
+	/**
+	 * Duration in seconds for which the presigned URL is valid.
+	 * @default 300 (5 minutes)
+	 */
+	expiresIn?: number;
+}
+
+/**
+ * Create an S3-compatible presigned-URL storage adapter.
+ * The server generates a short-lived presigned PUT URL; the browser uploads
+ * the file directly to S3 (or R2 / MinIO). The server never receives file bytes.
+ *
+ * @remarks Requires `@aws-sdk/client-s3` and `@aws-sdk/s3-request-presigner`
+ * as optional peer dependencies.
+ *
+ * @example
+ * ```ts
+ * mediaBackendPlugin({
+ *   storageAdapter: s3Adapter({
+ *     bucket: "my-bucket",
+ *     region: "us-east-1",
+ *     accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
+ *     secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
+ *     publicBaseUrl: "https://assets.example.com",
+ *   })
+ * })
+ * ```
+ */
+export function s3Adapter(options: S3StorageAdapterOptions): S3StorageAdapter {
+	const {
+		bucket,
+		region,
+		accessKeyId,
+		secretAccessKey,
+		endpoint,
+		publicBaseUrl,
+		expiresIn = 300,
+	} = options;
+
+	let s3ModulePromise: Promise<typeof import("@aws-sdk/client-s3")> | null =
+		null;
+	let clientPromise: Promise<
+		InstanceType<typeof import("@aws-sdk/client-s3").S3Client>
+	> | null = null;
+
+	function getS3Module() {
+		if (!s3ModulePromise) {
+			s3ModulePromise = import("@aws-sdk/client-s3").catch(() => {
+				s3ModulePromise = null;
+				throw new Error(
+					"[@btst/stack] S3 adapter requires '@aws-sdk/client-s3'. " +
+						"Run: npm install @aws-sdk/client-s3 @aws-sdk/s3-request-presigner",
+				);
+			});
+		}
+		return s3ModulePromise;
+	}
+
+	function getClient() {
+		if (!clientPromise) {
+			clientPromise = getS3Module().then(({ S3Client }) => {
+				return new S3Client({
+					region,
+					endpoint,
+					credentials: { accessKeyId, secretAccessKey },
+					forcePathStyle: !!endpoint,
+				});
+			});
+		}
+		return clientPromise.catch((error) => {
+			if (clientPromise) {
+				clientPromise = null;
+			}
+			if (s3ModulePromise && error instanceof Error) {
+				throw error;
+			}
+			throw new Error(
+				"[@btst/stack] S3 adapter requires '@aws-sdk/client-s3'. " +
+					"Run: npm install @aws-sdk/client-s3 @aws-sdk/s3-request-presigner",
+			);
+		});
+	}
+
+	async function buildSignedUrl(
+		client: unknown,
+		command: unknown,
+		opts: { expiresIn: number },
+	): Promise<string> {
+		let getSignedUrl: typeof import("@aws-sdk/s3-request-presigner")["getSignedUrl"];
+		try {
+			({ getSignedUrl } = await import("@aws-sdk/s3-request-presigner"));
+		} catch {
+			throw new Error(
+				"[@btst/stack] S3 adapter requires '@aws-sdk/s3-request-presigner'. " +
+					"Run: npm install @aws-sdk/client-s3 @aws-sdk/s3-request-presigner",
+			);
+		}
+		return getSignedUrl(
+			client as Parameters<typeof getSignedUrl>[0],
+			command as Parameters<typeof getSignedUrl>[1],
+			opts,
+		);
+	}
+
+	return {
+		type: "s3" as const,
+		urlPrefix: publicBaseUrl.replace(/\/$/, ""),
+
+		async generateUploadToken(
+			uploadOptions: UploadOptions,
+		): Promise<S3UploadToken> {
+			const [client, { PutObjectCommand }] = await Promise.all([
+				getClient(),
+				getS3Module(),
+			]);
+
+			const key = uploadOptions.folderId
+				? `${uploadOptions.folderId}/${uploadOptions.filename}`
+				: uploadOptions.filename;
+
+			const command = new PutObjectCommand({
+				Bucket: bucket,
+				Key: key,
+				ContentType: uploadOptions.mimeType,
+				ContentLength: uploadOptions.size,
+			});
+
+			const uploadUrl = await buildSignedUrl(client, command, { expiresIn });
+
+			// Percent-encode each path segment so the stored public URL is always
+			// valid. The raw `key` is used for the S3 key (which the AWS SDK
+			// handles separately); the encoded form is what gets stored in the DB
+			// and returned to clients.
+			const encodedKey = key.split("/").map(encodeURIComponent).join("/");
+			const publicUrl = `${publicBaseUrl.replace(/\/$/, "")}/${encodedKey}`;
+
+			return {
+				type: "presigned-url",
+				payload: {
+					uploadUrl,
+					publicUrl,
+					key,
+					method: "PUT" as const,
+					headers: { "Content-Type": uploadOptions.mimeType },
+				},
+			};
+		},
+
+		async delete(url: string): Promise<void> {
+			const [client, { DeleteObjectCommand }] = await Promise.all([
+				getClient(),
+				getS3Module(),
+			]);
+
+			const base = publicBaseUrl.replace(/\/$/, "");
+			const encodedKey = url.startsWith(base)
+				? url.slice(base.length + 1)
+				: (url.split("/").pop() ?? url);
+			// Decode the percent-encoded key back to the raw S3 object key.
+			const key = decodeURIComponent(encodedKey);
+
+			await client.send(new DeleteObjectCommand({ Bucket: bucket, Key: key }));
+		},
+	};
+}