@btst/stack 2.12.2 → 3.0.0-rc.2

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

@@ -1,4 +1,3 @@
-import type { ComponentType } from "react";
 import type { QueryClient } from "@tanstack/react-query";
 import type { ImageCompressionOptions } from "./utils/image-compression";
 
@@ -17,16 +16,6 @@ export type MediaUploadMode = "direct" | "s3" | "vercel-blob";
  * via the StackProvider overrides.
  */
 export interface MediaPluginOverrides {
-	/**
-	 * Base URL for API calls (e.g., "http://localhost:3000").
-	 */
-	apiBaseURL: string;
-
-	/**
-	 * Path where the API is mounted (e.g., "/api/data").
-	 */
-	apiBasePath: string;
-
 	/**
 	 * React Query client — used by the MediaPicker to cache and fetch assets.
 	 */
@@ -43,32 +32,6 @@ export interface MediaPluginOverrides {
 	 */
 	headers?: HeadersInit;
 
-	/**
-	 * Navigation function for programmatic navigation.
-	 */
-	navigate: (path: string) => void | Promise<void>;
-
-	/**
-	 * Link component for navigation within the media library page.
-	 */
-	Link?: ComponentType<React.ComponentProps<"a"> & Record<string, any>>;
-
-	/**
-	 * Image component for rendering asset thumbnails and previews.
-	 *
-	 * When provided, replaces the default `<img>` element in asset cards,
-	 * the media library grid, and the ImageInputField preview. Use this
-	 * to plug in Next.js `<Image>` for automatic optimisation.
-	 *
-	 * @example
-	 * ```tsx
-	 * Image: (props) => <NextImage {...props} />
-	 * ```
-	 */
-	Image?: ComponentType<
-		React.ImgHTMLAttributes<HTMLImageElement> & Record<string, any>
-	>;
-
 	/**
 	 * Client-side image compression applied before upload via the Canvas API.
 	 *
@@ -100,20 +63,6 @@ export interface MediaPluginOverrides {
 		error: Error,
 		context: MediaRouteContext,
 	) => void | Promise<void>;
-
-	/**
-	 * Called before the media library page is rendered.
-	 * Return `false` to prevent rendering (e.g., redirect unauthenticated users).
-	 *
-	 * @example
-	 * ```ts
-	 * media: {
-	 *   onBeforeLibraryPageRendered: (context) => !!currentUser?.isAdmin,
-	 *   onRouteError: (routeName, error, context) => navigate("/login"),
-	 * }
-	 * ```
-	 */
-	onBeforeLibraryPageRendered?: (context: MediaRouteContext) => boolean;
 }
 
 export interface MediaRouteContext {

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

@@ -3,7 +3,7 @@ import {
 	createApiClient,
 	isConnectionError,
 } from "@btst/stack/plugins/client";
-import { createRoute } from "@btst/yar";
+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";
@@ -81,16 +81,17 @@ 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),
-				};
-			}),
-		}),
+		routes: () =>
+			defineRoutes(
+				{
+					library: defineRoute("/media", {
+						page: LibraryPageComponent,
+						loader: createMediaLibraryLoader(config),
+						meta: createMediaLibraryMeta(config),
+					}),
+				},
+				{ pages: config.pageComponents },
+			),
 	});
 
 function createMediaLibraryLoader(config: MediaClientConfig) {

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

@@ -1,13 +1,17 @@
 "use client";
 
 import type { SerializedAsset } from "../types";
-import type { MediaPluginOverrides } from "./overrides";
+import type { MediaUploadMode } from "./overrides";
 import { compressImage } from "./utils/image-compression";
-
-export type MediaUploadClientConfig = Pick<
-	MediaPluginOverrides,
-	"apiBaseURL" | "apiBasePath" | "headers" | "uploadMode" | "imageCompression"
->;
+import type { ImageCompressionOptions } from "./utils/image-compression";
+
+export interface MediaUploadClientConfig {
+	apiBaseURL: string;
+	apiBasePath: string;
+	headers?: HeadersInit;
+	uploadMode?: MediaUploadMode;
+	imageCompression?: ImageCompressionOptions | false;
+}
 
 export interface UploadAssetInput {
 	file: File;

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

@@ -1,96 +1,147 @@
 import {
-	mergeQueryKeys,
-	createQueryKeys,
-} from "@lukemorales/query-key-factory";
-import { createApiClient } from "@btst/stack/plugins/client";
+	createApiClient,
+	createResourceQueryKeys,
+	type ResourcesDeclaration,
+} 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";
+import {
+	assetListDiscriminator,
+	folderListDiscriminator,
+} from "./api/query-key-defs";
+import { ROOT_FOLDER_QUERY_VALUE } from "./schemas";
+import type { SerializedAsset, SerializedFolder } from "./types";
 
-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
-	);
+export interface RegisterAssetInput {
+	url: string;
+	filename: string;
+	mimeType?: string;
+	size?: number;
+	folderId?: string;
 }
 
-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 interface CreateMediaFolderInput {
+	name: string;
+	parentId?: string;
 }
 
-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 {
+function normalizeSearch(query: string | undefined): string | undefined {
+	const normalized = query?.trim();
+	return normalized || undefined;
+}
+
+function paginatedNextPageParam(
+	lastPage: { items?: unknown[]; total?: number },
+	allPages: { items?: unknown[] }[],
+): number | undefined {
+	const items = Array.isArray(lastPage.items) ? lastPage.items : [];
+	const loadedCount = allPages.reduce(
+		(sum, page) => sum + (Array.isArray(page.items) ? page.items.length : 0),
+		0,
+	);
+	return loadedCount < (lastPage.total ?? 0) && items.length > 0
+		? loadedCount
+		: undefined;
+}
+
+/**
+ * Media resource declaration — the single source of truth for HTTP mappings,
+ * query keys, pagination, and JSON mutations. File uploads stay on the custom
+ * upload transport because direct, S3, and Vercel Blob use different flows.
+ */
+export const mediaResources = {
+	mediaAssets: {
+		queries: {
+			list: {
+				path: "/media/assets",
+				query: (params: AssetListParams = {}) => ({
+					folderId: params.folderId,
+					mimeType: params.mimeType,
+					query: normalizeSearch(params.query),
+					limit: params.limit ?? 20,
+				}),
+				key: (params: AssetListParams = {}) => [assetListDiscriminator(params)],
+				select: (data: 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[];
-				},
-			}),
-		}),
-	);
+					},
+				infinite: true,
+				pageSize: (params: AssetListParams = {}) => params.limit ?? 20,
+				nextPageParam: paginatedNextPageParam,
+			},
+		},
+		mutations: {
+			create: {
+				path: "@post/media/assets",
+				method: "POST" as const,
+				input: (input: RegisterAssetInput) => ({
+					body: {
+						filename: input.filename,
+						originalName: input.filename,
+						mimeType: input.mimeType ?? "application/octet-stream",
+						size: input.size ?? 0,
+						url: input.url,
+						folderId: input.folderId,
+					},
+				}),
+				select: (data: any) => data as SerializedAsset,
+				invalidates: ["mediaAssets.list"],
+				refetchType: "all",
+				refresh: false,
+			},
+			delete: {
+				path: "@delete/media/assets/:id",
+				method: "DELETE" as const,
+				input: (id: string) => ({ params: { id } }),
+				select: (data: any) => data as { success: boolean },
+				invalidates: ["mediaAssets.list"],
+				refetchType: "all",
+				refresh: false,
+			},
+		},
+	},
+
+	mediaFolders: {
+		queries: {
+			list: {
+				path: "/media/folders",
+				query: (parentId?: string | null) =>
+					parentId === undefined
+						? {}
+						: { parentId: parentId ?? ROOT_FOLDER_QUERY_VALUE },
+				key: (parentId?: string | null) => [folderListDiscriminator(parentId)],
+				select: (data: any) => data as SerializedFolder[],
+			},
+		},
+		mutations: {
+			create: {
+				path: "@post/media/folders",
+				method: "POST" as const,
+				input: (input: CreateMediaFolderInput) => ({ body: input }),
+				select: (data: any) => data as SerializedFolder,
+				invalidates: ["mediaFolders.list"],
+				refresh: false,
+			},
+			delete: {
+				path: "@delete/media/folders/:id",
+				method: "DELETE" as const,
+				input: (id: string) => ({ params: { id } }),
+				select: (data: any) => data as { success: boolean },
+				invalidates: ["mediaFolders.list"],
+				refresh: false,
+			},
+		},
+	},
+} satisfies ResourcesDeclaration;
+
+export function createMediaQueryKeys(
+	client: ReturnType<typeof createApiClient<MediaApiRouter>>,
+	headers?: HeadersInit,
+) {
+	return createResourceQueryKeys(client, mediaResources, headers);
 }
 
 export type MediaQueryKeys = ReturnType<typeof createMediaQueryKeys>;

package/src/plugins/media/schemas.ts

@@ -3,11 +3,26 @@ import { z } from "zod";
 export const AssetListQuerySchema = z.object({
 	folderId: z.string().optional(),
 	mimeType: z.string().optional(),
-	query: z.string().optional(),
+	query: z
+		.string()
+		.max(200)
+		.transform((value) => value.trim() || undefined)
+		.optional(),
 	offset: z.coerce.number().int().min(0).optional(),
 	limit: z.coerce.number().int().min(1).max(100).optional(),
 });
 
+/** HTTP-only sentinel that distinguishes root folders from an unfiltered list. */
+export const ROOT_FOLDER_QUERY_VALUE = "__root__";
+
+export const FolderListQuerySchema = z
+	.object({
+		parentId: z.string().optional(),
+	})
+	.transform(({ parentId }) => ({
+		parentId: parentId === ROOT_FOLDER_QUERY_VALUE ? null : parentId,
+	}));
+
 export const createAssetSchema = z.object({
 	filename: z.string().min(1),
 	originalName: z.string().min(1),

package/src/plugins/route-docs/client/plugin.tsx

@@ -1,6 +1,6 @@
 import { lazy } from "react";
 import { defineClientPlugin } from "@btst/stack/plugins/client";
-import { createRoute } from "@btst/yar";
+import { defineRoute } from "@btst/yar";
 import type { QueryClient } from "@tanstack/react-query";
 import type { ClientStackContext } from "../../../types";
 import {
@@ -204,20 +204,18 @@ export const routeDocsClientPlugin = (config: RouteDocsClientConfig) => {
 			moduleStoredContext = context || null;
 
 			return {
-				docs: createRoute("/route-docs", () => {
-					return {
-						PageComponent: () => (
-							<DocsPageComponent
-								title={config.title}
-								description={config.description}
-								siteBasePath={config.siteBasePath || "/pages"}
-							/>
-						),
-						LoadingComponent: () => <DocsPageSkeleton />,
-						ErrorComponent: () => <DocsErrorComponent />,
-						loader: createRouteDocsLoader(config),
-						meta: createDocsMeta(config),
-					};
+				docs: defineRoute("/route-docs", {
+					page: () => (
+						<DocsPageComponent
+							title={config.title}
+							description={config.description}
+							siteBasePath={config.siteBasePath || "/pages"}
+						/>
+					),
+					loading: DocsPageSkeleton,
+					error: DocsErrorComponent,
+					loader: createRouteDocsLoader(config),
+					meta: createDocsMeta(config),
 				}),
 			};
 		},