@btst/stack 2.8.1 → 2.9.1

package/src/plugins/media/api/adapters/vercel-blob.ts

@@ -0,0 +1,131 @@
+import type {
+	VercelBlobStorageAdapter,
+	VercelBlobHandlerCallbacks,
+} from "../storage-adapter";
+
+export interface VercelBlobStorageAdapterOptions {
+	/**
+	 * The `BLOB_READ_WRITE_TOKEN` environment variable is read automatically
+	 * by `@vercel/blob`. You only need to provide this option if you store
+	 * the token under a different name.
+	 */
+	token?: string;
+}
+
+/**
+ * Minimal subset of the `@vercel/blob/client` `handleUpload` options.
+ * Defined inline so we do not hard-depend on a specific `@vercel/blob` release.
+ */
+interface HandleUploadOptions {
+	body: unknown;
+	request: Request;
+	token?: string;
+	onBeforeGenerateToken: (
+		pathname: string,
+		clientPayload?: string | null,
+	) => Promise<{
+		addRandomSuffix?: boolean;
+		allowedContentTypes?: string[];
+		maximumSizeInBytes?: number;
+	}>;
+	onUploadCompleted: (args: {
+		blob: { url: string; pathname: string };
+		tokenPayload?: string | null;
+	}) => Promise<void>;
+}
+
+type HandleUploadFn = (options: HandleUploadOptions) => Promise<unknown>;
+type DelFn = (url: string, options?: { token?: string }) => Promise<void>;
+
+/**
+ * Create a Vercel Blob storage adapter using the signed direct-upload protocol.
+ * The server never receives file bytes — it only issues short-lived client tokens
+ * via `@vercel/blob`'s `handleUpload` helper (available via `@vercel/blob/client`
+ * in compatible versions).
+ *
+ * @remarks Requires `@vercel/blob` as an optional peer dependency (version
+ * with `handleUpload` exported from `@vercel/blob/client`).
+ *
+ * Upload flow:
+ * 1. Client calls `POST /media/upload/vercel-blob` to obtain a client token.
+ * 2. Client uses `@vercel/blob/client`'s `upload()` to upload directly to Vercel.
+ * 3. After upload, client calls `POST /media/assets` to save metadata to the DB.
+ *
+ * @example
+ * ```ts
+ * mediaBackendPlugin({
+ *   storageAdapter: vercelBlobAdapter(),
+ *   hooks: {
+ *     onBeforeUpload: async (_meta, ctx) => {
+ *       const session = await getSession(ctx.headers);
+ *       if (!session) throw new Error("Unauthorized");
+ *     },
+ *   },
+ * })
+ * ```
+ */
+export function vercelBlobAdapter(
+	options: VercelBlobStorageAdapterOptions = {},
+): VercelBlobStorageAdapter {
+	return {
+		type: "vercel-blob" as const,
+		urlHostnameSuffix: ".public.blob.vercel-storage.com",
+
+		async handleRequest(
+			request: Request,
+			callbacks: VercelBlobHandlerCallbacks,
+		): Promise<unknown> {
+			let handleUpload: HandleUploadFn;
+			try {
+				const vercelBlobClient =
+					/* @vite-ignore */
+					(await import("@vercel/blob/client")) as {
+						handleUpload: HandleUploadFn;
+					};
+				({ handleUpload } = vercelBlobClient);
+			} catch {
+				throw new Error(
+					"[@btst/stack] Vercel Blob adapter requires '@vercel/blob' with " +
+						"'handleUpload' exported from '@vercel/blob/client'. " +
+						"Run: npm install @vercel/blob",
+				);
+			}
+
+			const body = await request.json();
+
+			return handleUpload({
+				body,
+				request,
+				token: options.token,
+				onBeforeGenerateToken: async (pathname, clientPayload) => {
+					const tokenOptions =
+						(await callbacks.onBeforeGenerateToken?.(
+							pathname,
+							clientPayload ?? null,
+						)) ?? {};
+					return {
+						addRandomSuffix: true,
+						...tokenOptions,
+					};
+				},
+				onUploadCompleted: async () => {
+					// DB record is created by the client calling POST /media/assets
+					// after the upload completes. Nothing to do server-side here.
+				},
+			});
+		},
+
+		async delete(url: string): Promise<void> {
+			let del: DelFn;
+			try {
+				({ del } = (await import("@vercel/blob")) as { del: DelFn });
+			} catch {
+				throw new Error(
+					"[@btst/stack] Vercel Blob adapter requires '@vercel/blob'. " +
+						"Run: npm install @vercel/blob",
+				);
+			}
+			await del(url, options.token ? { token: options.token } : undefined);
+		},
+	};
+}

package/src/plugins/media/api/getters.ts

@@ -0,0 +1,174 @@
+import type { DBAdapter as Adapter } from "@btst/db";
+import type { Asset, Folder } from "../types";
+
+/**
+ * Parameters for filtering and paginating the asset list.
+ */
+export interface AssetListParams {
+	folderId?: string;
+	mimeType?: string;
+	query?: string;
+	offset?: number;
+	limit?: number;
+}
+
+/**
+ * Paginated result returned by {@link listAssets}.
+ */
+export interface AssetListResult {
+	items: Asset[];
+	total: number;
+	limit?: number;
+	offset?: number;
+}
+
+/**
+ * Parameters for filtering the folder list.
+ */
+export interface FolderListParams {
+	parentId?: string | null;
+}
+
+/**
+ * Retrieve all assets matching optional filter criteria.
+ * Pure DB function — no hooks, no HTTP context. Safe for server-side use.
+ *
+ * @remarks **Security:** Authorization hooks are NOT called. The caller is
+ * responsible for any access-control checks before invoking this function.
+ */
+export async function listAssets(
+	adapter: Adapter,
+	params?: AssetListParams,
+): Promise<AssetListResult> {
+	const query = params ?? {};
+
+	const whereConditions: Array<{
+		field: string;
+		value: string | number | boolean | string[] | number[] | Date | null;
+		operator: "eq" | "in";
+	}> = [];
+
+	if (query.folderId !== undefined) {
+		whereConditions.push({
+			field: "folderId",
+			value: query.folderId,
+			operator: "eq" as const,
+		});
+	}
+
+	if (query.mimeType) {
+		whereConditions.push({
+			field: "mimeType",
+			value: query.mimeType,
+			operator: "eq" as const,
+		});
+	}
+
+	const needsInMemoryFilter = !!query.query;
+	const dbWhere = whereConditions.length > 0 ? whereConditions : undefined;
+
+	const dbTotal: number | undefined = !needsInMemoryFilter
+		? await adapter.count({ model: "mediaAsset", where: dbWhere })
+		: undefined;
+
+	let assets = await adapter.findMany<Asset>({
+		model: "mediaAsset",
+		limit: !needsInMemoryFilter ? query.limit : undefined,
+		offset: !needsInMemoryFilter ? query.offset : undefined,
+		where: dbWhere,
+		sortBy: { field: "createdAt", direction: "desc" },
+	});
+
+	if (query.query) {
+		const searchLower = query.query.toLowerCase();
+		assets = assets.filter(
+			(asset) =>
+				asset.filename.toLowerCase().includes(searchLower) ||
+				asset.originalName.toLowerCase().includes(searchLower) ||
+				asset.alt?.toLowerCase().includes(searchLower),
+		);
+	}
+
+	if (needsInMemoryFilter) {
+		const total = assets.length;
+		const offset = query.offset ?? 0;
+		const limit = query.limit;
+		assets = assets.slice(
+			offset,
+			limit !== undefined ? offset + limit : undefined,
+		);
+		return { items: assets, total, limit: query.limit, offset: query.offset };
+	}
+
+	return {
+		items: assets,
+		total: dbTotal ?? assets.length,
+		limit: query.limit,
+		offset: query.offset,
+	};
+}
+
+/**
+ * Retrieve a single asset by its ID.
+ * Returns `null` if no asset is found.
+ * Pure DB function — no hooks, no HTTP context.
+ *
+ * @remarks **Security:** Authorization hooks are NOT called.
+ */
+export async function getAssetById(
+	adapter: Adapter,
+	id: string,
+): Promise<Asset | null> {
+	return adapter.findOne<Asset>({
+		model: "mediaAsset",
+		where: [{ field: "id", value: id, operator: "eq" as const }],
+	});
+}
+
+/**
+ * Retrieve all folders, optionally filtered by `parentId`.
+ * Pass `null` to list root-level folders (those without a parent).
+ * Pure DB function — no hooks, no HTTP context.
+ *
+ * @remarks **Security:** Authorization hooks are NOT called.
+ */
+export async function listFolders(
+	adapter: Adapter,
+	params?: FolderListParams,
+): Promise<Folder[]> {
+	// Only add a where clause when parentId is explicitly provided as a string.
+	// Passing undefined (or no params) returns all folders unfiltered.
+	const where =
+		params?.parentId !== undefined
+			? [
+					{
+						field: "parentId",
+						value: params.parentId,
+						operator: "eq" as const,
+					},
+				]
+			: undefined;
+
+	return adapter.findMany<Folder>({
+		model: "mediaFolder",
+		where,
+		sortBy: { field: "name", direction: "asc" },
+	});
+}
+
+/**
+ * Retrieve a single folder by its ID.
+ * Returns `null` if no folder is found.
+ * Pure DB function — no hooks, no HTTP context.
+ *
+ * @remarks **Security:** Authorization hooks are NOT called.
+ */
+export async function getFolderById(
+	adapter: Adapter,
+	id: string,
+): Promise<Folder | null> {
+	return adapter.findOne<Folder>({
+		model: "mediaFolder",
+		where: [{ field: "id", value: id, operator: "eq" as const }],
+	});
+}

package/src/plugins/media/api/index.ts

@@ -0,0 +1,41 @@
+export * from "./plugin";
+
+export {
+	listAssets,
+	getAssetById,
+	listFolders,
+	getFolderById,
+	type AssetListParams,
+	type AssetListResult,
+	type FolderListParams,
+} from "./getters";
+
+export {
+	createAsset,
+	updateAsset,
+	deleteAsset,
+	createFolder,
+	deleteFolder,
+	type CreateAssetInput,
+	type UpdateAssetInput,
+	type CreateFolderInput,
+} from "./mutations";
+
+export { serializeAsset, serializeFolder } from "./serializers";
+
+export { MEDIA_QUERY_KEYS, assetListDiscriminator } from "./query-key-defs";
+
+export {
+	localAdapter,
+	type LocalStorageAdapterOptions,
+} from "./adapters/local";
+
+export type {
+	StorageAdapter,
+	DirectStorageAdapter,
+	S3StorageAdapter,
+	S3UploadToken,
+	VercelBlobStorageAdapter,
+	VercelBlobHandlerCallbacks,
+	UploadOptions,
+} from "./storage-adapter";

package/src/plugins/media/api/mutations.ts

@@ -0,0 +1,179 @@
+import type { DBAdapter as Adapter } from "@btst/db";
+import type { Asset, Folder } from "../types";
+
+/**
+ * Input for creating a new asset record.
+ */
+export interface CreateAssetInput {
+	filename: string;
+	originalName: string;
+	mimeType: string;
+	size: number;
+	url: string;
+	folderId?: string;
+	alt?: string;
+}
+
+/**
+ * Input for updating an existing asset record.
+ */
+export interface UpdateAssetInput {
+	alt?: string;
+	folderId?: string | null;
+}
+
+/**
+ * Input for creating a new folder.
+ */
+export interface CreateFolderInput {
+	name: string;
+	parentId?: string;
+}
+
+/**
+ * Create an asset record in the database.
+ * Pure DB function — no authorization hooks, no HTTP context.
+ *
+ * @remarks **Security:** No authorization hooks (e.g. `onBeforeUpload`) are called.
+ * The caller is responsible for any access-control checks before invoking this function.
+ */
+export async function createAsset(
+	adapter: Adapter,
+	input: CreateAssetInput,
+): Promise<Asset> {
+	return adapter.create<Asset>({
+		model: "mediaAsset",
+		data: {
+			filename: input.filename,
+			originalName: input.originalName,
+			mimeType: input.mimeType,
+			size: input.size,
+			url: input.url,
+			folderId: input.folderId,
+			alt: input.alt,
+			createdAt: new Date(),
+		},
+	});
+}
+
+/**
+ * Update an asset's `alt` text or `folderId`.
+ * Pure DB function — no authorization hooks, no HTTP context.
+ *
+ * @remarks **Security:** No authorization hooks are called.
+ */
+export async function updateAsset(
+	adapter: Adapter,
+	id: string,
+	input: UpdateAssetInput,
+): Promise<Asset | null> {
+	const update: Record<string, unknown> = {};
+
+	if (input.alt !== undefined) {
+		update.alt = input.alt;
+	}
+
+	if ("folderId" in input) {
+		// null explicitly clears the folder association; undefined means "not provided"
+		update.folderId = input.folderId;
+	}
+
+	return adapter.update<Asset>({
+		model: "mediaAsset",
+		where: [{ field: "id", value: id, operator: "eq" as const }],
+		update,
+	});
+}
+
+/**
+ * Delete an asset record from the database by its ID.
+ * Does NOT delete the underlying file — the caller must do that via the storage adapter.
+ * Pure DB function — no authorization hooks, no HTTP context.
+ *
+ * @remarks **Security:** No authorization hooks are called.
+ */
+export async function deleteAsset(adapter: Adapter, id: string): Promise<void> {
+	await adapter.delete<Asset>({
+		model: "mediaAsset",
+		where: [{ field: "id", value: id, operator: "eq" as const }],
+	});
+}
+
+/**
+ * Create a folder record in the database.
+ * Pure DB function — no authorization hooks, no HTTP context.
+ *
+ * @remarks **Security:** No authorization hooks are called.
+ */
+export async function createFolder(
+	adapter: Adapter,
+	input: CreateFolderInput,
+): Promise<Folder> {
+	return adapter.create<Folder>({
+		model: "mediaFolder",
+		data: {
+			name: input.name,
+			parentId: input.parentId,
+			createdAt: new Date(),
+		},
+	});
+}
+
+/**
+ * Delete a folder record from the database by its ID.
+ * Child folders are cascade-deleted automatically. Throws if the folder or
+ * any of its descendants contain assets (which have associated storage files
+ * that must be deleted via the storage adapter first).
+ * Pure DB function — no authorization hooks, no HTTP context.
+ *
+ * @remarks **Security:** No authorization hooks are called.
+ */
+export async function deleteFolder(
+	adapter: Adapter,
+	id: string,
+): Promise<void> {
+	// BFS to collect the target folder and all of its descendants.
+	const allFolderIds: string[] = [id];
+	const queue: string[] = [id];
+
+	while (queue.length > 0) {
+		const parentId = queue.shift()!;
+		const children = await adapter.findMany<Folder>({
+			model: "mediaFolder",
+			where: [{ field: "parentId", value: parentId, operator: "eq" as const }],
+		});
+		for (const child of children) {
+			allFolderIds.push(child.id);
+			queue.push(child.id);
+		}
+	}
+
+	// Reject the deletion if any folder in the subtree contains assets.
+	// Assets map to real storage files — the caller must delete them via the
+	// storage adapter before removing the DB records.
+	let totalAssets = 0;
+	for (const folderId of allFolderIds) {
+		totalAssets += await adapter.count({
+			model: "mediaAsset",
+			where: [{ field: "folderId", value: folderId, operator: "eq" as const }],
+		});
+	}
+
+	if (totalAssets > 0) {
+		throw new Error(
+			`Cannot delete folder: it or one of its subfolders contains ${totalAssets} asset(s). Move or delete them first.`,
+		);
+	}
+
+	// Wrap all deletions in a transaction so the subtree is removed atomically.
+	// If any individual deletion fails the entire subtree is left intact.
+	await adapter.transaction(async (tx) => {
+		// Delete deepest folders first, then work back up to the root.
+		for (const folderId of [...allFolderIds].reverse()) {
+			await tx.delete<Folder>({
+				model: "mediaFolder",
+				where: [{ field: "id", value: folderId, operator: "eq" as const }],
+			});
+		}
+	});
+}