@btst/stack 3.0.0-rc.2 → 3.0.0-rc.4

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

@@ -1,21 +1,42 @@
 import {
-	defineClientPlugin,
 	createApiClient,
+	createSanitizedSSRLoaderError,
+	defineClientPlugin,
 	isConnectionError,
+	type ResolvedClientPluginRuntime,
 } from "@btst/stack/plugins/client";
+import { normalizePath } from "@btst/stack/client";
 import { defineRoute, defineRoutes } 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 { lazy, type ComponentType } from "react";
 import type { MediaApiRouter } from "../api/plugin";
-
+import type { MediaIdentityPartition } from "../api/query-key-defs";
+import { createMediaQueryKeys } from "../query-keys";
+import { MEDIA_PLUGIN_ID } from "./constants";
+import type {
+	MediaPluginOverrides,
+	MediaProviderConfig,
+	MediaUploadMode,
+} from "./overrides";
+
+const LibraryPageComponent = lazy(() =>
+	import("./components/pages/library-page").then((module) => ({
+		default: module.LibraryPageComponent,
+	})),
+);
+
+/** Resolved request context supplied to Media SSR loader hooks. */
 export interface MediaLoaderContext {
+	/** Normalized Media route path being loaded. */
 	path: string;
+	/** Whether the hook is running during server-side rendering. */
 	isSSR: boolean;
+	/** Resolved absolute origin for the Media backend. */
 	apiBaseURL: string;
+	/** Resolved path where the Media backend is mounted. */
 	apiBasePath: string;
-	headers?: HeadersInit;
+	/** Request-scoped server headers used by the Media SSR loader. */
+	headers?: Headers;
 }
 
 export interface MediaClientHooks {
@@ -25,141 +46,165 @@ export interface MediaClientHooks {
 	/** 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?: (
+	/**
+	 * Reports an SSR loader failure once. Callback failures are contained and
+	 * cannot make the loader reject.
+	 */
+	onErrorLoad?: (
 		error: Error,
 		context: MediaLoaderContext,
 	) => Promise<void> | void;
 }
 
+/**
+ * Media-specific client configuration. Shared API, site, query-client, and
+ * request-header values are inherited from `createClientStack()`.
+ */
 export interface MediaClientConfig {
-	/** Base URL for API calls (e.g., "http://localhost:3000") */
+	/** Upload transport matching the storage adapter configured on the backend. */
+	uploadMode?: MediaUploadMode;
+	/** Identity snapshot used to align protected SSR prefetch and browser keys. */
+	identityPartition?: MediaIdentityPartition;
+	/** Optional lifecycle hooks for the media client plugin. */
+	hooks?: MediaClientHooks;
+	/** Optional replacement for the media library page. */
+	pageComponents?: {
+		library?: ComponentType;
+	};
+}
+
+interface ResolvedMediaClientConfig extends MediaClientConfig {
 	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;
-	};
+	headers?: Headers;
+	credentials?: RequestCredentials;
 }
 
-/**
- * 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",
+function resolveMediaClientConfig(
+	config: MediaClientConfig,
+	runtime: ResolvedClientPluginRuntime<typeof MEDIA_PLUGIN_ID>,
+): ResolvedMediaClientConfig {
+	return {
+		uploadMode: config.uploadMode,
+		identityPartition: config.identityPartition,
+		hooks: config.hooks,
+		pageComponents: config.pageComponents,
+		apiBaseURL: runtime.api.baseURL,
+		apiBasePath: runtime.api.basePath,
+		siteBaseURL: runtime.site.baseURL,
+		siteBasePath: runtime.site.basePath,
+		queryClient: runtime.queryClient,
+		...(runtime.api.headers ? { headers: runtime.api.headers } : {}),
+		...(runtime.api.credentials
+			? { credentials: runtime.api.credentials }
+			: {}),
+	};
+}
 
-		routes: () =>
-			defineRoutes(
-				{
-					library: defineRoute("/media", {
-						page: LibraryPageComponent,
-						loader: createMediaLibraryLoader(config),
-						meta: createMediaLibraryMeta(config),
-					}),
-				},
-				{ pages: config.pageComponents },
-			),
+function createMediaApiClient(config: ResolvedMediaClientConfig) {
+	return createApiClient<MediaApiRouter>({
+		baseURL: config.apiBaseURL,
+		basePath: config.apiBasePath,
+		headers: config.headers,
+		credentials: config.credentials,
 	});
+}
 
-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);
+function createLoadErrorReporter(
+	hooks: MediaClientHooks | undefined,
+	context: MediaLoaderContext,
+) {
+	let reported = false;
+	return async (error: unknown) => {
+		if (reported || !hooks?.onErrorLoad) return;
+		reported = true;
+		try {
+			await hooks.onErrorLoad(
+				error instanceof Error ? error : new Error(String(error)),
+				context,
+			);
+		} catch {
+			// Reporting hooks cannot make an SSR loader reject or report twice.
+		}
+	};
+}
 
-				// Prefetch initial asset grid (infinite query — root folder, default limit)
+function createMediaLibraryLoader(config: ResolvedMediaClientConfig) {
+	return async () => {
+		if (typeof window !== "undefined") return;
+
+		const {
+			queryClient,
+			apiBasePath,
+			apiBaseURL,
+			hooks,
+			headers,
+			identityPartition,
+		} = config;
+		const context: MediaLoaderContext = {
+			path: "/media",
+			isSSR: true,
+			apiBaseURL,
+			apiBasePath,
+			headers,
+		};
+		const reportError = createLoadErrorReporter(hooks, context);
+		const queries = createMediaQueryKeys(createMediaApiClient(config));
+		const endpointPartition = { baseURL: apiBaseURL, basePath: apiBasePath };
+		const assetQuery = queries.mediaAssets.list(
+			{ limit: 40 },
+			identityPartition,
+			endpointPartition,
+		);
+		const folderQuery = queries.mediaFolders.list(
+			undefined,
+			identityPartition,
+			endpointPartition,
+		);
+
+		try {
+			await hooks?.beforeLoadLibrary?.(context);
+			await queryClient.prefetchInfiniteQuery({
+				...assetQuery,
+				initialPageParam: 0,
+			});
+			await queryClient.prefetchQuery(folderQuery);
+			await hooks?.afterLoadLibrary?.(context);
+
+			const queryError =
+				queryClient.getQueryState(assetQuery.queryKey)?.error ??
+				queryClient.getQueryState(folderQuery.queryKey)?.error;
+			if (queryError) await reportError(queryError);
+		} catch (error) {
+			if (isConnectionError(error)) {
+				console.warn(
+					"[btst/media] route.loader() failed — no server running at build time. " +
+						"For an explicitly public static library, use the explicit " +
+						"stack.raw.media.prefetchForRoute() server helper instead.",
+				);
+			} else {
+				const sanitizedError = createSanitizedSSRLoaderError();
 				await queryClient.prefetchInfiniteQuery({
-					...queries.mediaAssets.list({ limit: 40 }),
+					queryKey: assetQuery.queryKey,
+					queryFn: () => {
+						throw sanitizedError;
+					},
 					initialPageParam: 0,
+					retry: false,
 				});
-
-				// 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);
-				}
 			}
+			await reportError(error);
 		}
 	};
 }
 
-function createMediaLibraryMeta(config: MediaClientConfig) {
+function createMediaLibraryMeta(config: ResolvedMediaClientConfig) {
 	return () => {
-		const { siteBaseURL, siteBasePath } = config;
-		const fullUrl = `${siteBaseURL}${siteBasePath}/media`;
+		const sitePath = normalizePath([config.siteBasePath, "/media"].join("/"));
+		const fullUrl = `${config.siteBaseURL}${sitePath}`;
 		const title = "Media Library";
 
 		return [
@@ -167,19 +212,39 @@ function createMediaLibraryMeta(config: MediaClientConfig) {
 			{ 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:description", content: "Manage your media assets" },
 			{ property: "og:url", content: fullUrl },
-
-			// Twitter
 			{ name: "twitter:card", content: "summary" },
 			{ name: "twitter:title", content: title },
 		];
 	};
 }
+
+function createResolvedMediaPlugin(config: ResolvedMediaClientConfig) {
+	return {
+		routes: () =>
+			defineRoutes(
+				{
+					library: defineRoute("/media", {
+						page: LibraryPageComponent,
+						loader: createMediaLibraryLoader(config),
+						meta: createMediaLibraryMeta(config),
+					}),
+				},
+				{ pages: config.pageComponents },
+			),
+	};
+}
+
+/** Registers the Media library against the enclosing resolved client runtime. */
+export const mediaClientPlugin = (config: MediaClientConfig = {}) =>
+	defineClientPlugin<MediaPluginOverrides>()({
+		id: MEDIA_PLUGIN_ID,
+		providerConfig: {
+			...(config.uploadMode ? { uploadMode: config.uploadMode } : {}),
+		} satisfies MediaProviderConfig,
+		resolve: (runtime) =>
+			createResolvedMediaPlugin(resolveMediaClientConfig(config, runtime)),
+	});

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

@@ -1,18 +1,50 @@
 "use client";
 
+import { normalizePath } from "@btst/stack/client";
 import type { SerializedAsset } from "../types";
-import type { MediaUploadMode } from "./overrides";
+import type { MediaProviderConfig, MediaUploadMode } from "./overrides";
+import { resolveMediaAsset } from "../asset-url";
 import { compressImage } from "./utils/image-compression";
 import type { ImageCompressionOptions } from "./utils/image-compression";
 
+/** Transport and preprocessing options for an imperative Media upload. */
 export interface MediaUploadClientConfig {
+	/** Resolved Media API base URL. */
 	apiBaseURL: string;
+	/** Mount path of the resolved Media API endpoint. */
 	apiBasePath: string;
+	/** Browser-safe headers sent with Media API requests. Never include secrets. */
 	headers?: HeadersInit;
+	/**
+	 * Fetch credentials mode applied only to Media API requests.
+	 * Configure this explicitly when a cross-origin Media endpoint accepts
+	 * browser credentials. It is not forwarded to storage upload URLs and does
+	 * not make server-only headers safe to expose.
+	 */
+	credentials?: RequestCredentials;
+	/** Upload transport matching the backend Media storage adapter. Defaults to `"direct"`. */
 	uploadMode?: MediaUploadMode;
+	/** Client-side image compression options, or `false` to skip compression. */
 	imageCompression?: ImageCompressionOptions | false;
 }
 
+/** Browser-safe Media runtime exposed as `stack.provider.plugins.media`. */
+export interface MediaUploadProviderRuntime {
+	/** Resolved browser transport for the Media API. */
+	readonly api: {
+		/** Resolved Media API base URL. */
+		readonly baseURL: string;
+		/** Media API mount path. */
+		readonly basePath: string;
+		/** Explicitly public headers safe to expose to browser code. */
+		readonly browserHeaders?: HeadersInit;
+		/** Explicit browser Fetch credentials behavior. */
+		readonly credentials?: RequestCredentials;
+	};
+	/** Browser-safe Media factory configuration. */
+	readonly config?: MediaProviderConfig;
+}
+
 export interface UploadAssetInput {
 	file: File;
 	folderId?: string;
@@ -24,6 +56,31 @@ const DEFAULT_IMAGE_COMPRESSION = {
 	quality: 0.85,
 } as const;
 
+/**
+ * Bind imperative uploads to the Media endpoint resolved by `createClientStack`.
+ */
+export function createMediaUploadConfig(
+	runtime: MediaUploadProviderRuntime,
+	overrides: Pick<MediaUploadClientConfig, "imageCompression"> = {},
+): MediaUploadClientConfig {
+	return {
+		apiBaseURL: runtime.api.baseURL,
+		apiBasePath: runtime.api.basePath,
+		headers: runtime.api.browserHeaders,
+		credentials: runtime.api.credentials,
+		uploadMode: runtime.config?.uploadMode ?? "direct",
+		...overrides,
+	};
+}
+
+function createMediaApiURL(
+	apiBaseURL: string,
+	apiBasePath: string,
+	path: string,
+): string {
+	return `${apiBaseURL}${normalizePath([apiBasePath, path].join("/"))}`;
+}
+
 /**
  * Upload an asset using the media plugin's configured storage mode.
  *
@@ -39,6 +96,7 @@ export async function uploadAsset(
 		apiBaseURL,
 		apiBasePath,
 		headers,
+		credentials,
 		uploadMode = "direct",
 		imageCompression,
 	} = config;
@@ -52,7 +110,6 @@ export async function uploadAsset(
 					imageCompression ?? DEFAULT_IMAGE_COMPRESSION,
 				);
 
-	const base = `${apiBaseURL}${apiBasePath}`;
 	const headersObj = new Headers(headers as HeadersInit | undefined);
 
 	if (uploadMode === "direct") {
@@ -60,32 +117,40 @@ export async function uploadAsset(
 		formData.append("file", processedFile);
 		if (folderId) formData.append("folderId", folderId);
 
-		const res = await fetch(`${base}/media/upload`, {
-			method: "POST",
-			headers: headersObj,
-			body: formData,
-		});
+		const res = await fetch(
+			createMediaApiURL(apiBaseURL, apiBasePath, "/media/upload"),
+			{
+				method: "POST",
+				headers: headersObj,
+				credentials,
+				body: formData,
+			},
+		);
 		if (!res.ok) {
 			const err = await res.json().catch(() => ({ message: res.statusText }));
 			throw new Error(err.message ?? "Upload failed");
 		}
-		return res.json();
+		return resolveMediaAsset((await res.json()) as SerializedAsset, apiBaseURL);
 	}
 
 	if (uploadMode === "s3") {
-		const tokenRes = await fetch(`${base}/media/upload/token`, {
-			method: "POST",
-			headers: {
-				...Object.fromEntries(headersObj.entries()),
-				"Content-Type": "application/json",
+		const tokenRes = await fetch(
+			createMediaApiURL(apiBaseURL, apiBasePath, "/media/upload/token"),
+			{
+				method: "POST",
+				headers: {
+					...Object.fromEntries(headersObj.entries()),
+					"Content-Type": "application/json",
+				},
+				credentials,
+				body: JSON.stringify({
+					filename: processedFile.name,
+					mimeType: processedFile.type,
+					size: processedFile.size,
+					folderId,
+				}),
 			},
-			body: JSON.stringify({
-				filename: processedFile.name,
-				mimeType: processedFile.type,
-				size: processedFile.size,
-				folderId,
-			}),
-		});
+		);
 		if (!tokenRes.ok) {
 			const err = await tokenRes
 				.json()
@@ -111,64 +176,116 @@ export async function uploadAsset(
 		});
 		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",
+		const assetRes = await fetch(
+			createMediaApiURL(apiBaseURL, apiBasePath, "/media/assets"),
+			{
+				method: "POST",
+				headers: {
+					...Object.fromEntries(headersObj.entries()),
+					"Content-Type": "application/json",
+				},
+				credentials,
+				body: JSON.stringify({
+					filename: processedFile.name,
+					originalName: file.name,
+					mimeType: processedFile.type,
+					size: processedFile.size,
+					url: token.payload.publicUrl,
+					folderId,
+				}),
 			},
-			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();
+		return resolveMediaAsset(
+			(await assetRes.json()) as SerializedAsset,
+			apiBaseURL,
+		);
 	}
 
 	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 handleUploadUrl = createMediaApiURL(
+			apiBaseURL,
+			apiBasePath,
+			"/media/upload/vercel-blob",
+		);
+		const clientPayload = JSON.stringify({
+			mimeType: processedFile.type,
+			size: processedFile.size,
+			...(folderId ? { folderId } : {}),
 		});
-
-		const assetRes = await fetch(`${base}/media/assets`, {
+		const tokenRes = await fetch(handleUploadUrl, {
 			method: "POST",
 			headers: {
 				...Object.fromEntries(headersObj.entries()),
 				"Content-Type": "application/json",
 			},
+			credentials,
 			body: JSON.stringify({
-				filename: processedFile.name,
-				originalName: file.name,
-				mimeType: processedFile.type,
-				size: processedFile.size,
-				url: blob.url,
-				folderId,
+				type: "blob.generate-client-token",
+				payload: {
+					pathname: processedFile.name,
+					callbackUrl: handleUploadUrl,
+					clientPayload,
+					multipart: false,
+				},
 			}),
 		});
+		if (!tokenRes.ok) {
+			const err = await tokenRes
+				.json()
+				.catch(() => ({ message: tokenRes.statusText }));
+			throw new Error(err.message ?? "Failed to get Vercel Blob upload token");
+		}
+		const { clientToken } = (await tokenRes.json()) as {
+			clientToken?: string;
+		};
+		if (!clientToken) {
+			throw new Error("Failed to get Vercel Blob upload token");
+		}
+
+		// Dynamic import keeps @vercel/blob/client optional. The app-authenticated
+		// token exchange stays under our fetch control; the scoped token alone is
+		// then sent to Vercel's storage origin.
+		const { put } = await import("@vercel/blob/client");
+		const blob = await put(processedFile.name, processedFile, {
+			access: "public",
+			token: clientToken,
+		});
+
+		const assetRes = await fetch(
+			createMediaApiURL(apiBaseURL, apiBasePath, "/media/assets"),
+			{
+				method: "POST",
+				headers: {
+					...Object.fromEntries(headersObj.entries()),
+					"Content-Type": "application/json",
+				},
+				credentials,
+				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();
+		return resolveMediaAsset(
+			(await assetRes.json()) as SerializedAsset,
+			apiBaseURL,
+		);
 	}
 
 	throw new Error(`Unknown uploadMode: ${uploadMode}`);