@btst/stack 2.9.4 → 2.11.0

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

@@ -15,6 +15,7 @@ import {
 	getAssetById,
 	listFolders,
 	getFolderById,
+	getFolderByName,
 } from "./getters";
 import {
 	createAsset,
@@ -187,6 +188,26 @@ export interface MediaBackendConfig {
 	 * Optional lifecycle hooks for the media backend plugin.
 	 */
 	hooks?: MediaBackendHooks;
+
+	/**
+	 * Optional function to resolve a tenant ID from the incoming request context.
+	 *
+	 * When provided, all asset and folder list/create operations through the HTTP
+	 * API are automatically scoped to the returned tenant ID:
+	 * - GET /media/assets  →  filters results to the resolved tenant
+	 * - POST /media/assets →  tags the created asset with the resolved tenant
+	 * - POST /media/upload →  tags the uploaded asset with the resolved tenant
+	 * - GET /media/folders →  filters results to the resolved tenant
+	 * - POST /media/folders → tags the created folder with the resolved tenant
+	 *
+	 * When absent, no tenant filtering is applied (existing behaviour).
+	 *
+	 * Returning `null` or `undefined` means "no tenant" for this request —
+	 * the operation proceeds without tenant scoping (useful for super-admin routes).
+	 */
+	resolveTenantId?: (
+		context: MediaApiContext,
+	) => Promise<string | null | undefined> | string | null | undefined;
 }
 
 /**
@@ -222,6 +243,11 @@ export const mediaBackendPlugin = (config: MediaBackendConfig) =>
 			listFolders: (params?: Parameters<typeof listFolders>[1]) =>
 				listFolders(adapter, params),
 			getFolderById: (id: string) => getFolderById(adapter, id),
+			getFolderByName: (
+				name: string,
+				parentId?: string | null,
+				tenantId?: string,
+			) => getFolderByName(adapter, name, parentId, tenantId),
 		}),
 
 		routes: (adapter: Adapter) => {
@@ -231,6 +257,7 @@ export const mediaBackendPlugin = (config: MediaBackendConfig) =>
 				allowedMimeTypes,
 				allowedUrlPrefixes,
 				hooks,
+				resolveTenantId,
 			} = config;
 
 			function validateMimeType(mimeType: string, ctx: { error: Function }) {
@@ -261,6 +288,10 @@ export const mediaBackendPlugin = (config: MediaBackendConfig) =>
 					const { query, headers } = ctx;
 					const context: MediaApiContext = { query, headers };
 
+					const tenantId = resolveTenantId
+						? ((await resolveTenantId(context)) ?? undefined)
+						: undefined;
+
 					if (hooks?.onBeforeListAssets) {
 						await runHookWithShim(
 							() => hooks.onBeforeListAssets!(query, context),
@@ -269,7 +300,7 @@ export const mediaBackendPlugin = (config: MediaBackendConfig) =>
 						);
 					}
 
-					return listAssets(adapter, query);
+					return listAssets(adapter, { ...query, tenantId });
 				},
 			);
 
@@ -285,6 +316,10 @@ export const mediaBackendPlugin = (config: MediaBackendConfig) =>
 						headers: ctx.headers,
 					};
 
+					const tenantId = resolveTenantId
+						? ((await resolveTenantId(context)) ?? undefined)
+						: undefined;
+
 					if (hooks?.onBeforeUpload) {
 						await runHookWithShim(
 							() =>
@@ -354,9 +389,12 @@ export const mediaBackendPlugin = (config: MediaBackendConfig) =>
 						if (!folder) {
 							throw ctx.error(404, { message: "Folder not found" });
 						}
+						if (tenantId !== undefined && folder.tenantId !== tenantId) {
+							throw ctx.error(404, { message: "Folder not found" });
+						}
 					}
 
-					const asset = await createAsset(adapter, ctx.body);
+					const asset = await createAsset(adapter, { ...ctx.body, tenantId });
 
 					if (hooks?.onAfterUpload) {
 						await hooks.onAfterUpload(asset, context);
@@ -384,6 +422,14 @@ export const mediaBackendPlugin = (config: MediaBackendConfig) =>
 						headers: ctx.headers,
 					};
 
+					const tenantId = resolveTenantId
+						? ((await resolveTenantId(context)) ?? undefined)
+						: undefined;
+
+					if (tenantId !== undefined && existing.tenantId !== tenantId) {
+						throw ctx.error(404, { message: "Asset not found" });
+					}
+
 					if (hooks?.onBeforeUpdateAsset) {
 						await runHookWithShim(
 							() => hooks.onBeforeUpdateAsset!(existing, ctx.body, context),
@@ -397,6 +443,9 @@ export const mediaBackendPlugin = (config: MediaBackendConfig) =>
 						if (!folder) {
 							throw ctx.error(404, { message: "Folder not found" });
 						}
+						if (tenantId !== undefined && folder.tenantId !== tenantId) {
+							throw ctx.error(404, { message: "Folder not found" });
+						}
 					}
 
 					const updated = await updateAsset(adapter, ctx.params.id, ctx.body);
@@ -419,11 +468,19 @@ export const mediaBackendPlugin = (config: MediaBackendConfig) =>
 						headers: ctx.headers,
 					};
 
+					const tenantId = resolveTenantId
+						? ((await resolveTenantId(context)) ?? undefined)
+						: undefined;
+
 					const asset = await getAssetById(adapter, ctx.params.id);
 					if (!asset) {
 						throw ctx.error(404, { message: "Asset not found" });
 					}
 
+					if (tenantId !== undefined && asset.tenantId !== tenantId) {
+						throw ctx.error(404, { message: "Asset not found" });
+					}
+
 					if (hooks?.onBeforeDelete) {
 						await runHookWithShim(
 							() => hooks.onBeforeDelete!(asset, context),
@@ -475,6 +532,10 @@ export const mediaBackendPlugin = (config: MediaBackendConfig) =>
 						headers: ctx.headers,
 					};
 
+					const tenantId = resolveTenantId
+						? ((await resolveTenantId(context)) ?? undefined)
+						: undefined;
+
 					if (hooks?.onBeforeListFolders) {
 						await runHookWithShim(
 							() => hooks.onBeforeListFolders!(filter, context),
@@ -483,7 +544,7 @@ export const mediaBackendPlugin = (config: MediaBackendConfig) =>
 						);
 					}
 
-					return listFolders(adapter, filter);
+					return listFolders(adapter, { ...filter, tenantId });
 				},
 			);
 
@@ -499,6 +560,10 @@ export const mediaBackendPlugin = (config: MediaBackendConfig) =>
 						headers: ctx.headers,
 					};
 
+					const tenantId = resolveTenantId
+						? ((await resolveTenantId(context)) ?? undefined)
+						: undefined;
+
 					if (hooks?.onBeforeCreateFolder) {
 						await runHookWithShim(
 							() => hooks.onBeforeCreateFolder!(ctx.body, context),
@@ -507,7 +572,17 @@ export const mediaBackendPlugin = (config: MediaBackendConfig) =>
 						);
 					}
 
-					return createFolder(adapter, ctx.body);
+					if (ctx.body.parentId) {
+						const folder = await getFolderById(adapter, ctx.body.parentId);
+						if (!folder) {
+							throw ctx.error(404, { message: "Folder not found" });
+						}
+						if (tenantId !== undefined && folder.tenantId !== tenantId) {
+							throw ctx.error(404, { message: "Folder not found" });
+						}
+					}
+
+					return createFolder(adapter, { ...ctx.body, tenantId });
 				},
 			);
 
@@ -517,15 +592,23 @@ export const mediaBackendPlugin = (config: MediaBackendConfig) =>
 					method: "DELETE",
 				},
 				async (ctx) => {
+					const context: MediaApiContext = {
+						params: ctx.params,
+						headers: ctx.headers,
+					};
+
+					const tenantId = resolveTenantId
+						? ((await resolveTenantId(context)) ?? undefined)
+						: undefined;
+
 					const folder = await getFolderById(adapter, ctx.params.id);
 					if (!folder) {
 						throw ctx.error(404, { message: "Folder not found" });
 					}
 
-					const context: MediaApiContext = {
-						params: ctx.params,
-						headers: ctx.headers,
-					};
+					if (tenantId !== undefined && folder.tenantId !== tenantId) {
+						throw ctx.error(404, { message: "Folder not found" });
+					}
 
 					if (hooks?.onBeforeDeleteFolder) {
 						await runHookWithShim(
@@ -625,6 +708,10 @@ export const mediaBackendPlugin = (config: MediaBackendConfig) =>
 
 					const context: MediaApiContext = { headers: ctx.headers };
 
+					const tenantId = resolveTenantId
+						? ((await resolveTenantId(context)) ?? undefined)
+						: undefined;
+
 					if (hooks?.onBeforeUpload) {
 						await runHookWithShim(
 							() =>
@@ -660,6 +747,9 @@ export const mediaBackendPlugin = (config: MediaBackendConfig) =>
 						if (!folder) {
 							throw ctx.error(404, { message: "Folder not found" });
 						}
+						if (tenantId !== undefined && folder.tenantId !== tenantId) {
+							throw ctx.error(404, { message: "Folder not found" });
+						}
 					}
 
 					const { url } = await storageAdapter.upload(buffer, {
@@ -680,6 +770,7 @@ export const mediaBackendPlugin = (config: MediaBackendConfig) =>
 							size: file.size,
 							url,
 							folderId,
+							tenantId,
 						});
 					} catch (err) {
 						try {
@@ -721,6 +812,13 @@ export const mediaBackendPlugin = (config: MediaBackendConfig) =>
 						headers: ctx.headers,
 					};
 
+					// Resolve tenant for auth checks and folder ownership validation.
+					// The token response does not embed tenantId — the follow-up POST /media/assets
+					// call tags the asset automatically via resolveTenantId.
+					const tenantId = resolveTenantId
+						? ((await resolveTenantId(context)) ?? undefined)
+						: undefined;
+
 					if (hooks?.onBeforeUpload) {
 						await runHookWithShim(
 							() =>
@@ -753,6 +851,9 @@ export const mediaBackendPlugin = (config: MediaBackendConfig) =>
 								message: "Folder not found",
 							});
 						}
+						if (tenantId !== undefined && folder.tenantId !== tenantId) {
+							throw ctx.error(404, { message: "Folder not found" });
+						}
 						folderId = folder.id;
 					}
 					const filename = sanitizeS3KeySegment(ctx.body.filename);
@@ -782,6 +883,13 @@ export const mediaBackendPlugin = (config: MediaBackendConfig) =>
 
 					const context: MediaApiContext = { headers: ctx.headers };
 
+					// Resolve tenant for hook side-effects (e.g. auth checks). The token
+					// response does not embed tenantId — the follow-up POST /media/assets
+					// call tags the asset automatically via resolveTenantId.
+					if (resolveTenantId) {
+						await resolveTenantId(context);
+					}
+
 					if (!ctx.request) {
 						throw ctx.error(400, {
 							message: "Request object is not available",

package/src/plugins/media/db.ts

@@ -40,6 +40,10 @@ export const mediaSchema = createDbPlugin("media", {
 				type: "string",
 				required: false,
 			},
+			tenantId: {
+				type: "string",
+				required: false,
+			},
 			createdAt: {
 				type: "date",
 				defaultValue: () => new Date(),
@@ -61,6 +65,10 @@ export const mediaSchema = createDbPlugin("media", {
 					field: "id",
 				},
 			},
+			tenantId: {
+				type: "string",
+				required: false,
+			},
 			createdAt: {
 				type: "date",
 				defaultValue: () => new Date(),

package/src/plugins/media/types.ts

@@ -7,6 +7,7 @@ export type Asset = {
 	url: string;
 	folderId?: string;
 	alt?: string;
+	tenantId?: string | null;
 	createdAt: Date;
 };
 
@@ -14,6 +15,7 @@ export type Folder = {
 	id: string;
 	name: string;
 	parentId?: string;
+	tenantId?: string | null;
 	createdAt: Date;
 };
 

package/src/plugins/route-docs/client/hooks.ts

@@ -0,0 +1,20 @@
+"use client";
+
+import { useEffect, useState } from "react";
+import { getRegisteredRoutes, type RegisteredRoute } from "./plugin";
+
+/**
+ * React hook that returns all registered client route paths.
+ * Updates whenever the component mounts (after client hydration).
+ */
+export function useRegisteredRoutes(): RegisteredRoute[] {
+	const [routes, setRoutes] = useState<RegisteredRoute[]>(() =>
+		getRegisteredRoutes(),
+	);
+
+	useEffect(() => {
+		setRoutes(getRegisteredRoutes());
+	}, []);
+
+	return routes;
+}

package/src/plugins/route-docs/client/index.ts

@@ -4,4 +4,7 @@ export {
 	ROUTE_DOCS_QUERY_KEY,
 	generateSchema,
 	getStoredContext,
+	getRegisteredRoutes,
+	type RegisteredRoute,
 } from "./plugin";
+export { useRegisteredRoutes } from "./hooks";

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

@@ -42,6 +42,49 @@ export function getStoredContext(): ClientStackContext | null {
 	return moduleStoredContext;
 }
 
+/**
+ * A registered route entry
+ */
+export interface RegisteredRoute {
+	/** The route path pattern (e.g., "/blog/:slug") */
+	path: string;
+	/** The plugin this route belongs to (e.g., "blog") */
+	plugin: string;
+	/** The route key within the plugin (e.g., "detail") */
+	key: string;
+}
+
+/**
+ * Returns all registered client route paths from the stored ClientStackContext.
+ * The context is populated when `createStackClient` is called (i.e. on first render).
+ * Returns an empty array if called before the stack client has been initialised.
+ */
+export function getRegisteredRoutes(): RegisteredRoute[] {
+	if (!moduleStoredContext) return [];
+	const result: RegisteredRoute[] = [];
+	for (const [pluginKey, plugin] of Object.entries(
+		moduleStoredContext.plugins,
+	)) {
+		if (pluginKey === "routeDocs" || plugin.name === "route-docs") continue;
+		try {
+			const routes = plugin.routes(moduleStoredContext);
+			for (const [routeKey, route] of Object.entries(routes)) {
+				const path = (route as any)?.path;
+				if (path) {
+					result.push({
+						path,
+						plugin: plugin.name || pluginKey,
+						key: routeKey,
+					});
+				}
+			}
+		} catch {
+			// silently skip plugins whose routes() throws during introspection
+		}
+	}
+	return result;
+}
+
 /**
  * Generate the route docs schema from the stored context
  * This can be called from both server and client