@btst/stack 2.8.1 → 2.9.0

package/dist/shared/stack.vxskCkim.d.cts

@@ -0,0 +1,286 @@
+import * as _btst_stack_plugins_api from '@btst/stack/plugins/api';
+import { a as StorageAdapter, b as S3UploadToken } from './stack.CoBj86jf.cjs';
+import { c as AssetListResult, l as listAssets, a as listFolders, A as AssetListParams } from './stack.CAni8dnD.cjs';
+import * as better_call from 'better-call';
+import { z } from 'zod';
+import { A as Asset, F as Folder } from './stack.CLcnSF_b.cjs';
+
+declare const AssetListQuerySchema: z.ZodObject<{
+    folderId: z.ZodOptional<z.ZodString>;
+    mimeType: z.ZodOptional<z.ZodString>;
+    query: z.ZodOptional<z.ZodString>;
+    offset: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+    limit: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+}, z.core.$strip>;
+declare const updateAssetSchema: z.ZodObject<{
+    alt: z.ZodOptional<z.ZodString>;
+    folderId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>;
+declare const createFolderSchema: z.ZodObject<{
+    name: z.ZodString;
+    parentId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+
+/**
+ * Context passed to media API hooks.
+ */
+interface MediaApiContext<TBody = unknown, TParams = unknown, TQuery = unknown> {
+    body?: TBody;
+    params?: TParams;
+    query?: TQuery;
+    request?: Request;
+    headers?: Headers;
+    [key: string]: unknown;
+}
+/**
+ * Configuration hooks for the media backend plugin.
+ * All hooks are optional and allow consumers to customise behaviour.
+ */
+interface MediaBackendHooks {
+    /**
+     * Called before a file upload is allowed (both direct and signed adapters).
+     * Throw an Error to reject the upload (e.g. if the user is not authenticated).
+     */
+    onBeforeUpload?: (meta: {
+        filename: string;
+        mimeType: string;
+        size?: number;
+    }, context: MediaApiContext) => Promise<void> | void;
+    /**
+     * Called after an asset record is created in the database.
+     */
+    onAfterUpload?: (asset: Asset, context: MediaApiContext) => Promise<void> | void;
+    /**
+     * Called before an asset is deleted. Throw to prevent deletion.
+     */
+    onBeforeDelete?: (asset: Asset, context: MediaApiContext) => Promise<void> | void;
+    /**
+     * Called after an asset has been deleted from the DB and storage.
+     */
+    onAfterDelete?: (assetId: string, context: MediaApiContext) => Promise<void> | void;
+    /**
+     * Called before listing assets. Throw to deny access.
+     */
+    onBeforeListAssets?: (filter: z.infer<typeof AssetListQuerySchema>, context: MediaApiContext) => Promise<void> | void;
+    /**
+     * Called before updating an asset (PATCH). Throw to deny access.
+     */
+    onBeforeUpdateAsset?: (asset: Asset, updates: z.infer<typeof updateAssetSchema>, context: MediaApiContext) => Promise<void> | void;
+    /**
+     * Called before listing folders. Throw to deny access.
+     */
+    onBeforeListFolders?: (filter: {
+        parentId?: string;
+    }, context: MediaApiContext) => Promise<void> | void;
+    /**
+     * Called before creating a folder. Throw to deny access.
+     */
+    onBeforeCreateFolder?: (input: z.infer<typeof createFolderSchema>, context: MediaApiContext) => Promise<void> | void;
+    /**
+     * Called before deleting a folder. Throw to deny access.
+     */
+    onBeforeDeleteFolder?: (folder: Folder, context: MediaApiContext) => Promise<void> | void;
+}
+/**
+ * Configuration for the media backend plugin.
+ */
+interface MediaBackendConfig {
+    /**
+     * The storage adapter to use for file uploads.
+     * - `localAdapter()` — writes to the local filesystem (dev / self-hosted)
+     * - `s3Adapter()` — presigned PUT URL (AWS S3, Cloudflare R2, MinIO)
+     * - `vercelBlobAdapter()` — signed direct upload via Vercel Blob
+     */
+    storageAdapter: StorageAdapter;
+    /**
+     * Maximum file size in bytes.
+     * Enforced server-side for `localAdapter`.
+     * Passed into the Vercel Blob token for edge enforcement.
+     * Validated against the client-reported size for `s3Adapter`.
+     * @default 10485760 (10 MB)
+     */
+    maxFileSizeBytes?: number;
+    /**
+     * MIME type allowlist (e.g. `["image/jpeg", "image/png"]`).
+     * If omitted, all MIME types are accepted.
+     * Enforced server-side for `localAdapter`.
+     * Passed to Vercel Blob token for edge enforcement.
+     * Validated against the client-reported MIME type for `s3Adapter`.
+     */
+    allowedMimeTypes?: string[];
+    /**
+     * URL prefixes that are allowed when creating asset records via `POST /media/assets`.
+     * When omitted the plugin automatically derives a safe default from the storage adapter:
+     * - `s3Adapter` → the configured `publicBaseUrl`
+     * - `vercelBlobAdapter` → any URL whose hostname ends with `.public.blob.vercel-storage.com`
+     * - `localAdapter` → rejects client-supplied URLs; use `POST /media/upload` instead
+     *
+     * Provide this option only when you need to override the automatic default (e.g. to allow
+     * assets from a CDN in front of your storage that uses a different domain). When using
+     * `localAdapter`, setting `allowedUrlPrefixes` explicitly opts `POST /media/assets` back in.
+     */
+    allowedUrlPrefixes?: string[];
+    /**
+     * Optional lifecycle hooks for the media backend plugin.
+     */
+    hooks?: MediaBackendHooks;
+}
+/**
+ * Media backend plugin.
+ * Provides API endpoints for managing media assets and folders, and supports
+ * local, S3-compatible, and Vercel Blob storage backends.
+ *
+ * @example
+ * ```ts
+ * import { mediaBackendPlugin, localAdapter } from "@btst/stack/plugins/media/api";
+ *
+ * mediaBackendPlugin({
+ *   storageAdapter: localAdapter(),
+ *   hooks: {
+ *     onBeforeUpload: async (_meta, ctx) => {
+ *       const session = await getSession(ctx.headers as Headers);
+ *       if (!session) throw new Error("Unauthorized");
+ *     },
+ *   },
+ * })
+ * ```
+ */
+declare const mediaBackendPlugin: (config: MediaBackendConfig) => _btst_stack_plugins_api.BackendPlugin<{
+    readonly listAssets: better_call.StrictEndpoint<"/media/assets", {} & {
+        method: "GET";
+    } & {
+        query: better_call.StandardSchemaV1<{
+            folderId?: string | undefined;
+            mimeType?: string | undefined;
+            query?: string | undefined;
+            offset?: unknown;
+            limit?: unknown;
+        }, {
+            folderId?: string | undefined;
+            mimeType?: string | undefined;
+            query?: string | undefined;
+            offset?: unknown;
+            limit?: unknown;
+        }>;
+    }, AssetListResult>;
+    readonly createAsset: better_call.StrictEndpoint<"/media/assets", {} & {
+        method: "POST";
+        body: better_call.StandardSchemaV1<{
+            filename: string;
+            originalName: string;
+            mimeType: string;
+            size: number;
+            url: string;
+            folderId?: string | undefined;
+            alt?: string | undefined;
+        }, {
+            filename: string;
+            originalName: string;
+            mimeType: string;
+            size: number;
+            url: string;
+            folderId?: string | undefined;
+            alt?: string | undefined;
+        }>;
+    }, Asset>;
+    readonly updateAsset: better_call.StrictEndpoint<"/media/assets/:id", {} & {
+        method: "PATCH";
+        body: better_call.StandardSchemaV1<{
+            alt?: string | undefined;
+            folderId?: string | null | undefined;
+        }, {
+            alt?: string | undefined;
+            folderId?: string | null | undefined;
+        }>;
+    }, Asset>;
+    readonly deleteAsset: better_call.StrictEndpoint<"/media/assets/:id", {} & {
+        method: "DELETE";
+        body: better_call.StandardSchemaV1<unknown, unknown>;
+    }, {
+        success: boolean;
+    }>;
+    readonly listFolders: better_call.StrictEndpoint<"/media/folders", {} & {
+        method: "GET";
+    } & {
+        query: better_call.StandardSchemaV1<{
+            parentId?: string | undefined;
+        }, {
+            parentId?: string | undefined;
+        }>;
+    }, Folder[]>;
+    readonly createFolder: better_call.StrictEndpoint<"/media/folders", {} & {
+        method: "POST";
+        body: better_call.StandardSchemaV1<{
+            name: string;
+            parentId?: string | undefined;
+        }, {
+            name: string;
+            parentId?: string | undefined;
+        }>;
+    }, Folder>;
+    readonly deleteFolder: better_call.StrictEndpoint<"/media/folders/:id", {} & {
+        method: "DELETE";
+        body: better_call.StandardSchemaV1<unknown, unknown>;
+    }, {
+        success: boolean;
+    }>;
+    readonly uploadDirect: better_call.StrictEndpoint<"/media/upload", {
+        metadata: {
+            allowedMediaTypes: string[];
+        };
+    } & {
+        method: "POST";
+        body: better_call.StandardSchemaV1<unknown, unknown>;
+    }, Asset>;
+    readonly uploadToken: better_call.StrictEndpoint<"/media/upload/token", {} & {
+        method: "POST";
+        body: better_call.StandardSchemaV1<{
+            filename: string;
+            mimeType: string;
+            size: number;
+            folderId?: string | undefined;
+        }, {
+            filename: string;
+            mimeType: string;
+            size: number;
+            folderId?: string | undefined;
+        }>;
+    }, S3UploadToken>;
+    readonly uploadVercelBlob: better_call.StrictEndpoint<"/media/upload/vercel-blob", {} & {
+        method: "POST";
+        body: better_call.StandardSchemaV1<unknown, unknown>;
+    }, unknown>;
+}, {
+    listAssets: (params?: Parameters<typeof listAssets>[1]) => Promise<AssetListResult>;
+    getAssetById: (id: string) => Promise<Asset | null>;
+    listFolders: (params?: Parameters<typeof listFolders>[1]) => Promise<Folder[]>;
+    getFolderById: (id: string) => Promise<Folder | null>;
+}>;
+type MediaApiRouter = ReturnType<ReturnType<typeof mediaBackendPlugin>["routes"]>;
+
+/**
+ * Internal query key constants for the media plugin.
+ * Shared between query-keys.ts (HTTP path) and any SSR/SSG prefetching
+ * to prevent key drift between client and server.
+ */
+
+/**
+ * Discriminator for the asset list cache key.
+ */
+interface AssetListDiscriminator {
+    folderId: string | undefined;
+    mimeType: string | undefined;
+    query: string | undefined;
+    limit: number | undefined;
+    offset: number | undefined;
+}
+declare function assetListDiscriminator(params?: AssetListParams): AssetListDiscriminator;
+/** Full query key builders — use these with `queryClient.setQueryData()`. */
+declare const MEDIA_QUERY_KEYS: {
+    assetsList: (params?: AssetListParams) => readonly ["media", "assets", "list", AssetListDiscriminator];
+    assetDetail: (id: string) => readonly ["media", "assets", "detail", string];
+    foldersList: (parentId?: string | null) => readonly ["media", "folders", "list", string];
+};
+
+export { MEDIA_QUERY_KEYS as a, assetListDiscriminator as b, mediaBackendPlugin as m };
+export type { AssetListDiscriminator as A, MediaApiRouter as M, MediaApiContext as c, MediaBackendHooks as d, MediaBackendConfig as e };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@btst/stack",
-  "version": "2.8.1",
+  "version": "2.9.0",
   "description": "A composable, plugin-based library for building full-stack applications.",
   "repository": {
     "type": "git",
@@ -414,6 +414,77 @@
       }
     },
     "./plugins/comments/css": "./dist/plugins/comments/style.css",
+    "./plugins/media/api": {
+      "import": {
+        "types": "./dist/plugins/media/api/index.d.ts",
+        "default": "./dist/plugins/media/api/index.mjs"
+      },
+      "require": {
+        "types": "./dist/plugins/media/api/index.d.cts",
+        "default": "./dist/plugins/media/api/index.cjs"
+      }
+    },
+    "./plugins/media/api/adapters/s3": {
+      "import": {
+        "types": "./dist/plugins/media/api/adapters/s3.d.ts",
+        "default": "./dist/plugins/media/api/adapters/s3.mjs"
+      },
+      "require": {
+        "types": "./dist/plugins/media/api/adapters/s3.d.cts",
+        "default": "./dist/plugins/media/api/adapters/s3.cjs"
+      }
+    },
+    "./plugins/media/api/adapters/vercel-blob": {
+      "import": {
+        "types": "./dist/plugins/media/api/adapters/vercel-blob.d.ts",
+        "default": "./dist/plugins/media/api/adapters/vercel-blob.mjs"
+      },
+      "require": {
+        "types": "./dist/plugins/media/api/adapters/vercel-blob.d.cts",
+        "default": "./dist/plugins/media/api/adapters/vercel-blob.cjs"
+      }
+    },
+    "./plugins/media/client": {
+      "import": {
+        "types": "./dist/plugins/media/client/index.d.ts",
+        "default": "./dist/plugins/media/client/index.mjs"
+      },
+      "require": {
+        "types": "./dist/plugins/media/client/index.d.cts",
+        "default": "./dist/plugins/media/client/index.cjs"
+      }
+    },
+    "./plugins/media/client/components": {
+      "import": {
+        "types": "./dist/plugins/media/client/components/index.d.ts",
+        "default": "./dist/plugins/media/client/components/index.mjs"
+      },
+      "require": {
+        "types": "./dist/plugins/media/client/components/index.d.cts",
+        "default": "./dist/plugins/media/client/components/index.cjs"
+      }
+    },
+    "./plugins/media/client/hooks": {
+      "import": {
+        "types": "./dist/plugins/media/client/hooks/index.d.ts",
+        "default": "./dist/plugins/media/client/hooks/index.mjs"
+      },
+      "require": {
+        "types": "./dist/plugins/media/client/hooks/index.d.cts",
+        "default": "./dist/plugins/media/client/hooks/index.cjs"
+      }
+    },
+    "./plugins/media/query-keys": {
+      "import": {
+        "types": "./dist/plugins/media/query-keys.d.ts",
+        "default": "./dist/plugins/media/query-keys.mjs"
+      },
+      "require": {
+        "types": "./dist/plugins/media/query-keys.d.cts",
+        "default": "./dist/plugins/media/query-keys.cjs"
+      }
+    },
+    "./plugins/media/css": "./dist/plugins/media/client.css",
     "./plugins/route-docs/client": {
       "import": {
         "types": "./dist/plugins/route-docs/client/index.d.ts",
@@ -610,6 +681,27 @@
       "plugins/comments/query-keys": [
         "./dist/plugins/comments/query-keys.d.ts"
       ],
+      "plugins/media/api": [
+        "./dist/plugins/media/api/index.d.ts"
+      ],
+      "plugins/media/api/adapters/s3": [
+        "./dist/plugins/media/api/adapters/s3.d.ts"
+      ],
+      "plugins/media/api/adapters/vercel-blob": [
+        "./dist/plugins/media/api/adapters/vercel-blob.d.ts"
+      ],
+      "plugins/media/client": [
+        "./dist/plugins/media/client/index.d.ts"
+      ],
+      "plugins/media/client/components": [
+        "./dist/plugins/media/client/components/index.d.ts"
+      ],
+      "plugins/media/client/hooks": [
+        "./dist/plugins/media/client/hooks/index.d.ts"
+      ],
+      "plugins/media/query-keys": [
+        "./dist/plugins/media/query-keys.d.ts"
+      ],
       "plugins/route-docs/client": [
         "./dist/plugins/route-docs/client/index.d.ts"
       ],
@@ -646,13 +738,17 @@
   },
   "peerDependencies": {
     "@ai-sdk/react": ">=2.0.0",
+    "@aws-sdk/client-s3": ">=3.0.0",
+    "@aws-sdk/s3-request-presigner": ">=3.0.0",
     "@btst/yar": ">=1.2.0",
     "@hookform/resolvers": ">=5.0.0",
     "@radix-ui/react-dialog": ">=1.1.0",
     "@radix-ui/react-label": ">=2.1.0",
     "@radix-ui/react-slot": ">=1.1.0",
     "@radix-ui/react-switch": ">=1.1.0",
+    "@tailwindcss/typography": ">=0.5.0",
     "@tanstack/react-query": "^5.0.0",
+    "@vercel/blob": ">=0.14.0",
     "ai": ">=5.0.0",
     "better-call": ">=1.3.2",
     "class-variance-authority": ">=0.7.0",
@@ -675,25 +771,38 @@
     "sonner": ">=2.0.0",
     "tailwind-merge": ">=2.6.0",
     "tailwindcss": ">=3.0.0",
-    "@tailwindcss/typography": ">=0.5.0",
     "zod": ">=4.2.0"
   },
+  "peerDependenciesMeta": {
+    "@vercel/blob": {
+      "optional": true
+    },
+    "@aws-sdk/client-s3": {
+      "optional": true
+    },
+    "@aws-sdk/s3-request-presigner": {
+      "optional": true
+    }
+  },
   "devDependencies": {
-    "tsx": "catalog:",
     "@ai-sdk/react": "^2.0.94",
+    "@aws-sdk/client-s3": "^3.1011.0",
+    "@aws-sdk/s3-request-presigner": "^3.1011.0",
     "@btst/adapter-memory": "2.1.1",
     "@btst/yar": "1.2.0",
     "@types/react": "^19.0.0",
     "@types/slug": "^5.0.9",
+    "@vercel/blob": "^0.27.3",
     "@workspace/ui": "workspace:*",
     "ai": "^5.0.94",
     "better-call": "catalog:",
+    "knip": "^5.61.2",
     "react": "^19.1.1",
     "react-dom": "^19.1.1",
     "react-error-boundary": "^4.1.2",
-    "knip": "^5.61.2",
     "rollup-plugin-preserve-directives": "0.4.0",
     "rollup-plugin-visualizer": "^5.12.0",
+    "tsx": "catalog:",
     "typescript": "catalog:",
     "unbuild": "catalog:",
     "vitest": "catalog:",

package/src/plugins/blog/client/components/forms/image-field.tsx

@@ -28,13 +28,44 @@ export function FeaturedImageField({
 	const fileInputRef = useRef<HTMLInputElement>(null);
 	const [isUploading, setIsUploading] = useState(false);
 
-	const { uploadImage, Image, localization } = usePluginOverrides<
-		BlogPluginOverrides,
-		Partial<BlogPluginOverrides>
-	>("blog", { localization: BLOG_LOCALIZATION });
+	const {
+		uploadImage,
+		Image,
+		localization,
+		imageInputField: ImageInput,
+	} = usePluginOverrides<BlogPluginOverrides, Partial<BlogPluginOverrides>>(
+		"blog",
+		{ localization: BLOG_LOCALIZATION },
+	);
 
 	const ImageComponent = Image ? Image : DefaultImage;
 
+	// When a custom imageInput component is provided via overrides, delegate to it.
+	if (ImageInput) {
+		return (
+			<FormItem className="flex flex-col">
+				<FormLabel>
+					{localization.BLOG_FORMS_FEATURED_IMAGE_LABEL}
+					{isRequired && (
+						<span className="text-destructive">
+							{" "}
+							{localization.BLOG_FORMS_FEATURED_IMAGE_REQUIRED_ASTERISK}
+						</span>
+					)}
+				</FormLabel>
+				<FormControl>
+					<ImageInput
+						value={value || ""}
+						onChange={onChange}
+						isRequired={isRequired}
+					/>
+				</FormControl>
+				<FormDescription />
+				<FormMessage />
+			</FormItem>
+		);
+	}
+
 	const handleImageUpload = async (
 		event: React.ChangeEvent<HTMLInputElement>,
 	) => {

package/src/plugins/blog/client/components/forms/markdown-editor-with-overrides.tsx

@@ -1,4 +1,5 @@
 "use client";
+import { useCallback, useRef } from "react";
 import { usePluginOverrides } from "@btst/stack/context";
 import type { BlogPluginOverrides } from "../../overrides";
 import { BLOG_LOCALIZATION } from "../../localization";
@@ -6,24 +7,78 @@ import { MarkdownEditor, type MarkdownEditorProps } from "./markdown-editor";
 
 type MarkdownEditorWithOverridesProps = Omit<
 	MarkdownEditorProps,
-	"uploadImage" | "placeholder"
+	| "uploadImage"
+	| "placeholder"
+	| "insertImageRef"
+	| "openMediaPickerForImageBlock"
 >;
 
 export function MarkdownEditorWithOverrides(
 	props: MarkdownEditorWithOverridesProps,
 ) {
-	const { uploadImage, localization } = usePluginOverrides<
-		BlogPluginOverrides,
-		Partial<BlogPluginOverrides>
-	>("blog", {
-		localization: BLOG_LOCALIZATION,
-	});
+	const {
+		uploadImage,
+		imagePicker: ImagePickerTrigger,
+		localization,
+	} = usePluginOverrides<BlogPluginOverrides, Partial<BlogPluginOverrides>>(
+		"blog",
+		{ localization: BLOG_LOCALIZATION },
+	);
+
+	const insertImageRef = useRef<((url: string) => void) | null>(null);
+	// Holds the Crepe-image-block `setUrl` callback while the picker is open.
+	const pendingInsertUrlRef = useRef<((url: string) => void) | null>(null);
+	// Ref to the trigger wrapper so we can programmatically click the picker button.
+	const triggerContainerRef = useRef<HTMLDivElement | null>(null);
+
+	// Single onSelect handler for ImagePickerTrigger.
+	// URLs returned by the media plugin are already percent-encoded at the
+	// source (storage adapter), so no additional encoding is applied here.
+	const handleSelect = useCallback((url: string) => {
+		if (pendingInsertUrlRef.current) {
+			// Crepe image block flow: set the URL into the block's link input.
+			pendingInsertUrlRef.current(url);
+			pendingInsertUrlRef.current = null;
+		} else {
+			// Normal flow: insert image at end of markdown content.
+			insertImageRef.current?.(url);
+		}
+	}, []);
+
+	// Called by MarkdownEditor's click interceptor when the user clicks a Crepe
+	// image-block upload placeholder.
+	const openMediaPickerForImageBlock = useCallback(
+		(setUrl: (url: string) => void) => {
+			pendingInsertUrlRef.current = setUrl;
+			// Programmatically click the visible picker trigger button.
+			const btn = triggerContainerRef.current?.querySelector(
+				'[data-testid="open-media-picker"]',
+			) as HTMLButtonElement | null;
+			btn?.click();
+		},
+		[],
+	);
 
 	return (
-		<MarkdownEditor
-			{...props}
-			uploadImage={uploadImage}
-			placeholder={localization?.BLOG_FORMS_EDITOR_PLACEHOLDER}
-		/>
+		<div className="flex flex-col">
+			<MarkdownEditor
+				{...props}
+				uploadImage={uploadImage}
+				placeholder={localization?.BLOG_FORMS_EDITOR_PLACEHOLDER}
+				insertImageRef={insertImageRef}
+				openMediaPickerForImageBlock={
+					ImagePickerTrigger ? openMediaPickerForImageBlock : undefined
+				}
+			/>
+			{ImagePickerTrigger && (
+				<div
+					ref={triggerContainerRef}
+					className="flex justify-end mt-1"
+					data-testid="image-picker-trigger"
+				>
+					<ImagePickerTrigger onSelect={handleSelect} />
+				</div>
+			)}
+		</div>
 	);
 }