@btst/stack 2.8.1 → 2.9.1

package/dist/plugins/blog/client/index.d.ts

@@ -392,6 +392,17 @@ declare const BLOG_LOCALIZATION: {
 };
 type BlogLocalization = typeof BLOG_LOCALIZATION;
 
+/**
+ * Props for the overridable blog featured image input component.
+ */
+interface BlogImageInputFieldProps {
+    /** Current image URL value */
+    value: string;
+    /** Called when the image URL changes */
+    onChange: (value: string) => void;
+    /** Whether the field is required */
+    isRequired?: boolean;
+}
 /**
  * Context passed to lifecycle hooks
  */
@@ -435,9 +446,55 @@ interface BlogPluginOverrides {
      */
     Image?: ComponentType<React.ImgHTMLAttributes<HTMLImageElement> & Record<string, any>>;
     /**
-     * Function used to upload an image and return its URL.
+     * Function used to upload a new image file and return its URL.
+     * This is separate from `imagePicker`, which selects an existing asset URL.
      */
     uploadImage: (file: File) => Promise<string>;
+    /**
+     * Optional custom component for the featured image field.
+     *
+     * When provided it replaces the default file-upload input entirely.
+     * The component receives `value` (current URL string) and `onChange` (setter).
+     *
+     * Typical use case: render a preview when a value is set, and a media-picker
+     * trigger when no value is set.
+     *
+     * @example
+     * ```tsx
+     * imageInputField: ({ value, onChange }) =>
+     *   value ? (
+     *     <div>
+     *       <img src={value} alt="Preview" />
+     *       <MediaPicker trigger={<button>Change</button>} accept={["image/*"]}
+     *         onSelect={(assets) => onChange(assets[0].url)} />
+     *     </div>
+     *   ) : (
+     *     <MediaPicker trigger={<button>Browse media</button>} accept={["image/*"]}
+     *       onSelect={(assets) => onChange(assets[0].url)} />
+     *   )
+     * ```
+     */
+    imageInputField?: ComponentType<BlogImageInputFieldProps>;
+    /**
+     * Optional trigger component for a media picker.
+     * When provided, it is rendered adjacent to the Markdown editor and allows
+     * users to browse and select previously uploaded assets.
+     * Receives `onSelect(url)` — insert the chosen URL into the editor.
+     *
+     * @example
+     * ```tsx
+     * imagePicker: ({ onSelect }) => (
+     *   <MediaPicker
+     *     trigger={<Button size="sm" variant="outline">Browse media</Button>}
+     *     accept={["image/*"]}
+     *     onSelect={(assets) => onSelect(assets[0].url)}
+     *   />
+     * )
+     * ```
+     */
+    imagePicker?: ComponentType<{
+        onSelect: (url: string) => void;
+    }>;
     /**
      * Localization object for the blog plugin
      */

package/dist/plugins/cms/client/index.d.cts

@@ -261,6 +261,17 @@ declare const CMS_LOCALIZATION: {
 };
 type CMSLocalization = typeof CMS_LOCALIZATION;
 
+/**
+ * Props for the overridable CMS image input field component.
+ */
+interface CmsImageInputFieldProps {
+    /** Current image URL value */
+    value: string;
+    /** Called when the image URL changes */
+    onChange: (value: string) => void;
+    /** Whether the field is required */
+    isRequired?: boolean;
+}
 /**
  * Context passed to lifecycle hooks
  */
@@ -298,10 +309,53 @@ interface CMSPluginOverrides {
      */
     Image?: ComponentType<React.ImgHTMLAttributes<HTMLImageElement> & Record<string, unknown>>;
     /**
-     * Function used to upload an image and return its URL.
-     * Used by the default "file" field component.
+     * Function used to upload a new image file and return its URL.
+     * Used by the default "file" field component when not selecting an existing
+     * asset via `imagePicker` or `imageInputField`.
      */
     uploadImage?: (file: File) => Promise<string>;
+    /**
+     * Optional custom component for image fields (fieldType: "file").
+     *
+     * When provided it replaces the default file-upload input entirely.
+     * The component receives `value` (current URL string) and `onChange` (setter).
+     *
+     * @example
+     * ```tsx
+     * imageInputField: ({ value, onChange }) =>
+     *   value ? (
+     *     <div>
+     *       <img src={value} alt="Preview" />
+     *       <MediaPicker trigger={<button>Change</button>} accept={["image/*"]}
+     *         onSelect={(assets) => onChange(assets[0].url)} />
+     *     </div>
+     *   ) : (
+     *     <MediaPicker trigger={<button>Browse media</button>} accept={["image/*"]}
+     *       onSelect={(assets) => onChange(assets[0].url)} />
+     *   )
+     * ```
+     */
+    imageInputField?: ComponentType<CmsImageInputFieldProps>;
+    /**
+     * Optional trigger component for a media picker.
+     * When provided, it is rendered inside the default "file" field component as a
+     * "Browse media" option, letting users select a previously uploaded asset.
+     * Receives `onSelect(url)` — the URL is set as the field value.
+     *
+     * @example
+     * ```tsx
+     * imagePicker: ({ onSelect }) => (
+     *   <MediaPicker
+     *     trigger={<Button size="sm" variant="outline">Browse media</Button>}
+     *     accept={["image/*"]}
+     *     onSelect={(assets) => onSelect(assets[0].url)}
+     *   />
+     * )
+     * ```
+     */
+    imagePicker?: ComponentType<{
+        onSelect: (url: string) => void;
+    }>;
     /**
      * Custom field components for AutoForm fields.
      *
@@ -402,6 +456,22 @@ interface CMSFileUploadProps extends AutoFormInputComponentProps {
      * This is required - consumers must provide an upload implementation.
      */
     uploadImage: (file: File) => Promise<string>;
+    /**
+     * Optional custom component for the image field.
+     * When provided, it replaces the default file-upload input entirely.
+     */
+    imageInputField?: ComponentType<{
+        value: string;
+        onChange: (value: string) => void;
+        isRequired?: boolean;
+    }>;
+    /**
+     * Optional trigger component for a media picker.
+     * When provided, it is rendered as a "Browse media" option.
+     */
+    imagePicker?: ComponentType<{
+        onSelect: (url: string) => void;
+    }>;
 }
 /**
  * Default file upload component for CMS image fields.
@@ -425,7 +495,7 @@ interface CMSFileUploadProps extends AutoFormInputComponentProps {
  * }
  * ```
  */
-declare function CMSFileUpload({ label, isRequired, fieldConfigItem, fieldProps, field, uploadImage, }: CMSFileUploadProps): react_jsx_runtime.JSX.Element;
+declare function CMSFileUpload({ label, isRequired, fieldConfigItem, fieldProps, field, uploadImage, imageInputField: ImageInputField, imagePicker: ImagePickerTrigger, }: CMSFileUploadProps): react_jsx_runtime.JSX.Element;
 
 export { AutoFormInputComponentProps, CMSFileUpload, cmsClientPlugin };
 export type { CMSClientConfig, CMSClientHooks, CMSFileUploadProps, CMSLocalization, CMSPluginOverrides, LoaderContext, RouteContext };

package/dist/plugins/cms/client/index.d.mts

@@ -261,6 +261,17 @@ declare const CMS_LOCALIZATION: {
 };
 type CMSLocalization = typeof CMS_LOCALIZATION;
 
+/**
+ * Props for the overridable CMS image input field component.
+ */
+interface CmsImageInputFieldProps {
+    /** Current image URL value */
+    value: string;
+    /** Called when the image URL changes */
+    onChange: (value: string) => void;
+    /** Whether the field is required */
+    isRequired?: boolean;
+}
 /**
  * Context passed to lifecycle hooks
  */
@@ -298,10 +309,53 @@ interface CMSPluginOverrides {
      */
     Image?: ComponentType<React.ImgHTMLAttributes<HTMLImageElement> & Record<string, unknown>>;
     /**
-     * Function used to upload an image and return its URL.
-     * Used by the default "file" field component.
+     * Function used to upload a new image file and return its URL.
+     * Used by the default "file" field component when not selecting an existing
+     * asset via `imagePicker` or `imageInputField`.
      */
     uploadImage?: (file: File) => Promise<string>;
+    /**
+     * Optional custom component for image fields (fieldType: "file").
+     *
+     * When provided it replaces the default file-upload input entirely.
+     * The component receives `value` (current URL string) and `onChange` (setter).
+     *
+     * @example
+     * ```tsx
+     * imageInputField: ({ value, onChange }) =>
+     *   value ? (
+     *     <div>
+     *       <img src={value} alt="Preview" />
+     *       <MediaPicker trigger={<button>Change</button>} accept={["image/*"]}
+     *         onSelect={(assets) => onChange(assets[0].url)} />
+     *     </div>
+     *   ) : (
+     *     <MediaPicker trigger={<button>Browse media</button>} accept={["image/*"]}
+     *       onSelect={(assets) => onChange(assets[0].url)} />
+     *   )
+     * ```
+     */
+    imageInputField?: ComponentType<CmsImageInputFieldProps>;
+    /**
+     * Optional trigger component for a media picker.
+     * When provided, it is rendered inside the default "file" field component as a
+     * "Browse media" option, letting users select a previously uploaded asset.
+     * Receives `onSelect(url)` — the URL is set as the field value.
+     *
+     * @example
+     * ```tsx
+     * imagePicker: ({ onSelect }) => (
+     *   <MediaPicker
+     *     trigger={<Button size="sm" variant="outline">Browse media</Button>}
+     *     accept={["image/*"]}
+     *     onSelect={(assets) => onSelect(assets[0].url)}
+     *   />
+     * )
+     * ```
+     */
+    imagePicker?: ComponentType<{
+        onSelect: (url: string) => void;
+    }>;
     /**
      * Custom field components for AutoForm fields.
      *
@@ -402,6 +456,22 @@ interface CMSFileUploadProps extends AutoFormInputComponentProps {
      * This is required - consumers must provide an upload implementation.
      */
     uploadImage: (file: File) => Promise<string>;
+    /**
+     * Optional custom component for the image field.
+     * When provided, it replaces the default file-upload input entirely.
+     */
+    imageInputField?: ComponentType<{
+        value: string;
+        onChange: (value: string) => void;
+        isRequired?: boolean;
+    }>;
+    /**
+     * Optional trigger component for a media picker.
+     * When provided, it is rendered as a "Browse media" option.
+     */
+    imagePicker?: ComponentType<{
+        onSelect: (url: string) => void;
+    }>;
 }
 /**
  * Default file upload component for CMS image fields.
@@ -425,7 +495,7 @@ interface CMSFileUploadProps extends AutoFormInputComponentProps {
  * }
  * ```
  */
-declare function CMSFileUpload({ label, isRequired, fieldConfigItem, fieldProps, field, uploadImage, }: CMSFileUploadProps): react_jsx_runtime.JSX.Element;
+declare function CMSFileUpload({ label, isRequired, fieldConfigItem, fieldProps, field, uploadImage, imageInputField: ImageInputField, imagePicker: ImagePickerTrigger, }: CMSFileUploadProps): react_jsx_runtime.JSX.Element;
 
 export { AutoFormInputComponentProps, CMSFileUpload, cmsClientPlugin };
 export type { CMSClientConfig, CMSClientHooks, CMSFileUploadProps, CMSLocalization, CMSPluginOverrides, LoaderContext, RouteContext };

package/dist/plugins/cms/client/index.d.ts

@@ -261,6 +261,17 @@ declare const CMS_LOCALIZATION: {
 };
 type CMSLocalization = typeof CMS_LOCALIZATION;
 
+/**
+ * Props for the overridable CMS image input field component.
+ */
+interface CmsImageInputFieldProps {
+    /** Current image URL value */
+    value: string;
+    /** Called when the image URL changes */
+    onChange: (value: string) => void;
+    /** Whether the field is required */
+    isRequired?: boolean;
+}
 /**
  * Context passed to lifecycle hooks
  */
@@ -298,10 +309,53 @@ interface CMSPluginOverrides {
      */
     Image?: ComponentType<React.ImgHTMLAttributes<HTMLImageElement> & Record<string, unknown>>;
     /**
-     * Function used to upload an image and return its URL.
-     * Used by the default "file" field component.
+     * Function used to upload a new image file and return its URL.
+     * Used by the default "file" field component when not selecting an existing
+     * asset via `imagePicker` or `imageInputField`.
      */
     uploadImage?: (file: File) => Promise<string>;
+    /**
+     * Optional custom component for image fields (fieldType: "file").
+     *
+     * When provided it replaces the default file-upload input entirely.
+     * The component receives `value` (current URL string) and `onChange` (setter).
+     *
+     * @example
+     * ```tsx
+     * imageInputField: ({ value, onChange }) =>
+     *   value ? (
+     *     <div>
+     *       <img src={value} alt="Preview" />
+     *       <MediaPicker trigger={<button>Change</button>} accept={["image/*"]}
+     *         onSelect={(assets) => onChange(assets[0].url)} />
+     *     </div>
+     *   ) : (
+     *     <MediaPicker trigger={<button>Browse media</button>} accept={["image/*"]}
+     *       onSelect={(assets) => onChange(assets[0].url)} />
+     *   )
+     * ```
+     */
+    imageInputField?: ComponentType<CmsImageInputFieldProps>;
+    /**
+     * Optional trigger component for a media picker.
+     * When provided, it is rendered inside the default "file" field component as a
+     * "Browse media" option, letting users select a previously uploaded asset.
+     * Receives `onSelect(url)` — the URL is set as the field value.
+     *
+     * @example
+     * ```tsx
+     * imagePicker: ({ onSelect }) => (
+     *   <MediaPicker
+     *     trigger={<Button size="sm" variant="outline">Browse media</Button>}
+     *     accept={["image/*"]}
+     *     onSelect={(assets) => onSelect(assets[0].url)}
+     *   />
+     * )
+     * ```
+     */
+    imagePicker?: ComponentType<{
+        onSelect: (url: string) => void;
+    }>;
     /**
      * Custom field components for AutoForm fields.
      *
@@ -402,6 +456,22 @@ interface CMSFileUploadProps extends AutoFormInputComponentProps {
      * This is required - consumers must provide an upload implementation.
      */
     uploadImage: (file: File) => Promise<string>;
+    /**
+     * Optional custom component for the image field.
+     * When provided, it replaces the default file-upload input entirely.
+     */
+    imageInputField?: ComponentType<{
+        value: string;
+        onChange: (value: string) => void;
+        isRequired?: boolean;
+    }>;
+    /**
+     * Optional trigger component for a media picker.
+     * When provided, it is rendered as a "Browse media" option.
+     */
+    imagePicker?: ComponentType<{
+        onSelect: (url: string) => void;
+    }>;
 }
 /**
  * Default file upload component for CMS image fields.
@@ -425,7 +495,7 @@ interface CMSFileUploadProps extends AutoFormInputComponentProps {
  * }
  * ```
  */
-declare function CMSFileUpload({ label, isRequired, fieldConfigItem, fieldProps, field, uploadImage, }: CMSFileUploadProps): react_jsx_runtime.JSX.Element;
+declare function CMSFileUpload({ label, isRequired, fieldConfigItem, fieldProps, field, uploadImage, imageInputField: ImageInputField, imagePicker: ImagePickerTrigger, }: CMSFileUploadProps): react_jsx_runtime.JSX.Element;
 
 export { AutoFormInputComponentProps, CMSFileUpload, cmsClientPlugin };
 export type { CMSClientConfig, CMSClientHooks, CMSFileUploadProps, CMSLocalization, CMSPluginOverrides, LoaderContext, RouteContext };

package/dist/plugins/kanban/api/index.d.cts

@@ -1,4 +1,4 @@
-export { B as BoardListResult, C as CreateKanbanTaskInput, i as KANBAN_QUERY_KEYS, b as KanbanApiContext, K as KanbanApiRouter, c as KanbanBackendHooks, a as KanbanRouteKey, e as createKanbanTask, f as findOrCreateKanbanBoard, g as getAllBoards, d as getBoardById, h as getKanbanColumnsByBoardId, k as kanbanBackendPlugin } from '../../../shared/stack.BOokfhZD.cjs';
+export { B as BoardListResult, C as CreateKanbanTaskInput, i as KANBAN_QUERY_KEYS, b as KanbanApiContext, K as KanbanApiRouter, c as KanbanBackendHooks, a as KanbanRouteKey, e as createKanbanTask, f as findOrCreateKanbanBoard, g as getAllBoards, d as getBoardById, h as getKanbanColumnsByBoardId, k as kanbanBackendPlugin } from '../../../shared/stack.B6S3cgwN.cjs';
 import { B as BoardWithColumns, S as SerializedBoardWithColumns, C as ColumnWithTasks, a as SerializedColumn, T as Task, b as SerializedTask } from '../../../shared/stack.DJaKVY7v.cjs';
 import '@btst/stack/plugins/api';
 import '@btst/db';

package/dist/plugins/kanban/api/index.d.mts

@@ -1,4 +1,4 @@
-export { B as BoardListResult, C as CreateKanbanTaskInput, i as KANBAN_QUERY_KEYS, b as KanbanApiContext, K as KanbanApiRouter, c as KanbanBackendHooks, a as KanbanRouteKey, e as createKanbanTask, f as findOrCreateKanbanBoard, g as getAllBoards, d as getBoardById, h as getKanbanColumnsByBoardId, k as kanbanBackendPlugin } from '../../../shared/stack.CWxAl9K3.mjs';
+export { B as BoardListResult, C as CreateKanbanTaskInput, i as KANBAN_QUERY_KEYS, b as KanbanApiContext, K as KanbanApiRouter, c as KanbanBackendHooks, a as KanbanRouteKey, e as createKanbanTask, f as findOrCreateKanbanBoard, g as getAllBoards, d as getBoardById, h as getKanbanColumnsByBoardId, k as kanbanBackendPlugin } from '../../../shared/stack.Bzfx-_lq.mjs';
 import { B as BoardWithColumns, S as SerializedBoardWithColumns, C as ColumnWithTasks, a as SerializedColumn, T as Task, b as SerializedTask } from '../../../shared/stack.DJaKVY7v.mjs';
 import '@btst/stack/plugins/api';
 import '@btst/db';

package/dist/plugins/kanban/api/index.d.ts

@@ -1,4 +1,4 @@
-export { B as BoardListResult, C as CreateKanbanTaskInput, i as KANBAN_QUERY_KEYS, b as KanbanApiContext, K as KanbanApiRouter, c as KanbanBackendHooks, a as KanbanRouteKey, e as createKanbanTask, f as findOrCreateKanbanBoard, g as getAllBoards, d as getBoardById, h as getKanbanColumnsByBoardId, k as kanbanBackendPlugin } from '../../../shared/stack.BvCR4-9H.js';
+export { B as BoardListResult, C as CreateKanbanTaskInput, i as KANBAN_QUERY_KEYS, b as KanbanApiContext, K as KanbanApiRouter, c as KanbanBackendHooks, a as KanbanRouteKey, e as createKanbanTask, f as findOrCreateKanbanBoard, g as getAllBoards, d as getBoardById, h as getKanbanColumnsByBoardId, k as kanbanBackendPlugin } from '../../../shared/stack.j5SFLC1d.js';
 import { B as BoardWithColumns, S as SerializedBoardWithColumns, C as ColumnWithTasks, a as SerializedColumn, T as Task, b as SerializedTask } from '../../../shared/stack.DJaKVY7v.js';
 import '@btst/stack/plugins/api';
 import '@btst/db';

package/dist/plugins/kanban/client/hooks/index.d.cts

@@ -1,5 +1,5 @@
 import * as _tanstack_react_query from '@tanstack/react-query';
-import { a as KanbanUser } from '../../../../shared/stack.BxFl46lB.cjs';
+import { a as KanbanUser } from '../../../../shared/stack.DxQl8Wa1.cjs';
 import { S as SerializedBoardWithColumns, c as SerializedBoard, a as SerializedColumn, b as SerializedTask, P as Priority } from '../../../../shared/stack.DJaKVY7v.cjs';
 import 'react';
 

package/dist/plugins/kanban/client/hooks/index.d.mts

@@ -1,5 +1,5 @@
 import * as _tanstack_react_query from '@tanstack/react-query';
-import { a as KanbanUser } from '../../../../shared/stack.Jb0kQDJC.mjs';
+import { a as KanbanUser } from '../../../../shared/stack.Cd6McBu1.mjs';
 import { S as SerializedBoardWithColumns, c as SerializedBoard, a as SerializedColumn, b as SerializedTask, P as Priority } from '../../../../shared/stack.DJaKVY7v.mjs';
 import 'react';
 

package/dist/plugins/kanban/client/hooks/index.d.ts

@@ -1,5 +1,5 @@
 import * as _tanstack_react_query from '@tanstack/react-query';
-import { a as KanbanUser } from '../../../../shared/stack.DRpeDS6X.js';
+import { a as KanbanUser } from '../../../../shared/stack.BMx2QYOK.js';
 import { S as SerializedBoardWithColumns, c as SerializedBoard, a as SerializedColumn, b as SerializedTask, P as Priority } from '../../../../shared/stack.DJaKVY7v.js';
 import 'react';
 

package/dist/plugins/kanban/client/index.d.cts

@@ -3,7 +3,7 @@ import * as _btst_yar from '@btst/yar';
 import { ComponentType } from 'react';
 import { QueryClient } from '@tanstack/react-query';
 import { S as SerializedBoardWithColumns } from '../../../shared/stack.DJaKVY7v.cjs';
-export { K as KanbanPluginOverrides, a as KanbanUser } from '../../../shared/stack.BxFl46lB.cjs';
+export { K as KanbanPluginOverrides, a as KanbanUser } from '../../../shared/stack.DxQl8Wa1.cjs';
 
 /**
  * Context passed to route hooks

package/dist/plugins/kanban/client/index.d.mts

@@ -3,7 +3,7 @@ import * as _btst_yar from '@btst/yar';
 import { ComponentType } from 'react';
 import { QueryClient } from '@tanstack/react-query';
 import { S as SerializedBoardWithColumns } from '../../../shared/stack.DJaKVY7v.mjs';
-export { K as KanbanPluginOverrides, a as KanbanUser } from '../../../shared/stack.Jb0kQDJC.mjs';
+export { K as KanbanPluginOverrides, a as KanbanUser } from '../../../shared/stack.Cd6McBu1.mjs';
 
 /**
  * Context passed to route hooks

package/dist/plugins/kanban/client/index.d.ts

@@ -3,7 +3,7 @@ import * as _btst_yar from '@btst/yar';
 import { ComponentType } from 'react';
 import { QueryClient } from '@tanstack/react-query';
 import { S as SerializedBoardWithColumns } from '../../../shared/stack.DJaKVY7v.js';
-export { K as KanbanPluginOverrides, a as KanbanUser } from '../../../shared/stack.DRpeDS6X.js';
+export { K as KanbanPluginOverrides, a as KanbanUser } from '../../../shared/stack.BMx2QYOK.js';
 
 /**
  * Context passed to route hooks

package/dist/plugins/kanban/query-keys.d.cts

@@ -1,5 +1,5 @@
 import * as _tanstack_react_query from '@tanstack/react-query';
-import { K as KanbanApiRouter, j as BoardsListDiscriminator } from '../../shared/stack.BOokfhZD.cjs';
+import { K as KanbanApiRouter, j as BoardsListDiscriminator } from '../../shared/stack.B6S3cgwN.cjs';
 import { createApiClient } from '@btst/stack/plugins/client';
 import { S as SerializedBoardWithColumns } from '../../shared/stack.DJaKVY7v.cjs';
 import '@btst/stack/plugins/api';

package/dist/plugins/kanban/query-keys.d.mts

@@ -1,5 +1,5 @@
 import * as _tanstack_react_query from '@tanstack/react-query';
-import { K as KanbanApiRouter, j as BoardsListDiscriminator } from '../../shared/stack.CWxAl9K3.mjs';
+import { K as KanbanApiRouter, j as BoardsListDiscriminator } from '../../shared/stack.Bzfx-_lq.mjs';
 import { createApiClient } from '@btst/stack/plugins/client';
 import { S as SerializedBoardWithColumns } from '../../shared/stack.DJaKVY7v.mjs';
 import '@btst/stack/plugins/api';

package/dist/plugins/kanban/query-keys.d.ts

@@ -1,5 +1,5 @@
 import * as _tanstack_react_query from '@tanstack/react-query';
-import { K as KanbanApiRouter, j as BoardsListDiscriminator } from '../../shared/stack.BvCR4-9H.js';
+import { K as KanbanApiRouter, j as BoardsListDiscriminator } from '../../shared/stack.j5SFLC1d.js';
 import { createApiClient } from '@btst/stack/plugins/client';
 import { S as SerializedBoardWithColumns } from '../../shared/stack.DJaKVY7v.js';
 import '@btst/stack/plugins/api';

package/dist/plugins/media/api/adapters/s3.cjs

@@ -0,0 +1,106 @@
+'use strict';
+
+function s3Adapter(options) {
+  const {
+    bucket,
+    region,
+    accessKeyId,
+    secretAccessKey,
+    endpoint,
+    publicBaseUrl,
+    expiresIn = 300
+  } = options;
+  let s3ModulePromise = null;
+  let clientPromise = null;
+  function getS3Module() {
+    if (!s3ModulePromise) {
+      s3ModulePromise = import('@aws-sdk/client-s3').catch(() => {
+        s3ModulePromise = null;
+        throw new Error(
+          "[@btst/stack] S3 adapter requires '@aws-sdk/client-s3'. Run: npm install @aws-sdk/client-s3 @aws-sdk/s3-request-presigner"
+        );
+      });
+    }
+    return s3ModulePromise;
+  }
+  function getClient() {
+    if (!clientPromise) {
+      clientPromise = getS3Module().then(({ S3Client }) => {
+        return new S3Client({
+          region,
+          endpoint,
+          credentials: { accessKeyId, secretAccessKey },
+          forcePathStyle: !!endpoint
+        });
+      });
+    }
+    return clientPromise.catch((error) => {
+      if (clientPromise) {
+        clientPromise = null;
+      }
+      if (s3ModulePromise && error instanceof Error) {
+        throw error;
+      }
+      throw new Error(
+        "[@btst/stack] S3 adapter requires '@aws-sdk/client-s3'. Run: npm install @aws-sdk/client-s3 @aws-sdk/s3-request-presigner"
+      );
+    });
+  }
+  async function buildSignedUrl(client, command, opts) {
+    let getSignedUrl;
+    try {
+      ({ getSignedUrl } = await import('@aws-sdk/s3-request-presigner'));
+    } catch {
+      throw new Error(
+        "[@btst/stack] S3 adapter requires '@aws-sdk/s3-request-presigner'. Run: npm install @aws-sdk/client-s3 @aws-sdk/s3-request-presigner"
+      );
+    }
+    return getSignedUrl(
+      client,
+      command,
+      opts
+    );
+  }
+  return {
+    type: "s3",
+    urlPrefix: publicBaseUrl.replace(/\/$/, ""),
+    async generateUploadToken(uploadOptions) {
+      const [client, { PutObjectCommand }] = await Promise.all([
+        getClient(),
+        getS3Module()
+      ]);
+      const key = uploadOptions.folderId ? `${uploadOptions.folderId}/${uploadOptions.filename}` : uploadOptions.filename;
+      const command = new PutObjectCommand({
+        Bucket: bucket,
+        Key: key,
+        ContentType: uploadOptions.mimeType,
+        ContentLength: uploadOptions.size
+      });
+      const uploadUrl = await buildSignedUrl(client, command, { expiresIn });
+      const encodedKey = key.split("/").map(encodeURIComponent).join("/");
+      const publicUrl = `${publicBaseUrl.replace(/\/$/, "")}/${encodedKey}`;
+      return {
+        type: "presigned-url",
+        payload: {
+          uploadUrl,
+          publicUrl,
+          key,
+          method: "PUT",
+          headers: { "Content-Type": uploadOptions.mimeType }
+        }
+      };
+    },
+    async delete(url) {
+      const [client, { DeleteObjectCommand }] = await Promise.all([
+        getClient(),
+        getS3Module()
+      ]);
+      const base = publicBaseUrl.replace(/\/$/, "");
+      const encodedKey = url.startsWith(base) ? url.slice(base.length + 1) : url.split("/").pop() ?? url;
+      const key = decodeURIComponent(encodedKey);
+      await client.send(new DeleteObjectCommand({ Bucket: bucket, Key: key }));
+    }
+  };
+}
+
+exports.s3Adapter = s3Adapter;

package/dist/plugins/media/api/adapters/s3.d.cts

@@ -0,0 +1,60 @@
+import { S as S3StorageAdapter } from '../../../../shared/stack.BttDsJJn.cjs';
+
+interface S3StorageAdapterOptions {
+    /**
+     * The S3 bucket name.
+     */
+    bucket: string;
+    /**
+     * AWS region (e.g. `"us-east-1"`).
+     */
+    region: string;
+    /**
+     * AWS access key ID.
+     */
+    accessKeyId: string;
+    /**
+     * AWS secret access key.
+     */
+    secretAccessKey: string;
+    /**
+     * Custom endpoint URL for S3-compatible providers (Cloudflare R2, MinIO, etc.).
+     * @example "https://<account-id>.r2.cloudflarestorage.com"
+     */
+    endpoint?: string;
+    /**
+     * Base URL used to construct the final public asset URL after upload.
+     * @example "https://assets.example.com" or "https://pub-<id>.r2.dev"
+     */
+    publicBaseUrl: string;
+    /**
+     * Duration in seconds for which the presigned URL is valid.
+     * @default 300 (5 minutes)
+     */
+    expiresIn?: number;
+}
+/**
+ * Create an S3-compatible presigned-URL storage adapter.
+ * The server generates a short-lived presigned PUT URL; the browser uploads
+ * the file directly to S3 (or R2 / MinIO). The server never receives file bytes.
+ *
+ * @remarks Requires `@aws-sdk/client-s3` and `@aws-sdk/s3-request-presigner`
+ * as optional peer dependencies.
+ *
+ * @example
+ * ```ts
+ * mediaBackendPlugin({
+ *   storageAdapter: s3Adapter({
+ *     bucket: "my-bucket",
+ *     region: "us-east-1",
+ *     accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
+ *     secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
+ *     publicBaseUrl: "https://assets.example.com",
+ *   })
+ * })
+ * ```
+ */
+declare function s3Adapter(options: S3StorageAdapterOptions): S3StorageAdapter;
+
+export { s3Adapter };
+export type { S3StorageAdapterOptions };