@btst/stack 2.8.1 → 2.9.1

package/src/plugins/media/client/plugin.tsx

@@ -0,0 +1,184 @@
+import {
+	defineClientPlugin,
+	createApiClient,
+	isConnectionError,
+} from "@btst/stack/plugins/client";
+import { createRoute } from "@btst/yar";
+import type { ComponentType } from "react";
+import type { QueryClient } from "@tanstack/react-query";
+import { LibraryPageComponent } from "./components/pages/library-page";
+import { createMediaQueryKeys } from "../query-keys";
+import type { MediaApiRouter } from "../api/plugin";
+
+export interface MediaLoaderContext {
+	path: string;
+	isSSR: boolean;
+	apiBaseURL: string;
+	apiBasePath: string;
+	headers?: HeadersInit;
+}
+
+export interface MediaClientHooks {
+	/** Called before the media library data is fetched during SSR. Throw to cancel. */
+	beforeLoadLibrary?: (context: MediaLoaderContext) => Promise<void> | void;
+
+	/** Called after the media library data is fetched during SSR. */
+	afterLoadLibrary?: (context: MediaLoaderContext) => Promise<void> | void;
+
+	/** Called when an error occurs during the SSR loader. */
+	onLoadError?: (
+		error: Error,
+		context: MediaLoaderContext,
+	) => Promise<void> | void;
+}
+
+export interface MediaClientConfig {
+	/** Base URL for API calls (e.g., "http://localhost:3000") */
+	apiBaseURL: string;
+	/** Path where the API is mounted (e.g., "/api/data") */
+	apiBasePath: string;
+	/** Base URL of your site for SEO meta tags */
+	siteBaseURL: string;
+	/** Path where pages are mounted (e.g., "/pages") */
+	siteBasePath: string;
+	/** React Query client — used by the SSR loader to prefetch data */
+	queryClient: QueryClient;
+	/** Optional headers forwarded with SSR API requests (e.g. auth cookies) */
+	headers?: HeadersInit;
+	/** Optional lifecycle hooks for the media client plugin */
+	hooks?: MediaClientHooks;
+	/**
+	 * Optional page component overrides.
+	 * Replace any plugin page with a custom React component.
+	 * The built-in component is used as the fallback when not provided.
+	 */
+	pageComponents?: {
+		/** Replaces the media library page */
+		library?: ComponentType;
+	};
+}
+
+/**
+ * Media client plugin.
+ * Registers the /media library route.
+ *
+ * Configure overrides in StackProvider:
+ * ```tsx
+ * <StackProvider overrides={{ media: { apiBaseURL, apiBasePath, queryClient, uploadMode: "direct", navigate } }}>
+ * ```
+ *
+ * @example
+ * ```ts
+ * import { mediaClientPlugin } from "@btst/stack/plugins/media/client"
+ *
+ * const clientPlugins = [
+ *   mediaClientPlugin({ apiBaseURL, apiBasePath, siteBaseURL, siteBasePath, queryClient }),
+ *   // ...other plugins
+ * ]
+ * ```
+ */
+export const mediaClientPlugin = (config: MediaClientConfig) =>
+	defineClientPlugin({
+		name: "media",
+
+		routes: () => ({
+			library: createRoute("/media", () => {
+				const CustomLibrary = config.pageComponents?.library;
+				return {
+					PageComponent: CustomLibrary ?? LibraryPageComponent,
+					loader: createMediaLibraryLoader(config),
+					meta: createMediaLibraryMeta(config),
+				};
+			}),
+		}),
+	});
+
+function createMediaLibraryLoader(config: MediaClientConfig) {
+	return async () => {
+		if (typeof window === "undefined") {
+			const { queryClient, apiBasePath, apiBaseURL, hooks, headers } = config;
+
+			const context: MediaLoaderContext = {
+				path: "/media",
+				isSSR: true,
+				apiBaseURL,
+				apiBasePath,
+				headers,
+			};
+
+			try {
+				if (hooks?.beforeLoadLibrary) {
+					await hooks.beforeLoadLibrary(context);
+				}
+
+				const client = createApiClient<MediaApiRouter>({
+					baseURL: apiBaseURL,
+					basePath: apiBasePath,
+				});
+				const queries = createMediaQueryKeys(client, headers);
+
+				// Prefetch initial asset grid (infinite query — root folder, default limit)
+				await queryClient.prefetchInfiniteQuery({
+					...queries.mediaAssets.list({ limit: 40 }),
+					initialPageParam: 0,
+				});
+
+				// Prefetch root-level folders for the sidebar tree
+				await queryClient.prefetchQuery(queries.mediaFolders.list(null));
+
+				if (hooks?.afterLoadLibrary) {
+					await hooks.afterLoadLibrary(context);
+				}
+
+				const queryState = queryClient.getQueryState(
+					queries.mediaAssets.list({ limit: 40 }).queryKey,
+				);
+				if (queryState?.error && hooks?.onLoadError) {
+					const error =
+						queryState.error instanceof Error
+							? queryState.error
+							: new Error(String(queryState.error));
+					await hooks.onLoadError(error, context);
+				}
+			} catch (error) {
+				if (isConnectionError(error)) {
+					console.warn(
+						"[btst/media] route.loader() failed — no server running at build time. " +
+							"The media library does not support SSG.",
+					);
+				}
+				if (hooks?.onLoadError) {
+					await hooks.onLoadError(error as Error, context);
+				}
+			}
+		}
+	};
+}
+
+function createMediaLibraryMeta(config: MediaClientConfig) {
+	return () => {
+		const { siteBaseURL, siteBasePath } = config;
+		const fullUrl = `${siteBaseURL}${siteBasePath}/media`;
+		const title = "Media Library";
+
+		return [
+			{ title },
+			{ name: "title", content: title },
+			{ name: "description", content: "Manage your media assets" },
+			{ name: "robots", content: "noindex, nofollow" },
+
+			// Open Graph
+			{ property: "og:type", content: "website" },
+			{ property: "og:title", content: title },
+			{
+				property: "og:description",
+				content: "Manage your media assets",
+			},
+			{ property: "og:url", content: fullUrl },
+
+			// Twitter
+			{ name: "twitter:card", content: "summary" },
+			{ name: "twitter:title", content: title },
+		];
+	};
+}

package/src/plugins/media/client/upload.ts

@@ -0,0 +1,171 @@
+"use client";
+
+import type { SerializedAsset } from "../types";
+import type { MediaPluginOverrides } from "./overrides";
+import { compressImage } from "./utils/image-compression";
+
+export type MediaUploadClientConfig = Pick<
+	MediaPluginOverrides,
+	"apiBaseURL" | "apiBasePath" | "headers" | "uploadMode" | "imageCompression"
+>;
+
+export interface UploadAssetInput {
+	file: File;
+	folderId?: string;
+}
+
+const DEFAULT_IMAGE_COMPRESSION = {
+	maxWidth: 2048,
+	maxHeight: 2048,
+	quality: 0.85,
+} as const;
+
+/**
+ * Upload an asset using the media plugin's configured storage mode.
+ *
+ * Use this in non-React contexts like editor `uploadImage` callbacks. React
+ * components should usually prefer `useUploadAsset()`, which wraps this helper
+ * and handles cache invalidation.
+ */
+export async function uploadAsset(
+	config: MediaUploadClientConfig,
+	input: UploadAssetInput,
+): Promise<SerializedAsset> {
+	const {
+		apiBaseURL,
+		apiBasePath,
+		headers,
+		uploadMode = "direct",
+		imageCompression,
+	} = config;
+	const { file, folderId } = input;
+
+	const processedFile =
+		imageCompression === false
+			? file
+			: await compressImage(
+					file,
+					imageCompression ?? DEFAULT_IMAGE_COMPRESSION,
+				);
+
+	const base = `${apiBaseURL}${apiBasePath}`;
+	const headersObj = new Headers(headers as HeadersInit | undefined);
+
+	if (uploadMode === "direct") {
+		const formData = new FormData();
+		formData.append("file", processedFile);
+		if (folderId) formData.append("folderId", folderId);
+
+		const res = await fetch(`${base}/media/upload`, {
+			method: "POST",
+			headers: headersObj,
+			body: formData,
+		});
+		if (!res.ok) {
+			const err = await res.json().catch(() => ({ message: res.statusText }));
+			throw new Error(err.message ?? "Upload failed");
+		}
+		return res.json();
+	}
+
+	if (uploadMode === "s3") {
+		const tokenRes = await fetch(`${base}/media/upload/token`, {
+			method: "POST",
+			headers: {
+				...Object.fromEntries(headersObj.entries()),
+				"Content-Type": "application/json",
+			},
+			body: JSON.stringify({
+				filename: processedFile.name,
+				mimeType: processedFile.type,
+				size: processedFile.size,
+				folderId,
+			}),
+		});
+		if (!tokenRes.ok) {
+			const err = await tokenRes
+				.json()
+				.catch(() => ({ message: tokenRes.statusText }));
+			throw new Error(err.message ?? "Failed to get upload token");
+		}
+
+		const token = (await tokenRes.json()) as {
+			type: "presigned-url";
+			payload: {
+				uploadUrl: string;
+				publicUrl: string;
+				key: string;
+				method: "PUT";
+				headers: Record<string, string>;
+			};
+		};
+
+		const putRes = await fetch(token.payload.uploadUrl, {
+			method: "PUT",
+			headers: token.payload.headers,
+			body: processedFile,
+		});
+		if (!putRes.ok) throw new Error("Failed to upload to S3");
+
+		const assetRes = await fetch(`${base}/media/assets`, {
+			method: "POST",
+			headers: {
+				...Object.fromEntries(headersObj.entries()),
+				"Content-Type": "application/json",
+			},
+			body: JSON.stringify({
+				filename: processedFile.name,
+				originalName: file.name,
+				mimeType: processedFile.type,
+				size: processedFile.size,
+				url: token.payload.publicUrl,
+				folderId,
+			}),
+		});
+		if (!assetRes.ok) {
+			const err = await assetRes
+				.json()
+				.catch(() => ({ message: assetRes.statusText }));
+			throw new Error(err.message ?? "Failed to register asset");
+		}
+		return assetRes.json();
+	}
+
+	if (uploadMode === "vercel-blob") {
+		// Dynamic import keeps @vercel/blob/client optional.
+		const { upload } = await import("@vercel/blob/client");
+		const blob = await upload(processedFile.name, processedFile, {
+			access: "public",
+			handleUploadUrl: `${base}/media/upload/vercel-blob`,
+			clientPayload: JSON.stringify({
+				mimeType: processedFile.type,
+				size: processedFile.size,
+			}),
+		});
+
+		const assetRes = await fetch(`${base}/media/assets`, {
+			method: "POST",
+			headers: {
+				...Object.fromEntries(headersObj.entries()),
+				"Content-Type": "application/json",
+			},
+			body: JSON.stringify({
+				filename: processedFile.name,
+				originalName: file.name,
+				mimeType: processedFile.type,
+				size: processedFile.size,
+				url: blob.url,
+				folderId,
+			}),
+		});
+		if (!assetRes.ok) {
+			const err = await assetRes
+				.json()
+				.catch(() => ({ message: assetRes.statusText }));
+			throw new Error(err.message ?? "Failed to register asset");
+		}
+		return assetRes.json();
+	}
+
+	throw new Error(`Unknown uploadMode: ${uploadMode}`);
+}

package/src/plugins/media/client/utils/image-compression.ts

@@ -0,0 +1,131 @@
+/**
+ * Canvas-based client-side image compression.
+ *
+ * Skips SVG and GIF (vector data / animation would be lost on a canvas round-trip).
+ * All other image/* types are scaled down to fit within maxWidth × maxHeight
+ * (preserving aspect ratio) and re-encoded at the configured quality.
+ */
+
+export interface ImageCompressionOptions {
+	/**
+	 * Maximum width in pixels. Images wider than this are scaled down.
+	 * @default 2048
+	 */
+	maxWidth?: number;
+
+	/**
+	 * Maximum height in pixels. Images taller than this are scaled down.
+	 * @default 2048
+	 */
+	maxHeight?: number;
+
+	/**
+	 * Encoding quality (0–1). Applies to JPEG and WebP.
+	 * @default 0.85
+	 */
+	quality?: number;
+
+	/**
+	 * Output MIME type. Defaults to the source image's MIME type.
+	 * Set to `"image/webp"` for better compression at the cost of format change.
+	 */
+	outputFormat?: string;
+}
+
+function loadImage(file: File): Promise<HTMLImageElement> {
+	return new Promise((resolve, reject) => {
+		const url = URL.createObjectURL(file);
+		const img = new Image();
+		img.onload = () => {
+			URL.revokeObjectURL(url);
+			resolve(img);
+		};
+		img.onerror = () => {
+			URL.revokeObjectURL(url);
+			reject(new Error(`Failed to load image: ${file.name}`));
+		};
+		img.src = url;
+	});
+}
+
+const SKIP_TYPES = new Set(["image/svg+xml", "image/gif"]);
+
+/**
+ * Compresses an image file client-side using the Canvas API.
+ *
+ * Returns the original file unchanged if:
+ * - The file is not an image
+ * - The MIME type is SVG or GIF (would lose vector data / animation)
+ * - The browser does not support canvas (SSR guard)
+ */
+export async function compressImage(
+	file: File,
+	options: ImageCompressionOptions = {},
+): Promise<File> {
+	if (!file.type.startsWith("image/") || SKIP_TYPES.has(file.type)) {
+		return file;
+	}
+
+	// SSR guard — canvas is only available in the browser
+	if (typeof document === "undefined") return file;
+
+	const {
+		maxWidth = 2048,
+		maxHeight = 2048,
+		quality = 0.85,
+		outputFormat,
+	} = options;
+
+	const img = await loadImage(file);
+
+	let { width, height } = img;
+
+	const needsResize = width > maxWidth || height > maxHeight;
+	const needsFormatChange =
+		outputFormat !== undefined && outputFormat !== file.type;
+
+	// Skip canvas entirely if the image is already within the limits and no
+	// format conversion is needed — re-encoding a small image can make it larger.
+	if (!needsResize && !needsFormatChange) return file;
+
+	// Scale down proportionally if either dimension exceeds the max
+	if (needsResize) {
+		const ratio = Math.min(maxWidth / width, maxHeight / height);
+		width = Math.round(width * ratio);
+		height = Math.round(height * ratio);
+	}
+
+	const canvas = document.createElement("canvas");
+	canvas.width = width;
+	canvas.height = height;
+
+	const ctx = canvas.getContext("2d");
+	if (!ctx) return file;
+
+	ctx.drawImage(img, 0, 0, width, height);
+
+	const mimeType = outputFormat ?? file.type;
+
+	return new Promise<File>((resolve, reject) => {
+		canvas.toBlob(
+			(blob) => {
+				if (!blob) {
+					reject(new Error("canvas.toBlob returned null"));
+					return;
+				}
+
+				// Preserve the original filename, updating extension only if
+				// the output format changed from the source.
+				let name = file.name;
+				if (outputFormat && outputFormat !== file.type) {
+					const ext = outputFormat.split("/")[1] ?? "jpg";
+					name = name.replace(/\.[^.]+$/, `.${ext}`);
+				}
+
+				resolve(new File([blob], name, { type: mimeType }));
+			},
+			mimeType,
+			quality,
+		);
+	});
+}

package/src/plugins/media/client.css

@@ -0,0 +1 @@
+/* Media plugin client styles — included in consumer CSS via @import "@btst/stack/plugins/media/css" */

package/src/plugins/media/db.ts

@@ -0,0 +1,62 @@
+import { createDbPlugin } from "@btst/db";
+
+/**
+ * Media plugin schema
+ * Defines the database tables for media assets and folders
+ */
+export const mediaSchema = createDbPlugin("media", {
+	asset: {
+		modelName: "mediaAsset",
+		fields: {
+			filename: {
+				type: "string",
+				required: true,
+			},
+			originalName: {
+				type: "string",
+				required: true,
+			},
+			mimeType: {
+				type: "string",
+				required: true,
+			},
+			size: {
+				type: "number",
+				required: true,
+			},
+			url: {
+				type: "string",
+				required: true,
+			},
+			folderId: {
+				type: "string",
+				required: false,
+			},
+			alt: {
+				type: "string",
+				required: false,
+			},
+			createdAt: {
+				type: "date",
+				defaultValue: () => new Date(),
+			},
+		},
+	},
+	folder: {
+		modelName: "mediaFolder",
+		fields: {
+			name: {
+				type: "string",
+				required: true,
+			},
+			parentId: {
+				type: "string",
+				required: false,
+			},
+			createdAt: {
+				type: "date",
+				defaultValue: () => new Date(),
+			},
+		},
+	},
+});

package/src/plugins/media/query-keys.ts

@@ -0,0 +1,96 @@
+import {
+	mergeQueryKeys,
+	createQueryKeys,
+} from "@lukemorales/query-key-factory";
+import { createApiClient } from "@btst/stack/plugins/client";
+import type { MediaApiRouter } from "./api/plugin";
+import type { SerializedAsset, SerializedFolder } from "./types";
+import { assetListDiscriminator } from "./api/query-key-defs";
+import type { AssetListParams } from "./api/getters";
+
+function isErrorResponse(response: unknown): response is { error: unknown } {
+	return (
+		typeof response === "object" &&
+		response !== null &&
+		"error" in response &&
+		(response as Record<string, unknown>).error !== null &&
+		(response as Record<string, unknown>).error !== undefined
+	);
+}
+
+function toError(error: unknown): Error {
+	if (error instanceof Error) return error;
+	if (typeof error === "object" && error !== null) {
+		const errorObj = error as Record<string, unknown>;
+		const message =
+			(typeof errorObj.message === "string" ? errorObj.message : null) ||
+			JSON.stringify(error);
+		const err = new Error(message);
+		Object.assign(err, error);
+		return err;
+	}
+	return new Error(String(error));
+}
+
+export function createMediaQueryKeys(
+	client: ReturnType<typeof createApiClient<MediaApiRouter>>,
+	headers?: HeadersInit,
+) {
+	return mergeQueryKeys(
+		createQueryKeys("mediaAssets", {
+			list: (params?: AssetListParams) => ({
+				queryKey: [assetListDiscriminator(params)],
+				queryFn: async ({ pageParam }: { pageParam?: number }) => {
+					const response = await (client as any)("/media/assets", {
+						method: "GET",
+						query: {
+							folderId: params?.folderId,
+							mimeType: params?.mimeType,
+							query: params?.query,
+							offset: pageParam ?? params?.offset ?? 0,
+							limit: params?.limit ?? 20,
+						},
+						headers,
+					});
+					if (isErrorResponse(response)) throw toError(response.error);
+					const data = (response as any).data as {
+						items: SerializedAsset[];
+						total: number;
+						limit?: number;
+						offset?: number;
+					};
+					return data;
+				},
+			}),
+			detail: (id: string) => ({
+				queryKey: [id],
+				queryFn: async () => {
+					const response = await (client as any)("/media/assets", {
+						method: "GET",
+						query: { id },
+						headers,
+					});
+					if (isErrorResponse(response)) throw toError(response.error);
+					return (response as any).data as SerializedAsset | null;
+				},
+			}),
+		}),
+		createQueryKeys("mediaFolders", {
+			list: (parentId?: string | null) => ({
+				queryKey: [parentId ?? "root"],
+				queryFn: async () => {
+					const response = await (client as any)("/media/folders", {
+						method: "GET",
+						query:
+							parentId !== undefined ? { parentId: parentId ?? undefined } : {},
+						headers,
+					});
+					if (isErrorResponse(response)) throw toError(response.error);
+					return (response as any).data as SerializedFolder[];
+				},
+			}),
+		}),
+	);
+}
+
+export type MediaQueryKeys = ReturnType<typeof createMediaQueryKeys>;

package/src/plugins/media/schemas.ts

@@ -0,0 +1,37 @@
+import { z } from "zod";
+
+export const AssetListQuerySchema = z.object({
+	folderId: z.string().optional(),
+	mimeType: z.string().optional(),
+	query: z.string().optional(),
+	offset: z.coerce.number().int().min(0).optional(),
+	limit: z.coerce.number().int().min(1).max(100).optional(),
+});
+
+export const createAssetSchema = z.object({
+	filename: z.string().min(1),
+	originalName: z.string().min(1),
+	mimeType: z.string().min(1),
+	// Allow 0 for URL-registered assets where size is unknown at registration time.
+	size: z.number().int().min(0),
+	url: z.httpUrl(),
+	folderId: z.string().optional(),
+	alt: z.string().optional(),
+});
+
+export const updateAssetSchema = z.object({
+	alt: z.string().optional(),
+	folderId: z.string().nullable().optional(),
+});
+
+export const createFolderSchema = z.object({
+	name: z.string().min(1),
+	parentId: z.string().optional(),
+});
+
+export const uploadTokenRequestSchema = z.object({
+	filename: z.string().min(1),
+	mimeType: z.string().min(1),
+	size: z.number().int().positive(),
+	folderId: z.string().optional(),
+});

package/src/plugins/media/style.css

@@ -0,0 +1 @@
+@source "./client/**/*.{ts,tsx}";